Skip to main content

Aperture Enrichment

Overview

Aperture Enrichment is a global data enrichment service enabling your organization to gain an improved level of insight into individuals, households and geographical areas. You can append a variety of attributes from Experian reference data sets, at the point of interaction, to fully enrich your data.

The datasets currently available are:

Workflow

The service supports a very simple workflow:

  • Make an enrich request, providing the dataset code, search key and attributes to be returned.
  • Enrichment will authenticate, validate and process the request.
  • For an invalid request, Enrichment will provide an appropriate http response and request status code(s).
  • For a valid request, Enrichment will return the corresponding value from the reference dataset for each requested attribute. If the requested attribute is not found, Enrichment will return a default null value for the particular attribute.

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. Find out more about tokens. To view and manage your tokens, log into the Self Service Portal

Security

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

If you don’t specify URLs or IPs that will be allowed to use your token, there’s a risk of other websites accessing and using your integration which you may be charged for.

Depending on your setup, you can specify:

  • Permitted URLs
    If you're integrating your token into a web form, we recommend that you specify the permitted URLs to ensure that only requests from your domains are authenticated. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five URLs.
  • Whitelisted IPs/IP ranges
    If you're integrating your token to an API service on your server, specify the IP addresses or IP address ranges to ensure that only requests from your servers are authenticated. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five IPs/IP ranges. 

API reference

The Aperture Enrichment API reference defines the available resources, parameters and the expected response values.

Attributes

The available attributes for the supported datasets are listed below.

ConsumerView Australia - Person data

Dataset code - AUS_CV_Person

Search key(s) - pin, email_address or mobile

Note that only one search key can be used per dataset for each request.

AttributeDescription
pin  A unique Experian person identifier. 
title  Consumer's title. 
first_name  Consumer's first name. 
middle_name  Consumer's middle name. 
surname  Consumer's surname. 
gender  Consumer's gender.  
date_of_birth  Consumer's date of birth.  
landline 

Consumer's contact - landline. 

An additional landline_suppression attribute will be returned if this landline is suppressed and should not be contacted.  

mobile 

Consumer's contact – mobile. 

An additional mobile_suppression attribute will be returned if this mobile is suppressed and should not be contacted. 

email_address 

Consumer's contact - email address.  

An additional email_suppression attribute will be returned if this email_address is suppressed and should not be contacted. 

hin  A unique Experian household identifier. 

ConsumerView Australia - Household data

Dataset code - AUS_CV_Household

Search key(s) - dpid, gnaf_pid or hin

Note that only one search key can be used per dataset for each request.

AttributeDescription
hin A unique Experian household identifier.
address

The full address.

An additional mail_suppression attribute will be returned if the address is suppressed and should not be contacted.

suburb The suburb of the address .
postcode The postal code of the address. 
state The state of the address. 
residential_flag Indicates whether the address is residential. 
gnaf_pid

The persistent identifier of the address. This is a unique 14-character alphanumeric identifier of the address record; for example,  GANSW716798454”.

An additional mail_suppression attribute will be returned if the address is suppressed and should not be contacted.

gnaf_latitude The address-level latitude in degrees.
gnaf_longitude The address-level longitude in degrees.
meshblock The Mesh Block ID. This element consists of 15 alphanumeric characters: a 4 character descriptor, followed by the 11 digit Mesh Block Code.
sa1 The 7 digit SA1 code 
local_government_area_code The Local Government Area persistent identifier.
local_government_area_name The Local Government Area name. 
mosaic_group The Mosaic group, e.g. K
mosaic_type The Mosaic group and type, e.g. K39 
mosaic_segment The Mosaic group, type and segment e.g. K39_4
affluence_code A rating indicating the household level of wealth based on household demographics, assets and investments. 
affluence_description Description of the code returned for the above attribute. 
adults_at_address_code Estimate of the number of people aged 18 and over in a household. 
adults_at_address_description Description of the code returned for the above attribute.
children_at_address_code_0_10_years A prediction of the presence of children aged 0-10 in a household. Code represents one of 10 likelihood bands. 
children_at_address_description_0_10_years Description of the code returned for the above attribute. 
children_at_address_code_11_18_years A prediction of the presence of children aged 11-18 in a household. 
children_at_address_description_11_18_years Description of the code returned for the above attribute. 
credit_demand_code An indicator of demand for credit at the sub meshblock level. For privacy reasons, credit data is aggregated to a geographical region, rather than a single address. 
credit_demand_description Description of the code returned for the above attribute. 
channel_preference Channel Preferences classifies every Australian household into one of eight unique segments based on their most preferred form of media. This is provided as a code ranging from 1 to 8.
channel_preference_description Channel Preferences classifies every Australian household into one of eight unique segments based on their most preferred form of media. This is provided as a description.
household_income_code Prediction of annual income of the household. Code represents one of 7 income bands.  
household_income_description Description of the code returned for the above attribute. 
household_composition_code Indication of the type of household in which the people at an address are living in. Code represents one of 6 bands. 
household_composition_description Description of the code returned for the above attribute. 
head_of_household_age_code A prediction of the age for the person likely to be head of household. Code represents one of 15 age bands. 
head_of_household_age_description Description of the code returned for the above attribute. 
lifestage_code An indication of the stage of life of the household occupants. Represents one of 10 bands.  
lifestage_description Description of the code returned for the above attribute. 
length_of_residence_code An estimate of the length of time a person or family has lived at an address. Code represents one of 15 bands. 
length_of_residence_description Description of the code returned for the above attribute. 
mosaic_factor1_score Mosaic factor score for Family Composition
mosaic_factor2_score Mosaic factor score for Prosperity
mosaic_factor3_score Mosaic factor score for Dependants
mosaic_factor4_score Mosaic factor score for Cultural Diversity 
mosaic_factor5_score Mosaic factor score for Housing Ownership 
mosaic_factor1_percentile Mosaic factor percentile for Family Composition 
mosaic_factor2_percentile Mosaic factor percentile for Prosperity
mosaic_factor3_percentile Mosaic factor percentile for Dependants
mosaic_factor4_percentile Mosaic factor percentile for Cultural Diversity
mosaic_factor5_percentile Mosaic factor percentile for Housing Ownership
risk_insight_code Indicator of risk at the sub meshblock level. For privacy reasons, the bureau data is aggregated to a geographical region, rather than a single address. Code represents one of 12 bands. 
risk_insight_description Description of the code returned for the above attribute. 

