# Report a number range from the regulator's table

`GET /api/v1/phone/block/{country}/{prefix}`

- Authentication: Secret API key as a bearer token
- Billing: 1 credit per answered report, free for the next seven days for the same prefix. A prefix or country with nothing to report costs nothing.
- Group: Phone

What the national regulator's own allocation table says about every block under one prefix: how many blocks are allocated, unassigned or reserved, who holds them and what share each holds, how much of the range is mobile or VoIP, and the place, time zones and line types the numbering plan names for it. Original allocation only — never who serves a number today, which no open table publishes.

It is the endpoint behind the public area-code pages, so screening a whole area code before a campaign, or checking a range a signup wave arrived from, is one call rather than a page scrape. `country` is an ISO 3166-1 alpha-2 code and `prefix` the digits of the range in national notation, with no calling code: `/v1/phone/block/us/415`, `/v1/phone/block/gb/020`. A longer prefix narrows the report to the blocks underneath it.

A country whose numbering plan Spaw does not carry — including a region whose numbers live in another's table, as the Crown dependencies do under GB — and a prefix no block starts with both answer `404 PHONE_BLOCK_NOT_FOUND` and cost nothing.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `country` | path | string | yes | An ISO 3166-1 alpha-2 code, in either case. 2 to 2 characters. |
| `prefix` | path | string | yes | The range in national notation, digits only and no calling code. |

## Example request

```bash
curl https://spaw.co/api/v1/phone/block/us/415 \
  -H "Authorization: Bearer sk_live_…"
```

## Responses

### 200 — The report for that range.

```json
{
    "success": true,
    "data": {
        "country": "US",
        "country_name": "United States",
        "calling_code": 1,
        "prefix": "415",
        "international_prefix": "+1 415",
        "place": "San Francisco, CA",
        "timezones": [
            "America/Los_Angeles"
        ],
        "line_types": [
            "fixed_line_or_mobile"
        ],
        "example": "+1 415-200-0000",
        "blocks": {
            "total": 792,
            "allocated": 604,
            "unassigned": 171,
            "reserved": 17
        },
        "block_length": 6,
        "kinds": {
            "mobile": 41.2,
            "voip": 12.7,
            "unsettled": 46.1
        },
        "holders": [
            {
                "holder": "PACIFIC BELL",
                "kind": null,
                "blocks": 96,
                "share": 15.9
            },
            {
                "holder": "T-MOBILE USA, INC.",
                "kind": "mobile",
                "blocks": 71,
                "share": 11.8
            }
        ],
        "feed": {
            "key": "nanpa",
            "dataset": "nanpa-co-codes",
            "version": "2026-09-04",
            "complete": true
        }
    },
    "meta": {
        "credits_used": 1,
        "credits_remaining": 9,
        "cache_hit": false,
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

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

### 402 — The balance is empty. The lookup did not run.

```json
{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 404 — No numbering plan covers the country, or no block starts with the prefix. Nothing was charged.

```json
{
    "success": false,
    "error": {
        "code": "PHONE_BLOCK_NOT_FOUND",
        "message": "No number block in US starts with 999.",
        "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
- `INSUFFICIENT_CREDITS` — https://spaw.co/docs/errors/INSUFFICIENT_CREDITS
- `PHONE_BLOCK_NOT_FOUND` — https://spaw.co/docs/errors/PHONE_BLOCK_NOT_FOUND
- `RATE_LIMITED` — https://spaw.co/docs/errors/RATE_LIMITED

---

Canonical page: https://spaw.co/docs/api/phone-block-report · OpenAPI document: https://spaw.co/openapi.json · All endpoints: https://spaw.co/docs/api