Validate up to 1,000 numbers in one call

POST/api/v1/phone/batch

authentication: Secret API key as a bearer token
billing: Each number bills like a single lookup: 1 credit for a fresh valid answer; invalid numbers and 7-day repeats are free. The call stops cleanly where the balance ends.

Runs the single-number lookup for every item, in input order, under the exact single-lookup billing rules. Every answer comes from local metadata and the synced regulator tables, so a full batch of 1,000 takes well under a second. data.results[] mirrors the single-number response per item and each item's meta carries credits_used and cache_hit.

Repeats inside the list are looked up once and answer as cache hits. The list is walked in order and stops where the balance would run out: running out of credits mid-batch returns the paid partial results with meta.stopped_reason: "insufficient_credits" and processed lower than requested, never discarding billed work. Only a batch whose first lookup is refused answers the typed 402. A string that is not a number is an answer (valid: false), not a validation error.

A batch counts as one request against the rate limit. country applies to every number in the list that does not name its own; the live carrier-network check is available on single lookups only.

Request body

field	type	description
phonesrequired	string[]	1 to 1,000 numbers, in any common notation. Each item is a plain string, or an object carrying its own country.
phones[].phonerequired	string	The number, in any common notation. At most 32 characters.
phones[].country	string \| null	This item's own ISO 3166-1 alpha-2 region code, for a number written without a calling code. Wins over the list-level country.
country	string \| null	An ISO 3166-1 alpha-2 region code used to parse every number written without a calling code, unless the item names its own.
hlr	boolean	Ask for the live carrier check on every number. While the check is not enabled on the service it answers `hlr_checked` false at no extra cost; when it is, each item that answers is charged the premium credits, and the balance is gated per item before any network query. Default: .

Example request

curl -X POST https://spaw.co/api/v1/phone/batch \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "phones": [
    "(415) 555-0142",
    {
      "phone": "020 7946 0018",
      "country": "GB"
    },
    "not a number"
  ],
  "country": "US"
}'

const response = await fetch('https://spaw.co/api/v1/phone/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_…',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phones": [
      "(415) 555-0142",
      {
        "phone": "020 7946 0018",
        "country": "GB"
      },
      "not a number"
    ],
    "country": "US"
  }),
});
const result = await response.json();

import requests

response = requests.post(
    'https://spaw.co/api/v1/phone/batch',
    headers={'Authorization': 'Bearer sk_live_…'},
    json={
        'phones': [
            '(415) 555-0142',
            {
                'phone': '020 7946 0018',
                'country': 'GB'
            },
            'not a number'
        ],
        'country': 'US'
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/phone/batch');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'phones' => [
            '(415) 555-0142',
            [
                'phone' => '020 7946 0018',
                'country' => 'GB'
            ],
            'not a number'
        ],
        'country' => 'US'
    ]),
]);
$result = json_decode(curl_exec($ch), true);

Responses

200One result per processed number, plus the batch totals.

{
    "success": true,
    "data": {
        "results": [
            {
                "data": {
                    "valid": true,
                    "reason": null,
                    "e164": "+14155550142",
                    "country": "US",
                    "line_type": "fixed_line_or_mobile",
                    "is_fictional": true,
                    "risk_score": 80,
                    "risk_level": "high"
                },
                "meta": {
                    "credits_used": 1,
                    "cache_hit": false
                }
            },
            {
                "data": {
                    "valid": false,
                    "reason": "unassigned_block",
                    "e164": "+442079460018",
                    "country": "GB",
                    "block_status": "unassigned",
                    "is_fictional": true,
                    "risk_score": null,
                    "risk_level": null
                },
                "meta": {
                    "credits_used": 0,
                    "cache_hit": false
                }
            },
            {
                "data": {
                    "valid": false,
                    "reason": "not_a_number",
                    "e164": null,
                    "country": null,
                    "risk_score": null,
                    "risk_level": null
                },
                "meta": {
                    "credits_used": 0,
                    "cache_hit": false
                }
            }
        ]
    },
    "meta": {
        "requested": 3,
        "processed": 3,
        "credits_used": 1,
        "credits_remaining": 9,
        "stopped_reason": null,
        "request_id": "req_01m1kgdrtqdvwnks99vfgx2rcw"
    }
}

401The key is missing, malformed, or revoked.

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

402The balance is empty. The lookup did not run.

{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

422The request body could not be validated; `error.errors` lists the fields.

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

429Over 5 requests per second for the key. Retry after the limit resets.

{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

Error codes

Failures answer { success: false, error: { code, message, request_id } }. Each code has its own page.

markdown version·openapi.json