ConsumerView Australia - Postcode data

Dataset code - AUS_CV_Postcode

Search key - postcode

Note that only one search key can be used per dataset for each request.

AttributeDescription
 postcode The postal code of the address.
 adults_at_address_code Estimate of the number of people aged 18 and over in a household.
 adults_at_address_description Description of the code returned for the above attribute.
 affluence_code A rating indicating the household level of wealth based on household demographics, assets and investments.
 affluence_code_description Description of the code returned for the above attribute.
 children_at_address_code_0_10_years A prediction of the presence of children aged 0-10 in a household. Code represents one of 10 likelihood bands.
 children_at_address_description_0_10_years Description of the code returned for the above attribute.
 children_at_address_code_11_18_years A prediction of the presence of children aged 11-18 in a household.
 children_at_address_description_11_18_years Description of the code returned for the above attribute.
 credit_demand_code An indicator of demand for credit at the sub meshblock level. For privacy reasons, credit data is aggregated to a geographical region, rather than a single address.
 credit_demand_description Description of the code returned for the above attribute.
 head_of_household_age_code A prediction of the age for the person likely to be head of household. Code represents one of 15 age bands.
 head_of_household_age_description Description of the code returned for the above attribute.
 household_income_code Prediction of annual income of the household. Code represents one of 7 income bands. 
 household_income_description Description of the code returned for the above attribute.
 length_of_residence_code An estimate of the length of time a person or family has lived at an address. Code represents one of 15 bands.
 length_of_residence_description Description of the code returned for the above attribute.
 lifestage_code An indication of the stage of life of the household occupants. Represents one of 10 bands. 
 lifestage_code_description Description of the code returned for the above attribute.
 mosaic_group Mosaic classification group. One of 13.  e.g. K
 mosaic_type Mosaic classification group and type. One of 13 groups and 49 types. e.g. K39.
 household_composition_code Indication of the type of household in which the people at an address are living in. Code represents one of 6 bands.
 household_composition_description Description of the code returned for the above attribute.
 risk_insight_code Indicator of risk at the sub meshblock level. For privacy reasons, the bureau data is aggregated to a geographical region, rather than a single address. Code represents one of 12 bands.
 risk_insight_description Description of the code returned for the above attribute.

Response codes

HTTP response codes

These are the standard HTTP response codes the service will explicitly return. In addition to these codes, it is recommended that client programs are prepared to handle any of the standard HTTP codes. 

CodeMessageDescription
200 Ok Request processed successfully.
400 Bad request Request failed due to malformed syntax. 
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.
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.

General status codes

CodeMessageDescription
200 OK Request has been successfully sent and valid responses are being returned back.
400 Bad query: Missing security token The token is missing in the request's header or the URL.
400 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
400 Bad query: Empty request body Request’s body is empty.
401 Unauthorized: Token not recognized Provided token is incorrect. Please check your token: log into the Self Service Portal > Licenses
403 Forbidden: Product not matched Request is not authorized to use the service.
403 Forbidden: Entitlement disabled  Your token has run out of credits. To find token information, log into the Self Service Portal > Licenses.

Transaction level status codes

Http response codeApplication status codeMessageDetails
200 S200 Success All requested attribute(s) retrieved.
200 S206 Success Some of the requested attribute(s) retrieved.
200 S204 No match No records matching the specified search key(s).
200 S201 Not authorized Attributes not authorized.
400 E400 Bad request

There is something wrong with the formatting of the request, i.e. bad syntax. This message is normally accompanied by description providing more detail. Sample messages/scenarios:

  • Search key(s) are invalid
  • Required search key(s) are not specified
  • Required attribute(s) are not specified
  • Search field may not be null
  • Attribute field may not be null
  • Duplicate search key <search key name> found
  • Country code not supported
  • Missing request header 'Country' for method parameter of type String
  • Multiple search keys for dataset <dataset name> not supported
  • No search key for dataset <dataset name>
  • Invalid email
  • Invalid mobile phone number
  • Bad mobile phone number format
500 E500 Processing error Please contact support.

Attribute level status codes

Http response code Application status code Message Description 
200  S200  Match   The requested attribute is retrieved successfully.
200  E404  Not found   The requested attribute is not found.
200  E401  Not authorized   You are not authorized to use the requested attribute based on the token you have provided.