# ASIC Extract Person Search

`POST /asic_extract_person_search`

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

Runs an ASIC person search to locate individual ASIC person IDs that can be used when requesting a full ASIC extract.
Provide the subject's legal name, date of birth, and whether you want **current** or **historical** data. The API
returns a list of matching ASIC identities (`matches`) including the `person_id` and `search_id` you must supply to
`/asic_extract` when ordering the actual extract.

Each result can also include an `additional` array. These entries represent linked ASIC person IDs that have either
the same name or the same name and birth date (for example, with shareholdings). When requesting a person extract you
should copy the `person_id` values from `additional` into the `additional_person_ids` field so the resulting extract
contains every related person.

## Input expectations

- Names must be provided exactly as they appear on ASIC records. A combined maximum of three given names is allowed
  across `first_name` and `middle_name`.
- `birth_date` must be an ISO `YYYY-MM-DD` date after 1900-01-01.
- `extract_type` selects the extract type that the search results will be used for. This must be provided before
   ordering an extract as it will affect the search id result returned. Choose one of the following:
  - `current` – returns people with current roles/shareholdings.
  - `historical` – includes ceased roles/shareholdings.

## Sandbox environment

The sandbox dataset is deterministic. Use one of the following combinations to receive sample matches:

| First Name | Middle Name | Last Name   | Birth Date  | Extract Type | Notes                                               |
|:-----------|:------------|:------------|:------------|:-------------|:----------------------------------------------------|
| John       | Michael     | Doe         | 1980-05-15  | historical   | Standard three-part name with linked extract.       |
| Jane       | Alice       | Smith       | 1987-03-22  | current      | Standard three-part name with linked extract.       |
| Lucas      | Benjamin    | Carter      | 1992-08-09  | current      | Standard three-part name with linked extract.       |
| Maria      |             | Scott       | 1971-11-02  | historical   | No middle name on the ASIC record.                  |
| Patrick    |             | O'Connor    | 1965-07-19  | historical   | Apostrophe in the surname (also matches `OConnor`). |
| Mary-Jane  |             | Parker      | 1983-02-28  | historical   | Hyphenated first name.                              |

## Request body

Details of the individual to search for.

| Field | Type | Description |
|-------|------|-------------|
| `first_name` | string [max 100 characters] | **Required.** The person's first given name (one to three given names when combined with `middle_name`). Example: `John` |
| `middle_name` | string [max 100 characters] or null | Optional middle names. Combined with `first_name` this cannot exceed three words. Example: `Michael` |
| `last_name` | string [max 100 characters] | **Required.** The person's family name as recorded with ASIC. Example: `Doe` |
| `birth_date` | string (date) | **Required.** The person's date of birth in `YYYY-MM-DD` format (must be after 1900-01-01). Example: `1980-05-15` |
| `extract_type` | string | **Required.** Indicates whether to search current or historical ASIC data. Historical searches include ceased roles and can take longer to return. Enum: `current`, `historical` Example: `historical` |

**Sample request**

```json
{
    "first_name": "John",
    "middle_name": "Michael",
    "last_name": "Doe",
    "birth_date": "1980-05-15",
    "extract_type": "historical"
}
```

## Responses

### 200 Search completed successfully.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Always `Ok` when the request succeeds. Example: `Ok` |
| `function` | string | The API function that handled the request. Example: `asic_extract_person_search` |
| `api_reference` | string (uuid) | Audit reference you can use with `/asic_extract/{api_reference}` to retrieve logs. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `matches` | array of objects | A list of ASIC identities that match the supplied name and birth date. |
| `matches[].person_id` | string | ASIC person identifier to pass as `person_id` when ordering an extract. Example: `123456780` |
| `matches[].search_id` | string | ASIC search reference identifier to pass as `search_id` when ordering an extract. Example: `11223344` |
| `matches[].name` | string | The full formatted name returned by ASIC (usually uppercase). Example: `JOHN MICHAEL DOE` |
| `matches[].birth_date` | string (date) | Date of birth for the matched person. Some upstream providers may label this field `dob`. Example: `1980-05-15` |
| `matches[].state` | string | State or territory associated with the person's ASIC address. Example: `NSW` |
| `matches[].suburb` | string | Suburb associated with the person's ASIC address. Example: `Sydney` |
| `matches[].additional` | array of objects | Additional ASIC person identifiers linked to this match (for example joint shareholdings). Supply each `person_id` in `additional_person_ids` when calling `/asic_extract`. |
| `matches[].additional[].person_id` | string | Linked ASIC person identifier. Example: `123456781` |
| `matches[].additional[].name` | string | Full name of the linked individual (if provided). Example: `JOHN MICHAEL DOE` |
| `matches[].additional[].state` | string or null | State or territory associated with the linked record. |
| `matches[].additional[].suburb` | string or null | Suburb associated with the linked record. |
| `matches[].additional[].birth_date` | string (date) or null | Date of birth for the linked individual. |
| `matches[].additional[].additional` | array of objects | Nested linked identities (rare). Typically empty. |

**Sample response**

```json
{
    "message": "Ok",
    "function": "asic_extract_person_search",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "matches": [
        {
            "person_id": "123456780",
            "search_id": "11223344",
            "name": "JOHN MICHAEL DOE",
            "birth_date": "1980-05-15",
            "state": "NSW",
            "suburb": "Sydney",
            "additional": [
                {
                    "person_id": "123456781",
                    "name": "JOHN MICHAEL DOE",
                    "state": "string",
                    "suburb": "string",
                    "birth_date": "2024-01-01",
                    "additional": []
                }
            ]
        }
    ]
}
```

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