Skip to main content

Phone Validate v2

Overview

Phone Validate v2 is a web service that allows you to validate phone numbers and obtain additional information related to those numbers.

This web service can be accessed in real-time by submitting a request to the web service endpoint. The service will return a response in JSON format that contains information about the validated phone number.

We currently support mobile numbers for United States, Canada, United Kingdom, Ireland, Australia, Singapore, and France. 

For the United States and Canada, the coverage extends to landline numbers as well.

Phone Validate v2 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 v2 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 v2 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 v2 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 Phone Validate v2 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 Phone Validate v2 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 v2 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 v2 API reference defines the available resources, the parameters to include with each request and the expected response values. 

 https://api.experianmarketingservices.com/<resource>/PhoneValidate/2.0/<token>/

Asynchronous

Synchronous

Headers

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

To make an API request, your request has to specify the security token as part of 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/PhoneValidate/2.0/<token>/

If your token is set up 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. 

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/PhoneValidate/2.0/

Parameters 

ParameterDescription

Number

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

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

    For UK, Ireland, Australia, Singapore and France, append a '0' before the number with this option.

Supported CountryDefault Country Code
Australia +61
France +33
Ireland +353
Singapore +65
UK +44
USA & Canada +1

Sample request object

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

Response

Sample response

Content-Location:
https://api.experianmarketingservices.com/result/PhoneValidate/2.0/00000000-0000-0000-0000-000000000000
Date: Wed, 11 Sep 2013 08:04:12 GMT

GET /result

Asynchronous - retrieves the results of a Phone Validate v2 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/PhoneValidate/2.0/00000000-0000-0000-0000-000000000000

Response

Sample response 

