Skip to main content

Experian Aperture Phone Validation (Draft)

The guide below is for the latest version of Experian Aperture Phone Validation. It's the one to use if you are integrating this product for the first time. For previous versions and information on changes, view the release notes.

Overview

Experian Aperture Phone Validation ("the API" or "Phone Validation") is a real-time REST API that you can use to validate phone numbers and obtain additional information about them. For example, you can determine whether the numbers are landline or cell phone numbers.

You can use the API in many different scenarios, depending on your specific needs. A frequent use case: you have a web form or a shopping cart and want to validate the information the user enters before saving it, to ensure it's accurate, and that the user didn't make a mistake. 

The API can validate phone numbers in real-time from over 200 countries and territories, including United States, Canada, United Kingdom, Ireland, Australia, Singapore and France.

Try out a live demo to see Phone Validation integrated into a website.

What do I need to send my first API request?

  1. A phone number you want to validate.
  2. A license to use the product. Talk to your account manager or contact support to get a license if you don’t have one.
  3. Your token, which confirms you are licensed to use Phone Validation and authenticates each request you send to the API. This article explains tokens and includes instructions on where to find yours.  
  4. A tool that allows you to make API calls. Check out Sending my first API request for more information.

Sending my first API request

There are many different ways to make API requests. This section covers two ways you can send a test request to the API.

From this page

Follow the instructions below to send requests to the API from this page:

  1. Go to Parameters, request and response bodies and click the POST block, so that it expands.
    post_block.png
  2. Click the Try it out button in the upper-right corner.
  3. Enter your token in the Auth-Token field.
  4. (Optional) Select true from the Add-Metadata dropdown, so the response also returns metadata information.
  5. (Optional) Enter an identifier in the Reference-Id field.
  6. (Optional) Under phoneRequest, you can replace the number value with a phone number of your choice and the country_code_number value with the corresponding international country calling code. Note that both values must be enclosed in quotation marks, e.g. "1". Alternatively, you can skip this step and use the preset values.
  7. (Optional) Select an option from the Parameter content type and Response content type dropdowns. Check out Supported data formats for more information.
  8. Click the Execute button to send the request to the API.
  9. View the response returned by the API under Responses > Server response. Note that your request was successful only if the API returned an HTTP status code of 200 - Success. Check out Response status codes to find out more about scenarios where the API returns errors.

Using Postman

Postman is a free, easy-to-use third-party application that you can use to send API calls.

Follow these instructions to send requests to the API via Postman:

  1. Download external link.pngand install the free Postman app.
  2. Download this file and unzip it.
  3. Open the Postman app and click the Import button in the upper-left corner.
  4. Import the file you've downloaded and unzipped. 
  5. Go to the Collections tab on the left-hand side panel and click the API request you want to test.
  6. Go to the Headers tab.
  7. Replace the {{Auth-Token}} value with your token.
  8. Go to the Body tab.
  9. (Optional) Replace the number value with a phone number of your choice and the country_code_number value with the corresponding international country calling code. Note that both values must be enclosed in quotation marks, e.g. "1". Alternatively, you can skip this step and use the preset values.
  10. Click the Send button to submit the API request.
  11. View the response returned by the API. Note that your request was successful only if the API returned an HTTP status code of 200 - Success. Check out Response status codes to find out more about scenarios where the API returns errors. 

API reference

This technical section covers authentication, supported data formats, parameters, request and response bodies, response status codes, and confidence level details.

Authentication

You must provide your specific authentication token to send requests to the API.

The token must be entered in the request header, along with the Auth-Token parameter, e.g.

Auth-Token: ab123ab1-abc1-1234-abcd-ab1a123a1a12

You can find your token by signing in to the Self Service Portal.

Supported data formats

The request and response bodies can have the following data formats:

  • application/json
  • application/xml
  • application/x-msgpack

You need to specify the data format in the request header, as illustrated in the sample below.

