Skip to Content
OpenRoam Docs
Utility

Search billers

Searches the billers of a country and returns them with their offers, one page at a time.

GET
/v1/utility/search

Searches the billers of a country and returns them with their offers, one page at a time.

Returns { items, pagination }. countryCode is required; category, serviceType and q select billers. Utility has no value or price filter. Pages count billers that still have an offer, and prices are indicative, in currency. Quote and order take an offer's publicId, never the biller's id. An invalid or unknown parameter gives 400 / 10001; an unsupported currency gives 404 / 10004.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Query Parameters

countryCode*string

Required ISO 3166-1 alpha-2 country code of the billers, in either case.

category?string

Keep the billers of this category, for example electricity.

Value in"other""electricity""water""television""internet""gas""toll""voip""landline"
serviceType?string

Keep prepaid or postpaid billers.

Value in"prepaid""postpaid"
q?string

Text in the biller name, case-insensitive; at most 100 characters, without control characters.

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

Page number, from 1; default 1.

Formatint32
limit?integer

Page size, 1 to 100; default 10.

Formatint32

Response Body

OK

  1. response

A page of billers; pagination.totalCount counts billers that still have an offer after filtering.

items*array<>
pagination*

Paging of a list response.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/utility/search?countryCode=AZ&category=other&serviceType=prepaid&currency=USD&page=1&limit=10'
Example Response
{  "items": [    {      "id": "biller_3jx464dkw4ekdjgj4qxuib5wki",      "name": "Fixed postpaid",      "countryCode": "AZ",      "category": "other",      "logoUrl": null,      "description": null,      "offers": [        {          "publicId": "utility_7tq2mw5kxr3nbv6hzc4dpe2ysa",          "name": "Local tier",          "description": null,          "value": {            "type": "fixed",            "amount": 40,            "currency": "AZN"          },          "price": {            "amount": 27.5,            "currency": "USD"          },          "requiredInputs": [            {              "name": "accountNumber",              "type": "text",              "required": true,              "description": "The customer's account or meter number with the biller."            },            {              "name": "invoiceId",              "type": "text",              "required": true,              "description": "The ID of the bill to pay, as the biller issued it."            }          ]        }      ],      "details": {        "serviceType": "postpaid",        "deliveryType": "directCredit"      }    },    {      "id": "biller_jeicjoplfgowwmc2h7mbwbatqe",      "name": "Range prepaid",      "countryCode": "AZ",      "category": "other",      "logoUrl": null,      "description": null,      "offers": [        {          "publicId": "utility_k4hv2cq7wnz5jr3xmtb6eyl2pa",          "name": "Range prepaid 20–200 AZN",          "description": null,          "value": {            "type": "range",            "min": 20,            "max": 200,            "step": 0.01,            "currency": "AZN"          },          "price": {            "min": 14.38,            "max": 132.5,            "currency": "USD"          },          "requiredInputs": [            {              "name": "accountNumber",              "type": "text",              "required": true,              "description": "The customer's account or meter number with the biller."            }          ]        }      ],      "details": {        "serviceType": "prepaid",        "deliveryType": "token"      }    }  ],  "pagination": {    "currentCount": 2,    "totalCount": 2,    "skip": 0,    "limit": 10,    "hasMore": false,    "page": 1,    "totalPages": 1  }}