{ "openapi": "3.0.1", "info": { "title": "Phone Number Intelligence API - Carrier, Type and Risk", "description": "Look up any phone number worldwide: carrier, line type, city, region, country, time zone and coordinates, plus a fraud risk score with an allow, flag or block recommendation, SIM swap and porting checks, and whether the number is reachable right now. Pay per result.", "version": "0.1", "x-build-id": "G1v5DIbOPGeXdwkpl" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~phone-number-intelligence-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-phone-number-intelligence-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~phone-number-intelligence-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-phone-number-intelligence-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~phone-number-intelligence-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-phone-number-intelligence-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 look up", "enum": [ "phone-intelligence", "phone-lookup", "live-status" ], "type": "string", "description": "Risk scoring returns everything the lookup returns plus a score and a recommendation. The plain lookup is cheaper on your provider credits when the risk verdict is not needed. Live status answers one question: is this number reachable on the network right now.", "default": "phone-intelligence" }, "phones": { "title": "Phone numbers", "type": "array", "description": "Numbers to look up, one per line, in complete international form with the country code. A plus sign, a leading double zero, spaces, brackets and dashes are all fine. You can also give a JSON object with any of these fields: phone, externalId, accountId, deviceId, email, originatingIp. Numbers that cannot be a complete international number are refused before the request rather than sent and charged for, and are recorded as refusals.", "items": { "type": "string" } }, "defaultCountryCode": { "title": "Default calling code", "type": "string", "description": "The calling code to put in front of numbers written in national format, such as 1 for North America or 44 for the United Kingdom. With this set, a number starting with a trunk zero has the zero replaced by the code. With it empty, a number starting with a zero is refused rather than guessed at, since a national number belongs to a different subscriber in every country that shares the pattern, and a number with no country code and fewer than ten digits is refused as well. Numbers written with a plus or a leading double zero are unaffected either way." }, "addons": { "title": "Identity attributes to include", "type": "array", "description": "Extra attributes to request alongside the standard answer, on the two lookup modes. Each one is a separate product with the provider and most must be enabled on your account before they return anything; some also require a record of consent. Leave empty for the standard answer only.", "items": { "type": "string", "enum": [ "contact", "contact_match", "contact_plus", "subscriber_status", "number_deactivation", "porting_history", "porting_status", "sim_swap", "active_call_status", "breached_number_check", "call_forward_detection", "age_verify" ], "enumTitles": [ "Contact: the name and address on the line", "Contact match: whether a name and address you hold match the line", "Contact plus: an extended contact record", "Subscriber status: the account state behind the number", "Number deactivation: whether the number has been given up", "Porting history: past moves between networks", "Porting status: whether the number is being moved right now", "SIM swap: whether the SIM was recently changed", "Active call status: whether the line is on a call", "Breached number check: whether the number appears in known breaches", "Call forward detection: whether calls are being forwarded", "Age verify: whether the subscriber is over a threshold" ] }, "default": [] }, "addonOptions": { "title": "Identity attribute settings", "type": "object", "description": "A JSON object of settings for the attributes that take their own parameters, merged into the request exactly as written. Use this for things like a name and address to match against, or an age threshold, without waiting for a named field. Anything named here is enabled whether or not it is ticked above." }, "consentMethod": { "title": "How consent was obtained", "minimum": 1, "maximum": 4, "type": "integer", "description": "The provider's numeric code for how you obtained the subscriber's consent to query this number, from one to four. Some identity attributes will not return anything without it. Left off entirely unless a value is given here, because an invented consent record is worse than none." }, "consentTimestamp": { "title": "When consent was obtained", "type": "string", "description": "The time consent was obtained, as an ISO 8601 timestamp. Sent alongside the consent method." }, "lifecycleEvent": { "title": "What the end user is doing", "enum": [ "create", "sign-in", "transact", "update", "delete" ], "type": "string", "description": "The point in the account lifecycle this check belongs to. The risk model reads this: the same number carries a very different risk at account creation than it does at sign-in, and telling the provider which one you are in makes the score meaningfully better." }, "originatingIp": { "title": "End user IP address", "type": "string", "description": "The IP address the end user came from, applied to every number that does not carry its own. Improves the risk score, since a number and an IP that disagree about geography is a signal in itself." }, "recommendations": { "title": "Keep only these recommendations", "type": "array", "description": "Only keep rows the provider recommended this way. This is the fastest way to turn a scoring run into a block list or an allow list. Leave empty to keep every recommendation.", "items": { "type": "string", "enum": [ "allow", "flag", "block" ], "enumTitles": [ "Allow: proceed", "Flag: review", "Block: refuse" ] }, "default": [] }, "riskLevels": { "title": "Keep only these risk levels", "type": "array", "description": "Only keep rows at these risk levels. Leave empty to keep every level.", "items": { "type": "string", "enum": [ "low", "medium-low", "medium", "medium-high", "high" ] }, "default": [] }, "maxRiskScore": { "title": "Maximum risk score", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Only keep rows scoring at or below this on the provider's zero to one thousand scale. A finer instrument than the level, and the right one when you are tuning a threshold. Leave at zero to keep every score.", "default": 0 }, "phoneTypes": { "title": "Keep only these line types", "type": "array", "description": "Only keep rows whose line type matches one of these, written as the provider names them, such as Mobile or Landline. Useful when a campaign needs mobiles for messaging or landlines for a call list. Leave empty to keep every type.", "items": { "type": "string" } }, "countries": { "title": "Keep only these countries", "type": "array", "description": "Only keep rows whose number resolves to one of these two-letter country codes. Leave empty to keep every country.", "items": { "type": "string" } }, "excludeBlocklisted": { "title": "Drop blocklisted numbers", "type": "boolean", "description": "Leave out numbers the provider has blocklisted for any reason.", "default": false }, "excludeProhibited": { "title": "Drop numbers you may not contact", "type": "boolean", "description": "Leave out numbers the provider blocks by policy rather than by risk, meaning your account is not permitted to contact them at all. That is a different decision from a high score and it is kept as its own column.", "default": false }, "requireReachable": { "title": "Keep only reachable numbers", "type": "boolean", "description": "In the live status mode, drop numbers that are not currently reachable on the network. Has no effect in the other two modes, since only the live status route answers that question and an absent answer is not a negative one.", "default": false }, "authScheme": { "title": "Authentication scheme", "enum": [ "signed", "basic" ], "type": "string", "description": "Signed builds a request signature from your API key and works on every route. Basic sends the credentials directly and is accepted by the lookup routes but refused by the risk scoring route, which complains about the header format rather than about the key. Leave this on signed unless you have a reason not to.", "default": "signed" }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 3000, "type": "integer", "description": "Pace the run so it stays under whatever rate your plan allows. Lower this if the provider starts rate limiting; raise it to finish a long list sooner.", "default": 600 }, "skipNotFound": { "title": "Skip numbers with no result", "type": "boolean", "description": "Leave numbers the provider returned nothing for, and inputs refused before they were sent, out of the dataset. Off by default, because knowing which of your numbers were unusable is usually the point. 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 }, "clientId": { "title": "Customer ID", "type": "string", "description": "Your own customer id for the phone intelligence API. This is a separate value from the API key and both are required; a run with only one of them will be rejected on every request. Stored as a secret." }, "apiKey": { "title": "API key", "type": "string", "description": "Your own API key for the phone intelligence API, which is the long encoded secret issued alongside the customer id. 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 } } } } } } } } } }