Developer Reference · REST JSON & CSV

REST API v2 Documentation

Authenticate with Authorization: Bearer xnc_live_.... Synchronous single lookups accept the same lookup and checks payload as DataSoap v2 so existing integrations migrate in minutes.

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