{ "openapi": "3.1.0", "info": { "title": "Moleman API", "version": "2026-11-05", "summary": "Find and check business emails, search businesses in an area, write company summaries.", "description": "Docs: https://moleman.io/docs. Rate limit: 120 requests per minute per key. Every error: { error: { code, message, docs_url } }.", "contact": { "url": "https://moleman.io/docs" } }, "servers": [ { "url": "https://moleman.io" } ], "externalDocs": { "url": "https://moleman.io/docs", "description": "Guides, quickstart and examples" }, "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer mm_live_… (or mm_test_… for made-up test results)." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key", "revoked_api_key", "wrong_key_mode", "invalid_request", "invalid_json", "invalid_cursor", "invalid_webhook_url", "no_eligible_rows", "insufficient_credits", "not_found", "place_not_found", "route_not_found", "idempotency_in_progress", "payload_too_large", "unsupported_media_type", "idempotency_key_reused", "rate_limited", "server_error", "search_unavailable" ] }, "message": { "type": "string" }, "docs_url": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "code", "message", "docs_url" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } }, "paths": { "/api/v1/account": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "Your credits, plan and rate limit", "description": "Shows which key you are using, how many credits are left, your plan, the prices per result and your rate limit. A good first call to check that your key works.\n\n**Credits:** Free.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "livemode": { "type": "boolean" }, "key": { "type": "object", "properties": { "name": { "type": "string" }, "prefix": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] } }, "required": [ "name", "prefix", "mode" ], "additionalProperties": false }, "account": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email", "name" ], "additionalProperties": false }, "credits": { "type": "object", "properties": { "balance": { "type": "number", "description": "Credits left now." }, "planCredits": { "description": "Of these: plan credits (used first).", "type": [ "number", "null" ] }, "keptCredits": { "description": "Of these: credits that never expire (top-ups, bonus).", "type": [ "number", "null" ] } }, "required": [ "balance", "planCredits", "keptCredits" ], "additionalProperties": false }, "plan": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "period": { "type": "string", "enum": [ "monthly", "yearly" ] }, "status": { "type": "string" }, "creditsPerMonth": { "type": "number" }, "renewsAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "period", "status", "creditsPerMonth", "renewsAt" ], "additionalProperties": false }, { "type": "null" } ] }, "trial": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "status", "expiresAt" ], "additionalProperties": false }, { "type": "null" } ] }, "rateLimit": { "type": "object", "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "resetSeconds": { "type": "integer" }, "windowSeconds": { "type": "integer" } }, "required": [ "limit", "remaining", "resetSeconds", "windowSeconds" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "maxRowsPerRequest": { "type": "integer" }, "maxDeepSearchRows": { "type": "integer" }, "maxWaitSeconds": { "type": "integer" }, "maxPageSize": { "type": "integer" } }, "required": [ "maxRowsPerRequest", "maxDeepSearchRows", "maxWaitSeconds", "maxPageSize" ], "additionalProperties": false }, "prices": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "credits": { "type": "number" }, "charged": { "type": "string" } }, "required": [ "credits", "charged" ], "additionalProperties": false }, "description": "Credits per result, and when a result is charged." } }, "required": [ "livemode", "key", "account", "credits", "plan", "trial", "rateLimit", "limits", "prices" ], "additionalProperties": false }, "example": { "livemode": true, "key": { "name": "Clay", "prefix": "mm_live_Ab3x", "mode": "live" }, "account": { "email": "you@yourcompany.com", "name": "Sam" }, "credits": { "balance": 4210, "planCredits": 4000, "keptCredits": 210 }, "plan": { "id": "growth", "name": "Growth", "period": "monthly", "status": "active", "creditsPerMonth": 5000, "renewsAt": "2026-12-01T00:00:00.000Z" }, "trial": null, "rateLimit": { "limit": 120, "remaining": 119, "resetSeconds": 60, "windowSeconds": 60 }, "limits": { "maxRowsPerRequest": 50000, "maxDeepSearchRows": 10000, "maxWaitSeconds": 30, "maxPageSize": 1000 }, "prices": { "verify": { "credits": 0.1, "charged": "you only pay when the email works (bad or unclear emails are free)" }, "findEmail": { "credits": 1, "charged": "you only pay for emails that work (everything else is free)" } } } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/find-contacts": { "post": { "operationId": "findContacts", "tags": [ "Find emails" ], "summary": "Find emails for people or businesses", "description": "Finds and checks emails. `findEmail`: a named person at a business (first name, last name and website). `companyInbox`: the business email (info@, office@ …). `roleContact`: the owner, only when the business names the owner on its own website.\n\nSend up to 50,000 `rows` (or a `listId`). The job runs in the background: poll `GET /api/v1/jobs/{id}`, set `webhookUrl`, or send `wait` (up to 30 seconds) to get small jobs back finished.\n\nOnly emails that **Work** are delivered; the others come back with a plain reason and cost nothing.\n\n**Credits:** 1 credit per email that Works (you only pay for emails that work (everything else is free)). Not found, not sure or \"takes any name\" results are free. Rows your account already got an answer for in the last 30 days are answered again for free (`cached30d`).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID). A retry with the same key and body returns the first answer and is never charged twice. Kept 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "null when every row was answered from your last 30 days (free, nothing to wait for)." }, "listId": { "type": "integer" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "done", "cancelled", "failed" ] }, "livemode": { "type": "boolean" }, "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" }, "creditsCharged": { "type": "number", "description": "Credits this job used so far." }, "creditsHeld": { "type": "number", "description": "Credits still held while the job runs (what it does not use goes back)." }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": "integer" }, "finishedAt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "results": { "description": "Present when the job is already done (cached, test mode, or `wait`).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "jobTitle": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "Works", "Probably works", "Not sure", "On hold", "Still checking…" ] }, { "type": "null" } ], "description": "The app's word for the email. Only \"Works\" is charged." }, "resultCode": { "anyOf": [ { "type": "string", "enum": [ "verified", "likely", "more-volume", "check-paused", "checking" ] }, { "type": "null" } ] }, "resultMeaning": { "type": [ "string", "null" ] }, "emailStatus": { "anyOf": [ { "type": "string", "enum": [ "valid", "invalid", "catch-all", "unknown" ] }, { "type": "null" } ] }, "emailStatusText": { "description": "Works, Does not work, Takes any name, Not sure.", "type": [ "string", "null" ] }, "emailScore": { "type": [ "number", "null" ] }, "resolveStatus": { "anyOf": [ { "type": "string", "enum": [ "likely-valid", "likely-invalid", "unknown", "not-resolvable", "check-paused", "check-pending" ] }, { "type": "null" } ], "description": "For \"takes any name\" emails: how likely the address is real." }, "resolveStatusText": { "type": [ "string", "null" ] }, "findStatus": { "anyOf": [ { "type": "string", "enum": [ "found", "unconfirmed", "not-found", "needs-check", "checking" ] }, { "type": "null" } ] }, "findStatusText": { "type": [ "string", "null" ] }, "emailType": { "anyOf": [ { "type": "string", "enum": [ "business-inbox", "owner-published", "owner-guessed" ] }, { "type": "null" } ], "description": "Business searches: business inbox, owner email from their website, or owner email we found and checked." }, "emailTypeText": { "type": [ "string", "null" ] }, "briefText": { "type": [ "string", "null" ] }, "briefLine": { "type": [ "string", "null" ] }, "briefRelevance": { "type": [ "string", "null" ] }, "registryCompanyNumber": { "description": "Deep Search only (official company registry, GB and AU).", "type": [ "string", "null" ] }, "registryStatus": { "type": [ "string", "null" ] }, "registryIncorporatedOn": { "type": [ "string", "null" ] }, "registrySic": { "type": [ "string", "null" ] }, "directorNames": { "description": "Deep Search only. Never used to find or guess emails.", "type": [ "string", "null" ] }, "registrySource": { "type": [ "string", "null" ] }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Your own extra columns (phone, city, address …)." } }, "required": [ "id", "company", "domain", "firstName", "lastName", "fullName", "jobTitle", "email", "result", "resultCode", "resultMeaning", "emailStatus", "emailStatusText", "emailScore", "resolveStatus", "resolveStatusText", "findStatus", "findStatusText", "emailType", "emailTypeText", "briefText", "briefLine", "briefRelevance", "extra" ], "additionalProperties": false } }, "nextCursor": { "description": "More results: call again with cursor=.", "type": [ "string", "null" ] }, "queued": { "type": "integer", "description": "Rows that will be worked on." }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "reason", "count" ], "additionalProperties": false }, "description": "Rows that cannot run this action, and why." }, "cached30d": { "type": "integer", "description": "Rows answered for free from your own results of the last 30 days." }, "maxCreditsHeld": { "type": "number", "description": "The most this job can cost. Held now, the unused part goes back." }, "pollUrl": { "type": [ "string", "null" ] } }, "required": [ "jobId", "listId", "status", "livemode", "queued", "skipped", "cached30d", "maxCreditsHeld", "pollUrl" ], "additionalProperties": false }, "example": { "jobId": 981, "listId": 377, "action": "findEmail", "status": "done", "livemode": true, "total": 1, "done": 1, "failed": 0, "creditsCharged": 1, "creditsHeld": 0, "message": null, "createdAt": 1762344000000, "finishedAt": 1762344014000, "results": [ { "id": 4102, "company": "Bright Smile Dental", "domain": "brightsmiledental.com", "firstName": "Sarah", "lastName": "Miller", "fullName": "Sarah Miller", "jobTitle": null, "email": "sarah.miller@brightsmiledental.com", "result": "Works", "resultCode": "verified", "resultMeaning": "We checked it. This inbox is real, so you can send to it.", "emailStatus": "valid", "emailStatusText": "Works", "emailScore": 96, "resolveStatus": null, "resolveStatusText": null, "findStatus": "found", "findStatusText": "Found and checked", "emailType": null, "emailTypeText": null, "briefText": null, "briefLine": null, "briefRelevance": null, "extra": {} } ], "nextCursor": null, "queued": 1, "skipped": [], "cached30d": 0, "maxCreditsHeld": 1, "pollUrl": "/api/v1/jobs/981" } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_json`: The body is not valid JSON. `no_eligible_rows`: None of the rows can run this action (for example: no website or domain to find an email for, or no email to check). `invalid_webhook_url`: The webhook URL is not a public https address (private networks and other schemes are refused).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`insufficient_credits`: The account has fewer credits than this request could use at most. We hold the maximum while the job runs and give back what it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`wrong_key_mode`: A test key asked for something made with a live key, or the other way round. Test and live data never mix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: The job or list does not exist, belongs to another account, or was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`idempotency_in_progress`: A request with the same Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`idempotency_key_reused`: The Idempotency-Key was already used in the last 24 hours with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listId": { "description": "Run on a list you already have (from POST /api/v1/lists or a search) instead of `rows`.", "type": "integer", "exclusiveMinimum": 0 }, "contactIds": { "description": "With listId: only these rows (default: all rows of the list).", "maxItems": 50000, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0 } }, "name": { "description": "Name of the new list (shown in the app). Default: \"API ()\".", "type": "string", "maxLength": 120 }, "action": { "default": "findEmail", "description": "findEmail: a named person (first + last name + website). companyInbox: the business email (info@, office@ …). roleContact: the owner, only when the business names them on its own website.", "type": "string", "enum": [ "findEmail", "companyInbox", "roleContact" ] }, "rows": { "description": "Up to 50,000 rows.", "maxItems": 50000, "type": "array", "items": { "type": "object", "properties": { "company": { "description": "Business name.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "website": { "description": "Website (any form: https://acme.com, acme.com/contact, www.acme.com).", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "domain": { "description": "Domain, if you have it instead of a website.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "firstName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "fullName": { "description": "Used when first and last name are not given separately.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "jobTitle": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "email": { "description": "The email to check (verify).", "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "country": { "description": "Two-letter country code, e.g. US, CA, GB.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "address": { "description": "Business address. For US businesses it decides which state rules apply.", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] } } } }, "webhookUrl": { "description": "Public https URL we POST the result to when the job is done (see the webhooks guide).", "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "webhookSecret": { "description": "Optional: sign this webhook with your own secret instead of the account signing secret.", "anyOf": [ { "type": "string", "minLength": 8, "maxLength": 200 }, { "type": "null" } ] }, "wait": { "default": 0, "description": "Seconds to wait for the job to finish before answering (0–30). Handy for Zapier, Make and Clay: small jobs come back done, with results.", "type": "integer", "minimum": 0, "maximum": 30 } } }, "example": { "rows": [ { "firstName": "Sarah", "lastName": "Miller", "website": "https://brightsmiledental.com" } ], "wait": 20 } } } } } }, "/api/v1/verify": { "post": { "operationId": "verifyEmails", "tags": [ "Find emails" ], "summary": "Check if emails work", "description": "Checks each email with the mail server. \"Takes any name\" addresses (the server accepts everything) get a second check and come back as Probably works or Not sure. Send `emails`, `rows` with an `email` field, or a `listId`.\n\n**Credits:** 0.1 credits per email that Works (you only pay when the email works (bad or unclear emails are free)). Rows your account already got an answer for in the last 30 days are answered again for free (`cached30d`).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID). A retry with the same key and body returns the first answer and is never charged twice. Kept 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "null when every row was answered from your last 30 days (free, nothing to wait for)." }, "listId": { "type": "integer" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "done", "cancelled", "failed" ] }, "livemode": { "type": "boolean" }, "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" }, "creditsCharged": { "type": "number", "description": "Credits this job used so far." }, "creditsHeld": { "type": "number", "description": "Credits still held while the job runs (what it does not use goes back)." }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": "integer" }, "finishedAt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "results": { "description": "Present when the job is already done (cached, test mode, or `wait`).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "jobTitle": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "Works", "Probably works", "Not sure", "On hold", "Still checking…" ] }, { "type": "null" } ], "description": "The app's word for the email. Only \"Works\" is charged." }, "resultCode": { "anyOf": [ { "type": "string", "enum": [ "verified", "likely", "more-volume", "check-paused", "checking" ] }, { "type": "null" } ] }, "resultMeaning": { "type": [ "string", "null" ] }, "emailStatus": { "anyOf": [ { "type": "string", "enum": [ "valid", "invalid", "catch-all", "unknown" ] }, { "type": "null" } ] }, "emailStatusText": { "description": "Works, Does not work, Takes any name, Not sure.", "type": [ "string", "null" ] }, "emailScore": { "type": [ "number", "null" ] }, "resolveStatus": { "anyOf": [ { "type": "string", "enum": [ "likely-valid", "likely-invalid", "unknown", "not-resolvable", "check-paused", "check-pending" ] }, { "type": "null" } ], "description": "For \"takes any name\" emails: how likely the address is real." }, "resolveStatusText": { "type": [ "string", "null" ] }, "findStatus": { "anyOf": [ { "type": "string", "enum": [ "found", "unconfirmed", "not-found", "needs-check", "checking" ] }, { "type": "null" } ] }, "findStatusText": { "type": [ "string", "null" ] }, "emailType": { "anyOf": [ { "type": "string", "enum": [ "business-inbox", "owner-published", "owner-guessed" ] }, { "type": "null" } ], "description": "Business searches: business inbox, owner email from their website, or owner email we found and checked." }, "emailTypeText": { "type": [ "string", "null" ] }, "briefText": { "type": [ "string", "null" ] }, "briefLine": { "type": [ "string", "null" ] }, "briefRelevance": { "type": [ "string", "null" ] }, "registryCompanyNumber": { "description": "Deep Search only (official company registry, GB and AU).", "type": [ "string", "null" ] }, "registryStatus": { "type": [ "string", "null" ] }, "registryIncorporatedOn": { "type": [ "string", "null" ] }, "registrySic": { "type": [ "string", "null" ] }, "directorNames": { "description": "Deep Search only. Never used to find or guess emails.", "type": [ "string", "null" ] }, "registrySource": { "type": [ "string", "null" ] }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Your own extra columns (phone, city, address …)." } }, "required": [ "id", "company", "domain", "firstName", "lastName", "fullName", "jobTitle", "email", "result", "resultCode", "resultMeaning", "emailStatus", "emailStatusText", "emailScore", "resolveStatus", "resolveStatusText", "findStatus", "findStatusText", "emailType", "emailTypeText", "briefText", "briefLine", "briefRelevance", "extra" ], "additionalProperties": false } }, "nextCursor": { "description": "More results: call again with cursor=.", "type": [ "string", "null" ] }, "queued": { "type": "integer", "description": "Rows that will be worked on." }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "reason", "count" ], "additionalProperties": false }, "description": "Rows that cannot run this action, and why." }, "cached30d": { "type": "integer", "description": "Rows answered for free from your own results of the last 30 days." }, "maxCreditsHeld": { "type": "number", "description": "The most this job can cost. Held now, the unused part goes back." }, "pollUrl": { "type": [ "string", "null" ] } }, "required": [ "jobId", "listId", "status", "livemode", "queued", "skipped", "cached30d", "maxCreditsHeld", "pollUrl" ], "additionalProperties": false }, "example": { "jobId": 982, "listId": 378, "status": "queued", "livemode": true, "queued": 2, "skipped": [], "cached30d": 0, "maxCreditsHeld": 0.2, "pollUrl": "/api/v1/jobs/982" } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_json`: The body is not valid JSON. `no_eligible_rows`: None of the rows can run this action (for example: no website or domain to find an email for, or no email to check). `invalid_webhook_url`: The webhook URL is not a public https address (private networks and other schemes are refused).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`insufficient_credits`: The account has fewer credits than this request could use at most. We hold the maximum while the job runs and give back what it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`wrong_key_mode`: A test key asked for something made with a live key, or the other way round. Test and live data never mix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: The job or list does not exist, belongs to another account, or was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`idempotency_in_progress`: A request with the same Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`idempotency_key_reused`: The Idempotency-Key was already used in the last 24 hours with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listId": { "description": "Run on a list you already have (from POST /api/v1/lists or a search) instead of `rows`.", "type": "integer", "exclusiveMinimum": 0 }, "contactIds": { "description": "With listId: only these rows (default: all rows of the list).", "maxItems": 50000, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0 } }, "name": { "description": "Name of the new list (shown in the app). Default: \"API ()\".", "type": "string", "maxLength": 120 }, "emails": { "description": "The emails to check (or send `rows` with an `email` field).", "maxItems": 50000, "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "rows": { "maxItems": 50000, "type": "array", "items": { "type": "object", "properties": { "company": { "description": "Business name.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "website": { "description": "Website (any form: https://acme.com, acme.com/contact, www.acme.com).", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "domain": { "description": "Domain, if you have it instead of a website.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "firstName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "fullName": { "description": "Used when first and last name are not given separately.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "jobTitle": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "email": { "description": "The email to check (verify).", "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "country": { "description": "Two-letter country code, e.g. US, CA, GB.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "address": { "description": "Business address. For US businesses it decides which state rules apply.", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] } } } }, "webhookUrl": { "description": "Public https URL we POST the result to when the job is done (see the webhooks guide).", "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "webhookSecret": { "description": "Optional: sign this webhook with your own secret instead of the account signing secret.", "anyOf": [ { "type": "string", "minLength": 8, "maxLength": 200 }, { "type": "null" } ] }, "wait": { "default": 0, "description": "Seconds to wait for the job to finish before answering (0–30). Handy for Zapier, Make and Clay: small jobs come back done, with results.", "type": "integer", "minimum": 0, "maximum": 30 } } }, "example": { "emails": [ "sarah.miller@brightsmiledental.com", "info@brightsmiledental.com" ], "webhookUrl": "https://hooks.zapier.com/hooks/catch/123/abc/" } } } } } }, "/api/v1/deep-search": { "post": { "operationId": "deepSearch", "tags": [ "Deep Search" ], "summary": "Company summary and first line", "description": "Reads each business's own website and writes a short summary, why your offer could matter to them (set \"What you sell\" in the app) and a personal first line. For GB and AU businesses it adds official company-registry facts. Registry data is never used to find or guess emails.\n\n**Credits:** 0.5 credits per business we write a summary for (you only pay when we write the report). Rows your account already got an answer for in the last 30 days are answered again for free (`cached30d`).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID). A retry with the same key and body returns the first answer and is never charged twice. Kept 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "null when every row was answered from your last 30 days (free, nothing to wait for)." }, "listId": { "type": "integer" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "done", "cancelled", "failed" ] }, "livemode": { "type": "boolean" }, "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" }, "creditsCharged": { "type": "number", "description": "Credits this job used so far." }, "creditsHeld": { "type": "number", "description": "Credits still held while the job runs (what it does not use goes back)." }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": "integer" }, "finishedAt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "results": { "description": "Present when the job is already done (cached, test mode, or `wait`).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "jobTitle": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "Works", "Probably works", "Not sure", "On hold", "Still checking…" ] }, { "type": "null" } ], "description": "The app's word for the email. Only \"Works\" is charged." }, "resultCode": { "anyOf": [ { "type": "string", "enum": [ "verified", "likely", "more-volume", "check-paused", "checking" ] }, { "type": "null" } ] }, "resultMeaning": { "type": [ "string", "null" ] }, "emailStatus": { "anyOf": [ { "type": "string", "enum": [ "valid", "invalid", "catch-all", "unknown" ] }, { "type": "null" } ] }, "emailStatusText": { "description": "Works, Does not work, Takes any name, Not sure.", "type": [ "string", "null" ] }, "emailScore": { "type": [ "number", "null" ] }, "resolveStatus": { "anyOf": [ { "type": "string", "enum": [ "likely-valid", "likely-invalid", "unknown", "not-resolvable", "check-paused", "check-pending" ] }, { "type": "null" } ], "description": "For \"takes any name\" emails: how likely the address is real." }, "resolveStatusText": { "type": [ "string", "null" ] }, "findStatus": { "anyOf": [ { "type": "string", "enum": [ "found", "unconfirmed", "not-found", "needs-check", "checking" ] }, { "type": "null" } ] }, "findStatusText": { "type": [ "string", "null" ] }, "emailType": { "anyOf": [ { "type": "string", "enum": [ "business-inbox", "owner-published", "owner-guessed" ] }, { "type": "null" } ], "description": "Business searches: business inbox, owner email from their website, or owner email we found and checked." }, "emailTypeText": { "type": [ "string", "null" ] }, "briefText": { "type": [ "string", "null" ] }, "briefLine": { "type": [ "string", "null" ] }, "briefRelevance": { "type": [ "string", "null" ] }, "registryCompanyNumber": { "description": "Deep Search only (official company registry, GB and AU).", "type": [ "string", "null" ] }, "registryStatus": { "type": [ "string", "null" ] }, "registryIncorporatedOn": { "type": [ "string", "null" ] }, "registrySic": { "type": [ "string", "null" ] }, "directorNames": { "description": "Deep Search only. Never used to find or guess emails.", "type": [ "string", "null" ] }, "registrySource": { "type": [ "string", "null" ] }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Your own extra columns (phone, city, address …)." } }, "required": [ "id", "company", "domain", "firstName", "lastName", "fullName", "jobTitle", "email", "result", "resultCode", "resultMeaning", "emailStatus", "emailStatusText", "emailScore", "resolveStatus", "resolveStatusText", "findStatus", "findStatusText", "emailType", "emailTypeText", "briefText", "briefLine", "briefRelevance", "extra" ], "additionalProperties": false } }, "nextCursor": { "description": "More results: call again with cursor=.", "type": [ "string", "null" ] }, "queued": { "type": "integer", "description": "Rows that will be worked on." }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "reason", "count" ], "additionalProperties": false }, "description": "Rows that cannot run this action, and why." }, "cached30d": { "type": "integer", "description": "Rows answered for free from your own results of the last 30 days." }, "maxCreditsHeld": { "type": "number", "description": "The most this job can cost. Held now, the unused part goes back." }, "pollUrl": { "type": [ "string", "null" ] } }, "required": [ "jobId", "listId", "status", "livemode", "queued", "skipped", "cached30d", "maxCreditsHeld", "pollUrl" ], "additionalProperties": false }, "example": { "jobId": 983, "listId": 379, "status": "queued", "livemode": true, "queued": 1, "skipped": [], "cached30d": 0, "maxCreditsHeld": 0.5, "pollUrl": "/api/v1/jobs/983" } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_json`: The body is not valid JSON. `no_eligible_rows`: None of the rows can run this action (for example: no website or domain to find an email for, or no email to check). `invalid_webhook_url`: The webhook URL is not a public https address (private networks and other schemes are refused).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`insufficient_credits`: The account has fewer credits than this request could use at most. We hold the maximum while the job runs and give back what it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`wrong_key_mode`: A test key asked for something made with a live key, or the other way round. Test and live data never mix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: The job or list does not exist, belongs to another account, or was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`idempotency_in_progress`: A request with the same Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`idempotency_key_reused`: The Idempotency-Key was already used in the last 24 hours with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listId": { "description": "Run on a list you already have (from POST /api/v1/lists or a search) instead of `rows`.", "type": "integer", "exclusiveMinimum": 0 }, "contactIds": { "description": "With listId: only these rows (default: all rows of the list).", "maxItems": 50000, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0 } }, "name": { "description": "Name of the new list (shown in the app). Default: \"API ()\".", "type": "string", "maxLength": 120 }, "rows": { "description": "Up to 10,000 businesses (company + website).", "maxItems": 10000, "type": "array", "items": { "type": "object", "properties": { "company": { "description": "Business name.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "website": { "description": "Website (any form: https://acme.com, acme.com/contact, www.acme.com).", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "domain": { "description": "Domain, if you have it instead of a website.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "firstName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "fullName": { "description": "Used when first and last name are not given separately.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "jobTitle": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "email": { "description": "The email to check (verify).", "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "country": { "description": "Two-letter country code, e.g. US, CA, GB.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "address": { "description": "Business address. For US businesses it decides which state rules apply.", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] } } } }, "webhookUrl": { "description": "Public https URL we POST the result to when the job is done (see the webhooks guide).", "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "webhookSecret": { "description": "Optional: sign this webhook with your own secret instead of the account signing secret.", "anyOf": [ { "type": "string", "minLength": 8, "maxLength": 200 }, { "type": "null" } ] }, "wait": { "default": 0, "description": "Seconds to wait for the job to finish before answering (0–30). Handy for Zapier, Make and Clay: small jobs come back done, with results.", "type": "integer", "minimum": 0, "maximum": 30 } } }, "example": { "rows": [ { "company": "Bright Smile Dental", "website": "brightsmiledental.com", "city": "Austin", "country": "US" } ] } } } } } }, "/api/v1/search": { "post": { "operationId": "startSearch", "tags": [ "Business search" ], "summary": "Find businesses in an area, with emails", "description": "Finds businesses of one kind in a place (for example dentists in Austin, TX) and the best email for each: the business email or the owner's, checked. It runs in rounds until it has `target` emails that work (or searched the whole area). Poll `GET /api/v1/lists/{listId}` or set `webhookUrl` (event `search.completed`).\n\nOwner emails: only owners the business names on its own website. For businesses in Vermont, Oregon and Connecticut we deliver owner emails only when the website prints them.\n\n**Credits:** 1 credit per delivered email that Works. Businesses without a website, and emails we could not confirm, are free. With `brief: true`, plus 0.5 credits per summary.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID). A retry with the same key and body returns the first answer and is never charged twice. Kept 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "integer" }, "listId": { "type": "integer" }, "jobId": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "run": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "pollUrl": { "type": "string" } }, "required": [ "runId", "listId", "jobId", "livemode", "run", "pollUrl" ], "additionalProperties": false }, "example": { "runId": 55, "listId": 380, "jobId": 984, "livemode": true, "run": { "status": "running", "delivered": 0, "creditsUsed": 0 }, "pollUrl": "/api/v1/lists/380" } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_json`: The body is not valid JSON. `invalid_webhook_url`: The webhook URL is not a public https address (private networks and other schemes are refused).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`insufficient_credits`: The account has fewer credits than this request could use at most. We hold the maximum while the job runs and give back what it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`place_not_found`: We could not find the place you searched in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`idempotency_in_progress`: A request with the same Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`idempotency_key_reused`: The Idempotency-Key was already used in the last 24 hours with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`search_unavailable`: Business search is not available right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "minLength": 2, "maxLength": 80, "description": "What kind of business, e.g. \"dentist\", \"roofing contractor\", \"yoga studio\"." }, "location": { "type": "string", "minLength": 2, "maxLength": 120, "description": "City, county, state or ZIP / post code." }, "country": { "type": "string", "enum": [ "US", "CA", "GB", "AU", "NZ", "IE", "DE", "AT", "CH", "FR", "ES", "IT", "NL", "BE", "LU", "PT", "DK", "SE", "FI", "PL", "CZ", "MX" ], "description": "Country of the location." }, "mode": { "default": "target", "description": "target: stop at `target` emails that work. all: search the whole area (up to creditLimit).", "type": "string", "enum": [ "target", "all" ] }, "target": { "default": 25, "description": "How many emails that work you want (mode \"target\").", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 5000 }, { "type": "null" } ] }, "creditLimit": { "default": null, "description": "mode \"all\": stop when this many credits are used (default: until your credits run out).", "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "role": { "default": "any", "description": "any: the business email (info@, office@ …). best: the owner when the business names one on its own website, else the business email. owner: only owners named on the business's own website.", "type": "string", "enum": [ "any", "best", "owner", "marketing", "sales" ] }, "brief": { "default": false, "description": "Also write a short company summary and a first line for each business.", "type": "boolean" }, "webhookUrl": { "description": "Public https URL we POST the result to when the job is done (see the webhooks guide).", "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "webhookSecret": { "description": "Optional: sign this webhook with your own secret instead of the account signing secret.", "anyOf": [ { "type": "string", "minLength": 8, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "category", "location", "country" ] }, "example": { "category": "dentist", "location": "Austin, TX", "country": "US", "target": 25 } } } } } }, "/api/v1/jobs": { "get": { "operationId": "listJobs", "tags": [ "Jobs" ], "summary": "Your jobs, newest first", "description": "All jobs of your account (made with keys of the same kind), newest first, without their results. Page with `cursor`.\n\n**Credits:** Free.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Rows per page, 1–1000.", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the page before. Leave out for the first page.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "jobId": { "type": "integer" }, "listId": { "type": "integer" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "done", "cancelled", "failed" ] }, "livemode": { "type": "boolean", "description": "false for test keys (made-up results, never charged)." }, "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" }, "creditsCharged": { "type": "number", "description": "Credits this job used so far." }, "creditsHeld": { "type": "number", "description": "Credits still held while the job runs (what it does not use goes back)." }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": "integer" }, "finishedAt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "jobId", "listId", "action", "status", "livemode", "total", "done", "failed", "creditsCharged", "creditsHeld", "message", "createdAt", "finishedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_cursor`: The cursor is not one we gave out (they are opaque; do not build them yourself).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/jobs/{id}": { "get": { "operationId": "getJob", "tags": [ "Jobs" ], "summary": "A job's status and results", "description": "Status (`queued`, `running`, `paused`, `done`, `cancelled`, `failed`), progress and the results so far. Poll every 5–10 seconds until `status` is `done`, or use a webhook. More than 1,000 results: page with `cursor`.\n\n**Credits:** Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "integer", "exclusiveMinimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, 1–1000.", "schema": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the page before. Leave out for the first page.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "integer" }, "listId": { "type": "integer" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "done", "cancelled", "failed" ] }, "livemode": { "type": "boolean", "description": "false for test keys (made-up results, never charged)." }, "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" }, "creditsCharged": { "type": "number", "description": "Credits this job used so far." }, "creditsHeld": { "type": "number", "description": "Credits still held while the job runs (what it does not use goes back)." }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": "integer" }, "finishedAt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "jobTitle": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "Works", "Probably works", "Not sure", "On hold", "Still checking…" ] }, { "type": "null" } ], "description": "The app's word for the email. Only \"Works\" is charged." }, "resultCode": { "anyOf": [ { "type": "string", "enum": [ "verified", "likely", "more-volume", "check-paused", "checking" ] }, { "type": "null" } ] }, "resultMeaning": { "type": [ "string", "null" ] }, "emailStatus": { "anyOf": [ { "type": "string", "enum": [ "valid", "invalid", "catch-all", "unknown" ] }, { "type": "null" } ] }, "emailStatusText": { "description": "Works, Does not work, Takes any name, Not sure.", "type": [ "string", "null" ] }, "emailScore": { "type": [ "number", "null" ] }, "resolveStatus": { "anyOf": [ { "type": "string", "enum": [ "likely-valid", "likely-invalid", "unknown", "not-resolvable", "check-paused", "check-pending" ] }, { "type": "null" } ], "description": "For \"takes any name\" emails: how likely the address is real." }, "resolveStatusText": { "type": [ "string", "null" ] }, "findStatus": { "anyOf": [ { "type": "string", "enum": [ "found", "unconfirmed", "not-found", "needs-check", "checking" ] }, { "type": "null" } ] }, "findStatusText": { "type": [ "string", "null" ] }, "emailType": { "anyOf": [ { "type": "string", "enum": [ "business-inbox", "owner-published", "owner-guessed" ] }, { "type": "null" } ], "description": "Business searches: business inbox, owner email from their website, or owner email we found and checked." }, "emailTypeText": { "type": [ "string", "null" ] }, "briefText": { "type": [ "string", "null" ] }, "briefLine": { "type": [ "string", "null" ] }, "briefRelevance": { "type": [ "string", "null" ] }, "registryCompanyNumber": { "description": "Deep Search only (official company registry, GB and AU).", "type": [ "string", "null" ] }, "registryStatus": { "type": [ "string", "null" ] }, "registryIncorporatedOn": { "type": [ "string", "null" ] }, "registrySic": { "type": [ "string", "null" ] }, "directorNames": { "description": "Deep Search only. Never used to find or guess emails.", "type": [ "string", "null" ] }, "registrySource": { "type": [ "string", "null" ] }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Your own extra columns (phone, city, address …)." } }, "required": [ "id", "company", "domain", "firstName", "lastName", "fullName", "jobTitle", "email", "result", "resultCode", "resultMeaning", "emailStatus", "emailStatusText", "emailScore", "resolveStatus", "resolveStatusText", "findStatus", "findStatusText", "emailType", "emailTypeText", "briefText", "briefLine", "briefRelevance", "extra" ], "additionalProperties": false } }, "nextCursor": { "description": "More results: call again with cursor=.", "type": [ "string", "null" ] } }, "required": [ "jobId", "listId", "action", "status", "livemode", "total", "done", "failed", "creditsCharged", "creditsHeld", "message", "createdAt", "finishedAt", "results", "nextCursor" ], "additionalProperties": false }, "example": { "jobId": 981, "listId": 377, "action": "findEmail", "status": "done", "livemode": true, "total": 1, "done": 1, "failed": 0, "creditsCharged": 1, "creditsHeld": 0, "message": null, "createdAt": 1762344000000, "finishedAt": 1762344014000, "results": [ { "id": 4102, "company": "Bright Smile Dental", "domain": "brightsmiledental.com", "firstName": "Sarah", "lastName": "Miller", "fullName": "Sarah Miller", "jobTitle": null, "email": "sarah.miller@brightsmiledental.com", "result": "Works", "resultCode": "verified", "resultMeaning": "We checked it. This inbox is real, so you can send to it.", "emailStatus": "valid", "emailStatusText": "Works", "emailScore": 96, "resolveStatus": null, "resolveStatusText": null, "findStatus": "found", "findStatusText": "Found and checked", "emailType": null, "emailTypeText": null, "briefText": null, "briefLine": null, "briefRelevance": null, "extra": {} } ], "nextCursor": null } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_cursor`: The cursor is not one we gave out (they are opaque; do not build them yourself).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`wrong_key_mode`: A test key asked for something made with a live key, or the other way round. Test and live data never mix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: The job or list does not exist, belongs to another account, or was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/jobs/{id}/cancel": { "post": { "operationId": "cancelJob", "tags": [ "Jobs" ], "summary": "Stop a job", "description": "Stops a running job. Results already delivered stay (and stay charged); the credits held for the rest go back at once.\n\n**Credits:** Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "integer", "exclusiveMinimum": 0 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID). A retry with the same key and body returns the first answer and is never charged twice. Kept 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "integer" }, "listId": { "type": "integer" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "done", "cancelled", "failed" ] }, "livemode": { "type": "boolean", "description": "false for test keys (made-up results, never charged)." }, "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" }, "creditsCharged": { "type": "number", "description": "Credits this job used so far." }, "creditsHeld": { "type": "number", "description": "Credits still held while the job runs (what it does not use goes back)." }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": "integer" }, "finishedAt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "jobTitle": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "Works", "Probably works", "Not sure", "On hold", "Still checking…" ] }, { "type": "null" } ], "description": "The app's word for the email. Only \"Works\" is charged." }, "resultCode": { "anyOf": [ { "type": "string", "enum": [ "verified", "likely", "more-volume", "check-paused", "checking" ] }, { "type": "null" } ] }, "resultMeaning": { "type": [ "string", "null" ] }, "emailStatus": { "anyOf": [ { "type": "string", "enum": [ "valid", "invalid", "catch-all", "unknown" ] }, { "type": "null" } ] }, "emailStatusText": { "description": "Works, Does not work, Takes any name, Not sure.", "type": [ "string", "null" ] }, "emailScore": { "type": [ "number", "null" ] }, "resolveStatus": { "anyOf": [ { "type": "string", "enum": [ "likely-valid", "likely-invalid", "unknown", "not-resolvable", "check-paused", "check-pending" ] }, { "type": "null" } ], "description": "For \"takes any name\" emails: how likely the address is real." }, "resolveStatusText": { "type": [ "string", "null" ] }, "findStatus": { "anyOf": [ { "type": "string", "enum": [ "found", "unconfirmed", "not-found", "needs-check", "checking" ] }, { "type": "null" } ] }, "findStatusText": { "type": [ "string", "null" ] }, "emailType": { "anyOf": [ { "type": "string", "enum": [ "business-inbox", "owner-published", "owner-guessed" ] }, { "type": "null" } ], "description": "Business searches: business inbox, owner email from their website, or owner email we found and checked." }, "emailTypeText": { "type": [ "string", "null" ] }, "briefText": { "type": [ "string", "null" ] }, "briefLine": { "type": [ "string", "null" ] }, "briefRelevance": { "type": [ "string", "null" ] }, "registryCompanyNumber": { "description": "Deep Search only (official company registry, GB and AU).", "type": [ "string", "null" ] }, "registryStatus": { "type": [ "string", "null" ] }, "registryIncorporatedOn": { "type": [ "string", "null" ] }, "registrySic": { "type": [ "string", "null" ] }, "directorNames": { "description": "Deep Search only. Never used to find or guess emails.", "type": [ "string", "null" ] }, "registrySource": { "type": [ "string", "null" ] }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Your own extra columns (phone, city, address …)." } }, "required": [ "id", "company", "domain", "firstName", "lastName", "fullName", "jobTitle", "email", "result", "resultCode", "resultMeaning", "emailStatus", "emailStatusText", "emailScore", "resolveStatus", "resolveStatusText", "findStatus", "findStatusText", "emailType", "emailTypeText", "briefText", "briefLine", "briefRelevance", "extra" ], "additionalProperties": false } }, "nextCursor": { "description": "More results: call again with cursor=.", "type": [ "string", "null" ] } }, "required": [ "jobId", "listId", "action", "status", "livemode", "total", "done", "failed", "creditsCharged", "creditsHeld", "message", "createdAt", "finishedAt", "results", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_json`: The body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`wrong_key_mode`: A test key asked for something made with a live key, or the other way round. Test and live data never mix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: The job or list does not exist, belongs to another account, or was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`idempotency_in_progress`: A request with the same Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`idempotency_key_reused`: The Idempotency-Key was already used in the last 24 hours with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/lists": { "post": { "operationId": "createList", "tags": [ "Lists" ], "summary": "Upload a list", "description": "Stores rows as a list (it shows up in the app). Then run find-contacts, verify or deep-search on it with `listId`. Most integrations skip this and send `rows` directly.\n\n**Credits:** Free.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID). A retry with the same key and body returns the first answer and is never charged twice. Kept 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "listId": { "type": "integer" }, "rowCount": { "type": "integer" }, "contactIds": { "type": "array", "items": { "type": "integer" } }, "livemode": { "type": "boolean" } }, "required": [ "listId", "rowCount", "contactIds", "livemode" ], "additionalProperties": false }, "example": { "listId": 381, "rowCount": 1, "contactIds": [ 4110 ], "livemode": true } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_json`: The body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`idempotency_in_progress`: A request with the same Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`idempotency_key_reused`: The Idempotency-Key was already used in the last 24 hours with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "default": "API List", "type": "string", "minLength": 1, "maxLength": 120 }, "rows": { "minItems": 1, "maxItems": 50000, "type": "array", "items": { "type": "object", "properties": { "company": { "description": "Business name.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "website": { "description": "Website (any form: https://acme.com, acme.com/contact, www.acme.com).", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "domain": { "description": "Domain, if you have it instead of a website.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "firstName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "fullName": { "description": "Used when first and last name are not given separately.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "jobTitle": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "email": { "description": "The email to check (verify).", "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "country": { "description": "Two-letter country code, e.g. US, CA, GB.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "address": { "description": "Business address. For US businesses it decides which state rules apply.", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] } } } } }, "required": [ "rows" ] }, "example": { "name": "Austin dentists", "rows": [ { "company": "Bright Smile Dental", "website": "brightsmiledental.com", "firstName": "Sarah", "lastName": "Miller" } ] } } } } }, "get": { "operationId": "listLists", "tags": [ "Lists" ], "summary": "Your lists, newest first", "description": "All lists of your account (uploads, API jobs and business searches), newest first.\n\n**Credits:** Free.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Rows per page, 1–1000.", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the page before. Leave out for the first page.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "listId": { "type": "integer" }, "name": { "type": "string" }, "rowCount": { "type": "integer" }, "livemode": { "type": "boolean" }, "createdAt": { "type": "integer" } }, "required": [ "listId", "name", "rowCount", "livemode", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_cursor`: The cursor is not one we gave out (they are opaque; do not build them yourself).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/lists/{id}": { "get": { "operationId": "getList", "tags": [ "Lists" ], "summary": "A list with its results", "description": "The list, the progress of its business search (if it is one) and up to 1,000 rows per page.\n\n**Credits:** Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "integer", "exclusiveMinimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, 1–1000.", "schema": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the page before. Leave out for the first page.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "listId": { "type": "integer" }, "name": { "type": "string" }, "rowCount": { "type": "integer" }, "livemode": { "type": "boolean" }, "createdAt": { "type": "integer" }, "run": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Business searches: progress of the search (status, delivered, creditsUsed, message)." }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "jobTitle": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "Works", "Probably works", "Not sure", "On hold", "Still checking…" ] }, { "type": "null" } ], "description": "The app's word for the email. Only \"Works\" is charged." }, "resultCode": { "anyOf": [ { "type": "string", "enum": [ "verified", "likely", "more-volume", "check-paused", "checking" ] }, { "type": "null" } ] }, "resultMeaning": { "type": [ "string", "null" ] }, "emailStatus": { "anyOf": [ { "type": "string", "enum": [ "valid", "invalid", "catch-all", "unknown" ] }, { "type": "null" } ] }, "emailStatusText": { "description": "Works, Does not work, Takes any name, Not sure.", "type": [ "string", "null" ] }, "emailScore": { "type": [ "number", "null" ] }, "resolveStatus": { "anyOf": [ { "type": "string", "enum": [ "likely-valid", "likely-invalid", "unknown", "not-resolvable", "check-paused", "check-pending" ] }, { "type": "null" } ], "description": "For \"takes any name\" emails: how likely the address is real." }, "resolveStatusText": { "type": [ "string", "null" ] }, "findStatus": { "anyOf": [ { "type": "string", "enum": [ "found", "unconfirmed", "not-found", "needs-check", "checking" ] }, { "type": "null" } ] }, "findStatusText": { "type": [ "string", "null" ] }, "emailType": { "anyOf": [ { "type": "string", "enum": [ "business-inbox", "owner-published", "owner-guessed" ] }, { "type": "null" } ], "description": "Business searches: business inbox, owner email from their website, or owner email we found and checked." }, "emailTypeText": { "type": [ "string", "null" ] }, "briefText": { "type": [ "string", "null" ] }, "briefLine": { "type": [ "string", "null" ] }, "briefRelevance": { "type": [ "string", "null" ] }, "registryCompanyNumber": { "description": "Deep Search only (official company registry, GB and AU).", "type": [ "string", "null" ] }, "registryStatus": { "type": [ "string", "null" ] }, "registryIncorporatedOn": { "type": [ "string", "null" ] }, "registrySic": { "type": [ "string", "null" ] }, "directorNames": { "description": "Deep Search only. Never used to find or guess emails.", "type": [ "string", "null" ] }, "registrySource": { "type": [ "string", "null" ] }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Your own extra columns (phone, city, address …)." } }, "required": [ "id", "company", "domain", "firstName", "lastName", "fullName", "jobTitle", "email", "result", "resultCode", "resultMeaning", "emailStatus", "emailStatusText", "emailScore", "resolveStatus", "resolveStatusText", "findStatus", "findStatusText", "emailType", "emailTypeText", "briefText", "briefLine", "briefRelevance", "extra" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "listId", "name", "rowCount", "livemode", "createdAt", "run", "results", "nextCursor" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_cursor`: The cursor is not one we gave out (they are opaque; do not build them yourself).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`wrong_key_mode`: A test key asked for something made with a live key, or the other way round. Test and live data never mix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: The job or list does not exist, belongs to another account, or was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "operationId": "deleteList", "tags": [ "Lists" ], "summary": "Delete a list", "description": "Deletes the list and all its rows and results for good (running jobs on it stop). The same as deleting it in the app.\n\n**Credits:** Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "integer", "exclusiveMinimum": 0 } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "listId": { "type": "integer" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "listId", "deleted" ], "additionalProperties": false } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`wrong_key_mode`: A test key asked for something made with a live key, or the other way round. Test and live data never mix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: The job or list does not exist, belongs to another account, or was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/lists/{id}/rows": { "get": { "operationId": "getListRows", "tags": [ "Lists" ], "summary": "Rows as JSON pages or one CSV file", "description": "The rows of a list. `format=json` (default): pages of `limit` rows with `nextCursor`. `format=csv`: the whole list as one CSV file with plain column names (email, first_name, last_name, company_name, website, personalization …) that Instantly, Smartlead and most CRMs map without help. `only=works` keeps only emails that Work.\n\n**Credits:** Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "integer", "exclusiveMinimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page, 1–1000.", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the page before. Leave out for the first page.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "format", "in": "query", "required": false, "description": "csv: the whole list as one CSV file (no paging), ready for Instantly, Smartlead or a CRM.", "schema": { "default": "json", "type": "string", "enum": [ "json", "csv" ] } }, { "name": "only", "in": "query", "required": false, "description": "works: only rows whose email Works.", "schema": { "default": "all", "type": "string", "enum": [ "all", "works" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "listId": { "type": "integer" }, "livemode": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "company": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "jobTitle": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "result": { "anyOf": [ { "type": "string", "enum": [ "Works", "Probably works", "Not sure", "On hold", "Still checking…" ] }, { "type": "null" } ], "description": "The app's word for the email. Only \"Works\" is charged." }, "resultCode": { "anyOf": [ { "type": "string", "enum": [ "verified", "likely", "more-volume", "check-paused", "checking" ] }, { "type": "null" } ] }, "resultMeaning": { "type": [ "string", "null" ] }, "emailStatus": { "anyOf": [ { "type": "string", "enum": [ "valid", "invalid", "catch-all", "unknown" ] }, { "type": "null" } ] }, "emailStatusText": { "description": "Works, Does not work, Takes any name, Not sure.", "type": [ "string", "null" ] }, "emailScore": { "type": [ "number", "null" ] }, "resolveStatus": { "anyOf": [ { "type": "string", "enum": [ "likely-valid", "likely-invalid", "unknown", "not-resolvable", "check-paused", "check-pending" ] }, { "type": "null" } ], "description": "For \"takes any name\" emails: how likely the address is real." }, "resolveStatusText": { "type": [ "string", "null" ] }, "findStatus": { "anyOf": [ { "type": "string", "enum": [ "found", "unconfirmed", "not-found", "needs-check", "checking" ] }, { "type": "null" } ] }, "findStatusText": { "type": [ "string", "null" ] }, "emailType": { "anyOf": [ { "type": "string", "enum": [ "business-inbox", "owner-published", "owner-guessed" ] }, { "type": "null" } ], "description": "Business searches: business inbox, owner email from their website, or owner email we found and checked." }, "emailTypeText": { "type": [ "string", "null" ] }, "briefText": { "type": [ "string", "null" ] }, "briefLine": { "type": [ "string", "null" ] }, "briefRelevance": { "type": [ "string", "null" ] }, "registryCompanyNumber": { "description": "Deep Search only (official company registry, GB and AU).", "type": [ "string", "null" ] }, "registryStatus": { "type": [ "string", "null" ] }, "registryIncorporatedOn": { "type": [ "string", "null" ] }, "registrySic": { "type": [ "string", "null" ] }, "directorNames": { "description": "Deep Search only. Never used to find or guess emails.", "type": [ "string", "null" ] }, "registrySource": { "type": [ "string", "null" ] }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Your own extra columns (phone, city, address …)." } }, "required": [ "id", "company", "domain", "firstName", "lastName", "fullName", "jobTitle", "email", "result", "resultCode", "resultMeaning", "emailStatus", "emailStatusText", "emailScore", "resolveStatus", "resolveStatusText", "findStatus", "findStatusText", "emailType", "emailTypeText", "briefText", "briefLine", "briefRelevance", "extra" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "listId", "livemode", "results", "nextCursor" ], "additionalProperties": false } }, "text/csv": { "schema": { "type": "string" } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_cursor`: The cursor is not one we gave out (they are opaque; do not build them yourself).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`wrong_key_mode`: A test key asked for something made with a live key, or the other way round. Test and live data never mix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`not_found`: The job or list does not exist, belongs to another account, or was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/webhooks/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhooks" ], "summary": "Send a signed test event", "description": "Sends a signed `ping` event to your URL right now and tells you what your server answered. Use it to set up Make, Zapier or n8n, and to test your signature check.\n\n**Credits:** Free.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (a UUID). A retry with the same key and body returns the first answer and is never charged twice. Kept 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "statusCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ] }, "signature": { "type": "string", "description": "The X-Moleman-Signature header we sent." } }, "required": [ "delivered", "statusCode", "error", "signature" ], "additionalProperties": false }, "example": { "delivered": true, "statusCode": 200, "error": null, "signature": "t=1762344000,v1=5f2c…" } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute with this key." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in this minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute starts over." } } }, "400": { "description": "`invalid_request`: A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path. `invalid_json`: The body is not valid JSON. `invalid_webhook_url`: The webhook URL is not a public https address (private networks and other schemes are refused).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`missing_api_key`: The request has no API key. `invalid_api_key`: The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted). `revoked_api_key`: The API key was revoked on the API page. Revoking takes effect at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`idempotency_in_progress`: A request with the same Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`idempotency_key_reused`: The Idempotency-Key was already used in the last 24 hours with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`: More than 120 requests in one minute with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`server_error`: Something broke on our side. Nothing was charged for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "description": "The https URL to send a signed test event (\"ping\") to." }, "webhookSecret": { "description": "Optional: sign this webhook with your own secret instead of the account signing secret.", "anyOf": [ { "type": "string", "minLength": 8, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "url" ] }, "example": { "url": "https://hook.eu2.make.com/abc123" } } } } } }, "/api/v1/openapi.json": { "get": { "operationId": "getOpenApi", "tags": [ "Docs" ], "summary": "This API as OpenAPI 3.1", "description": "The OpenAPI 3.1 description of every endpoint, built from the same schemas the server checks requests with. No key needed.\n\n**Credits:** Free.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [] } }, "/api/v1/docs.md": { "get": { "operationId": "getDocsMarkdown", "tags": [ "Docs" ], "summary": "All docs as one Markdown file", "description": "Every guide and endpoint in one Markdown file, for reading offline or giving to an AI agent. No key needed.\n\n**Credits:** Free.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "text/markdown": { "schema": { "type": "string" } } } } }, "security": [] } }, "/api/v1/clay-template.json": { "get": { "operationId": "getClayTemplate", "tags": [ "Docs" ], "summary": "Clay HTTP API column settings", "description": "Ready settings for Clay's \"HTTP API\" column (find email, verify, Deep Search). No key needed. See the Clay guide.\n\n**Credits:** Free.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [] } } } }