{"id":2563,"date":"2022-02-24T14:41:38","date_gmt":"2022-02-24T14:41:38","guid":{"rendered":"https:\/\/www.reloadly.com\/blog\/?p=2563"},"modified":"2023-05-31T12:39:59","modified_gmt":"2023-05-31T12:39:59","slug":"how-to-reloadly-automatically-detect-operator-id","status":"publish","type":"post","link":"https:\/\/reloadly.com\/blog\/how-to-reloadly-automatically-detect-operator-id\/","title":{"rendered":"How to have Reloadly automatically detect the Operator Id when doing a top-up request"},"content":{"rendered":"\n

In order to make an API call to the TopUp endpoint<\/a> you\u2019ll need to provide the OperatorId<\/code> as a parameter. <\/p>\n\n\n\n

If all you have at hand is the recipient\u2019s phone number you\u2019ll have to determine it\u2019s OperatorId<\/code> before the topup can be effectively done.<\/p>\n\n\n\n

The best way to go about this is to use another Reloadly API\u2019s endpoint: Operator Auto-Detect<\/a>.<\/p>\n\n\n\n

Through this API call you can get information about the Mobile operator servicing the TopUp recipient.<\/p>\n\n\n\n

What is the OperatorId<\/h2>\n\n\n\n

Every phone number is associated with a Mobile Operator (The company that provides the mobile service).<\/p>\n\n\n\n

Inside of Reloadly, each mobile operator is uniquely identified by it\u2019s OperatorId<\/code>.<\/p>\n\n\n\n


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

Getting the OperatorId for a mobile number<\/h2>\n\n\n\n

As a prerequisite to making this API call I will assume you already hold a valid access token<\/a>.<\/p>\n\n\n\n

Making the call<\/h3>\n\n\n\n

The endpoint you\u2019ll be using is https:\/\/topups.reloadly.com\/operators\/auto-detect\/phone\/[MOBILE_NUMBER]\/countries\/[COUNTRY_ISO_CODE]<\/a>.<\/p>\n\n\n\n

This call:<\/p>\n\n\n\n

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'<\/pre>\n\n\n\n
Will return:<\/p>\n\n\n\n
{\n  \"id\": 16,\n  \"operatorId\": 16,\n  \"name\": \"Movistar Argentina\",\n  \"bundle\": false,\n  \"data\": false,\n  \"pin\": false,\n  \"supportsLocalAmounts\": false,\n  \"supportsGeographicalRechargePlans\": false,\n  \"denominationType\": \"FIXED\",\n  \"senderCurrencyCode\": \"EUR\",\n  \"senderCurrencySymbol\": \"\u20ac\",\n  \"destinationCurrencyCode\": \"ARS\",\n  \"destinationCurrencySymbol\": \"$\",\n  \"commission\": 3,\n  \"internationalDiscount\": 3,\n  \"localDiscount\": 0,\n  \"mostPopularAmount\": 4.35,\n  \"mostPopularLocalAmount\": null,\n  \"minAmount\": null,\n  \"maxAmount\": null,\n  \"localMinAmount\": null,\n  \"localMaxAmount\": null,\n  \"country\": {\n    \"isoName\": \"AR\",\n    \"name\": \"Argentina\"\n  },\n  \"fx\": {\n    \"rate\": 112.333,\n    \"currencyCode\": \"ARS\"\n  },\n  \"logoUrls\": [\n    \"https:\/\/s3.amazonaws.com\/rld-operator\/76eaeaf7-e614-48c6-80dc-c46f4f13ff4d-size-2.png\",\n    \"https:\/\/s3.amazonaws.com\/rld-operator\/76eaeaf7-e614-48c6-80dc-c46f4f13ff4d-size-3.png\",\n    \"https:\/\/s3.amazonaws.com\/rld-operator\/76eaeaf7-e614-48c6-80dc-c46f4f13ff4d-size-1.png\"\n  ],\n  \"fixedAmounts\": [\n    0.04,\n    0.09,\n    0.15,\n    0.18,\n    0.26,\n    0.36,\n    0.44,\n    0.53,\n    0.61,\n    0.7,\n    0.78,\n    0.87,\n    0.96,\n    1.05,\n    1.14,\n    1.22,\n    1.31,\n    1.4,\n    1.49,\n    1.57,\n    1.66,\n    1.74,\n    2.18,\n    2.62,\n    3.05,\n    3.48,\n    3.92,\n    4.35\n  ],\n  \"fixedAmountsDescriptions\": {},\n  \"localFixedAmounts\": [],\n  \"localFixedAmountsDescriptions\": {},\n  \"suggestedAmounts\": [],\n  \"suggestedAmountsMap\": {},\n  \"geographicalRechargePlans\": [],\n  \"promotions\": [\n    {\n      \"id\": 5902,\n      \"promotionId\": 5902,\n      \"operatorId\": 16,\n      \"title\": \"Movistar Argentina From 01 May 2021 00:00 To 31 May 2021 23:59 (GMT-03:00)\",\n      \"title2\": \"Bonus 5x\",\n      \"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;\",\n      \"startDate\": \"2021-05-01 07:00:00\",\n      \"endDate\": \"2021-06-01 06:59:00\",\n      \"denominations\": \"USD 5 and up\",\n      \"localDenominations\": null\n    }\n<\/pre>\n\n\n\n
Analyzing the result<\/h3>\n\n\n\n
The request you just made got you quite a lot of information about the Mobile Operator behind the number 91154973586<\/strong> (Registered in Argentina).<\/p>\n\n\n\n
While there\u2019s a lot of valuable information in this json object, what you\u2019re looking for is the value associated with the key operatorId<\/code><\/strong>, in this case 16<\/code><\/strong>.<\/p>\n\n\n\n
That number (16<\/code>) is what you need to use to fill the parameters of the call to the TopUp endpoint.<\/p>\n\n\n\n
In summary, you\u2019ll need to make, at least, two API calls besides the one getting you the access token:<\/p>\n\n\n\n
  1. To the Operator auto-detect<\/li>
  2. To the topup endpoint<\/li><\/ol>\n\n\n\n
    On a few occasions the response you\u2019ll get from the first API call will be HTTP 404. <\/p>\n\n\n\n
    This could happen because of several reasons, for instance, the phone number + country combination is invalid.<\/p>\n\n\n\n
    In these situations, besides the HTTP error code, you\u2019ll have some context to determine what happened. You\u2019ll get a json object similar to:<\/p>\n\n\n\n
    {\n  \"timeStamp\": \"2022-02-23 10:29:27\",\n  \"message\": \"Could not auto detect operator for given phone number\",\n  \"path\": \"\/operators\/auto-detect\/phone\/91154973586\/countries\/ES\",\n  \"errorCode\": \"COULD_NOT_AUTO_DETECT_OPERATOR\",\n  \"infoLink\": null,\n  \"details\": []\n}<\/pre>\n\n\n\n
    Finally, there might be a case where the data you provided to the auto-detect endpoint is correct but still you don\u2019t get the answer you\u2019re looking for. This could happen if the number you’re trying to top up has recently been ported to a different operator.<\/p>\n\n\n\n
    Should that be the case your options are:<\/p>\n\n\n\n
    1. To show the end-user a list of every available operator in their country and have them select the appropriate one.<\/li>
    2. Use Reloadly’s Number Lookup service<\/a><\/li><\/ol>\n\n\n\n
      EndPoints mentioned in this article<\/h2>\n\n\n\n