# Consulti.ai API

> Lead enrichment, email verification, and B2B/local/creator database search. REST + MCP.

Base URL: https://www.consulti.ai/api/v1
Documentation: https://www.consulti.ai/api-docs
OpenAPI: https://www.consulti.ai/api/v1/openapi.json
API keys: https://www.consulti.ai/settings?tab=integrations#api-keys

## Free tools (web pages)

Browser tools at https://www.consulti.ai/tools. No API key needed; each page is indexable:

- Email Verifier: https://www.consulti.ai/tools/email-verifier (Verify any email instantly)
- Domain Health: https://www.consulti.ai/tools/domain-health (Check SPF, DKIM, DMARC records)
- Blacklist Checker: https://www.consulti.ai/tools/blacklist (Scan domain across blacklists)
- DNS Generator: https://www.consulti.ai/tools/dns-generator (Generate SPF, DKIM, DMARC)
- Inbox Placement: https://www.consulti.ai/tools/inbox-placement (Test inbox vs spam placement)
- Spam Checker: https://www.consulti.ai/tools/spam-checker (Get your spam score instantly)
- DNS Setup Wizard: https://www.consulti.ai/tools/dns-wizard (Generate DNS records and apply them to Cloudflare)
- SPF Generator: https://www.consulti.ai/tools/spf-generator (Create SPF records to authorize senders)
- DKIM Generator: https://www.consulti.ai/tools/dkim-generator (Generate DKIM keys for email signing)
- DMARC Generator: https://www.consulti.ai/tools/dmarc-generator (Build DMARC policies for protection)
- Mailbox Setup: https://www.consulti.ai/tools/cold-email-setup (Done-for-you domains & mailboxes)
- AI Copywriter: https://www.consulti.ai/tools/offer-scanner (AI-powered email copywriting)
- Campaign Doctor: https://www.consulti.ai/tools/campaign-doctor (Optimize your sequences)
- Scaling Calculator: https://www.consulti.ai/tools/email-scaling-calculator (Plan domains & mailboxes)
- Spintax Generator: https://www.consulti.ai/tools/spintax-generator (Create unique email variations)
- Lead Magnet Builder: https://www.consulti.ai/tools/reverse-lead-magnet (Build a reverse lead magnet app)
- AI Reply Agent: https://www.consulti.ai/ai-reply-agent (Auto-classify & draft replies to cold email responses)

## Moses, the AI SDR

- Moses: https://www.consulti.ai/ai-sdr (an AI SDR that interviews you, builds your audience, writes the emails, warms up new mailboxes, sends, and answers replies with your booking link)

## Authentication

Every endpoint except the canonical value lookups requires a Bearer token in the Authorization header:

    Authorization: Bearer capi_your_api_key

API keys start with "capi_" and are generated in Settings, Integrations: https://www.consulti.ai/settings?tab=integrations#api-keys

## Access tiers

- Any plan: POST /verify, GET /credits.
- Every other authenticated endpoint requires the Pro plan or higher.

## Endpoints

### POST /verify
Verify whether an email address is valid and deliverable. Uses SMTP checks.
Access: any plan, Bearer auth, MCP tool available.
Credits: Only successful verifications are billed — 1 verification credit each. Requests that fail validation (400) or auth (401), or hit insufficient credits (402), are never billed and return credits_used: 0. Results served from our cache cost the same as fresh ones. When the verifier does not answer in time or is temporarily unavailable, the call returns 503 with code verifier_unavailable, credits_used: 0 and a Retry-After header in seconds. The 503 is sent only after the reserved credit is confirmed refunded. Retry after Retry-After only when credits_used: 0 is present. If the refund cannot be confirmed, the call returns 500 with code refund_unconfirmed and no Retry-After. Reconcile with GET /credits before retrying, because a retry reserves another credit.
Request (JSON body):
- email (string, required): Email address to verify. Leading/trailing whitespace is trimmed automatically before validation.
Example request:
    {
      "email": "john@acme.com"
    }
Example response:
    {
      "success": true,
      "data": {
        "email": "john@acme.com",
        "status": "good",
        "is_deliverable": true,
        "is_disposable": false,
        "is_role_account": false,
        "is_catch_all": false,
        "credits_used": 1
      }
    }
Response fields:
- data.status: Status (good / risky / bad / unknown)
- data.is_deliverable: Deliverable?
- data.is_catch_all: Catch-all domain? Route to LinkedIn enrichment when true — SMTP cannot verify catch-all mailboxes.
- data.is_role_account: Role/shared inbox (info@, support@, sales@)? Deprioritise — typically low reply rate.
- data.is_disposable: Disposable provider (10minutemail, mailinator)? Drop.
- data.credits_used: Verification credits charged (1).
Routing guide: use the boolean flags alongside the status field to route follow-ups. is_catch_all=true → route to LinkedIn enrichment (SMTP cannot verify catch-all mailboxes). is_role_account=true → deprioritise (info@, support@, sales@ usually low reply rates). is_disposable=true → drop (10minutemail, mailinator, etc.). status=unknown → retry later (transient upstream issue, not a permanent verdict).

### POST /verify/catchall
Resolve whether a specific mailbox on a catch-all domain actually exists. Unlike /verify (SMTP), this uses Consulti’s ESP verification engine to probe mailbox existence. Use it on addresses that /verify reports as is_catch_all=true.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: Only successful verifications are billed — 5 verification credits each. Requests that fail validation (400) or auth (401), or hit insufficient credits (402), are never billed and return credits_used: 0. That includes an address that passes the format check but is rejected as malformed during verification: it returns 400 "Invalid email address." and the reserved credits are refunded. Results served from our cache cost the same as fresh ones. The verdict normally arrives within about 50 seconds of the request, but a slow call can run for up to 300 seconds, so set your client timeout to more than 300 seconds. A call your client gives up on can still be billed if the verdict lands afterwards. When the engine does not return a verdict within about 50 seconds, the call returns 503 with code verifier_unavailable and a Retry-After header in seconds. The reserved credits are refunded, but this 503 carries no credits_used, so check GET /credits before you retry. When the reserved credits cannot be confirmed as refunded, any failure (including a malformed address that would otherwise be a 400) returns 500 with code refund_unconfirmed and no Retry-After. Reconcile with GET /credits before retrying, because a retry reserves another 5 credits. The call stays billed when a 500 follows a verdict the engine already returned, so check GET /credits before you retry any 500.
Request (JSON body):
- email (string, required): Email address on a catch-all domain to resolve. Leading/trailing whitespace is trimmed automatically before validation.
Example request:
    {
      "email": "john@catchall-domain.com"
    }
Example response:
    {
      "success": true,
      "data": {
        "email": "john@catchall-domain.com",
        "status": "good",
        "is_catch_all": true,
        "catch_all_verification": {
          "score": 95,
          "status": "Deliverable",
          "provider": "consulti"
        },
        "credits_used": 5,
        "cached": false
      }
    }
Response fields:
- data.status: Resolved status (good / risky / bad / unknown). good = mailbox exists; bad = does not exist; risky = catch-all/inconclusive (do not send).
- data.catch_all_verification.score: Confidence score 0–100 for the resolved verdict.
- data.catch_all_verification.status: Deliverable / Catch-All / Undeliverable / Unknown.
- data.credits_used: Verification credits charged (5).
- data.cached: true when served from a prior result without re-probing upstream.
Requires a plan with catch-all verification enabled (Pro or higher); returns 402 when the plan isn't entitled.

### GET /credits
Return the authenticated API user’s current lead and verification credit balances. Useful as a pre-flight check before running a large search/enrich batch.
Access: any plan, Bearer auth, MCP tool available.
Credits: Free — no deduction.
Request: none.
Example response:
    {
      "success": true,
      "data": {
        "lead_credits": 1500,
        "verification_credits": 5000
      }
    }
Response fields:
- data.lead_credits: Total spendable lead credits across all pools; team accounts report the shared team pool
- data.verification_credits: Current verification credit balance

### GET /meta/{filter}
Return the canonical list of values accepted by a given enum filter. No auth required. Snapshot-first with a 1-hour edge cache that revalidates against the live database. Use slug "_all" to fetch every filter in one snapshot-only payload.
Filters: industries, countries, states, email-statuses, technologies, local-states, local-email-statuses, creator-podcast-categories, creator-podcast-email-statuses, creator-youtube-niches, creator-languages, creator-countries, instagram-categories, instagram-account-types, instagram-countries, instagram-email-statuses. Special slug "_all" returns every filter at once.
Access: any plan, no auth required, REST only, not in MCP.
Credits: Free. No auth required.
Path parameters:
- filter (string, required): A canonical filter slug (e.g. industries, technologies, states, instagram-categories) — or "_all" to return every filter in one payload. The complete slug set is listed in the Canonical filter values section of the docs and returned by the "_all" response. The technologies response also includes entries: [{ name, category }] for category grouping.
Example response:
    {
      "filter": "industries",
      "canonical_filter": "b2b-industries",
      "source": "live",
      "count": 145,
      "generated_at": "2026-05-03T19:18:38.822Z",
      "values": ["Accounting", "Agriculture", "Airlines/Aviation", "..."]
    }
Response fields:
- values: Array of accepted values for this filter
- count: Total number of canonical values
- source: "live" if fetched from DB, "snapshot" if served from build-time fallback
- generated_at: ISO timestamp the values were generated at
- filter: The slug you requested
- canonical_filter: The canonical filter name the slug resolves to (e.g. b2b-industries)
- entries: technologies only: [{ name, category }] pairs for category grouping, returned when source is "snapshot".
- filters: "_all" only: an object keyed by slug, each value { canonical_filter, count, values: string[], generated_at }.
The technologies filter is non-strict (values outside the list still filter) and its response also includes "entries": [{ name, category }] for category grouping.
Response (_all): { "filters": { "<slug>": { "canonical_filter", "count", "values": string[], "generated_at" } } }

### POST /leads/find-by-name
Look up a B2B lead by first name, last name, and company domain.
Beta: the contract may change.
Access: Pro plan or higher, Bearer auth, REST only, not in MCP.
Credits: 1 lead credit — only deducted on a successful match.
Request (JSON body):
- first_name (string, required): First name
- last_name (string, required): Last name
- domain (string, required): Company domain (e.g. acme.com)
Example request:
    {
      "first_name": "John",
      "last_name": "Doe",
      "domain": "acme.com"
    }
Example response:
    {
      "success": true,
      "data": {
        "email": "john@acme.com",
        "first_name": "John",
        "last_name": "Doe",
        "job_title": "CEO",
        "seniority": "C-Suite",
        "departments": ["C-Suite"],
        "company_name": "Acme Inc",
        "company_domain": "acme.com",
        "industry": "Technology",
        "linkedin_url": "https://linkedin.com/in/johndoe",
        "city": "San Francisco",
        "state": "California",
        "country": "United States",
        "employee_count": 250,
        "technologies": ["Shopify", "HubSpot"],
        "mobile_phone": null,
        "company_phone": "+14155550100",
        "email_status": "valid",
        "verified_at": "2026-05-10T12:00:00.000Z"
      },
      "credits_used": 1
    }
