{
  "openapi": "3.0.1",
  "info": {
    "title": "Bulk Phone Number Validator & Cleaner — E.164, $0.50/1k",
    "description": "Clean a phone list end to end: parse and validate with libphonenumber, format to E.164, international and national, detect line type, region, carrier and timezone offline, deduplicate on E.164 and export segmented CSV. Reads numbers buried in free text. No external API calls.",
    "version": "0.1",
    "x-build-id": "lfJ4EKcialr81Y2Ay"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/yabanana99~phone-number-cleaner-validator/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-yabanana99-phone-number-cleaner-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/yabanana99~phone-number-cleaner-validator/runs": {
      "post": {
        "operationId": "runs-sync-yabanana99-phone-number-cleaner-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/yabanana99~phone-number-cleaner-validator/run-sync": {
      "post": {
        "operationId": "run-sync-yabanana99-phone-number-cleaner-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": {
          "phones": {
            "title": "Phone numbers (inline)",
            "type": "array",
            "description": "Numbers to check, one per item. Use this for quick runs; for real lists use <b>Contact files</b> below. Inline numbers and files are merged and deduplicated together.",
            "default": [
              "+39 333 1234567",
              "0039 333 1234567",
              "(212) 555-0123",
              "+44 20 7946 0958",
              "call me on 333 1234567 after 6pm",
              "+1 555 555 5555",
              "not a number"
            ],
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "title": "Contact files (CSV, XLSX, JSON)",
            "type": "array",
            "description": "Files to read. Each item is an object with exactly one of: <b>url</b> (http/https link to the file), <b>base64</b> (base64-encoded file content, data URIs accepted) or <b>key</b> (record key in a key-value store, with optional <b>store_id</b>). Add <b>filename</b> (e.g. <code>contacts.csv</code>) to help format detection. Supported: CSV, TSV, XLSX, JSON, JSON Lines and plain-text lists. Up to 20 files per run."
          },
          "default_region": {
            "title": "Default region (ISO-2 country code)",
            "type": "string",
            "description": "Country to assume for numbers written <b>without</b> a country code (<code>212 555 0123</code>, <code>06 12345678</code>). Two letters, e.g. <code>US</code>, <code>GB</code>, <code>DE</code>, <code>IT</code>, <code>IN</code>, <code>BR</code>. Numbers that already start with <code>+</code> or <code>00</code> ignore it. If your list is national and you leave this empty, the run stops before charging anything and tells you which region to set.",
            "default": "IT"
          },
          "phone_column": {
            "title": "Phone column",
            "type": "string",
            "description": "Name of the column (CSV/XLSX header or JSON field) holding the number. Leave empty to auto-detect: known header names first (phone, mobile, telefono, telefon, téléphone…), then the column whose values really are phone numbers. The column actually used is always reported in the run log."
          },
          "dedup": {
            "title": "Remove duplicates",
            "type": "boolean",
            "description": "<b>On</b>: one record per unique number, matched on <b>E.164</b> — so <code>+39 333 1234567</code>, <code>0039 333 1234567</code> and <code>333 1234567</code> are one contact, with <code>occurrences</code> telling how many times it appeared. <b>Off</b>: one record per input row, duplicates flagged with <code>is_duplicate</code> and <code>duplicate_of</code>. Either way a duplicate is never charged twice.",
            "default": true
          },
          "output_formats": {
            "title": "Output formats",
            "type": "array",
            "description": "Which formats to write for every number. <b>E.164</b> (<code>+393331234567</code>) is what CRMs, SMS gateways and WhatsApp APIs want, and it is always produced because it is also the deduplication key.",
            "items": {
              "type": "string",
              "enum": [
                "e164",
                "international",
                "national",
                "rfc3966"
              ],
              "enumTitles": [
                "E.164 (+393331234567)",
                "International (+39 333 123 4567)",
                "National (333 123 4567)",
                "RFC3966 (tel:+39-333-123-4567)"
              ]
            },
            "default": [
              "e164",
              "international",
              "national",
              "rfc3966"
            ]
          },
          "strict": {
            "title": "Strict: reject possible-but-not-valid numbers",
            "type": "boolean",
            "description": "A number can have a plausible length for its country and still belong to no assigned range. By default those land in the <b>possible</b> segment (score 60). Turn this on to call them <b>invalid</b> — recommended before an SMS campaign you pay per message.",
            "default": false
          },
          "detect_type": {
            "title": "Detect line type",
            "type": "boolean",
            "description": "Mobile, fixed line, VoIP, toll-free, premium rate, shared cost, pager, UAN, voicemail. This is what tells you which numbers can receive an SMS and which ones cost money to call.",
            "default": true
          },
          "carrier_lookup": {
            "title": "Carrier (offline metadata)",
            "type": "boolean",
            "description": "Name of the carrier the number range was <b>originally allocated</b> to, from the metadata bundled in the image — no HLR lookup, no network call. Only mobile ranges are covered. Where the country has mobile number portability the record says so (<code>carrier_may_have_changed</code>), because the subscriber may have moved to another operator.",
            "default": true
          },
          "timezone_lookup": {
            "title": "Time zones",
            "type": "boolean",
            "description": "IANA time zones for the number (<code>Europe/Rome</code>), from the bundled metadata. Useful to schedule calls at a sane local hour.",
            "default": true
          },
          "geo_lookup": {
            "title": "Area description",
            "type": "boolean",
            "description": "Geographic description of the number's area (<code>Milan</code>, <code>New York, NY</code>), from the bundled metadata. Available for geographic (mostly fixed-line) numbers only.",
            "default": true
          },
          "extract_from_text": {
            "title": "Extract numbers from free text",
            "type": "boolean",
            "description": "Read the number out of a cell that also contains text (<code>call me on 333 1234567 after 6pm</code>, <code>+39 333 1234567 (home)</code>) instead of calling the row invalid. Only numbers that are <b>valid</b> are taken from text, so an order id in a sentence is never mistaken for a contact.",
            "default": true
          },
          "output_segments": {
            "title": "Export segment CSV files",
            "type": "boolean",
            "description": "Also write <code>valid.csv</code>, <code>possible.csv</code>, <code>invalid.csv</code> and <code>mobile.csv</code> to the run's key-value store, ready to download and import.",
            "default": true
          },
          "include_source_row": {
            "title": "Keep the original row",
            "type": "boolean",
            "description": "Copy the source row (all its columns) into <code>source_row</code>, so the cleaned output keeps names, companies and every other field. Up to 30 columns, 500 characters per value and 1000 characters per row.",
            "default": false
          },
          "ignore_low_validity": {
            "title": "Process the file even if nothing validates",
            "type": "boolean",
            "description": "By default the run stops after the first 1000 numbers if not one of them is a valid phone number (a wrong column, a wrong file or a missing <b>default_region</b>) — you are charged for the sample, not for the whole file. Turn this on when the list really is that bad and you want every row processed anyway.",
            "default": false
          },
          "max_numbers": {
            "title": "Max numbers per run",
            "minimum": 1,
            "maximum": 200000,
            "type": "integer",
            "description": "Safety cap on how many rows are processed (and therefore charged) in one run. Hard limit: 200000.",
            "default": 200000
          },
          "max_file_size_mb": {
            "title": "Max file size (MB)",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Files larger than this are skipped with a warning instead of failing the run.",
            "default": 50
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}