Choose an individual prefix
Use the country and area discovery calls, then getprefixes without grouping. Copy the selected prefix’s uuid. If returns_numbers is 0, the prefix assigns a number when ordered; use the returned next_function rather than requiring a list of individual numbers.
Browse a bounded batch
For a normal search, use compact=1 and put the desired batch size in both the path and quantity query, as shown below. There is no page or cursor parameter. A compact result is a sample; repeating a request does not guarantee a disjoint next page. Do not interpret an empty or small result as the total inventory count.
Find a memorable digit pattern
Supply number_filter_mode=contains or ends_with together with number_filter_value. The value must contain 1–15 digits. A search may fetch limited candidate batches before applying the filter, so it can miss other matching inventory. If you need a supported source to apply the required search, obtain a pid selector from MultiTEL and use filter_required=1; an absent or unsupported selection returns an API error.
Review the selected number
Read number, info.uuid, the selected price[].uuid, available feature names and registration requirements from the same result. The price array may offer multiple plans with different channel quantities and rates. Monetary fields and quantities can be encoded as strings. Optional metadata, including info.state, varies between sources; do not require one universal state shape or infer prices from an ID.
In the nonstreaming path, candidates are deduplicated and allocated across sources before the selected batch is sorted using the first plan’s monthly price. Other paths can stream earlier, so no global ordering or deduplication guarantee applies to every request. Sorting also does not prove the returned sample contains the cheapest number in the whole catalogue.
Order separately and confirm the result
A search does not purchase or reserve anything. Keep the returned number and plan identifiers for the ordering workflow under the same account. Review the actual plan, requirements and charges before submitting an order. Registration requirements can delay activation; no fixed activation deadline is established by a search result.
Request
Use an enabled MultiTEL API account: HTTP Basic credentials for a password account, or Authorization: Bearer with a token account. Account permissions and its IP restrictions apply. See the common authentication guidance.
Path parameters and URL query parameters. Use GET for the public search workflow. The handler also accepts selected form/request values, but it is not a JSON-body search API.
curl --fail-with-body --get \
--user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
--data-urlencode "compact=1" \
--data-urlencode "quantity=10" \
"https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"| Name | Type | Required | Description |
|---|---|---|---|
prefix_id | string | Yes | An individual prefix ID returned by an ungrouped getprefixes response. Copy it exactly; do not substitute a country, area, grouped prefix or price-plan ID. |
quantity | integer | No | Fetch target, default 1. Nonpositive values become 1. A path quantity alone is not a reliable overall result limit: an unpinned search without a quantity query can broaden its fetch and return up to 50 entries per source before other processing. For ordinary bounded browsing, use compact=1 and repeat the desired quantity in the query, as in the example. |
| Name | Type | Required | Description |
|---|---|---|---|
quantity | integer | No | Requested final batch size. Nonempty values are converted to integers, with a minimum of 1. In the unpinned nonstreaming path this limits final allocation. It does not force the service to find that many numbers. Compact searches pinned to a source may return the compact source batch instead of this limit. |
compact | string | No | Use 1, true or on for a smaller nonstreaming response, with up to 10 entries per source before final allocation. The results are a sample of currently fetched inventory, not a complete catalogue. |
number_filter_mode | string | No | Optional digit-pattern mode: contains or ends_with. Supply number_filter_value too. Results are checked against normalized phone-number digits; the search does not enumerate all inventory to guarantee every possible match. |
number_filter_value | string | No | Between 1 and 15 digits, without spaces, + or punctuation. Leading zeros are significant; send it as text. |
filter_required | string | No | Advanced: 1, true, yes or on requires a supported, explicitly selected inventory source for the filter mode. Otherwise the API returns status.code 422. This is not needed for ordinary catalogue browsing. |
pid | string | No | Advanced inventory selector supplied by MultiTEL. Numeric and supported 32-character hexadecimal forms are accepted; unrecognized values are silently ignored. Omit for normal use. Do not derive selectors from price IDs or assume an arbitrary selector is an exclusive inventory constraint. |
Response
One JSON object containing status and response. On success, status.code is 200 and response is an array of number entries. status.results is the returned array count; status.msg can be Results: N or OK for a streaming response. Without compact=1 some searches write the response array incrementally and finish with status, so wait for the complete JSON body. This is not newline-delimited JSON. Check status.code even when HTTP transport succeeds. Typical fields are shown below; source-specific metadata and optional fields vary. Treat every identifier as opaque and retain the number and its selected price[].uuid together.
Illustrative response shape; not live account data or a current quote.
{
"status": {
"code": 200,
"msg": "Results: 1",
"results": 1
},
"response": [
{
"number": "12125550123",
"info": {
"uuid": "NUMBER_ID_FROM_RESPONSE",
"prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
"area_uuid": "AREA_ID_FROM_RESPONSE",
"country_uuid": "COUNTRY_ID_FROM_RESPONSE",
"country_iso": "US",
"prefix": "+1212",
"name": "Example area",
"state": "US"
},
"price": [
{
"uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
"per_minute": "0.01",
"per_sms": "0",
"per_mms": "0",
"free_minutes": "0",
"setup_price": "1.00",
"monthly_price": "2.00",
"yearly_price": "0",
"channels": "2"
}
],
"contract": {
"term": "1 month",
"renewal": "monthly",
"notice": "none"
},
"restrictions": {
"needs_registration": "0",
"restrictions": ""
},
"features": [
"voice"
],
"overflow": "0"
}
]
}Errors
- 401: Authentication failed. Invalid or missing credentials and rejected API-account access do not produce search results.
- 404: Invalid prefix ID, Invalid country, Invalid area, or No numbers found. Read status.msg; an error response is not a number array.
- 400: NUMBER_FILTER_INVALID in response.code: invalid mode, a value other than 1–15 digits, or filter_required without both mode and value.
- 422: NUMBER_FILTER_UNSUPPORTED in response.code: either the prefix assigns a number at order time (reason=order_only_prefix and next_function identifies the order route), or the explicit source cannot support the required filter.
Availability and side effects
- This handler searches and prepares quotes; it does not submit a number order or debit a number-purchase charge. It can refresh catalogue caches, remove stale cached inventory, save account-scoped price plans and write search logs.
- Availability is a point-in-time result, not a reservation. A subsequent order can fail or return different availability. Reconcile the order result before retrying a purchase.
- Prices are account-specific. Keep the selected plan ID for the same account and review the order terms and charges separately; this endpoint alone does not prove a price will remain valid until a later order.
- The example number and prices are fictional response-shape examples, not a live quote. Capabilities, channel quantities, term and registration information must be read from the actual selected result.
- Some registration descriptions contain formatted text or links. Treat returned strings as untrusted data when rendering them in your own application.
- Mobile availability and flags depend on account eligibility and inventory. A catalogue prefix or is_mobile flag alone does not establish a particular number’s mobile capabilities.