Placing an order
Order a number with /purchase/sms — the best option, one provider's, or exactly the option you picked — with a price ceiling.
Embed
<a href="https://numestri.com/docs/placing-an-order"><img src="https://numestri.com/docs/_api/public/orgs/25229885-9620-4c08-bd2e-a0d0d74ac8b6/spaces/ef21e0c3-966d-4b03-b6d2-e66d449835d4/pages/7f6674e9-3aa9-4d11-8d3c-c2ff6bb44ab8/social-card.svg?v=3e7ae33eec8b" alt="Placing an order" width="600" height="315"></a>/purchase/sms buys a number for a platform and country. It needs an API key, and your balance is charged the moment the number is issued.
Everything you need to choose — platform and country ids, providers, options and their prices — comes from the catalogue and /request/price, which you can call without a key.
Three ways to choose
- Best option
- One provider
- Exact option
Give the platform and country. The best option in stock fills it, and if it cannot deliver the next one takes over.
curl https://numestri.com/api/v1/purchase/sms -H "Authorization: Bearer $NUMESTRI_KEY" \
-d service=telegram -d country=USAdd provider. Only that provider fills the order, starting with its best option.
curl https://numestri.com/api/v1/purchase/sms -H "Authorization: Bearer $NUMESTRI_KEY" \
-d service=telegram -d country=US -d provider=prv_k3Jd9QmXa2If it has nothing in stock the order is refused with code PROVIDER_UNAVAILABLE; nobody else fills it.
Add option. That exact offer fills the order at its listed price — or the order is refused with code OPTION_GONE. It is never substituted.
curl https://numestri.com/api/v1/purchase/sms -H "Authorization: Bearer $NUMESTRI_KEY" \
-d service=telegram -d country=US -d option=5sQY4PwqkxD3gE7OParameters
Parameter | Required | Meaning |
|---|---|---|
| yes | Platform id from the catalogue, e.g. |
| yes | ISO country code, e.g. |
| no | A provider id. Only that provider fills the order. |
| no | An option id. Exactly that offer, or nothing. |
| no | Refuse if the price is above this, in dollars, e.g. |
| no |
|
| no | A header (or |
The price you pay
You never send a price. The amount charged is worked out on our side when the order is placed, for your account — the same price the catalogue and /request/price show you when you send your key, which can differ from the public list if your account has negotiated pricing. With option, it is that option's listed price; with provider, that provider's cheapest option in stock; otherwise the best option's price. If one option fails and the next takes over, you are still charged the price fixed at the start.
Prices move with the market, so a quote is not a reservation. max_price is your ceiling: if the price is above it the order is refused with 400 and code PRICE_ABOVE_MAX, and nothing is charged. The response's cost is always what was actually taken.
Response
{
"success": 1,
"number": 12025550123,
"cc": "1",
"phonenumber": "2025550123",
"order_id": "JRJ5UEXS",
"country": "United States",
"country_code": "US",
"service": "Telegram",
"service_id": "telegram",
"expires_in": 1198,
"expiration": 1792131600,
"cost": "0.99",
"cost_in_cents": 99
}Keep order_id: it is how you receive the code, cancel, or resend.
Shared numbers are public
number_class=shared buys a number whose inbox is a public web page: anyone can read the code. Use one only where that does not matter.
When an order is refused
A refused order costs nothing. Branch on type (or the finer code) rather than on the message text; see Errors for the full list.
{
"success": 0,
"message": "That option is no longer available. Pick another.",
"type": "OUT_OF_STOCK",
"code": "OPTION_GONE"
}