# Retrieve ASIC Extract

`GET /asic_extract/{api_reference}`

- Live: `GET https://gdapi.globaldata.net.au/api/v2/asic_extract/{api_reference}`
- Sandbox: `GET https://sandbox-gdapi.globaldata.net.au/api/v2/asic_extract/{api_reference}`

Polls the status of an ASIC extract that was previously queued via `POST /asic_extract`. Provide the
`api_reference` returned from the original request to determine whether the extract is ready, download the JSON
payload, or stream a PDF copy. This retrieval call is not billable and can be repeated until the extract is ready.

- While the extract is still compiling the API responds with HTTP `202`. Keep polling with an exponential backoff.
- Once ready, the endpoint returns HTTP `200` with the full JSON extract. The JSON payload includes the exact ASIC
  structure from the upstream dataset (for both company and person extracts) plus the `asic_extract_show`
  `api_reference` for auditing.
- Append `?pdf=true` to stream a formatted PDF copy of the same extract. When `pdf=true`, the response body is a PDF
  (`application/pdf`) instead of JSON.
- The service polls upstream data for up to 30 seconds; if no extract is available at that point you will receive a
  `202` response. Continue polling with the same `api_reference`.
- An extract can only be retrieved for 24 hours after the original `POST /asic_extract` request. Once that window
  has passed the endpoint responds with HTTP `410` and you need to submit a new extract request.

## Sandbox usage

Use the sandbox company/person identifiers listed under `POST /asic_extract` to create a request, then poll this
endpoint with the returned `api_reference`. Two fixtures are configured to **always** return a `202` on the first poll
to help you test retry logic:

- Company: Creative Media Agency (`ABN 33234567894`, `ACN 234567894`)
- Person: Lucas Benjamin Carter (`person_id 998877660`, `search_id 77889900`)

Other sandbox extracts typically complete within a few seconds but still require polling – you may see a `202`
response before the sample payload is ready.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `api_reference` | path | string (uuid) | **Required.** The audit reference returned when the extract was queued via `POST /asic_extract`. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `pdf` | query | boolean | When set to `true`, returns the extract as a PDF document instead of JSON. Omit (or send `false`) to receive the JSON payload. Default: `false` |

## Responses

### 200 Extract is ready. Returns JSON by default or a PDF when `pdf=true`.

Content type: `application/json`, `application/pdf`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Always `Ok` when the extract payload is returned. Example: `Ok` |
| `function` | string | Name of the API function that handled the request. Example: `asic_extract_show` |
| `api_reference` | string (uuid) | Audit reference for **this** retrieval call (not the original queue reference). Example: `7cbb094c-0f27-42f4-9f36-9cf0b2f6d5ff` |
| `extract` | object (dynamic) | Full ASIC extract payload. The structure mirrors the original request type: - Company extracts contain `entity_type: company`, `entity` metadata, `asic_extracts`, `directors`, `shareholders`, etc. - Person extracts contain `entity_type: person`, an `entity` block with the subject details, and related roles/shareholdings. |

**Sample response**

```json
{
    "message": "Ok",
    "function": "asic_extract_show",
    "api_reference": "7cbb094c-0f27-42f4-9f36-9cf0b2f6d5ff",
    "extract": {
        "id": "ee4c241c-93d3-4439-9a00-3fb551759168",
        "entity_type": "company",
        "entity": {
            "abn": "32111111114",
            "acn": "111111114",
            "name": "TECH INNOVATORS LTD",
            "abr_status": "Active"
        },
        "asic_extracts": [
            {
                "id": "ee4c241c-0001-4439-9a00-3fb551759168",
                "type": "Current",
                "directors": [
                    {
                        "name": "JANE DOE",
                        "type": "Director"
                    }
                ],
                "addresses": [
                    {
                        "type": "Registered Office",
                        "address": "100 SAMPLE STREET SYDNEY 2000 NSW"
                    }
                ]
            }
        ]
    }
}
```

Also available as a PDF (application/pdf)

### 202 Extract is still being prepared (returned when no data is available after the 30‑second polling window).

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Status message indicating the extract is not ready yet. Example: `Extract is still being processed. Please try again later.` |

**Sample response**

```json
{
    "message": "Extract is still being processed. Please try again later."
}
```

### 404 No extract was found for the provided `api_reference`, or it belongs to another account/environment.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Error message describing that the record could not be located. Example: `Not Found.` |

**Sample response**

```json
{
    "message": "Not Found."
}
```

### 410 The extract can no longer be retrieved. Extracts are only available for retrieval for 24 hours after the original `POST /asic_extract` request. Submit a new extract request to obtain a current extract.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Error message describing that the extract has expired. Example: `This extract has expired. Please request a new one` |

**Sample response**

```json
{
    "message": "This extract has expired. Please request a new one"
}
```

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