# ASIC Extract Company Search

`POST /asic_extract_company_search`

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

`asic_extract_company_search` locates the ASIC identifiers you must supply when ordering a company extract via
`/asic_extract`. The endpoint accepts any of the following search modes and automatically determines which one to use
based on the `search` value:

| Search mode | Input format | Typical use |
|-------------|--------------|-------------|
| ABN search  | 11 digits (spacing ignored) | When you already know the company's ABN |
| ACN search  | 9 digits (spacing ignored)  | When you have the ACN / NNI |
| Name search | Free‑form string matched against ASIC extract names | When you only know the legal company name |

## Behaviour

- Number searches return a single match (or an empty list) containing the ASIC record retrieved.
- Name searches can return multiple organisations. Use the optional `status` filter and `max_results` to keep the
  result set manageable. If the ASIC upstream indicates there are more results than returned, `more_results` is set to
  `true`.
- Copy either the `identifier.number` (usually an ACN) or the `abn` from a match when submitting a company extract
  request.

## Status filters

When running a name search you can restrict the response to companies in a particular ASIC registration status:

| status value   | Meaning                                           |
|----------------|---------------------------------------------------|
| `registered`   | Only active/registered companies                  |
| `deregistered` | Only deregistered companies                       |
| `all` (default)| Return both registered and deregistered companies |

Status filters are ignored for ABN / ACN lookups because those queries already return a single company.

## Location filters

When running a name search you can restrict the response to a postcode or state.
Results will only be included if they have a registered office address in the specified location.
Postcode searches will include neighbouring postcodes.

If both a postcode and state are provided, only the postcode is applied.

Location filters are ignored for ABN / ACN lookups because those queries already return a single company.

## Sandbox environment

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

| Company Name            | ABN          | ACN        | Registration Status  |
|:------------------------|:-------------|:-----------|:---------------------|
| Tech Innovators Ltd     | 32111111114  | 111111114  | Registered           |
| Green Energy Solutions  | 11123456780  | 123456780  | Deregistered         |
| Urban Development Corp  | 54222222228  | 222222228  | Registered           |
| Creative Media Agency   | 33234567894  | 234567894  | Registered           |

## Request body

Parameters describing the company search.

| Field | Type | Description |
|-------|------|-------------|
| `search` | string [max 100 characters] | **Required.** Company name, ABN, or ACN to look up. Letter casing is ignored for name searches; whitespace is ignored for number searches. Example: `ACME CORPORATION PTY LTD` |
| `max_results` | integer [1..90] or null | Maximum number of matches to return for name searches (1-90). Defaults to 20. Ignored for ABN/ACN lookups because those return at most one record. Example: `25` |
| `status` | string or null | Optional name-search filter that limits responses to registered, deregistered, or all companies. If not supplied the API searches all companies. Enum: `registered`, `deregistered`, `all` Example: `registered` |
| `postcode` | string [max 4 characters] or null | Optional name-search filter that limits responses to companies with a registered office in the specified postcode or neighbouring postcodes. Ignored for ABN/ACN lookups. |
| `state` | string or null | Optional name-search filter that limits responses to companies with a registered office in the specified state. Use the two/three-letter state code (e.g. `VIC`, `NSW`). Ignored for ABN/ACN lookups. |

**Sample request**

```json
{
    "search": "ACME CORPORATION PTY LTD",
    "max_results": 25,
    "status": "registered",
    "postcode": "string",
    "state": "string"
}
```

## Responses

### 200 Company search completed successfully.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Always `Ok` on success. Example: `Ok` |
| `function` | string | The API function that handled the request. Example: `asic_extract_company_search` |
| `api_reference` | string (uuid) | Audit reference for the request. Use `/asic_extract/{api_reference}` to retrieve audit logs. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `matches` | array of objects | A list of companies that match the search criteria. Each object contains the metadata you will need when calling `/asic_extract` (typically an ACN or ABN) plus additional ASIC attributes when available. |
| `matches[].identifier` | object | Primary ASIC identifier (usually an ACN) returned during name searches. |
| `matches[].identifier.numberHeading` | string | ASIC identifier type (`ACN`, `ABN`, etc.). Example: `ACN` |
| `matches[].identifier.number` | integer | Identifier value for the company. Example: `123456780` |
| `matches[].name` | object | Structured ASIC name block. |
| `matches[].name.name` | string | Uppercase legal name of the organisation. Example: `ACME CORPORATION PTY LTD` |
| `more_results` | boolean | Indicates that ASIC reported more matches than were returned (for example when `max_results` was reached). Refine your search and try again if this is `true`. Example: `false` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "asic_extract_company_search",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "matches": [
        {
            "identifier": {
                "numberHeading": "ACN",
                "number": 123456780
            },
            "name": {
                "name": "ACME CORPORATION PTY LTD"
            },
            "status": {
                "code": "REGD,",
                "description": "Registered",
                "isRegistered": true,
                "effectiveFrom": "2020-01-15"
            }
        },
        {
            "identifier": {
                "numberHeading": "ACN",
                "number": 987654321
            },
            "name": {
                "name": "ACME CORPORATION PTY LTD"
            },
            "status": {
                "code": "DRGD,",
                "description": "Deregistered,",
                "isRegistered": false
            }
        }
    ],
    "more_results": false
}
```

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