Skip to main content

Reverse Phone Append


Are you compatible with TLS 1.2?
Test your connections before December 4th

Overview

Experian Reverse Phone Append API allows you to validate phone data and returns different types of phone information. This API can also link phone numbers with the person's name and postal address information, in real time. 

You will find this API useful if you need to obtain additional information linked to phone numbers, such as:

  • phone type and status
  • name
  • postal address
  • consumer or business location

This API supports USA and Canada phone numbers only. 

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

Reverse Phone Append 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 Reverse Phone Append 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 Reverse Phone Append 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.  

Synchronous I want the results as soon as possible.

In contrast, with the synchronous integration when a request is fired to the Reverse Phone Append 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. 

Existing customers can view and manage their tokens via the Self Service Portal. For more information about tokens visit our portal help page.

Security

This API supports Cross Origin Resource Sharing (CORS). This is a specification developed by W3C that allows browsers to make cross-domain requests thus enabling client-side integrations. When making a request, the browser will add an origin request header. The API will then respond with a CORS specific response header denoting the origin domains allowed to make requests to the API.

CORS supported OS and browsers:

  • iOS devices (all versions)
  • Safari, IE, and Chrome

 

Permitted URLs

We strongly recommend that you specify the permitted URLs to be used for phone capture. This is essential to prevent fraudulent use of your token on another domain by ensuring that only requests made from your specified URLs are authenticated. See Self Service Portal help for more information about tokens and full instructions on how to set your permitted URLs.

 

 

Asynchronous integration

With this integration, you can fire your request to the Reverse Phone Append 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 Reverse Phone Append 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 Reverse Phone Append API reference defines the available resources, the parameters to include with each request and the expected response values.

 https://api.experianmarketingservices.com/<resource>/PhoneValidatePlus/1.0/<token>/

Asynchronous

Synchronous

Headers

Auth-Token: [Token] 
Content-Type: application/json 

When you make an authenticated API request, your request has to specify the Auth-Token HTTP request header as shown above. Alternatively, the token (auth-token) can be passed as a query parameter in the URL endpoint. 

For example: https://api.experianmarketingservices.com/query/PhoneValidatePlus/1.0/<token>/

If your token is setup with the URL restriction, you will need to ensure that the Permitted URL (in HTTP Referer Header) is sent along with your request.

We strongly recommend that you specify the permitted URLs to be used for phone capture. This is essential to prevent fraudulent use of your token on another domain by ensuring that only requests made from your specified URLs are authenticated. See Self Service Portal help for more information about tokens and full instructions on how to set your permitted URLs. 

Note that all values supplied in the request must be URL encoded. Only include parameters that are needed for the information you want to process. The casing of parameter values is ignored.

 

POST /query

Asynchronous - posts a phone number to the service to be validated. Make a GET /result request to retrieve the results.

Request

https://api.experianmarketingservices.com/query/PhoneValidatePlus/1.0/

Note that URLs that do not specify the version number will default to version 1.0.

Parameters 

ParameterDescription

Number

The calling party number is the phone number of the person who originates the call. 

There are two options for formatting:

  1. With calling country code (e.g. +15026576033)
  2. Without calling country code (e.g. 5026576033) 
    DefaultCountryCode 
    parameter is required for this option

DefaultCountryCode
(optional) 

The calling country code for the phone number in the Number parameter. 

Sample request object

{
  "Number": "8139960713", 
  "DefaultCountryCode": "+1"
}

Sample response

HTTP/1.1 204 No Content
Content-Length: 0
Content-Location:https://api.experianmarketingservices.com/result/PhoneValidatePlus/1.0
/00000000-0000-0000-0000-000000000000
Date: Mon, 10 Jun 2014 08:15:29 GMT

GET /result

Asynchronous - retrieves the results of a Reverse Phone Validate POST /query request. The URL for this request is returned in the Content-Location field name of the response header when making the initial query.

Request

Sample request

GET https://api.experianmarketingservices.com/result/PhoneValidatePlus/1.0/00000000-0000-0000-0000-000000000000

Response

Sample response 

