After choosing a country (and, for the US or Canada, optionally a state from getstates), call getareas to see where numbers are offered. Keep the area uuid for the next step.
Each area leads to one of two next steps:
- available > 0:
next_functionisv3/getprefixes/{uuid}, with?state=appended when you filtered by state. Use it to browse prefixes. - available = 0: the area has prefixes but no stock, and
next_functionisv3/order/{uuid}. See the ordering documentation for what this step requires.
available is the area-wide total, even when you filter by state. The state filter accepts a code or a full name, but works only for US and CA. If a state filter returns No areas found, try again without it. Checks run in this order: missing country code, unknown country, state filter for another country, invalid state, no matching areas. Each of these returns code 500 or 404 in status.code, without a matching HTTP status.
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 and the optional state and pid parameters in the query string. If the path segment is omitted, a form-encoded isocode field is read instead.
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'| Name | Type | Required | Description |
|---|---|---|---|
isocode | string | Yes | ISO 3166-1 alpha-2 country code. Case-insensitive; surrounding whitespace is ignored. It must be a country known to MultiTEL; the country does not need to appear in getcountries. |
| Name | Type | Required | Description |
|---|---|---|---|
state | string | No | US and CA only. Accepts a two-letter state or province code in any case, or a full name (case-insensitive; surrounding spaces ignored and repeated inner spaces collapsed), for example NY or new york. An empty value is ignored. With a state, only areas that have at least one in-stock prefix recorded for that state are returned, but available is still the area-wide total. The next_function from getstates already includes this parameter. |
pid | string | No | Advanced and optional. Narrows results to areas flagged for one inventory source that have at least one prefix from that source (stock not required), and limits available and the other statistics to that source. Use only a value provided by MultiTEL, in numeric or 32-character hexadecimal form, and omit it for normal use. Unrecognised values and values this endpoint does not accept are ignored without an error. |
Response
Standard envelope. On success, status.code is 200, status.msg is 'Results: N', status.results is N, and response is a list sorted by area name. Fields: uuid (opaque area identifier used by the next step); country_uuid (opaque 32-character country identifier, not needed later); name; area_type and number_type (catalog descriptors; entries are not necessarily local number types); country_iso; is_mobile (0 or 1, from the area's mobile flags; always 0 for US unless your account is enabled for US mobile numbers); available (total stock across the area's matching prefixes, not limited to the requested state); sms_coverage (0 or 1); returns_numbers (0 or 1, the highest flag among the area's prefixes); latitude and longitude; state_iso; next_function. state_iso: with a state filter, it is the resolved filter code. For US and CA without a filter, it is the state whose name equals the area name, otherwise the stored area value, otherwise a code derived from the area's prefix data. For other countries, it is the stored value and may be empty. next_function is 'v3/getprefixes/{uuid}' (plus '?state={code}' when filtered) when available is greater than 0, otherwise 'v3/order/{uuid}'. Areas with no matching prefix at all are omitted. Areas with prefixes but no stock are returned with available 0.
Illustrative response shape; not live account data or a current quote.
{
"status": {
"code": 200,
"msg": "Results: 2",
"results": 2
},
"response": [
{
"uuid": "0000000000000000000000000000a001",
"country_uuid": "0000000000000000000000000000c001",
"name": "Example City",
"area_type": "City",
"number_type": "Local",
"country_iso": "US",
"is_mobile": 0,
"available": 58,
"sms_coverage": 1,
"returns_numbers": 1,
"latitude": "40.0000",
"longitude": "-75.0000",
"state_iso": "NY",
"next_function": "v3/getprefixes/0000000000000000000000000000a001"
},
{
"uuid": "0000000000000000000000000000a002",
"country_uuid": "0000000000000000000000000000c001",
"name": "Sample Town",
"area_type": "City",
"number_type": "Local",
"country_iso": "US",
"is_mobile": 0,
"available": 0,
"sms_coverage": 0,
"returns_numbers": 0,
"latitude": "41.0000",
"longitude": "-76.0000",
"state_iso": "PA",
"next_function": "v3/order/0000000000000000000000000000a002"
}
]
}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.
- 404: msg 'Error: no such country': the country code is unknown. No matching HTTP status is set.
- 404: msg 'State filter is only available for US and CA': a non-empty state was sent for another country. No matching HTTP status is set.
- 404: msg 'Invalid state': state is neither a known code nor a known name for the country. No matching HTTP status is set.
- 404: msg 'No areas found': no area matches the country, source and state filters. No matching HTTP status is set.
- 401: Authentication missing or failed. Sent with HTTP status 401.
Availability and side effects
- Lookup only for customer accounts. It does not reserve, order or change anything.
- available is informational and can change before the next step.