Check North American allocation coverage

Check allocation-table coverage

Check whether a North American number matches a prefix in MultiTEL’s allocation table, and retrieve the associated city, state and country. This is a prefix-table lookup. It does not establish that a subscriber is active, that a number is assigned, that it belongs to your account, or that you can order it.

Request

Use your enabled API account and allowed source IP address. The example uses HTTP Basic credentials from environment variables and a fictional number. No body is required.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  https://api.multitel.net/v3/nanpacheck/12025550123

Prefer an eleven-digit North American number beginning with 1. The handler strips non-digits and prepends 1 to a ten-digit input. Other digit counts are rejected. This normalization does not validate every North American numbering rule, so a successful table match is not exhaustive number validation.

Response

Illustrative field values only; this is not a live allocation-table result.

{
  "status": {
    "code": 200,
    "msg": "12025550123"
  },
  "response": {
    "number": "12025550123",
    "npanxx": "1202555",
    "city": "Example City",
    "state": "DC",
    "country": "US"
  }
}

Allocation match fields
Field	Meaning
number	Normalized digit-only input.
npanxx	The matching stored prefix. The handler prefers a seven-digit country/area/exchange prefix and can fall back to a four-digit country/area prefix; do not assume this field always identifies a full exchange.
city, state, country	Metadata for the matched allocation prefix. These fields do not identify a subscriber’s current physical location or current carrier after porting.

Errors

Read the JSON status.code rather than relying on HTTP 200 alone. API code 404 with message Not part of NANPA means no prefix matched the table used by the service; it is not a definitive global numbering-authority determination. API code 500 is used for an invalid digit count or missing number.

Cost and next steps

The reviewed handler makes a local allocation-table query and contains no account debit or external lookup. No lookup fee is applied by this handler. Use available-number search to find orderable inventory. A name lookup, routing lookup or number order is a different operation with its own account pricing.