One header. One envelope. Counts are free.

Readiness and the running build. Returns { ok, control_ok, build, mode, control, ts } plus a few fields that describe the data it serves; while our ledger cannot be reached it answers 503 with ok: false (paid calls would fail then too).

Count what a filter combination matches. Takes every company filter plus:

$ curl -H "x-api-key: $KEY" "https://api.smarterdata.ai/v1/count?state=TX&niche=general_contractor&entity=contacts"
{ "ok": true, "entity": "contacts", "definition": "named_dm_strict", "count": 10448, "credits_used": 0, "credits_remaining": 1900 }

# a segment narrower than coverage_min_segment companies: coverage is withheld, never guessed
{ "ok": true, "entity": "companies_with_named_dm", "count": null,
  "note": "segment_too_small: coverage is reported for segments of 25+ companies", "credits_used": 0, … }

Search the store. Takes every company filter plus limit (≤ 1000), estimate, exclude_delivered, redeliver_after_days. Ordered by data quality, so your first records are your best records. Response adds total_matching, has_more, pagination_mode. Record shape: Company.

One company, same projection as search (entity: "company", one record). Counts as a delivery. Free for a company your account already bought (by a search or an earlier detail) — the answer then says already_delivered: true. Takes only estimate (free: count: 1 and the exact credit_cost, 0 or 1); any other parameter is 400 unknown_filter. Unknown id → 404 not_found.

Reveal the contacts at one company your account already holds — get it first (a search that returns it, or GET /v1/companies/{business_id}); otherwise the reveal and its estimate answer 409 company_required and nothing is charged. An unknown company is 404 not_found. You are billed only for distinct contacts that carry at least one channel you asked for; a record with none of the requested channels is never returned and never billed. Record shape: Contact (reveal).

$ ID=co%3Ad%3Aexamplepaving.com
$ curl -H "x-api-key: $KEY" "https://api.smarterdata.ai/v1/companies/$ID/contacts?channels=email,cell&estimate=true"
{ "ok": true, "estimate": true, "entity": "contacts", "count": 2, "credit_cost": 6, "credits_per_record": 3,
  "definition": "named_dm_strict", "credits_used": 0, "credits_remaining": 1900 }

$ curl -H "x-api-key: $KEY" "https://api.smarterdata.ai/v1/companies/$ID/contacts?channels=email,cell"
{ "ok": true, "entity": "contacts", "count": 2, "credits_used": 6, "credits_remaining": 1894, "definition": "named_dm_strict",
  "records": [ { "name": "Jordan Doe", "title": "Owner", "seniority": "owner_operator", "is_decision_maker": true,
                 "contact_class": "person",
                 "channels": { "email": { "value": "jordan@example.com", "type": "personal", "status": "unverified" },
                               "cell":  { "value": "2145550177", "type": "personal", "line_type": "unknown" } },
                 "email_capable": true, "sms_capable": true, "call_capable": true, … } ] }

Wide search: contacts across all companies matching the filters — for "every owner of a roofing company in Arizona" without pulling the companies first. Takes every company filter plus the person filters below; limit ≤ 1000, estimate, ledger controls. One record per contact at each company: a person listed at two companies of the segment comes back once for each (each company sells its own contacts); inside one company an email appears once. Response adds has_more, pagination_mode and definition (repeat the call for the next batch). The company filters must match at least coverage_min_segment companies (25): a narrower segment is 400 segment_too_small (its estimate answers count: null) — for one company, use its own contacts route. Record shape: Contact (wide search) — flat fields.

Body { "email": "…", "smtp": false }. Without smtp: an instant mail-host check — status is mx_ok, no_mail_host, invalid_syntax or unknown (a domain that publishes a null MX — it accepts no mail — is no_mail_host). The answer always carries the same keys — email, domain, status, mx, cached, verified_at, origin — with null where a value is not known (an invalid_syntax or unknown answer has no verified_at or origin). Every verification is charged: 1 credit per check. An answer verified in the last 60 days comes back at once from our store, at the same price — it says cached: true, origin: "store" and its original verified_at, so you can see how old the check is; an older one is checked again live. 0 for a string that is not an email (invalid_syntax — no lookup happens) and when the mail host could not be checked right now (unknown — nothing is stored; try again later). email must be one address as a string (400 email_required), smtp a boolean — true/false/1/0 (400 bad_boolean). An idempotency-key replays the original answer — a retry of the same request is free. It checks that the domain accepts mail — not that the mailbox exists. With "smtp": true and a live mail host: deep mailbox verification is queued as a job — 3 credits held, settled when it completes: 3 with a deep verdict (the mail-host answer comes with it), 1 — the mail-host answer alone — when the deep check gives none (unknown, error, unavailable); the rest is refunded. Every answer you receive is paid, the mail-host answer included. The reply carries job_id (a UUID) and credits_held. A deep verdict reached in the last 60 days comes back from our store at the same 3 credits (the record says cached: true, origin: "store" and its original verified_at); an older one is verified again.

