Choose the number and price together
Purchase one specific number selected from a fresh available-number search. Use the selected entry’s info.uuid as the number ID and one of that same entry’s price[].uuid values as the price ID. The route also accepts the complete stored number, but a country, area or prefix ID is not a substitute for a number selection.
Searching or reading saved pricing does not reserve a number or freeze its price. Confirm the selected setup price, monthly price, incoming-minute rate, included minutes and channels, plus the account’s purchase permissions and registration requirements. The initial base amount in the reviewed helper is setup plus monthly price; full provider-specific charges and terms must be confirmed for the selected plan.
POST a guarded purchase request
Use an enabled API account over HTTPS from an allowed source IP address. The following command is a purchase, not a quotation or dry run. Set every variable from the same fresh number/price selection. The cap fields preserve the legacy restore_quote_ prefix; the current portal also uses them for guarded specific-number purchases.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode "restore_quote_price_id=$PRICE_ID" \
--data-urlencode "restore_quote_setup=$SETUP_PRICE" \
--data-urlencode "restore_quote_monthly=$MONTHLY_PRICE" \
--data-urlencode "restore_quote_per_minute=$PER_MINUTE_PRICE" \
--data-urlencode "restore_quote_channels=$CHANNELS" \
"https://api.multitel.net/v3/rentnumber/$NUMBER_ID/$PRICE_ID"Use form POST as shown. The helper also has JSON/options-wrapper parsing, but complete parity for all quote and provider paths is not established by this review. Do not use GET for purchasing even though this legacy coordinator has no explicit method guard.
| Field | Meaning |
|---|---|
| NUMBER_ID | Selected number UUID from the search, or the full stored number. One number per request. |
| PRICE_ID | Price UUID associated with that selected number and your account. Always supply it explicitly. |
| restore_quote_price_id | Must match the resolved price ID. Supplying this field enables the quote checks; it is not an idempotency key. |
| restore_quote_setup | Maximum accepted setup price, as a finite nonnegative numeric value. |
| restore_quote_monthly | Maximum accepted monthly price, as a finite nonnegative numeric value. |
| restore_quote_per_minute | Maximum accepted incoming-minute rate, as a finite nonnegative numeric value. |
| restore_quote_channels | The exact whole-number channel quantity of the selected price option, not a request for a different channel plan. |
Supply all numeric quote fields whenever you supply the quote price ID. A changed ID, price above a cap, missing/invalid cap, changed channel quantity or busy quote lock returns API code 409 before the selected rental provider is dispatched. Comparisons permit a small floating-point tolerance; use the actual displayed plan values rather than a hand-rounded price.
The guards do not make the whole workflow a dry run or transaction. Registration lookups, identity provisioning or other helper work can occur before these checks. They also do not freeze external inventory or replace account-level purchase restrictions.
Registration and activation
When required, add the RegistrationID form field containing the customer-owned registration profile UUID. It is not the ID of an uploaded proof, a supplier address or a separate identity entity. The helper resolves the profile against the authenticated account and rejects missing or unavailable profiles.
Some supported inventory permits purchase before registration is complete; other inventory requires a profile before purchase. Carrier-specific validation or provisioning may still be required. Do not interpret a successful purchase or an omitted up-front check as a registration exemption or immediate activation.
Where present, the response’s registration_requirements identifies the structured requirements lookup with country and number type. Use the registration catalogue and proof workflow to complete the applicable requirements. Returned text and metadata do not themselves approve a profile.
Avoid silent plan substitution
The legacy coordinator can infer an omitted price from cached number data. It can also fall back to the newest account price for a cached prefix when an explicitly supplied price ID no longer exists, and update the cached allowed-price selection. Do not rely on these fallbacks to select the plan a customer approved.
Supply the explicit selected price and matching quote guard fields. The quote-ID guard rejects a fallback to another ID before rental dispatch. Refresh the search and obtain a newly approved selection after a stale-price conflict rather than removing the guards to force the purchase.
There is no guaranteed reservation period or universally enforced cache lifetime for every path. Number availability, account price limits and purchase policies are rechecked in the workflow, but the full provider-specific behavior remains under review.
Advanced: account routing defaults
A purchase can inherit the account’s existing voice destinations, failover destinations, SMS destination and origination-trunk preference. Review those defaults before ordering; omitting routing options does not promise an unconfigured number. The reviewed helper enables auto-renew by default.
| Option | Resolution behavior |
|---|---|
| uri, uri2, uri3 | Omitted values inherit corresponding account defaults. Explicit empty values clear the helper’s value instead of inheriting it. Use valid destinations appropriate to the selected routing mode. |
| smsuri | Omitted value inherits the account SMS destination; an explicit empty value clears it in the helper. |
| origintrunk | Recognized explicit trunk ID takes precedence. An unresolved value can fall back to the account preference or legacy default rather than producing an error. |
| forward_destination, forwarding_destination, type | Nonempty routing-mode aliases, in that precedence order. Use supported values from the account’s routing configuration, not a guessed numeric mode. |
| RegistrationID | Registration profile lookup, scoped to the customer; it is separate from routing destinations. |
| autorenew | Defaults to 1. The helper uses a nonempty-value check, so 0 does not reliably disable renewal through this purchase field. Use supported account renewal management and verify the saved setting. |
These are shared-helper semantics, not a guarantee that every supplier persists every optional setting identically. Other legacy voice, voicemail, fax and SMS fields exist but still require complete provider-specific review. Verify the purchased number’s saved configuration through the account workflow before relying on calls or messages.
Response
Fictional example for an uncomplicated purchase; values and features vary by the selected plan.
{
"status": {
"code": 200,
"msg": ""
},
"response": {
"number": "12025550123",
"price": {
"per_minute": "0.0100",
"free_minutes": "100",
"setup_price": "2.00",
"monthly_price": "4.00",
"channels": "2",
"overflow": "0"
},
"features": [
"voice"
],
"needs_registration": 0,
"registration_requirements": null
}
}The coordinator uses its own status.code/status.msg and response envelope, without a guaranteed status.results field. An error generally has an empty response list. On success, inspect the returned number and price, then reconcile account inventory and registration state. Provider acceptance is not a live voice, SMS or fax test.
Errors and uncertain results
| API code | Meaning |
|---|---|
| 403 | Account price/purchase restrictions, an unavailable price selection or an inaccessible registration profile can block processing. |
| 404 | Missing or unavailable number, price or prefix selection. |
| 409 | The number is already active, a quote guard no longer matches or another guarded operation holds the lock. |
| 422 | Registration information is required, incomplete or cannot be provisioned in the reviewed registration paths. |
| 500 and other provider/account codes | Provider, local-processing or policy failure. These are not universal proof that no purchase or charge occurred. |
Read the actual API body as well as HTTP status. An external provider may accept a rental before local notification, registration or other processing fails. Some local-inventory allocations use database transactions, but there is no universal rollback of external provider orders. There is no client idempotency key on this coordinator.
Reconcile before retrying
- Keep the approved number, price and quote caps in your application’s order record before submitting once.
- Read the purchased-number inventory and number details for the same account after the request, including after a timeout or error.
- If the number exists, verify its price, renewal, routing and registration state instead of placing another purchase request.
- If the result is still uncertain, have support reconcile the provider order and account billing before retrying. An error message or a legacy log success flag alone is insufficient evidence.
- After ownership and activation are confirmed, complete the account’s normal routing checks and service tests.