How to have Reloadly automatically detect the Operator Id when doing a top-up request

In order to make an API call to the TopUp endpoint you’ll need to provide the OperatorId as a parameter.

If all you have at hand is the recipient’s phone number you’ll have to determine it’s OperatorId before the topup can be effectively done.

The best way to go about this is to use another Reloadly API’s endpoint: Operator Auto-Detect.

Through this API call you can get information about the Mobile operator servicing the TopUp recipient.

What is the OperatorId

Every phone number is associated with a Mobile Operator (The company that provides the mobile service).

Inside of Reloadly, each mobile operator is uniquely identified by it’s OperatorId.

You can get a list of all available operators by making a request to https://docs.reloadly.com/airtime/Operators/Get-Operators. Kindly note that you can apply different filters, more details are available on the previous link.

Getting the OperatorId for a mobile number

As a prerequisite to making this API call I will assume you already hold a valid access token.

Making the call

The endpoint you’ll be using is https://topups.reloadly.com/operators/auto-detect/phone/[MOBILE_NUMBER]/countries/[COUNTRY_ISO_CODE].

This call:

curl --location --request GET 'https://topups-sandbox.reloadly.com/operators/auto-detect/phone/91154973586/countries/AR?suggestedAmounsMap=true&SuggestedAmounts=true' --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' --header 'Accept: application/com.reloadly.topups-v1+json'

Will return:

{
  "id": 16,
  "operatorId": 16,
  "name": "Movistar Argentina",
  "bundle": false,
  "data": false,
  "pin": false,
  "supportsLocalAmounts": false,
  "supportsGeographicalRechargePlans": false,
  "denominationType": "FIXED",
  "senderCurrencyCode": "EUR",
  "senderCurrencySymbol": "€",
  "destinationCurrencyCode": "ARS",
  "destinationCurrencySymbol": "$",
  "commission": 3,
  "internationalDiscount": 3,
  "localDiscount": 0,
  "mostPopularAmount": 4.35,
  "mostPopularLocalAmount": null,
  "minAmount": null,
  "maxAmount": null,
  "localMinAmount": null,
  "localMaxAmount": null,
  "country": {
    "isoName": "AR",
    "name": "Argentina"
  },
  "fx": {
    "rate": 112.333,
    "currencyCode": "ARS"
  },
  "logoUrls": [
    "https://s3.amazonaws.com/rld-operator/76eaeaf7-e614-48c6-80dc-c46f4f13ff4d-size-2.png",
    "https://s3.amazonaws.com/rld-operator/76eaeaf7-e614-48c6-80dc-c46f4f13ff4d-size-3.png",
    "https://s3.amazonaws.com/rld-operator/76eaeaf7-e614-48c6-80dc-c46f4f13ff4d-size-1.png"
  ],
  "fixedAmounts": [
    0.04,
    0.09,
    0.15,
    0.18,
    0.26,
    0.36,
    0.44,
    0.53,
    0.61,
    0.7,
    0.78,
    0.87,
    0.96,
    1.05,
    1.14,
    1.22,
    1.31,
    1.4,
    1.49,
    1.57,
    1.66,
    1.74,
    2.18,
    2.62,
    3.05,
    3.48,
    3.92,
    4.35
  ],
  "fixedAmountsDescriptions": {},
  "localFixedAmounts": [],
  "localFixedAmountsDescriptions": {},
  "suggestedAmounts": [],
  "suggestedAmountsMap": {},
  "geographicalRechargePlans": [],
  "promotions": [
    {
      "id": 5902,
      "promotionId": 5902,
      "operatorId": 16,
      "title": "Movistar Argentina From 01 May 2021 00:00 To 31 May 2021 23:59 (GMT-03:00)",
      "title2": "Bonus 5x",
      "description": "<br />- For top ups of USD 5 (EUR 5) or more, customers will receive 5X balance.<br />- Receivers need to send a SMS with the number 5 + Send 3456 to activate the promotion.<br />- Promotional balance can be used for voice calls, SMS and internet browsing.<br />- Promotional balance will be valid for 7 days.<br />- This promotion applies to all prepaid plans.<br /><br />T&eacute;rminos y condiciones (Spanish version):<br />- Recarga a tu familia y pueden Multiplicar todos los dias desde 5 USD (5 EUR)! Enviando 5 al 3456 Y QUINTUPLICA&nbsp;el&nbsp;saldo /hablar, mensajear y navegar x 7 DIAS!&nbsp;<br />- Promoci&oacute;n aplica para todos los clientes prepago.<br />&nbsp;",
      "startDate": "2021-05-01 07:00:00",
      "endDate": "2021-06-01 06:59:00",
      "denominations": "USD 5 and up",
      "localDenominations": null
    }

Analyzing the result

The request you just made got you quite a lot of information about the Mobile Operator behind the number 91154973586 (Registered in Argentina).

While there’s a lot of valuable information in this json object, what you’re looking for is the value associated with the key operatorId, in this case 16.

That number (16) is what you need to use to fill the parameters of the call to the TopUp endpoint.

In summary, you’ll need to make, at least, two API calls besides the one getting you the access token:

1. To the Operator auto-detect
2. To the topup endpoint

On a few occasions the response you’ll get from the first API call will be HTTP 404.

This could happen because of several reasons, for instance, the phone number + country combination is invalid.

In these situations, besides the HTTP error code, you’ll have some context to determine what happened. You’ll get a json object similar to:

{
  "timeStamp": "2022-02-23 10:29:27",
  "message": "Could not auto detect operator for given phone number",
  "path": "/operators/auto-detect/phone/91154973586/countries/ES",
  "errorCode": "COULD_NOT_AUTO_DETECT_OPERATOR",
  "infoLink": null,
  "details": []
}

Finally, there might be a case where the data you provided to the auto-detect endpoint is correct but still you don’t get the answer you’re looking for. This could happen if the number you’re trying to top up has recently been ported to a different operator.

Should that be the case your options are:

1. To show the end-user a list of every available operator in their country and have them select the appropriate one.
2. Use Reloadly’s Number Lookup service

EndPoints mentioned in this article

• https://topups.reloadly.com/operators/auto-detect/phone/
• https://topups.reloadly.com/operators
• https://auth.reloadly.com/oauth/token
• https://topups.reloadly.com/operators/mnp-lookup/phone/{phone}/countries/{countryCode}