Skip to Content
OpenRoam Docs
Airtime

Search airtime by phone number

Searches for a phone number's operator by carrier lookup and returns it with its offers (detected flow).

GET
/v1/airtime/search

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.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Query Parameters

phoneNumber*string

The recipient's number in international format, starting with + or 00; spaces, hyphens and parentheses are allowed.

valueType?string

Keep only fixed or only range offers.

Value in"fixed""range"
valueCurrency?string

Currency of minValue and maxValue, three letters; required with either of them.

minValue?number

Keep the offers whose value reaches at least this amount, in valueCurrency.

Formatdecimal
maxValue?number

Keep the offers whose value starts at or below this amount, in valueCurrency.

Formatdecimal
minPrice?number

Keep the offers whose indicative price reaches at least this amount, in the price currency.

Formatdecimal
maxPrice?number

Keep 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.

Formatdecimal
currency?string

Price 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?integer

Must be 1: search returns at most one operator.

Formatint32
limit?integer

Page size, 1 to 100; default 10.

Formatint32

Response Body

OK

  1. 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.

Example Request
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&currency=USD&page=1&limit=10'
Example Response
{  "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.