{"openapi":"3.1.0","info":{"title":"MillionPhones API","version":"1.0.0","description":"REST API for looking up verified mobile phone numbers by social profile. API keys are created at https://millionphones.com/api-keys (free account, no card needed)."},"servers":[{"url":"https://millionphones.com/v1","description":""}],"security":[{"apiKey":[]},{"oauth2":["api"]}],"tags":[{"name":"Enrich","description":"Unlock or verify phone numbers for a social profile. Phone lookup costs 10 credits per new unlock; phone verification costs 1 credit per verified/invalid result. Re-calls on the same input are free."},{"name":"Account","description":"Caller identity, credit balance, plan tier. Read-only and credit-free."},{"name":"Search","description":"Discover people by industry, seniority, department, country, and company size. Read-only and credit-free."},{"name":"Tables","description":"Collect profiles into a table, then bulk-enrich it. Create / list / read rows are free; enrichment costs 10 credits per unlocked phone."}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key passed via `x-api-key` header. Format: `mp_live_…`. Right path for server-to-server scripts."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 + PKCE. Use `Authorization: Bearer mp_oat_…`. Right path for delegated/interactive use (MCP, partner apps, \"Connect with MillionPhones\"). See `/.well-known/oauth-authorization-server` for metadata.","flows":{"authorizationCode":{"authorizationUrl":"https://millionphones.com/oauth/authorize","tokenUrl":"https://millionphones.com/oauth/token","refreshUrl":"https://millionphones.com/oauth/token","scopes":{"api":"Full API access (phone lookups, credits, account info)"},"x-usePkce":"SHA-256","x-default-scopes":["api"]}}}},"schemas":{},"parameters":{}},"paths":{"/phone":{"get":{"operationId":"lookupPhone","summary":"Phone Lookup","description":"Look up mobile phone numbers for a social profile. Costs 10 credits per new lookup; re-looking up the same profile is free. By default returns both verified and community-tier phones; pass `verifiedOnly=true` for verified only. Already hold a number you suspect is wrong? Pass it as `existing_phone`. The lookup then does not settle for agreement: it keeps searching past every answer that merely repeats your number until a different one turns up or the search is exhausted, and counts how many times your number was confirmed along the way (`confirmations`). `existing_phone_status` is `alternative` when a different number was found (charged as a normal lookup), `confirmed` when your number held up and nothing different appeared (free), `not_found` when nothing turned up either way (free). `phone_numbers` never repeats the number you supplied.","tags":["Enrich"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"type":"string","description":"Social profile URL or slug (e.g. \"williamhgates\"). Sales Navigator lead URLs and profile-ID URLs are accepted too, exactly as copied — they are case-sensitive.","example":"williamhgates"},"required":true,"description":"Social profile URL or slug (e.g. \"williamhgates\"). Sales Navigator lead URLs and profile-ID URLs are accepted too, exactly as copied — they are case-sensitive.","name":"social_url","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"If \"true\", only return first-party verified phones. If omitted or \"false\" (default), includes community-tier data.","example":"false"},"required":false,"description":"If \"true\", only return first-party verified phones. If omitted or \"false\" (default), includes community-tier data.","name":"verifiedOnly","in":"query"},{"schema":{"type":"string","description":"A phone number you already hold for this profile and want to improve on. Compared digit-for-digit, any formatting; at least 7 digits. The lookup keeps searching past answers that only repeat this number, adds `existing_phone_status` and `confirmations` to the response, and excludes this number from `phone_numbers`. Free unless a different number is returned.","example":"+14255551234"},"required":false,"description":"A phone number you already hold for this profile and want to improve on. Compared digit-for-digit, any formatting; at least 7 digits. The lookup keeps searching past answers that only repeat this number, adds `existing_phone_status` and `confirmations` to the response, and excludes this number from `phone_numbers`. Free unless a different number is returned.","name":"existing_phone","in":"query"}],"responses":{"200":{"description":"Phone numbers found (or empty array if no match)","content":{"application/json":{"schema":{"type":"object","properties":{"phone_numbers":{"type":"array","items":{"type":"string"},"description":"Array of mobile phone numbers in E.164 format","example":["+14255551234"]},"tier":{"type":"string","enum":["verified","community"],"description":"Data tier that served this result. Only present when phone_numbers is non-empty. \"verified\" = first-party verified data. \"community\" = community-tier (not independently verified).","example":"verified"},"existing_phone_status":{"type":"string","enum":["confirmed","alternative","not_found"],"description":"Only when `existing_phone` was supplied. \"alternative\" = a different number was found, returned in `phone_numbers` (charged as a normal lookup). \"confirmed\" = the number you supplied held up and nothing different appeared (no charge, `phone_numbers` empty). \"not_found\" = nothing was found either way (no charge).","example":"confirmed"},"confirmations":{"type":"integer","minimum":0,"description":"Only when `existing_phone` was supplied: how many times the number you supplied was confirmed during this lookup; 0 = never seen. Read it with `existing_phone_status`: \"confirmed\" with a high count is strong evidence your number is right; \"alternative\" after several confirmations disagrees with a well-supported number, so weigh it accordingly.","example":2}},"required":["phone_numbers"]}}}},"400":{"description":"Missing required parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Insufficient credits — buy credits or upgrade the subscription at billing_url","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"billing_url":{"type":"string","description":"Where to buy credits or upgrade the subscription."}},"required":["error","billing_url"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Lookup temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/verifyPhone":{"get":{"operationId":"verifyPhone","summary":"Phone Verification","description":"Verify a phone number against a social profile. Compares the provided phone number with our verified records. Returns verified if the phone matches, invalid if it does not match, or unknown if we have no data. Costs 1 credit per verified/invalid result. Re-checking the same profile is free.","tags":["Enrich"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"type":"string","description":"Social profile URL or slug (e.g. \"williamhgates\"). Sales Navigator lead URLs and profile-ID URLs are accepted too, exactly as copied — they are case-sensitive.","example":"williamhgates"},"required":true,"description":"Social profile URL or slug (e.g. \"williamhgates\"). Sales Navigator lead URLs and profile-ID URLs are accepted too, exactly as copied — they are case-sensitive.","name":"social_url","in":"query"},{"schema":{"type":"string","description":"Phone number to verify (e.g. \"+1-555-123-4567\")","example":"+15551234567"},"required":true,"description":"Phone number to verify (e.g. \"+1-555-123-4567\")","name":"phone_number","in":"query"}],"responses":{"200":{"description":"Verification status returned","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["verified","invalid","unknown"],"description":"verified = valid phone data exists, invalid = phone data known to be incorrect, unknown = no data available"},"person":{"type":"object","nullable":true,"properties":{"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"linkedin_slug":{"type":"string"}},"required":["first_name","last_name","company_name","title","linkedin_slug"],"description":"Basic person info. Null when status is unknown."}},"required":["status","person"]}}}},"400":{"description":"Missing required parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Insufficient credits — buy credits or upgrade the subscription at billing_url","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"billing_url":{"type":"string","description":"Where to buy credits or upgrade the subscription."}},"required":["error","billing_url"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Verification temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/email":{"get":{"operationId":"findEmail","summary":"Find Email","description":"Find a work email address for a person by their social profile URL. Costs 1 credit per returned email — free when your account has already unlocked the same person's phone number, and re-requesting the same person is always free. Requests that return no email cost nothing.","tags":["Enrich"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"type":"string","description":"Social profile URL or slug (e.g. \"williamhgates\"). Sales Navigator lead URLs and profile-ID URLs are accepted too, exactly as copied — they are case-sensitive.","example":"williamhgates"},"required":true,"description":"Social profile URL or slug (e.g. \"williamhgates\"). Sales Navigator lead URLs and profile-ID URLs are accepted too, exactly as copied — they are case-sensitive.","name":"social_url","in":"query"}],"responses":{"200":{"description":"Find result returned","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean","description":"Whether an email was found for this person."},"email":{"type":"string","description":"The email address, when found."},"status":{"type":"string","enum":["verified","risky","none"],"description":"Deliverability: verified = mailbox confirmed, will not bounce; risky = could not be confirmed (may bounce — send with care); none = no viable email"},"match_confidence":{"type":"number","description":"Probability (0–1) that this is the requested person’s address — independent of status, which speaks only to deliverability."},"reason":{"type":"string","enum":["invalid_url","person_not_found","no_company_domain"],"description":"Why the find was not attempted (found=false without a status)."}},"required":["found"]}}}},"400":{"description":"Missing required parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Insufficient credits — buy credits or upgrade the subscription at billing_url","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"billing_url":{"type":"string","description":"Where to buy credits or upgrade the subscription."}},"required":["error","billing_url"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Email finder temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/verifyEmail":{"get":{"operationId":"verifyEmail","summary":"Email Verification","description":"Verify the deliverability of an email address. Returns valid if the mailbox exists, invalid if the mailbox or its domain does not accept mail, catch_all if the domain accepts every address (so mailbox-level verification is impossible), or unknown if no determination could be made. Costs 0.1 credits per decisive result (valid / invalid / catch_all), billed as 1 credit per 10 verifications; unknown results are free. Re-checking the same address is free.","tags":["Enrich"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"type":"string","description":"Email address to verify","example":"jane.doe@acme.com"},"required":true,"description":"Email address to verify","name":"email","in":"query"}],"responses":{"200":{"description":"Verification result returned","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The address that was verified (normalized to lowercase)."},"result":{"type":"string","enum":["valid","invalid","catch_all","unknown"],"description":"valid = mailbox exists, invalid = mailbox or domain rejects mail, catch_all = domain accepts everything, unknown = could not determine"},"credits_charged":{"type":"number","description":"Credits debited by this call: 1 when it opens a new block of 10 verifications, otherwise 0 (within an open block, for unknown results, and for re-checks)."}},"required":["email","result","credits_charged"]}}}},"400":{"description":"Missing or malformed email parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Insufficient credits — buy credits or upgrade the subscription at billing_url","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"billing_url":{"type":"string","description":"Where to buy credits or upgrade the subscription."}},"required":["error","billing_url"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Verification temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/credits":{"get":{"operationId":"getCredits","summary":"Credit Balance","description":"Returns the caller's current credit balance, lifetime usage, and plan. Read-only — never charges credits.","tags":["Account"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"responses":{"200":{"description":"Current credit balance and plan","content":{"application/json":{"schema":{"type":"object","properties":{"remaining":{"type":"number","description":"Credits available to spend right now (granted − used).","example":487},"used":{"type":"number","description":"Lifetime credits spent on this account.","example":13},"plan":{"type":"string","enum":["free","pro"],"description":"Current plan tier. Determines per-minute rate limit (100/min free, 300/min pro).","example":"free"}},"required":["remaining","used","plan"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/search/count":{"get":{"operationId":"searchCount","summary":"Search Count","description":"Count the matching profiles (position rows) for the given filters. Never returns the underlying rows, so the result is always free. Use `/v1/search/filters` to discover the valid filter values.","tags":["Search"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Industry name. Repeat the param for multiple (OR), e.g. `?industry=Fintech&industry=SaaS`. Partial/fuzzy names resolve when unambiguous. Valid values from `/v1/search/filters`.","example":"Fintech"},"required":false,"description":"Industry name. Repeat the param for multiple (OR), e.g. `?industry=Fintech&industry=SaaS`. Partial/fuzzy names resolve when unambiguous. Valid values from `/v1/search/filters`.","name":"industry","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Seniority level name, e.g. `C-Level`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","example":"C-Level"},"required":false,"description":"Seniority level name, e.g. `C-Level`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","name":"seniority","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Department name, e.g. `Engineering`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","example":"Engineering"},"required":false,"description":"Department name, e.g. `Engineering`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","name":"department","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Country name or ISO-3166 alpha-2 code, e.g. `United States` or `US`. Repeat the param for multiple (OR).","example":"United States"},"required":false,"description":"Country name or ISO-3166 alpha-2 code, e.g. `United States` or `US`. Repeat the param for multiple (OR).","name":"country","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Company size bucket label, e.g. `11-50`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","example":"11-50"},"required":false,"description":"Company size bucket label, e.g. `11-50`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","name":"size","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Company website domains to restrict to, e.g. `acme.com`. Repeat the param or comma-separate, up to 100. URLs are accepted (`https://www.acme.com/about` → `acme.com`). A company matches by its website or its email domain. A domain that matches no company is retried one level up and then at its main domain (`eu.careers.acme.com` → `careers.acme.com` → `acme.com`); such matches are listed in `domain_fallbacks`, and domains that match nothing in `unmatched_domains`. When no domain matches, the result is empty (and free).","example":"acme.com"},"required":false,"description":"Company website domains to restrict to, e.g. `acme.com`. Repeat the param or comma-separate, up to 100. URLs are accepted (`https://www.acme.com/about` → `acme.com`). A company matches by its website or its email domain. A domain that matches no company is retried one level up and then at its main domain (`eu.careers.acme.com` → `careers.acme.com` → `acme.com`); such matches are listed in `domain_fallbacks`, and domains that match nothing in `unmatched_domains`. When no domain matches, the result is empty (and free).","name":"company_domains","in":"query"}],"responses":{"200":{"description":"Match count for the filter combination","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","description":"Number of matching profiles (position rows). A person with multiple current roles is counted once per role — dedupe by person_id from /search/people for distinct people.","example":1284},"unmatched_domains":{"type":"array","items":{"type":"string"},"description":"Present when `company_domains` was sent: domains that did not match a known company.","example":["notacompany.io"]},"domain_fallbacks":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","description":"The domain as sent (normalised).","example":"careers.acme.com"},"matched":{"type":"string","description":"The parent domain that matched.","example":"acme.com"}},"required":["domain","matched"]},"description":"Present when `company_domains` was sent: domains that matched only through a parent domain, and the parent that matched."}},"required":["count"]}}}},"400":{"description":"Unrecognized filter value, or more than the allowed number of company_domains","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"unresolved":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"value":{"type":"string"},"reason":{"type":"string","enum":["unknown","ambiguous"]},"suggestions":{"type":"array","items":{"type":"string"}}},"required":["dimension","value","reason","suggestions"]}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Company matching temporarily unavailable (only when `company_domains` is sent)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"unresolved":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"value":{"type":"string"},"reason":{"type":"string","enum":["unknown","ambiguous"]},"suggestions":{"type":"array","items":{"type":"string"}}},"required":["dimension","value","reason","suggestions"]}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/search/filters":{"get":{"operationId":"searchFilters","summary":"Search Filter Values","description":"Returns the valid values for every search filter dimension — pass these directly to `/v1/search/count` and `/v1/search/people`. Industry / seniority / department are plain strings; size uses the `label`; country accepts either the `name` or the `iso2` code. Free, idempotent — cache client-side. (The internal numeric IDs are no longer exposed; filter by these values.)","tags":["Search"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"responses":{"200":{"description":"Valid filter values per dimension","content":{"application/json":{"schema":{"type":"object","properties":{"industries":{"type":"array","items":{"type":"string"},"example":["Software","Fintech"]},"seniorities":{"type":"array","items":{"type":"string"},"example":["IC","Manager","C-Level"]},"departments":{"type":"array","items":{"type":"string"},"example":["Engineering","Sales"]},"countries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"iso2":{"type":"string"}},"required":["name","iso2"]},"example":[{"name":"United States","iso2":"US"}]},"size_buckets":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"min_employees":{"type":"number","nullable":true},"max_employees":{"type":"number","nullable":true}},"required":["label","min_employees","max_employees"]},"example":[{"label":"11-50","min_employees":11,"max_employees":50}]}},"required":["industries","seniorities","departments","countries","size_buckets"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/person":{"get":{"operationId":"enrichPerson","summary":"Person Enrichment","description":"Identify a person and get their mobile phone and work email in one call. Identify them by `person_id` (from an earlier result here or from /v1/search/people), by `linkedin_url`, or by `first_name` + `last_name` + a company (`company_domain` or `company` name).\n\n**One match:** returns the person, their phone numbers and their work email.\n\n**Several people match** (common names at a large company) — **free**: returns up to 5 `candidates` (no phone or email) and `total_matches`, how many matched in all. Call again with the chosen candidate's `person_id`; if more than 5 matched, narrow the query, e.g. with `company_domain`. A last name given as an initial (`S.` or `S`) always returns candidates — every surname starting with it, abbreviated ones first — even when only one person fits, because an initial alone cannot confirm who the person is. Likewise a first name nobody at the company has exactly is retried as its common nickname or formal form (Matt ↔ Matthew, Jim ↔ James); those finds are returned as candidates too.\n\n**No match** — **free**.\n\n**Cost of a single match:** the phone is 10 credits per new unlock (re-requests free); the email is **free** when the phone was found, otherwise 1 credit. A matched person with neither phone nor email found costs 0.1 credits (repeats free). Set `phone=false` or `email=false` to skip either. Candidates and no-match answers are always free.","tags":["Enrich"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"type":"string","description":"The `person_id` from an earlier /v1/person or /v1/search/people result. Use it alone.","example":"1611494989785140680"},"required":false,"description":"The `person_id` from an earlier /v1/person or /v1/search/people result. Use it alone.","name":"person_id","in":"query"},{"schema":{"type":"string","description":"LinkedIn profile URL or slug. Sales Navigator lead URLs and profile-ID URLs are accepted too, exactly as copied — they are case-sensitive.","example":"https://www.linkedin.com/in/williamhgates"},"required":false,"description":"LinkedIn profile URL or slug. Sales Navigator lead URLs and profile-ID URLs are accepted too, exactly as copied — they are case-sensitive.","name":"linkedin_url","in":"query"},{"schema":{"type":"string","description":"First name (with last_name and a company).","example":"Bill"},"required":false,"description":"First name (with last_name and a company).","name":"first_name","in":"query"},{"schema":{"type":"string","description":"Last name (with first_name and a company).","example":"Gates"},"required":false,"description":"Last name (with first_name and a company).","name":"last_name","in":"query"},{"schema":{"type":"string","description":"Company website domain, e.g. `gatesfoundation.org`. Matches by website or email domain.","example":"gatesfoundation.org"},"required":false,"description":"Company website domain, e.g. `gatesfoundation.org`. Matches by website or email domain.","name":"company_domain","in":"query"},{"schema":{"type":"string","description":"Company name, when you have no domain. Every company with that name is searched.","example":"Gates Foundation"},"required":false,"description":"Company name, when you have no domain. Every company with that name is searched.","name":"company","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Return the mobile phone. Default true.","example":"true"},"required":false,"description":"Return the mobile phone. Default true.","name":"phone","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Return the work email (free when the phone is found). Default true.","example":"true"},"required":false,"description":"Return the work email (free when the phone is found). Default true.","name":"email","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Phone from verified data only: lower coverage. Default false.","example":"false"},"required":false,"description":"Phone from verified data only: lower coverage. Default false.","name":"verified_only","in":"query"}],"responses":{"200":{"description":"The matched person with phone and email, or candidates when several people match","content":{"application/json":{"schema":{"type":"object","properties":{"person":{"type":"object","nullable":true,"properties":{"person_id":{"type":"string","nullable":true,"description":"Opaque stable person identifier (int64 as string) — the same `person_id` /v1/search/people returns. Null only for a person found without a stored profile.","example":"1611494989785140680"},"linkedin_url":{"type":"string","nullable":true,"example":"https://www.linkedin.com/in/williamhgates"},"first_name":{"type":"string","nullable":true,"example":"Bill"},"last_name":{"type":"string","nullable":true,"example":"Gates"},"title":{"type":"string","nullable":true,"example":"Co-chair"},"company_name":{"type":"string","nullable":true,"example":"Gates Foundation"},"company_domain":{"type":"string","nullable":true,"example":"gatesfoundation.org"}},"required":["person_id","linkedin_url","first_name","last_name","title","company_name","company_domain"],"description":"The matched person. Null when nobody (or several people) matched."},"phone_numbers":{"type":"array","items":{"type":"string"},"description":"Present when `phone` was requested for a single match."},"tier":{"type":"string","enum":["verified","community"]},"email":{"type":"string","nullable":true,"description":"Present when `email` was requested for a single match. Null when none was found."},"email_status":{"type":"string","enum":["verified","risky","none","insufficient_credits","unavailable"]},"candidates":{"type":"array","items":{"type":"object","properties":{"person_id":{"type":"string","nullable":true,"description":"Opaque stable person identifier (int64 as string) — the same `person_id` /v1/search/people returns. Null only for a person found without a stored profile.","example":"1611494989785140680"},"linkedin_url":{"type":"string","nullable":true,"example":"https://www.linkedin.com/in/williamhgates"},"first_name":{"type":"string","nullable":true,"example":"Bill"},"last_name":{"type":"string","nullable":true,"example":"Gates"},"title":{"type":"string","nullable":true,"example":"Co-chair"},"company_name":{"type":"string","nullable":true,"example":"Gates Foundation"},"company_domain":{"type":"string","nullable":true,"example":"gatesfoundation.org"}},"required":["person_id","linkedin_url","first_name","last_name","title","company_name","company_domain"]},"description":"When several people match, or the last name was an initial: up to 5, no phone or email — free (`credits_charged` 0). Call again with the chosen person_id."},"total_matches":{"type":"number","description":"With `candidates`: how many people matched in all. More than listed → narrow the query.","example":12},"reason":{"type":"string","enum":["company_not_found","person_not_found"],"description":"Why nobody matched."},"credits_charged":{"type":"number","example":10}},"required":["person","credits_charged"]}}}},"400":{"description":"Missing or conflicting identifiers, or an unsupported profile URL","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Insufficient credits — buy credits or upgrade the subscription at billing_url","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"billing_url":{"type":"string","description":"Where to buy credits or upgrade the subscription."}},"required":["error","billing_url"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Lookup temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/company":{"get":{"operationId":"lookupCompany","summary":"Company Lookup","description":"Look up companies by name and/or website domain. Each name or domain returns its matching companies (up to 10, largest first) rather than a guess — pick the right one by domain, size, industry or location, then pass its `domain` to `company_domains` on `/v1/search/people`.\n\n**By name:** matches the full company name, ignoring case, punctuation and legal suffixes; partial names are not matched. A name often belongs to several companies.\n\n**By domain:** matches a company by its website or its email domain, the same way `company_domains` does on people search. A domain that matches nothing is retried one level up and then at its main domain; such matches carry `matched_via`. Several company pages can share one domain.\n\n**Cost:** 0.1 credits per company returned, billed as 1 credit per 10 new companies. A company you have already received is free every time after. Anything with no match is free.\n\n**Limits:** up to 25 names and 100 domains per call — repeat the `name` / `domain` params.","tags":["Enrich"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Company name. Repeat for several (up to 25).","example":"Ava Labs"},"required":false,"description":"Company name. Repeat for several (up to 25).","name":"name","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Company website domain; URLs are fine. Repeat or comma-separate for several (up to 100).","example":"avalabs.org"},"required":false,"description":"Company website domain; URLs are fine. Repeat or comma-separate for several (up to 100).","name":"domain","in":"query"}],"responses":{"200":{"description":"Matching companies per name and per domain, in the order they were sent","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The name as sent."},"total_matches":{"type":"number","description":"How many companies carry this name; `candidates` shows up to 10."},"candidates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Ava Labs"},"domain":{"type":"string","nullable":true,"description":"Company website domain — pass it to `company_domains` on `/v1/search/people`. Null when no domain is known.","example":"avalabs.org"},"linkedin_url":{"type":"string","nullable":true,"example":"https://www.linkedin.com/company/avalabsofficial"},"industry":{"type":"string","nullable":true,"example":"Software Development"},"employee_count":{"type":"number","nullable":true,"example":498},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}},"required":["name","domain","linkedin_url","industry","employee_count","city","country"]}}},"required":["name","total_matches","candidates"]},"description":"One entry per name sent."},"domain_results":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","description":"The domain as sent (normalised)."},"matched_via":{"type":"string","nullable":true,"description":"The parent domain that matched, when the domain itself did not."},"total_matches":{"type":"number","description":"How many companies match this domain; `candidates` shows up to 10."},"candidates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Ava Labs"},"domain":{"type":"string","nullable":true,"description":"Company website domain — pass it to `company_domains` on `/v1/search/people`. Null when no domain is known.","example":"avalabs.org"},"linkedin_url":{"type":"string","nullable":true,"example":"https://www.linkedin.com/company/avalabsofficial"},"industry":{"type":"string","nullable":true,"example":"Software Development"},"employee_count":{"type":"number","nullable":true,"example":498},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}},"required":["name","domain","linkedin_url","industry","employee_count","city","country"]}}},"required":["domain","matched_via","total_matches","candidates"]},"description":"Present when `domain` was sent: one entry per domain that matched."},"unmatched_domains":{"type":"array","items":{"type":"string"},"description":"Present when `domain` was sent: domains that did not match a known company."},"credits_charged":{"type":"number","description":"Credits debited for this call.","example":1}},"required":["results","credits_charged"]}}}},"400":{"description":"No name or domain, or too many","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"unresolved":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"value":{"type":"string"},"reason":{"type":"string","enum":["unknown","ambiguous"]},"suggestions":{"type":"array","items":{"type":"string"}}},"required":["dimension","value","reason","suggestions"]}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Insufficient credits — buy credits or upgrade the subscription at billing_url","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"billing_url":{"type":"string","description":"Where to buy credits or upgrade the subscription."}},"required":["error","billing_url"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Company search temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"unresolved":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"value":{"type":"string"},"reason":{"type":"string","enum":["unknown","ambiguous"]},"suggestions":{"type":"array","items":{"type":"string"}}},"required":["dimension","value","reason","suggestions"]}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/search/people":{"get":{"operationId":"searchPeople","summary":"Search People","description":"Paginated profile search. Returns identity, employer, and category metadata for people matching the given filters — but never phone numbers. Use the returned `linkedin_slug` with `/v1/phone` to unlock individual phones.\n\n**Cost:** 0.1 credits per person your account has not received before, billed as 1 credit per 10 new people. A person already returned to your account — by this endpoint, by saving a search, or by person enrichment — is free, so paging back over the same results costs nothing. An empty result is free.\n\n**Limits:** 50 results per page by default (1..100). Hard cap of 10000 total results across all pages — once reached, `next_cursor` is null.\n\n**Pagination is cursor-based (sequential).** Omit `cursor` for the first page; pass the previous response's `next_cursor` to fetch the next page. `next_cursor` is null when there are no more results. A cursor is only valid for the filter set it was issued under.\n\n**Result rows are per (person, current_position).** A person with multiple resolved current employers appears once per role; deduplicate client-side by `person_id` if you only want distinct people.","tags":["Search"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Industry name. Repeat the param for multiple (OR), e.g. `?industry=Fintech&industry=SaaS`. Partial/fuzzy names resolve when unambiguous. Valid values from `/v1/search/filters`.","example":"Fintech"},"required":false,"description":"Industry name. Repeat the param for multiple (OR), e.g. `?industry=Fintech&industry=SaaS`. Partial/fuzzy names resolve when unambiguous. Valid values from `/v1/search/filters`.","name":"industry","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Seniority level name, e.g. `C-Level`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","example":"C-Level"},"required":false,"description":"Seniority level name, e.g. `C-Level`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","name":"seniority","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Department name, e.g. `Engineering`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","example":"Engineering"},"required":false,"description":"Department name, e.g. `Engineering`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","name":"department","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Country name or ISO-3166 alpha-2 code, e.g. `United States` or `US`. Repeat the param for multiple (OR).","example":"United States"},"required":false,"description":"Country name or ISO-3166 alpha-2 code, e.g. `United States` or `US`. Repeat the param for multiple (OR).","name":"country","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Company size bucket label, e.g. `11-50`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","example":"11-50"},"required":false,"description":"Company size bucket label, e.g. `11-50`. Repeat the param for multiple (OR). Valid values from `/v1/search/filters`.","name":"size","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Company website domains to restrict to, e.g. `acme.com`. Repeat the param or comma-separate, up to 100. URLs are accepted (`https://www.acme.com/about` → `acme.com`). A company matches by its website or its email domain. A domain that matches no company is retried one level up and then at its main domain (`eu.careers.acme.com` → `careers.acme.com` → `acme.com`); such matches are listed in `domain_fallbacks`, and domains that match nothing in `unmatched_domains`. When no domain matches, the result is empty (and free).","example":"acme.com"},"required":false,"description":"Company website domains to restrict to, e.g. `acme.com`. Repeat the param or comma-separate, up to 100. URLs are accepted (`https://www.acme.com/about` → `acme.com`). A company matches by its website or its email domain. A domain that matches no company is retried one level up and then at its main domain (`eu.careers.acme.com` → `careers.acme.com` → `acme.com`); such matches are listed in `domain_fallbacks`, and domains that match nothing in `unmatched_domains`. When no domain matches, the result is empty (and free).","name":"company_domains","in":"query"},{"schema":{"type":"string","description":"Opaque pagination cursor from a prior response's `next_cursor`. Omit for the first page.","example":"eyJrIjpbIjEiLG51bGxdfQ"},"required":false,"description":"Opaque pagination cursor from a prior response's `next_cursor`. Omit for the first page.","name":"cursor","in":"query"},{"schema":{"type":"string","description":"Results per page (1..100). Default 50.","example":"50"},"required":false,"description":"Results per page (1..100). Default 50.","name":"page_size","in":"query"},{"schema":{"type":"string","description":"Result order. Supported: `seniority` (Founder, Owner, C-Level, VP, Head, Director, Manager, … with `direction=desc`). Omit for the default order. Use with `company_domains` to get the most senior people at each account first.","example":"seniority"},"required":false,"description":"Result order. Supported: `seniority` (Founder, Owner, C-Level, VP, Head, Director, Manager, … with `direction=desc`). Omit for the default order. Use with `company_domains` to get the most senior people at each account first.","name":"sort","in":"query"},{"schema":{"type":"string","description":"`desc` (default, most senior first) or `asc`. Only with `sort`.","example":"desc"},"required":false,"description":"`desc` (default, most senior first) or `asc`. Only with `sort`.","name":"direction","in":"query"}],"responses":{"200":{"description":"Paginated profile results. Charge applied to caller account proportional to returned count.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"person_id":{"type":"string","description":"Opaque stable person identifier (int64 as string).","example":"1611494989785140680"},"linkedin_slug":{"type":"string","description":"LinkedIn URL slug — pass to `/v1/phone` to unlock the phone number.","example":"williamhgates"},"name":{"type":"string","description":"Best display name (first+last; falls back to slug if name fields are empty).","example":"Bill Gates"},"title":{"type":"string","nullable":true,"description":"Current job title from this position row.","example":"Co-chair"},"company_name":{"type":"string","nullable":true,"description":"Employer name for this position. Null when the position does not resolve to a known company.","example":"Bill & Melinda Gates Foundation"},"industry":{"type":"string","nullable":true,"description":"Industry name.","example":"Philanthropy"},"seniority":{"type":"string","nullable":true,"description":"Seniority level parsed from title (IC, Manager, Director, VP, C-Level, …).","example":"C-Level"},"department":{"type":"string","nullable":true,"description":"Functional department parsed from title (Engineering, Sales, Finance, …).","example":"Executive"},"country":{"type":"string","nullable":true,"description":"Country name.","example":"United States"},"country_iso2":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code.","example":"US"},"size":{"type":"string","nullable":true,"description":"Company size bucket label.","example":"10,001+"}},"required":["person_id","linkedin_slug","name","title","company_name","industry","seniority","department","country","country_iso2","size"]}},"page":{"type":"number","example":1},"page_size":{"type":"number","example":50},"total_results":{"type":"number","description":"Total matching results (may exceed the hard cap; pagination stops at the cap).","example":1284},"total_pages":{"type":"number","description":"Number of pages reachable given the page_size and hard cap.","example":26},"next_cursor":{"type":"string","nullable":true,"description":"Pass as `cursor` to fetch the next page. Null when the result set is exhausted or the hard cap is reached.","example":"eyJrIjpbIjEiLG51bGxdfQ"},"credits_charged":{"type":"number","description":"Credits debited from the caller account for this response.","example":5},"unmatched_domains":{"type":"array","items":{"type":"string"},"description":"Present when `company_domains` was sent: domains that did not match a known company.","example":["notacompany.io"]},"domain_fallbacks":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","description":"The domain as sent (normalised).","example":"careers.acme.com"},"matched":{"type":"string","description":"The parent domain that matched.","example":"acme.com"}},"required":["domain","matched"]},"description":"Present when `company_domains` was sent: domains that matched only through a parent domain, and the parent that matched."}},"required":["results","page","page_size","total_results","total_pages","next_cursor","credits_charged"]}}}},"400":{"description":"Unrecognized filter value, too many company_domains, unsupported sort, or invalid cursor / page_size","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"unresolved":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"value":{"type":"string"},"reason":{"type":"string","enum":["unknown","ambiguous"]},"suggestions":{"type":"array","items":{"type":"string"}}},"required":["dimension","value","reason","suggestions"]}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Insufficient credits — buy credits or upgrade the subscription at billing_url","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"billing_url":{"type":"string","description":"Where to buy credits or upgrade the subscription."}},"required":["error","billing_url"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Company matching temporarily unavailable (only when `company_domains` is sent)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"unresolved":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"value":{"type":"string"},"reason":{"type":"string","enum":["unknown","ambiguous"]},"suggestions":{"type":"array","items":{"type":"string"}}},"required":["dimension","value","reason","suggestions"]}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/tables":{"post":{"operationId":"createTable","summary":"Create Table","description":"Create an empty table to collect and enrich profiles. Free.","tags":["Tables"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Q3 fintech VPs"}},"required":["name"]}}}},"responses":{"201":{"description":"Table created","content":{"application/json":{"schema":{"type":"object","properties":{"table":{"type":"object","properties":{"id":{"type":"string","example":"a1b2c3d4e5f6"},"name":{"type":"string","example":"Q3 fintech VPs"},"row_count":{"type":"number","description":"Rows currently in the table (max 100000)."},"enriched_count":{"type":"number","description":"Rows that already have a phone number."},"active_job":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string","description":"queued · running · paused · done · failed · cancelled","example":"running"},"total_rows":{"type":"number","description":"Rows the job will attempt (snapshotted at start)."},"processed_rows":{"type":"number"},"unlocked_rows":{"type":"number","description":"Rows for which a phone was found + unlocked."},"not_found_rows":{"type":"number"},"failed_rows":{"type":"number"},"pause_reason":{"type":"string","nullable":true,"description":"Why a paused job stopped, e.g. \"insufficient_credits\". Null unless paused."}},"required":["id","status","total_rows","processed_rows","unlocked_rows","not_found_rows","failed_rows","pause_reason"],"description":"In-flight (or most recent, on `get`) enrichment job, or null."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","row_count","enriched_count","active_job","created_at","updated_at"]}},"required":["table"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"get":{"operationId":"listTables","summary":"List Tables","description":"All of the caller's tables with row counts and any in-flight enrichment job. Free.","tags":["Tables"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"responses":{"200":{"description":"Tables for the caller","content":{"application/json":{"schema":{"type":"object","properties":{"tables":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"a1b2c3d4e5f6"},"name":{"type":"string","example":"Q3 fintech VPs"},"row_count":{"type":"number","description":"Rows currently in the table (max 100000)."},"enriched_count":{"type":"number","description":"Rows that already have a phone number."},"active_job":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string","description":"queued · running · paused · done · failed · cancelled","example":"running"},"total_rows":{"type":"number","description":"Rows the job will attempt (snapshotted at start)."},"processed_rows":{"type":"number"},"unlocked_rows":{"type":"number","description":"Rows for which a phone was found + unlocked."},"not_found_rows":{"type":"number"},"failed_rows":{"type":"number"},"pause_reason":{"type":"string","nullable":true,"description":"Why a paused job stopped, e.g. \"insufficient_credits\". Null unless paused."}},"required":["id","status","total_rows","processed_rows","unlocked_rows","not_found_rows","failed_rows","pause_reason"],"description":"In-flight (or most recent, on `get`) enrichment job, or null."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","row_count","enriched_count","active_job","created_at","updated_at"]}}},"required":["tables"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"delete":{"operationId":"deleteTableByName","summary":"Delete Table by Name","description":"Permanently delete a table by name (and ALL its rows). If more than one table shares the name, this returns 409 and deletes nothing — delete by id instead. Cannot be undone. Free.","tags":["Tables"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Exact table name (must be unique within your account).","example":"Q3 fintech VPs"},"required":true,"description":"Exact table name (must be unique within your account).","name":"name","in":"query"}],"responses":{"200":{"description":"Table deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"table":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"rows_deleted":{"type":"number","description":"Rows removed along with the table."}},"required":["deleted","table","rows_deleted"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"No table with that name","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Multiple tables share the name — delete by id instead","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"matches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"row_count":{"type":"number"}},"required":["id","name","row_count"]},"description":"The tables sharing the name — delete one by id."}},"required":["code","message","matches"]}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/tables/{id}":{"get":{"operationId":"getTable","summary":"Get Table","description":"One table: its row/enriched counts, the most-recent enrichment job (poll this to track `enrich` progress), and a cursor-paginated page of rows with their phone state. Free.","tags":["Tables"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"type":"string","example":"a1b2c3d4e5f6"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Pass the previous response's `next_cursor`. Omit for the first page."},"required":false,"description":"Pass the previous response's `next_cursor`. Omit for the first page.","name":"cursor","in":"query"},{"schema":{"type":"string","description":"Rows per page (1..100). Default 50.","example":"50"},"required":false,"description":"Rows per page (1..100). Default 50.","name":"page_size","in":"query"}],"responses":{"200":{"description":"Table with a page of rows","content":{"application/json":{"schema":{"type":"object","properties":{"table":{"type":"object","properties":{"id":{"type":"string","example":"a1b2c3d4e5f6"},"name":{"type":"string","example":"Q3 fintech VPs"},"row_count":{"type":"number","description":"Rows currently in the table (max 100000)."},"enriched_count":{"type":"number","description":"Rows that already have a phone number."},"active_job":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string","description":"queued · running · paused · done · failed · cancelled","example":"running"},"total_rows":{"type":"number","description":"Rows the job will attempt (snapshotted at start)."},"processed_rows":{"type":"number"},"unlocked_rows":{"type":"number","description":"Rows for which a phone was found + unlocked."},"not_found_rows":{"type":"number"},"failed_rows":{"type":"number"},"pause_reason":{"type":"string","nullable":true,"description":"Why a paused job stopped, e.g. \"insufficient_credits\". Null unless paused."}},"required":["id","status","total_rows","processed_rows","unlocked_rows","not_found_rows","failed_rows","pause_reason"],"description":"In-flight (or most recent, on `get`) enrichment job, or null."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","row_count","enriched_count","active_job","created_at","updated_at"]},"rows":{"type":"array","items":{"type":"object","properties":{"linkedin_slug":{"type":"string","nullable":true,"description":"LinkedIn slug — pass to `/v1/phone` to unlock individually.","example":"williamhgates"},"name":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"phone_numbers":{"type":"array","nullable":true,"items":{"type":"string"},"description":"E.164 numbers once enriched; null until then.","example":["+14255551234"]},"tier":{"type":"string","nullable":true,"enum":["verified","community",null],"description":"Coverage tier of the enriched phone. Null until the row is enriched.","example":"verified"}},"required":["linkedin_slug","name","company_name","phone_numbers","tier"]}},"next_cursor":{"type":"string","nullable":true}},"required":["table","rows","next_cursor"]}}}},"400":{"description":"Invalid page_size","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Table not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"delete":{"operationId":"deleteTable","summary":"Delete Table","description":"Permanently delete a table and ALL its rows (cascades leads + any enrichment job). Cannot be undone. Free.","tags":["Tables"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"type":"string","example":"a1b2c3d4e5f6"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Table deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"table":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"rows_deleted":{"type":"number","description":"Rows removed along with the table."}},"required":["deleted","table","rows_deleted"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Table not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/tables/{id}/rows":{"post":{"operationId":"addTableRows","summary":"Add Rows","description":"Add LinkedIn profiles as rows. Accepts URLs or slugs (normalized server-side). Rows are NOT deduplicated — the same profile may appear more than once. Up to 2500 per call, and never beyond the table's 100000-row cap (overflow is reported as skipped_over_cap). Does not enrich — call enrich for that. Free.","tags":["Tables"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"social_urls":{"type":"array","items":{"type":"string"},"minItems":1,"description":"LinkedIn profile URLs or slugs. Sales Navigator lead URLs and profile-ID URLs are accepted too, exactly as copied — they are case-sensitive.","example":["williamhgates","https://www.linkedin.com/in/satyanadella/"]}},"required":["social_urls"]}}}},"responses":{"200":{"description":"Rows added","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"number","description":"Rows inserted."},"skipped_over_cap":{"type":"number","description":"Slugs dropped because the table hit 100000 rows."},"skipped_unparseable":{"type":"number","description":"Inputs that did not yield a LinkedIn slug."},"row_count":{"type":"number","description":"Total rows after the add."}},"required":["added","skipped_over_cap","skipped_unparseable","row_count"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Table not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/tables/{id}/enrich":{"post":{"operationId":"enrichTable","summary":"Enrich Table","description":"Start a background job that finds + unlocks a phone number for every un-enriched row. Returns immediately with the job; poll `GET /v1/tables/{id}` (the `active_job` field) for progress. Each successful unlock costs 10 credits; rows already enriched and re-runs of found rows are free. If credits run out mid-run the job pauses and resumes automatically on top-up.","tags":["Tables"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"202":{"description":"Enrichment job started","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","description":"queued · running · paused · done · failed · cancelled","example":"running"},"total_rows":{"type":"number","description":"Rows the job will attempt (snapshotted at start)."},"processed_rows":{"type":"number"},"unlocked_rows":{"type":"number","description":"Rows for which a phone was found + unlocked."},"not_found_rows":{"type":"number"},"failed_rows":{"type":"number"},"pause_reason":{"type":"string","nullable":true,"description":"Why a paused job stopped, e.g. \"insufficient_credits\". Null unless paused."}},"required":["id","status","total_rows","processed_rows","unlocked_rows","not_found_rows","failed_rows","pause_reason"]}},"required":["job"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Table not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"A job is already in flight for this table","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Too many concurrent jobs, or rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/search/save":{"post":{"operationId":"searchSave","summary":"Save Search to Table","description":"Resolve a people search and add the matching profiles as rows in a table — the durable sibling of `/v1/search/people`.Pass `table` (a NAME): an existing table of that name is appended to, otherwise one is created. Omit `table` to auto-create an \"MCP_Search_<timestamp>\" table. Charges 0.1 credits per profile saved (the same rate as results) for people your account has not received before — a person already returned by results, an earlier save, or person enrichment is free — and only for profiles that actually fit: a near-full table fills to the 100000-row cap and reports the rest as skipped_over_cap (never overcharging), and a full table is a no-op. No client pagination — the server materializes the matches directly into the list. Use `limit` to bound how many; one call saves up to 10000 profiles. Run `/v1/search/count` first (free) to size it. Filters are natural-language VALUES (industry \"Fintech\", country \"US\"); each dimension is an array (OR within, AND across).","tags":["Tables"],"security":[{"apiKey":[]},{"oauth2":["api"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"table":{"type":"string","description":"Target table NAME. Existing → append; new → created. Omit to auto-create \"MCP_Search_<timestamp>\".","example":"Q3 fintech VPs"},"industry":{"type":"array","items":{"type":"string"}},"seniority":{"type":"array","items":{"type":"string"}},"department":{"type":"array","items":{"type":"string"}},"country":{"type":"array","items":{"type":"string"}},"size":{"type":"array","items":{"type":"string"}},"company_domains":{"type":"array","items":{"type":"string"},"description":"Company website domains to restrict to (up to 100), same rules as `company_domains` on `/v1/search/people`: matches by website or email domain, a miss retries one level up and then the main domain.","example":["acme.com"]},"sort":{"type":"string","description":"Which profiles to save first when there are more matches than `limit`: `seniority` (with `direction`). Omit for the default order.","example":"seniority"},"direction":{"type":"string","description":"`desc` (default, most senior first) or `asc`. Only with `sort`.","example":"desc"},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Max profiles to save this call (clamped to 10000 and to remaining capacity). Omit to save as many as fit."}}}}}},"responses":{"200":{"description":"Search materialized into the table","content":{"application/json":{"schema":{"type":"object","properties":{"table":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created":{"type":"boolean","description":"true if this call created the table, false if it appended to an existing one."}},"required":["id","name","created"],"description":"The resolved (or created) table — pass id to enrich/get it."},"matched_total":{"type":"number","description":"Total profiles matching the filters."},"added":{"type":"number","description":"Rows inserted this call."},"skipped_over_cap":{"type":"number","description":"Matches not added because the table hit 100000 rows."},"credits_charged":{"type":"number","description":"Credits debited for the profiles saved."},"unmatched_domains":{"type":"array","items":{"type":"string"},"description":"Present when `company_domains` was sent: domains that did not match a known company."},"domain_fallbacks":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"matched":{"type":"string"}},"required":["domain","matched"]},"description":"Present when `company_domains` was sent: domains that matched only through a parent domain, and the parent that matched."}},"required":["table","matched_total","added","skipped_over_cap","credits_charged"]}}}},"400":{"description":"Unrecognized filter value, too many company_domains, or unsupported sort","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"unresolved":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"value":{"type":"string"},"reason":{"type":"string","enum":["unknown","ambiguous"]},"suggestions":{"type":"array","items":{"type":"string"}}},"required":["dimension","value","reason","suggestions"]}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Invalid or missing API key / Bearer token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Insufficient credits — buy credits or upgrade the subscription at billing_url","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"billing_url":{"type":"string","description":"Where to buy credits or upgrade the subscription."}},"required":["error","billing_url"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Company matching temporarily unavailable (only when `company_domains` is sent)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"unresolved":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string"},"value":{"type":"string"},"reason":{"type":"string","enum":["unknown","ambiguous"]},"suggestions":{"type":"array","items":{"type":"string"}}},"required":["dimension","value","reason","suggestions"]}}},"required":["code","message"]}},"required":["error"]}}}}}}}}}