Queue a bulk phone lookup run

Queues up to 100,000 numbers and processes them in the background. Creation answers 202 with the job's id and status. Poll GET /api/v1/phone/bulk/{jobId} for progress, then download the result CSV from GET /api/v1/phone/bulk/{jobId}/results: one row per input number with every response field as a column. Jobs and their files are kept for 30 days.

Rows repeating a number already in the list (as submitted) are looked up once and counted in duplicate_count. A run that exhausts the balance stops with stopped_reason: "insufficient_credits" and keeps everything answered so far. Because nothing about a phone lookup is stored, the input list and the result file are the only copies and both are deleted with the job. country applies to every row; the live carrier-network check is single lookups only.

With a webhook_url, the finish (completed, failed, or cancelled) is POSTed there as { "event": "bulk_phone_job.finished", "job": { … } }, signed with webhook_secret exactly like bulk email and IP runs: X-Spaw-Signature-V2 carries t={unix seconds},v2={lowercase hex}, the HMAC-SHA256 of v2:{t}:{raw body}, and a receiver should refuse a t more than five minutes from its own clock so a captured delivery cannot be replayed at it later. The original X-Spaw-Signature, over the body alone, is sent beside it until 1 March 2027. Send an Idempotency-Key header to make creation safe to retry: a repeat of the same request answers the job the first attempt created, as 200 with Idempotent-Replayed: true; the same key with a different request answers 409 IDEMPOTENCY_KEY_REUSED.

Reading a list before you start it

Send preview: true with the same body — or csv with a raw CSV instead of the item list — and the call answers 200 with data.draft instead of queueing anything: what the list was read as, which column filled which field and whether a heading named it or we guessed, the first rows as parsed, the repeats, the balance, and credits_upper_bound. Nothing is charged.

credits_upper_bound is a CEILING, not a quote. Rows come back free for reasons no preview can know in advance — a repeat inside the seven-day window, an entry on your suppression list, a verdict that is not charged for, a provider outage — so a run usually costs less than the ceiling and never more. It is priced against the mapping in play, so correcting a column at start re-prices the run rather than holding you to the figure the guess produced — ask for the draft again after a correction if you want the new number. What it actually cost is credits_used on the finished job.

Start it with {"draft_id": <id>}, adding mapping to correct a column we read wrongly. Starting consumes the draft; one left unstarted is deleted, with the rows it holds, after retention_hours.

curl -X POST https://spaw.co/api/v1/phone/bulk \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "phones": [
    "+1 415 555 0142",
    "(415) 555-0143"
  ],
  "country": "US",
  "webhook_url": "https://example.com/hooks/spaw"
}'

const response = await fetch('https://spaw.co/api/v1/phone/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_…',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phones": [
      "+1 415 555 0142",
      "(415) 555-0143"
    ],
    "country": "US",
    "webhook_url": "https://example.com/hooks/spaw"
  }),
});
const result = await response.json();

import requests

response = requests.post(
    'https://spaw.co/api/v1/phone/bulk',
    headers={'Authorization': 'Bearer sk_live_…'},
    json={
        'phones': [
            '+1 415 555 0142',
            '(415) 555-0143'
        ],
        'country': 'US',
        'webhook_url': 'https://example.com/hooks/spaw'
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/phone/bulk');
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' => [
            '+1 415 555 0142',
            '(415) 555-0143'
        ],
        'country' => 'US',
        'webhook_url' => 'https://example.com/hooks/spaw'
    ]),
]);
$result = json_decode(curl_exec($ch), true);

from spaw import Client

client = Client('sk_live_…')
result = client.create_phone_bulk_job([
    '+1 415 555 0142',
    '(415) 555-0143'
], country='US', webhook_url='https://example.com/hooks/spaw')

import Spaw from 'spaw';

const spaw = new Spaw({ apiKey: 'sk_live_…' });
const result = await spaw.createPhoneBulkJob([
    '+1 415 555 0142',
    '(415) 555-0143'
], {
    country: 'US',
    webhookUrl: 'https://example.com/hooks/spaw'
});

use Spaw\Client;

$spaw = new Client('sk_live_…');
$result = $spaw->createPhoneBulkJob([
    '+1 415 555 0142',
    '(415) 555-0143'
], country: 'US', webhookUrl: 'https://example.com/hooks/spaw');

{
    "success": true,
    "data": {
        "job": {
            "id": 733,
            "status": "queued",
            "total": 2,
            "duplicate_count": 0,
            "processed": 0,
            "valid": 0,
            "invalid": 0,
            "low": 0,
            "medium": 0,
            "high": 0,
            "credits_used": 0,
            "stopped_reason": null,
            "cancel_requested": false,
            "country": "US",
            "webhook_status": null,
            "created_at": "2026-09-04T10:12:44+00:00",
            "finished_at": null,
            "webhook_secret": "8fJ2…40 characters…Qk1"
        }
    }
}

{
    "success": true,
    "data": {
        "job": {
            "id": 733,
            "status": "processing",
            "total": 2,
            "duplicate_count": 0,
            "processed": 1,
            "valid": 1,
            "invalid": 0,
            "low": 0,
            "medium": 0,
            "high": 1,
            "credits_used": 1,
            "stopped_reason": null,
            "cancel_requested": false,
            "country": "US",
            "webhook_status": null,
            "created_at": "2026-09-04T10:12:44+00:00",
            "finished_at": null
        }
    }
}

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

{
    "success": false,
    "error": {
        "code": "IDEMPOTENCY_KEY_REUSED",
        "message": "This Idempotency-Key was already used for a different request.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

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

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