# ASIC Banned Persons Search

`POST /asic_banned_persons`

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

ASIC Banned Persons Search searches the ASIC register of banned persons.

This endpoint allows multiple requests to be simultaneously made in a single query.

## Narrow Search
A narrow search will match exact first name, exact last name. The middle name is matched based on the similarity_threshold.
This is the most restrictive search and should be used for low risk searches.

## Medium Search
A medium search will match exact last name, and will allow for a partial match on other names based on the similarity_threshold.
This is a good balance between accuracy and flexibility.

## Broad Search
A broad search will match partial first name, partial middle name, and partial last name.
This is the most flexible search and should be used for high risk searches.

## Sandbox environment data

When simulating queries in the sandbox environment, the following records will return a match. Any other name returns an empty `matches` array.

| First name | Middle name  | Last name | Banned type                  | Suburb     | State |
|:-----------|:-------------|:----------|:-----------------------------|:-----------|:------|
| John       | Michael      | Smith     | afs_banned_disqualified      | Shepparton | VIC   |
| John       | Robert       | Smith     | banned_futures               | Sydney     | NSW   |
| Jane       | Penny Sally  | Roberts   | banned_securities            | Camberwell | VIC   |
| Jane       | -            | Roberts   | banned_securities            | Camberwell | VIC   |
| J          | S            | Roberts   | credit_banned_disqualified   | Melbourne  | VIC   |
| P          | -            | Zao       | disqualified_director        | Woolongong | NSW   |
| Simone     | N            | Zao       | disqualified_smsf            | -          | -     |
| Adam       | Darren       | Halliday  | disqualified_director        | Illawong   | NSW   |

## Request body

The details of the individuals to search for.

| Field | Type | Description |
|-------|------|-------------|
| `search_type` | string | The type of search to perform. Narrow searches for exact matches, medium searches for similar matches and broad searches for partial matches. Enum: `narrow_search`, `medium_search`, `broad_search` Example: `medium_search` |
| `banned_types` | array of strings | The type of banned person to search for. Leave empty to search for all types. Enum: `afs_banned_disqualified`, `banned_futures`, `banned_securities`, `credit_banned_disqualified`, `disqualified_director` |
| `similarity_threshold` | number [0..100] | The minimum similarity percentage to return results for. Default: `80` Example: `80` |
| `requests` | array of objects | The list of requests to make. |
| `requests[].check_id` | string | The unique identifier for this request. This can be used match the request in the results. Example: `abcd123456789` |
| `requests[].first_name` | string [1..50 characters] | The first name of the individual Example: `Phil` |
| `requests[].middle_name` | string [1..50 characters] or null | The middle name of the individual |
| `requests[].last_name` | string [1..50 characters] | The last name of the individual Example: `Smith` |

**Sample request**

```json
{
    "search_type": "medium_search",
    "banned_types": [
        "afs_banned_disqualified"
    ],
    "similarity_threshold": 80,
    "requests": [
        {
            "check_id": "abcd123456789",
            "first_name": "Phil",
            "middle_name": null,
            "last_name": "Smith"
        }
    ]
}
```

## Responses

### 200 Successful response

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` |
| `function` | string | The function that was called. Example: `asic_banned_persons` |
| `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` |
| `results` | array of objects | A list of results for each of the requests made. |
| `results[].check_id` | string | The unique identifier for this request. This can be used match the request in the results. Example: `abcd123456789` |
| `results[].matches` | array of objects | Array of matched individuals. |
| `results[].matches[].first_name` | string | The first name of the individual. Example: `Phil` |
| `results[].matches[].middle_name` | string or null | The middle name of the individual. Example: `Michael` |
| `results[].matches[].last_name` | string | The last name of the individual. Example: `Smith` |
| `results[].matches[].banned_type` | string | The type of banned person the individual is. Example: `afs_banned_disqualified` |
| `results[].matches[].document_number` | string | ASIC's internal document number used to identify the document containing the ban or disqualification notice/order. Example: `1234567890` |
| `results[].matches[].start_date` | string | The start date of the ban or disqualification. Example: `2021-01-01` |
| `results[].matches[].end_date` | string or null | The end date of the ban or disqualification. Example: `2021-01-01` |
| `results[].matches[].address_suburb` | string or null | The suburb of the individual. Example: `Sydney` |
| `results[].matches[].address_state` | string or null | The state of the individual. Example: `NSW` |
| `results[].matches[].address_postcode` | string or null | The postcode of the individual. Example: `2000` |
| `results[].matches[].address_country` | string or null | The country of the individual. Example: `Australia` |
| `results[].matches[].comments` | string or null | Additional information associated with the banned or disqualified person. Example: `This is a comment` |
| `results[].matches[].name_similarity` | number | The similarity of the name of the individual to the search name. Example: `100` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "asic_banned_persons",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "results": [
        {
            "check_id": "abcd123456789",
            "matches": [
                {
                    "first_name": "Phil",
                    "middle_name": "Michael",
                    "last_name": "Smith",
                    "banned_type": "afs_banned_disqualified",
                    "document_number": "1234567890",
                    "start_date": "2021-01-01",
                    "end_date": "2021-01-01",
                    "address_suburb": "Sydney",
                    "address_state": "NSW",
                    "address_postcode": "2000",
                    "address_country": "Australia",
                    "comments": "This is a comment",
                    "name_similarity": 100
                }
            ]
        }
    ]
}
```

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