Data matching
The ADC RESTful web service allows users to perform single record matching. Each match request relies on forming valid request headers (see https://rbdmqld.atlassian.net/wiki/spaces/ADC/pages/601063691) and match fields dependent on your access.
You will be provided the a unique client username for your web service as well as the data sets you are allowed to match against. These data sets define which fields you must supply in order to perform a match.
How ADC matches records
The ADC service performs basic data massaging on both client field data and death data in order to improve the chance of matches. There are two types of fields in the ADC: TEXT and DATE. Each of these types performs different types of data massaging:
TEXT fields undergo the following transformation before matching:
ASCII-folded to replace common Latin accents with their ASCII equivalent. e.g. Renaé would be converted to: Renae.
Upper case the value to remove case sensitivity. e.g. Renae is converted to RENAE.
Remove apostrophes. e.g. O'BRIEN is converted to OBRIEN.
Split multiple words including hyphenated names into two separate match conditions (when partial matching is enabled). e.g. ANNE-MARIE would be converted to ANNE MARIE and ANNE. This way we can match against first names.
Leading and trailing spaces are removed, and any double spaces are changed to single spaces.
DATE fields undergo the following transformation before matching:
Add any missing zero (0) in the date. e.g. 1/2/2019 would be converted to 01/02/2019.
When partial matching is enabled on DATE fields, the year is separated out as an additional match. e.g. 01/02/2019 would match against the full date 01/02/2019 and 2019. This allows matching on problematic dates such as date of birth where either the informant is unsure of the deceased’s date of birth or there are variations in various forms of ID or the client simply does not store the full date of birth.
Note: ADC will attempt to perform an exact match on the full value of a field before splitting it for partial matching. You will not receive partial matches back when exact matches have been found.
Dataset definitions
Datasets are subsets of matching fields and returning reference data within a full datasource. There can be multiple datasets per datasource and are set up to meet commons matching requirements. Your client API key will be designated one or more datasets depending on your business requirements and agreement with the Australian Death Check.
Common datasets for identifying deceased citizens involve enough shared matching fields to confidently identify against your record and typically return reference data to determine when to take action from, such as the deceased’s date of death.
In the examples below, the FOD datasource has a dataset named NAMEDOB. This dataset allows your API key to search against the given name/s, surname/family name, and date of birth of deceased. This dataset also returns the ACR, state of registration (typically the state the death occurred within), registration year, registration date, date of death and a date of death other (which can be used when the date of death is not certain). Refer to https://rbdmqld.atlassian.net/wiki/spaces/ADC/pages/604143619 for more information.
In all datasets, the matching fields (GN, SN, DB) are required.
Single searches
Endpoint | Method |
|---|---|
/ws/api/search/match | POST |
Request
Model
{
"requestId": "string",
"datasource": "string",
"dataset": "string",
"remoteUser": "string",
"prehashed": boolean,
"fields": [
{
"name": "string",
"value": "string"
}
]
}Note: Prehashed matches are used to match against ADC without exchanging any customer data.
When prehashing is “true”, each field’s value goes through the same transformation described above before it is HMacSHA256 hashed using a shared key between ADC and clients. This hashed value is then Base64 encoded and provided in the request field’s value.
Note: The test environment uses the hash key: “test”. If you are planning on testing the prehashed feature, the field’s value needs to be HMacSHA256 using the hash key and encoded to Base64.
Example
{
"requestId": "your unique request ID",
"datasource": "FOD",
"dataset": "NAMEDOB",
"remoteUser": "joe.bloggs@example.com",
"prehashed": false,
"fields": [
{ "name": "DB", "value": "29/04/1996" },
{ "name": "SN", "value": "Smith" },
{ "name": "GN", "value": "John Henry" }
]
}Response
{
"responseId": "da1760d9-dc49-4e41-b92d-9804d2591c61",
"matchedFields": [
{
"equivalent": 1,
"matchedField": [
"GN",
"SN",
"DB"
],
"references": [
"1000000002"
],
"partial": false
}
],
"referenceData": [
{
"reference": "1000000002",
"results": [
{
"name": "ACR",
"value": "1000000002"
},
{
"name": "STATE",
"value": "QLD"
},
{
"name": "REGYEAR",
"value": "2018"
},
{
"name": "REGNUM",
"value": "12344"
},
{
"name": "DD",
"value": "30/10/2018"
},
{
"name": "DDS",
"value": ""
}
]
}
],
"responseCode": null
}Bulk matching
Endpoint | Method |
|---|---|
/ws/api/bulk/bulksearch | POST |
Request
Bulk search requests use the multipart/form-data Content-Type. This content type allows the ADC to accept a request body that defines both the matching rules and outlines the data attachment’s contents.
Please note there is a 100mb file size limit for the bulk search.
Bulk search performance is impacted based on the number of matches found. The service can match at approximately 60,000 records per second. Each match found has at least 2 milliseconds additional time. This number increases to approximately 10 milliseconds when reference data is returned for matched records.
Model for first multipart attachment
Example request attachment
Example data attachment
Example of raw request
Response
The bulk match will be performed once the payload is verified outside of the transaciton. The searchId response is used to query the status and subsequently download results.
Checking the status of bulk matches
Endpoint | Method |
|---|---|
/ws/api/bulk/status | POST |
Request
Model
Example
Response
Downloading bulk match results
Endpoint | Method |
|---|---|
/ws/api/bulk/download | POST |
Request
Model
Example
Response
Example response