{ "openapi": "3.1.0", "info": { "title": "OrbiSearch Public API", "version": "1.0.0", "description": "Email verification API for developers and agents. [Get your API key \u2192](https://orbisearch.com/dashboard/api-keys)\n\n**Rate limiting:** requests are limited per account, across all of its API keys (20 requests per second by default). Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers describing the current per-account window so clients can self-throttle; `429` responses also include a `Retry-After` header with the suggested backoff in seconds.", "contact": { "name": "Get API Key", "url": "https://orbisearch.com/dashboard/api-keys" } }, "servers": [ { "url": "https://api.orbisearch.com", "description": "OrbiSearch Public API" } ], "paths": { "/v1/verify": { "get": { "tags": [ "Public API v1" ], "summary": "Verify Single Email", "description": "Verify a single email address in real-time by probing DNS, MX, and the\ntarget mail server. Returns `status`, `substatus`, a plain-English\n`explanation`, the detected `email_provider`, and enrichment flags\n(`is_disposable`, `is_role_account`, `is_free`).\n\nCosts 0.2 credits per verification. Every verification is charged,\nincluding repeat verifications of the same address. On timeout you\nreceive a `status=unknown` / `substatus=timeout`\nresult (HTTP 200), so automated workflows can continue without branching on\nstatus codes. Credits are refunded only when the verification service is\nunavailable (HTTP 502).\n\nRate limit: 20 requests per second per account, shared across all of its\nAPI keys. For larger workloads prefer\nthe asynchronous `/v1/bulk` endpoint.", "operationId": "verify_single_email_v1_verify_get", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 320, "description": "Email address to verify.", "examples": [ "jane.doe@acme.com" ], "title": "Email" }, "description": "Email address to verify." }, { "name": "timeout", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 97, "minimum": 3, "description": "Timeout in seconds (3-97).", "examples": [ 70 ], "default": 97, "title": "Timeout" }, "description": "Timeout in seconds (3-97)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "example": { "detail": "API key required in X-API-Key header" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "403": { "description": "Insufficient credits", "content": { "application/json": { "example": { "detail": "Insufficient credits. You have 0.15 credits but need 0.2." }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Missing required query parameter: email.", "errors": [ { "loc": "query.email", "msg": "Missing required query parameter: email.", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } } } }, "/v1/email-lookup": { "post": { "tags": [ "Public API v1" ], "summary": "Find Email by LinkedIn URL or Name and Domain", "description": "Find a person's deliverable work email from their LinkedIn profile URL, or\nfrom their first name, last name and company domain (provide at least one\nof first or last name). Send one or the other, never both. Returns the\nemail found together with the same\nenrichment fields as `/v1/verify` (`status`, `substatus`, `explanation`,\n`email_provider`, `mx_record`, `is_domain_catch_all`,\n`is_secure_email_gateway`, `is_disposable`, `is_role_account`, `is_free`).\n\nTimeout parameter (optional):\n- Range: 30-97 seconds\n- Default: 97 seconds\n\nCosts 1 credit per returned response. Refunds are issued only when\nOrbiSearch infrastructure cannot complete the request (HTTP 502).\nEvery returned response is charged, including repeat searches for the\nsame person.\n\nRate limit: 20 requests per second per account, shared with `/v1/verify`\nand `/v1/bulk`. For best results, use the bulk email finder\n(`/v1/bulk-lookup`) where possible, as it allows more time per entry.", "operationId": "lookup_email_v1_email_lookup_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailLookupRequest" }, "examples": { "By LinkedIn URL": { "summary": "By LinkedIn URL", "value": { "linkedin_url": "https://www.linkedin.com/in/jane-doe" } }, "By name and domain": { "summary": "By name and domain", "value": { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com" } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailLookupResponse" }, "examples": { "By LinkedIn URL": { "summary": "By LinkedIn URL", "value": { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com", "email_domain": "acme.com", "linkedin_url": "https://www.linkedin.com/in/jane-doe", "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "confidence": 99, "full_name": "Jane Doe", "employer_name": "Acme", "employer_linkedin_url": "https://www.linkedin.com/company/acme", "all_emails": [ { "email": "jane.doe@acme.com", "job_order": 1, "company_linkedin_url": "https://www.linkedin.com/company/acme", "email_domain": "acme.com" } ], "email_provider": "Google Workspace", "mx_record": "aspmx.l.google.com", "is_domain_catch_all": false, "is_secure_email_gateway": false, "is_disposable": false, "is_role_account": false, "is_free": false, "credits_consumed": 1 } }, "By name and domain": { "summary": "By name and domain", "value": { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com", "email_domain": "acme.com", "linkedin_url": null, "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "confidence": 99, "full_name": null, "employer_name": null, "employer_linkedin_url": null, "all_emails": null, "email_provider": "Google Workspace", "mx_record": "aspmx.l.google.com", "is_domain_catch_all": false, "is_secure_email_gateway": false, "is_disposable": false, "is_role_account": false, "is_free": false, "credits_consumed": 1 } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "API key required in X-API-Key header" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" } } } }, "403": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Insufficient credits. You have 0.15 credits but need 0.2." } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Invalid request body field '0': Input should be a valid string.", "errors": [ { "loc": "body.0", "msg": "Invalid request body field '0': Input should be a valid string.", "type": "string_type" } ] } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "503": { "description": "Email finder service not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Email finder is not available in this environment" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/company-enrichment": { "get": { "tags": [ "Public API v1" ], "summary": "Enrich a company by LinkedIn URL or website domain", "description": "Return an enriched public record for a company, by its LinkedIn company\nURL or its website domain: firmographics, estimated headcount, follower\ncount and similar companies.\n\nCosts 1 credit per attempt. found and not_found are both charged,\nincluding repeat requests for the same company; refunds are issued only\nwhen OrbiSearch infrastructure cannot complete the request (HTTP 502).\nInvalid input is rejected with 422 before any charge.\n\nRate limit: shared with the other /v1/* endpoints.", "operationId": "company_enrichment_v1_company_enrichment_get", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "linkedin_url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A LinkedIn company or showcase URL. Preferred. Send this or domain, not both.", "examples": [ "https://www.linkedin.com/company/kearney" ], "title": "Linkedin Url" }, "description": "A LinkedIn company or showcase URL. Preferred. Send this or domain, not both." }, { "name": "domain", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The company's website domain, or a full URL reduced to its domain. Send this or linkedin_url, not both.", "examples": [ "kearney.com" ], "title": "Domain" }, "description": "The company's website domain, or a full URL reduced to its domain. Send this or linkedin_url, not both." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyEnrichmentResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "example": { "detail": "API key required in X-API-Key header" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "403": { "description": "Insufficient credits", "content": { "application/json": { "example": { "detail": "Insufficient credits. You have 0.15 credits but need 0.2." }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Missing required query parameter: email.", "errors": [ { "loc": "query.email", "msg": "Missing required query parameter: email.", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "502": { "description": "Temporarily unable to complete the request (refunded)", "content": { "application/json": { "example": { "detail": "Company enrichment service temporarily unavailable" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "example": { "detail": "Company enrichment is not available in this environment" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } } } }, "/v1/company-enrichment/bulk": { "post": { "tags": [ "Public API v1" ], "summary": "Submit Company Enrichment Bulk", "description": "Submit a list of LinkedIn company URLs for asynchronous bulk enrichment.\nDuplicate companies are charged once; every input row still comes back in\nresults, in order. Credits are deducted upfront at 1 credit per unique\nrow, once for the whole job.\n\nReturns a `job_id` immediately. Poll\n`GET /v1/company-enrichment/bulk/{job_id}` until `status` reaches\n`completed`, then fetch results via\n`GET /v1/company-enrichment/bulk/{job_id}/results`.\n\nEvery accepted row is charged, including not_found and error rows.\nDuplicates and invalid rows cost nothing. Refunds are issued\nonly when OrbiSearch infrastructure cannot accept or process the\nsubmission itself (the upfront charge is reversed in that case).", "operationId": "submit_company_enrichment_bulk_v1_company_enrichment_bulk_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyBulkSubmitRequest" } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyBulkSubmitResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "API key required in X-API-Key header" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" } } } }, "403": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Insufficient credits. You have 0.15 credits but need 0.2." } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Invalid request body field '0': Input should be a valid string.", "errors": [ { "loc": "body.0", "msg": "Invalid request body field '0': Input should be a valid string.", "type": "string_type" } ] } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Bulk company enrichment is not available in this environment" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/company-enrichment/bulk/{job_id}": { "get": { "tags": [ "Public API v1" ], "summary": "Get Company Enrichment Bulk Status", "description": "Check the status and progress of a bulk company-enrichment job. Returns\nthe current `status` (`running` or `completed`), per-outcome counts, and\nrow totals. Poll until `status=completed`, then fetch results.", "operationId": "get_company_enrichment_bulk_status_v1_company_enrichment_bulk__job_id__get", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyBulkStatusResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "example": { "detail": "API key required in X-API-Key header" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "404": { "description": "Job not found or does not belong to this API key", "content": { "application/json": { "example": { "detail": "Job not found" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Missing required query parameter: email.", "errors": [ { "loc": "query.email", "msg": "Missing required query parameter: email.", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } } } }, "/v1/company-enrichment/bulk/{job_id}/results": { "get": { "tags": [ "Public API v1" ], "summary": "Get Company Enrichment Bulk Results", "description": "Fetch results for a bulk company-enrichment job. Paginated with `limit`\n(default 50, max 500) and `offset` (default 0). Rows come back in submit\norder: every input row, repeats included, with the URL as sent echoed in\n`input_url`. A company not answered yet is returned with\n`result=pending`, so pages never shift while a job runs; rows our\ninfrastructure could not answer are returned with `result=error`. Each\nunique company carries its 1 credit on its first row; repeats and\ninvalid_url rows cost 0.", "operationId": "get_company_enrichment_bulk_results_v1_company_enrichment_bulk__job_id__results_get", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Rows per page (1-500).", "default": 50, "title": "Limit" }, "description": "Rows per page (1-500)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Row offset into the ordered result set.", "default": 0, "title": "Offset" }, "description": "Row offset into the ordered result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyBulkResultsResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "example": { "detail": "API key required in X-API-Key header" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "404": { "description": "Job not found or does not belong to this API key", "content": { "application/json": { "example": { "detail": "Job not found" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Missing required query parameter: email.", "errors": [ { "loc": "query.email", "msg": "Missing required query parameter: email.", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } } } }, "/v1/bulk-lookup": { "post": { "tags": [ "Public API v1" ], "summary": "Submit Bulk Email Finder Job", "description": "Submit a bulk email finder job: a list of LinkedIn profile URLs, or a list\nof (first_name, last_name, domain) rows, searched asynchronously. One input\ntype per job. Rows are deduplicated (case-insensitive) before billing;\ncredits are deducted upfront at 1 credit per unique row.\n\nReturns a `job_id` immediately. Poll `GET /v1/bulk-lookup/{job_id}` until\n`status` reaches `completed`, then fetch results via\n`GET /v1/bulk-lookup/{job_id}/results`.\n\nEvery returned row is charged, except `invalid_linkedin_url` rows, which\nare free. Refunds are issued only when OrbiSearch\ninfrastructure cannot accept or process the submission itself (the\nupfront charge is reversed in that case).\n\nRate limit: 20 requests per second per account, shared with `/v1/verify`,\n`/v1/bulk`, and `/v1/email-lookup`.", "operationId": "submit_bulk_lookup_v1_bulk_lookup_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupSubmitRequest" }, "examples": { "By LinkedIn URL": { "summary": "By LinkedIn URL", "value": { "input": [ { "linkedin_url": "https://www.linkedin.com/in/jane-doe" }, { "linkedin_url": "https://www.linkedin.com/in/john-smith" } ] } }, "By name and domain": { "summary": "By name and domain", "value": { "input": [ { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com" }, { "first_name": "John", "last_name": "Smith", "domain": "bigcorp.io" } ] } } } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupSubmitResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "API key required in X-API-Key header" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" } } } }, "403": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Insufficient credits. You have 0.15 credits but need 0.2." } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Invalid request body field '0': Input should be a valid string.", "errors": [ { "loc": "body.0", "msg": "Invalid request body field '0': Input should be a valid string.", "type": "string_type" } ] } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "503": { "description": "Email finder service not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Email finder is not available in this environment" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/bulk-lookup/{job_id}": { "get": { "tags": [ "Public API v1" ], "summary": "Get Bulk Email Finder Job Status", "description": "Check the status and progress of a bulk email finder job. Returns the current\n`status` (`running` or `completed`), per-outcome counts, and row totals.\n\nPoll this until `status=completed`, then fetch results via\n`GET /v1/bulk-lookup/{job_id}/results`.\n\nAll rows are charged per the bulk email finder billing policy: refunds happen\nonly when OrbiSearch infrastructure cannot accept the submission itself,\nnot on a per-row outcome basis.", "operationId": "get_bulk_lookup_status_v1_bulk_lookup__job_id__get", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupStatusResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "example": { "detail": "API key required in X-API-Key header" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "404": { "description": "Job not found or does not belong to this API key", "content": { "application/json": { "example": { "detail": "Job not found" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Missing required query parameter: email.", "errors": [ { "loc": "query.email", "msg": "Missing required query parameter: email.", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "503": { "description": "Email finder service not configured", "content": { "application/json": { "example": { "detail": "Email finder is not available in this environment" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } } } }, "/v1/bulk-lookup/{job_id}/results": { "get": { "tags": [ "Public API v1" ], "summary": "Get Bulk Email Finder Job Results", "description": "Fetch results for a bulk email finder job. Paginated with `limit` (default 50,\nmax 500) and `offset` (default 0). Each row mirrors the `/v1/email-lookup`\nresponse shape.\n\nRows whose search did not find a deliverable address are\nreturned with `status=unknown`, `substatus=no_address_found`, and\n`credits_consumed=1`. Every returned row is charged, except\n`invalid_linkedin_url` rows (`credits_consumed=0`).", "operationId": "get_bulk_lookup_results_v1_bulk_lookup__job_id__results_get", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupResultsResponse" }, "examples": { "By LinkedIn URL": { "summary": "By LinkedIn URL", "value": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "total_rows": 2, "total_processed": 2, "limit": 50, "offset": 0, "results": [ { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com", "email_domain": "acme.com", "linkedin_url": "https://www.linkedin.com/in/jane-doe", "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "confidence": 99, "full_name": "Jane Doe", "employer_name": "Acme", "employer_linkedin_url": "https://www.linkedin.com/company/acme", "all_emails": [ { "email": "jane.doe@acme.com", "job_order": 1, "company_linkedin_url": "https://www.linkedin.com/company/acme", "email_domain": "acme.com" } ], "email_provider": "Google Workspace", "mx_record": "aspmx.l.google.com", "is_domain_catch_all": false, "is_secure_email_gateway": false, "is_disposable": false, "is_role_account": false, "is_free": false, "credits_consumed": 1 }, { "first_name": "John", "last_name": "Smith", "domain": "bigcorp.io", "email_domain": "bigcorp.io", "linkedin_url": "https://www.linkedin.com/in/john-smith", "email": null, "status": "unknown", "substatus": "no_address_found", "explanation": "We couldn't find a valid work email for this person.", "confidence": null, "full_name": "John Smith", "employer_name": "Bigcorp", "employer_linkedin_url": "https://www.linkedin.com/company/bigcorp", "all_emails": [], "email_provider": "Unknown", "mx_record": null, "is_domain_catch_all": null, "is_secure_email_gateway": false, "is_disposable": null, "is_role_account": null, "is_free": null, "credits_consumed": 1 } ] } }, "By name and domain": { "summary": "By name and domain", "value": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "total_rows": 2, "total_processed": 2, "limit": 50, "offset": 0, "results": [ { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com", "email_domain": "acme.com", "linkedin_url": null, "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "confidence": 99, "full_name": null, "employer_name": null, "employer_linkedin_url": null, "all_emails": null, "email_provider": "Google Workspace", "mx_record": "aspmx.l.google.com", "is_domain_catch_all": false, "is_secure_email_gateway": false, "is_disposable": false, "is_role_account": false, "is_free": false, "credits_consumed": 1 }, { "first_name": "John", "last_name": "Smith", "domain": "bigcorp.io", "email_domain": "bigcorp.io", "linkedin_url": null, "email": null, "status": "unknown", "substatus": "no_address_found", "explanation": "No deliverable address could be found for the given name at this domain.", "confidence": null, "full_name": null, "employer_name": null, "employer_linkedin_url": null, "all_emails": null, "email_provider": "Unknown", "mx_record": null, "is_domain_catch_all": null, "is_secure_email_gateway": false, "is_disposable": null, "is_role_account": null, "is_free": null, "credits_consumed": 1 } ] } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "example": { "detail": "API key required in X-API-Key header" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "404": { "description": "Job not found or does not belong to this API key", "content": { "application/json": { "example": { "detail": "Job not found" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Missing required query parameter: email.", "errors": [ { "loc": "query.email", "msg": "Missing required query parameter: email.", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "503": { "description": "Email finder service not configured", "content": { "application/json": { "example": { "detail": "Email finder is not available in this environment" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } } } }, "/v1/bulk": { "post": { "tags": [ "Public API v1" ], "summary": "Submit Bulk Verification", "description": "Submit a list of email addresses for asynchronous bulk verification. The\nendpoint accepts the list, deduplicates it, queues the job, and returns a\n`job_id` immediately. Verification runs in the background. Poll\n`GET /v1/bulk/{job_id}` until `status` reaches `complete` and retrieve\nresults via `GET /v1/bulk/{job_id}/results` (partial results are available\nat any time).\n\nCosts 0.2 credits per unique email after deduplication. Maximum 100,000\nemails per submission.", "operationId": "submit_bulk_verification_v1_bulk_post", "requestBody": { "content": { "application/json": { "schema": { "items": { "type": "string", "maxLength": 320, "minLength": 3 }, "type": "array", "maxItems": 100000, "minItems": 1, "title": "Emails", "examples": [ [ "ceo@acme.com", "sales@example.com", "john.doe@bigcorp.io" ] ] } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobSubmitResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "API key required in X-API-Key header" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Email list cannot be empty" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "403": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Insufficient credits. You have 0.15 credits but need 0.2." } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Invalid request body field '0': Input should be a valid string.", "errors": [ { "loc": "body.0", "msg": "Invalid request body field '0': Input should be a valid string.", "type": "string_type" } ] } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/bulk/{job_id}": { "get": { "tags": [ "Public API v1" ], "summary": "Get Bulk Job Status", "description": "Check the status and progress of a bulk verification job. Returns the\ncurrent `status` (`pending`, `in_progress`, `partial_complete_retrying`,\n`complete`, or `failed`), the number of emails processed so far, and the\n`retry_status` for any emails that initially returned `unknown` and are\nbeing automatically retried.\n\nClients should poll this endpoint after submitting a job and treat results\nas final only once `status=complete`.", "operationId": "get_bulk_job_status_v1_bulk__job_id__get", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobStatusResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "example": { "detail": "API key required in X-API-Key header" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Email list cannot be empty" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "404": { "description": "Job not found or does not belong to this API key", "content": { "application/json": { "example": { "detail": "Job not found" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Missing required query parameter: email.", "errors": [ { "loc": "query.email", "msg": "Missing required query parameter: email.", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } } } }, "/v1/bulk/{job_id}/results": { "get": { "tags": [ "Public API v1" ], "summary": "Get Bulk Job Results", "description": "Retrieve the verification results for a bulk job. Returns an array of\n`EmailVerificationResponse` objects, one per email processed so far.\n\nPartial results are served while the job is still in progress; the\n`total_results` field reflects the count in the current response, not the\nfinal job total. Treat the result set as final only when the job `status`\nis `complete` and `pending_retries` is empty.", "operationId": "get_bulk_job_results_v1_bulk__job_id__results_get", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobResultsResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "example": { "detail": "API key required in X-API-Key header" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Email list cannot be empty" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "404": { "description": "Job not found or does not belong to this API key", "content": { "application/json": { "example": { "detail": "Job not found" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "409": { "description": "Job has not completed yet", "content": { "application/json": { "example": { "detail": "Job is not completed yet. Current status: in_progress" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Missing required query parameter: email.", "errors": [ { "loc": "query.email", "msg": "Missing required query parameter: email.", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } } } }, "/v1/content-spam-check": { "post": { "tags": [ "Public API v1" ], "summary": "Check Email Copy for Spam Triggers", "description": "Analyse the text of a cold email for the content signals SpamAssassin\nflags, and get back the same `score`, `threshold`, `verdict`, and fired\n`rules` shown in the OrbiSearch dashboard. Use it to spot and rewrite the\nphrases that push a message toward the spam threshold before you send.\n\nFree to call. No credits are deducted. Usage is bounded by a daily cap of\n100 checks per account, **shared** with the in-dashboard spam checker (both\ndraw down the same pool), plus the standard 20 requests per second per\naccount. Exceeding the daily cap returns `429` with `code: \"daily_quota_exceeded\"`\nand a `Retry-After` of seconds until reset; exceeding the per-second limit\nreturns `429` with `code: \"rate_limited\"` and a `Retry-After` computed from\nthe remaining rate-limit window.", "operationId": "content_spam_check_v1_content_spam_check_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentSpamCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentSpamCheckResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "API key required in X-API-Key header" } } } }, "429": { "description": "Daily free-tier limit reached", "headers": { "Retry-After": { "description": "Seconds until the daily quota resets (UTC midnight).", "schema": { "type": "integer", "examples": [ 43200 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "You've reached today's limit of 100 checks. Try again tomorrow.", "code": "daily_quota_exceeded" } } } }, "503": { "description": "Spam-analysis engine temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Spam checker temporarily unavailable. Please try again.", "code": "engine_unavailable" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Invalid request body field 'content': String should have at least 1 character.", "errors": [ { "loc": "body.content", "msg": "Invalid request body field 'content': String should have at least 1 character.", "type": "string_too_short" } ] } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/credits": { "get": { "tags": [ "Public API v1" ], "summary": "Get Credits", "description": "Retrieve the current credit balance for the API key making the request.\nEach single or bulk verification costs 0.2 credits. Fractional values are\npossible.\n\nThe `X-RateLimit-*` headers on its responses report your current\nper-account window state.", "operationId": "get_credits_v1_credits_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "API key required in X-API-Key header" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/unlimited/email-lookup": { "post": { "tags": [ "Unlimited Plans" ], "summary": "Find Email by LinkedIn URL or Name and Domain (Unlimited Plans)", "description": "Identical email finder and response shape as `/v1/email-lookup`, for\nunlimited-plan subscription keys. Counts 1 request against your plan's\nmonthly cap per returned response; no credits are consumed. Rate\nlimited to your plan's requests-per-second, per account.\n\n`credits_consumed` is retained for wire compatibility and reads 0.\nNo credits move on unlimited plans.", "operationId": "unlimited_lookup_email_v1_unlimited_email_lookup_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailLookupRequest" }, "examples": { "By LinkedIn URL": { "summary": "By LinkedIn URL", "value": { "linkedin_url": "https://www.linkedin.com/in/jane-doe" } }, "By name and domain": { "summary": "By name and domain", "value": { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com" } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailLookupResponse" }, "examples": { "By LinkedIn URL": { "summary": "By LinkedIn URL", "value": { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com", "email_domain": "acme.com", "linkedin_url": "https://www.linkedin.com/in/jane-doe", "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "confidence": 99, "full_name": "Jane Doe", "employer_name": "Acme", "employer_linkedin_url": "https://www.linkedin.com/company/acme", "all_emails": [ { "email": "jane.doe@acme.com", "job_order": 1, "company_linkedin_url": "https://www.linkedin.com/company/acme", "email_domain": "acme.com" } ], "email_provider": "Google Workspace", "mx_record": "aspmx.l.google.com", "is_domain_catch_all": false, "is_secure_email_gateway": false, "is_disposable": false, "is_role_account": false, "is_free": false, "credits_consumed": 0 } }, "By name and domain": { "summary": "By name and domain", "value": { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com", "email_domain": "acme.com", "linkedin_url": null, "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "confidence": 99, "full_name": null, "employer_name": null, "employer_linkedin_url": null, "all_emails": null, "email_provider": "Google Workspace", "mx_record": "aspmx.l.google.com", "is_domain_catch_all": false, "is_secure_email_gateway": false, "is_disposable": false, "is_role_account": false, "is_free": false, "credits_consumed": 0 } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "API key required in X-API-Key header" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" } } } }, "402": { "description": "No active subscription for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "No active subscription. This key resumes working when the subscription is reinstated.", "code": "subscription_inactive" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "403": { "description": "Key plan does not match this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "This endpoint requires an unlimited API key. Pay-as-you-go keys use the credit-metered /v1 endpoints.", "code": "wrong_key_plan" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Invalid request body field '0': Input should be a valid string.", "errors": [ { "loc": "body.0", "msg": "Invalid request body field '0': Input should be a valid string.", "type": "string_type" } ] } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/unlimited/bulk-lookup": { "post": { "tags": [ "Unlimited Plans" ], "summary": "Submit Bulk Email Finder Job (Unlimited Plans)", "description": "Same as `/v1/bulk-lookup` (same 10,000-row cap per\njob, same status/results contract), gated by your plan's daily bulk\nsearch quota instead of credits, with unlimited jobs; each accepted\nsubmission consumes one search per unique row from the day's quota\n(`invalid_linkedin_url` rows use none). A\nrejected or failed submission consumes nothing. `credits_consumed`\nreads 0. No credits move on unlimited plans.", "operationId": "unlimited_submit_bulk_lookup_v1_unlimited_bulk_lookup_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupSubmitRequest" }, "examples": { "By LinkedIn URL": { "summary": "By LinkedIn URL", "value": { "input": [ { "linkedin_url": "https://www.linkedin.com/in/jane-doe" }, { "linkedin_url": "https://www.linkedin.com/in/john-smith" } ] } }, "By name and domain": { "summary": "By name and domain", "value": { "input": [ { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com" }, { "first_name": "John", "last_name": "Smith", "domain": "bigcorp.io" } ] } } } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupSubmitResponse" }, "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "status": "submitted", "total_rows": 500, "credits_consumed": 0 } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "API key required in X-API-Key header" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" } } } }, "402": { "description": "No active subscription for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "No active subscription. This key resumes working when the subscription is reinstated.", "code": "subscription_inactive" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "403": { "description": "Key plan does not match this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "This endpoint requires an unlimited API key. Pay-as-you-go keys use the credit-metered /v1 endpoints.", "code": "wrong_key_plan" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Invalid request body field '0': Input should be a valid string.", "errors": [ { "loc": "body.0", "msg": "Invalid request body field '0': Input should be a valid string.", "type": "string_type" } ] } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/unlimited/bulk-lookup/{job_id}": { "get": { "tags": [ "Unlimited Plans" ], "summary": "Bulk Email Finder Job Status (Unlimited Plans)", "description": "Status of an unlimited-plan bulk email finder job. Same contract as\n`GET /v1/bulk-lookup/{job_id}`.", "operationId": "unlimited_bulk_lookup_status_v1_unlimited_bulk_lookup__job_id__get", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupStatusResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "example": { "detail": "API key required in X-API-Key header" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "402": { "description": "No active subscription for this key", "content": { "application/json": { "example": { "detail": "No active subscription. This key resumes working when the subscription is reinstated.", "code": "subscription_inactive" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "403": { "description": "Key plan does not match this endpoint", "content": { "application/json": { "example": { "detail": "This endpoint requires an unlimited API key. Pay-as-you-go keys use the credit-metered /v1 endpoints.", "code": "wrong_key_plan" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "404": { "description": "Job not found or does not belong to this API key", "content": { "application/json": { "example": { "detail": "Job not found" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Missing required query parameter: email.", "errors": [ { "loc": "query.email", "msg": "Missing required query parameter: email.", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } } } }, "/v1/unlimited/bulk-lookup/{job_id}/results": { "get": { "tags": [ "Unlimited Plans" ], "summary": "Bulk Email Finder Job Results (Unlimited Plans)", "description": "Results of an unlimited-plan bulk email finder job. Same contract as\n`GET /v1/bulk-lookup/{job_id}/results`.", "operationId": "unlimited_bulk_lookup_results_v1_unlimited_bulk_lookup__job_id__results_get", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupResultsResponse" }, "examples": { "By LinkedIn URL": { "summary": "By LinkedIn URL", "value": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "total_rows": 2, "total_processed": 2, "limit": 50, "offset": 0, "results": [ { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com", "email_domain": "acme.com", "linkedin_url": "https://www.linkedin.com/in/jane-doe", "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "confidence": 99, "full_name": "Jane Doe", "employer_name": "Acme", "employer_linkedin_url": "https://www.linkedin.com/company/acme", "all_emails": [ { "email": "jane.doe@acme.com", "job_order": 1, "company_linkedin_url": "https://www.linkedin.com/company/acme", "email_domain": "acme.com" } ], "email_provider": "Google Workspace", "mx_record": "aspmx.l.google.com", "is_domain_catch_all": false, "is_secure_email_gateway": false, "is_disposable": false, "is_role_account": false, "is_free": false, "credits_consumed": 0 }, { "first_name": "John", "last_name": "Smith", "domain": "bigcorp.io", "email_domain": "bigcorp.io", "linkedin_url": "https://www.linkedin.com/in/john-smith", "email": null, "status": "unknown", "substatus": "no_address_found", "explanation": "We couldn't find a valid work email for this person.", "confidence": null, "full_name": "John Smith", "employer_name": "Bigcorp", "employer_linkedin_url": "https://www.linkedin.com/company/bigcorp", "all_emails": [], "email_provider": "Unknown", "mx_record": null, "is_domain_catch_all": null, "is_secure_email_gateway": false, "is_disposable": null, "is_role_account": null, "is_free": null, "credits_consumed": 0 } ] } }, "By name and domain": { "summary": "By name and domain", "value": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "total_rows": 2, "total_processed": 2, "limit": 50, "offset": 0, "results": [ { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com", "email_domain": "acme.com", "linkedin_url": null, "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "confidence": 99, "full_name": null, "employer_name": null, "employer_linkedin_url": null, "all_emails": null, "email_provider": "Google Workspace", "mx_record": "aspmx.l.google.com", "is_domain_catch_all": false, "is_secure_email_gateway": false, "is_disposable": false, "is_role_account": false, "is_free": false, "credits_consumed": 0 }, { "first_name": "John", "last_name": "Smith", "domain": "bigcorp.io", "email_domain": "bigcorp.io", "linkedin_url": null, "email": null, "status": "unknown", "substatus": "no_address_found", "explanation": "No deliverable address could be found for the given name at this domain.", "confidence": null, "full_name": null, "employer_name": null, "employer_linkedin_url": null, "all_emails": null, "email_provider": "Unknown", "mx_record": null, "is_domain_catch_all": null, "is_secure_email_gateway": false, "is_disposable": null, "is_role_account": null, "is_free": null, "credits_consumed": 0 } ] } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "example": { "detail": "API key required in X-API-Key header" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "402": { "description": "No active subscription for this key", "content": { "application/json": { "example": { "detail": "No active subscription. This key resumes working when the subscription is reinstated.", "code": "subscription_inactive" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "403": { "description": "Key plan does not match this endpoint", "content": { "application/json": { "example": { "detail": "This endpoint requires an unlimited API key. Pay-as-you-go keys use the credit-metered /v1 endpoints.", "code": "wrong_key_plan" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "404": { "description": "Job not found or does not belong to this API key", "content": { "application/json": { "example": { "detail": "Job not found" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "example": { "detail": "Missing required query parameter: email.", "errors": [ { "loc": "query.email", "msg": "Missing required query parameter: email.", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } } } }, "/v1/unlimited/usage": { "get": { "tags": [ "Unlimited Plans" ], "summary": "Current Plan Usage", "description": "Your plan's consumption for the current billing period: single search\nrequests used vs the monthly cap, bulk searches used today against the\ndaily cap (with its next UTC-midnight reset time), and when the\nbilling period resets. Free, and does not count against the monthly cap\n(it does share the per-account request-rate window).", "operationId": "unlimited_usage_v1_unlimited_usage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlimitedUsageResponse" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "API key required in X-API-Key header" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying. Computed from the remaining rate-limit window (typically 1 for the per-second limit, longer when the limit is exceeded by 3x or more); for endpoints with a daily quota, seconds until the quota resets.", "schema": { "type": "integer", "examples": [ 1 ] } }, "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "Rate limit exceeded. Maximum 20 requests per second per account. Contact us to discuss higher limits.", "code": "rate_limited" } } } }, "402": { "description": "No active subscription for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "No active subscription. This key resumes working when the subscription is reinstated.", "code": "subscription_inactive" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } }, "403": { "description": "Key plan does not match this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "detail": "This endpoint requires an unlimited API key. Pay-as-you-go keys use the credit-metered /v1 endpoints.", "code": "wrong_key_plan" } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 20 ] } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current per-API-key window.", "schema": { "type": "integer", "examples": [ 13 ] } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) at which the current window resets.", "schema": { "type": "integer", "examples": [ 1751700000 ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "ApiErrorResponse": { "properties": { "detail": { "type": "string", "title": "Detail", "description": "Human-readable description of what went wrong.", "examples": [ "API key required in X-API-Key header" ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code", "description": "Stable machine-readable error code, present on conditions a client may want to branch on (for example `rate_limited` for the per-second limit versus `daily_quota_exceeded` for the daily cap). Absent on errors that need no further disambiguation.", "examples": [ "daily_quota_exceeded" ] }, "errors": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ValidationErrorDetail" }, "type": "array" }, { "type": "null" } ], "title": "Errors", "description": "Individual validation failures, one entry per invalid parameter or field. Present only on 422 responses; when the request has a single problem, `detail` carries the same message. Absent on all other error codes." } }, "type": "object", "required": [ "detail" ], "title": "ApiErrorResponse", "description": "Error response body." }, "BulkJobResultsResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "Unique job identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "status": { "type": "string", "enum": [ "complete", "partial_complete_retrying" ], "title": "Status", "description": "Job status when results were fetched.", "examples": [ "complete" ] }, "total_results": { "type": "integer", "title": "Total Results", "description": "Total number of results in this response.", "examples": [ 500 ] }, "results": { "items": { "$ref": "#/components/schemas/EmailVerificationResponse" }, "type": "array", "title": "Results", "description": "Array of email verification results." }, "pending_retries": { "items": { "type": "string" }, "type": "array", "title": "Pending Retries", "description": "Emails still being retried (greylisted, awaiting MTA retry window). Empty when the job has fully settled.", "examples": [ [] ] }, "retry_count": { "type": "integer", "title": "Retry Count", "description": "The number of emails still queued for retry. Always the same as the number of entries in `pending_retries`.", "default": 0, "examples": [ 0 ] } }, "type": "object", "required": [ "job_id", "status", "total_results", "results" ], "title": "BulkJobResultsResponse", "description": "Results of a completed bulk verification job.", "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "status": "complete", "total_results": 500, "results": [ { "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "email_provider": "Google Workspace", "is_disposable": false, "is_role_account": false, "is_free": false } ], "pending_retries": [], "retry_count": 0 } }, "BulkJobStatusResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "Unique job identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "status": { "type": "string", "enum": [ "pending", "in_progress", "partial_complete_retrying", "complete", "failed" ], "pattern": "^[a-z_]{1,64}$", "title": "Status", "description": "Current job status: pending, in_progress, partial_complete_retrying, complete, failed.", "examples": [ "in_progress" ] }, "total_emails": { "type": "integer", "title": "Total Emails", "description": "Total number of emails in this job.", "examples": [ 500 ] }, "emails_processed": { "type": "integer", "title": "Emails Processed", "description": "Number of emails processed so far.", "examples": [ 245 ] }, "retry_status": { "type": "string", "enum": [ "none", "pending", "partial", "complete" ], "title": "Retry Status", "description": "Retry status: none, pending, partial, complete.", "default": "none", "examples": [ "none" ] }, "submitted_at": { "type": "string", "format": "date-time", "title": "Submitted At", "description": "When the job was submitted (ISO 8601 timestamp).", "examples": [ "2024-01-15T10:30:00+00:00" ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Completed At", "description": "When the job was completed (ISO 8601 timestamp), or null if still in progress.", "examples": [ null ] } }, "type": "object", "required": [ "job_id", "status", "total_emails", "emails_processed", "submitted_at" ], "title": "BulkJobStatusResponse", "description": "Status information for a bulk verification job.", "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "status": "in_progress", "total_emails": 500, "emails_processed": 245, "retry_status": "none", "submitted_at": "2024-01-15T10:30:00+00:00" } }, "BulkJobSubmitResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "Unique job identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "status": { "type": "string", "enum": [ "submitted" ], "const": "submitted", "title": "Status", "description": "Submission acknowledgement status.", "examples": [ "submitted" ] }, "total_emails": { "type": "integer", "title": "Total Emails", "description": "Total number of unique emails to verify.", "examples": [ 500 ] }, "estimated_cost": { "type": "number", "title": "Estimated Cost", "description": "Estimated credit cost for this job.", "examples": [ 100.0 ] } }, "type": "object", "required": [ "job_id", "status", "total_emails", "estimated_cost" ], "title": "BulkJobSubmitResponse", "description": "Response when submitting a bulk verification job.", "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "status": "submitted", "total_emails": 500, "estimated_cost": 100.0 } }, "BulkLookupInputRow": { "properties": { "first_name": { "type": "string", "maxLength": 64, "title": "First Name", "description": "Person's first name. Optional individually, but provide at least one of first or last name when submitting a name and domain.", "default": "", "examples": [ "Jane" ] }, "last_name": { "type": "string", "maxLength": 64, "title": "Last Name", "description": "Person's last name. Optional individually, but provide at least one of first or last name when submitting a name and domain.", "default": "", "examples": [ "Doe" ] }, "domain": { "type": "string", "maxLength": 253, "title": "Domain", "description": "Company domain to search within. Required unless a linkedin_url is provided.", "default": "", "examples": [ "acme.com" ] }, "linkedin_url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Linkedin Url", "description": "LinkedIn profile URL to find a work email for. Provide this instead of first_name, last_name and domain.", "examples": [ "https://www.linkedin.com/in/jane-doe" ] } }, "type": "object", "title": "BulkLookupInputRow", "description": "One bulk row: a name+domain tuple, or a LinkedIn profile URL.", "example": { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com" } }, "BulkLookupResultsResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "Unique job identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "total_rows": { "type": "integer", "title": "Total Rows", "description": "Total rows submitted.", "examples": [ 500 ] }, "total_processed": { "type": "integer", "title": "Total Processed", "description": "Rows processed so far.", "examples": [ 500 ] }, "limit": { "type": "integer", "title": "Limit", "description": "Page size used for this response.", "examples": [ 50 ] }, "offset": { "type": "integer", "title": "Offset", "description": "Row offset into the ordered result set.", "examples": [ 0 ] }, "results": { "items": { "$ref": "#/components/schemas/EmailLookupResponse" }, "type": "array", "title": "Results", "description": "Per-row search results, one object per submitted row." } }, "type": "object", "required": [ "job_id", "total_rows", "total_processed", "limit", "offset", "results" ], "title": "BulkLookupResultsResponse", "description": "Paginated results for a bulk email finder job.", "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "total_rows": 500, "total_processed": 500, "limit": 50, "offset": 0, "results": [] } }, "BulkLookupStatusResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "Unique job identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "status": { "type": "string", "enum": [ "running", "completed" ], "title": "Status", "description": "Job status: running (still processing) or completed (all rows done).", "examples": [ "running" ] }, "total_rows": { "type": "integer", "title": "Total Rows", "description": "Total rows submitted.", "examples": [ 500 ] }, "total_processed": { "type": "integer", "title": "Total Processed", "description": "Rows processed so far.", "examples": [ 237 ] }, "summary": { "$ref": "#/components/schemas/BulkLookupSummary", "description": "Per-outcome counts." }, "created_at": { "type": "string", "title": "Created At", "description": "Job submission timestamp (UTC).", "examples": [ "2026-04-21T14:30:00Z" ] }, "finished_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finished At", "description": "Timestamp of the last processed row (UTC). Null while running.", "examples": [ null ] } }, "type": "object", "required": [ "job_id", "status", "total_rows", "total_processed", "summary", "created_at" ], "title": "BulkLookupStatusResponse", "description": "Status snapshot of a bulk email finder job.", "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "status": "running", "total_rows": 500, "total_processed": 237, "summary": { "total_found": 198, "total_not_found": 39 }, "created_at": "2026-04-21T14:30:00Z" } }, "BulkLookupSubmitRequest": { "properties": { "input": { "items": { "$ref": "#/components/schemas/BulkLookupInputRow" }, "type": "array", "maxItems": 10000, "minItems": 1, "title": "Input", "description": "Rows to search: every row a linkedin_url, or every row a first/last name and a company domain. One input type per job; a list that mixes them is refused with 422. Duplicate rows are deduplicated before billing. Maximum 10,000 rows per submission." } }, "type": "object", "required": [ "input" ], "title": "BulkLookupSubmitRequest", "description": "Submission payload for POST /v1/bulk-lookup.", "example": { "input": [ { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com" }, { "first_name": "John", "last_name": "Smith", "domain": "bigcorp.io" } ] } }, "BulkLookupSubmitResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "Unique job identifier. Pass this to GET /v1/bulk-lookup/{job_id} to poll status.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "status": { "type": "string", "enum": [ "submitted" ], "const": "submitted", "title": "Status", "description": "Submission acknowledgement status.", "examples": [ "submitted" ] }, "total_rows": { "type": "integer", "title": "Total Rows", "description": "Number of unique rows submitted after deduplication.", "examples": [ 500 ] }, "credits_consumed": { "type": "integer", "title": "Credits Consumed", "description": "Credits deducted for this submission: 1 per unique row on pay-as-you-go keys, except invalid_linkedin_url rows, which are free; 0 on unlimited plans (rows draw on the daily cap instead).", "examples": [ 500 ] } }, "type": "object", "required": [ "job_id", "status", "total_rows", "credits_consumed" ], "title": "BulkLookupSubmitResponse", "description": "Response when submitting a bulk email finder job.", "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "status": "submitted", "total_rows": 500, "credits_consumed": 500 } }, "BulkLookupSummary": { "properties": { "total_found": { "type": "integer", "title": "Total Found", "description": "Rows where a deliverable email was found.", "examples": [ 420 ] }, "total_not_found": { "type": "integer", "title": "Total Not Found", "description": "Processed rows that returned no email, whatever the substatus.", "examples": [ 80 ] } }, "type": "object", "required": [ "total_found", "total_not_found" ], "title": "BulkLookupSummary", "description": "Per-outcome counts for a bulk email finder job." }, "CompanyBulkInputRow": { "properties": { "linkedin_url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Linkedin Url", "description": "A LinkedIn company or showcase URL. Preferred: when a row fills both fields, this one is used. A malformed URL, a numeric-ID URL, a blank cell or a name over 200 characters is skipped (see result=invalid_url), not rejected.", "examples": [ "https://www.linkedin.com/company/kearney" ] }, "domain": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Domain", "description": "The company's website domain, or a full URL reduced to its domain. Used when linkedin_url is absent or blank. A value that is not a website domain is skipped (see result=invalid_url), not rejected.", "examples": [ "kearney.com" ] } }, "type": "object", "title": "CompanyBulkInputRow", "description": "One company submitted for bulk enrichment: its LinkedIn company URL\n(preferred) or its website domain.", "example": { "linkedin_url": "https://www.linkedin.com/company/kearney" } }, "CompanyBulkResultsResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "Unique job identifier." }, "total_rows": { "type": "integer", "title": "Total Rows", "description": "Total input rows submitted (repeats included).", "examples": [ 500 ] }, "total_processed": { "type": "integer", "title": "Total Processed", "description": "Input rows answered so far.", "examples": [ 500 ] }, "limit": { "type": "integer", "title": "Limit", "description": "Page size used for this response.", "examples": [ 50 ] }, "offset": { "type": "integer", "title": "Offset", "description": "Row offset into the ordered result set.", "examples": [ 0 ] }, "results": { "items": { "$ref": "#/components/schemas/CompanyEnrichmentResultItem" }, "type": "array", "title": "Results", "description": "Per-row results in submit order: every input row, repeats included, with the URL as sent echoed in input_url." } }, "type": "object", "required": [ "job_id", "total_rows", "total_processed", "limit", "offset", "results" ], "title": "CompanyBulkResultsResponse", "description": "Paginated results for a bulk company-enrichment job.", "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "total_rows": 500, "total_processed": 500, "limit": 50, "offset": 0, "results": [] } }, "CompanyBulkStatusResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "Unique job identifier." }, "status": { "type": "string", "enum": [ "running", "completed" ], "title": "Status", "description": "Job status: running (still processing) or completed (all rows done).", "examples": [ "running" ] }, "total_rows": { "type": "integer", "title": "Total Rows", "description": "Total input rows submitted (repeats included; unique companies are what was charged).", "examples": [ 500 ] }, "total_processed": { "type": "integer", "title": "Total Processed", "description": "Input rows answered so far.", "examples": [ 237 ] }, "credits_consumed": { "type": "number", "title": "Credits Consumed", "description": "Credits deducted for this job: 1 credit per distinct input, charged once at submit and never refunded after acceptance. Failed rows stay charged; invalid rows were never charged.", "examples": [ 490.0 ] }, "summary": { "$ref": "#/components/schemas/CompanyBulkSummary", "description": "Per-outcome counts." }, "created_at": { "type": "string", "title": "Created At", "description": "Job submission timestamp (UTC)." }, "finished_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finished At", "description": "Timestamp of the last processed row (UTC). Null while running." } }, "type": "object", "required": [ "job_id", "status", "total_rows", "total_processed", "credits_consumed", "summary", "created_at" ], "title": "CompanyBulkStatusResponse", "description": "Status snapshot of a bulk company-enrichment job.", "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "status": "running", "total_rows": 500, "total_processed": 237, "credits_consumed": 490.0, "summary": { "total_found": 198, "total_not_found": 29, "total_error": 10, "total_invalid_url": 5 }, "created_at": "2026-09-25T14:30:00Z" } }, "CompanyBulkSubmitRequest": { "properties": { "input": { "items": { "$ref": "#/components/schemas/CompanyBulkInputRow" }, "type": "array", "maxItems": 100000, "minItems": 1, "title": "Input", "description": "Companies to enrich, one row each: a LinkedIn company/showcase URL (preferred) or a website domain. Repeats of the same input are charged once but each comes back as its own result row, in order. Maximum 100,000 rows per submission." } }, "type": "object", "required": [ "input" ], "title": "CompanyBulkSubmitRequest", "description": "Submission payload for POST /v1/company-enrichment/bulk.", "example": { "input": [ { "linkedin_url": "https://www.linkedin.com/company/kearney" }, { "linkedin_url": "https://www.linkedin.com/company/maple-inc" } ] } }, "CompanyBulkSubmitResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "Unique job identifier. Pass this to GET /v1/company-enrichment/bulk/{job_id} to poll status." }, "status": { "type": "string", "enum": [ "submitted" ], "const": "submitted", "title": "Status", "description": "Submission acknowledgement status.", "examples": [ "submitted" ] }, "total_rows": { "type": "integer", "title": "Total Rows", "description": "Number of rows submitted, duplicates and invalid rows included.", "examples": [ 500 ] }, "total_invalid": { "type": "integer", "title": "Total Invalid", "description": "Input rows that were skipped at submit (a numeric-ID or malformed URL, a name over 200 characters, a domain cell that is not a website domain, or a blank row), repeats included. They cost nothing and appear in results as invalid_url.", "examples": [ 10 ] }, "credits_consumed": { "type": "number", "title": "Credits Consumed", "description": "Credits deducted for this submission: 1 credit per distinct input (a LinkedIn URL and a domain for the same company are two inputs), charged once per job. Repeats of the same input and invalid rows are not charged.", "examples": [ 490.0 ] } }, "type": "object", "required": [ "job_id", "status", "total_rows", "total_invalid", "credits_consumed" ], "title": "CompanyBulkSubmitResponse", "description": "Response when submitting a bulk company-enrichment job.", "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "status": "submitted", "total_rows": 500, "total_invalid": 10, "credits_consumed": 490.0 } }, "CompanyBulkSummary": { "properties": { "total_found": { "type": "integer", "title": "Total Found", "description": "Input rows where a company record was returned (repeats included).", "examples": [ 420 ] }, "total_not_found": { "type": "integer", "title": "Total Not Found", "description": "Input rows that were read (a company URL or a website domain) but no company matches them (repeats included).", "examples": [ 70 ] }, "total_error": { "type": "integer", "title": "Total Error", "description": "Input rows our infrastructure could not answer (repeats included).", "examples": [ 10 ] }, "total_invalid_url": { "type": "integer", "title": "Total Invalid Url", "description": "Input rows skipped at submit (a numeric-ID or malformed URL, a name over 200 characters, a domain cell that is not a website domain, or a blank row), repeats included. Counted as processed and charged nothing.", "examples": [ 10 ] } }, "type": "object", "required": [ "total_found", "total_not_found", "total_error", "total_invalid_url" ], "title": "CompanyBulkSummary", "description": "Per-outcome counts for a bulk company-enrichment job." }, "CompanyEnrichmentResponse": { "properties": { "result": { "type": "string", "enum": [ "found", "not_found" ], "title": "Result", "description": "found (a company record is returned) or not_found (no company matches the URL or the domain; all data fields are null)." }, "input": { "type": "string", "title": "Input", "description": "The linkedin_url or domain you sent, verbatim.", "examples": [ "https://www.linkedin.com/company/kearney" ] }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Url", "description": "The company's LinkedIn URL, normalized. Null when a search by domain finds no company.", "examples": [ "https://www.linkedin.com/company/kearney" ] }, "linkedin_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Linkedin Id", "description": "Stable numeric company ID. Null for not_found.", "examples": [ 2196 ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Company name.", "examples": [ "Kearney" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Full company description (not truncated)." }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website", "description": "Website the company lists.", "examples": [ "https://www.kearney.com/" ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "The company's website domain. Null when the company has no website of its own.", "examples": [ "kearney.com" ] }, "email_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Domain", "description": "The domain the company hosts its email on. Null when there's no domain.", "examples": [ "kearney.com" ] }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Industry", "description": "Industry label.", "examples": [ "Business Consulting and Services" ] }, "company_size": { "anyOf": [ { "$ref": "#/components/schemas/CompanySizeBucket" }, { "type": "null" } ], "description": "The company's self-reported headcount range." }, "employee_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Employee Count", "description": "Estimated headcount.", "examples": [ 7548 ] }, "company_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Type", "description": "Company type (Privately held, Public company, \u2026).", "examples": [ "Partnership" ] }, "headquarters": { "anyOf": [ { "$ref": "#/components/schemas/CompanyHeadquarters" }, { "type": "null" } ], "description": "Headquarters location." }, "founded_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Founded Year", "description": "Year founded.", "examples": [ 1926 ] }, "specialties": { "items": { "type": "string" }, "type": "array", "title": "Specialties", "description": "Specialties the company lists. Empty when unknown.", "examples": [ [ "Management Consulting" ] ] }, "follower_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Follower Count", "description": "Exact follower count.", "examples": [ 694285 ] }, "similar_companies": { "items": { "$ref": "#/components/schemas/SimilarCompany" }, "type": "array", "title": "Similar Companies", "description": "Companies similar to this one. Empty when unknown." }, "is_redirect": { "type": "boolean", "title": "Is Redirect", "description": "Searches by domain: true when the domain you sent redirects to another website. Always false for a search by LinkedIn URL.", "default": false, "examples": [ false ] }, "redirected_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redirected To", "description": "Searches by domain: the website domain your domain redirects to, or null. Always null for a search by LinkedIn URL.", "examples": [ null ] }, "credits_consumed": { "type": "number", "title": "Credits Consumed", "description": "Credits charged for this attempt (1).", "examples": [ 1.0 ] } }, "type": "object", "required": [ "result", "input", "credits_consumed" ], "title": "CompanyEnrichmentResponse", "description": "Enriched public record for a company, by LinkedIn URL or website domain.", "example": { "result": "found", "input": "https://www.linkedin.com/company/kearney", "linkedin_url": "https://www.linkedin.com/company/kearney", "linkedin_id": 2196, "name": "Kearney", "description": "As one of the original firms, we've never lost sight\u2026", "website": "https://www.kearney.com/", "domain": "kearney.com", "email_domain": "kearney.com", "industry": "Business Consulting and Services", "company_size": { "label": "5,001-10,000 employees", "min": 5001, "max": 10000 }, "employee_count": 7548, "company_type": "Partnership", "headquarters": { "text": "Chicago, Illinois", "city": "Chicago", "region": "Illinois", "country": "US" }, "founded_year": 1926, "specialties": [ "Management Consulting" ], "follower_count": 694285, "similar_companies": [ { "name": "Oliver Wyman", "linkedin_url": "https://www.linkedin.com/company/oliver-wyman", "industry": "Business Consulting and Services", "location": "New York, NY" } ], "is_redirect": false, "credits_consumed": 1.0 } }, "CompanyEnrichmentResultItem": { "properties": { "result": { "type": "string", "enum": [ "found", "not_found", "error", "invalid_url", "pending" ], "title": "Result", "description": "found | not_found (definitive answers), error (OrbiSearch could not answer this row), invalid_url (we skipped the row at submit: a numeric-ID or malformed URL, a name over 200 characters, a domain cell that is not a website domain, or a blank row) or pending (the row is not answered yet; poll again). found/not_found/error are charged 1 credit; invalid_url and repeats cost 0; pending rows are charged once, on the first row of that input." }, "input": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Input", "description": "The linkedin_url or domain exactly as submitted for this row. Results return every input row in submit order, repeats included, so this is what to match against your own rows.", "examples": [ "linkedin.com/company/kearney" ] }, "input_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Input Url", "description": "The linkedin_url exactly as submitted for this row; null on a row submitted by domain (see input).", "examples": [ "linkedin.com/company/kearney" ] }, "is_redirect": { "type": "boolean", "title": "Is Redirect", "description": "Rows submitted by domain: true when that domain redirects to another website. Always false for a LinkedIn URL row.", "default": false, "examples": [ false ] }, "redirected_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redirected To", "description": "Rows submitted by domain: the website domain it redirects to, or null. Always null for a LinkedIn URL row.", "examples": [ null ] }, "credits_consumed": { "type": "number", "title": "Credits Consumed", "description": "Credits charged for this row: 1 on the first row of each distinct input (found, not_found and error alike), 0 on a repeat of the same input and 0 on an invalid_url row we skipped at submit. Nothing is refunded after the job is accepted.", "examples": [ 1.0 ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "One-line explanation of why a row was skipped. Non-null only for result=invalid_url; null on every other row.", "examples": [ "Numeric company URLs are not supported. Use the company's name URL, e.g. linkedin.com/company/kearney." ] }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Url", "description": "The company's LinkedIn URL, normalized from the input. Null for an invalid_url row (no company could be read from it).", "examples": [ "https://www.linkedin.com/company/kearney" ] }, "linkedin_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Linkedin Id", "description": "Stable numeric company ID. Null unless found.", "examples": [ 2196 ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Company name.", "examples": [ "Kearney" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Full company description (not truncated)." }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website", "description": "Website the company lists.", "examples": [ "https://www.kearney.com/" ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "The company's website domain. Null when not found or when the company has no website of its own.", "examples": [ "kearney.com" ] }, "email_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Domain", "description": "The domain the company hosts its email on. Null when there's no domain.", "examples": [ "kearney.com" ] }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Industry", "description": "Industry label.", "examples": [ "Business Consulting and Services" ] }, "company_size": { "anyOf": [ { "$ref": "#/components/schemas/CompanySizeBucket" }, { "type": "null" } ], "description": "The company's self-reported headcount range." }, "employee_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Employee Count", "description": "Estimated headcount.", "examples": [ 7548 ] }, "company_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Type", "description": "Company type.", "examples": [ "Partnership" ] }, "headquarters": { "anyOf": [ { "$ref": "#/components/schemas/CompanyHeadquarters" }, { "type": "null" } ], "description": "Headquarters location." }, "founded_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Founded Year", "description": "Year founded.", "examples": [ 1926 ] }, "specialties": { "items": { "type": "string" }, "type": "array", "title": "Specialties", "description": "Specialties the company lists. Empty when unknown." }, "follower_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Follower Count", "description": "Exact follower count.", "examples": [ 694285 ] }, "similar_companies": { "items": { "$ref": "#/components/schemas/SimilarCompany" }, "type": "array", "title": "Similar Companies", "description": "Companies similar to this one. Empty when unknown." } }, "type": "object", "required": [ "result", "credits_consumed" ], "title": "CompanyEnrichmentResultItem", "description": "One row of a bulk company enrichment job, in submit order.\n\nCarries the same data fields as the single company enrichment response, plus\ninput_url and reason." }, "CompanyHeadquarters": { "properties": { "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Display form of the location.", "examples": [ "Chicago, Illinois" ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City", "description": "City.", "examples": [ "Chicago" ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region", "description": "State or region.", "examples": [ "Illinois" ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "ISO 3166-1 alpha-2 country code.", "examples": [ "US" ] } }, "type": "object", "title": "CompanyHeadquarters", "description": "A company's headquarters location." }, "CompanySizeBucket": { "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "Headcount range label.", "examples": [ "5,001-10,000 employees" ] }, "min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Min", "description": "Lower bound of the bucket, inclusive.", "examples": [ 5001 ] }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max", "description": "Upper bound of the bucket, inclusive.", "examples": [ 10000 ] } }, "type": "object", "title": "CompanySizeBucket", "description": "The company's self-reported headcount range." }, "ContentSpamCheckRequest": { "properties": { "content": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "Content", "description": "Plain-text email body to analyse. Cold email is plain text in practice; HTML is not required." }, "subject": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Subject", "description": "Optional subject line. When provided, it is included in the analysis." } }, "type": "object", "required": [ "content" ], "title": "ContentSpamCheckRequest", "description": "Email copy to analyse for spam-filter triggers.", "example": { "content": "ACT NOW!! This EXCLUSIVE offer expires TONIGHT. Guaranteed to DOUBLE your revenue and make you $50,000 fast. Click here to claim your FREE spot!!!", "subject": "URGENT: claim your spot before midnight" } }, "ContentSpamCheckResponse": { "properties": { "score": { "type": "number", "title": "Score", "description": "Total SpamAssassin score for the copy. Higher means more spam-like.", "examples": [ 2.6 ] }, "threshold": { "type": "number", "title": "Threshold", "description": "Score at or above which mail is treated as spam (SpamAssassin default is 5.0).", "examples": [ 5.0 ] }, "verdict": { "type": "string", "title": "Verdict", "description": "Overall assessment: `clean` (well below threshold), `borderline` (approaching threshold), or `likely_flagged` (at or above threshold).", "examples": [ "borderline" ] }, "rules": { "items": { "$ref": "#/components/schemas/SpamRule" }, "type": "array", "title": "Rules", "description": "Content rules that fired, highest-scoring first. Empty when nothing triggered." } }, "type": "object", "required": [ "score", "threshold", "verdict", "rules" ], "title": "ContentSpamCheckResponse", "description": "SpamAssassin analysis of the submitted email copy.", "example": { "score": 2.6, "threshold": 5.0, "verdict": "borderline", "rules": [ { "name": "MONEY_NOHTML", "points": 2.5, "description": "Plain-text message focused on large sums of money" }, { "name": "ACT_NOW_CAPS", "points": 0.1, "description": "Talks about 'acting now' with capitals" } ] } }, "CreditsResponse": { "properties": { "credits": { "type": "number", "title": "Credits", "description": "Current available credits.", "examples": [ 1250.5 ] }, "user_id": { "type": "string", "title": "User Id", "description": "Clerk-issued user identifier (e.g., user_xxx).", "examples": [ "user_2NXKxQjF8KhZHwH3JqRpYXxV" ] } }, "type": "object", "required": [ "credits", "user_id" ], "title": "CreditsResponse", "description": "Current credit balance information.", "example": { "credits": 1250.5, "user_id": "user_2NXKxQjF8KhZHwH3JqRpYXxV" } }, "EmailLookupFoundEmail": { "properties": { "email": { "type": "string", "title": "Email", "description": "The email address found for this person.", "examples": [ "jane.doe@acme.com" ] }, "job_order": { "type": "integer", "title": "Job Order", "description": "The email's position in this list, starting at 1.", "examples": [ 1 ] }, "company_linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Linkedin Url", "description": "LinkedIn URL of the employer the email belongs to.", "examples": [ "https://www.linkedin.com/company/acme" ] }, "email_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Domain", "description": "Domain of the returned email address.", "examples": [ "acme.com" ] } }, "type": "object", "required": [ "email", "job_order" ], "title": "EmailLookupFoundEmail", "description": "One work email returned for a search by LinkedIn profile URL." }, "EmailLookupRequest": { "properties": { "first_name": { "type": "string", "maxLength": 255, "title": "First Name", "description": "Person's first name. Optional individually, but provide at least one of first or last name.", "default": "", "examples": [ "Jane" ] }, "last_name": { "type": "string", "maxLength": 255, "title": "Last Name", "description": "Person's last name. Optional individually, but provide at least one of first or last name.", "default": "", "examples": [ "Doe" ] }, "domain": { "type": "string", "maxLength": 255, "title": "Domain", "description": "Company domain to search within. Required unless a linkedin_url is provided.", "default": "", "examples": [ "acme.com" ] }, "linkedin_url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Linkedin Url", "description": "LinkedIn profile URL to find a work email for. Provide this instead of first_name, last_name and domain.", "examples": [ "https://www.linkedin.com/in/jane-doe" ] }, "timeout": { "type": "integer", "maximum": 97.0, "minimum": 30.0, "title": "Timeout", "description": "Search timeout in seconds (30\u201397).", "default": 97, "examples": [ 97 ] } }, "type": "object", "title": "EmailLookupRequest", "description": "Find a deliverable email from a LinkedIn profile URL, or a name and company domain.", "example": { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com", "timeout": 97 } }, "EmailLookupResponse": { "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "The first name searched. Null when the request supplied none and none could be determined.", "examples": [ "Jane" ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "The last name searched. Null when the request supplied none and none could be determined.", "examples": [ "Doe" ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "The company's website domain. Null when the request supplied none and none could be determined.", "examples": [ "acme.com" ] }, "email_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Domain", "description": "The domain searched for the email address. Null when the request supplied no domain.", "examples": [ "acme.com" ] }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Url", "description": "The LinkedIn profile URL this result is for. Null for a request that did not supply one.", "examples": [ "https://www.linkedin.com/in/jane-doe" ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "The deliverable email address discovered for this person at this domain. Null when no deliverable address could be confirmed.", "examples": [ "jane.doe@acme.com" ] }, "status": { "type": "string", "enum": [ "safe", "unknown" ], "pattern": "^(safe|unknown)$", "title": "Status", "description": "Search status: safe (a deliverable address was found and is in the email field) or unknown (no deliverable address was found, or the search timed out; the email field is null).", "examples": [ "safe" ] }, "substatus": { "anyOf": [ { "type": "string", "pattern": "^(deliverable|no_address_found|timeout|profile_not_found|no_current_employer|no_company_website|invalid_linkedin_url|temporarily_unavailable)$" }, { "type": "null" } ], "enum": [ "deliverable", "no_address_found", "timeout", "profile_not_found", "no_current_employer", "no_company_website", "invalid_linkedin_url", "temporarily_unavailable" ], "title": "Substatus", "description": "Specific reason for the status. deliverable: a deliverable address was found (only with status=safe). no_address_found: no deliverable address was found for this person at this domain. profile_not_found: the URL supplied is a correctly formed LinkedIn profile URL but not a valid profile, for example mistyped or no longer in use. no_current_employer: we couldn't identify a current employer for this person. no_company_website: the person has a current employer, but we couldn't identify a company website for it, so there was no domain to search; if you know the company's website, search for the person by name and domain instead. invalid_linkedin_url: the value supplied is not a LinkedIn profile URL at all, for example a company page URL or plain text (bulk only; a single search rejects such a URL with 422). temporarily_unavailable: we could not complete this search and the row should be resubmitted. timeout: the caller's `timeout` parameter exhausted before the search completed (only returned from /v1/email-lookup, never from /v1/bulk-lookup, since bulk searches have no caller-tunable timeout). Every substatus is billable except invalid_linkedin_url, which costs nothing: a submit is only refunded when OrbiSearch cannot accept the submission itself.", "examples": [ "deliverable" ] }, "explanation": { "type": "string", "title": "Explanation", "description": "Plain-English explanation of the search result.", "examples": [ "Safe to email. The mailbox exists and is deliverable." ] }, "confidence": { "anyOf": [ { "type": "integer", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Confidence", "description": "How certain we are in the verdict on a 0\u2013100 scale. See EmailVerificationResponse.confidence for the full scale.", "examples": [ 99 ] }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Full Name", "description": "The person's full name. Null for a search by name and domain, or when it could not be determined.", "examples": [ "Jane Doe" ] }, "employer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Employer Name", "description": "The person's current employer. Null for a search by name and domain, or when it could not be determined.", "examples": [ "Acme" ] }, "employer_linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Employer Linkedin Url", "description": "LinkedIn URL of the person's current employer. Null for a search by name and domain, or when it could not be determined.", "examples": [ "https://www.linkedin.com/company/acme" ] }, "all_emails": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EmailLookupFoundEmail" }, "type": "array" }, { "type": "null" } ], "title": "All Emails", "description": "Every work email found for this person. Null for a search by name and domain." }, "email_provider": { "type": "string", "title": "Email Provider", "description": "Email service provider of the returned address (Google Workspace, Microsoft Outlook, etc.).", "examples": [ "Google Workspace" ] }, "mx_record": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mx Record", "description": "The main mail server the domain uses to receive email. Null if the domain has no mail server configured.", "examples": [ "aspmx.l.google.com" ] }, "is_domain_catch_all": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Domain Catch All", "description": "True if the domain accepts mail for any username (catch-all). Null if we could not determine whether the domain is catch-all.", "examples": [ false ] }, "is_secure_email_gateway": { "type": "boolean", "title": "Is Secure Email Gateway", "description": "True if the domain is protected by a secure email gateway: Proofpoint, Mimecast, Barracuda, or Trend Micro.", "default": false, "examples": [ false ] }, "is_disposable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Disposable", "description": "True if this is a temporary/disposable email service, false if not, null if unknown.", "examples": [ false ] }, "is_role_account": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Role Account", "description": "True if this is a generic role-based email (info@, support@, etc.), false if not, null if unknown.", "examples": [ false ] }, "is_free": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Free", "description": "True if this is from a free email provider (gmail.com, yahoo.com, etc.), false if not, null if unknown.", "examples": [ false ] }, "credits_consumed": { "type": "integer", "title": "Credits Consumed", "description": "Credits charged for this search: 1 on pay-as-you-go keys, 0 on unlimited plans (no credits move).", "examples": [ 1 ] } }, "type": "object", "required": [ "status", "explanation", "email_provider", "credits_consumed" ], "title": "EmailLookupResponse", "description": "Email finder result: the best deliverable email found for a LinkedIn profile URL or a (first_name, last_name, domain).", "example": { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com", "email_domain": "acme.com", "linkedin_url": "https://www.linkedin.com/in/jane-doe", "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "confidence": 99, "full_name": "Jane Doe", "employer_name": "Acme", "employer_linkedin_url": "https://www.linkedin.com/company/acme", "all_emails": [ { "company_linkedin_url": "https://www.linkedin.com/company/acme", "email": "jane.doe@acme.com", "email_domain": "acme.com", "job_order": 1 } ], "email_provider": "Google Workspace", "mx_record": "aspmx.l.google.com", "is_domain_catch_all": false, "is_secure_email_gateway": false, "is_disposable": false, "is_role_account": false, "is_free": false, "credits_consumed": 1 } }, "EmailVerificationResponse": { "properties": { "email": { "type": "string", "title": "Email", "description": "The email address that was verified.", "examples": [ "jane.doe@acme.com" ] }, "status": { "type": "string", "enum": [ "safe", "risky", "invalid", "unknown" ], "pattern": "^(safe|risky|invalid|unknown)$", "title": "Status", "description": "Overall verification status: safe (deliverable), risky (uncertain), invalid (undeliverable), unknown (verification failed).", "examples": [ "safe" ] }, "substatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Substatus", "description": "Specific reason for the status (e.g., deliverable, catch_all, policy_blocked, mailbox_not_found, invalid_syntax, greylisted, timeout).", "examples": [ "deliverable" ] }, "explanation": { "type": "string", "title": "Explanation", "description": "Plain-English explanation of the verification result.", "examples": [ "Safe to email. The mailbox exists and is deliverable." ] }, "email_provider": { "type": "string", "title": "Email Provider", "description": "Email service provider (Google Workspace, Gmail, Microsoft Outlook, etc.).", "examples": [ "Google Workspace" ] }, "mx_record": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mx Record", "description": "The main mail server the domain uses to receive email. Null if the domain has no mail server configured. When that happens, `substatus` will be `no_mx_records`.", "examples": [ "aspmx.l.google.com" ] }, "is_domain_catch_all": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Domain Catch All", "description": "True if the domain accepts mail for any username (catch-all). Null if we could not determine whether the domain is catch-all.", "examples": [ false ] }, "is_secure_email_gateway": { "type": "boolean", "title": "Is Secure Email Gateway", "description": "True if the domain is protected by a secure email gateway: Proofpoint, Mimecast, Barracuda, or Trend Micro.", "default": false, "examples": [ false ] }, "is_disposable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Disposable", "description": "True if this is a temporary/disposable email service, false if not, null if unknown.", "examples": [ false ] }, "is_role_account": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Role Account", "description": "True if this is a generic role-based email (info@, support@, etc.), false if not, null if unknown.", "examples": [ false ] }, "is_free": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Free", "description": "True if this is from a free email provider (gmail.com, yahoo.com, etc.), false if not, null if unknown.", "examples": [ false ] }, "confidence": { "anyOf": [ { "type": "integer", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Confidence", "description": "How certain we are in the result, on a 0\u2013100 scale. Use it alongside `status` to tune how aggressively you filter. For `safe` results: 99 = deliverable, highest certainty; 98 = deliverable, but the domain sits behind a secure email gateway (Mimecast, Proofpoint, Barracuda, Trend Micro) that may still filter the message after accepting it; 97 = the address exists, but carries some risk of bouncing after acceptance. For `invalid` and `risky`, 99 means we are certain of the negative result. For `unknown`, 0. `null` when no score could be attached to the result. Treat that as unscored, not as low confidence.", "examples": [ 99 ] } }, "type": "object", "required": [ "email", "status", "explanation", "email_provider" ], "title": "EmailVerificationResponse", "description": "Verification result for a single email address.", "example": { "email": "jane.doe@acme.com", "status": "safe", "substatus": "deliverable", "explanation": "Safe to email. The mailbox exists and is deliverable.", "email_provider": "Google Workspace", "mx_record": "aspmx.l.google.com", "is_domain_catch_all": false, "is_secure_email_gateway": false, "is_disposable": false, "is_role_account": false, "is_free": false, "confidence": 99 } }, "SimilarCompany": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Company name.", "examples": [ "Oliver Wyman" ] }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Url", "description": "The company's LinkedIn URL.", "examples": [ "https://www.linkedin.com/company/oliver-wyman" ] }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Industry", "description": "Industry label.", "examples": [ "Business Consulting and Services" ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location", "description": "Display location, when given.", "examples": [ "New York, NY" ] } }, "type": "object", "title": "SimilarCompany", "description": "A company similar to this one." }, "SpamRule": { "properties": { "name": { "type": "string", "title": "Name", "description": "The SpamAssassin rule name that matched.", "examples": [ "MONEY_NOHTML" ] }, "points": { "type": "number", "title": "Points", "description": "Points this rule added to the overall spam score.", "examples": [ 2.5 ] }, "description": { "type": "string", "title": "Description", "description": "Plain-English explanation of what the rule detects.", "examples": [ "Plain-text message focused on large sums of money" ] } }, "type": "object", "required": [ "name", "points", "description" ], "title": "SpamRule", "description": "A single SpamAssassin rule that fired on the submitted copy." }, "UnlimitedUsageResponse": { "properties": { "single_monthly_cap": { "type": "integer", "title": "Single Monthly Cap", "description": "Plan's single search requests per billing period." }, "single_used": { "type": "integer", "title": "Single Used", "description": "Single search requests consumed this billing period." }, "single_remaining": { "type": "integer", "title": "Single Remaining", "description": "Requests remaining before the monthly cap (never negative)." }, "single_rps": { "type": "integer", "title": "Single Rps", "description": "Plan's single search requests-per-second limit (per account)." }, "bulk_searches_per_day": { "type": "integer", "title": "Bulk Searches Per Day", "description": "Plan's daily bulk search limit (per account, UTC day)." }, "bulk_searches_used_today": { "type": "integer", "title": "Bulk Searches Used Today", "description": "Bulk searches consumed in the current daily window." }, "bulk_searches_reset_at": { "type": "string", "format": "date-time", "title": "Bulk Searches Reset At", "description": "When the daily bulk search limit resets (next UTC midnight)." }, "current_period_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Current Period Start", "description": "Start of the current billing period (cap window)." }, "current_period_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Current Period End", "description": "End of the current billing period, when the cap resets." } }, "type": "object", "required": [ "single_monthly_cap", "single_used", "single_remaining", "single_rps", "bulk_searches_per_day", "bulk_searches_used_today", "bulk_searches_reset_at", "current_period_start", "current_period_end" ], "title": "UnlimitedUsageResponse", "description": "Current-period consumption for an unlimited plan (/v1/unlimited/usage).", "example": { "single_monthly_cap": 100000, "single_used": 4211, "single_remaining": 95789, "single_rps": 10, "bulk_searches_per_day": 10000, "bulk_searches_used_today": 2500, "bulk_searches_reset_at": "2026-07-29T00:00:00Z", "current_period_start": "2026-07-01T00:00:00Z", "current_period_end": "2026-08-01T00:00:00Z" } }, "ValidationErrorDetail": { "properties": { "loc": { "type": "string", "title": "Loc", "description": "Where in the request the problem is, as a dot-separated path (e.g. `query.email`, `body.0`).", "examples": [ "query.email" ] }, "msg": { "type": "string", "title": "Msg", "description": "Human-readable description of this validation error.", "examples": [ "Missing required query parameter: email." ] }, "type": { "type": "string", "title": "Type", "description": "Machine-readable error category (e.g. `missing`, `less_than_equal`, `string_too_long`).", "examples": [ "missing" ] } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationErrorDetail", "description": "One request-validation failure." } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "API key for authentication", "in": "header", "name": "X-API-Key" } } }, "security": [ { "ApiKeyAuth": [] } ] }