List US states or Canadian provinces with numbers in stock

Use this optional step for the United States or Canada to narrow discovery by state or province. Only US and CA are accepted.

Each entry describes in-stock prefixes for that state at the time of the request.
Follow next_function to list the state's areas. It already includes the state filter but not pid.
State information is matched slightly differently by the area lookup. If a state's next_function returns No areas found, call getareas without a state instead.
Check status.code before reading response. An unsupported country, or a country with no matching stock, returns code 404 without a matching HTTP status.
An empty list with code 200 means stock exists but carries no state information. Call getareas without a state.

Request

Required: HTTP Basic or Bearer token (see Authentication and API responses). Failed authentication is answered with HTTP 401 before the lookup runs.

GET with isocode in the path. If the path segment is omitted, a form-encoded isocode field is read instead. The optional pid is sent in the query string.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getstates/US'

Path parameters
Name	Type	Required	Description
`isocode`	string	Yes	US or CA. Case-insensitive; surrounding whitespace is ignored.

Query parameters
Name	Type	Required	Description
`pid`	string	No	Advanced and optional. Restricts the counted prefixes to one inventory source. Use only a value provided by MultiTEL, in numeric or 32-character hexadecimal form, and omit it for normal use. Without pid, all sources currently offered for discovery are counted. Unrecognised values are ignored without an error. If the selected source has no in-stock prefixes available to your account, the result is 'No states found'.

Response

Standard envelope. On success, status.code is 200, status.msg is empty, and status.results is the number of entries. response is a list sorted by name (case-insensitive), then by state code. Fields: state (state or province code taken from the prefixes' state data, normally two letters; uncommon values are passed through unchanged); name (catalog name, or the code when the catalog has no name for it); country_iso; available (total stock across the counted prefixes, always greater than 0); prefix_count (number of in-stock prefixes counted); is_mobile (1 if any counted prefix is mobile-capable; always 0 for US unless your account is enabled for US mobile numbers); sms_coverage (1 if any counted prefix has SMS coverage); returns_numbers (1 if any counted prefix has the returns-numbers flag or no value for it); next_function ('v3/getareas/{isocode}?state={state}'). If in-stock prefixes exist but none carries state information, the result is status.code 200 with an empty list and status.results 0.

Illustrative response shape; not live account data or a current quote.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 2
  },
  "response": [
    {
      "state": "NY",
      "name": "New York",
      "country_iso": "US",
      "available": 120,
      "prefix_count": 8,
      "is_mobile": 0,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=NY"
    },
    {
      "state": "TX",
      "name": "Texas",
      "country_iso": "US",
      "available": 45,
      "prefix_count": 3,
      "is_mobile": 0,
      "sms_coverage": 0,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=TX"
    }
  ]
}

Errors

500: msg 'ISO Code parameter is required': isocode is missing or blank. This is a correctable request error. No matching HTTP status is set; read status.code.
404: msg 'getstates is only available for US and CA': any other country code. No matching HTTP status is set.
404: msg 'No states found': no in-stock prefixes match the country and source filters. No matching HTTP status is set.
401: Authentication missing or failed. Sent with HTTP status 401.

Availability and side effects

Lookup only. It does not reserve, order or change anything. available is informational and does not hold numbers.