{ "openapi": "3.0.1", "info": { "title": "Contact Verification API - Email, Phone and Address", "description": "Verify a whole contact record in one call: the email address, the phone number and the postal address, each with its own verdict and detail code. Get the corrected and standardised postal address back, plus line type and county. Real time or bulk lists. Pay per result.", "version": "0.1", "x-build-id": "oO2x0jSfg6EAXm9S7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~contact-verification-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-contact-verification-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/nabeelbaghoor~contact-verification-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-contact-verification-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/nabeelbaghoor~contact-verification-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-contact-verification-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "How to run it", "enum": [ "realtime", "bulk" ], "type": "string", "description": "Real time verifies one contact per request and answers immediately, which suits a few hundred records and is the only route that returns a corrected postal address. Bulk creates a list on the provider's side, waits for it to finish and exports the results, which suits tens of thousands and spends most of its time waiting rather than requesting.", "default": "realtime" }, "emails": { "title": "Email addresses", "type": "array", "description": "Email addresses, one per line. Paired line by line with the phone numbers and postal addresses below into one contact record each, so line three of this list belongs to the same person as line three of the others. Leave empty to verify only phones or only addresses. An address pasted inside a longer string is extracted before the request.", "items": { "type": "string" } }, "phones": { "title": "Phone numbers", "type": "array", "description": "Phone numbers, one per line, paired line by line with the addresses above. Brackets, dots and spaces are stripped before the request, so a pasted list in mixed formats still works. Leave empty to skip phone verification.", "items": { "type": "string" } }, "postalAddresses": { "title": "Postal addresses", "type": "array", "description": "One postal address per line, paired line by line with the lists above, written as street, city, state, postcode. Both the four part and the three part spelling are understood, so 1 Main St, Boston, MA 02116 works as well as 1 Main St, Boston, MA, 02116. Leave empty to skip address verification.", "items": { "type": "string" } }, "keyType": { "title": "Which kind of key you generated", "enum": [ "serverSide", "clientSide" ], "type": "string", "description": "This provider issues two kinds of key, and each answers on its own path. A key made for server use is the normal choice for an actor. Pick client side only if the key you have was generated as a browser key, otherwise the provider will reject it without explaining why.", "default": "serverSide" }, "emailStatuses": { "title": "Keep only these email verdicts", "type": "array", "description": "Only keep contacts whose email verdict is one of these. Restricting to valid is how you turn a raw list into one that is safe to send to. Leave empty to keep every verdict. Applied after the provider answers, so it reduces dataset noise and Apify spend rather than provider credits.", "items": { "type": "string", "enum": [ "valid", "invalid", "accept_all", "risky", "unknown" ], "enumTitles": [ "Valid: the mailbox exists", "Invalid: will bounce", "Accept all: the domain accepts everything", "Risky: may accept, but likely to underperform", "Unknown: no verdict could be reached" ] }, "default": [] }, "phoneStatuses": { "title": "Keep only these phone verdicts", "type": "array", "description": "Only keep contacts whose phone verdict is one of these. Leave empty to keep every verdict.", "items": { "type": "string", "enum": [ "valid", "invalid", "unknown" ], "enumTitles": [ "Valid", "Invalid", "Unknown" ] }, "default": [] }, "addressStatuses": { "title": "Keep only these address verdicts", "type": "array", "description": "Only keep contacts whose postal address verdict is one of these. Leave empty to keep every verdict.", "items": { "type": "string", "enum": [ "valid", "invalid", "unknown" ], "enumTitles": [ "Valid", "Invalid", "Unknown" ] }, "default": [] }, "statusDetails": { "title": "Keep only these email detail codes", "type": "array", "description": "Only keep contacts whose email detail code is one of these. The detail code is what sits under a non-valid verdict, and it is what separates a temporary error that will pass on a retry from a mailbox that genuinely does not exist. Leave empty to keep every detail code.", "items": { "type": "string", "enum": [ "email_address_invalid", "email_domain_invalid", "email_account_invalid", "mailbox_full", "disposable", "role_address", "temporary_error", "blocked", "not_enough_data", "unknown_error", "invalid_phone_number" ], "enumTitles": [ "Address format is wrong", "Domain does not exist", "Mailbox does not exist at that domain", "Mailbox is full", "Disposable address", "Role address such as info or sales", "Temporary error, retry later", "The provider blocked the check", "Not enough data to decide", "Unknown error", "Invalid phone number" ] }, "default": [] }, "excludeRoleAddresses": { "title": "Drop role addresses", "type": "boolean", "description": "Leave out shared inboxes such as info, sales and support, keeping only addresses that belong to an individual. Useful when the list is meant for one to one outreach.", "default": false }, "excludeDisposable": { "title": "Drop disposable addresses", "type": "boolean", "description": "Leave out addresses on throwaway providers, which are created to expire and are worth nothing in a list.", "default": false }, "requireAllValid": { "title": "Keep only fully valid contacts", "type": "boolean", "description": "Only keep contacts where every part you actually submitted came back valid. A record with no phone number is not failed for its phone, so this stays usable when you are verifying only one or two of the three.", "default": false }, "listSize": { "title": "Contacts per bulk list", "minimum": 1, "maximum": 10000, "type": "integer", "description": "How many contacts to put in one bulk list. Larger lists mean fewer jobs to wait on, at the cost of a longer wait for each. Bulk only.", "default": 10000 }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 1200, "type": "integer", "description": "Pace the run so it stays under whatever rate your plan allows. Lower this if the provider starts returning rate limit responses; raise it to finish a long list sooner.", "default": 300 }, "skipNotFound": { "title": "Skip inputs with no result", "type": "boolean", "description": "Leave contacts the provider returned no verdict at all for out of the dataset. Note that an invalid contact is a verdict, not a miss, so this does not drop invalid records. Off by default, because keeping the misses is what lets you see which contacts resolved and which did not. Misses are never charged for either way.", "default": false }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Stop after this many rows. This is the cap on both spend and run time.", "default": 100 }, "apiKey": { "title": "API key", "type": "string", "description": "Your own API key for the contact verification API. Sent as a request header, never on the URL. Required for every lookup. Stored as a secret." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }