# ADC Check Bulk

`POST /adc_checks`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/adc_checks`
- Sandbox: `POST https://sandbox-gdapi.globaldata.net.au/api/v2/adc_checks`

The ADC Check Bulk API allows you to check if an individual is recorded as deceased against the ADC (Australian Death Check) service.

This endpoint allows multiple requests to be simultaneously made in a single query by providing a list of requests in the requests array.

## ADC Check

The returned records are checked against the ADC (Australian Death Check) service and any matching records are returned
in the 'matches' field of the response. Note that the ADC check is performed based on the name and date of birth
of the individual. The results will also include the state of the individual, and this should be taken into account
when determining if the result is a match.

When searching a name, the first and last names must match exactly. The optional middle name(s) can be partial matches.
It is recommended that the full name (including middle names) are used when searching for a name.

### Examples:

Assuming the ADC has the following record:
Name: John Henry Smith

Different search names and the expected matched name result:

| Searched First Name | Searched Middle Name | Searched Last Name | Matched First Name | Matched Last Name | name_match |
|------------|-------------|-----------|--------------------|-------------------|------------|
| John       | Henry       | Smith     | John Henry         | Smith             | exact      |
| John       | Henry Peter | Smith     | John Henry         | Smith             | partial    |
| John       | Peter Henry | Smith     | John Henry         | Smith             | partial    |
| John       | Peter       | Smith     | John Henry         | Smith             | partial    |
| John       |             | Smith     | John Henry         | Smith             | partial    |

## Sandbox environment data

When simulating queries in the sandbox environment, the following records will return a match:

| Reference | First Name  | Last Name  | State | Date of Birth | Date of Death | Date of Death Range |
|:----------|:------------|:-----------|:------|:--------------|:--------------|:--------------------|
| 123400001 | John        | Smith      | VIC   | 1998-03-21    | 2023-07-24    |                     |
| 123400002 | John        | Doe        | NSW   | 1971-01-23    | 2003-08-22    |                     |
| 123400003 | John Andrew | Doe        | WA    | 1971-01-23    | 2011-11-03    |                     |
| 123400004 | Mary        | Smith      | NSW   | 1965-02-17    |               | Between 31/12/2018 and 2/2/2019 |

## Request body

The details of the record to search

| Field | Type | Description |
|-------|------|-------------|
| `requests` | array of objects | The list of requests to make. |
| `requests[].check_id` | string | The unique identifier for this request. This can be used match the request in the results. Example: `abcd123456789` |
| `requests[].first_name` | string | The first name of the individual Example: `John` |
| `requests[].middle_name` | string or null | The optional middle name of the individual Example: `Andrew` |
| `requests[].last_name` | string | The last name of the individual Example: `Smith` |
| `requests[].birth_date` | string (date) | The date of birth of the individual Example: `1998-03-21` |

**Sample request**

```json
{
    "requests": [
        {
            "check_id": "abcd123456789",
            "first_name": "John",
            "middle_name": "Andrew",
            "last_name": "Smith",
            "birth_date": "1998-03-21"
        }
    ]
}
```

## Responses

### 200 Successful response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok` |
| `api_reference` | string (uuid) | A unique identifier for this request. This can be used to track the request in the logs. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `results` | array of objects | A list of results for each of the requests made. |
| `results[].check_id` | string | The unique identifier for this request. This can be used match the request in the results. Example: `abcd123456789` |
| `results[].matches` | array of objects | Array of matched records. |
| `results[].matches[].first_name` | string | The first name (and middle name if applicable) of the matched individual. Example: `John Andrew` |
| `results[].matches[].last_name` | string | The last name of the matched individual. Example: `Smith` |
| `results[].matches[].date_of_birth` | string or null | The dob of the matched individual. Example: `1998-03-21` |
| `results[].matches[].date_of_death` | string or null | The date of death of the matched individual. Example: `2023-07-24` |
| `results[].matches[].date_of_death_range` | string or null | The date range of death of the matched individual. Example: `Between 31/12/2018 and 2/2/2019` |
| `results[].matches[].state` | string | The state of the matched individual. Enum: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` Example: `VIC` |
| `results[].matches[].reference` | string | The ADC reference number of the matched record. Example: `123400001` |
| `results[].matches[].name_match` | string | The type of match for the name. - exact: The name is an exact match. - partial: The name is a partial match (The last name is the same but the first / middle name differ). Enum: `exact`, `partial` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "results": [
        {
            "check_id": "abcd123456789",
            "matches": [
                {
                    "first_name": "John Andrew",
                    "last_name": "Smith",
                    "date_of_birth": "1998-03-21",
                    "date_of_death": "2023-07-24",
                    "date_of_death_range": "Between 31/12/2018 and 2/2/2019",
                    "state": "VIC",
                    "reference": "123400001",
                    "name_match": "exact"
                }
            ]
        }
    ]
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))