Content-Type: application/json
Accept: application/json
Parameter Description Required Default
Content-Type The data format of the request you send to the API. Yes N/A
Accept The data format of the response returned by the API. No application/json

Parameters, request and response bodies

Click the POST block under PhoneValidation to expand it.

Once you've expanded the POST block, follow the instructions below to browse it:

  1. Parameters are split into header and body parameters.
      • Headers are required to submit a request to the API.
      • In the case of body parameters, you can see an example, or switch to the model, to view their descriptions. 
  2. Under Responses, you can see the possible HTTP status codes that will be returned together with a response message.
      • If the API returns a status code of 200, it means your request was successful. You can see an example of a successful response, as well as the model.
      • If the API returns any other code, it means there was an error. Check out Response status codes for details.

Base URL:

Successful response example

Below you have an example of a successful response returned by the API.

RESPONSE HEADER
Content-Type: application/json; charset=utf-8
Date: 29 Mar 2019 11:12:06 GMT
Message: OK
X-Rate-Limit-Limit: 9000
X-Rate-Limit-Remaining: 8999
X-Rate-Limit-Reset: 1553857980

RESPONSE BODY
{ "reference_id": "My id Abc 321", "transaction_id": "f27b07f3-286b-4dd4-b9a8-274d00f9a5c9", "result": { "number": "6175014020", "phone_type": "Mobile", "country": "USA", "confidence": "Verified" }, "metadata": { "phone_detail": { "validated_phone_number": "16175014020", "validated_country_code": "1", "country_name": "United States", "operator_name": "Sprint", "ported_operator_name": "Verizon (Verizon Wireless)", "ported_country_name": "United States of America", "ported_country_code": "1", "is_roaming": "false", "mccmnc": "311480" } } }

Response status codes

Each response you receive from the API will also return an HTTP status code. 

The table below will help you identify the reason why you are getting a certain response.

HTTP status code Title Scenario
200 Success You've submitted a successful request and a valid response was returned.
400 Bad Request You didn't specify the number field. Try submitting another call and make sure the request body contains the number field.
You didn't provide an authentication token. Try submitting another request and make sure you specify your token, which you can find by signing in to the Self Service Portal.  
You've submitted a malformed request body. Try sending another call and make sure the request body contains all required fields and that they are formatted correctly.
You've submitted an empty request body. Try sending another call and make sure the request body contains all required fields. 
401 Unauthorized The authentication token you've provided is incorrect. Sign in to the Self Service Portal to find the right token. 
403 Forbidden The authentication token you've provided is valid, but it's associated with another product or you have insufficient credits. Sign in to the Self Service Portal to check if you are using the right token and if you have credits.  
The authentication token you've provided is disabled. Sign in to the Self Service Portal to activate the token. 
The domain you've sent the request from does not have access to your integration. Sign in to the Self Service Portal to whitelist the domain.
The IP address you've sent the request from does not have access to your integration. Sign in to the Self Service Portal to whitelist the IP address.
404 Not Found The resource you've requested could not be found. Try submitting another call and make sure you're using the correct endpoint URL. If the issue persists, contact support
406 Not Acceptable You've specified an invalid Accept header. Try submitting another call and make sure you specify a valid Accept value. Check out Supported data formats for details. 
415 Unsupported Media Type You've specified an invalid Content-Type header. Try submitting another call and make sure you specify a valid Content-Type value. Check out Supported data formats for details. 
429 Too Many Requests You've submitted too many requests. To protect all customers, your account has been temporarily throttled. Check out Rate limiting for details.
500 Internal Server Error An unexpected server error was encountered. Try submitting another request. If the issue persists, contact support
Your request has timed out (the web server failed to respond in the specified time frame). Try submitting another request. If the issue persists, contact support
503 Service Unavailable The service is currently unavailable. You can check the API's uptime and downtime by going to the service status page.

Note: The response body will also contain details about the scenarios presented above (with the exception of 404, 406 and 415). 

