Phone Number Validation API
Save time and money by making sure that you are only reaching out to valid and active numbers. The Phone Number Validation API helps you avoid wasted effort and money and helps you get better insights into your user base.
Do you have a list of phone numbers you want to validate on the fly? Good thing we have our Phone Number Validation API to help you!
Benefits
- Save a lot of money by avoiding sending SMS and Voice calls to deactivated numbers.
- Have more accurate expectations on response rates / impact rates.
- Know which of your customers/beneficiaries still have active numbers.
The cost is $0.02 per phone number validation request.
HTTP Method & Headers
The HTTP method is POST using this URL:
https://api.engagespark.com/v1/validate
You’ll need to set the following HTTP Headers:
Key | Value |
Authorization | Token {API_KEY} |
Content-type | application/json |
Replace {API_KEY} with your actual API Key from your account. Find it in your profile under Account Settings > API Key (https://app.engagespark.com/account/profile/info).
Alternatively, you may use this API via a GET request and include the parameters as query string parameters. If a GET request, make sure to still pass the Authorization header.
Parameters
{ "phoneNumber": "639123456789", "organizationId": "123" }
Request Body Definition
Key | Description | Data Type | Required | Example |
phoneNumber | The mobile number you want to validate. The phone number must be in international format (with country code e.g., 63). Please do not include a + sign. | String | Yes | 639123456789 |
organizationId | The organization id of the account sending the validation request. Find it in your organization profile: https://app.engagespark.com/account/organization/info | String | Yes | 123 |
Response Body Definition
Sample Successful Request
{ "phoneNumber": "639123456789", "organizationId": "123", "validationStatus": "Invalid", "phoneNumberCountry": "PH" }
Possible Validation Statuses
Validation Status | Definition | Account Charged |
Valid and connected to network | This is a live number that at the time we ran the validation, the number was connected to the phone network. | Yes |
Valid, but not connected to network | This is a live number, but at the time we ran the validation, the number was not connected to the phone network. It will probably be connected to the phone network at a later point in time, though there is a possibility that this sim card has already been discarded and will not be reconnected. | Yes |
Invalid | This is an invalid number/deactivated SIM. | Yes |
We are unable to run phone number validation on this number | We are able to perform phone number validation on most mobile phone numbers in the world, but not all. The number you passed is a number for which we cannot perform phone number validation. | No |
Errors (these responses will come as standard HTTP response status code errors in the 400 range, not as JSON)
Errors | Definition | Account Charged |
Invalid input, not a possible phone number | This is not a possible valid number. Some instances where a number is deemed as not a possible number is when the phone number length is either less than or more than what it should be, the country code is not included, or it is simply not a valid number. | No |
Required parameter missing | One or more fields is missing. Please make sure to include the 3 required fields: organizationId, phoneNumber, and apiToken. | No |
Invalid credentials | The apiToken you passed does not have the requisite permissions for the organizationId you passed. | No |
Insufficient funds. Please add funds to your account and try again. | Insufficient funds. Please add funds to your account and try again. | No |