Skip to main content

Phone Validate API


Are you compatible with TLS 1.2?
Test your connections as soon as possible to avoid service disruptions. 

Overview

Experian Phone Validate API allows you to validate full 10-digit numbers and identifies phone type in real time. You will find this API useful if you need to obtain phone type and status

This API supports USA and Canada phone numbers only. 

Phone Validate is a RESTful API service. REST is a style of software architecture that provides a convenient and consistent approach to requesting and retrieving data.

Phone Validate API returns data in JSON format. JSON is a common Internet format that provides a simple method of representing arbitrary data structures. According to json.org, it is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others.

Workflows

Using Phone Validate API is as simple as constructing a URL. We support both asynchronous and synchronous communications. Each integration has its own advantages and disadvantages, depending on the usage scenario.

AsynchronousI want more flexibility.

With asynchronous integration, you can fire your request to the Phone Validate service without having to wait for the result to return. The result can be retrieved from the service later, providing more flexibility. 

Note that the result will be removed if it is not accessed within 5 minutes. Also, you may have to make several attempts to retrieve the results if there is a delay in retrieving them back. 

SynchronousI want the results as soon as possible.

In contrast, with the synchronous integration when a request is fired to the Phone Validate service, you will receive your result within the request call itself. Therefore, you have to wait for the request to finish processing before you can continue with the workflow.

Postman collections

We now have pre-configured Postman collections for our APIs.

You can quickly test out the requests and responses and see how the API behaves. Simply import the relevant collections, add your token as a variable and start making requests with your desired parameters.

Get Postman collections

Authentication

Contact your Experian sales representative to create an account.

An Auth-Token is used to authenticate the service. Your Auth-Token must be specified in the request header or passed as a query parameter in the URL. Find out more about tokens. To view and manage your tokens, log into the Self Service Portal

Security

We strongly recommend that you secure your integration to prevent malicious use. 

If you don’t specify CORS origin domains, URLs or IPs that will be allowed to use your token, there’s a risk of other websites accessing and using your integration which you may be charged for.

Depending on your setup, you can specify:

  • CORS origin domains

    Cross Origin Resource Sharing (CORS) is a specification developed by W3C that allows browsers to make cross-domain requests. When making a request to our service, the browser will add an origin request header. Our service will then respond with a CORS specific response header denoting the origin domains allowed to make requests.
    To secure your integration, specify the origin domains that will have access to your integration. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five origin domains.

  • Permitted URLs
    If you're integrating your token into a web form, you can also specify the permitted URLs to ensure that only requests from your domains are authenticated. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five URLs. See an example of a successful response.
  • Whitelisted IPs/IP ranges
    If you're integrating your token to an API service on your server, specify the IP addresses or IP address ranges to ensure that only requests from your servers are authenticated. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five IPs/IP ranges. See an example of a successful response. 

Asynchronous integration

With this integration, you can fire your request to the Phone Validate service without having to wait for the result to return. The result can be retrieved from the service later, providing more flexibility. 

Note that the result will be removed if it is not accessed within 5 minutes. Also, you may have to make several attempts to retrieve the results if there is a delay in retrieving them back.

Alternative integration: synchronous

How does it work?

The client specifies an action using an HTTP POST followed by an HTTP GET to request the result.

Synchronous integration

With this integration when a request is fired to the Phone Validate service, you will receive your result within the request call itself. Therefore, you have to wait for the request to finish processing before you can continue with the workflow.

Alternative integration: asynchronous

How does it work?

The client specifies an action using an HTTP POST to request the result.

API reference

The Phone Validate API reference defines the available resources, parameters and the expected response values. 

API output elements

The response from this API will contain a section (represented as a JSON object) for each type of data returned. Response elements that may be included in this section:

ElementDescription
Number

Submitted phone number, e.g. "8139960713"

PhoneType

"LandLine", "Mobile", "Other" or "Provided number is Invalid".

Certainty

Indicates the confidence of the phone number, e.g. "Verified" or "Unverified".

