# Person History `POST /person_history` - Live: `POST https://gdapi.globaldata.net.au/api/v2/person_history` - Sandbox: `POST https://sandbox-gdapi.globaldata.net.au/api/v2/person_history` The Person History API allows you to query and retrieve additional historical data for a specific individual. By providing certain identifying information, you can obtain a comprehensive set of records that match the given criteria. ## ADC Check The returned records are checked against the ADC (Australian Death Check) service and the result is returned in the 'deceased' field of the match response. A 'Y' indicates that the individual is recorded as deceased, while an 'N' indicates that the individual is not recorded as deceased. The ADC lookup is based on the matched individual's name, date of birth and state. The ADC check is performed when the following fields are available: - first_name - last_name - birth_date - state ## Minimum search requirements In order to perform a valid lookup, a minimum of the following fields are required: - first_name and last_name, and at least one of: - birth_date - phone - email If less than the minimum requirements are supplied, the API will return a 400 error with the message "One of email or phone or dob is required." ## Sandbox environment data When simulating queries in the sandbox environment, the following records will return a match: | First Name | Last Name | Birth Date | Email | Telephone | Address | |:-----------|:----------|:-----------|:-------------------------|:-----------------------|:-------------------------------------| | John | Smith | 1998-03-21 | jsmith1998@example.com | 0399999999, 0491222111 | 20 HARDY ST, LILYDALE 3140 VIC | | John | Smith | | | 0491222111 | 8 WALTHAM ST, RICHMOND 3121 VIC | | Mary | Jones | 1989-08-12 | mary_jones89@example.com | 0399995000 | 35 YARALLA ST, CONCORD WEST 2138 NSW | ## Request body The details of the record to search | Field | Type | Description | |-------|------|-------------| | `first_name` | string | The first name of the individual Example: `John` | | `last_name` | string | The last name of the individual Example: `Smith` | | `birth_date` | string (date) | The date of birth of the individual Example: `1998-03-21` | | `phone` | string | The phone number in 0NSN format Example: `0491222111` | | `email` | string | The email address Example: `jsmith1998@example.com` | **Sample request** ```json { "first_name": "John", "last_name": "Smith", "birth_date": "1998-03-21", "phone": "0491222111", "email": "jsmith1998@example.com" } ``` ## 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` | | `matches` | array of objects | Array of matched individuals. | | `matches[].first_name` | string | The first name of the matched individual. Example: `John` | | `matches[].middle_name` | string | The middle name of the matched individual. Example: `Andrew` | | `matches[].last_name` | string | The last name of the matched individual. Example: `Smith` | | `matches[].birth_date` | string or null | The dob of the matched individual. Example: `1998-03-21` | | `matches[].deceased` | string | The result of the ADC check for the matched individual. - Y: The person is recorded as deceased - N: The person is not recorded as deceased Enum: `Y`, `N` Example: `N` | | `matches[].address` | string | The address of the matched individual. Example: `20 HARDY ST` | | `matches[].suburb` | string | The suburb of the matched individual. Example: `LILYDALE` | | `matches[].state` | string | The state of the matched individual. Enum: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` Example: `VIC` | | `matches[].postcode` | string | The postcode of the matched individual. Example: `3140` | | `matches[].date_start` | string (date) | The date the address record was first seen. Example: `2010-01-01` | | `matches[].date_end` | string (date) | The date the address record was last seen. Example: `2022-03-15` | | `matches[].phones` | array of objects | Array of phone numbers associated with the matched individual. | | `matches[].phones[].phone` | string | The phone number in 0NSN format. Example: `0491222111` | | `matches[].phones[].date_start` | string (date) | The date the phone record was first seen. Example: `2010-01-01` | | `matches[].phones[].date_end` | string (date) | The date the phone record was last seen. Example: `2022-03-15` | | `matches[].emails` | array of objects | Array of email addresses associated with the matched individual. | | `matches[].emails[].email` | string | The email address. Example: `jsmith1998@example.com` | | `matches[].emails[].date_start` | string (date) | The date the email record was first seen. Example: `2010-01-01` | | `matches[].emails[].date_end` | string (date) | The date the email record was last seen. Example: `2022-03-15` | **Sample response** ```json { "message": "Ok", "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95", "matches": [ { "first_name": "John", "middle_name": "Andrew", "last_name": "Smith", "birth_date": "1998-03-21", "deceased": "N", "address": "20 HARDY ST", "suburb": "LILYDALE", "state": "VIC", "postcode": "3140", "date_start": "2010-01-01", "date_end": "2022-03-15", "phones": [ { "phone": "0491222111", "date_start": "2010-01-01", "date_end": "2022-03-15" } ], "emails": [ { "email": "jsmith1998@example.com", "date_start": "2010-01-01", "date_end": "2022-03-15" } ] } ] } ``` Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))