$ curl -X POST -H "x-api-key: $KEY" -H "content-type: application/json" \
    -d '{"email":"jordan@example.com"}' https://api.smarterdata.ai/v1/verify/email
{ "ok": true, "entity": "email_verification", "email": "jordan@example.com", "domain": "example.com",
  "status": "mx_ok", "mx": true, "cached": false, "verified_at": "2026-10-24T09:14:02Z", "origin": "live",
  "credits_used": 1, "credits_remaining": 1893 }

$ … -d '{"email":"jordan@example.com","smtp":true}' …
{ "ok": true, "email": "…", "status": "mx_ok", "mx": true, "smtp": "queued", "job_id": "574e7696-a81e-4cd8-94c9-557df9140af1", "credits_held": 3,
  "note": "poll /v1/jobs/{id}; settled on completion: 3 credits with a deep verdict (the mail-host answer comes with it), 1 for the mail-host answer alone when the deep check gives none (unknown / error / unavailable); the rest of the hold is refunded" }

Body { "emails": [ … ] }, 1 to 10,000 addresses. Async: a hold of 3 × n is taken up front (402 insufficient_credits if your balance cannot cover the maximum), then the job settles to completed verifications only — valid, invalid and catch_all bill 3 each — a verdict we already hold too (verified in the last 60 days: cached: true, origin: "store", its original verified_at); unknown, error, unavailable (deep verification is not switched on — the record carries note: "smtp_verification_unavailable") and invalid_syntax (not an email address — never sent for checking) are refunded. One address is verified and billed once: duplicates (case and spaces ignored) are removed first and counted in duplicates_removed. Returns job_id, total, status, credits_held, credits_remaining; poll /v1/jobs/{id}.

