Get an airtime operator
Returns one operator with its offers for a phone number of its country (manual flow, step 2).
Returns one operator with its offers for a phone number of its country (manual flow, step 2).
Returns the operator in the item shape that search returns, without a carrier lookup. A number of another
country than the operator's gives 400 / 10001 with COUNTRY_MISMATCH at phoneNumber. An unknown
ID, including any value that is not an operator ID, or an operator without an orderable offer, gives
404 / 10004. Offer filters that match none of the operator's offers leave offers empty. A manual choice
is not checked against the number's carrier, so have the customer confirm the operator before ordering.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
id*stringThe operator ID (operator_…) from the operator list, the catalog or search.
phoneNumber*stringThe recipient's number in international format, starting with + or 00. It must belong to the operator's country.
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.
OK
- response
One operator with its offers, as search and operators/{id} return it. id is the stable
operator id operator_…, which is never orderable; an order names one of its offers by public
ID. Airtime has no categories or operator descriptions, so category and description
are always null. Prices are indicative; quote recalculates them.
id*stringname*stringcountryCode*stringcategory?string|nulllogoUrl?string|nulldescription?string|nulloffers*array<>curl -X GET 'https://api.sandbox.openroam.com/v1/airtime/operators/operator_tq7vbm2xk4hdn6wzr3pyjc5fae?phoneNumber=%2B994501234567&valueType=range&valueCurrency=AZN&minValue=10&maxValue=200&minPrice=5&maxPrice=130¤cy=USD'{ "id": "string", "name": "string", "countryCode": "string", "category": "string", "logoUrl": "string", "description": "string", "offers": [ { "publicId": "string", "name": "string", "description": "string", "value": { "amount": 0, "currency": "string", "type": "fixed" }, "price": { "amount": 0, "currency": "string" }, "requiredInputs": [ { "name": "string", "type": "text", "required": true, "description": "string", "fields": [ {} ] } ], "details": { "redemptionType": "directTopUp", "readMore": "string" } } ]}Order airtime POST
Places an airtime top-up 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. The number's operator is looked up again, as in quote; item errors are named at `items[i]`, and a current price above `inputs.maxPrice` gives 409 / 11002 before anything is charged. Track fulfillment 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.
List airtime operators GET
Lists the operators of a country that the customer can choose manually (manual flow, step 1). Returns the complete list, without paging or prices, as `{ items: [{ id, name, countryCode, category, logoUrl }] }`, ordered by name. Only operators with an offer that can be sold for a chosen operator are listed. An invalid `countryCode` gives 400 / 10001. Continue with `operators/{id}?phoneNumber=`.