Before we jump into the specifics it makes sense to get a few definitions clear.
What is a TopUp
Let’s start by revisiting the concept of a TopUp.
A TopUp operation is a means to send credit from your Reloadly Wallet to a phone around the world.
TopUps can be Local or International depending on your specific needs.
Also, TopUp operations can be made in two modes:
- Synchronous
- Asynchronous
To learn more about Top Up operations please refer to this document.
Why you need a valid number to make a TopUp
In order for a Top Up operation to be successful the information you provide in the parameters operatorId, recipientPhone (Or recipientEmail in the case of Cuba) and countryCode must correspond to an active and pre-paid phone.
If any of these conditions is not met your Top Up will fail.
What end point can be used to test the validity of a phone number
At the moment what you can do to test the validity of a phone number is to use the paid endpoint Number Lookup.
With this API you can get detailed information about a phone number anywhere in the world.
Example test of a phone number’s validity
As with all the other API calls, the first step is to get an access token. Read this article if you need further instructions on how to get one.
Sending the request
Once you have an access token, issuing a request such as:
curl --location --request GET 'https://topups.reloadly.com/operators/mnp-lookup/phone/PHONE_NUMBER/countries/COUNTRY_ISO_CODE?suggestedAmountsMap=true&SuggestedAmounts=true' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Accept: application/com.reloadly.topups-v1+json'
Will return a response like:
{
"id": 17,
"operatorId": 17,
"name": "Personal Argentina",
"bundle": false,
"data": false,
"pin": false,
"supportsLocalAmounts": false,
"supportsGeographicalRechargePlans": false,
"denominationType": "RANGE",
"senderCurrencyCode": "EUR",
"senderCurrencySymbol": "€",
"destinationCurrencyCode": "ARS",
"destinationCurrencySymbol": "$",
"commission": 8.0,
"internationalDiscount": 8.0,
"localDiscount": 0.0,
"mostPopularAmount": 8,
"mostPopularLocalAmount": null,
"minAmount": 0.05,
"maxAmount": 10,
"localMinAmount": null,
"localMaxAmount": null,
"country": {
"isoName": "AR",
"name": "Argentina"
},
"fx": {
"rate": 96.82926,
"currencyCode": "ARS"
},
"logoUrls": ["https://s3.amazonaws.com/rld-operator/51fb6a28-9274-4118-baaa-180297d9a0fc-size-1.png", "https://s3.amazonaws.com/rld-operator/51fb6a28-9274-4118-baaa-180297d9a0fc-size-3.png", "https://s3.amazonaws.com/rld-operator/51fb6a28-9274-4118-baaa-180297d9a0fc-size-2.png"],
"fixedAmounts": [],
"fixedAmountsDescriptions": {},
"localFixedAmounts": [],
"localFixedAmountsDescriptions": {},
"suggestedAmounts": [1, 4, 8],
"suggestedAmountsMap": {
"1": 96.83,
"4": 387.32,
"8": 774.64
},
"geographicalRechargePlans": [],
"promotions": []
}
If the parameters correspond to a valid phone number, otherwise the response will look something like:
{
"timeStamp": "2022-02-25 11:12:58",
"message": "MNP Lookup for given phone number failed",
"path": "/operators/mnp-lookup/phone/549115497368/countries/AR",
"errorCode": "COULD_NOT_AUTO_DETECT_OPERATOR",
"infoLink": null,
"details": []
}
Analyzing the response
In this particular case where all you need is to determine whether the number is valid or not you can simply examine the HTTP response code: a 200 means the number is in fact valid while a 404 signals the opposite.
Additional notes
Bear in mind that this is a paid service so each request will be charged to your account.
In fact, before you can make any of the requests discussed in this article you’ll need to enable the endpoint for the specific country or countries you’ll be looking numbers up.
You can do that from your Reloadly Dashboard, right here. In this screen you’ll have all the information you need, including the price for API usage so you can enable only those queries that are important for you.