Confidence level

If the HTTP status code of the response is 200, among other fields, the response body will contain a confidence level. 

Confidence Description
Verified Number format validated and number verified.
Absent Number format validated and number verified via network lookup but not currently available (e.g. phone off, out of range).
Teleservice not provisioned Valid number but not active on a network.
Unverified Invalid number format supplied.
Unknown Valid number format but not verified with network lookup.

How to integrate the API

You need an active license and your specific token to use the API. Talk to your account manager or contact support to get a license if you don’t have one.

Ask us for help

If you’ve purchased Professional Services support along with your license, contact us for assistance. Our consultants are highly skilled in all key programming languages and they will help you set up and integrate the API.

Swagger

To view the API's Swagger specification in JSON format, go to Parameters, request and response bodies and click the View specification link under the POST block. 

Use Swagger Codegen to quickly generate client integration code in the language you are using, such as C#, Java, Perl, PHP, Python or Ruby.
swagger-languages.png

Swagger Codegen is available to downloadexternal link.pngon GitHub, along with a README.

The tool is also available as a web-based versionexternal link.png

As an alternative to Codegen, you can use the Swagger Editor external link.pngto generate client integration code: upload the Swagger specification and select your programming language of choice from the Generate Client dropdown.

Rate limiting and timeouts

To ensure that our products perform at consistently high service levels, we set both a rate limit and a timeout value.

Rate limiting

Rate limiting is enforced on a per-account basis and it is shared across all your licenses, integrations and tokens.

You can send hundreds of requests per second, so it is unlikely you will breach the rate limiting threshold, but if you do, then calls from any of your tokens will return an HTTP status code of 429 - Too Many Requests until the window resets and you can submit requests successfully once again.

To help prevent yourself from hitting these limits and to understand HTTP 429 - Too Many Requests further, the API returns headers which detail your current rate limit status. 

Header Description Example
X-Rate-Limit-Limit The maximum number of requests a customer is allowed to make per minute. 150
X-Rate-Limit-Remaining The number of requests you have remaining in the current rate limit window. 5
X-Rate-Limit-Reset The time at which the current rate limit window resets. Expressed in UTC epoch seconds. 1547453281

Timeouts

The API tends to respond in 3-5 seconds to each request you send. However, since we are sending a live ping to check the phone number sent for validation, it can sometimes take longer for the response to be returned. The maximum time we allow is 15 seconds for each call that is submitted to the API. If we cannot determine the correct response in this time, you will receive an HTTP status code of 500 (note that you are not charged for these responses). 

FAQs

This section provides answers to frequently asked questions and offers guidance on some common issues you might come across when using the API.

How do I check if the API is working?

To check service availability, go to the service status page. There you can see if there are any current issues and you can subscribe to updates, so you're always informed about the API's uptime and downtime. 

How do I check my token works?

To check if your token is working correctly, you need to test it, by sending an API request.

If you get a response code of 403, check out My token isn't working. What should I do?

How do I secure my token?

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

Find out more about the steps you can take to secure your token. 

How long does it take for the API to respond?

Check out Timeouts to find out more about the API's response time.

How many credits does an API call cost?

The table below provides information about the costs of submitting a request to the API.

Scenario Cost per request
200 Success 1 credit
Any other status code No cost

How many phone numbers can I validate per API call?

The API is designed to validate one phone number at a time.

If you enter multiple phone numbers when you submit a request:

  • Only the last number in the list will be validated, provided the data format is application/json or application/x-msgpack.
  • Only the first number in the list will be validated, provided the data format is application/xml.

Which product does this API support?

The API supports the product "Global Mobile Validate", which covers over 200 countries. If you have a license for a country-specific dataset, you need to use an earlier version of the API.

Connection issues

To use the API, check that the following IP addresses aren't blocked by your firewall:

  • 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

The API uses TLS 1.2 encryption. Find out more.