Monitor a phone list on a schedule

Saves up to 500 numbers and re-checks them every week or every month. The first run starts right away and only sets the baseline; from the next run on, every number that was valid last time and is now invalid, in a block nobody holds or unreachable counts as decayed and is reported to the account's email; a number you suppressed yourself (an import, your own failure or abuse reports, an opt-out) answers suppressed and is not decay. A number that still answers valid but changed is flagged and reported in a second email: an SMS-receiving website started listing it, three or more accounts reported abuse, its risk rose to high, or its line type changed — and with the live check on, it was ported or another network serves it (see PhoneMonitorFlag; this is not SIM-swap detection). Runs honour the suppression list and the 7-day repeat cache. With live_check true, runs ask for the live carrier check whenever the service has it enabled, so decay also covers handsets that stopped answering. There is no daily cadence: most regulator tables behind a run refresh weekly (NANPA's and the SMS-receiving lists daily), a weekly run already catches a change within days, and a daily live check would pay for the network seven times a week.

Answers 201 with the monitor. The baseline run is queued, not finished: poll the monitor for last_run_at and last_summary.

With a webhook_url, a finished run is POSTed there as { "event": "phone_monitor.run", "monitor": { "id", "name", "cadence", "last_run_at", "next_run_at" }, "summary": { … the same block as last_summary … }, "changes": [ … ], "flags": { … } }, where changes names the numbers the two alert emails name — decayed and newly flagged, in list order, each once — and flags maps each newly flagged number to the flags it raised ({} when none did). The X-Spaw-Signature-V2 header carries t={unix seconds},v2={lowercase hex}, where the hex is the HMAC-SHA256 of v2:{t}:{raw body} keyed with webhook_secret, which this response returns once; a receiver should refuse anything whose t is more than five minutes from its own clock, since a signature over the body alone would let a captured delivery be replayed at it forever. The original X-Spaw-Signature, that HMAC of the body alone, is sent beside it until 1 March 2027. Connection errors and 5xx answers are retried twice with a short backoff, three attempts in all, and the outcome is readable afterwards as webhook_status and webhook_detail. A URL that resolves onto a private network is never posted to.

curl -X POST https://spaw.co/api/v1/phone/monitors \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "SMS audience",
  "numbers": [
    "+44 7911 012345",
    "020 3013 0018"
  ],
  "cadence": "monthly",
  "country": "GB"
}'

const response = await fetch('https://spaw.co/api/v1/phone/monitors', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_…',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "SMS audience",
    "numbers": [
      "+44 7911 012345",
      "020 3013 0018"
    ],
    "cadence": "monthly",
    "country": "GB"
  }),
});
const result = await response.json();

import requests

response = requests.post(
    'https://spaw.co/api/v1/phone/monitors',
    headers={'Authorization': 'Bearer sk_live_…'},
    json={
        'name': 'SMS audience',
        'numbers': [
            '+44 7911 012345',
            '020 3013 0018'
        ],
        'cadence': 'monthly',
        'country': 'GB'
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/phone/monitors');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'SMS audience',
        'numbers' => [
            '+44 7911 012345',
            '020 3013 0018'
        ],
        'cadence' => 'monthly',
        'country' => 'GB'
    ]),
]);
$result = json_decode(curl_exec($ch), true);

from spaw import Client

client = Client('sk_live_…')
result = client.create_phone_monitor(name='SMS audience', numbers=[
    '+44 7911 012345',
    '020 3013 0018'
], cadence='monthly', country='GB')

import Spaw from 'spaw';

const spaw = new Spaw({ apiKey: 'sk_live_…' });
const result = await spaw.createPhoneMonitor({
    name: 'SMS audience',
    numbers: [
        '+44 7911 012345',
        '020 3013 0018'
    ],
    cadence: 'monthly',
    country: 'GB'
});

use Spaw\Client;

$spaw = new Client('sk_live_…');
$result = $spaw->createPhoneMonitor(name: 'SMS audience', numbers: [
    '+44 7911 012345',
    '020 3013 0018'
], cadence: 'monthly', country: 'GB');

{
    "success": true,
    "data": {
        "monitor": {
            "id": 7,
            "name": "SMS audience",
            "cadence": "monthly",
            "number_count": 2,
            "country": "GB",
            "live_check": false,
            "next_run_at": "2026-10-05T10:12:44+00:00",
            "last_run_at": null,
            "last_summary": null,
            "created_at": "2026-09-05T10:12:44+00:00"
        }
    }
}

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "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"
    }
}