Before you start
Choose an area using getareas. Copy the area ID from its response or returned next_function. For a US or Canadian area, use getstates if you want to narrow the results to one state or province.
Read the result
Check status.code in the JSON body as well as the HTTP status. Successful results are in the response array. The default response is sorted by name. available is an estimate, and catalogue flags do not replace checking the selected number's actual capabilities and registration requirements.
Select the next step
Use an ungrouped result. When returns_numbers is 1, the returned next_function points to a number search. When it is 0, numbers are assigned at order time and the path points to an ordering operation. Inspect the operation and its requirements before sending it: an ordering request can charge your account. Do not automatically issue every returned path.
No price is included here. Review the relevant quote, required documents and ordering instructions before purchasing. Preserve the returned individual prefix and quote IDs instead of constructing them from a displayed telephone prefix.
Advanced display options
compact=1 returns a shuffled sample of at most 100 rows, not a page of a larger result set. Grouping creates summary rows and synthetic IDs; use an ordinary ungrouped response to select an individual prefix. Do not use sampled or grouped results to claim exhaustive inventory or exact capabilities.
Request
Use your enabled API account credentials over HTTPS. Basic authentication and enabled API-account bearer tokens are supported; account restrictions apply.
Use GET and send optional parameters in the query string. Do not depend on form-body fallback.
curl --fail-with-body --silent --show-error \
--user "$API_USER:$API_PASSWORD" \
"https://api.multitel.net/v3/getprefixes/$AREA_ID?state=NY"| Name | Type | Required | Description |
|---|---|---|---|
area_id | string | Yes | Copy the area identifier from getareas or its next_function. Treat it as an opaque value; do not construct or hash it yourself. |
| Name | Type | Required | Description |
|---|---|---|---|
state | string | No | US and CA areas only. Use a state/province code from getstates, or its full name. Codes are case-insensitive; names ignore case and repeated whitespace. Another country or an unrecognized nonempty value returns an API error. |
compact | string | No | Optional sample mode: 1, true or on. Results are shuffled, with at most 100 rows. Omit this parameter for a complete result list; there is no page/cursor in this endpoint. |
group | integer | No | Advanced display summaries: values 1 through 6 combine rows and return masked display prefixes. Group UUIDs are synthetic and are not interchangeable with individual prefix IDs. Make an ungrouped request before selecting a prefix for a number search or order. Omit this parameter for the normal workflow. |
pid | string | No | Optional inventory selector supplied by MultiTEL, in numeric or supported 32-character hexadecimal form. Omit it for normal use. Unrecognized values are silently ignored. The value is not a phone prefix or price-plan ID. |
Response
The standard status/response JSON envelope. status.results counts the returned rows, including sampling or grouping. response contains prefix objects. No price fields are returned. In the ordinary ungrouped response, uuid is the prefix ID; area_uuid and country_uuid are returned identifiers; prefix and name are display information; available is an availability estimate rather than a reservation; needs_registration and restrictions describe registration information; sms_coverage, is_mobile and number_type are catalogue hints, not a guarantee of a particular number capability. number_type may be empty or another catalogue string, so do not require a fixed enum. state is a string and may be empty or contain catalogue formatting. latitude and longitude may be empty. metered and overflow are catalogue flags, not monetary amounts. returns_numbers selects a number-listing route (1) or an order-time assignment route (0). next_function identifies that next route. Grouped responses additionally contain merged features, including fallback feature values; do not interpret these as verified capabilities of every number.
Illustrative response shape; not live account data or a current quote.
{
"status": {
"code": 200,
"msg": "",
"results": 1
},
"response": [
{
"uuid": "PREFIX_ID_FROM_RESPONSE",
"area_uuid": "AREA_ID_FROM_RESPONSE",
"country_uuid": "COUNTRY_ID_FROM_RESPONSE",
"prefix": "+1212",
"name": "Example area",
"metered": 0,
"overflow": 0,
"needs_registration": 0,
"restrictions": "",
"state": "NY",
"country_iso": "US",
"is_mobile": 0,
"number_type": "local",
"latitude": "",
"longitude": "",
"available": 12,
"sms_coverage": 1,
"returns_numbers": 1,
"next_function": "v3/getnumbers/PREFIX_ID_FROM_RESPONSE"
}
]
}Errors
- 404: Invalid area ID: obtain a current area ID from discovery.
- 404: State filter is only available for US and CA: omit state for other countries.
- 404: Invalid state: use a state/province returned by getstates for this country.
- 404: No prefixes found: no matching catalogue rows were returned. This does not prove that a particular number can never be ordered.
- 500: Error: 'Failed loading prefixes': the catalogue lookup failed. Retry later and contact support if it persists.
Availability and side effects
- This is a discovery step, not an order confirmation. Availability may be refreshed using further catalogue lookups, so response latency can vary.
- Prices are not returned. Retrieve the applicable number or order quote and review registration requirements before placing an order.
- Do not treat available as a precise stock count, zero as a universal ordering prohibition, or a successful lookup as a reservation. Availability can change before ordering.