Find available mobile numbers

Confirm mobile inventory is enabled

Use this search only after mobile-number inventory has been enabled for your customer account. Obtain a current individual mobile prefix through the account's discovery workflow. The supported path requests wireless inventory for that prefix. It does not depend on a matching wireline routing-metadata record. Contact support if you are unsure whether your account or prefix is enabled.

The current legacy route does not reliably reject every ineligible request. An account without mobile inventory enabled can receive ordinary inventory while the response still says info.is_mobile: 1. A toll-free prefix can also reach the toll-free inventory branch with that label. Do not use this label alone to identify mobile service, and do not send ordinary or toll-free prefixes to this endpoint. Use the account's confirmed mobile catalogue and enabled workflow.

Keep each number with its own price selection

For each candidate, keep number, info.uuid and that same entry's price list together. The response also contains prefix/area/country metadata, contract terms and registration restrictions. Candidates are sorted by the monthly price of their first price option, ascending; there is no guaranteed stable order for equal prices. Do not replace the returned number ID with an area or prefix ID, or pair it with another candidate's price ID.

The complete response can include additional metadata and price fields. Returned features, channel values and restrictions describe the candidate; they are not a guarantee that calls, SMS, MMS or fax are already usable. Account permissions, registration and the selected service plan still apply. Do not treat the example's placeholders as valid IDs or prices.

Use a small positive quantity

Start with a quantity of 1. The normal provider request normalizes a nonpositive quantity to 1 and caps the upstream value at 300, but later result handling still uses the original input. A zero quantity can therefore request upstream inventory and return no candidates. Other legacy branches do not consistently enforce the requested result count. Do not rely on a single universal maximum or send negative, fractional or nonnumeric values. No supported public search filter or price-ID body parameter is documented for this route.

Distinguish missing stock from lookup failure

A 404 response can represent unavailable inventory, disabled service, failed supplier lookup or invalid catalogue records. Treat a timeout or provider failure as unknown availability rather than confirmed zero stock. Refresh the selection and retry with backoff when appropriate. Avoid polling every exchange repeatedly. The separate mobile inventory-count endpoint is a snapshot hint and need not match the length of this account's candidate list.

Recheck before purchasing

Search does not reserve stock. The reviewed branch attempts to exclude numbers already purchased, but a failed local reservation lookup can leave such a candidate in the result. Availability, ownership, approved pricing and registration must be checked by the purchase workflow. Use a fresh selection with the guarded purchase request, and reconcile account inventory after any uncertain purchase result before retrying. Never purchase merely because a candidate was returned.

Request

Use an enabled API account over HTTPS from an allowed source IP address. Mobile inventory must also be enabled for the customer account; API authentication alone does not enable it.

GET with the current individual prefix identifier and a positive whole-number quantity in the URL path. Quantity defaults to 1 if omitted. Use the example with 1; this route does not consistently validate or enforce a universal result limit.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/v3/getmobiles/$PREFIX_ID/1"

Response

Inspect status.code and status.msg in the JSON body as well as HTTP status. On success, response is a list of number candidates, status.msg is Results: followed by the number returned, and status.results is the serialized list length. Candidate prices are account-specific. The illustrative abbreviated example uses placeholders instead of real inventory or a tariff quotation. Numbers contain the country code without a plus sign; identifiers are opaque strings.

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

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12025550123",
      "info": {
        "uuid": "NUMBER_ID",
        "prefix_uuid": "PREFIX_ID",
        "country_iso": "US",
        "is_mobile": 1
      },
      "price": [
        {
          "uuid": "PRICE_ID",
          "monthly_price": "ACCOUNT_MONTHLY_PRICE",
          "setup_price": "ACCOUNT_SETUP_PRICE",
          "per_minute": "ACCOUNT_INCOMING_RATE",
          "channels": "PLAN_CHANNELS"
        }
      ],
      "features": [
        "voice",
        "sms",
        "mms",
        "t38"
      ]
    }
  ]
}

Errors

• 404: Invalid prefix ID, country or area: refresh the individual mobile prefix selection.
• 404: No numbers found: may mean no usable stock, disabled service, failed provider lookup, unsupported selection or account limitations. It is not proof of an authoritative zero inventory count.

Availability and side effects

• Search does not rent or reserve a number and the reviewed path does not debit a purchase amount. It contacts the inventory provider and can take time.
• Successful searches write account-related number and price cache entries and query logs. Repeating a search is not a reservation, price lock or purchase.
• The returned prices, terms, restrictions and capabilities must be reviewed for the selected account and number. A feature label does not establish activation, messaging approval or tested service functionality.