{"openapi":"3.1.0","info":{"title":"Coldlytics API","version":"3.0.0","description":"Search companies and decision-makers, reveal verified emails and direct dials, and manage the contacts you own.\n\nAuthenticate with an API key (Integrations → API & MCP in the dashboard) as `Authorization: Bearer cl_live_…` or `X-Api-Key`, or with an OAuth access token from https://app.coldlytics.com/.well-known/oauth-authorization-server.\n\nThe same capabilities are available to AI assistants as an MCP server at https://mcp.coldlytics.com/mcp.\n\nDelivery webhooks (research tasks) are POSTed as JSON with `Coldlytics-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + '.' + body)>`; the secret is on Integrations → API & MCP.\n\nThe pre-2026 v1/v2 endpoints (`/v1/tasks/enrich`, `/v2/tasks/enrich/*`, `/v2/user`, HTTP Basic with the legacy account key) keep working unchanged for existing integrations; they are documented at https://coldlytics.notion.site/Coldlytics-API-v2-7e465c1c43814c768fc38f7067fa3f0a and are not extended.\n\nErrors are RFC 9457 problem+json with a stable `code`: unauthenticated, invalid_key, insufficient_scope, forbidden_seat, validation_error, not_found, rate_limited, monthly_cap_reached, insufficient_credits (402), subscription_required, idempotency_key_reused, search_timeout.","contact":{"name":"Coldlytics support","email":"support@coldlytics.com","url":"https://www.coldlytics.com"}},"servers":[{"url":"https://api.coldlytics.com"}],"security":[{"apiKey":[]},{"bearer":[]}],"tags":[{"name":"Account"},{"name":"Search","description":"Free within the monthly allowance (see GET /v3/account)"},{"name":"Companies"},{"name":"Reveals","description":"Spend credits"},{"name":"Contacts","description":"Contacts this account owns"},{"name":"Reveal runs","description":"Bulk reveals processed in the background"},{"name":"Research","description":"Human research tasks (1–3 business days); books credits"},{"name":"Suppression","description":"The account's global suppression list: emails and domains research tasks and exclude_suppressed searches leave out"}],"paths":{"/v3/account":{"get":{"tags":["Account"],"operationId":"getAccount","summary":"The connected account","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Account"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/search/options":{"get":{"tags":["Search"],"operationId":"getSearchOptions","summary":"Valid filter values (categories, technologies, locations, seniorities, departments)","parameters":[{"name":"kind","in":"query","required":true,"schema":{"type":"string","enum":["seniorities","departments","categories","technologies","locations"]}},{"name":"query","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SearchOptions"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/search/companies":{"post":{"tags":["Search"],"operationId":"searchCompanies","summary":"Search companies","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCompaniesInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"504":{"description":"Search timed out; narrow it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/search/people":{"post":{"tags":["Search"],"operationId":"searchPeople","summary":"Search people (decision-makers) at matching companies","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPeopleInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Person"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/companies/lookup":{"get":{"tags":["Companies"],"operationId":"lookupCompany","summary":"Company profile, branches and revealable people by domain","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"example":"acme.com"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LookupCompanyResult"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/reveals":{"post":{"tags":["Reveals"],"operationId":"revealContact","summary":"Reveal a person's email (1 credit) and optionally a direct dial (1 credit)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevealContactInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RevealContactResult"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Insufficient credits","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown contact","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/emails/find":{"post":{"tags":["Reveals"],"operationId":"findEmail","summary":"Find and verify one person's email from name + domain (1 credit when found)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindEmailInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FindEmailResult"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Insufficient credits","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/contacts":{"get":{"tags":["Contacts"],"operationId":"listContacts","summary":"List owned contacts","parameters":[{"name":"query","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/reveal-runs":{"post":{"tags":["Reveal runs"],"operationId":"startRevealRun","summary":"Reveal up to 500 people in the background","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Repeat-safe launches"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartRevealRunInput"}}}},"responses":{"201":{"description":"Run created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StartRevealRunResult"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Insufficient credits","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/reveal-runs/{id}":{"get":{"tags":["Reveal runs"],"operationId":"getRevealRun","summary":"Run progress, counts and first 200 revealed contacts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RevealRun"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/reveal-runs/{id}/contacts":{"get":{"tags":["Reveal runs"],"operationId":"listRevealRunContacts","summary":"Revealed contacts of a run, paged","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RevealedContact"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/research-tasks":{"post":{"tags":["Research"],"operationId":"launchResearch","summary":"Launch a research task (20+ companies or people)","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchResearchInput"}}}},"responses":{"201":{"description":"Task launched","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LaunchResearchResult"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Subscription required or insufficient credits","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"tags":["Research"],"operationId":"listResearchTasks","summary":"List research tasks","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","queued","in_progress","verifying","delivered","stopping","canceled"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResearchTaskSummary"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/research-tasks/{id}":{"get":{"tags":["Research"],"operationId":"getResearchTask","summary":"Task status, counts and first 100 delivered contacts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResearchTask"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/research-tasks/{id}/contacts":{"get":{"tags":["Research"],"operationId":"listResearchTaskContacts","summary":"Delivered contacts of a task, paged","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/contacts/{id}":{"get":{"tags":["Contacts"],"operationId":"getContact","summary":"One owned contact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/suppression-list":{"get":{"tags":["Suppression"],"operationId":"listSuppressionList","summary":"List suppressed emails or domains","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["email","domain"],"default":"email"}},{"name":"query","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SuppressionEntry"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["Suppression"],"operationId":"addToSuppressionList","summary":"Add emails and/or domains to the suppression list (repeat-safe)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionValues"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AddSuppressionResult"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["Suppression"],"operationId":"removeFromSuppressionList","summary":"Remove emails and/or domains from the suppression list","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionValues"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RemoveSuppressionResult"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Scope or seat permission missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or monthly search cap reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key `cl_live_…` (also accepted as `X-Api-Key`)"},"bearer":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://app.coldlytics.com/oauth/authorize","tokenUrl":"https://app.coldlytics.com/oauth/token","refreshUrl":"https://app.coldlytics.com/oauth/token","scopes":{"account:read":"See your plan, credit balance and usage limits","search:read":"Search companies and people in the Voyager database","contacts:read":"Read the contacts you own","reveals:write":"Reveal emails and direct dials (spends credits)","research:read":"See your research tasks and their results","research:write":"Launch research tasks (books credits)","suppression:write":"Add to and remove from your suppression list","offline_access":"Stay connected without signing in again","openid":"Confirm who you are","email":"See the email address on your account"}}}}},"schemas":{"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","description":"Stable machine-readable code"},"detail":{"type":"string"},"instance":{"type":"string","description":"Request id; quote it to support"}},"required":["type","title","status","code"]},"Meta":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer","nullable":true,"description":"Total matches; null when not computed"},"total_is_approximate":{"type":"boolean"},"has_more":{"type":"boolean"}},"required":["page","page_size","total","has_more"],"additionalProperties":false},"Account":{"type":"object","properties":{"email":{"type":"string","description":"Account owner email"},"first_name":{"type":"string","nullable":true},"workspace_name":{"type":"string","nullable":true},"subscribed":{"type":"boolean","description":"Whether the account has an active paid subscription"},"trial_started_at":{"type":"string","format":"date-time","nullable":true},"credits":{"type":"object","properties":{"available":{"type":"integer","description":"Credits that can be spent right now"},"booked":{"type":"integer","description":"Credits reserved by research tasks in progress"},"pending":{"type":"integer"},"spent":{"type":"integer"}},"required":["available","booked","pending","spent"],"additionalProperties":false},"searches":{"type":"object","properties":{"monthly_limit":{"type":"integer"},"used":{"type":"integer"},"resets_at":{"type":"string","format":"date-time"}},"required":["monthly_limit","used","resets_at"],"additionalProperties":false,"nullable":true,"description":"Company/people search allowance for the current period"},"principal":{"type":"object","properties":{"via":{"type":"string","enum":["api_key","oauth","legacy"]},"scopes":{"type":"array","items":{"type":"string","enum":["account:read","search:read","contacts:read","reveals:write","research:read","research:write","suppression:write"]}},"seat":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string"},"name":{"type":"string"}},"required":["id","email","name"],"additionalProperties":false,"nullable":true,"description":"Set when the credential belongs to a team seat rather than the owner"},"permissions":{"type":"object","properties":{"tasks":{"type":"boolean"},"reveals":{"type":"boolean"}},"required":["tasks","reveals"],"additionalProperties":false}},"required":["via","scopes","seat","permissions"],"additionalProperties":false}},"required":["email","first_name","workspace_name","subscribed","trial_started_at","credits","searches","principal"],"additionalProperties":false,"description":"The authenticated account: plan state, credit balance, search allowance"},"SearchOptions":{"type":"object","properties":{"kind":{"type":"string","enum":["seniorities","departments","categories","technologies","locations","data_points","job_functions"]},"options":{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Pass this in the corresponding filter"},"label":{"type":"string"},"description":{"type":"string"},"count":{"type":"integer","description":"Companies carrying this value, where known"},"type":{"type":"string","description":"locations: city | county | state | country"}},"required":["value","label"],"additionalProperties":false}},"usage":{"type":"string","description":"How to use these values in search_companies / search_people"}},"required":["kind","options","usage"],"additionalProperties":false},"SearchOptionsInput":{"type":"object","properties":{"kind":{"type":"string","enum":["seniorities","departments","categories","technologies","locations","data_points","job_functions"],"description":"Which vocabulary to list: seniorities, departments, data_points (research extras) and job_functions (research) are fixed lists; categories, technologies and locations are searched by `query`."},"query":{"type":"string","maxLength":80,"description":"Text to match (required for locations; recommended for categories and technologies)"}},"required":["kind"],"additionalProperties":false},"SearchCompaniesInput":{"type":"object","properties":{"query":{"type":"string","maxLength":200,"description":"Keywords describing the business, e.g. \"plumbers\" or \"dental clinic\". Synonyms are expanded."},"filters":{"type":"object","properties":{"locations":{"type":"array","items":{"anyOf":[{"type":"string","minLength":2,"maxLength":80},{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80,"description":"City, county, state or country, e.g. \"Austin, Texas, USA\""},"radius_miles":{"type":"integer","minimum":1,"maximum":200,"description":"Cities only; default 20"}},"required":["name"],"additionalProperties":false}]},"maxItems":10,"description":"Areas to search (any of). Names are resolved to the most populous match; use get_search_options(kind=locations) to disambiguate."},"postal_codes":{"type":"array","items":{"type":"string","minLength":2,"maxLength":24},"maxItems":200,"description":"ZIP / postal codes (any of), matched as prefixes: \"70809\", \"SW1A\". Equal-length US ranges like \"11933-11978\" are allowed. Combines with locations as OR."},"categories":{"type":"object","properties":{"include":{"type":"array","items":{"anyOf":[{"type":"integer","exclusiveMinimum":true,"minimum":0},{"type":"string","minLength":1,"maxLength":80}]},"maxItems":50,"description":"Match business categories in ANY of these"},"exclude":{"type":"array","items":{"anyOf":[{"type":"integer","exclusiveMinimum":true,"minimum":0},{"type":"string","minLength":1,"maxLength":80}]},"maxItems":50,"description":"Never match business categories in these (exclusion wins)"}},"additionalProperties":false,"description":"Business categories by id (from get_search_options) or exact name, e.g. \"Plumbing\""},"technologies":{"type":"object","properties":{"include":{"type":"array","items":{"anyOf":[{"type":"integer","exclusiveMinimum":true,"minimum":0},{"type":"string","minLength":1,"maxLength":80}]},"maxItems":50,"description":"Match website technologies in ANY of these"},"exclude":{"type":"array","items":{"anyOf":[{"type":"integer","exclusiveMinimum":true,"minimum":0},{"type":"string","minLength":1,"maxLength":80}]},"maxItems":50,"description":"Never match website technologies in these (exclusion wins)"}},"additionalProperties":false,"description":"Technologies detected on the website, by name (e.g. \"Shopify\", \"HubSpot\") or id"},"headcount":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Employee count range"},"revenue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Estimated annual revenue range, USD"},"founded_year":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Year the company was established"},"has_website_email":{"type":"boolean","description":"Only companies with a generic website email on file"},"franchise":{"type":"string","enum":["exclude","include"],"description":"exclude = drop franchises / national chains; include = only those"},"exclude_owned":{"type":"boolean","description":"Drop companies where this account already owns a contact (from research or reveals)"},"exclude_listed":{"type":"boolean","description":"Drop companies already saved to one of the account's lists"},"exclude_suppressed":{"type":"boolean","description":"Drop companies whose domain is on the account's suppression list (see list_suppression_list)"},"domains":{"type":"array","items":{"type":"string","minLength":3,"maxLength":253},"maxItems":500,"description":"Restrict to these website domains"}},"additionalProperties":false},"voyager_url":{"type":"string","maxLength":4000,"description":"A Voyager search URL copied from the Coldlytics dashboard; its query and filters are used as the base"},"page":{"type":"integer","minimum":1,"default":1,"description":"1-based page number"},"page_size":{"type":"integer","minimum":1,"maximum":50,"default":25,"description":"Results per page (max 50)"}},"additionalProperties":false},"SearchPeopleInput":{"type":"object","properties":{"query":{"type":"string","maxLength":200,"description":"Keywords describing the business, e.g. \"plumbers\" or \"dental clinic\". Synonyms are expanded."},"filters":{"type":"object","properties":{"locations":{"type":"array","items":{"anyOf":[{"type":"string","minLength":2,"maxLength":80},{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80,"description":"City, county, state or country, e.g. \"Austin, Texas, USA\""},"radius_miles":{"type":"integer","minimum":1,"maximum":200,"description":"Cities only; default 20"}},"required":["name"],"additionalProperties":false}]},"maxItems":10,"description":"Areas to search (any of). Names are resolved to the most populous match; use get_search_options(kind=locations) to disambiguate."},"postal_codes":{"type":"array","items":{"type":"string","minLength":2,"maxLength":24},"maxItems":200,"description":"ZIP / postal codes (any of), matched as prefixes: \"70809\", \"SW1A\". Equal-length US ranges like \"11933-11978\" are allowed. Combines with locations as OR."},"categories":{"type":"object","properties":{"include":{"type":"array","items":{"anyOf":[{"type":"integer","exclusiveMinimum":true,"minimum":0},{"type":"string","minLength":1,"maxLength":80}]},"maxItems":50,"description":"Match business categories in ANY of these"},"exclude":{"type":"array","items":{"anyOf":[{"type":"integer","exclusiveMinimum":true,"minimum":0},{"type":"string","minLength":1,"maxLength":80}]},"maxItems":50,"description":"Never match business categories in these (exclusion wins)"}},"additionalProperties":false,"description":"Business categories by id (from get_search_options) or exact name, e.g. \"Plumbing\""},"technologies":{"type":"object","properties":{"include":{"type":"array","items":{"anyOf":[{"type":"integer","exclusiveMinimum":true,"minimum":0},{"type":"string","minLength":1,"maxLength":80}]},"maxItems":50,"description":"Match website technologies in ANY of these"},"exclude":{"type":"array","items":{"anyOf":[{"type":"integer","exclusiveMinimum":true,"minimum":0},{"type":"string","minLength":1,"maxLength":80}]},"maxItems":50,"description":"Never match website technologies in these (exclusion wins)"}},"additionalProperties":false,"description":"Technologies detected on the website, by name (e.g. \"Shopify\", \"HubSpot\") or id"},"headcount":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Employee count range"},"revenue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Estimated annual revenue range, USD"},"founded_year":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Year the company was established"},"has_website_email":{"type":"boolean","description":"Only companies with a generic website email on file"},"franchise":{"type":"string","enum":["exclude","include"],"description":"exclude = drop franchises / national chains; include = only those"},"exclude_owned":{"type":"boolean","description":"Drop companies where this account already owns a contact (from research or reveals)"},"exclude_listed":{"type":"boolean","description":"Drop companies already saved to one of the account's lists"},"exclude_suppressed":{"type":"boolean","description":"Drop companies whose domain is on the account's suppression list (see list_suppression_list)"},"domains":{"type":"array","items":{"type":"string","minLength":3,"maxLength":253},"maxItems":500,"description":"Restrict to these website domains"}},"additionalProperties":false},"voyager_url":{"type":"string","maxLength":4000,"description":"A Voyager search URL copied from the Coldlytics dashboard; its query and filters are used as the base"},"page":{"type":"integer","minimum":1,"default":1,"description":"1-based page number"},"page_size":{"type":"integer","minimum":1,"maximum":50,"default":25,"description":"Results per page (max 50)"},"seniorities":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string","enum":["OWNERS_FOUNDERS","DIRECTORS_EXECUTIVES","MIDDLE_MANAGEMENT","STAFF"]},"maxItems":50,"description":"Match seniority in ANY of these"},"exclude":{"type":"array","items":{"type":"string","enum":["OWNERS_FOUNDERS","DIRECTORS_EXECUTIVES","MIDDLE_MANAGEMENT","STAFF"]},"maxItems":50,"description":"Never match seniority in these (exclusion wins)"}},"additionalProperties":false},"departments":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string","enum":["SALES","MARKETING","FINANCE","OPERATIONS","ENGINEERING","CLINICAL_MEDICAL","LEGAL","GENERAL_MANAGEMENT","OTHER"]},"maxItems":50,"description":"Match department in ANY of these"},"exclude":{"type":"array","items":{"type":"string","enum":["SALES","MARKETING","FINANCE","OPERATIONS","ENGINEERING","CLINICAL_MEDICAL","LEGAL","GENERAL_MANAGEMENT","OTHER"]},"maxItems":50,"description":"Never match department in these (exclusion wins)"}},"additionalProperties":false},"job_titles":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string","minLength":2,"maxLength":60},"maxItems":50,"description":"Match job-title keywords in ANY of these"},"exclude":{"type":"array","items":{"type":"string","minLength":2,"maxLength":60},"maxItems":50,"description":"Never match job-title keywords in these (exclusion wins)"}},"additionalProperties":false,"description":"Case-insensitive substrings of the job title, e.g. include [\"owner\", \"director\"]"},"has_dial":{"type":"boolean","description":"Only people with a direct dial on file"},"has_linkedin":{"type":"boolean","description":"Only people with a LinkedIn profile on file"},"max_per_company":{"type":"integer","minimum":1,"maximum":50,"description":"At most this many people per company, the most senior matching people first. Use 1 for one contact per business. Branches of one business count as the same company."}},"additionalProperties":false},"Company":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"website_title":{"type":"string","nullable":true},"address":{"type":"object","properties":{"line1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}},"required":["line1","city","state","zip","country"],"additionalProperties":false},"phone":{"type":"string","nullable":true},"categories":{"type":"array","items":{"type":"string"}},"headcount":{"type":"number","nullable":true},"revenue":{"type":"number","nullable":true,"description":"Estimated annual revenue, USD"},"founded_year":{"type":"number","nullable":true},"website_email":{"type":"string","nullable":true,"description":"Generic website email; masked on free accounts"},"social":{"type":"object","properties":{"linkedin":{"type":"string","nullable":true},"facebook":{"type":"string","nullable":true},"instagram":{"type":"string","nullable":true},"twitter":{"type":"string","nullable":true},"youtube":{"type":"string","nullable":true},"tiktok":{"type":"string","nullable":true}},"required":["linkedin","facebook","instagram","twitter","youtube","tiktok"],"additionalProperties":false},"google":{"type":"object","properties":{"profile_url":{"type":"string","nullable":true},"claimed":{"type":"boolean","nullable":true},"review_count":{"type":"number","nullable":true},"review_score":{"type":"number","nullable":true}},"required":["profile_url","claimed","review_count","review_score"],"additionalProperties":false},"page_speed":{"type":"number","nullable":true},"contact_count":{"type":"integer","description":"People on file at this company (revealable via search_people / lookup_company)"},"location_id":{"type":"integer","nullable":true,"description":"The branch this row shows; pass to reveal_contact"},"url":{"type":"string","description":"Company page in the Coldlytics dashboard"}},"required":["id","name","domain","address","phone","categories","headcount","revenue","founded_year","website_email","social","google","contact_count","location_id","url"],"additionalProperties":false},"Person":{"type":"object","properties":{"contact_id":{"type":"integer","description":"Pass to reveal_contact"},"first_name":{"type":"string"},"last_name":{"type":"string"},"job_title":{"type":"string","nullable":true},"seniority":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true},"has_email":{"type":"boolean"},"has_dial":{"type":"boolean"},"owned_crm_contact_id":{"type":"integer","nullable":true,"description":"Set when this account already owns the person (re-reveal is free; see get_contact)"},"location_id":{"type":"integer","nullable":true},"company":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true,"description":"The person's own branch name when they work at a branch other than the company's main one"},"domain":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"url":{"type":"string"}},"required":["id","name","domain","city","state","country","url"],"additionalProperties":false}},"required":["contact_id","first_name","last_name","job_title","seniority","department","linkedin_url","has_email","has_dial","owned_crm_contact_id","location_id","company"],"additionalProperties":false},"LookupCompanyResult":{"anyOf":[{"type":"object","properties":{"found":{"type":"boolean","enum":[true]},"domain":{"type":"string"},"company":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"domain":{"type":"string"},"description":{"type":"string","nullable":true},"website_email":{"type":"string","nullable":true},"headcount":{"type":"number","nullable":true},"revenue":{"type":"number","nullable":true},"founded_year":{"type":"number","nullable":true},"social":{"type":"object","properties":{"linkedin":{"type":"string","nullable":true},"facebook":{"type":"string","nullable":true},"instagram":{"type":"string","nullable":true},"twitter":{"type":"string","nullable":true},"youtube":{"type":"string","nullable":true},"tiktok":{"type":"string","nullable":true}},"required":["linkedin","facebook","instagram","twitter","youtube","tiktok"],"additionalProperties":false},"technologies":{"type":"array","items":{"type":"string"}},"contact_count":{"type":"integer"},"url":{"type":"string","nullable":true}},"required":["id","name","domain","description","website_email","headcount","revenue","founded_year","social","technologies","contact_count","url"],"additionalProperties":false},"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"is_primary":{"type":"boolean"},"address":{"type":"object","properties":{"line1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}},"required":["line1","city","state","zip","country"],"additionalProperties":false},"phone":{"type":"string","nullable":true},"google":{"type":"object","properties":{"profile_url":{"type":"string","nullable":true},"review_count":{"type":"number","nullable":true},"review_score":{"type":"number","nullable":true}},"required":["profile_url","review_count","review_score"],"additionalProperties":false},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true}},"required":["id","name","is_primary","address","phone","google","latitude","longitude"],"additionalProperties":false}},"primary_location_id":{"type":"integer","nullable":true},"people":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"integer"},"first_name":{"type":"string"},"last_name":{"type":"string"},"job_title":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true},"location_id":{"type":"integer","nullable":true},"has_email":{"type":"boolean"},"has_dial":{"type":"boolean"},"owned":{"type":"object","properties":{"crm_contact_id":{"type":"integer"},"emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"status":{"type":"string","enum":["VALID","INVALID","CATCHALL"],"nullable":true},"validated_at":{"type":"string","nullable":true}},"required":["email","status","validated_at"],"additionalProperties":false}},"direct_dials":{"type":"array","items":{"type":"string"}},"available":{"type":"object","properties":{"emails":{"type":"integer"},"dials":{"type":"integer"}},"required":["emails","dials"],"additionalProperties":false,"description":"Further unowned points purchasable as 1-credit top-ups"}},"required":["crm_contact_id","emails","direct_dials","available"],"additionalProperties":false,"nullable":true,"description":"Set when this account already owns the person"}},"required":["contact_id","first_name","last_name","job_title","linkedin_url","location_id","has_email","has_dial","owned"],"additionalProperties":false},"description":"Up to 100 revealable people across all branches"}},"required":["found","domain","company","locations","primary_location_id","people"],"additionalProperties":false},{"type":"object","properties":{"found":{"type":"boolean","enum":[false]},"domain":{"type":"string"},"hint":{"type":"string"}},"required":["found","domain","hint"],"additionalProperties":false}]},"RevealContactInput":{"type":"object","properties":{"contact_id":{"type":"integer","exclusiveMinimum":true,"minimum":0,"description":"From search_people or lookup_company"},"include_dial":{"type":"boolean","default":false,"description":"Also reveal a direct dial (1 extra credit when available)"},"location_id":{"type":"integer","exclusiveMinimum":true,"minimum":0,"description":"Branch the person was found at (location_id from search results)"}},"required":["contact_id"],"additionalProperties":false},"RevealContactResult":{"anyOf":[{"type":"object","properties":{"revealed":{"type":"boolean","enum":[true]},"crm_contact_id":{"type":"integer","description":"The saved contact in this account's Contacts (see get_contact)"},"email":{"type":"string"},"email_status":{"type":"string","enum":["VALID","INVALID","CATCHALL"]},"email_validated_at":{"type":"string"},"direct_dial":{"type":"string","nullable":true},"emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"status":{"type":"string","enum":["VALID","INVALID","CATCHALL"],"nullable":true},"validated_at":{"type":"string","nullable":true}},"required":["email","status","validated_at"],"additionalProperties":false}},"direct_dials":{"type":"array","items":{"type":"string"}},"available":{"type":"object","properties":{"emails":{"type":"integer"},"dials":{"type":"integer"}},"required":["emails","dials"],"additionalProperties":false},"credits_charged":{"type":"integer"},"already_owned":{"type":"boolean","description":"True when the account already owned this person; nothing was charged"},"credits_remaining":{"type":"integer"}},"required":["revealed","crm_contact_id","email","email_status","email_validated_at","direct_dial","emails","direct_dials","available","credits_charged","already_owned","credits_remaining"],"additionalProperties":false},{"type":"object","properties":{"revealed":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["no_email","validation_failed"]},"message":{"type":"string"}},"required":["revealed","reason","message"],"additionalProperties":false}]},"ListContactsInput":{"type":"object","properties":{"query":{"type":"string","maxLength":120,"description":"Free text over name, title, company and email"},"tag":{"type":"string","maxLength":60,"description":"Only contacts carrying this tag (by name)"},"page":{"type":"integer","minimum":1,"default":1,"description":"1-based page number"},"page_size":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Results per page (max 100)"}},"additionalProperties":false},"FindEmailInput":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"maxLength":80},"last_name":{"type":"string","minLength":1,"maxLength":80},"domain":{"type":"string","minLength":3,"maxLength":253,"description":"The person's company website domain"}},"required":["first_name","last_name","domain"],"additionalProperties":false},"FindEmailResult":{"anyOf":[{"type":"object","properties":{"found":{"type":"boolean","enum":[true]},"source":{"type":"string","enum":["database","pattern"],"description":"database = a known person; pattern = derived from the company's email pattern and verified live"},"email":{"type":"string"},"email_status":{"type":"string","enum":["VALID","INVALID","CATCHALL"]},"contact_id":{"type":"integer"},"crm_contact_id":{"type":"integer","description":"Saved to the account's Contacts"},"first_name":{"type":"string"},"last_name":{"type":"string"},"job_title":{"type":"string","nullable":true},"direct_dial":{"type":"string","nullable":true},"credits_charged":{"type":"integer"},"already_owned":{"type":"boolean"},"credits_remaining":{"type":"integer"},"company":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"domain":{"type":"string"}},"required":["id","name","domain"],"additionalProperties":false}},"required":["found","source","email","email_status","contact_id","crm_contact_id","first_name","last_name","job_title","direct_dial","credits_charged","already_owned","credits_remaining","company"],"additionalProperties":false},{"type":"object","properties":{"found":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["company_unknown","pattern_unknown","catch_all_domain","not_verified","no_email","daily_limit"]},"message":{"type":"string"},"suggestion":{"type":"string"}},"required":["found","reason","message"],"additionalProperties":false}]},"Contact":{"type":"object","properties":{"crm_contact_id":{"type":"integer"},"contact_id":{"type":"integer"},"first_name":{"type":"string"},"last_name":{"type":"string"},"job_title":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true},"email":{"type":"string","nullable":true,"description":"Primary email"},"email_status":{"type":"string","enum":["VALID","INVALID","CATCHALL"],"nullable":true},"emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"status":{"type":"string","enum":["VALID","INVALID","CATCHALL"],"nullable":true}},"required":["email","status"],"additionalProperties":false}},"direct_dial":{"type":"string","nullable":true},"direct_dials":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string","description":"RESEARCH (human research task) or REVEAL (instant reveal)"},"acquired_at":{"type":"string"},"available":{"type":"object","properties":{"emails":{"type":"integer"},"dials":{"type":"integer"}},"required":["emails","dials"],"additionalProperties":false,"description":"Unowned points purchasable as 1-credit top-ups via reveal_contact"},"company":{"type":"object","properties":{"id":{"type":"integer","nullable":true},"name":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}},"required":["id","name","domain","city","state","country","phone"],"additionalProperties":false}},"required":["crm_contact_id","contact_id","first_name","last_name","job_title","linkedin_url","email","email_status","emails","direct_dial","direct_dials","tags","source","acquired_at","available","company"],"additionalProperties":false},"StartRevealRunInput":{"type":"object","properties":{"contact_ids":{"type":"array","items":{"type":"integer","exclusiveMinimum":true,"minimum":0},"minItems":1,"maxItems":500,"description":"People to reveal (contact_id from search_people / lookup_company). Owned people are free."},"include_dial":{"type":"boolean","default":false,"description":"Also buy a direct dial where one exists (1 credit each)"},"tag":{"type":"string","minLength":1,"maxLength":60,"description":"Tag to apply to the revealed contacts (created if missing)"},"idempotency_key":{"type":"string","minLength":1,"maxLength":255,"description":"Client-chosen key; repeating it returns the same run instead of a second charge"}},"required":["contact_ids"],"additionalProperties":false},"StartRevealRunResult":{"type":"object","properties":{"run_id":{"type":"integer"},"status":{"type":"string","enum":["pending","in_progress","completed","failed","canceled"]},"requested_contacts":{"type":"integer"},"url":{"type":"string"},"next":{"type":"string","description":"How to follow progress"}},"required":["run_id","status","requested_contacts","url","next"],"additionalProperties":false},"RevealRun":{"type":"object","properties":{"run_id":{"type":"integer"},"status":{"type":"string","enum":["pending","in_progress","completed","failed","canceled"]},"title":{"type":"string","nullable":true},"requested_contacts":{"type":"integer"},"progress_percent":{"type":"integer"},"revealed_paid":{"type":"integer","description":"Fresh VALID emails, 1 credit each"},"revealed_free":{"type":"integer","description":"Catch-all emails (free)"},"already_owned":{"type":"integer"},"failed":{"type":"integer","description":"Verified undeliverable or gone; not retried"},"failed_retryable":{"type":"integer","description":"Verification errored; try again later"},"dials_revealed":{"type":"integer"},"credits_spent":{"type":"integer"},"stop_reason":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"created_at":{"type":"string"},"finished_at":{"type":"string","nullable":true},"url":{"type":"string","description":"Run history in the dashboard"},"contacts":{"type":"array","items":{"type":"object","properties":{"crm_contact_id":{"type":"integer"},"contact_id":{"type":"integer"},"first_name":{"type":"string"},"last_name":{"type":"string"},"job_title":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"email_status":{"type":"string","enum":["VALID","INVALID","CATCHALL"],"nullable":true},"direct_dial":{"type":"string","nullable":true},"company":{"type":"object","properties":{"id":{"type":"integer","nullable":true},"name":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true}},"required":["id","name","domain"],"additionalProperties":false}},"required":["crm_contact_id","contact_id","first_name","last_name","job_title","email","email_status","direct_dial","company"],"additionalProperties":false},"description":"Contacts revealed by this run (up to the first 200; REST pages the rest)"},"contacts_total":{"type":"integer"}},"required":["run_id","status","title","requested_contacts","progress_percent","revealed_paid","revealed_free","already_owned","failed","failed_retryable","dials_revealed","credits_spent","stop_reason","error","created_at","finished_at","url","contacts","contacts_total"],"additionalProperties":false},"RevealedContact":{"type":"object","properties":{"crm_contact_id":{"type":"integer"},"contact_id":{"type":"integer"},"first_name":{"type":"string"},"last_name":{"type":"string"},"job_title":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"email_status":{"type":"string","enum":["VALID","INVALID","CATCHALL"],"nullable":true},"direct_dial":{"type":"string","nullable":true},"company":{"type":"object","properties":{"id":{"type":"integer","nullable":true},"name":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true}},"required":["id","name","domain"],"additionalProperties":false}},"required":["crm_contact_id","contact_id","first_name","last_name","job_title","email","email_status","direct_dial","company"],"additionalProperties":false},"LaunchResearchInput":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":50,"description":"Name of the task as shown in the dashboard"},"companies":{"type":"array","items":{"type":"string","minLength":3,"maxLength":253,"description":"Company website domain, e.g. acme.com (a full URL is accepted)"},"minItems":20,"maxItems":2000,"description":"Company website domains to find people at (20–2000). Use with seniority_levels."},"people":{"type":"array","items":{"type":"object","properties":{"first_name":{"type":"string","maxLength":80},"last_name":{"type":"string","maxLength":80},"job_title":{"type":"string","maxLength":120},"company_name":{"type":"string","maxLength":160},"domain":{"type":"string","minLength":3,"maxLength":253,"description":"Company website domain, e.g. acme.com (a full URL is accepted)"},"linkedin_url":{"type":"string","format":"uri","maxLength":300}},"additionalProperties":false},"minItems":20,"maxItems":2000,"description":"Specific people to find contact details for (20–2000); each needs a domain or LinkedIn URL."},"seniority_levels":{"type":"array","items":{"type":"string","enum":["OWNERS_FOUNDERS","DIRECTORS_EXECUTIVES","MIDDLE_MANAGEMENT","STAFF"]},"minItems":1,"maxItems":4,"description":"Who to find at each company (companies mode)"},"job_functions":{"type":"array","items":{"type":"string","minLength":2,"maxLength":60},"maxItems":10,"description":"Optional job functions to target (see get_search_options kind=job_functions)"},"contacts_per_company":{"type":"integer","minimum":1,"maximum":5,"default":1,"description":"Companies mode: people to find per company"},"data_points":{"type":"array","items":{"type":"string","minLength":2,"maxLength":60},"maxItems":20,"description":"Extra data points beyond name, title, email, LinkedIn and website (see get_search_options kind=data_points); some cost extra credits"},"webhook_url":{"type":"string","format":"uri","maxLength":500,"description":"https URL to POST the delivered contacts to; signed with the account's webhook secret"},"dedupe_my_contacts":{"type":"boolean","default":true,"description":"Leave out companies and people already in the account's Contacts (from other tasks or reveals). false delivers them again: they cost credits as normal and stay one contact, linked to this task too"},"use_suppression_list":{"type":"boolean","default":true,"description":"Leave out everything on the account's global suppression list (see list_suppression_list)"},"suppress":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"string","minLength":3,"maxLength":254},"maxItems":5000,"description":"Email addresses (up to 5000 per request)"},"domains":{"type":"array","items":{"type":"string","minLength":3,"maxLength":253},"maxItems":5000,"description":"Company website domains, e.g. acme.com; full URLs are accepted (up to 5000 per request)"}},"additionalProperties":false,"description":"Emails and/or domains to leave out of this task only (a task-local suppression list, on top of the global one)"},"idempotency_key":{"type":"string","minLength":1,"maxLength":255,"description":"Client-chosen key; repeating it returns the same task instead of launching twice"}},"required":["title"],"additionalProperties":false},"LaunchResearchResult":{"type":"object","properties":{"task_id":{"type":"integer"},"launch_id":{"type":"integer"},"status":{"type":"string","enum":["draft","queued","in_progress","verifying","delivered","stopping","canceled"]},"contacts_requested":{"type":"integer"},"credits_per_contact":{"type":"integer"},"credits_required":{"type":"integer","description":"Booked when the task is allocated; unused credits are released at delivery"},"estimated_delivery_at":{"type":"string","nullable":true},"url":{"type":"string"},"next":{"type":"string"}},"required":["task_id","launch_id","status","contacts_requested","credits_per_contact","credits_required","estimated_delivery_at","url","next"],"additionalProperties":false},"ResearchTaskSummary":{"type":"object","properties":{"task_id":{"type":"integer"},"launch_id":{"type":"integer","nullable":true},"title":{"type":"string"},"status":{"type":"string","enum":["draft","queued","in_progress","verifying","delivered","stopping","canceled"]},"contacts_requested":{"type":"integer","nullable":true},"contacts_delivered":{"type":"object","properties":{"total":{"type":"integer"},"valid":{"type":"integer"},"catch_all":{"type":"integer"},"invalid":{"type":"integer"}},"required":["total","valid","catch_all","invalid"],"additionalProperties":false,"nullable":true},"deadline_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"message":{"type":"string","nullable":true,"description":"Delivery or cancellation note from the research team"},"webhook_url":{"type":"string","nullable":true},"created_at":{"type":"string"},"url":{"type":"string"}},"required":["task_id","launch_id","title","status","contacts_requested","contacts_delivered","deadline_at","delivered_at","canceled_at","message","webhook_url","created_at","url"],"additionalProperties":false},"ResearchTask":{"type":"object","properties":{"task_id":{"type":"integer"},"launch_id":{"type":"integer","nullable":true},"title":{"type":"string"},"status":{"type":"string","enum":["draft","queued","in_progress","verifying","delivered","stopping","canceled"]},"contacts_requested":{"type":"integer","nullable":true},"contacts_delivered":{"type":"object","properties":{"total":{"type":"integer"},"valid":{"type":"integer"},"catch_all":{"type":"integer"},"invalid":{"type":"integer"}},"required":["total","valid","catch_all","invalid"],"additionalProperties":false,"nullable":true},"deadline_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"message":{"type":"string","nullable":true,"description":"Delivery or cancellation note from the research team"},"webhook_url":{"type":"string","nullable":true},"created_at":{"type":"string"},"url":{"type":"string"},"contacts":{"type":"array","items":{"type":"object","properties":{"crm_contact_id":{"type":"integer"},"contact_id":{"type":"integer"},"first_name":{"type":"string"},"last_name":{"type":"string"},"job_title":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true},"email":{"type":"string","nullable":true,"description":"Primary email"},"email_status":{"type":"string","enum":["VALID","INVALID","CATCHALL"],"nullable":true},"emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"status":{"type":"string","enum":["VALID","INVALID","CATCHALL"],"nullable":true}},"required":["email","status"],"additionalProperties":false}},"direct_dial":{"type":"string","nullable":true},"direct_dials":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string","description":"RESEARCH (human research task) or REVEAL (instant reveal)"},"acquired_at":{"type":"string"},"available":{"type":"object","properties":{"emails":{"type":"integer"},"dials":{"type":"integer"}},"required":["emails","dials"],"additionalProperties":false,"description":"Unowned points purchasable as 1-credit top-ups via reveal_contact"},"company":{"type":"object","properties":{"id":{"type":"integer","nullable":true},"name":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}},"required":["id","name","domain","city","state","country","phone"],"additionalProperties":false}},"required":["crm_contact_id","contact_id","first_name","last_name","job_title","linkedin_url","email","email_status","emails","direct_dial","direct_dials","tags","source","acquired_at","available","company"],"additionalProperties":false},"description":"Delivered contacts (first 100; REST pages the rest)"},"contacts_total":{"type":"integer"}},"required":["task_id","launch_id","title","status","contacts_requested","contacts_delivered","deadline_at","delivered_at","canceled_at","message","webhook_url","created_at","url","contacts","contacts_total"],"additionalProperties":false},"SuppressionValues":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"string","minLength":3,"maxLength":254},"maxItems":5000,"description":"Email addresses (up to 5000 per request)"},"domains":{"type":"array","items":{"type":"string","minLength":3,"maxLength":253},"maxItems":5000,"description":"Company website domains, e.g. acme.com; full URLs are accepted (up to 5000 per request)"}},"additionalProperties":false},"SuppressionEntry":{"type":"object","properties":{"value":{"type":"string","description":"The email or domain, as stored (lowercased; domains reduced to the bare registrable domain)"},"added_at":{"type":"string"}},"required":["value","added_at"],"additionalProperties":false},"AddSuppressionResult":{"type":"object","properties":{"added":{"type":"integer","description":"Entries that were new"},"already_listed":{"type":"integer","description":"Entries that were already on the list"},"invalid":{"type":"integer","description":"Values that were not a valid email or domain and were skipped"},"over_limit":{"type":"integer","description":"Valid entries left out because the list is full"},"counts":{"type":"object","properties":{"emails":{"type":"integer","description":"Emails on the list after this call"},"domains":{"type":"integer","description":"Domains on the list after this call"}},"required":["emails","domains"],"additionalProperties":false}},"required":["added","already_listed","invalid","over_limit","counts"],"additionalProperties":false},"RemoveSuppressionResult":{"type":"object","properties":{"removed":{"type":"integer"},"counts":{"type":"object","properties":{"emails":{"type":"integer","description":"Emails on the list after this call"},"domains":{"type":"integer","description":"Domains on the list after this call"}},"required":["emails","domains"],"additionalProperties":false}},"required":["removed","counts"],"additionalProperties":false}}}}