Response fields:
- data.email: Work email
- data.industry: Company industry, or null when unknown
- data.linkedin_url: LinkedIn URL
- data.city: City, or null when unknown
- data.state: State / region, or null when unknown
- data.country: Country, or null when unknown
- data.employee_count: Company employee count, or null when unknown
- data.email_status: Email verification status: valid / risky / invalid / unknown / unverified
- data.verified_at: When the email was last verified, or null when unknown
- data.seniority: Seniority label as recorded (e.g. Director, Manager, C-Suite), or null. Not normalized, so casing and spelling can vary
- data.departments: Departments as recorded (e.g. Marketing, Sales), string array, or null when unknown
- data.technologies: Technologies the company’s website uses (Wappalyzer-style names), or null when unknown
- data.mobile_phone: Personal mobile phone if known, else null
- data.company_phone: Company phone line if known, else null

### POST /leads/enrich
Given an email address, return the full enriched B2B lead profile, including a company object (funding, traffic, HQ, followers, specialties) when the lead is linked to a company.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: 1 lead credit — only deducted on a successful match.
Request (JSON body):
- email (string, required): Work email address
Example request:
    {
      "email": "john@acme.com"
    }
Example response:
    {
      "success": true,
      "data": {
        "email": "john@acme.com",
        "first_name": "John",
        "last_name": "Doe",
        "job_title": "CEO",
        "seniority": "C-Suite",
        "departments": ["C-Suite"],
        "company_name": "Acme Inc",
        "company_domain": "acme.com",
        "industry": "Technology",
        "linkedin_url": "https://linkedin.com/in/johndoe",
        "city": "San Francisco",
        "state": "California",
        "country": "United States",
        "employee_count": 250,
        "technologies": ["Shopify", "HubSpot"],
        "mobile_phone": null,
        "company_phone": "+14155550100",
        "email_status": "valid",
        "verified_at": "2026-05-10T12:00:00.000Z",
        "company": {
          "funding_stage": "series_b",
          "total_funding_usd": 25000000,
          "monthly_web_visits": 1200000,
          "operating_status": "active",
          "hq_city": "San Francisco",
          "hq_state": "California",
          "hq_country": "US",
          "linkedin_followers": 54000,
          "specialties": ["SaaS", "B2B"]
        }
      },
      "credits_used": 1
    }
Response fields:
- data.first_name: First name
- data.last_name: Last name
- data.job_title: Job title
- data.seniority: Seniority label as recorded (e.g. Director, Manager, C-Suite), or null. Not normalized, so casing and spelling can vary
- data.departments: Departments as recorded (e.g. Marketing, Sales), string array, or null when unknown
- data.company_name: Company
- data.technologies: Technologies the company’s website uses (Wappalyzer-style names), or null when unknown
- data.mobile_phone: Personal mobile phone if known, else null
- data.company_phone: Company phone line if known, else null
- data.industry: Company industry, or null when unknown
- data.city: City, or null when unknown
- data.state: State / region, or null when unknown
- data.country: Country, or null when unknown
- data.employee_count: Company employee count, or null when unknown
- data.email_status: Email verification status: valid / risky / invalid / unknown / unverified
- data.verified_at: When the email was last verified, or null when unknown
- data.company: Company-level profile, or null when the lead is not linked to a company. Not filterable. Each nested field is null when unknown.
- data.company.funding_stage: Funding stage if known, else null
- data.company.total_funding_usd: Company total funding in USD if known, else null
- data.company.monthly_web_visits: Monthly website visits if known, else null
- data.company.operating_status: Operating status if known, else null
- data.company.hq_city: Headquarters city if known, else null
- data.company.hq_state: Headquarters state if known, else null
- data.company.hq_country: Headquarters country code if known, else null
- data.company.linkedin_followers: Company LinkedIn follower count if known, else null
- data.company.specialties: Company specialties (string[]), or null when unknown

