# Monitor a list of addresses on a schedule

`POST /api/v1/address/monitors`

- Authentication: Secret API key as a bearer token
- Billing: Creation is free. Each run bills every address like a single lookup: 1 credit for a fresh answer that stands as written; addresses that cannot, and 7-day repeats, are free. With `deliverability`, the premium is added only where the licensed partner answered.
- Group: Address

Saves up to 500 addresses — your own sites, a supplier's registered offices, the delivery addresses behind an order book — and re-checks them every week or month. There is no daily cadence: the national registers and postcode directories behind an address answer are refreshed weekly at best, so a daily run would bill for data that cannot have changed.

Each item is a written address as a plain string, or an object of the same fields the single lookup takes, and may name its own `country`; the list-level `country` applies to the rest. The first run starts right away and only sets the baseline. From the next run on, every address that newly leaves the national register, has its postcode terminated, becomes a mail drop, starts scoring high, or stops standing as written is reported to the account's email with the reason, so a customer's address goes stale in your inbox rather than in your post room.

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

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | A label for the alerts. At most 100 characters. |
| `addresses` | string[] | yes | 1 to 500 addresses. Each item is a written address as a string, or an object of the same fields the single lookup takes. |
| `addresses[].address` | string | null | no | The whole address written as it would be on an envelope. At most 500 characters. |
| `addresses[].address_line1` | string | null | no | The street line, when the address arrives separated. At most 255 characters. |
| `addresses[].address_line2` | string | null | no | At most 255 characters. |
| `addresses[].organization` | string | null | no | At most 200 characters. |
| `addresses[].dependent_locality` | string | null | no | At most 100 characters. |
| `addresses[].locality` | string | null | no | At most 100 characters. |
| `addresses[].administrative_area` | string | null | no | At most 100 characters. |
| `addresses[].postal_code` | string | null | no | At most 32 characters. |
| `addresses[].po_box` | string | null | no | At most 64 characters. |
| `addresses[].country` | string | null | no | This item's own country. Wins over the list-level one. At most 2 characters. |
| `cadence` | string | yes | How often the list is re-checked. There is no daily cadence. One of: weekly, monthly. |
| `country` | string | null | no | An ISO 3166-1 alpha-2 code applied to every entry that does not name its own. At most 2 characters. |
| `deliverability` | boolean | no | Ask the licensed partner whether post arrives at every address on every run. While no partner is enabled it answers `deliverability_checked` false at no extra cost. Default: . |

## Example request

```bash
curl -X POST https://spaw.co/api/v1/address/monitors \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Supplier offices",
  "addresses": [
    "221B Baker Street, London, NW1 6XE",
    {
      "address_line1": "10 Downing Street",
      "locality": "London",
      "postal_code": "SW1A 2AA"
    }
  ],
  "cadence": "monthly",
  "country": "GB"
}'
```

## Responses

### 201 — The monitor was saved and its baseline run queued.

```json
{
    "success": true,
    "data": {
        "monitor": {
            "id": 9,
            "name": "Supplier offices",
            "cadence": "monthly",
            "address_count": 2,
            "country": "GB",
            "deliverability": 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"
        }
    }
}
```

### 401 — The key is missing, malformed, or revoked.

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

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

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

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

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

## Error codes

- `UNAUTHENTICATED` — https://spaw.co/docs/errors/UNAUTHENTICATED
- `VALIDATION_FAILED` — https://spaw.co/docs/errors/VALIDATION_FAILED
- `RATE_LIMITED` — https://spaw.co/docs/errors/RATE_LIMITED

---

Canonical page: https://spaw.co/docs/api/create-address-monitor · OpenAPI document: https://spaw.co/openapi.json · All endpoints: https://spaw.co/docs/api