HTTP/1.1 200 OK
Content-Length: 60
Content-Type: application/json
Message: OK
QueryId: 00000000-0000-0000-0000-000000000000
Date: Mon, 10 Jun 2014 08:15:56 GMT
 
 
{
  "Number": "8139960713",
  "AccountType": "Consumer",
  "PhoneType": "LandLine",
  "Name": "Arbea J Bond",
  "FirstName": "Arbea",
  "MiddleInitial": "J",
  "LastName": "Bond",
  "Address": {
     "Country": "USA",
     "Locality1": "Land O Lakes",
     "Number1": "4049",
     "Postcode1": "34638-3524",
     "Province1": "FL",
     "Street1": "Mitchell Rd",
     "Certainty": "FullAddress"
  },
  "Country": "USA",
  "Certainty": "Verified",
}

 

POST /sync/queryresult

Synchronous - posts a phone number to the service to be validated and, once complete, returns the results of the validation along with any additional data.

Request

https://api.experianmarketingservices.com/sync/queryresult/PhoneValidatePlus/1.0/

Note that URLs that do not specify the version number will default to version 1.0.  

Parameters 

ParameterDescription

Number

The calling party number is the phone number of the person who originates the call. 
There are two options for formatting:

  1. With calling country code (e.g. +15026576033)
  2. Without calling country code (e.g. 5026576033) 
    DefaultCountryCode 
    parameter is required for this option

DefaultCountryCode
(optional)

The calling country code for the phone number in the Number parameter. 

Sample request object

{
"Number": "8139960713",
"DefaultCountryCode": "+1"
}

Response

Sample response

HTTP/1.1 200 OK
Content-Length: 60
Content-Type: application/json
Message: OK
QueryId: 00000000-0000-0000-0000-000000000000
Date: Mon, 10 Jun 2014 08:15:56 GMT
 
 
{
  "Number": "8139960713",
  "AccountType": "Consumer",
  "PhoneType": "LandLine",
  "Name": "Arbea J Bond",
  "FirstName": "Arbea",
  "MiddleInitial": "J",
  "LastName": "Bond",  
  "Address": {
     "Country": "USA",
     "Locality1": "Land O Lakes",
     "Number1": "4049",
     "Postcode1": "34638-3524",
     "Province1": "FL",
     "Street1": "Mitchell Rd",
     "Certainty": "FullAddress"
  },
  "Country": "USA",
  "Certainty": "Verified",
}

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:

Element 1Element 2Description
Number  

Submitted phone number, e.g. "8139960713"

AccountType   

"Business", "Consumer" or "NoName"

PhoneType  

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

Name  

Returned business or consumer name, e.g. "Arbea J Bond"

FirstName   Returned business or consumer first name, e.g. "Arbea"
MiddleInitial   Returned business or consumer middle initial, e.g. "J"
LastName   Returned business or consumer last name, e.g. "Bond"
Address   {Address tag starts}
  Certainty "FullAddress", "PartialAddress" or "NoAddress" 
  Number1 House or Building number, e.g "4049"
  Street1 Street name and type, e.g. "Mitchell Rd" 
  Locality Locality or City, e.g. "Land O Lakes"
  Province Province/State, e.g. "FL"
  Postcode1 Postal Code, e.g. "34638-3524"
Address   {Address tag ends}
Country   "USA" or "Canada"
Certainty  

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

Note that these elements are not interdependent and will be returned only after the phone number has been validated.

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 This API supports USA and Canada phone numbers only.
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).

Sample error

Response Header
Content-Type: application/json
Date: Wed, 11 Sep 2013 07:24:02 GMT
Message: Provider failure
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

Response Body
{
  "Number": "8139960713",
  "AccountType": "Consumer",
  "PhoneType": "LandLine",
  "Name": "Arbea J Bond",
  "FirstName": "Arbea",
  "MiddleInitial": "J",
  "LastName": "Bond",  
  "Address": {
     "Country": "USA",
     "Locality1": "Land O Lakes",
     "Number1": "4049",
     "Postcode1": "34638-3524",
     "Province1": "FL",
     "Street1": "Mitchell Rd",
     "Certainty": "FullAddress"
  },
  "Country": "USA",
  "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 certificate might have expired. To manually update your deployment:
  1. Download the update files.
  2. Extract the files.
  3. Install Root.crt in the Trusted Root Certificates Authorities Store.
  4. Install Intermediate1.crt and Intermediate2.crt  in the Intermediate Certificate Authorities Store.
  5. Install api.experianmarketingservices.com.cer in the Personal Certificate Store.

For further help contact support.

Copyright ©, 2014-2017. All rights reserved.