Data Quality user documentation

United Kingdom

Use the /enrichment/v2 endpoint to append specific United Kingdom health related information such as the National Health Service Authority (or equivalent), Primary Care Organisation (or equivalent), Electoral Ward, and Clinical Commissioning Group (or equivalent) to your validated addresses.

Credit usage

If you have a per-click license, each successful request will deduct one or more credits. Please contact your account manager or contact support for more information. You can also log in to Experian's Self Service Portal to review your product usage.

Headers

Name	Type	Description
Auth-Token	string	Input your unique token here. This is required to submit an API request.
Add-Metadata (Optional)	boolean	Specify whether the response should return all fields and values, in addition to the main core information. The default value of this setting is false.
Reference-Id (Optional)	string	Identifier that will be returned to the response to help you track the request.
Match-Rule (Optional)	string	Currently only `Strict` is supported.
Linkage-Rule (Optional)	string	Currently only `None` is supported.
Layout (Optional)	string	This element is not editable at this time.
Timeout-Seconds (Optional)	integer	Maximum time you are prepared to wait for a response, expressed in seconds. Acceptable values: 2-15. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned. The default value of this setting is 15.

Body parameters

In the request body you can specify:

Name		Type	Description
country_iso		string	The 3-letter ISO country code.
keys
	global_address_key	string	The unique Experian identifier identifing the address to append the Enrichment data to. You can find the `global_address_key` in the responses of the /search and /lookup endpoints, e.g. aWQ9fDEgQXVkcmV5IFphcHAgRHJpdm.
attributes
	gbr_health	collection	Specify the required attributes. Potential attributes for this dataset are: authority_code: Official NHS Authority code, as used by the ONS before January 2011. authority_code_2011: Official code given to the NHS Authority by the ONS in January 2011. authority_name: Official name given to the NHS Authority. pclh_code: Official Primary Care Trust or Local Health Group code, as used by the ONS before January 2011. pclh_code_2011: Official code given to the Primary Care Trust or Local Health Group by the ONS in January 2011. pclh_name: Official name given to the Primary Care Trust or Local Health Group. ward_code: Official Local Authority Ward code, as used by the ONS before January 2011. ward_code_2011: Official code given to the Local Authority Ward by the ONS in January 2011. ward_name: Official name given to the Local Authority Ward. ccg_code: The 9 character area code for Clinical Commissioning Group in England (E.g. E38000056), Local Health Board (LHB) in Wales, Community Health Partnership (CHP) in Scotland, Local Commissioning Group (LCG) in Northern Ireland and Primary Healthcare Directorate (PHD) in the Isle of Man. ccg_name: Official name given to the area, e.g. NHS Eastern Cheshire. doh_code: Department of Health area code, e.g. 01C.

Headers

Name	Type	Description
Reference-Id (Optional)	string	Identifier that was supplied by you in the request header to help you track the request.

Body

The response from the API returns the below attributes. Should an error occur, an error object is returned instead.

Name	Type	Description
reference_id (Optional)	string	Identifier that was supplied by you in the request header to help you track the request.
transaction_id	string	Unique Experian-assigned transaction identifier.
result	object	A `result` object containing the requested attributes.
metadata (Optional)	object	A `metadata` object containing detailed element level match information. This object is only returned when the `Add-Metadata` header is set to True on the request.

Result object

Attributes are only returned if

All attributes in this object are optionally returned - only when the requests includes them in the attributes collection.

Attribute	Description
authority_code	Official NHS Authority code, as used by the ONS before January 2011.
authority_code_2011	Official code give to the NHS Authority by the ONS in January 2011.
authority_name	Official name given to the NHS Authority.
pclh_code	Official Primary Care Trust or Local Health Group code, as used by the ONS before January 2011.
pclh_code_2011	Official code given to the Primary Care Trust or Local Health Group by the ONS in January 2011.
pclh_name	Official name given to the Primary Care Trust or Local Health Group.
ward_code	Official Local Authority Ward code, as used by the ONS before January 2011.
ward_code_2011	Official code given to the Local Authority Ward by the ONS in January 2011.
ward_name	Official name given to the Local Authority Ward.
ccg_code	The 9 character area code for Clinical Commissioning Group in England (E.g. E38000056), Local Health Board (LHB) in Wales, Community Health Partnership (CHP) in Scotland, Local Commissioning Group (LCG) in Northern Ireland and Primary Healthcare Directorate (PHD) in the Isle of Man.
ccg_name	Official name given to the area, e.g. NHS Eastern Cheshire.
doh_code	Department of Health area code, e.g. 01C.

