Documentation

Validate phone numbers with normalization to E.164, country & type detection, assignment checks, heuristics and risk scoring.

Endpoint

POST https://api.numgate.com/v1/validate
Accept: application/json
Content-Type: application/json
X-API-Key: <YOUR_API_KEY>

Request body

{
  "phone": "+12025550123"
}

Successful response

{
  "success": true,
  "data": {
    "result": {
      "input": "+12025550123",
      "normalized": "+12025550123",
      "valid": true,
      "country": { "code": "US", "callingCode": "+1" },
      "type": "FIXED_LINE_OR_MOBILE",
      "assignment": { "status": "assigned_with_operator", "source": "nanp:npa-nxx", "operator": "MULTIPLE OCN LISTING", "operatorSource": "nanpa" },
      "heuristics": { "improbable_pattern": false, "toll_free_nanp": false },
      "risk": { "score": 100, "bucket": "high_confidence" }
    },
    "quota": { "remaining": 720 }
  }
}

cURL

curl -X POST https://api.numgate.com/v1/validate \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "phone": "+12025550123" }'

Node (fetch)

const res = await fetch("https://api.numgate.com/v1/validate", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "X-API-Key": process.env.NG_API_KEY
  },
  body: JSON.stringify({ phone: "+12025550123" })
});
const json = await res.json();

Python (requests)

import requests
r = requests.post("https://api.numgate.com/v1/validate",
  headers={"Accept":"application/json","Content-Type":"application/json","X-API-Key":"<YOUR_API_KEY>"},
  json={"phone":"+12025550123"})
print(r.json())

Status & errors

• 200 OK — request processed.
• 401 Unauthorized — missing/invalid API key.
• 429 Too Many Requests — rate limit exceeded.
• 4xx — validation error (malformed input).
• 5xx — temporary service error, retry with backoff.

Limits

• Intro 1000: 1–2 RPS
• Starter: up to 5 RPS
• Growth: up to 20 RPS
• Business: up to 50 RPS