Skip to main content

Experian Aperture Enrichment

The guide below is for the latest version of Experian Aperture Enrichment. 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 Enrichment ("the API" or "Enrichment") is a real-time REST API that you can use to gain an improved level of insight into individuals, households and geographic areas. For example, you can find out a household's estimated income level.

You can use the API in many different scenarios, depending on your specific needs. A common use case: you want to perform customer segmentation on your website’s sign up page, so you can provide custom-made experiences throughout the user journey.

Currently, the API can enrich data that relates to Australia.

You can append a variety of attributes from our datasets to enrich your customer data.

Datasets

Datasets are collections of consumer data that help you infill missing information and gain additional insight into your customers.

The API can return enriched data based on 3 datasets:

  • Australia ConsumerView - Person Data. This dataset returns linkage information about individuals, e.g. household identification numbers for household lookups.
  • Australia ConsumerView - Household Data. This dataset returns information about households, e.g. corresponding Statistical Areas Level 1 (SA1) codes or Mosaic Types.
  • Australia ConsumerView - Postcode Data. This dataset returns information about addresses based on their post code, e.g. the number of adults living at a given address. 

Find out more about the search keys and attributes you can use for each of the datasets listed above.

What do I need to send my first API request?

  1. Some consumer data you want to enrich.
  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 Enrichment 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. Enter a 3-letter ISO country code in the country field. Currently, only AUS is supported.
  7. (Optional) Under enrichmentRequest, you can replace the keys, the dataset, and related attributes. Note that all of them must be enclosed in quotation marks, e.g. "pin". Alternatively, you can skip this step and use the preset keys, dataset and attributes.
  8. (Optional) Select an option from the Parameter content type and Response content type dropdowns. Check out Supported data formats for more information.
  9. Click the Execute button to send the request to the API.
  10. 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.
    Postman_UI.png
  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) You can replace the keys, the dataset and related attributes. Note that all of them must be enclosed in quotation marks, e.g. "pin". Alternatively, you can skip this step and use the preset keys, dataset and attributes.
  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, and response, metadata and attribute status codes.

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 Enrichment 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 issue 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:

Search keys

When you send a request to the API, you need to specify the search key(s) you want to use.

Note that search keys are dataset-specific, and you can only supply one search key per dataset. If you provide a search key that is specific to another dataset or if you supply multiple search keys for a dataset, your request will be unsuccessful, and the API will return an HTTP status code of 400 – Bad Request.

The table below provides more information about the search keys you can specify for each dataset.   

Australia ConsumerView dataset Search key Description
Person Data pin Unique Experian-assigned person identifier, e.g. 100000047.
email_address The consumer's email address.
mobile The consumer's cell phone number.
Household Data dpid Unique 8-digit identifier allocated to each address maintained in Australia Post’s National Address File, e.g. 31176490.
gnaf_pid Unique 14-character alphanumeric persistent identifier of the address record, e.g. GAVIC420630433.
hin Unique Experian-assigned household identifier, e.g. 987654326.
Postcode Data postcode The postal code or zip code of the address, e.g. 7140.

Note: You can write search keys with uppercase (e.g. PIN) or lowercase (e.g. pin) letters, depending on your preference.

Attributes

When you send a request to the API, you need to specify the dataset-specific attributes you want to use.

Follow the instructions below to view what attributes you can specify for each dataset:

  1. Go to Parameters, request and response bodies and click the POST block, so that it expands.
  2. Go to Responses and click Model.

  3. You can see the attributes for each dataset under EnrichmentV2Result.

Note: You can write attributes with uppercase (e.g. PIN) or lowercase (e.g. pin) letters, depending on your preference.

To find out more about attributes, check out the ConsumerView Fact Sheet.

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:25:17 GMT
Message: OK
X-Rate-Limit-Limit: 1200
X-Rate-Limit-Remaining: 1199
X-Rate-Limit-Reset: 1553858760

RESPONSE BODY
{ "reference_id": "My id Abc 321", "transaction_id": "5bf9141d-87bf-4341-87bc-23269894045e", "result": { "aus_cv_postcode": { "length_of_residence_code": "15", "length_of_residence_description": "14+ yrs", "household_composition_code": "1", "household_composition_description": "Families" } }, "metadata": { "code": "S200", "message": "Success", "detail": "All requested attribute(s) retrieved.", "datasets": { "aus_cv_postcode": { "length_of_residence_code": { "code": "S200", "message": "Match", "value": "15" }, "length_of_residence_description": { "code": "S200", "message": "Match", "value": "14+ yrs" }, "household_composition_code": { "code": "S200", "message": "Match", "value": "1" }, "household_composition_description": { "code": "S200", "message": "Match", "value": "Families" } } } } }

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. Check out Metadata status codes and Attribute status codes for details.
400 Bad Request You didn't specify the keys field. Try submitting another call and make sure the request body contains the keys field. Check out Search keys for details.
You've specified one or more invalid search keys. Try submitting another request and make sure you specify a valid search key for each dataset you use. Check out Search keys for details.
You didn't specify any search keys. Try submitting another request and make sure you specify a search key for each dataset you use. Check out Search keys for details.
You didn't specify any search key for a dataset. Try submitting another request and make sure you specify a search key for each dataset you use. Check out Search keys for details.
You've specified multiple search keys for a dataset. Try submitting another request and make sure you only specify one search key per dataset. Check out Search keys for details.
You didn't specify the attributes field. Try submitting another cal and make sure the request body contains the attributes field. Check out Attributes for details.
You've specified one or more invalid attributes. Try submitting another request and make sure you specify valid attributes. Check out Attributes for details.
You didn't specify any attributes. Try submitting another request and make sure you specify at least one attribute for each dataset you use. Check out Attributes for details.
You've specified one or more empty attributes (e.g. " "). Try submitting another request and make sure you specify attribute names (e.g. "pin"). Check out Attributes for details.
You've specified an invalid country value. Try submitting another request and make sure you specify a valid country value (currently, only AUS is supported).
You've specified an invalid mobile value. Try submitting another request and make sure you specify a valid mobile value. 
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. 
408 Request Timeout 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.
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
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).

Metadata status codes

If you send a request to the API with the Add-Metadata header set to true, and the HTTP status code of the response is 200, the API will return a metadata-level status code, a message and a detail field. 

Code Message Detail
S200 Success All requested attributes retrieved.
S206 Success Some of the requested attributes retrieved.
S204 No match No records matching the specified keys.
S201 Not authorized Attributes not authorized.

Attribute status codes

If you send a request to the API with the Add-Metadata header set to true, and the HTTP status code of the response is 200, the API will return a code and message for each attribute.

Code Message  Description 
S200  Match  Attribute retrieved successfully. 
E404  Not found  The requested attribute could not be found because there are no records matching the specified keys.
E401  Not authorized  You are not authorized to use the requested attribute based on the token you have provided.

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 tens 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. 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 return the enriched data 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
200 Success No cost for suppression attributes (e.g. mail_suppression).
No cost for attributes that cannot be retrieved (attribute status codes other than S200).
2 credits for each Mosaic attribute (e.g. mosaic_segment_2018) from the Australia ConsumerView - Household Data dataset.
1 credit for any other attribute.
Any other response status code No cost.

How many search keys can I specify per API call?

You can only specify one search key per dataset.

If you specify the same search key multiple times (e.g. "postcode": "7140", "postcode": "7150") when you submit a request:

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

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.