Change a monitor

PATCH/api/v1/phone/monitors/{monitorId}

authentication: Secret API key as a bearer token
billing: Free. The change applies to the next run.

Changes a saved monitor in place: rename it, move it to another cadence, replace the numbers, or point it at a webhook. Send only the fields you are changing; a body that names none of them answers 422 rather than quietly changing nothing, because that is the shape a misspelled field name takes.

Replacing numbers replaces the list. What the last run recorded about the numbers that stayed is kept, so their next run still compares against the answer they already had; what it recorded about the ones that are gone is deleted with them; and an entry that is new starts with no baseline, so its first run only sets one. A rename never touches a stored answer — they are keyed by the entry, never by the list.

Changing cadence neither skips a run nor starts a second one: a run already scheduled sooner than the new interval still happens, and a longer interval applies from the one after it. Nothing is queued by this call — the change applies to the next run, and POST .../run is there to have it now.

Sending a webhook_url that differs from the one stored mints a new signing secret and returns it once, here; sending the URL it already has keeps the secret it is signing with, and null removes the webhook. A monitor that belongs to another account answers 404.

Parameters

name	in	type	description
monitorIdrequired	path	integer	The monitor's id from the list endpoint.

Request body

field	type	description
name	string	At most 100 characters.
numbers	string[]
cadence	string	One of: weekly, monthly.
country	string \| null	The region numbers written without a calling code are read against.
live_check	boolean
webhook_url	string \| null	At most 2,048 characters.
webhook_events	string	One of: changes, every_run.

Example request

curl -X PATCH https://spaw.co/api/v1/phone/monitors/41 \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "SMS audience (EU)",
  "country": "DE"
}'

const response = await fetch('https://spaw.co/api/v1/phone/monitors/41', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer sk_live_…',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "SMS audience (EU)",
    "country": "DE"
  }),
});
const result = await response.json();

import requests

response = requests.patch(
    'https://spaw.co/api/v1/phone/monitors/41',
    headers={'Authorization': 'Bearer sk_live_…'},
    json={
        'name': 'SMS audience (EU)',
        'country': 'DE'
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/phone/monitors/41');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'SMS audience (EU)',
        'country' => 'DE'
    ]),
]);
$result = json_decode(curl_exec($ch), true);

from spaw import Client

client = Client('sk_live_…')
result = client.update_phone_monitor(41, name='SMS audience (EU)', country='DE')

import Spaw from 'spaw';

const spaw = new Spaw({ apiKey: 'sk_live_…' });
const result = await spaw.updatePhoneMonitor(41, {
    name: 'SMS audience (EU)',
    country: 'DE'
});

use Spaw\Client;

$spaw = new Client('sk_live_…');
$result = $spaw->updatePhoneMonitor(41, [
    'name' => 'SMS audience (EU)',
    'country' => 'DE'
]);

This endpoint has no console on its page. It writes to your account. A documentation page can show you the request; making the change is for the dashboard or for a call you make yourself.

Responses

200The monitor as it now stands.

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"
    }
}

404No such record on this account.

{
    "success": false,
    "error": {
        "code": "NOT_FOUND",
        "message": "No record with that id on this account.",
        "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