{
  "openapi": "3.0.1",
  "info": {
    "title": "Phone Number Lookup API",
    "description": "Validate phone numbers in bulk, or straight from another Apify run's results. Get format, country, carrier, line type and a can-receive-texts flag. Not a WhatsApp or owner lookup. Rows without carrier data are free.",
    "version": "1.5",
    "x-build-id": "I7gBAU8iIcWjbuXgl"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~phone-number-lookup-api/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-phone-number-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/khadinakbar~phone-number-lookup-api/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-phone-number-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/khadinakbar~phone-number-lookup-api/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-phone-number-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": {
          "phoneNumbers": {
            "title": "Phone numbers to look up",
            "maxItems": 10000,
            "type": "array",
            "description": "Type or paste phone numbers, one per line (up to 10,000). Best format: +12025551234. Local numbers like (202) 555-1234 work if you set Default country below. The same number written twice is charged once. If you paste or upload a CSV, or pick results from another run below, this list is ignored. Free Apify plan runs check up to 25 different numbers per run.",
            "items": {
              "type": "string"
            }
          },
          "datasetId": {
            "title": "Or: phone numbers from another Apify run",
            "type": "string",
            "description": "Pick the results (dataset) of another run, for example from a Google Maps, Yelp or contact-details scraper. The Actor finds the phone column, checks every number, and keeps each row's name, address and other simple fields next to the phone info. When you pick results here, the typed list above is ignored. You can also paste a dataset ID."
          },
          "csvText": {
            "title": "Or: paste a CSV",
            "type": "string",
            "description": "Paste CSV text with a header row, for example from Excel, Google Sheets or a CRM export. The phone column is found for you and each row's other columns (name, address, email) stay next to the phone result. Up to 10,000 phone numbers per run. If you also pick results from another run, those are used instead."
          },
          "csvFile": {
            "title": "Or: upload a CSV file",
            "type": "string",
            "description": "Upload a .csv file (up to 5 MB, header row required). Same behavior as pasting CSV text. Pasted text is used first if both are filled."
          },
          "phoneField": {
            "title": "Phone column name (optional)",
            "type": "string",
            "description": "Only needed if the phone column is not found automatically. Type the column name from the picked results or from the CSV header row, for example phone or Phone Number. Leave empty to detect it automatically."
          },
          "defaultCountry": {
            "title": "Default country (ISO 3166-1 alpha-2)",
            "type": "string",
            "description": "Two-letter country code (e.g. 'US', 'GB', 'IN', 'DE') used as fallback when a phone number has no country code prefix. Only needed for local-format numbers like '(555) 123-4567'. Leave empty if all numbers are already in E.164.",
            "default": "US"
          },
          "validateOnly": {
            "title": "Check format only (free)",
            "type": "boolean",
            "description": "Only clean and validate the list: format, country, E.164 and a basic line-type guess from the numbering plan. No carrier lookup and no charge per number. Use this to remove bad numbers first, then run again with this off for carrier data.",
            "default": false
          },
          "maxConcurrency": {
            "title": "Concurrent lookups",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Number of phone numbers processed in parallel. Higher is faster but may hit carrier lookup rate limits; stay conservative. Default 20 is safe for most cases. Max 100. Lower this to 5-10 if you see rate-limit warnings.",
            "default": 20
          },
          "includeReverseLookupUrls": {
            "title": "Generate reverse-lookup URLs",
            "type": "boolean",
            "description": "Adds pre-built search URLs for Google, Whitepages, Truecaller, BeenVerified, Spokeo, 800notes, MrNumber, Facebook, and LinkedIn so you can investigate any number manually. Free, no extra event charge. Defaults to true.",
            "default": true
          },
          "includeWhatsAppCheck": {
            "title": "Check WhatsApp format validity (experimental)",
            "type": "boolean",
            "description": "Experimental format check using an unauthenticated wa.me redirect. It cannot tell whether a number uses WhatsApp and returns no WhatsApp profile, name or photo. It only tests whether the number looks like a WhatsApp-acceptable format. Defaults to false.",
            "default": false
          },
          "includeTelegramCheck": {
            "title": "Check Telegram public profile",
            "type": "boolean",
            "description": "Checks whether the number has a public Telegram profile via t.me. Returns public name and photo only when the profile is public. Most Telegram users have private profiles and will return registered: false even if they use Telegram. Defaults to true.",
            "default": true
          },
          "maxCostUsd": {
            "title": "Max cost ceiling (USD)",
            "minimum": 0,
            "type": "number",
            "description": "Spending limit per run in US dollars, counted from billed carrier lookups at the highest listed price (so it is a safe limit). Decimals work, for example 0.50. The run stops cleanly and tells you how many numbers were left. Free format-only rows do not count. Leave at 0 for no limit.",
            "default": 0
          },
          "requireCarrier": {
            "title": "Require carrier data",
            "type": "boolean",
            "description": "Stop the run with a clear status when carrier lookup is unavailable, instead of saving a batch of format-only rows. Default false keeps the free format-only rows. Rows without carrier data are never billed either way. Not a filter for landlines or invalid numbers.",
            "default": false
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}