Phone Validation API
VALIDATE PHONE NUMBERS BEFORE SENDING MESSAGES AND FILTER OUT INVALID NON EXISTENT CONTACTS
API Outcome
- Type of service Identify different types of phone number services such as mobile, landline, toll free, special services and more.
- Carrier information Find information about the service provider specific to the location at which phone number is registered.
- Registered location User's registered country name and local area details as registered in service provider's database.
- Country code and prefix Accurate country code and prefix data for more than 230 supported countries in the world.
- Localized and international formats Show localized phone numbers in your application as per user's locale with local and international formats.
Single Contact Validation API Details
Request
| Type | URL |
|---|---|
| POST | https://api.attestr.com/api/{version}/public/checkx/contact |
Request Body Parameters
| Type | Name | Description | Optional (default) | Min Version | Max Version |
|---|---|---|---|---|---|
| String | number | Input phone number to be verified. | Required | v1 |
Only valid E.164 formats with leading country code prefix are supported.
Request Header Parameters
| Type | Name | Value / Description | Optional | Min Version | Max Version |
|---|---|---|---|---|---|
| String | Content-Type | application/json | Required | v1 | |
| String | Authorization | Basic {authToken} | Required | v1 |
If you do not have the authentication token, please refer to Register App to generate one.
Sample Request Payload
{ "number": "+91xxxx565318"}Response
HTTP status code 200
Please note that the valid key decides the availability of rest of the keys in the response. If provided contact number does not exist, all keys except valid and message are omitted. If true, remaining keys will have appropriate data.
| Key | Description | Type | Min Version | Max Version |
|---|---|---|---|---|
| valid | True | false depending on if provided contact number exists and is valid | Boolean | v1 | |
| type | Type of service for the provided contact number | ContactServiceTypeEnum | v1 | |
| localF | Localized format of the input contact number when distributed locally. | Boolean | v1 | |
| intlF | International E.164 format | Boolean | v1 | |
| prefix | Phone number prefix for the country | String | v1 | |
| code | Country code | String | v1 | |
| country | Country where the contact number is registered | String | v1 | |
| area | Area (state) where phone number is registered | String | v1 | |
| carrier | Service provider entity / company | String | v1 | |
| message | Error message if provided number is invalid | String | v1 |
ContactServiceTypeEnum
| Enum Values | Description |
|---|---|
| MOBILE | Cellular mobile service |
| LANDLINE | Fixed landline / dialed line service |
| SPECIAL | Listed under special services such as police, ambulance, fire etc |
| TOLLFREE | Toll free service |
| HOTLINE | Premium paid hotline service |
| SATELLITE | Satellite phone |
| PAGING | Used in paging devices |
Sample Response
Sample response for valid contact number
{ "valid": true, "type": "MOBILE", "localF": "0xxxx565318", "intlF": "+91xxxx565318", "prefix": "+91", "code": "IN", "country": "India (Republic of)", "area": "Andhra Pradesh", "carrier": "Bharti Airtel Ltd"}Sample response for invalid contact number
{ "valid": false, "message": "Provided contact number is not valid"}Error Response
| Parameter | Type | Description |
|---|---|---|
| code | Number | Unique error codes for different errors. Always available. |
| message | String | Error message describing the error. Always Available. |
| details | String | Detail error message. Available only for certain types of errors. |
Error Codes
| HTTP Status | Error Code | Error Message |
|---|---|---|
| 400 | 4001 | Malformed data or missing required parameter values |
| 400 | 4005 | Operation could not be performed due to low credits balance |
| 401 | 4016 | Invalid client authorization |
| 403 | 4031 | Unauthorized access |
| 403 | 4035 | Requested service is not provisioned for your account |
| 403 | 4039 | Client's IP address is not whitelisted |
| 403 | 4035 | Requested service is not provisioned for your account |
| 429 | 4291 | Maximum account rate limit exceeded |
| 429 | 4292 | Maximum API rate limit exceeded |
| 429 | 4293 | Maximum account daily limit exceeded |
| 429 | 4294 | Maximum API daily limit exceeded |
| 500 | 5001 | Request could not be processed |
Sample Error Response
{ "code": 4001, "message": "Malformed data or missing required parameter values"}