1. Authentication & Balance Endpoints
Generate keys in /app/api-keys. Keys starting xnc_test_ run deterministic sandbox lookups for £0.00; keys starting xnc_live_ execute live register and SS7 carrier queries.
GET /api/v2/authorised
Authorization: Bearer xnc_live_your_key
# 200 OK
{ "authorised": true, "workspace": "Severn Comms Ltd", "mode": "live" }
GET /api/v2/balance
Authorization: Bearer xnc_live_your_key
# 200 OK
{
"currency": "GBP",
"balance_gbp": 108.00,
"estimated_checks_remaining": { "tps_ctps": 113684, "hlr_mnp": 51428 }
}
2. Synchronous Single Lookup (POST /api/v2)
Pass any UK phone format (07700 900461, +447700900461, 447700900461) and an array of checks: "Tps", "Ctps", "Hlr", "Mnp", "Landline", "Email" or "Auto".
POST /api/v2
Authorization: Bearer xnc_live_your_key
Content-Type: application/json
{
"lookup": "07700 900461",
"checks": ["Tps", "Ctps", "Hlr", "Mnp"]
}
# 200 OK (~210ms)
{
"valid": true,
"live_status": "LIVE",
"verdict": "SAFE_TO_CALL",
"verdict_reason": "Clear of checked registers and valid on network",
"e164": "447700900461",
"national": "07700900461",
"tps": { "tps": false, "ctps": false },
"hlr": { "status": "LIVE", "valid": true, "on": true, "mcc": 234, "mnc": 30, "plmn": "23430", "networkName": "EE (BT Group)" },
"mnp": {
"isPorted": true,
"original": { "mcc": 234, "mnc": 10, "networkName": "Virgin Media O2" },
"current": { "mcc": 234, "mnc": 30, "networkName": "EE (BT Group)" }
},
"credits_charged_gbp": 0.00305
}
3. Batch Cleansing API (POST /api/v2/batch)
Submit up to 25,000 rows per batch as text/csv or JSON records, then download clean, suppressed or all CSV splits.
POST /api/v2/batch
Authorization: Bearer xnc_live_your_key
Content-Type: application/json
{
"filename": "monday-campaign.csv",
"checks": ["Tps", "Ctps", "Hlr", "Mnp"],
"records": ["07700900461", "01743598025", "02079460821"]
}
# Download clean dialler CSV:
GET /api/v2/batch/{batch_id}/download?split=clean