Metadata object

Object is only returned if

This object is only returned when the Add-Metadata header is set to True on the request.

Name			Type	Description
code			string	Response-level metadata code.
message			string	Response-level metadata message.
detail			string	Response-level metadata detail.
datasets			object
	gbr_health		object
		authority_code	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		authority_code_2011	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		authority_name	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		pclh_code	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		pclh_code_2011	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		pclh_name	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		ward_code	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		ward_code_2011	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		ward_name	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		ccg_code	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		ccg_name	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.
		doh_code	object	A MetadataDatasetElement object containing attribute level match information for this gbr_health attribute. Only included if the attribute was requested.

MetadataDatasetElement object

Name	Type	Description
code	string	Attribute-level metadata code.
message	string	Attribute-level metadata message.
value	string	The attribute's value that was returned by the API.

Response status codes

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

Scenarios

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

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

Status Code	Reason phrase	Description
200	Success	Request processed successfully.
400	Bad Request	Request failed due to malformed syntax.
		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 the attributes listed in the enrichment dataset you are using.
		You've specified one or more invalid attributes. Try submitting another request and make sure you specify valid attributes. Check out the attributes listed in the enrichment dataset you are using.
		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 the attributes listed in the enrichment dataset you are using.
		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 the attributes listed in the enrichment dataset you are using.
		You've specified an invalid country value. Try submitting another request and make sure you specify a valid country 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.
		You've submitted an invalid Reference-ID header. Try submitting another request and make sure this header is formatted correctly.
		You've submitted an invalid Add-Metadata header. Try submitting another request and make sure this header is formatted correctly.
401	Unauthorized	Auth-Token provided is incorrect. Sign in to the Self Service Portal to find the right token.
403	Forbidden	Request is not authorized to use this service.
		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 us.
406	Not Acceptable	Request is not in an acceptable format.
406	Not Acceptable	You've specified an invalid Accept header. Try submitting another call and make sure you specify a valid Accept value.
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 us.
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.
429	Too many requests	Too many requests were sent. To protect all customers, your account has been temporarily throttled. Check our rate limiting for more details.
500	Internal Server Error	An unexpected server error was encountered. Try submitting another request. If the issue persists, contact us.
503	Service Unavailable	Service unavailable. Check service status for up-to-date information.

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 code

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.

Request

POST /enrichment/v2 HTTP/1.1
Add-Metadata: true

{
  "country_iso": "GBR",
  "keys": {
    "global_address_key": "aWQ9NzcgU3RhdGlvbiBSb2FkLCBLZWx0eSwgS1k0IDBCTCwgVW"
  },
  "attributes": {
    "gbr_health": [
      "authority_code_2011",
      "pclh_code_2011",
      "ward_code_2011",
      "ccg_code",
      "doh_code"
    ]
  }
}

Response

{
  "transaction_id": "00000000-0000-0000-0000-000000000000",
  "result": {
    "gbr_health": {
      "authority_code_2011": "S08000029",
      "pclh_code_2011": "S03000006",
      "ward_code_2011": "S13003128",
      "ccg_code": "S03000006",
      "doh_code": "006"
    }
  },
  "metadata": {
    "code": "S200",
    "message": "Success",
    "detail": "All requested attribute(s) retrieved.",
    "datasets": {
      "gbr_health": {
        "authority_code_2011": {
          "code": "S200",
          "message": "Match",
          "value": "S08000029"
        },
        "pclh_code_2011": {
          "code": "S200",
          "message": "Match",
          "value": "S03000006"
        },
        "ward_code_2011": {
          "code": "S200",
          "message": "Match",
          "value": "S13003128"
        },
        "ccg_code": {
          "code": "S200",
          "message": "Match",
          "value": "S03000006"
        },
        "doh_code": {
          "code": "S200",
          "message": "Match",
          "value": "006"
        }
      }
    }
  }
}

Was this helpful?

Previous: Regional Location Insights

Next: Government

Experian Address Validation

Enrichment API reference

Next topic:
Introduction
Previous topic:
API specification