Search airtime by phone number
Searches for a phone number's operator by carrier lookup and returns it with its offers (detected flow).
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.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
phoneNumber*stringThe recipient's number in international format, starting with + or 00; spaces, hyphens and parentheses are allowed.
valueType?stringKeep only fixed or only range offers.
"fixed""range"valueCurrency?stringCurrency of minValue and maxValue, three letters; required with either of them.
minValue?numberKeep the offers whose value reaches at least this amount, in valueCurrency.
decimalmaxValue?numberKeep the offers whose value starts at or below this amount, in valueCurrency.
decimalminPrice?numberKeep the offers whose indicative price reaches at least this amount, in the price currency.
decimalmaxPrice?numberKeep the offers whose indicative price starts at or below this amount, in the price currency. A filter, not the inputs.maxPrice limit of a purchase.
decimalcurrency?stringPrice currency, three letters in either case; the API key's currency when omitted. An unsupported code gives 400 / 10001 at currency, reason NOT_SUPPORTED.
page?integerMust be 1: search returns at most one operator.
int32limit?integerPage size, 1 to 100; default 10.
int32OK
- response
The detected flow: at most one item, the operator the phone lookup detected, with its offers. items is
empty unless details.phoneLookup.status is detected and an offer is left after filtering; the
partner then falls back to the operator list.
items*array<>pagination*Paging of a list response.
details*Airtime search facts outside the root keys every partner service shares.
curl -X GET 'https://api.sandbox.openroam.com/v1/airtime/search?phoneNumber=%2B994501234567&valueType=range&valueCurrency=AZN&minValue=10&maxValue=200&minPrice=5&maxPrice=130¤cy=USD&page=1&limit=10'{ "items": [ { "id": "operator_tq7vbm2xk4hdn6wzr3pyjc5fae", "name": "Test operator", "countryCode": "AZ", "category": null, "logoUrl": "https://cdn.openroam.test/airtime/test-operator.png", "description": null, "offers": [ { "publicId": "airtime_raanuxyz6cxzie3w3my6c3r2wm", "name": "Test operator 40 AZN", "description": "Top-up for **Test operator** numbers.", "value": { "type": "fixed", "amount": 40, "currency": "AZN" }, "price": { "amount": 25, "currency": "USD" }, "requiredInputs": [ { "name": "phoneNumber", "type": "phone", "required": true, "description": "The recipient's mobile number in international format, starting with + or 00." } ], "details": { "redemptionType": "directTopUp", "readMore": "Credit arrives within minutes." } }, { "publicId": "airtime_ms45o6lwxtqgrsculqdhop74zq", "name": "Test operator 10 - 200 AZN", "description": "Top-up for **Test operator** numbers.", "value": { "type": "range", "min": 10, "max": 200, "step": 0.01, "currency": "AZN" }, "price": { "min": 6.25, "max": 125, "currency": "USD" }, "requiredInputs": [ { "name": "phoneNumber", "type": "phone", "required": true, "description": "The recipient's mobile number in international format, starting with + or 00." } ], "details": { "redemptionType": "directTopUp", "readMore": "Credit arrives within minutes." } } ] } ], "pagination": { "currentCount": 1, "totalCount": 1, "skip": 0, "limit": 10, "hasMore": false, "page": 1, "totalPages": 1 }, "details": { "phoneLookup": { "status": "detected", "carrierName": "Test operator", "countryCode": "AZ" } }}Quote airtime POST
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.
Pay utility bills POST
Places a utility bill payment order and returns the accepted order. Takes the same body as quote and needs the `manage` order permission (403 / 10003 without it). An `Idempotency-Key` header with a new UUID is required for every purchase: a retry with the same key and body returns the order already accepted, 409 / 12002 with `Retry-After` while it is still being accepted, and a changed body gives 409 / 12001. Every price is recalculated: a current price above `inputs.maxPrice` gives 409 / 11002 at `items[i].inputs.maxPrice` before anything is charged, and without `inputs.maxPrice` the current price is charged. The item is fulfilled when the payment is confirmed and, for a `token` biller, the token is returned; track it with the order routes or the `order.fulfillment.updated` webhook. A wallet charge that fails creates no order and gives 402 / 16000, with `details[0]` naming `wallet` and `INSUFFICIENT_BALANCE` or `WALLET_BLOCKED`; send the same request with the same key after a top-up.