Body { "domains": [ … ] }, 1 to 500. Crawls each site and returns what is on it. A site we crawled in the last 30 days comes back from our store at the same price, with origin: "store" and the scraped_at of that crawl — never dated as crawled now. Each domain is crawled and billed once (https://Example.com/ and example.com are one domain; duplicates_removed says how many were dropped). Hold of 2 × n, settled to successfully crawled domains. A crawl succeeds when the site's own pages answer and carry at least one contact signal of it (a same-domain email, a phone or a social profile). A domain that cannot be fetched, a block / parked / for-sale page, or pages with no contact signal cost 0 and come back ok: false with a reason (unreachable · not_the_site · nothing_found). Per domain on completion: domain, ok, title, emails[] (same-domain addresses only), phones[] (10-digit), socials{} (profile links: facebook, instagram, linkedin, x, yelp), pages_fetched, scraped_at.

$ curl -X POST -H "x-api-key: $KEY" -H "content-type: application/json" \
    -d '{"domains":["example.com","examplepaving.com"]}' https://api.smarterdata.ai/v1/scrape
{ "ok": true, "job_id": "9b1d7e40-2c6f-4f0a-8d3e-61a5c2b7f9e4", "total": 2, "status": "queued", "credits_held": 4,
  "note": "2 credits per successfully scraped domain; unused hold refunded at completion" }

Map-listing style local results from the live web — name, category, address, coordinates, phone, website, rating. A page fetched in the last 24 hours comes back from our store at the same price (origin: "store", with the fetched_at of that fetch); every other page is fetched now. The ranking comes in pages of 10.

Billing: 2 credits per page actually fetched, even when a page is empty. The hold is 2 × pages; the walk stops at the end of the ranking and unfetched pages are refunded, so credits_used is what was fetched. If the upstream fails mid-walk you keep the pages already fetched (upstream_error is set) and pay only for those. Results are de-duplicated across pages by place_ref. Response: live: true, fetched_at (when the page was really fetched — the oldest page of a walk), origin (live, store or mixed), page, pages_fetched, page_size, next_page (null at the end), records[] of name, category, address, latitude, longitude, phone, website, rating, rating_count, place_ref, page, position, origin. Never served stale beyond 24 hours.

$ curl -H "x-api-key: $KEY" "https://api.smarterdata.ai/v1/live/places?q=roofing+companies&location=Austin,+TX&pages=2"
{ "ok": true, "entity": "live_places", "count": 20, "credits_used": 4, "credits_remaining": 1889,
  "live": true, "fetched_at": "2026-10-24T09:16:01Z", "page": 1, "pages_fetched": 2, "page_size": 10, "next_page": 3,
  "records": [ { "name": "…", "category": "Roofing contractor", "address": "…", "latitude": 30.26, "longitude": -97.74,
                 "phone": "5125550123", "website": "…", "rating": 4.8, "rating_count": 213, "place_ref": "…", "page": 1, "position": 1 }, … ] }

Organic web search. Params: q (required), num (1–10, default 10; else 400 bad_request), page (1–10, default 1; else 400 page_range), estimate. Response: live: true, fetched_at, page, next_page (null after an empty page or page 10), records[] of position, title, link, snippet, date, origin, plus a knowledge object (title, type, website, description) when a knowledge panel exists. 1 credit per query, even at zero results.

Body { "address", "zip", "city"?, "state"? } (address and zip required, all four are text — 400 bad_request otherwise). Address → owner. A match is the owner with a cell, a phone or an email on file — an owner with none of them is no match. A hold of 6 is taken before the lookup and refunded on no match (count: 0, credits_used: 0) — and refunded automatically if the call is interrupted on our side; a retry with the same idempotency-key is charged once. The answer carries origin and fetched_at: an address traced in the last 90 days comes back from our store at the same price with origin: "store" and the date of that trace. Record: owner_first_name, owner_last_name, address, city, state, zip, cell_1, cell_1_dnc, phone_1, phone_1_type, phone_1_dnc, email_1, origin: "public_records".

Body { "phone": "2145550177" } (10-digit U.S. — anything else is 400 bad_phone, nothing charged). Reverse phone → owner identity and address. Same hold-and-refund rule, same origin / fetched_at. Record: phone, first_name, last_name, address, city, state, zip, email, line_type, dnc, company_name, origin.

Progress of a bulk verify or crawl job (the id is the UUID the submission returned): { ok, id, type, status, total, done }. status is queued, running, complete, failed or cancelled. When it is complete the response also carries records, credits_used and credits_remaining — the hold is settled exactly once; a failed job carries error and its hold is refunded in full. One exception: a deep check of POST /v1/verify/email that our service could not finish already gave you its mail-host answer, so it completes at 1 credit for that answer, its record saying it was interrupted; the deep check itself is refunded. Poll until it finishes; there is no callback URL. A job id that is not yours is 404 not_found.

{ ok, email, name, credits, scopes, keys: [ { prefix, scopes, status, last_used_at } ] } — your balance and your keys (prefixes only; a full key is never shown again after minting).

Mint a key. Body (optional) { "scopes": ["read","personal_data"], "revoke_prefix": "sk_live_…" }. Scopes default to read + personal_data and can never exceed the caller's own; read is required (400 bad_scopes). With revoke_prefix the named key is revoked in the same call — this is Rotate; it must be one of your active keys (otherwise 404 not_found, nothing minted) and, being a swap, it works at the limit. Minting an 11th active key → 409 too_many_keys. Response: { ok, api_key, prefix, scopes, revoked, note: "shown once — copy it now" }.

Revoke one of your keys by prefix → { ok, revoked }. Needs keys:manage (a console session; a plain API key gets 403 keys_manage_required). No active key with that prefix on your account → 404 not_found.

{ ok, usage, ledger } — usage is the last 30 days per action, [ { action, units, calls } ]: net credits (a hold counts only what it settled to — a refunded skip-trace is 0) under the price-table words of /v1/schema → credits (company_search, verify_smtp, scrape_domain, skiptrace_full, …) — a deep check of POST /v1/verify/email that settled at the mail-host price is listed under verify_smtp. ledger is the last 25 ledger entries (charges, holds, refunds, purchases); a call that neither charged nor held credits writes none; a refunded hold appears as the hold and its refund (net 0).

{ ok, packs: [ { id, credits, amount_cents, name } ], billing }. billing is "live" when purchases are open; any other value (or an empty list) means billing is still being activated — the console shows a notice instead of Buy buttons.

Body { "pack_id", "success_url"?, "cancel_url"? } → { ok, checkout_url, session_id }. Redirect the buyer to checkout_url; credits land on your balance moments after payment. Return URLs must be on https://smarterdata.ai or one of its subdomains (400 bad_return_url). Your card statement shows a SMARTEROUT… line with the suffix SMARTERDAT (the exact prefix is the account's shortened descriptor). If Stripe is unreachable the call answers 503 billing_unavailable — nothing is charged. Put Stripe's literal {CHECKOUT_SESSION_ID} in success_url (unencoded) and Stripe fills in the session id on the way back.

Has this checkout landed on your balance? { ok, session_id, credited, credits, credited_at, credits_remaining } — credited: true once the purchase's credits are on your ledger (another account's session always reads false). An id that is not a Checkout Session id (cs_live_… / cs_test_…) is 400 bad_session_id. The console asks this after Stripe sends you back.

The machine-readable contract: company_filters[], contact_filters[], values (the words each value filter accepts, read from the data: niche, sector, service_line, employees_band, revenue_band, seniority, contact_class, and level and function when contact_filters lists them), routes (every route's accepted query parameters), count_entities[], named_dm_definition, data_notes (honesty labels), credits (the live price table) and coverage_min_segment. Read it at startup if you cache prices or build a filter picker.