{
  "openapi": "3.0.1",
  "info": {
    "title": "Bulk Phone Number Validator & Cleaner: Carrier, CSV or Sheet",
    "description": "Bulk phone validation for an Apify dataset, CSV/Excel/JSON file or Google Sheet. Returns every original row plus country, line type, mobile or landline, region, carrier lookup, timezone and E.164. Inputs: datasetId or fileUrl, phoneField, defaultRegion. Charged per number. Agent-ready: x402, MCP.",
    "version": "0.1",
    "x-build-id": "VXispgCO2BZFedbh5"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/nerolabs~phone-number-validator/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-nerolabs-phone-number-validator",
        "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/nerolabs~phone-number-validator/runs": {
      "post": {
        "operationId": "runs-sync-nerolabs-phone-number-validator",
        "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/nerolabs~phone-number-validator/run-sync": {
      "post": {
        "operationId": "run-sync-nerolabs-phone-number-validator",
        "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": {
          "datasetId": {
            "title": "Dataset",
            "type": "string",
            "description": "Pick an existing Apify dataset, for example the output of any scraper run. Use this OR 'File URL' OR 'Data (inline)'. Declaring it this way is what lets this Actor run with limited permissions: it may read the dataset you point at, and nothing else on your account."
          },
          "fileUrl": {
            "title": "File URL (CSV, Excel, JSON or Google Sheet)",
            "type": "string",
            "description": "A public link to a CSV or TSV file, an Excel .xlsx file, a JSON array or JSON Lines file, or a Google Sheet (paste the normal sheet link with sharing set to 'Anyone with the link can view'). Format is detected automatically. Up to 100 MB."
          },
          "data": {
            "title": "Data (inline)",
            "type": "array",
            "description": "Paste rows directly instead, for a quick one-off check."
          },
          "fileFormat": {
            "title": "File format",
            "enum": [
              "auto",
              "csv",
              "tsv",
              "json",
              "jsonl",
              "xlsx"
            ],
            "type": "string",
            "description": "Only needed if automatic detection gets the file URL's format wrong.",
            "default": "auto"
          },
          "phoneField": {
            "title": "Phone field",
            "type": "string",
            "description": "Which column holds the number, for example 'phone' or 'contact_number'. Leave empty and it is detected automatically, first by column name and then by looking at which column actually contains real numbers."
          },
          "defaultRegion": {
            "title": "Default region (two-letter country code)",
            "type": "string",
            "description": "The country to assume for numbers stored without a country code, such as '020 7946 0123' or '(212) 555-0123'. Use GB, US, AU, DE and so on. Numbers that already start with + are unaffected. Without this, a number with no country code cannot be validated at all and is reported as 'unknown_region' rather than guessed at."
          },
          "flagPremiumRate": {
            "title": "Flag premium-rate numbers",
            "type": "boolean",
            "description": "Marks expensive premium-rate lines (UK 09, US 900 and their equivalents) as risky rather than valid. These are real numbers, but calling one costs money and it is almost never a person's own phone.",
            "default": true
          },
          "flagVoip": {
            "title": "Flag VoIP numbers",
            "type": "boolean",
            "description": "Marks internet-telephony ranges as risky. VoIP numbers are cheap and quick to create, so on a signup list they play much the same role a throwaway email address does.",
            "default": true
          },
          "flagNonPersonal": {
            "title": "Flag toll-free and other non-personal lines",
            "type": "boolean",
            "description": "Marks toll-free, shared-cost, UAN, pager and voicemail numbers as risky. They work, but they reach a switchboard or a service rather than the contact you have in the row.",
            "default": true
          },
          "markDuplicates": {
            "title": "Mark duplicates",
            "type": "boolean",
            "description": "The first time a number appears it is checked normally; later repeats are marked 'duplicate'. Matching is done on the E.164 form, so '020 7946 0123', '+44 20 7946 0123' and '+442079460123' are correctly recognised as the same number.",
            "default": true
          },
          "lookupRegion": {
            "title": "Look up the region",
            "type": "boolean",
            "description": "Adds a place description where the numbering plan carries one, for example 'London' or 'New York, NY'. Mobile numbers usually have no geographic meaning, so this is normally empty for them.",
            "default": true
          },
          "lookupCarrier": {
            "title": "Look up the carrier",
            "type": "boolean",
            "description": "Adds the network the number's range was originally ALLOCATED to, for example Vodafone or Optus. This is not the current network if the number has since been ported, and it needs no live lookup. Available for mobile ranges in most countries, but not in the United States or Canada.",
            "default": true
          },
          "lookupTimezone": {
            "title": "Look up the timezone",
            "type": "boolean",
            "description": "Adds the IANA timezone or timezones the number sits in, so a dialling list can respect local calling hours.",
            "default": true
          },
          "keep": {
            "title": "Rows to keep",
            "enum": [
              "all",
              "valid",
              "valid_and_risky",
              "problems",
              "mobile"
            ],
            "type": "string",
            "description": "Filters the output. Every row is still checked and charged either way, so this is about what you get back, not about cost.",
            "default": "all"
          },
          "exportFormats": {
            "title": "Also export as a file",
            "type": "array",
            "description": "Optionally write the results as a real downloadable CSV and/or Excel file, on top of the dataset.",
            "items": {
              "type": "string",
              "enum": [
                "csv",
                "xlsx"
              ],
              "enumTitles": [
                "CSV",
                "Excel (.xlsx)"
              ]
            },
            "default": []
          },
          "outputDatasetName": {
            "title": "Also append to a named dataset",
            "type": "string",
            "description": "Optional. Every run's results are also appended to a dataset of this name, so a scheduled job builds one growing clean list. Not charged again."
          },
          "maxItems": {
            "title": "Maximum rows",
            "minimum": 1,
            "type": "integer",
            "description": "Stop after this many rows, a cost guard while you are testing. There is a hard ceiling of 200,000 per run regardless."
          },
          "webhookUrl": {
            "title": "Webhook URL (optional)",
            "type": "string",
            "description": "Optional. If set, the run summary (counts and download links, never the numbers themselves) is POSTed here as JSON when the run finishes, so a scheduled clean-up can report into Slack, Zapier, Make, n8n or your own API. Only charged on a confirmed 2xx."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}