{ "openapi": "3.0.1", "info": { "title": "Address Verification API - Global Cleanse and Geocode", "description": "Verify and standardise postal addresses in 245 countries with a match grade per address, plus email verification with a risk score, phone validation with network and number type, forward and reverse geocoding, and UK bank account checks. Pay per result.", "version": "0.1", "x-build-id": "Nuq2GPlbzd38vl6vC" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~address-verification-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-address-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~address-verification-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-address-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~address-verification-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-address-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": "What to verify", "enum": [ "address-verify", "address-search", "address-retrieve", "email-verify", "phone-verify", "geocode", "reverse-geocode", "bank-verify" ], "type": "string", "description": "Which service to call. Each mode reads a different input list, so fill in the list named in the mode you pick and leave the others empty.", "default": "address-verify" }, "addresses": { "title": "Addresses", "type": "array", "description": "Addresses to verify, one per line. A whole address written as plain text works, and so does a JSON object with any of these fields: address, address1 to address5, organization, building, premise, subBuilding, thoroughfare, locality (or city), dependentLocality, administrativeArea (or state), subAdministrativeArea, superAdministrativeArea, postalCode (or zip), postBox, country, contact, department, latitude, longitude. Supplying a country raises the match rate considerably.", "items": { "type": "string" } }, "searches": { "title": "Searches", "type": "array", "description": "Partial addresses to search for, one per line, used by the search mode. Searching costs nothing and returns identifiers, and turning an identifier into a full address is the step that is charged.", "items": { "type": "string" } }, "addressIds": { "title": "Address IDs", "type": "array", "description": "Address identifiers from an earlier search, one per line, used by the retrieve mode. This is how a run picks up where a search left off without paying for the search again.", "items": { "type": "string" } }, "emails": { "title": "Email addresses", "type": "array", "description": "Addresses to verify, one per line. An address pasted inside a longer string is extracted before the request, and duplicates are removed so you are never charged twice for the same address.", "items": { "type": "string" } }, "phones": { "title": "Phone numbers", "type": "array", "description": "Numbers to verify, one per line. Include the country code, or set a default country below so numbers written in national format still resolve.", "items": { "type": "string" } }, "locations": { "title": "Locations", "type": "array", "description": "Place names or postal codes to turn into coordinates, one per line. Set a default country to keep a name that exists in several countries from resolving to the wrong one.", "items": { "type": "string" } }, "coordinates": { "title": "Coordinates", "type": "array", "description": "Coordinate pairs to turn into places, one per line, written as latitude then longitude. Pairs outside the valid range are dropped before the request rather than sent and charged for.", "items": { "type": "string" } }, "bankAccounts": { "title": "Bank accounts", "type": "array", "description": "United Kingdom accounts to verify, one per line, written as a sort code and an account number in either order. The two are told apart by length, so any separator works.", "items": { "type": "string" } }, "countries": { "title": "Restrict searches to these countries", "type": "array", "description": "Two-letter or three-letter country codes, used by the search mode to keep results inside the countries you care about. Leave empty to search everywhere.", "items": { "type": "string" } }, "defaultCountry": { "title": "Default country", "type": "string", "description": "The country to assume when an input does not say. Used by address verification, phone verification and geocoding. A phone number in national format and a postal code that exists in several countries both need this to resolve correctly." }, "geocode": { "title": "Return coordinates with verified addresses", "type": "boolean", "description": "Ask the address verification service for latitude and longitude alongside the corrected address. Off by default because it can cost more of your provider credits.", "default": false }, "minVerificationLevel": { "title": "Minimum verification level", "minimum": 0, "maximum": 5, "type": "integer", "description": "Only keep addresses matched at least this well, on a five point scale where five is fully verified, four is partially verified, three is ambiguous and below that is unverified. Sent to the provider as well as applied locally, so it genuinely narrows the results. Leave at zero to keep every level.", "default": 0 }, "maxMatchesPerAddress": { "title": "Maximum matches per address", "minimum": 1, "maximum": 100, "type": "integer", "description": "How many candidate matches the verification service may return for one ambiguous address. Every candidate is a row, so this multiplies both the dataset and the spend. Leave empty for the provider's own default." }, "outputCasing": { "title": "Output casing", "type": "string", "description": "How verified addresses are cased on the way out, such as Title, Upper or Lower. Leave empty for the provider's own default." }, "outputScript": { "title": "Output script", "type": "string", "description": "The script verified addresses are transliterated into, such as Latn for Latin or Native to keep the local script. Leave empty for the provider's own default." }, "retrieveAddresses": { "title": "Retrieve the full address after a search", "type": "boolean", "description": "In the search mode, turn each matched address identifier into the full address. On by default, because a search on its own returns identifiers rather than addresses. Turning it off makes a run free and gives you identifiers to retrieve later.", "default": true }, "followContainers": { "title": "Search inside partial matches", "type": "boolean", "description": "A search can return a street, a postcode or a building rather than an address, and those have to be searched into rather than used. On by default, which is what turns a postcode into the addresses inside it. Searching is free, so this costs nothing until an address is actually retrieved.", "default": true }, "searchLimit": { "title": "Search results per query", "minimum": 1, "maximum": 100, "type": "integer", "description": "How many results one search returns before the run starts retrieving them. Raising it widens the net and, with retrieval on, multiplies the spend.", "default": 10 }, "language": { "title": "Search language", "type": "string", "description": "A three letter language code for the search mode. Be careful with this: filtering by a language the search term is not written in returns nothing at all rather than falling back." }, "findTypes": { "title": "Keep only these search result types", "type": "array", "description": "When search results are written directly rather than retrieved, keep only these kinds. Leave empty to keep every kind.", "items": { "type": "string", "enum": [ "Address", "Postcode", "Street", "BuildingNumber", "BuildingName", "Locality", "Subbuilding" ] }, "default": [] }, "emailResponseCodes": { "title": "Keep only these email verdicts", "type": "array", "description": "Only keep addresses with these verdicts. Note that a catch-all result means the domain accepts everything, so the individual mailbox is unproven rather than confirmed. Leave empty to keep every verdict.", "items": { "type": "string", "enum": [ "Valid", "Valid_CatchAll", "Invalid", "Timeout" ], "enumTitles": [ "Valid: the mailbox itself was confirmed", "Valid catch-all: the domain accepts everything, so the mailbox is unproven", "Invalid: the address is not usable", "Timeout: the check did not finish in the time allowed" ] }, "default": [] }, "emailRiskLevels": { "title": "Keep only these email risk levels", "type": "array", "description": "Only keep addresses the provider rated this way. The risk level aggregates every signal it holds into a single estimate of how likely the address is to bounce.", "items": { "type": "string", "enum": [ "Low", "Medium", "High", "Unknown" ] }, "default": [] }, "excludeDisposableEmail": { "title": "Drop disposable addresses", "type": "boolean", "description": "Leave out addresses on throwaway or temporary mailbox providers, which are created to expire and are worth nothing in a list.", "default": false }, "emailTimeoutMs": { "title": "Email lookup timeout in milliseconds", "minimum": 1, "maximum": 15000, "type": "integer", "description": "How long the provider may spend on one address, from one to fifteen thousand milliseconds. Below about five thousand you will see noticeably more timeout verdicts, which cost you a lookup and tell you nothing.", "default": 5000 }, "phoneNumberTypes": { "title": "Keep only these phone number types", "type": "array", "description": "Only keep numbers of these kinds. Useful when a campaign needs mobiles for messaging or landlines for a call list.", "items": { "type": "string", "enum": [ "Mobile", "Landline", "VOIP", "Unknown" ] }, "default": [] }, "requireValidPhone": { "title": "Keep only confirmed phone numbers", "type": "boolean", "description": "Drop numbers the provider could not confirm. Note that this also drops the inconclusive answer the provider returns when the network could not be reached, which is not the same as a bad number.", "default": false }, "forceSingle": { "title": "Verify email addresses one at a time", "type": "boolean", "description": "Send every address as its own request rather than in batches of up to one hundred. Slower and far more requests, and the only route that honours a per address timeout. The actor already uses it automatically for very short lists.", "default": false }, "batchSize": { "title": "Records per batch", "minimum": 1, "maximum": 100, "type": "integer", "description": "How many addresses or email addresses to submit in one request, up to the provider's ceiling of one hundred. The provider's own advice is to keep an address batch to one country at a time, which lets its engine work far more efficiently.", "default": 100 }, "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's surge protector starts tripping; raise it to finish a long list sooner.", "default": 300 }, "skipNotFound": { "title": "Skip inputs with no result", "type": "boolean", "description": "Leave inputs the provider returned nothing for out of the dataset. Note that an invalid email address is a verdict, not a miss, so this does not drop invalid rows. Off by default. 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, and it matters most in the search mode, where one query can drill into a postcode holding dozens of addresses.", "default": 100 }, "apiKey": { "title": "API key", "type": "string", "description": "Your own API key for the address verification API. Keys look like AA11-AA11-AA11-AA11 and carry their own security settings, so a key restricted to a URL, an IP address or a subset of services will be refused for anything outside them. 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 } } } } } } } } } }