Order phone numbers from a prefix

Order from a prefix

Use this operation when the prefix catalogue directs you to order a quantity from a prefix rather than choose individual available numbers. Start with countries, areas or states, and prefixes. Keep the prefix identifier and price plan from the same fresh result. For a particular number selected from an available-number list, use Purchase a selected phone number.

This request can purchase numbers and incur charges. It is not a price quotation, reservation or dry run. Review setup and monthly charges, incoming-minute rates, included minutes, channels, registration requirements and the account’s purchase limits before submitting. A catalogue result does not reserve inventory or freeze prices. Account funding checks can happen before fulfillment; an error does not by itself prove that no purchase or account funding occurred.

Submit the purchase

Use an enabled API account over HTTPS from an allowed source IP address. Set the variables from your current catalogue selection and your approved delivery configuration. The following command purchases one number.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

Form POST is shown above. The coordinator also reads a JSON object when Content-Type is application/json. JSON fields override matching form/request fields. Use one encoding consistently; do not send conflicting query and body values.

Delivery and renewal settings

Choose the same delivery settings you would use for the number in the portal. These are advanced configuration values, not instructions to create a Hosted PBX or an origination trunk. Reuse a known working account configuration and verify the saved number after purchase. An accepted purchase alone does not verify that voice or SMS delivery works.

These fields are normalized and passed to checkout, but persistence differs across inventory paths. The current order route does not expose the selected-number purchase guide’s strict quote-cap fields as equivalent guards. Use the account’s purchase permissions and price limits, and inspect the resulting number configuration.

Read the complete result

Parse the JSON body and inspect status.code and status.msg even when the HTTP request succeeds. This route writes its own JSON response, and the shared response helper also does not necessarily map the application code to the HTTP status. Application codes may be JSON numbers or numeric strings. Do not require status.results; it is not present in the normal order result.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

The identifier, number and prices above are fictional. Treat the order ID as opaque. numbers lists the numbers this response reports as purchased; compare its length with the quantity you requested. Price amounts are strings and this response rounds monetary rates to two decimal places, including per_minute; use the fresh catalogue for the original rate precision. Included minutes and channels can arrive as numeric values or numeric strings.

The price block describes the selected plan used to build the response, not a detailed invoice for every number or the order’s total. Multiple inventory candidates can have different plans. Reconcile the individual purchased numbers and account transactions rather than multiplying this block and assuming it proves the final total.

Partial purchases and uncertain outcomes

An application code of 200 can accompany a warning and fewer numbers than requested. A later failure does not undo numbers already purchased. Preserve the returned order ID, numbers and message. Reconcile those numbers in your inventory and account transactions before deciding whether to order a remaining quantity.

A timeout, disconnected request, malformed response or error after submission is not evidence that nothing happened. Do not automatically submit another purchase, even with the same reference. Preserve the original request, reference and any returned order ID, check inventory and account transactions, and contact support when the outcome remains uncertain.

An unconfirmed order can return application code 400 with wording that it is still being confirmed. Preserve its returned order ID and reconcile that purchase; this is not an instruction to submit it again. Recorded-order recovery tracks the original order internally. A new request to this operation creates a separate purchase attempt rather than resuming an order by your reference, so it can buy and charge for more numbers. Do not use repeated purchase requests to check status or search inventory.

Registration and activation

A purchased or allocated number may still need registration or activation. If needs_registration is 1, inspect restrictions and registration_requirements. The latter can identify v3/get_requirements with country and number_type values. Complete the applicable identity/address workflow and confirm the number’s status before relying on inbound calls or messaging.

features describes advertised capabilities; it does not verify live routing, campaign approval, SMS delivery or fax reception. Check the saved delivery settings and perform the appropriate service test when the number is active.

Order callbacks

Callbacks POST JSON containing the order status and response, with your reference added when supplied. They are sent for reported purchases, including partial results. A failed callback does not roll back the purchase. Delivery can be retried, so process duplicates by order ID and reconcile the numbers rather than issuing another purchase.

This route does not add a cryptographic callback signature. Treat a callback as a notification to reconcile against your authenticated inventory, not as independent authorization to charge, provision or grant access. Do not put API credentials in the callback URL. Submitting another purchase with a different callback URL does not update the original order; it creates a separate purchase attempt. Retain the original order ID when asking support to investigate its callback.

Failures to handle