Skip to main content

Experian Aperture Email Validation

The guide below is for the latest version of Experian Aperture Email 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 Email Validation ("the API" or "Email Validation") is a real-time REST API that you can use to validate that both business and personal email addresses actually exist. The API also offers suggestions for correcting email addresses, if they contain syntax errors or typos in domain names.

You can use the API in many different scenarios, depending on your specific needs. A frequent use case: you collect user information before processing their order and want to ensure they did not enter an invalid email address or made a mistake that would prevent them from receiving their order confirmation. 

The API can validate email addresses in real-time from hundreds of providers, including:

  • Global - Gmail, Outlook, Hotmail, Yahoo, iCloud, MSN etc.
  • Local - Comcast, Rogers, Docomo, SoftBank, Sky etc.
  • Regional - Bigpond/Telstra Media (Australia), QQ (China), BT (UK), Brazil Online (Brazil) etc.

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

What do I need to send my first API request?

  1. An email address 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 Email 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) Enter an identifier in the Reference-Id field.
  5. (Optional) Under emailRequest, you can replace the email value with an email address of your choice and the timeout value with a number between 3 and 15. Note that the email value must be enclosed in quotation marks, e.g. "support@experian.com". Alternatively, you can skip this step and use the preset values.
  6. (Optional) Select an option from the Parameter content type and Response content type dropdowns. Check out Supported data formats for more information.
  7. Click the Execute button to send the request to the API.
  8. 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 email value with an email address of your choice and the timeout value with a number between 3 and 15. Note that the email value must be enclosed in quotation marks, e.g. "support@experian.com". 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 EmailValidation 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:19:09 GMT
Message: OK
X-Rate-Limit-Limit: 27000
X-Rate-Limit-Remaining: 26999
X-Rate-Limit-Reset: 1553858400

RESPONSE BODY
{ "reference_id": "My id Abc 321", "transaction_id": "659ebdbe-40e3-4227-9172-315e4b44a596", "result": { "email": "support@experian.com", "confidence": "illegitimate", "verbose": "roleAccount" } }

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 email field. Try submitting another call and make sure the request body contains the email field.
You've specified an email value that is too long. Try submitting another request and make sure the email address you specify contains a maximum of 254 characters.
You've specified an unsupported timeout value. Try submitting another call and make sure you specify a timeout value that is between 3 and 15.
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 increasing the timeout value to a maximum of 15 (seconds) and submit 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 and verbose details.

Confidence Verbose Description
verified verified The mailbox exists, is reachable, and is not known to be illegitimate or disposable.
undeliverable mailboxDisabled The mailbox is disabled.
mailboxDoesNotExist The mailbox does not exist.
mailboxFull The mailbox is full.
syntaxFailure The syntax of the specified email address is incorrect.
unreachable unreachable The domain is not responding to validation requests or does not have any active mail severs. 
illegitimate illegitimate Seed, spamtrap, black hole, technical role account or inactive domain.
roleAccount Role accounts such as support@, sales@, info@ etc.
typoDomain The domain of the email address you've provided was close to a common domain and, although it exists, it is highly unlikely to be correct. 
localPartSpamTrap Known local portions of the email address that may indicate spam traps.
Profanity The email address contains profanity.
disposable disposable The domain is administered by a disposable email provider (e.g. Mailinator).
unknown unknown We were unable to conclusively verify or invalidate the email address.
timeout The request timed out due to the host domain not responding in time.
acceptAll The domain is accept-all, so the email address cannot be validated.
relayDenied The result was validated at the incorrect mail exchanger.

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 email address 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). 

You also have the option of controlling the timeout value yourself: the timeout parameter lets you specify the number of seconds you are willing to wait before a response is returned. If you select a value between 3 (minimum acceptable) and 15 and a timeout occurs, a confidence status of "unknown" and a verbose result of "timeout" will be returned (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. 

Are there any email addresses that the API cannot validate?

The API can validate email addresses from most email service providers.

However, there are some scenarios where the API is unable to validate the email address provided. On such occasions, the confidence level and verbose details returned in the response body will help you understand why the service was unable to conclusively verify the specified email address. 

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
Timeout

How many email addresses can I validate per API call?

The API is designed to validate one email address at a time.

If you enter multiple email addresses when you submit a request:

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

What are corrections?

The API uses an algorithm that looks at the email address submitted for validation and determines whether there are alternative email addresses that are more likely that the one supplied. If there are, the API can return up to 8 suggested corrections (although, the most common scenario is that one correction is returned).    

The table below provides suggested correction examples.

Email address submitted for validation Suggested correction
jane_doe@yahooo.com

jane_doe@yahoo.com

jane,doe@hotmail.com

jane.doe@hotmail.com

johndoe2gmail.com

johndoe@gmail.com

john.doe@al.com

john.doe@aol.com

Note that the API validates email addresses before they are supplied as suggested corrections. Only email addresses that have a confidence level of "verified" or "unknown" can be returned as suggested corrections.

Corrections help correct syntax errors or typos in domain names for the email address submitted for validation. However, the API may return correction suggestions even if the email address supplied is valid. The presence of corrections does not relate to the validity of the email address. Corrections are supplied when they are more likely to be the intended email address than the original.

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.