{
  "ResultCode": "0",
  "AdditionalPhoneInfo":
  {
     "TimeZone": "Eastern",
     "PointCode": "Non-protected 48 states, Alaska, Hawaii",
     "DaylightSavingObserved": "Yes",
     "Dialable": "Yes",
     "StateProvince": "FL"    
  },
  "Number": "8139960713",
"PhoneType": "LandLine", "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.

Request

https://api.experianmarketingservices.com/sync/queryresult/PhoneValidate/2.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 of formatting:

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

    For UK, Ireland, Australia, Singapore and France, append a '0' before the number with this option.

Supported CountryDefault Country Code
Australia +61
France +33
Ireland +353
Singapore +65
UK +44
USA & Canada +1

Sample request object

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

Response

Sample response

{
  "ResultCode": "0",
  "AdditionalPhoneInfo":
  {
     "TimeZone": "Eastern",
     "PointCode": "Non-protected 48 states, Alaska, Hawaii",
     "DaylightSavingObserved": "Yes",
     "Dialable": "Yes",
     "StateProvince": "FL"    
  },
  "Number": "8139960713",
"PhoneType": "LandLine", "Certainty": "Verified", }

API output elements

A successful lookup of a telephone number will return information about the number supplied.

Generic response body fields

FieldDescription
ResultCode

Status code of the submitted phone. See result codes for details.

Certainty

Description of the ResultCode

PhoneType

Type of the submitted phone number, e.g. "LandLine", "Mobile", "Provided number is Invalid"

Number

Phone number supplied

UK, Ireland, France, Australia and Singapore specific
FieldDescription
ValidatedPhoneNumber Verified number in international format without the leading "+", e.g. "447123456789"
CountryCode Home country relating to the phone number, e.g. "44"
CountryIso Country ISO alpha-2 code relating to the phone number, e.g. "Gb"
CountryName Name of the country relating to the phone number, e.g. "United Kingdom"
OperatorName Company name of the MSISDN Operator, e.g. "T-Mobile"
OperatorAlias Alternate name for the MSISDN Operator, e.g. "One2one"
OperatorCountryIso Country ISO alpha-2 code relating to the operator. If the UK mobile telephone is roaming internationally, the ISO code will show the country in which the phone is currently connected.
OperatorCountryName Name of the country relating to the operator. If the UK mobile telephone is roaming internationally, the country name will show the country in which the phone is currently connected.
PortedStatus "Yes" or "No" indicating whether the mobile number is ported from one operator to another.
PortedOperatorName Operator from which the mobile number is ported.
PortedOperatorAlias Alternate name for the operator from which the mobile number is ported.
USA and Canada specific
FieldDescription
PointCode

Similar to an IP address in an IP network. It is a unique address for a node to identify the destination of a message signal unit. 

DaylightSavingObserved "Yes" or "No" indicating Daylight Time Saving flag.
Dialable "Yes" or "No" indicating dialable flag.
StateProvince State or province of the phone number. 
TimeZone Timezone of the phone number. 

USA & Canada examples

FieldExample
PointCode

0 = non-protected 48 states, Alaska, Hawaii
1 = protected code
2 = Canadian
3 = Caribbean
4 = Mexican
5 = 900 service number
6 = PCS

StateProvince

AL = Alabama
AK = Alaska
AZ = Arizona
AR = Arkansas
CA = California
CO = Colorado
CT = Connecticut
DE = Delaware
DC = District of Columbia
FL = Florida
GA = Georgia
HI = Hawaii
ID = Idaho
IL = Illinois
IN = Indiana
IA = Iowa
KS = Kansas
KY = Kentucky
LA = Louisiana
ME = Maine
MD = Maryland
MA = Massachusetts
MI = Michigan
MN = Minnesota
MS = Mississippi
MO = Missouri
MT = Montana
NE = Nebraska
NV = Nevada
NH = New Hampshire
NJ = New Jersey
NM = New Mexico
NY = New York
NC = North Carolina
ND = North Dakota
OH = Ohio
OK = Oklahoma
OR = Oregon
PA = Pennsylvania
RI = Rhode Island
SC = South Carolina
SD = South Dakota
TN = Tennessee
TX = Te xas
UT = Utah
VT = Vermont
VA = Virginia
WA = Washington
WV = West Virginia
WI = Wisconsin
WY = Wyoming
AS = American Samoa
FM = Federated States of Micronesia
GU = Guam
MH = Marshall Islands
NN = CNMI (N. Marianas)
PW = Palau
PR = Puerto Rico
UM = U.S. Minor Outlying Islands
VI = U.S. Virgin Islands
AI = Anguilla
AN = Antigua
BA = Bahamas
BD = Barbados
BM = Bermuda
BV = British Virgin Islands
CQ = Cayman Islands
DM = Dominica
DR = Dominican Republic
GN = Grenada
JM = Jamaica
RT = Montserrat
KA = St. Kitts & Nevis
SA = St. Lucia
ZF = St. Vincent
TR = Trinidad & Tobago
TC = Turks & Caicos
AB = Alberta
BC = British Columbia
MB = Manitoba
NB = New Brunswick
NF = Newfoundland
NT = Northwest Territory
NS = Nova Scotia
VU = Nunavut Territory
ON = Ontario
PE = Prince Edward Island
PQ = Quebec
SK = Saskatchewan
YT = Yukon Territory
MX = Mexico

Time Zone

0 = not applicable
1 = Samoa
2 = Hawaii
3 = Alaska/ Yukon
4 = Pacific
5 = Mountain
6 = Central
7 = Eastern
8 = Atlantic
9 = Newfoundland

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: Invalid phone number

This API supports United States, Canada, United Kingdom, Ireland, Australia, Singapore and France mobile phone numbers. For the United States and Canada, the coverage extends to landline numbers as well.

Bad query: Invalid input parameter value

Check the parameter values you've entered are valid. Possible causes:

  • Missing a mandatory parameter
  • The country code that you have supplied is invalid
Bad query: Malformed JSON in request 

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

  • 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 the following number of digits (excluding the country code):

  • North America: 10
  • United Kingdom: 10
  • Australia: 9
  • France: 9
  • Ireland: 9
  • Singapore: 8
Phone number has too many digits

The submitted phone number is too long - it cannot exceed the following number of digits (excluding the country code):

  • North America: 10
  • United Kingdom: 10
  • Australia: 9
  • France: 9
  • Ireland: 9
  • Singapore: 8

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
{
"ResultCode": "0"
"AdditionalPhoneInfo": 
{
"TimeZone": "Eastern",
"PointCode": "Non-protected 48 states, Alaska, Hawaii",
"DaylightSavingObserved": "Yes",
"Dialable": "Yes",
"StateProvince": "FL"
},
"Number": "8139960713"
"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.

Result codes

ResultCodeCertaintyComment
0 Unverified Invalid number format supplied.
1 Unknown Valid number format but not verified with network lookup.
2 Absent Number format validated and number verified via network lookup but not currently available (i.e. phone off, out of range).
3 Verified Number format validated and number verified.
4 Teleservice not provisioned Valid number but not active on a network.

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.