{ "openapi": "3.0.1", "info": { "title": "Reverse Phone Lookup API - Caller ID, Owner and Address Data", "description": "Find the person or business behind a phone number, with line type, carrier and an activity score that separates a live number from a disconnected one. Grade inbound leads across phone, email and address, screen for TCPA litigators, and list the residents of an address. Pay per result.", "version": "0.1", "x-build-id": "ciM8lMfXcTYESt8hF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~reverse-phone-lookup-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-reverse-phone-lookup-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~reverse-phone-lookup-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-reverse-phone-lookup-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~reverse-phone-lookup-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-reverse-phone-lookup-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 do", "enum": [ "realContact", "phoneValidation", "callerId", "smartCnam", "reversePhone", "reverseAddress", "addressValidation" ], "type": "string", "description": "Lead grading scores a whole lead at once: the phone, the email and the address are each graded A to F and checked against the name on the form. Phone validation returns line type, carrier and an activity score that tells a disconnected number from a live one. Caller identification and caller name return the owner behind a number. Reverse phone returns every owner on record, which is how a reassigned mobile is caught. Reverse address returns the current residents of a postal address. Address validation checks an address is real and deliverable.", "default": "realContact" }, "phones": { "title": "Phone numbers", "type": "array", "description": "Phone numbers, one per line, in international format or in the local format of the country you set below. Used by every phone product, and by lead grading as the phone half of each lead.", "items": { "type": "string" } }, "names": { "title": "Names on the lead", "type": "array", "description": "The name each lead gave you, one per line. Lead grading reads the lists row by row rather than crossing them, so row one of this list belongs with row one of every other list: one row is one lead. Lead grading only.", "items": { "type": "string" } }, "emails": { "title": "Email addresses on the lead", "type": "array", "description": "The email address each lead gave you, one per line, in the same order as the names. Graded for deliverability and checked against the name. Lead grading only.", "items": { "type": "string" } }, "addresses": { "title": "Postal addresses", "type": "array", "description": "Postal addresses, one per line, written as one line each. Reverse address and address validation read this list as the thing to look up; lead grading reads it as the address half of each lead, in the same order as the names. A single line is split into street, city, state and postal code before the request.", "items": { "type": "string" } }, "ipAddresses": { "title": "Signup IP addresses", "type": "array", "description": "The IP address each lead submitted the form from, one per line, in the same order as the names. Returns a trust score and how far the IP sits from the address given, which is what separates a local lead from one filled in from another continent. Lead grading only.", "items": { "type": "string" } }, "businessNames": { "title": "Business names on the lead", "type": "array", "description": "The business name each lead gave you, one per line, in the same order as the names. Use it when the lead is a company rather than a person. Lead grading only.", "items": { "type": "string" } }, "countryCode": { "title": "Country code for addresses", "type": "string", "description": "Two letter ISO 3166 country code applied to the postal addresses above, for example US or CA. Leave empty to let the provider infer it." }, "countryHint": { "title": "Country hint for phone numbers", "type": "string", "description": "Two letter ISO 3166 country code used to read phone numbers written in local format, for example US. Numbers already in international format do not need it." }, "nameHint": { "title": "Name hint", "type": "string", "description": "A person or business name you already associate with the numbers, used to rank the owners the provider returns. Caller identification and reverse phone only." }, "postalCodeHint": { "title": "Postal code hint", "type": "string", "description": "A postal code you already associate with the numbers, used to rank the owners the provider returns. Caller identification and reverse phone only." }, "addOns": { "title": "Add-ons", "type": "array", "description": "Extra checks the provider bills separately. Litigator screening flags numbers belonging to known TCPA litigators before you dial. Spam screening flags numbers reported as spam. The two email checks return deliverability and how long the address has existed. Each add-on is only sent to the products that accept it, so leaving them all on is safe.", "items": { "type": "string", "enum": [ "litigator_checks", "spam_checks", "email_checks_deliverability", "email_checks_age" ], "enumTitles": [ "Litigator screening: flag known TCPA litigators", "Spam screening: flag numbers reported as spam", "Email deliverability: is the address deliverable", "Email age: how long the address has existed" ] }, "default": [] }, "keepContactGrades": { "title": "Keep only these phone grades", "type": "array", "description": "Only keep leads whose phone graded one of these. Restricting to A and B is how a raw form dump becomes a call list. Leave empty to keep every grade. Applied after the provider answers, so it reduces dataset noise and Apify spend rather than provider credits.", "items": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ], "enumTitles": [ "A: reachable and the name matches", "B: reachable, weaker name match", "C: reachable, no name match", "D: questionable", "F: unreachable or invalid" ] }, "default": [] }, "keepLineTypes": { "title": "Keep only these line types", "type": "array", "description": "Only keep rows whose phone is one of these line types. Keeping mobile only is how an SMS list is built; dropping VOIP is how throwaway numbers are filtered out. Leave empty to keep every line type.", "items": { "type": "string", "enum": [ "Landline", "Mobile", "FixedVOIP", "NonFixedVOIP", "Premium", "TollFree", "Voicemail", "Other" ], "enumTitles": [ "Landline", "Mobile", "Fixed VOIP", "Non-fixed VOIP: often disposable", "Premium rate", "Toll free", "Voicemail only", "Other" ] }, "default": [] }, "minActivityScore": { "title": "Minimum phone activity score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Only keep rows whose phone activity score is at least this, on a 0 to 100 scale. The activity score is what separates a number still in service from one that was disconnected months ago. Leave empty to keep every score." }, "requireValidPhone": { "title": "Drop rows whose phone is invalid", "type": "boolean", "description": "Skip any row the provider reported as an invalid phone number.", "default": false }, "requireNameMatch": { "title": "Drop rows where the name does not match the phone", "type": "boolean", "description": "Skip rows where the provider says the number belongs to somebody other than the name on the lead. Lead grading only.", "default": false }, "excludeLitigatorRisk": { "title": "Drop known TCPA litigators", "type": "boolean", "description": "Skip rows flagged as belonging to a known TCPA litigator. Needs the litigator screening add-on above to be switched on, since without it the provider never returns the flag.", "default": false }, "skipNotFound": { "title": "Skip inputs that resolve to nothing", "type": "boolean", "description": "By default an input that resolved to nothing is still written, with found set to false and the reason on the row, so a list can be reconciled against what went in. Switch this on to leave those rows out entirely. Rows with no result are never charged for either way.", "default": false }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Stop after this many rows. Note that reverse phone and reverse address can return several rows per input, since a number can have several owners and an address several residents.", "default": 100 }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 1200, "type": "integer", "description": "How fast to call the provider. Requests are spaced evenly rather than sent in bursts, which is what keeps a long list from bunching up against the rate limiter. Lower this if your plan has a tighter ceiling.", "default": 300 }, "apiKey": { "title": "API key", "type": "string", "description": "Your own API key for the identity data provider this actor calls. The actor never ships a key: you bring yours, the run uses it, and it is stored encrypted. Can also be supplied as the DATA_API_KEY environment 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 } } } } } } } } } }