In JSON, objects and the values within them are unordered. Programs calling the API should therefore never make assumptions about the sequencing of the data returned by it.

Lookup status messages

The status of the call can be found in the response’s header under Message:

Message (in JSON response header)Comments
OK Request has been successfully sent and valid responses are being returned back.
Bad query: Unsupported country The supplied country code is invalid.
Bad query: Malformed JSON in request

Request has been successfully sent but no responses are being returned. Possible causes:

  • Missing a mandatory parameter
  • Invalid JSON format
  • Blank values are being sent
Bad query: Missing security token The token is missing in the request's header or the URL.
Bad query: Missing query id parameter in URL The query id parameter is missing in the URL.
Resource not found The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
Unauthorized: Token not recognized Provided token is incorrect. Please check your token: log into the Self Service Portal > Licenses.
Forbidden: Product not matched Request is not authorized to use the service.
Forbidden: Entitlement disabled Your token has run out of credits. To find token information, log into the Self Service Portal > Licenses.
Phone number has too few digits The submitted phone number is too short - it has to contain 10 digits (excluding the country code).
Phone number has too many digits The submitted phone number is too long - it cannot exceed 10 digits (excluding the country code).

Forbidden: Your IP address is not whitelisted. 

This IP address does not have access to your integration. To whitelist it, log into the Self Service Portal > Licenses.
Forbidden: Your origin domain is not defined. This domain does not have access to your integration. To allow access to it, log into the Self Service Portal > Licenses.

Note that the specific validation status message can also be found in the response body under Message.

Response examples

Sample error

Response Header
Content-Type: application/json
Date: Wed, 11 Sep 2013 07:24:02 GMT
Message: Provider failure
Message: Unauthorized: Token not recognized
QueryId: 5bd1bb45-85b7-4a25-aeb4-7bad67b7249b

Response Body
{}

Sample success

Response Header
Content-Type: application/json
Date: Wed, 11 Sep 2013 07:31:00 GMT
Message: OK
QueryId: 9da8c5cc-b27b-4026-b7a2-f7196367a085
Access-Control-Allow-Origin: https://www.example.com
Access-Control-Expose-Headers: Message, Content-Location 


Response Body
{
"Number": "+15026576033",
"PhoneType": "LandLine",
"Certainty": "Verified"
}

Status codes

These are the HTTP codes the service will explicitly return; however, client programs should be prepared to handle any of the standard HTTP codes.

CodeMessageDescription
200 OK Request processed successfully.
400 Bad Request Request failed due to malformed syntax. Check the response header for more information. 
401 Unauthorized Provided token is incorrect. Please check your token: go to Self Service Portal > Licenses.
403 Forbidden Request is not authorized to use the service.
404 Not Found The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
409 Conflict Result is not ready. Please resubmit the request to try and retrieve the result again.
500 Internal Server Error We have encountered an unexpected server error. Please contact support if the problem persists.
503 Service Unavailable The server is currently unavailable. Please try again or contact support if the problem persists.

Troubleshooting

SSL certificate errors

Your SSL certificates might have expired. You will need to update your certificates with the relevant certificate files. 
  1. Download both Entrust and GlobalSign files. 
  2. Extract the files.
  3. Install the certificates in the correct certificate stores as shown below:
  Trusted RootIntermediatePersonal
Entrust

EntrustCA
EntrustRootCA-G2

EntrustCA-L1K

api.experianmarketingservices.com

GlobalSign

GlobalSignRoot-R1

GlobalSigncloudsslsha2g3r3

EDQincapsula

For further help contact support. 

Connection issues

In order to use our services, you need to ensure that certain IP addresses (listed below) are accessible to you (i.e. not blocked by your firewalls). 

  • 167.107.82.39
  • 45.60.31.210
  • 45.60.32.212
  • 45.60.33.210
  • 45.60.34.212
  • 45.60.35.210
  • 45.60.36.212
  • 45.60.37.210
  • 45.60.38.212
  • 45.60.39.210
  • 45.60.40.212