{"openapi":"3.1.0","info":{"title":"ProspectChief API","version":"1.3.0","description":"Programmatic access to ProspectChief account data: projects, saved Maps businesses, Extractor contacts, imports and email verification. Live map/page capture happens in the browser extensions and is not exposed as a server-side scraping API.","contact":{"url":"https://prospectchief.com/contact/"}},"servers":[{"url":"https://app.prospectchief.com/api/v1","description":"ProspectChief API v1"}],"tags":[{"name":"Account","description":"Plan, credits, entitlements and devices for the API key owner."},{"name":"Projects","description":"Projects group leads. Purpose `leads` (Extractor) or `maps` (Maps businesses). Free accounts have a project quota per purpose (see `project_limit_reached`)."},{"name":"Maps businesses","description":"Businesses saved from Bing Maps / Google Maps by the ProspectChief extensions. The API reads, filters, saves and enriches saved businesses; live map capture is extension-only."},{"name":"Extractor contacts","description":"Email contacts saved by the FreeEmailExtractor extension or via the API."},{"name":"Imports","description":"Large asynchronous contact imports in batches."},{"name":"Email verification","description":"Mail Intelligence (free) and metered mailbox verification. Credits are shared across products."},{"name":"Credits","description":"How verification credits are previewed, reserved, charged and reused."}],"x-scopes":{"account":"Account data: projects, businesses, contacts, imports, exports, verification previews and job status.","email_validate":"Operations that can spend verification credits: /validate, /validate/batch, creating project verification jobs."},"x-extension-only":["POST /auth/extension/exchange","POST /extension/events","POST /businesses/collect","POST /businesses/{business}/emails/reveal","POST /checkout/intents","GET /admission-policy","POST /mx/observe","GET /mx/providers","GET /mx/registry","POST /public/contact","POST /public/mx/resolve","GET /public/pricing","POST /public/url-extract","POST /public/url-extract/authorize","GET /contacts/activity"],"x-rate-limits":{"account":"180 requests per minute per API key","validation":"named limiter `validation-api` (per key); 429 with Retry-After"},"paths":{"/account":{"get":{"tags":["Account"],"summary":"Account, plan, credits, entitlements and devices","operationId":"getAccount","security":[{"bearerAuth":[]}],"x-scope":"account","x-credits":"none","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/businesses":{"get":{"tags":["Maps businesses"],"summary":"List saved businesses (paginated, filterable)","operationId":"listBusinesses","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"project_id","in":"query","schema":{"type":"integer"}},{"name":"platform","in":"query","schema":{"type":"string","enum":["bing_maps","google_maps"]}},{"name":"has_email","in":"query","schema":{"type":"boolean"}},{"name":"enrichment_status","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","description":"Matches name, website domain or locality","schema":{"type":"string","maxLength":120}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"source_place_ids","in":"query","description":"Extension lookup mode (\u226450 comma-separated platform ids). When present the legacy `{ok, businesses[]}` shape is returned.","schema":{"type":"string"}}],"responses":{"200":{"description":"Business page","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Business"}},"meta":{"$ref":"#/components/schemas/PageMeta"},"email_visibility":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/businesses/{business}":{"get":{"tags":["Maps businesses"],"summary":"Business detail","operationId":"getBusiness","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"business","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Business","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Business"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/contacts":{"get":{"tags":["Extractor contacts"],"summary":"List contacts","operationId":"listContacts","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"project_id","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Extractor contacts"],"summary":"Save contacts (\u22641000 per request)","operationId":"saveContacts","security":[{"bearerAuth":[]}],"x-scope":"account","description":"Exclusion rules (Settings \u2192 Exclusions) are applied server-side; skipped rows are counted under `rejected_by_reason.user_exclusion`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contacts"],"properties":{"project_id":{"type":"integer"},"project_ids":{"type":"array","items":{"type":"integer"}},"contacts":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/ContactInput"}}}}}}},"responses":{"200":{"description":"Save summary","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/contacts/mail-summary":{"get":{"tags":["Extractor contacts"],"summary":"Domain Mail Ready aggregates","operationId":"contactsMailSummary","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project_id","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/contacts/{contact}":{"patch":{"tags":["Extractor contacts"],"summary":"Update a contact","operationId":"updateContact","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"contact","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Extractor contacts"],"summary":"Delete a contact","operationId":"deleteContact","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"contact","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/devices":{"get":{"tags":["Account"],"summary":"Connected extension devices","operationId":"listDevices","security":[{"bearerAuth":[]}],"x-scope":"account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/devices/{device}":{"delete":{"tags":["Account"],"summary":"Disconnect a device","operationId":"deleteDevice","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"device","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/entitlements":{"get":{"tags":["Account"],"summary":"Alias of GET /account","operationId":"getEntitlements","security":[{"bearerAuth":[]}],"x-scope":"account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/imports":{"post":{"tags":["Imports"],"summary":"Open an async import","operationId":"createImport","security":[{"bearerAuth":[]}],"x-scope":"account","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"type":"integer"},"project_ids":{"type":"array","items":{"type":"integer"}},"expected_total":{"type":"integer"}}}}}},"responses":{"201":{"description":"Import job","content":{"application/json":{"schema":{"type":"object"}}}},"200":{"description":"Import job","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/imports/{job}":{"get":{"tags":["Imports"],"summary":"Import status","operationId":"getImport","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"job","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/imports/{job}/batches":{"post":{"tags":["Imports"],"summary":"Append a batch (idempotent by batch_index)","operationId":"appendImportBatch","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"job","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contacts"],"properties":{"batch_index":{"type":"integer"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ContactInput"}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"`import_closed`"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/imports/{job}/complete":{"post":{"tags":["Imports"],"summary":"Close the import","operationId":"completeImport","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"job","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects":{"get":{"tags":["Projects"],"summary":"List projects","operationId":"listProjects","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"purpose","in":"query","description":"Default `leads`. Use `maps` for Maps projects or `all`.","schema":{"type":"string","enum":["leads","extractor","maps","all"]}}],"responses":{"200":{"description":"Project page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Projects"],"summary":"Create a project","operationId":"createProject","security":[{"bearerAuth":[]}],"x-scope":"account","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"purpose":{"type":"string","enum":["leads","maps"],"default":"leads"},"autosave":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"403":{"description":"`project_limit_reached` \u2014 quota for this purpose (Maps: Free 3 / Pro 100 by default) with `limit`, `used`, `upgrade_url`."},"401":{"$ref":"#/components/responses/Unauthenticated"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{project}":{"get":{"tags":["Projects"],"summary":"Project detail","operationId":"getProject","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"tags":["Projects"],"summary":"Rename / toggle autosave","operationId":"updateProject","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"autosave":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Projects"],"summary":"Delete (archive) a project","operationId":"deleteProject","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{project}/businesses":{"get":{"tags":["Maps businesses"],"summary":"Businesses saved on a Maps project (extension shape)","operationId":"listProjectBusinesses","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"`maps_project_required`"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Maps businesses"],"summary":"Save businesses to a Maps project","operationId":"saveProjectBusinesses","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}}],"description":"Upserts by platform id / identity. Businesses with a website are queued for website enrichment (contact-page email discovery) subject to plan limits. Empty email lists never remove existing emails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["businesses"],"properties":{"session_id":{"type":"string"},"session_name":{"type":"string"},"businesses":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/BusinessInput"}}}}}}},"responses":{"200":{"description":"Save summary (saved, updated, rejected_by_reason, enrichment)","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"`maps_project_required` or validation error"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{project}/businesses/enrich":{"post":{"tags":["Maps businesses"],"summary":"Queue website enrichment for businesses on a project","operationId":"enrichProjectBusinesses","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"business_ids":{"type":"array","items":{"type":"integer"}},"force":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{project}/businesses/{business}/enrich":{"post":{"tags":["Maps businesses"],"summary":"Queue website enrichment for one business","operationId":"enrichBusiness","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}},{"name":"business","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{project}/businesses/{business}/enrich/cancel":{"post":{"tags":["Maps businesses"],"summary":"Cancel pending enrichment","operationId":"cancelBusinessEnrichment","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}},{"name":"business","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{project}/contacts":{"get":{"tags":["Extractor contacts"],"summary":"Contacts on a project","operationId":"listProjectContacts","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Extractor contacts"],"summary":"Save contacts to a project","operationId":"saveProjectContacts","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contacts"],"properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ContactInput"}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{project}/contacts/{contact}":{"delete":{"tags":["Extractor contacts"],"summary":"Detach a contact from a project","operationId":"detachProjectContact","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}},{"name":"contact","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{project}/export":{"get":{"tags":["Projects"],"summary":"Export project contacts (CSV or XLSX)","operationId":"exportProject","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}},{"name":"format","in":"query","schema":{"type":"string","enum":["csv","xlsx"],"default":"csv"}}],"responses":{"200":{"description":"File download (`text/csv` with BOM, or XLSX)"},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{project}/verification":{"post":{"tags":["Email verification"],"summary":"Create (and start) a project verification job","operationId":"createProjectVerification","security":[{"bearerAuth":[]}],"x-scope":"account + email_validate","x-credits":"eligible contacts are reserved at start and settled per result; fresh results are reused free","description":"Requires an `Idempotency-Key` header. Replaying the same key returns the existing job (200) and never creates or charges twice. Exclusion rules, syntax/no-mail filters and the freshness window are applied by the planner before any credit is reserved.","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":120,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"force_reverify":{"type":"boolean","default":false},"start":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Job created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"replayed":{"type":"boolean"},"job":{"$ref":"#/components/schemas/VerificationJob"}}}}}},"200":{"description":"Idempotent replay \u2014 existing job returned"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"409":{"description":"`up_to_date` (all fresh; pass force_reverify) or `cannot_start`"},"422":{"description":"`idempotency_key_required`, `nothing_to_verify` or validation error"},"503":{"$ref":"#/components/responses/VerificationUnavailable"},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/projects/{project}/verification/preview":{"get":{"tags":["Email verification"],"summary":"Cost preview for verifying a project (nothing is created or charged)","operationId":"previewProjectVerification","security":[{"bearerAuth":[]}],"x-scope":"account","x-credits":"none","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"integer"}},{"name":"force_reverify","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Preview","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service_enabled":{"type":"boolean"},"preview":{"$ref":"#/components/schemas/VerificationPreview"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/validate":{"post":{"tags":["Email verification"],"summary":"Analyze one email (Mail Intelligence; optional metered mailbox verification)","operationId":"validateEmail","security":[{"bearerAuth":[]}],"x-scope":"email_validate","x-credits":"1 per new/stale mailbox check when mailbox_verification=true","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","maxLength":320},"mailbox_verification":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"$ref":"#/components/responses/InsufficientCredits"},"503":{"$ref":"#/components/responses/VerificationUnavailable"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/validate/batch":{"post":{"tags":["Email verification"],"summary":"Analyze up to 200 emails","operationId":"validateEmailBatch","security":[{"bearerAuth":[]}],"x-scope":"email_validate","x-credits":"1 per new/stale mailbox check when mailbox_verification=true","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","maxItems":200,"items":{"type":"string"}},"mailbox_verification":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"$ref":"#/components/responses/InsufficientCredits"},"503":{"$ref":"#/components/responses/VerificationUnavailable"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/verification/jobs":{"get":{"tags":["Email verification"],"summary":"List verification jobs","operationId":"listVerificationJobs","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"project_id","in":"query","schema":{"type":"integer"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/verification/jobs/{publicId}":{"get":{"tags":["Email verification"],"summary":"Verification job status","operationId":"getVerificationJob","security":[{"bearerAuth":[]}],"x-scope":"account","parameters":[{"name":"publicId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"job":{"$ref":"#/components/schemas/VerificationJob"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Settings \u2192 API keys. Keep it server-side; never ship it in browser JavaScript or an extension bundle."}},"responses":{"Unauthenticated":{"description":"Missing, revoked or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_authenticated","message":"Missing, revoked or expired API key"}}}},"Forbidden":{"description":"Key lacks the required scope, or the resource belongs to another account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"insufficient_scope","message":"Key lacks the required scope, or the resource belongs to another account"}}}},"NotFound":{"description":"Resource not found (also returned for resources owned by other accounts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"Resource not found (also returned for resources owned by other accounts)"}}}},"ValidationError":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object"}}}}}},"RateLimited":{"description":"Rate limited \u2014 back off exponentially and honour Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limited","message":"Rate limited \u2014 back off exponentially and honour Retry-After"}}}},"InsufficientCredits":{"description":"Not enough mailbox verification credits (response includes balance.available and balance.required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"insufficient_verification_balance","message":"Not enough mailbox verification credits (response includes balance.available and balance.required)"}}}},"VerificationUnavailable":{"description":"Mailbox verification is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"mailbox_verification_unavailable","message":"Mailbox verification is temporarily unavailable"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"PageMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"last_page":{"type":"integer"}}},"Account":{"type":"object","properties":{"ok":{"type":"boolean"},"email":{"type":"string"},"plan":{"type":"string"},"timezone":{"type":"string"},"verification":{"type":"object","properties":{"service_enabled":{"type":"boolean"},"available_credits":{"type":"integer"},"reserved_credits":{"type":"integer"},"total_credits":{"type":"integer"}}},"products":{"type":"object","description":"Per-product entitlement flags (e.g. fee, prospectchief)"},"entitlements":{"type":"object"},"devices":{"type":"object"}}},"Project":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string"},"purpose":{"type":"string","enum":["leads","maps"]},"type":{"type":"string"},"autosave":{"type":"boolean"},"contacts_count":{"type":"integer"},"businesses_count":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ContactInput":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"name":{"type":"string"},"company_name":{"type":"string"},"source_url":{"type":"string","format":"uri"},"source_type":{"type":"string"},"provider_id":{"type":"string"}}},"BusinessInput":{"type":"object","properties":{"name":{"type":"string"},"source_platform":{"type":"string","enum":["bing_maps","google_maps"]},"source_place_id":{"type":"string","description":"Stable platform id (`ypid:\u2026` for Bing, `cid:\u2026`/`place:\u2026` for Google)"},"source_url":{"type":"string"},"website_url":{"type":"string"},"phone_raw":{"type":"string"},"additional_phones":{"type":"array","items":{"type":"string"}},"category":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"full_address":{"type":"string"},"street":{"type":"string"},"locality":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"plus_code":{"type":"string"},"rating":{"type":"number"},"review_count":{"type":"integer"},"emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"source_url":{"type":"string"}}}}}},"Business":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"category":{"type":["string","null"]},"categories":{"type":"array","items":{"type":"string"}},"phone":{"type":["string","null"]},"additional_phones":{"type":"array","items":{"type":"string"}},"website_url":{"type":["string","null"]},"website_domain":{"type":["string","null"]},"address":{"type":"object","properties":{"full":{"type":["string","null"]},"street":{"type":["string","null"]},"locality":{"type":["string","null"]},"region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"plus_code":{"type":["string","null"]}}},"rating":{"type":["number","null"]},"review_count":{"type":["integer","null"]},"review_url":{"type":["string","null"]},"opening_hours":{"type":["object","string","null"]},"image_url":{"type":["string","null"]},"social_profiles":{"type":"array","items":{"type":"string"}},"source":{"type":"object","properties":{"platform":{"type":"string","enum":["bing_maps","google_maps",""]},"place_id":{"type":["string","null"]},"listing_url":{"type":["string","null"],"description":"Public listing link derived from the stable id; null when unknown"},"search_url":{"type":["string","null"],"description":"Search results URL the business was captured from; never synthesized"},"claim_status":{"type":"string"}}},"enrichment":{"type":"object","properties":{"status":{"type":["string","null"]},"error":{"type":["string","null"]}}},"emails":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"integer"},"email":{"type":"string"},"source_url":{"type":"string"},"discovery_method":{"type":"string"},"mailbox_status":{"type":["string","null"]},"mailbox_checked_at":{"type":["string","null"],"format":"date-time"}}}},"emails_hidden_count":{"type":"integer","description":"Emails locked by the Maps Free allowance; only opaque contact ids are returned"},"emails_locked":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"integer"}}}},"project_ids":{"type":"array","items":{"type":"integer"}},"first_discovered_at":{"type":["string","null"],"format":"date-time"},"last_discovered_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"VerificationPreview":{"type":"object","properties":{"total":{"type":"integer"},"already_verified_fresh":{"type":"integer"},"needs_verification":{"type":"integer"},"never_verified":{"type":"integer"},"stale":{"type":"integer"},"eligible":{"type":"integer"},"estimated_credits":{"type":"integer"},"reverify_estimated_credits":{"type":"integer"},"available_credits":{"type":"integer"},"excluded_not_charged":{"type":"integer"},"excluded_user":{"type":"integer"},"duplicates_collapsed":{"type":"integer"},"freshness_days":{"type":"integer"},"up_to_date":{"type":"boolean"},"can_start":{"type":"boolean"},"insufficient_credits":{"type":"boolean"}}},"VerificationJob":{"type":"object","properties":{"public_id":{"type":"string"},"project_id":{"type":["integer","null"]},"label":{"type":"string"},"status":{"type":"string","enum":["preparing","ready","queued","running","completed","completed_with_warnings","failed","cancelled","expired"]},"is_terminal":{"type":"boolean"},"eligible":{"type":"integer"},"submitted":{"type":"integer"},"resolved":{"type":"integer"},"percent":{"type":"integer"},"counts":{"type":"object"},"credits_reserved":{"type":"integer"},"credits_charged":{"type":"integer"},"queue_position":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"}}}}}}