Quote airtime
Prices the order body with current prices, without placing an order.
Prices the order body with current prices, without placing an order.
Takes the same body as order and resolves the number's operator as the order does, with a carrier lookup per
item. Each item is priced on its own, in request order; the first failing item aborts the quote and is named at
items[i], for example 409 / 11002 at items[i].inputs.maxPrice when the current price is above
it. 409 / 20000 means the lookup shows that the offer's operator cannot be the number's: search again. A
carrier lookup that fails gives 503 / 10007. A quote reserves nothing and does not expire; to hold the quoted
price, send it as inputs.maxPrice in the order.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
- body
The body B2B airtime quote and order both take.
currency?|Order currency, three letters in either case; the API key's currency when omitted. An unsupported code gives
400 / 10001 at currency, reason NOT_SUPPORTED, before any item is checked.
referenceId?|Optional partner order reference, unique per partner, at most 128 characters without leading or trailing spaces. A quote validates it and ignores it.
items*array<>1 to 5 items, each topping up one number once.
OK
- response
Current prices for the requested items, in request order. total is the sum of each item's unit price
times its quantity. A quote reserves nothing and does not expire.
currency*stringitems*array<>total*curl -X POST 'https://api.sandbox.openroam.com/v1/airtime/quote' \ -H 'Content-Type: application/json' \ -d '{ "currency": "USD", "referenceId": "partner-order-42", "items": [ { "publicId": "airtime_raanuxyz6cxzie3w3my6c3r2wm", "quantity": 1, "inputs": { "phoneNumber": "+994501234567", "maxPrice": { "amount": 25, "currency": "USD" } } }, { "publicId": "airtime_ms45o6lwxtqgrsculqdhop74zq", "quantity": 1, "inputs": { "phoneNumber": "+994501234567", "value": { "amount": 50, "currency": "AZN" }, "maxPrice": { "amount": 31.25, "currency": "USD" } } } ]}'{ "currency": "USD", "items": [ { "publicId": "airtime_raanuxyz6cxzie3w3my6c3r2wm", "quantity": 1, "name": "Test operator 40 AZN", "value": { "amount": 40, "currency": "AZN" }, "price": { "amount": 25, "currency": "USD" }, "details": { "estimatedDeliveredValue": { "amount": 40, "currency": "AZN" } } }, { "publicId": "airtime_ms45o6lwxtqgrsculqdhop74zq", "quantity": 1, "name": "Test operator 50 AZN", "value": { "amount": 50, "currency": "AZN" }, "price": { "amount": 31.25, "currency": "USD" }, "details": { "estimatedDeliveredValue": { "amount": 50, "currency": "AZN" } } } ], "total": { "amount": 56.25, "currency": "USD" }}Look up a phone number GET
Describes a phone number and returns its carrier from a carrier lookup when the number is valid. Describes the number from numbering-plan data and, for a valid number, adds carrier information from a live carrier lookup. A number without the international shape gives 400 / 10001; a number its country does not assign returns 200 with `isValid: false` and `carrier: null`, without a carrier lookup. Returns 503 / 10007 when the carrier lookup is unavailable. The carrier is for display only and nothing is stored; use search to find a sellable operator.
Search airtime by phone number GET
Searches for a phone number's operator by carrier lookup and returns it with its offers (detected flow). Returns `{ items, pagination, details: { phoneLookup: { status, carrierName, countryCode } } }`. `items` holds at most the detected operator with its offers. It is empty when `status` is not `detected` or no offer remains after the filters; then let the customer choose the operator with `GET operators?countryCode=`, using `details.phoneLookup.countryCode`. Each call makes exactly one carrier lookup and returns at most one item, so `page` must be 1. A `phoneNumber` that is not in international format gives 400 / 10001; a carrier lookup that fails gives 503 / 10007, retry later.