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, cache_hit, suppressed and opted_out.

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 key with a daily credit cap stops the list the same way once the cap is spent: the numbers already paid for come back with meta.stopped_reason: "key_spend_cap", and a call that starts with the cap already spent answers 429 KEY_SPEND_CAP_REACHED and runs nothing. 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. hlr: true adds the live carrier-network check to every item: the premium credits are reserved per item before its lookup and charged only where the network answered. call_window answers in_call_window for every item.

Every item carries index, its zero-based position in the list you sent, and input, the number exactly as you sent it — the answer's e164 is what the plan made of it. A batch stopped early by stopped_reason answers only a prefix of the list, so those two are what line an answer up with the row it came from.

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 64 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 under the single-lookup rules (free where the account paid for that number's check in the last 7 days and the network's answer is still held), and the balance is gated per item before any network query. Default: .
call_window	string \| null	Your calling window in each number's local time, "HH:MM-HH:MM" from the start up to, not including, the end (a window may run past midnight), applied to every item. Answers `in_call_window`; the zone is where the number was issued, not where the person is, and the answer is arithmetic, not compliance advice.

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 3013 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 3013 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 3013 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 3013 0018',
                'country' => 'GB'
            ],
            'not a number'
        ],
        'country' => 'US'
    ]),
]);
$result = json_decode(curl_exec($ch), true);

from spaw import Client

client = Client('sk_live_…')
result = client.validate_phones([
    '(415) 555-0142',
    {
        'phone': '020 3013 0018',
        'country': 'GB'
    },
    'not a number'
], country='US')

import Spaw from 'spaw';

const spaw = new Spaw({ apiKey: 'sk_live_…' });
const result = await spaw.validatePhones([
    '(415) 555-0142',
    {
        phone: '020 3013 0018',
        country: 'GB'
    },
    'not a number'
], {
    country: 'US'
});

use Spaw\Client;

$spaw = new Client('sk_live_…');
$result = $spaw->validatePhones([
    '(415) 555-0142',
    [
        'phone' => '020 3013 0018',
        'country' => 'GB'
    ],
    'not a number'
], country: 'US');

This endpoint has no console on its page. It bills once per item in the list, so what one run costs depends on what you paste in. The single-value endpoint for the same signal is runnable instead.

Responses

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

{
    "success": true,
    "data": {
        "results": [
            {
                "index": 0,
                "input": "(415) 555-0142",
                "data": {
                    "valid": true,
                    "reason": null,
                    "e164": "+14155550142",
                    "country": "US",
                    "line_type": "fixed_line_or_mobile",
                    "is_fictional": true,
                    "risk_score": 80,
                    "risk_level": "high",
                    "ok_to_send": false,
                    "blocked_by": "fictional"
                },
                "meta": {
                    "credits_used": 1,
                    "cache_hit": false,
                    "suppressed": false,
                    "opted_out": false
                }
            },
            {
                "index": 1,
                "input": "020 3013 0018",
                "data": {
                    "valid": false,
                    "reason": "unassigned_block",
                    "e164": "+442030130018",
                    "country": "GB",
                    "block_status": "unassigned",
                    "is_fictional": false,
                    "risk_score": null,
                    "risk_level": null,
                    "ok_to_send": false,
                    "blocked_by": "invalid"
                },
                "meta": {
                    "credits_used": 0,
                    "cache_hit": false,
                    "suppressed": false,
                    "opted_out": false
                }
            },
            {
                "index": 2,
                "input": "not a number",
                "data": {
                    "valid": false,
                    "reason": "not_a_number",
                    "e164": null,
                    "country": null,
                    "risk_score": null,
                    "risk_level": null,
                    "ok_to_send": false,
                    "blocked_by": "invalid"
                },
                "meta": {
                    "credits_used": 0,
                    "cache_hit": false,
                    "suppressed": false,
                    "opted_out": 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