# Deceased Check

`POST /deceased_check`

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

The Deceased Check API allows you to check if an individual is recorded as deceased against the
Global Data death check service.

## Deceased Check

The check is performed based on the name and date of birth / date of death of the individual.
If the individual is found in the deceased records, then the deceased indicator will be set to 'Y'.

## Search modes

Note that the search treats the first name field differently depending on whether a date of birth or date of death is provided.

**Date of birth based search**

When providing a name and date of birth only, the check will be performed based on the name and date of birth. In this mode
the name search for first name allows the the omission of the middle name(s). So a search for "John Smith" will match
"John Andrew Smith" and "John Smith" but not "Andrew Smith".

When providing a first and middle name (provided together in the first_name field), the search will be performed based on the
first and middle name. So a search for "John Andrew Smith" will match "John Andrew Smith" but not "John Smith" or "John Peter Smith".

**Date of death based search**

When providing a name and date of death only, the check will be performed based on the name and date of death. In this mode
the name search for first name must be an exact match. So a search for "John Smith" will match "John Smith" but not
"John Andrew Smith".

**Date of birth and date of death based search**

When providing a name, date of birth and date of death, the check will be performed based on the name and date of birth. Once
results are returned, the date of death will be checked against the returned results. This search mode operates identically to
the date of birth based search and allows for the omission of the middle name(s).

## Sandbox environment data

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

| First Name  | Last Name  | Date of Birth | Date of Death |
|:------------|:-----------|:--------------|:--------------|
| John        | Smith      | 1998-03-21    | 2023-07-24    |
| John        | Doe        | 1971-01-23    | 2003-08-22    |
| John Andrew | Doe        | 1971-01-23    | 2011-11-03    |

These samples can be queried with or without the date of death.

## Request body

The details of the record to search

| Field | Type | Description |
|-------|------|-------------|
| `first_name` | string | The first and optional middle name of the individual Example: `John Andrew` |
| `last_name` | string | The last name of the individual Example: `Doe` |
| `birth_date` | string (date) | The date of birth of the individual Example: `1998-03-21` |
| `death_date` | string (date) or null | The date of death of the individual (optional) Example: `2011-11-03` |

**Sample request**

```json
{
    "first_name": "John Andrew",
    "last_name": "Doe",
    "birth_date": "1998-03-21",
    "death_date": "2011-11-03"
}
```

## Responses

### 200 Result of the check

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` |
| `deceased_indicator` | string | The deceased indicator. This will be 'Y' if the individual is found in the deceased records, otherwise it will be 'N'. Enum: `Y`, `N` Example: `N` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "deceased_indicator": "N"
}
```

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