### POST /enrich/linkedin
Enrich a person by their LinkedIn profile URL → a verified work email plus their US mobile phone as a free add-on. Cache-first: served instantly from our database when we already hold a verified email for that profile, otherwise enriched live via the provider and cached for next time.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: 1 lead credit — charged only when an email is returned. Phone is a free add-on; phone-only or no-email responses are free.
Request (JSON body):
- linkedin_url (string, required): LinkedIn profile URL (e.g. https://linkedin.com/in/johndoe)
Example request:
    {
      "linkedin_url": "https://linkedin.com/in/johndoe"
    }
Example response:
    {
      "success": true,
      "source": "live",
      "credits_used": 1,
      "data": {
        "email": "john@acme.com",
        "email_status": "unknown",
        "phone": "+14155550100",
        "company_domain": "acme.com",
        "person_linkedin_url": "https://linkedin.com/in/johndoe"
      }
    }
Response fields:
- source: "cache" (served from our database) or "live" (freshly enriched)
- data.email: Verified work email
- data.email_status: Canonical verification status: valid / risky / invalid / unknown / unverified. Live responses return "unknown" today — the result lands as "valid" or "invalid" once it is re-verified.
- data.phone: US mobile phone if found, else null (free add-on)
- data.company_domain: Company domain (derived from the email on a live miss-fill)
- data.person_linkedin_url: The matched LinkedIn URL
- data.first_name: Profile fields (first_name, last_name, full_name, job_title, company_name, company_linkedin_url, industry, city, state, country, technologies) are also returned on a cache hit; each is null when unknown
- data.full_name: Full name — cache hits only
- data.company_linkedin_url: Company LinkedIn URL — cache hits only
- data.technologies: Technologies the company’s website uses (Wappalyzer-style names), string[] or null when unknown — cache hits only

### POST /leads/search
Search the B2B lead database with filters on title, industry, location, company size, and more. Results are always restricted to leads carrying our verified email label — there is no option to include unverified leads.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: 1 lead credit per result returned. Reserved up to `size`, then refunded down to the actual row count. 0 results = 0 credits. A retried request is a new billable search. An `Idempotency-Key` header is accepted but has no effect at present, so de-duplicate on your side rather than relying on replay. A 503 means the search could not run right now: code search_unavailable when the database was busy or a connection dropped, and code search_timeout when the query ran too long, so narrow the filters. Both carry a Retry-After header in seconds. The reserved credits are refunded, but the body has no credits_used, so check GET /credits before you retry.
Request (JSON body):
- q (string): Free-text search across job title, company name, and industry only. Does not match person names; use POST /leads/find-by-name for that (Beta, REST-only).
- titles (string[]): Job titles to match (e.g. ["CEO", "CTO"])
- industries (string[]): Industries (case-sensitive exact match). See GET /api/v1/meta/industries for the full canonical list.
- technologies (string[]): Technologies the company’s website uses, exact Wappalyzer-style names (e.g. ["Shopify", "HubSpot"]). OR-matched: a lead matches if it uses any listed technology. Max 25. See GET /api/v1/meta/technologies for the canonical list.
- excludeTechnologies (string[]): Technologies to exclude, same Wappalyzer-style names. A lead is dropped if its company uses any listed technology; leads with no technology data are kept. Max 25.
- countries (string[]): Countries. Alias-group members are equivalent (e.g. "United States" and "US"). See GET /api/v1/meta/countries.
- states (string[]): States/regions. Alias-group members are equivalent (e.g. "Ontario" and "ON"). See GET /api/v1/meta/states.
- cities (string[]): Cities to match
- company (string): Company name substring
- empMin (number): Minimum employee count
- empMax (number): Maximum employee count
- revenueMin (number): Minimum annual revenue in USD, whole dollars. Leads with no revenue data on file are excluded when either bound is set. Must be less than or equal to revenueMax when both are set.
- revenueMax (number): Maximum annual revenue in USD, whole dollars. Leads with no revenue data on file are excluded when either bound is set. Must be greater than or equal to revenueMin when both are set.
- excludeTitles (string[]): Job titles to exclude. A lead is dropped if its job title matches any listed value. Max 25.
- excludeListId (string): UUID of a saved list you own, and it must be a LEAD list (the kind created by POST /lists with kind "lead"). Business, podcast, YouTube and Instagram lists hold no lead emails; passing one returns 400 rather than silently excluding nothing. GET /lists reports the kind of each list. Leads whose email is on that list are removed from the result set before billing, so excluded leads never cost credits. Because exclusion is applied in the query, request `page: 1` on every call and add each batch you receive to the list with POST /lists/{id}/add-leads — paging forward while excluding skips leads. Returns 400 if the list does not exist or is not owned by the API key holder.
- page (number): Page number (default: 1). When using excludeListId, keep this at 1 and grow the list instead.
- size (number): Results per page, max 100 (default: 25)
Example request:
    {
      "titles": [
        "CEO",
        "Founder"
      ],
      "industries": [
        "Computer Software"
      ],
      "countries": [
        "United States"
      ],
      "empMin": 10,
      "empMax": 200,
      "revenueMin": 1000000,
      "revenueMax": 50000000,
      "excludeTitles": [
        "intern",
        "assistant"
      ],
      "page": 1,
      "size": 25
    }
Example response:
    {
      "leads": [
        {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john@acme.com",
          "job_title": "CEO",
          "seniority": "C-Suite",
          "departments": ["C-Suite"],
          "company_name": "Acme Inc",
          "company_domain": "acme.com",
          "linkedin_url": "https://linkedin.com/in/johndoe",
          "city": "San Francisco",
          "state": "California",
          "country": "United States",
          "employees": 150,
          "annual_revenue": 12000000,
          "industry": "Computer Software",
          "technologies": ["Shopify", "HubSpot"],
          "mobile_phone": null,
          "company_phone": "+14155550100",
          "email_status": "valid"
        }
      ],
      "total": 1247,
      "total_after_exclusion": 1247,
      "page": 1,
      "size": 25,
      "has_more": true,
      "credits_used": 1
    }
Response fields:
- leads[].email: Lead email
- leads[].job_title: Job title
- leads[].seniority: Seniority label as recorded (e.g. Director, Manager, C-Suite), or null. Not normalized, so casing and spelling can vary
- leads[].departments: Departments as recorded (e.g. Marketing, Sales), string array, or null when unknown
- leads[].company_name: Company
- leads[].annual_revenue: Annual revenue in USD, whole dollars (`number | null`). Null when we hold no revenue data for that lead.
- leads[].technologies: Technologies the company’s website uses (Wappalyzer-style names), or null when unknown
- leads[].mobile_phone: Personal mobile phone if known, else null
- leads[].company_phone: Company phone line if known, else null
- leads[].state: State / region, or null when unknown
- leads[].email_status: Email verification status: valid / risky / invalid / unknown / unverified
- total: Total matching leads before excludeListId is applied. Capped at 10001 — treat 10001 as "more than 10,000".
- total_after_exclusion: Total after excludeListId is applied; equal to `total` when excludeListId is omitted. A LOWER value proves matching rows were excluded. An equal value is inconclusive, not a failure signal: it also occurs when the list holds no email matching this search, and when both counts saturate the 10001 cap. To confirm exclusion directly, re-request a page whose leads you just added to the list.
- has_more: true when this page was full - request the next page to continue; an empty page ends pagination
Retries: responses do not currently carry an `artifact_id`, so de-duplicate on your side rather than relying on replay or re-fetch.

### POST /local-leads/search
Search local businesses scraped from Google Maps, with verified business emails, ratings, and reviews. The email returned for a business is always one that passed verification — the verified-only filter is forced on and cannot be broadened.
Beta: the contract may change.
Access: Pro plan or higher, Bearer auth, REST only, not in MCP.
Credits: 1 lead credit per result returned. Reserved up to `size`, then refunded down to the actual row count. 0 results = 0 credits. Successful paid results become business unlocks for your account, so saving those IDs costs no additional credits. A retried search remains billable. An `Idempotency-Key` header has no effect at present. A rare success response carries `warning.code` SEARCH_COMMIT_UNCONFIRMED: the results are paid and delivered, but the charge record is unconfirmed, so do not repeat the search and contact support with `warning.request_id`.
Request (JSON body):
- q (string): Free-text search (name or category), max 200 chars. Matches singular/plural variants and related categories for common niches (e.g. "restaurants" includes every restaurant type, "med spa" includes Medical spa). A trailing "near me" is ignored.
- name (string): Business name substring
- keywords (string[]): OR-matched keywords, max 50, each max 100 chars. Each keyword also matches singular/plural variants and related Google Maps categories for common niches (e.g. "commercial cleaners" includes Janitorial service, "hvac" includes Air conditioning contractor).
- states (string[]): US states, DC, and Canadian provinces/territories. Accepts full names or 2-letter codes. See GET /api/v1/meta/local-states.
- cities (string[]): Cities
- zips (string[]): ZIP codes
- ratingMin (number): Minimum Google rating
- ratingMax (number): Maximum Google rating
- reviewsMin (number): Minimum review count
- reviewsMax (number): Maximum review count
- hasWeb (boolean): true: only businesses with a website. false: only businesses without one
- hasPhone (boolean): Only return businesses with a phone number
- hasOwnerEmail (boolean): Only return businesses whose returned email was derived from the owner’s name (email_type "owner") rather than a shared alias. A pattern classification, not a claim that the named person reads the mailbox. Set with hasRoleEmail to accept either.
- hasRoleEmail (boolean): Only return businesses whose returned email is a role address such as info@ or contact@ (email_type "role"). Set with hasOwnerEmail to accept either.
- hasOwner (boolean): Only return businesses that have a named owner on record. Filters on owner presence, which is not the same as the returned email belonging to that person — see owner_name below.
- excludeListId (string): UUID of a saved list you own, and it must be a business list (kind "business"). GET /lists reports the kind of each list. Businesses on that list are removed from the result set before billing, so excluded rows never cost credits. A blank or malformed id, a list that does not exist or is not yours, and a list of another kind each return 400. A list with more than 100,000 members returns 422 (code exclusion_too_large), and a temporary lookup failure returns 503 (code list_resolution_unavailable). All of these are returned before anything is reserved, with credits_used: 0. Because exclusion is applied in the query, a harvest loop that adds each batch to the list should request page 1 on every call.
- page (number): Page number (default: 1)
- size (number): Results per page, max 100 (default: 25)
Example request:
    {
      "keywords": [
        "plumber"
      ],
      "states": [
        "Texas"
      ],
      "ratingMin": 4,
      "hasOwnerEmail": true,
      "page": 1,
      "size": 25
    }
Example response:
    {
      "businesses": [
        {
          "id": 12345,
          "name": "Acme Plumbing",
          "phone": "+1-512-555-0100",
          "website": "https://acmeplumbing.com",
          "email": "owner@acmeplumbing.com",
          "address": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701",
          "rating": 4.8,
          "reviews": 127,
          "category": "Plumber",
          "google_maps_url": "https://maps.google.com/?cid=12345",
          "scraped_at": "2026-07-01T12:00:00.000Z",
          "email_type": "owner",
          "email_status": "safe",
          "verified_at": "2026-07-02T09:30:00.000Z",
          "owner_name": "Jane Doe",
          "owner_title": "Owner"
        }
      ],
      "total": 892,
      "page": 1,
      "size": 25,
      "has_more": true,
      "credits_used": 1
    }
Response fields:
- has_more: true when this page was full - request the next page to continue; an empty page ends pagination. Paginate on this, not on total.
- page: The page actually used — the requested value after normalization (floored, minimum 1)
- size: The page size actually used — the requested value after normalization (floored, clamped to 1–100). Read it back rather than assuming your requested size was honoured.
- credits_used: Lead credits actually charged — equal to the number of rows returned. Always present on success, and returned as 0 on the rate-limit, tier and pagination-depth errors. On a 402 or a 5xx the key may be absent, and its absence is UNSPECIFIED — it does not assert that nothing was charged, because a reservation may already have been taken and the automatic refund can itself fail. Reconcile against GET /credits before retrying either; a blind retry reserves again.
- total: Approximate size of the matching set, capped at 10001. May be null when the count exceeds its internal time budget — the results themselves are unaffected, so use has_more to paginate.
- total_after_exclusion: Present only when excludeListId is sent. Matching rows after the exclusion, counted up to 10001; null when the count times out. When excludeListId is sent, `total` is counted the same way (up to 10001, nullable). A lower value proves rows were excluded; an equal value is inconclusive.
- exclusion_ignored_members: Present only when excludeListId is sent and some list members cannot match any record in this database (for example a malformed id). Those members are skipped.
- warning: Absent on almost every response. Present with `code: "SEARCH_COMMIT_UNCONFIRMED"`, `request_id` and `message` when the results were charged and delivered but we could not confirm the charge record. `credits_used` is still what you paid. Do not repeat the search, since that buys the rows again, and contact support with `request_id`. The rows are still unlocked for your account, so saving them is normally free. In the rarer case where that unlock could not be written either, `message` says a save may charge again: contact support before saving those IDs.
- businesses[].id: Business identifier
- businesses[].name: Business name
- businesses[].phone: Phone if known, else null
- businesses[].website: Website if known, else null
- businesses[].email: A business email that passed verification. May be an owner-name-derived address or a role-based one (info@, contact@) — read email_type to tell which, rather than assuming.
- businesses[].email_type: How the address was derived, not who reads it. "owner" means it matches a pattern built from the owner’s name (jane@, jane.doe@, jdoe@) and carries our verified label; "role" means a shared pattern such as info@ or contact@. An "owner" address is a name-derived address that passed verification — that is a verified label, NOT a deliverability guarantee (it is catch-all-blind and can be stale), and NOT proof that a person owns or reads the mailbox. Use it to rank and to decide whether personalising is sensible, not as an identity claim.
- businesses[].email_status: Verification verdict for the returned email. Always "safe" while the verified-only filter is forced on — included for parity with the CSV export, whose selection is user-controllable.
- businesses[].verified_at: When that email was last verified, if known, else null
- businesses[].address: Street address if known, else null
- businesses[].city: City if known, else null
- businesses[].state: State / province if known, else null
- businesses[].zip: Postal code if known, else null
- businesses[].rating: Google rating if known, else null
- businesses[].reviews: Google review count if known, else null
- businesses[].category: Google Maps category if known, else null
- businesses[].google_maps_url: Google Maps listing URL if known, else null
- businesses[].scraped_at: When this business was FIRST recorded, if known, else null — it never moves again. A re-scrape refreshes only name, rating and reviews; phone, website, address, category and google_maps_url keep their originally-scraped values indefinitely and no field reports their age. Read this as record age, and re-verify contact details independently rather than inferring freshness.
- businesses[].owner_name: The owner on record for the BUSINESS — not verified as the person who owns or uses the returned email. Present for 82.7% of returned businesses (289,129 / 349,630, measured 2026-07-25); null when unknown. Check email_type before merging this into a greeting: 8.8% of rows (30,603 / 349,630) pair a known owner name with a role address like info@. A role address is a shared alias and we do not track who reads it, so on those rows the owner name is unconfirmed for greeting purposes — the figure sizes that cohort, it is not a measured mis-delivery rate. All figures are database-wide snapshots, not per-query guarantees — a narrow filter can return far fewer. Resolved by a second lookup, so in rare cases a row matched by hasOwner can still come back with a null owner.
- businesses[].owner_title: The owner’s role at the business (e.g. "Owner", "President") if known, else null. Same caveats as owner_name.
Historical purchases require a separate repair.
Retries: responses do not currently carry an `artifact_id`, so de-duplicate on your side rather than relying on replay or re-fetch.
Rate limited per API key and per source IP; a 429 carries Retry-After.

### POST /creator-leads/search
Search podcasts and YouTube channels with contact emails, subscriber counts, and categories. Every result is restricted to a verified email — podcasts to a verified (non-catch-all) status, YouTube channels to those with a valid, non-catch-all verification verdict. Unverified, catch-all, and invalid emails are never returned.
Beta: the contract may change.
Access: Pro plan or higher, Bearer auth, REST only, not in MCP.
Credits: 1 lead credit per result returned. Reserved up to `size`, then refunded down to the actual row count. 0 results = 0 credits. A retried request is a new billable search. An `Idempotency-Key` header is accepted but has no effect at present, so de-duplicate on your side rather than relying on replay.
Request (JSON body):
- source ("youtube" | "podcast", required): Which creator type to search
- q (string): Free-text keyword search
- categories (string[]): Podcast category filters (exact match against the categories[] column). See GET /api/v1/meta/creator-podcast-categories.
- niches (string[]): YouTube niche filters (fuzzy ILIKE match). See GET /api/v1/meta/creator-youtube-niches for common values.
- country (string): YouTube country filter — comma-separated ISO codes (e.g. "US,GB"). See GET /api/v1/meta/creator-countries.
- language (string): Podcast language filter (e.g. "en"). See GET /api/v1/meta/creator-languages.
- minSubscribers (number): Minimum subscriber count (YouTube)
- maxSubscribers (number): Maximum subscriber count (YouTube)
- minEpisodes (number): Minimum episode count (podcasts)
- excludeListId (string): UUID of a saved list you own, and it must be a list whose kind matches `source`: kind "youtube" for source "youtube", kind "podcast" for source "podcast". GET /lists reports the kind of each list. Creators on that list are removed from the result set before billing, so excluded rows never cost credits. A blank or malformed id, a list that does not exist or is not yours, and a list of another kind each return 400. A list with more than 100,000 members returns 422 (code exclusion_too_large), and a temporary lookup failure returns 503 (code list_resolution_unavailable). All of these are returned before anything is reserved, with credits_used: 0.
- page (number): Page number (default: 1)
- size (number): Results per page, max 100 (default: 25)
Example request:
    {
      "source": "youtube",
      "niches": [
        "Marketing"
      ],
      "minSubscribers": 10000,
      "page": 1,
      "size": 25
    }
Example response:
    {
      "creators": [
        {
          "id": "yt_UC123abc",
          "name": "Marketing Weekly",
          "email": "hello@marketingweekly.com",
          "source": "youtube",
          "niche": "Marketing",
          "country": "US",
          "subscribers": 125000,
          "website": "https://marketingweekly.com"
        }
      ],
      "total": 1840,
      "page": 1,
      "size": 25,
      "has_more": true,
      "credits_used": 1
    }
Response fields:
- creators[].email: Contact email
- creators[].name: Channel / podcast name
- creators[].id: Creator identifier (prefixed yt_ for YouTube, pod_ for podcasts)
- creators[].source: "youtube" or "podcast"
- creators[].niche: YouTube channels only: the channel niche
- creators[].category: Podcasts only: the primary podcast category (returned in place of niche)
- creators[].country: Country code (YouTube)
- creators[].subscribers: Subscribers (YouTube)
- creators[].episodes: Podcasts only: episode count, or null when unknown (returned in place of subscribers)
- creators[].language: Podcasts only: the podcast language
- creators[].website: Website URL if known, else null
- total_after_exclusion: Present only when excludeListId is sent. Matching rows after the exclusion, counted up to 10001; null when the count times out. When excludeListId is sent, `total` is counted the same way (up to 10001, nullable). A lower value proves rows were excluded; an equal value is inconclusive.
- exclusion_ignored_members: Present only when excludeListId is sent and some list members cannot match any record in this database (for example a malformed id). Those members are skipped.
- has_more: true when this page was full - request the next page to continue; an empty page ends pagination
Retries: responses do not currently carry an `artifact_id`, so de-duplicate on your side rather than relying on replay or re-fetch.
Rate limited per API key and per source IP; a 429 carries Retry-After.

### GET /artifacts/{id}
NOT CURRENTLY ENABLED: billed searches do not return an `artifact_id` today and this endpoint returns 404 for every id. The contract below is what it serves once the feature is switched on. Re-fetch the result of a billed search you already paid for, using the `artifact_id` returned by /leads/search, /local-leads/search, or /creator-leads/search. Built for the case where the original response was lost — a dropped connection, a client timeout, a crashed consumer — so you do not have to re-run and re-pay for the same search. Artifacts are retained for 30 days and are tied to your user account, not to the API key that created them, so they survive key rotation and plan changes.
Beta: the contract may change.
Access: Pro plan or higher, Bearer auth, REST only, not in MCP.
Credits: Free. Retrieval is never billed — the search that produced the artifact was already charged.
Path parameters:
- id (string, required): The artifact_id returned by a billed search response.
Example response:
    {
      "artifact_id": "0f9d2c6a-2b47-4c5e-9a10-7b2c8d1e4f30",
      "endpoint": "/api/v1/leads/search",
      "created_at": "2026-08-03T12:00:00.000Z",
      "expires_at": "2026-09-02T12:00:00.000Z",
      "row_count": 25,
      "credits_charged": 25,
      "result": {
        "leads": [],
        "total": 1247,
        "page": 1,
        "size": 25,
        "has_more": true,
        "credits_used": 25
      }
    }
Response fields:
- result: The original search response, byte-for-byte as it was first returned
- credits_charged: Credits the original search cost
- expires_at: When this artifact is deleted (30 days after creation). A request after this returns 410.
Errors: 404 for an unknown, foreign, or unfinished artifact (a foreign id is deliberately 404, not 403); 410 once past the 30-day retention window. Not exposed through MCP while Beta.

### POST /placement-tests
Create an inbox placement test. Checking starts when the test is created, so there is no second call to make: send one email from the mailbox you want to test to every seed address within 15 minutes, with the test code anywhere in the subject or the body, then poll GET /placement-tests/{id}. Results usually arrive within about 2 minutes of sending. A test can complete before expires_at, 2 minutes after the last arrival, with the seeds still missing reported as not found. Until expires_at, such a seed is corrected if the email reaches it, and the score is rebuilt. Results are final at expires_at. If the test could not be started, the response says status "draft" with a next_step: call POST /placement-tests/{id}/sent after sending. If that draft already has a sent_at, its window runs from sent_at and closes at expires_at. At most 3 of your tests can be checking at once; another create is a 429 with code too_many_open_tests and a Retry-After header, is not charged, and is safe to retry.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: 1 lead credit per test, charged when the test is created. Refunded if creation fails. Not refunded for poor placement results. A retried request creates, and charges for, a new test. An `Idempotency-Key` header is accepted but has no effect at present, so de-duplicate on your side rather than relying on replay.
Request (JSON body):
- name (string): Optional label for the test (max 120 characters). Defaults to the subject.
- subject (string): Optional subject of the email you will send (max 998 characters). Used for the content check when no seed returns a body.
- body (string): Optional body of the email you will send (max 100,000 characters), for the same purpose.
Example request:
    {
      "name": "October outreach",
      "subject": "Quick question about your Q4 hiring",
      "body": "Hi Sam, ..."
    }
Example response (201):
    {
      "success": true,
      "data": {
        "id": "6b1f0c2e-5a3d-4f7e-9c21-0d8e4b7a9f10",
        "name": "October outreach",
        "status": "checking",
        "test_code": "IPT-abc12xyz",
        "seed_addresses": [
          { "email": "seed1@example.com", "provider": "google" },
          { "email": "seed2@example.com", "provider": "microsoft" }
        ],
        "seed_list": "seed1@example.com,seed2@example.com",
        "instructions": ["Send one email from the mailbox you want to test to every address in seed_addresses (To, Cc or Bcc). seed_list holds the same addresses as one comma-separated string.", "..."],
        "created_at": "2026-10-04T12:00:00.000Z",
        "sent_at": "2026-10-04T12:00:00.400Z",
        "expires_at": "2026-10-04T12:30:00.400Z"
      },
      "credits_used": 1
    }
Response fields:
- data.status: checking: the test is being watched, send your email now. draft: it could not be started; follow data.next_step.
- data.test_code: Put this anywhere in the subject or the body of the email you send.
- data.seed_addresses: Send one email to every one of these addresses. provider is google, microsoft, yahoo or other.
- data.seed_list: The same addresses as one comma-separated string, ready to paste into a To or Bcc field.
- data.expires_at: When results are final. A test can complete earlier and still correct a seed reported missing until then. Present when status is checking.
- data.next_step: Present only when status is draft.
- code: On a 429 from the open-test cap: too_many_open_tests (the rate limit's 429 has no code). Nothing was charged; retry after Retry-After seconds.

### POST /placement-tests/{id}/sent
Optional. A test created through the API is already checking, and calling this on a checking test changes nothing: it returns the current status and sent_at, so it can never extend the window. Call it when the create response said status "draft", once the email has gone out; checking then starts. A completed test is a 409 with code already_finished; create a new test to check again. A failed test is re-checked for free, but only while fewer than 3 of your tests are checking; otherwise it is the same 429 too_many_open_tests as a create, with Retry-After, and the test stays failed. A test whose creation failed and was refunded is a 409 with code not_charged and cannot be started. Another account's test, or an id that does not exist, is a 404.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: Free. The test was charged when it was created.
Path parameters:
- id (string, required): The test id returned by POST /placement-tests.
Example response:
    {
      "success": true,
      "data": { "id": "6b1f0c2e-5a3d-4f7e-9c21-0d8e4b7a9f10", "status": "checking", "sent_at": "2026-10-04T12:03:00.000Z", "expires_at": "2026-10-04T12:33:00.000Z" },
      "credits_used": 0
    }
Response fields:
- data.sent_at: When checking started. Set once and never moved by a later call.

### GET /placement-tests/{id}
Status, per-seed placement, a summary of where the email landed, and the 0 to 10 score and full report once built. Each seed shows where the email landed (inbox, spam, promotions and other tabs, not_found), delivery times, and the SPF, DKIM and DMARC verdicts that seed recorded. report_status is pending while the report is being built, ready once it is stored, and unavailable when it could not be built. Another account's test, or an id that does not exist, is a 404.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: Free.
Path parameters:
- id (string, required): The test id returned by POST /placement-tests.
Example response:
    {
      "success": true,
      "data": {
        "id": "6b1f0c2e-5a3d-4f7e-9c21-0d8e4b7a9f10",
        "name": "October outreach",
        "status": "completed",
        "created_at": "2026-10-04T12:00:00.000Z",
        "completed_at": "2026-10-04T12:31:00.000Z",
        "test_code": "IPT-abc12xyz",
        "sent_at": "2026-10-04T12:00:00.400Z",
        "expires_at": "2026-10-04T12:30:00.400Z",
        "score": 8.5,
        "summary": {
          "seeds": 2, "inbox": 1, "spam": 1, "missing": 0, "archived": 0, "undetermined": 0, "error": 0, "pending": 0,
          "tabs": { "primary": 0, "promotions": 1, "updates": 0, "social": 0, "forums": 0, "focused": 0, "other": 0 },
          "inbox_rate": 50
        },
        "seeds": [
          { "mailbox": "seed1@example.com", "provider": "google", "placement": "promotions", "sub_placement": "promotions", "received_at": "2026-10-04T12:03:20.000Z", "delivered_at": "2026-10-04T12:03:21.000Z", "discovered_at": "2026-10-04T12:04:02.000Z", "spf": "pass", "dkim": "pass", "dmarc": "pass" }
        ],
        "report_status": "ready",
        "report": { "score": 8.5, "report_version": 1, "built_at": "2026-10-04T12:33:00.000Z", "report": { "summary": {}, "providers": {}, "authentication": {}, "blacklist": {}, "content": {}, "domain_health": {} } }
      },
      "credits_used": 0
    }
Response fields:
- data.status: draft, checking, completed or failed.
- data.score: The 0 to 10 placement score, the one the app shows. Null until report_status is ready.
- data.summary: Seed counts: inbox (every tab counts, broken down in tabs), spam, missing (not found when the test completed, still corrected until expires_at if the email arrives), archived, undetermined, error, and pending (no result yet while the test is checking). inbox_rate is a percent of the seeds read.
- data.seeds[].provider: google, microsoft, yahoo or other.
- data.seeds[].placement: inbox, primary, promotions, updates, social, forums, spam, archived, not_found, unknown or error.
- data.report_status: pending, ready or unavailable once the test is completed; null before that.
- data.report: The built report: { score, report_version, built_at, report }. Null until report_status is ready.

### GET /placement-tests
Your placement tests, newest first. Only tests your account created are listed.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: Free.
Request (query):
- page (number): Page number, from 1 (default 1).
- size (number): Tests per page, 1 to 100 (default 25).
Example response:
    {
      "success": true,
      "data": {
        "tests": [
          { "id": "6b1f0c2e-5a3d-4f7e-9c21-0d8e4b7a9f10", "name": "October outreach", "status": "completed", "created_at": "2026-10-04T12:00:00.000Z", "completed_at": "2026-10-04T12:31:00.000Z", "report_status": "ready", "score": 8.5 }
        ],
        "page": 1,
        "size": 25,
        "has_more": false
      },
      "credits_used": 0
    }
Response fields:
- data.has_more: True when another page exists.

### POST /instagram/search
Search a database of Instagram profiles with filters on follower count, category, location, account type, and email data quality. Results can be filtered by verification status; all listed filters are optional. Pagination depth is capped at 100,000 results to prevent deep-offset performance issues.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: 1 lead credit per result returned. Reserved up to `size`, then refunded down to the actual row count. 0 results = 0 credits.
Request (JSON body):
- q (string): Case-insensitive text match on username or full name
- bioKeywords (string[]): Keywords to search for in profile bios
- excludeKeywords (string[]): Exclude profiles whose bio contains any of these keywords
- excludeAdultContent (boolean): Exclude profiles with adult/sexual content terms in their bio
- followerMin (number): Minimum follower count
- followerMax (number): Maximum follower count
- followingMin (number): Minimum following count
- followingMax (number): Maximum following count
- postsMin (number): Minimum post count
- postsMax (number): Maximum post count
- categories (string[]): Categories to filter by. See GET /api/v1/meta/instagram-categories for the canonical list.
- countries (string[]): Countries to filter by (exact match). See GET /api/v1/meta/instagram-countries for the canonical list.
- accountTypes (string[]): Account types to filter by (e.g. ["business", "personal"]). See GET /api/v1/meta/instagram-account-types for valid values.
- emailStatus (string[]): Email verification status to filter by (e.g. ["good", "risky", "bad", "catch_all"]). See GET /api/v1/meta/instagram-email-statuses for valid values.
- verified (boolean): Filter to only verified accounts
- hasEmail (boolean): Filter to only accounts with an email on file. Use emailStatus to filter by verification quality.
- hasPhone (boolean): Filter to only accounts with a phone number
- hasWebsite (boolean): Filter to only accounts with a website
- excludeListId (string): UUID of a saved list you own, and it must be an Instagram list (kind "instagram"). GET /lists reports the kind of each list. Profiles on that list are removed from the result set before billing, so excluded rows never cost credits. A blank or malformed id, a list that does not exist or is not yours, and a list of another kind each return 400. A list with more than 100,000 members returns 422 (code exclusion_too_large), and a temporary lookup failure returns 503 (code list_resolution_unavailable). All of these are returned before anything is reserved, with credits_used: 0.
- sortBy (string): Field to sort by (followers, posts, engagement, username)
- sortOrder (string): Sort order (asc or desc)
- page (number): Page number (default: 1). Keep (page - 1) * size ≤ 100,000 to avoid deep-offset performance issues.
- size (number): Results per page, max 100 (default: 25)
Example request:
    {
      "categories": [
        "Digital creator",
        "Photographer"
      ],
      "followerMin": 5000,
      "followerMax": 100000,
      "hasEmail": true,
      "page": 1,
      "size": 25
    }
Example response:
    {
      "data": [
        {
          "username": "john_photography",
          "full_name": "John Smith",
          "bio": "Professional photographer | Travel & lifestyle",
          "followers": 15400,
          "following_cnt": 342,
          "posts": 287,
          "category_std": "Photography",
          "email": "john@photography.com",
          "email_verification_status": "good",
          "email_verified_at": "2026-05-10T12:00:00Z",
          "phone": "+1-415-555-0100",
          "website": "https://johnphoto.com",
          "verified": true,
          "is_business": true,
          "is_private": false,
          "country": "US",
          "engagement_pct": 3.2
        }
      ],
      "total": 1247,
      "page": 1,
      "size": 25,
      "has_more": true,
      "credits_used": 1
    }
Response fields:
- data[].username: Instagram username
- data[].full_name: Profile display name
- data[].bio: Profile bio
- data[].followers: Follower count
- data[].following_cnt: Following count
- data[].posts: Post count
- data[].category_std: Standardized category
- data[].email: Contact email if available, else null
- data[].email_verification_status: Email verification status (good / risky / bad / catch_all)
- data[].email_verified_at: ISO timestamp of email verification, if verified
- data[].phone: Phone number if available, else null
- data[].website: Website URL if available, else null
- data[].verified: Instagram verified badge status
- data[].is_business: Whether the account is a business account
- data[].is_private: Whether the account is private
- data[].country: Country code if inferred
- data[].engagement_pct: Engagement rate as a percentage
- total: Total matching profiles before pagination
- total_after_exclusion: Present only when excludeListId is sent. Matching rows after the exclusion, counted up to 10001; null when the count times out. When excludeListId is sent, `total` is counted the same way (up to 10001, nullable). A lower value proves rows were excluded; an equal value is inconclusive.
- exclusion_ignored_members: Present only when excludeListId is sent and some list members cannot match any record in this database (for example a malformed id). Those members are skipped.
- has_more: true when this page was full - request the next page to continue; an empty page ends pagination
- credits_used: Lead credits charged for this request

### GET /lists
Return all saved lead lists owned by the authenticated API user, with member counts.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: Free.
Request: none.
Example response:
    {
      "lists": [
        {
          "id": "uuid-1",
          "name": "Q1 Prospects",
          "description": "CEOs in SaaS",
          "created_at": "2025-01-15T10:30:00Z",
          "member_count": 142
        }
      ]
    }
Response fields:
- lists[].id: List ID (use for add-leads)
- lists[].name: List name
- lists[].member_count: Number of leads

### POST /lists
Create a new saved lead list.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: Free.
Request (JSON body):
- name (string, required): List name
- description (string): Optional description
- kind (string): List kind: lead (B2B), business (local), podcast, youtube, or instagram (default: lead)
Example request:
    {
      "name": "Q1 Prospects",
      "description": "CEOs in SaaS",
      "kind": "lead"
    }
Example response (201):
    {
      "list": {
        "id": "uuid-1",
        "name": "Q1 Prospects",
        "description": "CEOs in SaaS",
        "kind": "lead",
        "created_at": "2025-01-15T10:30:00Z"
      }
    }
Response fields:
- list.id: New list ID
- list.kind: List kind (lead, business, podcast, youtube, instagram)

### POST /lists/{id}/add-leads
Add members to a saved list by email (B2B leads) or business ID (local leads). Duplicates are ignored. The payload must match the list's kind: send emails to a kind="lead" list and businessIds to a kind="business" list. A mismatch on a list that already has members is rejected with 400 LIST_KIND_MISMATCH and nothing is written; an empty list takes the kind of its first payload. Create the list with the matching kind first. Send only one of the two arrays per call.
Access: Pro plan or higher, Bearer auth, MCP tool available.
Credits: B2B email saves are free. Business IDs cost 1 lead credit per newly unlocked business with usable email data. IDs already unlocked by your account, including successful paid local searches, cost 0 additional credits. Duplicate IDs and businesses without email data do not cost credits.
Request (JSON body):
- emails (string[]): Array of B2B lead emails. Requires a list with kind="lead"
- businessIds (number[]): Up to 50,000 local business IDs. Requires a list with kind="business". Unpurchased IDs can consume lead credits.
Example request:
    {
      "emails": [
        "john@acme.com",
        "jane@acme.com"
      ]
    }
Example response:
    {
      "added": 2,
      "skipped": 0
    }
Response fields:
- added: Leads added to list
- skipped: Duplicates ignored
- credits_used: Business saves only: lead credits consumed by newly unlocked businesses.
- already_unlocked: Business saves only: businesses with usable email data already owned by this account.

## Error codes

- 400 Bad Request: Malformed body or invalid filter value. Validation responses include the field, the invalid values, and a hint pointing at the /api/v1/meta/{filter} endpoint that lists accepted values. Rejected before any credit is reserved, so never billed.
- 401 Unauthorized: The API key is missing or invalid. Check the Authorization header. Never billed.
- 402 Payment Required: Several causes: insufficient credits, a plan gate (reason "tier_required"), a usage cap, a billing lock, or paused lead access (reason "billing_past_due": the last payment failed, so lead endpoints are refused until billing is updated; is_owner: false means the key belongs to a team member and the team owner must update billing). Read the body; do not assume a top-up is the fix.
- 403 Forbidden: The current plan does not include this endpoint. Lead data endpoints require Pro or higher. Never billed.
- 404 Not Found: No lead matched the query on a find or enrich request. The reserved credit is refunded, but the route does not verify the refund succeeded.
- 429 Too Many Requests: Rate limited. Honor the Retry-After header or retry with exponential backoff.
- 500 Server Error: The request failed inside Consulti. On billed endpoints treat it as possibly charged and do not retry automatically: every retry is a new billable request with no replay protection. With code refund_unconfirmed the refund could not be confirmed. Reconcile with GET /credits before any retry. If a 500 persists, contact support with the request id.
- 503 Service Unavailable: Temporarily unavailable; what it means for billing depends on the endpoint. POST /verify returns code verifier_unavailable with credits_used: 0 and a Retry-After header, and only after the reserved credit is confirmed refunded, so it can be retried after Retry-After. POST /leads/search (code search_unavailable or search_timeout; narrow the filters on a timeout) and POST /verify/catchall (code verifier_unavailable) send a Retry-After header but no credits_used, so they are billing-ambiguous: reconcile with GET /credits, then retry after Retry-After. A slow /verify/catchall call can run for up to 300 seconds, so give it a client timeout of more than 300 seconds.

Billing on errors: 400, 401 and 403 are rejected before any credit is reserved, so they are unbilled. 402, 404 and 5xx are billing-ambiguous: a reservation may already have been taken and the automatic refund can fail without reporting it, so a credits_used: 0 (or a missing credits_used) on those does not prove you were not charged. The one exception is a /verify 503 with code verifier_unavailable and credits_used: 0, which is sent only after the refund is confirmed. Otherwise reconcile with GET /credits before retrying: a blind retry reserves again and you can pay twice for one set of results.

All errors return: { "success": false, "error": "message", "code"?: "stable_error_code", "hint"?: "...", "field"?: "...", "credits_used"?: number }

## Command line

Consulti has a command line for the same stable endpoints. Needs Node.js 20 or newer.

Install: curl -fsSL https://consulti.ai/install.sh | bash   (or: npm i -g consulti)

Log in with: consulti login. On a terminal it asks for your API key at a hidden prompt; without one it reads a single line from stdin. Then run: consulti credits

For CI or servers you can set CONSULTI_API_KEY instead.

Package: https://www.npmjs.com/package/consulti

## MCP Server

Consulti.ai publishes an MCP server that exposes its stable endpoints as tools for Claude Desktop, Cursor, and other MCP clients. Beta endpoints are REST-only and not exposed via MCP.

Install: npx -y consulti-mcp

Claude Desktop config:

    {
      "mcpServers": {
        "consulti": {
          "command": "npx",
          "args": [
            "-y",
            "consulti-mcp"
          ],
          "env": {
            "CONSULTI_API_KEY": "capi_your_api_key"
          }
        }
      }
    }

Available tools:
- verify_email: Verify if an email address is valid and deliverable
- verify_catchall: Resolve a mailbox on a catch-all domain (ESP engine) when verify_email returns is_catch_all
- enrich_lead: Enrich a lead's full profile using their email address, including company-level data when linked
- enrich_linkedin: Enrich a person by their LinkedIn URL → verified work email + US mobile phone
- search_b2b_leads: Search B2B leads with filters (title, industry, location, size)
- search_instagram_profiles: Search Instagram profiles with filters (followers, category, location, email)
- get_lists: Get all saved lists for the authenticated user, with each list kind
- create_list: Create a new saved list, choosing the kind of member it holds
- add_leads_to_list: Save emails for free, or business IDs with credits charged only for new business unlocks
- get_credits: Check your current lead and verification credit balance
- create_placement_test: Create an inbox placement test (1 lead credit, Pro plan or higher) and get the seed addresses to send to
- mark_placement_test_sent: Start checking a placement test that was created as a draft, once the email has been sent
- get_placement_test: Get a placement test with per-seed placement, summary, score and report
- list_placement_tests: List your placement tests, newest first

## Agent Skill

A guided skill package (SKILL.md + reference files) teaches coding agents to scope tasks, validate filters, and estimate credit cost before spending. Install for Claude Code:

    curl -fsSL https://www.consulti.ai/skill/install.sh | bash

For Codex CLI, append: -s -- --dir ~/.agents/skills/consulti

## Canonical filter values

Every accepted value for every enum filter, inlined so an LLM doesn't need a tool call to know what's valid. Source of truth: lib/api/canonical/*.json (refreshed via npm run sync:canonical-lists). For machine-readable JSON, GET /api/v1/meta/{filter} or GET /api/v1/meta/_all.

### industries (b2b-industries) — 145 values
Accounting, Agriculture, Airlines/Aviation, Alternative Dispute Resolution, Alternative Medicine, Animation, Apparel & Fashion, Architecture & Planning, Arts & Crafts, Automotive, Aviation & Aerospace, Banking, Biotechnology, Broadcast Media, Building Materials, Business Supplies & Equipment, Capital Markets, Chemicals, Civic & Social Organization, Civil Engineering, Commercial Real Estate, Computer Games, Computer Hardware, Computer Networking, Computer & Network Security, Computer Software, Construction, Consumer Electronics, Consumer Goods, Consumer Services, Cosmetics, Dairy, Defense & Space, Design, Education Management, E-Learning, Electrical/Electronic Manufacturing, Entertainment, Environmental Services, Events Services, Executive Office, Facilities Services, Farming, Financial Services, Fine Art, Fishery, Food & Beverages, Food Production, Fund-Raising, Furniture, Gambling & Casinos, Glass, Ceramics & Concrete, Government Administration, Government Relations, Graphic Design, Health, Wellness & Fitness, Higher Education, Hospital & Health Care, Hospitality, Human Resources, Import & Export, Individual & Family Services, Industrial Automation, Information Services, Information Technology & Services, Insurance, International Affairs, International Trade & Development, Internet, Investment Banking, Investment Management, Law Enforcement, Law Practice, Legal Services, Legislative Office, Leisure, Travel & Tourism, Libraries, Logistics & Supply Chain, Luxury Goods & Jewelry, Machinery, Management Consulting, Maritime, Marketing & Advertising, Market Research, Mechanical or Industrial Engineering, Media Production, Medical Devices, Medical Practice, Mental Health Care, Military, Mining & Metals, Motion Pictures & Film, Museums & Institutions, Music, Nanotechnology, Nonprofit Organization Management, Oil & Energy, Online Media, Outsourcing/Offshoring, Package/Freight Delivery, Packaging & Containers, Paper & Forest Products, Performing Arts, Pharmaceuticals, Philanthropy, Photography, Plastics, Political Organization, Primary/Secondary Education, Printing, Professional Training & Coaching, Program Development, Public Policy, Public Relations & Communications, Public Safety, Publishing, Railroad Manufacture, Ranching, Real Estate, Recreational Facilities & Services, Religious Institutions, Renewables & Environment, Research, Restaurants, Retail, Security & Investigations, Semiconductors, Shipbuilding, Sporting Goods, Sports, Staffing & Recruiting, Telecommunications, Textiles, Think Tanks, Tobacco, Translation & Localization, Transportation/Trucking/Railroad, Utilities, Venture Capital & Private Equity, Veterinary, Warehousing, Wholesale, Wine & Spirits, Wireless, Writing & Editing

### countries (b2b-countries) — 198 values
Afghanistan, Albania, Algeria, Andorra, Angola, Argentina, Arizona, Armenia, Aruba, Australia, Austria, Azerbaijan, Bahrain, Bangladesh, Barbados, Belarus, Belgium, Belize, Benin, Bermuda, Bolivia, Bosnia and Herzegovina, Botswana, Brazil, Bulgaria, Burkina Faso, California, Cambodia, Cameroon, Canada, Cayman Islands, Chile, China, Colombia, Colorado, Costa Rica, Cote d'Ivoire, Cote D'ivoire, Croatia, C??te d'Ivoire, Curacao, Cyprus, Czechia, Czech Republic, Democratic Republic of the Congo, Denmark, District of Columbia, Dominican Republic, Ecuador, Egypt, El Salvador, Estonia, Ethiopia, Fiji, Finland, Florida, France, Georgia, Germany, Ghana, Gibraltar, Greece, Guam, Guatemala, Guernsey, Guinea, Haiti, Honduras, Hong Kong, Hungary, Iceland, Illinois, India, Indiana, Indonesia, Iran, Iraq, Ireland, Isle of Man, Israel, Italy, Jamaica, Japan, Jersey, Jordan, Kazakhstan, Kenya, Kosovo, Kuwait, Kyrgyzstan, Laos, Latvia, Lebanon, Liberia, Libya, Liechtenstein, Lithuania, Luxembourg, Macau, Madagascar, Malawi, Malaysia, Maldives, Mali, Malta, Maryland, Massachusetts, Mauritius, Mexico, Michigan, Minnesota, Missouri, Moldova, Monaco, Mongolia, Montenegro, Morocco, Mozambique, Namibia, Nepal, Netherlands, New Jersey, New York, New Zealand, Nicaragua, Nigeria, North Carolina, North Macedonia, Norway, Ohio, Oman, Oregon, Pakistan, Palestine, Panama, Papua New Guinea, Paraguay, Pennsylvania, Peru, Philippines, Poland, Portugal, Puerto Rico, Qatar, Republic of Indonesia, Republic of the Union of Myanmar, REVIEW_REQUIRED, Romania, Russia, Rwanda, Saint Lucia, Saudi Arabia, Senegal, Serbia, Singapore, Slovakia, Slovenia, Somalia, South Africa, South Korea, Spain, Sri Lanka, Suriname, Sweden, Switzerland, Syria, Taiwan, Tanzania, Tennessee, Texas, Thailand, The Bahamas, Trinidad and Tobago, Tuerkiye, Tunisia, Turkey, Uganda, Ukraine, United Arab Emirates, United Kingdom, United States, Uruguay, U.S. Virgin Islands, Utah, Uzbekistan, Venezuela, Vietnam, Virginia, Washington, Wisconsin, Zambia, Zimbabwe, US, CA, GB, AU, NZ, IE

### states (b2b-states) — 942 values
Aargau, Abidjan, Abidjan Autonomous District, Abruzzo, Abu Dhabi, Adana, Addis Ababa, Adjara, Administrative unit Maribor, Aguascalientes, Ajman, Akershus, Akmola Region, Alabama, Alagoas, Al Ahmadi Governorate, Alajuela, Alajuela Province, Al Asimah, Al Asimah Governate, Alaska, Alberta, Alexandria Governorate, Algiers Province, Al Madinah Province, Almaty Province, Al Qassim, Al Rayyan Municipality, Alsace, Amazonas, Amman, Amman Governorate, Andalucia, Andalucía, Andalusia, Andhra Pradesh, Ankara, Ankara Province, Antalya, Antioquia, Antofagasta Region, Appenzell Ausserrhoden, Apulia, Aquitaine, Arad County, Aragon, Araucania, Arizona, Arkansas, Aseer Province, Ashanti, Assam, Asturias, Atlanta, Atlantico, Attica, Attica region, Auckland, Aust-Agder, Australian Capital Territory, Autonomous City of Buenos Aires, Auvergne, Auvergne-Rhone-Alpes, Auvergne-Rhône-Alpes, Aveiro, Aveiro District, Bacs-Kiskun, Baden-Wuerttemberg, Baden-Württemberg, Baghdad Governorate, Bahia, Baja California, Baja California Sur, Balearic Islands, Bali, Baltimore, Bangkok, Banska Bystrica Region, Banten, Baranya, Basel-Landschaft, Basel-Stadt, Basilicata, Basque Country, Bavaria, Bayern, Bay of Plenty, Bay Of Plenty, Beijing, Beirut Governorate, Ben Arous, Berlin, Bihar, Bihor County, Bio Bio, Bio-Bio, Blekinge County, Bogota, Bolivar, Borsod-Abauj-Zemplen, Boston, Bourgogne-Franche-Comte, Braga, Brandenburg, Brașov County, Bratislava Region, Bremen, British Columbia, Brittany, Brussel, Brussels, Bucharest, Budapest, Buenos Aires Province, Burgenland, Burgundy, Bursa, Buskerud, Cairo Governorate, Cajamarca, Calabarzon, Calabria, Caldas, California, Campania, Campeche, Canarias, Canary Islands, Cantabria, Canterbury, Canton of Bern, Canton of Fribourg, Canton of Jura, Canton of Neuchatel, Canton of Schaffhausen, Canton of Schwyz, Canton of Solothurn, Canton of Zug, Capital District, Capital Governorate, Capital Region, Capital Region of Denmark, Carinthia, Carlow, Casablanca-Settat, Castelo Branco District, Castile and Leon, Castile and León, Castile-La Mancha, Castilla-La Mancha, Castilla y Leon, Castilla Y Leon, Castilla y León, Catalonia, Catalunya, Ceara, Celje, Center District, Central Bohemian Region, Central Denmark Region, Central Development Region, Central Java, Central Luzon, Central Province, Central Region, Central Serbia, Central Visayas, Centre, Centre-Val de Loire, Centre-Val De Loire, Champagne-Ardenne, Chandigarh, Chhattisgarh, Chiang Mai, Chiapas, Chiba Prefecture, Chicago, Chihuahua, Chisinau, Chittagong Division, Chon Buri, City of Zagreb, Ciudad de Mexico, Ciudad De Mexico, Ciudad de México, Clare, Cluj County, Coahuila, Coahuila de Zaragoza, Coimbra, Coimbra District, Colima, Colorado, Community of Madrid, Comunidad de Madrid, Comunidad De Madrid, Comunidad Valenciana, Comunitat Valenciana, Connecticut, Constanta County, Coquimbo Region, Cordoba, Cork, Corrientes Province, Corsica, Cortes, County Cork, County Donegal, County Dublin, County Galway, County Kerry, County Kildare, County Kilkenny, County Limerick, County Louth, County Mayo, County Meath, County Waterford, County Westmeath, County Wicklow, Csongrad, Cundinamarca, Dakar Region, Dalarna County, Dallas, Da Nang, Dar es Salaam, Dar Es Salaam, Davao Region, Delaware, Delhi, Denver, Dhaka Division, District of Columbia, Distrito Federal, Distrito Nacional, Dnipropetrovsk Oblast, Doha, Domzale, Donegal, Drenthe, Dubai, Dublin, Durango, Eastern, Eastern Cape, Eastern Province, East Java, East Kalimantan, Edo, Emilia-Romagna, England, Entre Rios, Eskisehir Province, Espirito Santo, Estado de Mexico, Estado De Mexico, Euskadi, Evora District, Extremadura, Falcon, Faro, Faro District, Federal Capital Territory, Federal District, Federal Territory of Kuala Lumpur, Federation of Bosnia and Herzegovina, Fejer, Flanders, Flevoland, Florida, Franche-Comte, Francisco Morazan, Free State, Fribourg, Friesland, Friuli-Venezia Giulia, Fujian, Galicia, Galway, Gauteng, Gavleborg County, Gaziantep, Gelderland, Geneva, George Town, Georgia, Giza Governorate, Goa, Goias, Gotland County, Grand Casablanca, Grand Est, Greater Accra, Greater Accra Region, Greater Poland Voivodeship, Greater Skopje, Grisons, Groningen, Guanajuato, Guangdong, Guatemala, Guatemala Department, Guayas, Guerrero, Gujarat, Gyeonggi-do, Gyor-Moson-Sopron, Haifa District, Hajdu-Bihar, Halland County, Hamburg, Hanoi, Harare Province, Harju County, Haryana, Hauts-de-France, Hauts-De-France, Hawaii, Hawalli Governorate, Hawke's Bay, Heredia Province, Hesse, Hessen, Heves County, Hidalgo, Himachal Pradesh, Hlavni mesto Praha, Hlavni Mesto Praha, Hlavní město Praha, Ho Chi Minh, Hong Kong Island, Hordaland, Houston, Hradec Kralove Region, Hradec Králové Region, Iași County, Idaho, Ile-de-France, Ile-De-France, Île-de-France, Ilfov County, Illes Balears, Illinois, Indiana, Innlandet, Iowa, Islamabad Capital Territory, Istanbul, İstanbul, Istanbul Province, Istria County, Izmir, Jakarta, Jalisco, Jamtland County, Jasz-Nagykun-Szolnok, Jerusalem District, Jharkhand, Jiangsu, Johor, Jonkoping County, Kalmar County, Kanagawa Prefecture, Kandal Province, Kansas, Kaohsiung City, Karnataka, Kaunas County, Kayseri Province, Kedah, Kentucky, Kerala, Kerry, Kharkiv Oblast, Khomas, Khyber Pakhtunkhwa, Kigali, Kigali City, Klaipeda County, Kocaeli, Komarom-Esztergom, Konya, Koper, Kosice Region, Kowloon, Kranj, Kronoberg County, Kurdistan Region, Kuyavian-Pomeranian Voivodeship, Kwazulu-Natal, KwaZulu-Natal, Kyiv city, Kyiv City, Lagos, Lagunes, Lagunes Region, La Libertad, Languedoc-Roussillon, Lapland, La Rioja, Larnaca, Lazio, Leiria, Leiria District, Lesser Poland Voivodeship, Liaoning, Liberec Region, Liguria, Lima, Lima Region, Limassol, Limburg, Limerick, Limousin, Limpopo, Lisboa, Lisbon, Littoral, Ljubljana, Lodz Voivodeship, Łódź Voivodeship, Lombardia, Lombardy, Lorraine, Los Angeles, Los Lagos Region, Louisiana, Louth, Lower Austria, Lower Normandy, Lower Saxony, Lower Silesian Voivodeship, Luanda Province, Lublin Voivodeship, Lubusz Voivodeship, Lucerne, Lusaka, Luxembourg, Luxembourg District, Lviv Oblast, Madeira, Madhya Pradesh, Maharashtra, Maine, Makedonia Thraki, Makkah Province, Malacca, Male, Managua, Managua Department, Manawatu-Wanganui, Manitoba, Maputo City, Maranhao, Marche, Maryland, Masovian Voivodeship, Massachusetts, Mato Grosso, Mato Grosso do Sul, Maule Region, Mayo, mazowieckie, Meath, Mecklenburg-Vorpommern, Mendoza Province, Metro Manila, Mexico City, Michigan, Michoacan, Minas Gerais, Minneapolis, Minnesota, Minsk Region, Mississippi, Missouri, Montana, Montevideo Department, Moravian-Silesian Region, Morelos, More og Romsdal, More Og Romsdal, Moscow, Mount Lebanon Governorate, Mpumalanga, Mugla, Muharraq Governorate, Muscat Governorate, N/A, Nairobi, Nairobi County, Nashville, National District, Navarre, Nayarit, Nebraska, Negeri Sembilan, Nelson, Neuchatel, Nevada, New Brunswick, Newfoundland and Labrador, New Hampshire, New Jersey, New Mexico, New Providence, New South Wales, New Taipei City, New Territories, New York, Nicosia, Nidwalden, Nitra Region, Nonthaburi, Noord-Brabant, Noord-Holland, Nordland, Nord-Pas-de-Calais, Nord-Pas-De-Calais, Nordrhein-Westfalen, Normandy, Norrbotten County, North Brabant, North Carolina, North Dakota, North Denmark Region, North District, Northern Cape, Northern Governorate, Northern Ireland, Northern Mindanao, Northern Ostrobothnia, Northern Territory, North Governorate, North Holland, North Karelia, Northland, North Rhine-Westphalia, North Sumatra, North West, Northwest Territories, Nouvelle-Aquitaine, Nova Gorica, Nova Scotia, Nuevo Leon, Oaxaca, Occitanie, Odessa Oblast, Odisha, Ogun State, O'Higgins Region, Ohio, Oklahoma, Olomouc Region, Ontario, Opole Voivodeship, Orebro County, Örebro County, Oregon, Osaka Prefecture, Osijek-Baranja County, Oslo, Ostergoetland County, Ostergoetlands laen, Östergötland County, Ostfold, Otago, Overijssel, Oyo, Pahang, Panama, Paphos, Para, Paraiba, Parana, Pardubice Region, Pays de la Loire, Pays De La Loire, PE, Penang, Pennsylvania, Perak, Pernambuco, Pest County, Phnom Penh, Phuket, Piaui, Picardy, Pichincha, Piedmont, Piemonte, Pirkanmaa, Plaines Wilhems District, Plovdiv Province, Plzen Region, Podgorica Municipality, Podkarpackie Voivodeship, Podlaskie Voivodeship, Poitou-Charentes, Pomeranian Voivodeship, Porto, Porto District, Port of Spain, Prahova, Presov Region, Primorje-Gorski Kotar County, Prince Edward Island, Principado de Asturias, Provence-Alpes-Cote d'Azur, Provence-Alpes-Cote D'azur, Provence-Alpes-Côte d'Azur, Provincia de Alajuela, Puducherry, Puebla, Puglia, Punjab, Putrajaya, Quebec, Québec, Queensland, Queretaro, Querétaro, Quintana Roo, Rabat-Sale-Kenitra, Rajasthan, Ras al Khaimah, Ras Al Khaimah, Rayong, Region de Murcia, Region De Murcia, Región de Murcia, Region Metropolitana, Region of Murcia, Region of Southern Denmark, Region Syddanmark, Region wallonne, Region Wallonne, Region Zealand, Republika Srpska, Rheinland-Pfalz, Rhineland-Palatinate, Rhode Island, Rhone-Alpes, Riau, Riau Islands, Riga, Rigas pilseta, Rio de Janeiro, Rio De Janeiro, Rio Grande do Norte, Rio Grande do Sul, Rio Grande Do Sul, Risaralda, Rivers, Riyadh Province, Rogaland, Saarland, Sabah, Sachsen, Saint Petersburg, Sakarya, Salzburg, San Francisco, San Jose, San Jose Province, San Juan, San Luis Potosi, San Salvador, San Salvador Department, Santa Catarina, Santa Cruz, Santa Fe Province, Santander Department, Santarem, Santarem District, Santiago Metropolitan Region, Sao Paulo, Sarawak, Sardegna, Sardinia, Saskatchewan, Satakunta, Saxony, Saxony-Anhalt, Schleswig-Holstein, Schwyz, Scotland, Seattle, Selangor, Sergipe, Setubal, Shaanxi, Shandong, Shanghai, Sharjah, Sibiu, Sichuan, Sicilia, Sicily, Siem Reap, Siem Reap Province, Silesian Voivodeship, Sinaloa, Sindh, Skane County, Skåne County, Sligo, Sodermanland County, Södermanland County, Soedermanland County, Sofia City Province, Solothurn, Sonora, South Australia, South Bohemian Region, South Carolina, South Dakota, South District, South-East District, Southern Governorate, Southern Region, South Holland, South Moravian Region, South Sulawesi, South Sumatra, Southwest Finland, Special Capital Region of Jakarta, Special Region of Yogyakarta, Split-Dalmatia County, St. Andrew Parish, State of Bahia, State of Ceara, State of Espirito Santo, State of Goias, State of Mexico, State of Minas Gerais, State of Parana, State of Pernambuco, State of Rio de Janeiro, State of Rio De Janeiro, State of Rio Grande do Sul, State of Rio Grande Do Sul, State of Rondonia, State of Santa Catarina, State of Sao Paulo, State of São Paulo, St. Gallen, St Helier, Stockholm County, Styria, Swietokrzyskie, Szabolcs-Szatmar-Bereg, Tabasco, Tabuk Province, Taichung City, Tainan City, Taipei City, Tamaulipas, Tamil Nadu, Tangier-Tetouan-Al Hoceima, Taranaki, Tartu County, Tashkent Province, Tasmania, Tbilisi, Tehran Province, Tekirdag, Telangana, Tel Aviv District, Tennessee, Texas, Thurgau, Thuringia, Tianjin, Ticino, Timiș County, Tipperary, Tirana County, Tocantins, Tokyo, Toscana, Trencin Region, Trentino-Alto Adige, Trentino-Alto Adige/south Tyrol, Trentino-Alto Adige/South Tyrol, Trnava Region, Troms, Trondelag, Tucuman, Tunis, Tuscany, Tyrol, Ulaanbaatar, Umbria, United States, Upper Austria, Upper Normandy, Uppsala County, Usti Nad Labem Region, Utah, Utrecht, Uttarakhand, Uttar Pradesh, Uusimaa, Vaesterbotten County, Vaesternorrland County, Vaestmanland County, Vaestra Goetaland County, Valais, Valencian Community, Valle del Cauca, Valle Del Cauca, Valparaiso, Valparaiso Region, Varazdin County, Varmland County, Varna, Västerbotten County, Västernorrland County, Västmanland County, Västra Götaland County, Vaud, Veneto, Veracruz, Vermont, Vest-Agder, Vestfold, Vestfold og Telemark, Vestland, Veszprem, Viana do Castelo District, Victoria, Vienna, Viken, Vilnius County, Virginia, Viseu District, Vlaams Gewest, Vojvodina, Vorarlberg, Vysocina Region, Waikato, Wales, Wallonia, Walloon Region, Warmian-Masurian Voivodeship, Washington, Waterford, Wellington, West Bengal, Western Australia, Western Cape, Western Province, Western Visayas, West Java, Westmeath, West Pomeranian Voivodeship, West Virginia, Wexford, Wicklow, Wisconsin, Wyoming, Yangon Region, Yerevan, Yucatan, Yukon Territory, Zacatecas, Zadar County, Zagreb County, Zala County, Zeeland, Zhejiang, Zilina Region, Zlin Region, Zuid-Holland, Zurich, AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY, DC, ON, QC, BC, AB, MB, SK, NS, NB, NL, NT, Nunavut, NU, Yukon, YT

### email-statuses (b2b-email-statuses) — 6 values
bad, good, invalid, risky, unknown, valid

### technologies (b2b-technologies) — 7538 values (not inlined)
Too large to inline. GET /api/v1/meta/technologies for the full list. Non-strict filter: values outside the list still work. Examples: Shopify, WordPress, HubSpot, Salesforce, Wix, Squarespace, Webflow, WooCommerce, Google Analytics, Marketo, Stripe, Intercom, ...

### local-states (gmaps-states) — 128 values
AB, AK, AL, AR, AZ, BC, CA, CO, CT, DC, DE, FL, GA, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MI, MN, MO, MS, MT, NB, NC, ND, NE, NH, NJ, NM, NS, NV, NY, OH, OK, ON, OR, PA, QC, RI, SC, SD, SK, TN, TX, UT, VA, VT, WA, WI, WV, WY, Alabama, Alaska, Arizona, Arkansas, California, Colorado, Connecticut, Delaware, Florida, Georgia, Hawaii, Idaho, Illinois, Indiana, Iowa, Kansas, Kentucky, Louisiana, Maine, Maryland, Massachusetts, Michigan, Minnesota, Mississippi, Missouri, Montana, Nebraska, Nevada, New Hampshire, New Jersey, New Mexico, New York, North Carolina, North Dakota, Ohio, Oklahoma, Oregon, Pennsylvania, Rhode Island, South Carolina, South Dakota, Tennessee, Texas, Utah, Vermont, Virginia, Washington, West Virginia, Wisconsin, Wyoming, District of Columbia, Alberta, British Columbia, Manitoba, New Brunswick, Newfoundland and Labrador, Northwest Territories, Nova Scotia, Nunavut, Ontario, Prince Edward Island, Quebec, Saskatchewan, Yukon, MB, NL, NT, NU, PE, YT

### local-email-statuses (gmaps-email-statuses) — 2 values
risky, safe

### creator-podcast-categories (creator-podcast-categories) — 243 values
After-Shows, Alternative, Animals, Animation, Arts, Astronomy, Automotive, Aviation, Baseball, Basketball, Beauty, Books, Buddhism, Business, Business News, Careers, Chemistry, Christianity, Comedy, Comedy Interviews, Commentary, Courses, Crafts, Cricket, Culture, Daily, Daily News, Design, Documentary, Drama, Earth, Earth Sciences, Education, Education for Kids, Entertainment, Entertainment News, Entrepreneurship, Family, Fantasy, Fashion, Fashion & Beauty, Fiction, Film, Fitness, Food, Football, Games, Garden, Golf, Government, Health, Health & Fitness, Hinduism, History, Hobbies, Hockey, Home, Home & Garden, How To, Improv, Interviews, Investing, Islam, Journals, Judaism, Kids, Kids & Family, Language, Language Learning, Learning, Leisure, Life, Life Sciences, Management, Manga, Marketing, Mathematics, Medicine, Mental, Mental Health, Music, Natural, Natural Sciences, Nature, News, News Commentary, Non-Profit, Non-profit, Nutrition, Parenting, Performing, Performing Arts, Personal, Personal Journals, Pets, Philosophy, Physics, Places, Places & Travel, Podcasts, Politics, Relationships, Religion, Religion & Spirituality, Reviews, Rugby, Running, Science, Self Improvement, Self-Improvement, Sexuality, Soccer, Social, Social Sciences, Society, Society & Culture, Spirituality, Sports, Sports News, Stand-Up, Stand-up, Stories, Swimming, TV & Film, Tech News, Technology, Tennis, Travel, True Crime, Tv, Video Games, Visual, Visual Arts, Volleyball, Wilderness, Wrestling, after-shows, alternative, animals, animation, arts, astronomy, automotive, aviation, baseball, basketball, beauty, books, buddhism, business, careers, chemistry, christianity, comedy, commentary, courses, crafts, cricket, culture, daily, design, documentary, drama, earth, education, entertainment, entrepreneurship, family, fantasy, fashion, fiction, film, fitness, food, football, games, garden, golf, government, health, hinduism, history, hobbies, hockey, home, how to, improv, interviews, investing, islam, journals, judaism, kids, language, learning, leisure, life, management, manga, marketing, mathematics, medicine, mental, music, natural, nature, news, non-profit, nutrition, parenting, performing, personal, pets, philosophy, physics, places, politics, relationships, religion, reviews, rugby, running, science, self improvement, sexuality, soccer, social, society, spirituality, sports, stand-up, stories, swimming, technology, tennis, travel, true crime, tv, video games, visual, volleyball, wilderness, wrestling

### creator-podcast-email-statuses (creator-podcast-email-statuses) — 4 values
catch_all, invalid, unknown, valid

### creator-youtube-niches (creator-youtube-niches) — 361 values
3d, 401k, SEO, ableton, abs, accounting, acne, acrylic, adobe, aerospace, affiliate, after, agency, ai, airbnb, altcoin, amateur, amazon, ancient, angel, angular, animal, animation, anime, anthropology, anti, apex, api, apple, aquaponics, aquarium, archery, arduino, argumentation, asmr, astrophotography, async, athletic, atomic, audiobook, augmented, autism, auto, automation, b2b, baby, backpacking, bakery, barbershop, baseball, basement, basketball, beauty, betta, biohacking, biology, biomedical, bird, blogging, bluesky, body, bohemian, bootstrapped, bouldering, brand, brazilian, bread, budget, budgeting, bushcraft, business, calligraphy, camera, capsule, car, career, cat, chemical, chemistry, chicken, chinese, chromebook, cleaning, cockatiel, coding, coffee, cold, college, color, commercial, commodities, community, composting, computer, construction, consulting, content, cooking, copywriting, cosplay, coworking, creator, credit, critical, crochet, cryptocurrency, curly, cybersecurity, data, dating, day, daycare, debate, debt, decision, deck, declutter, deep, dental, devops, devrel, digital, diorama, direct, discord, divorce, diy, drift, drone, dropshipping, ecology, ecommerce, electric, electrician, electronics, elimination, email, embroidery, emergency, engine, engineering, entrepreneur, entrepreneurship, equity, esp32, esports, estate, event, existentialism, expat, facebook, family, fantasy, farmhouse, fashion, ferret, film, filmmaking, final, financial, fitness, flag, fodmap, food, forensic, forex, fortnite, fpv, freelancing, french, functional, funnel, furniture, game, gaming, garage, german, ghost, github, goal, goat, golf, google, grad, graphic, grief, growth, guitar, hair, harley, healthy, home, homeschool, horse, hot, house, hr, hydroponics, hypercar, import, indian, indie, information, instagram, interior, international, investing, japanese, javascript, jdm, jeep, journaling, knitting, korean, language, latin, law, lego, library, linkedin, linux, local, long, luxury, machine, macro, map, market, marriage, mba, meal, mechanic, mechanical, medical, meditation, mens, mental, mid, minecraft, mma, mobile, model, montessori, mortgage, motorcycle, music, natural, nft, no, note, notion, nutrition, obstacle, online, overland, overlanding, parenting, passive, peer, perfume, permaculture, personal, pharmacy, photography, photoshop, pizza, podcast, podcasting, pottery, powerlifting, pro, product, programming, public, react, real, relationship, remote, rescue, research, restaurant, resume, roblox, rowing, running, rv, saas, sales, salon, scholarship, science, screenwriting, self, senior, sewing, sign, single, site, skincare, small, smart, sober, soccer, social, software, solar, solo, space, speedrun, sponsor, sportbike, sports, stable, startup, stock, stop, streaming, study, supplement, surfing, sustainability, sustainable, tabletop, target, tattoo, tax, tech, technical, tennis, terminal, terraform, tesla, thai, threads, thrift, tiktok, transmission, travel, truck, trucking, twitch, ultrawide, van, veterinary, video, vlogging, vr, water, wealth, web, web3, wedding, weight, whiteboard, wildlife, wood, workout, writing, yoga, youtube, zoo

### creator-languages (creator-languages) — 31 values
EN, English, de, en, en-AU, en-CA, en-EN, en-GB, en-IE, en-IN, en-NZ, en-PI, en-UK, en-US, en-ZA, en-au, en-ca, en-en, en-gb, en-ie, en-jm, en-nz, en-ph, en-tt, en-uk, en-us, en-za, en-zw, en_US, eng, english

### creator-countries (creator-countries) — 66 values
AE, AT, AU, Australia, BD, BE, BR, Bangladesh, Brazil, CA, CH, Canada, DE, DK, EG, ES, Egypt, FI, FR, France, GB, GH, Germany, HK, ID, IE, IN, IT, India, Indonesia, Italy, JP, KE, KR, LK, MX, MY, NG, NL, NO, NZ, Netherlands, Nigeria, PH, PK, PL, PT, Pakistan, Philippines, RO, RU, SE, SG, South Africa, Spain, Sri Lanka, TH, TR, Türkiye, UA, US, United Arab Emirates, United Kingdom, United States, VN, ZA

### instagram-categories (instagram-categories) — 250 values
Accessories, Accountant, Actor, Advertising agency, Advertising/marketing, Agriculture, Alternative & holistic health service, Animals & pets, Antique store, Apartment & condo building, App page, Architectural designer, Art, Art director, Art gallery, Artist, Arts & crafts store, Arts & entertainment, Astrologist & psychic, Athlete, Author, Automotive repair shop, Automotive restoration service, Automotive service, Baby & children's clothing store, Baby goods/kids goods, Bakery, Bar, Barber shop, Beauty salon, Beauty, cosmetic & personal care, Blogger, Book, Bookstore, Boutique, Brand, Building materials, Business center, Business consultant, Business service, Cafe, Camera Operator, Camera/photo, Car dealership, Car sales & service, Car wash, Carpenter, Cars, Cars, planes & boats, Caterer, Charity organization, Chef, Chiropractor, Clothing, Clothing (Brand), Clothing store, Coffee shop, College & university, Comedian, Community, Community organization, Computer company, Construction company, Consultant, Consulting agency, Contractor, Cosmetic dentist, Crafts, DJ, Dancer, Dentist & dental office, Design & fashion, Designer, Dessert shop, Digital creator, Doctor, Dry cleaner, E-commerce website, Editor, Education, Education website, Educational consultant, Electrician, Engineering service, Entertainment service, Entertainment website, Entrepreneur, Event, Event planner, Fan page, Farm, Fashion accessories, Fashion designer, Film director, Finance, Financial consultant, Financial planner, Financial service, Fitness model, Fitness trainer, Florist, Food & beverage, Food truck, Furniture, Furniture store, Gamer, Gaming video creator, General dentist, Gift shop, Government organization, Graphic designer, Grocery store, Gym/Physical fitness center, Hair extensions service, Hair salon, Hair stylist, Health & wellness website, Health/beauty, Heating, ventilating & air conditioning service, Home decor, Home improvement, Hospital/clinic, Hotel, Hotel & lodging, Illustrator, Industrial company, Information technology company, Instructor, Insurance agent, Insurance broker, Insurance company, Interior design studio, Internet marketing service, Internet service provider, Investing service, Investment management company, Jewelry & watches store, Jewelry wholesaler, Jewelry/watches, Journalist, Just for fun, Kitchen/cooking, Landscape company, Lawyer & law firm, Legal, Loan service, Local business, Local service, Magazine, Makeup artist, Marketing agency, Martial arts school, Massage service, Massage therapist, Media, Media agency, Media/news company, Medical & health, Medical spa, Model, Modeling agency, Mortgage brokers, Motivational speaker, Movie character, Music producer, Musician, Musician/band, Nail salon, Nail technician, News & media website, Non-governmental organization (NGO), Nonprofit organization, Nutritionist, Orthodontist, Other, Painting service, People, Performance & event venue, Personal blog, Personal trainer, Pet groomer, Pet service, Pet supplies, Pharmacy, Photographer, Photography & videography, Physical therapist, Pilates studio, Pizza place, Plastic surgeon, Plumbing service, Podcast, Politician, Printing service, Producer, Product/service, Property management company, Psychologist, Psychotherapist, Public figure, Publisher, Real estate, Real estate agency, Real estate agent, Real estate developer, Real estate investment firm, Recording studio, Recruiter, Reels creator, Religious organization, Restaurant, Retail, Retreat Center, Roofing service, School, Science, technology & engineering, Scientist, Shopping & retail, Skin care service, Social media agency, Software, Software company, Solar energy company, Spiritual health center, Sports, Sports & fitness instruction, Sports & recreation, Sports club, Sports team, Tattoo & piercing shop, Therapist, Transportation service, Travel & tourism website, Travel & transportation, Travel agency, Travel company, Tutor/teacher, Vacation home rental, Veterinarian, Video creator, Visual arts, Vitamins/supplements, Web designer, Website, Wedding planning service, Wholesale store, Wine/spirits, Women's clothing store, Writer, Yoga studio

### instagram-account-types (instagram-account-types) — 4 values
business, personal, public, private

### instagram-countries (instagram-countries) — 0 values


### instagram-email-statuses (instagram-email-statuses) — 4 values
bad, catch_all, good, risky