Validate and enrich a phone number

POST/api/v1/phone

authentication: Secret API key as a bearer token
billing: 1 credit for a fresh lookup that answers `valid` true; invalid numbers and 7-day repeats are free.

Parses a number with libphonenumber metadata and answers whether it is valid for its region, its E.164, national and international formats, the country, the line type (mobile, fixed_line, fixed_line_or_mobile, voip, toll_free, …), the carrier and region where the metadata knows them, and the time zones the number belongs to. Pass country (an ISO 3166-1 alpha-2 code) to parse numbers written without a country calling code.

The phone product page is marked "coming soon"; the endpoint itself works today under the same envelope, billing and error codes as every other lookup.

Request body

field	type	description
phonerequired	string	The number, in any common notation. Include the country calling code or pass `country`. At most 32 characters.
country	string \| null	An ISO 3166-1 alpha-2 region code (`US`, `GB`, `PL`) used to parse numbers written without a calling code.

Example request

curl -X POST https://spaw.co/api/v1/phone \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+1 415 555 0142"
}'

const response = await fetch('https://spaw.co/api/v1/phone', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_…',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phone": "+1 415 555 0142"
  }),
});
const result = await response.json();

import requests

response = requests.post(
    'https://spaw.co/api/v1/phone',
    headers={'Authorization': 'Bearer sk_live_…'},
    json={
        'phone': '+1 415 555 0142'
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/phone');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'phone' => '+1 415 555 0142'
    ]),
]);
$result = json_decode(curl_exec($ch), true);

Responses

200The parsed number; `valid: false` with a `reason` for numbers that do not parse.

{
    "success": true,
    "data": {
        "valid": true,
        "reason": null,
        "e164": "+14155550142",
        "national": "(415) 555-0142",
        "international": "+1 415-555-0142",
        "country": "US",
        "line_type": "fixed_line_or_mobile",
        "carrier": null,
        "region": "San Francisco, CA",
        "extension": null,
        "timezones": [
            "America/Los_Angeles"
        ],
        "sources": [
            {
                "dataset": "libphonenumber",
                "version": "9.0.37"
            }
        ]
    },
    "meta": {
        "credits_used": 1,
        "credits_remaining": 8,
        "cache_hit": false,
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

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

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

{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "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