# Banned and Disqualified Person Search

`POST /banned_disqualified_persons`

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

Banned and Disqualified Person Search searches multiple public authorities for persons who have been banned or disqualified from performing a role.

The sources used in this search include:
- ASIC Banned Persons Register
- ATO Disqualified SMSF Trustees (as published by the ATO)

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

## Search Types

The search types affect how the names are matched. One of these three search types must be provided.

| Search Type | Description |
| ----------- | ----------- |
| 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. |

## Similarity Threshold

The `similarity_threshold` parameter controls how closely a returned name must match the search input to be included in the results. For each record, the API calculates a similarity score by comparing the search values (first, middle, and last names) against the result's names by measuring their likeness. This likeness is calculated by comparing the characters in the search name and the result name, measuring how much of the text overlaps, and expressing that as a percentage similarity.

These individual scores are averaged into an overall similarity percentage, which is stored with each result. The `similarity_threshold` then acts as a filter to only results with an average similarity equal to or greater than the threshold are returned. The returned result includes the overall similarity percentage in the `name_similarity` property.

## Banned Types

The `banned_types` parameter controls which types of banned person to search for. **If omitted, the API will search for all types.**

The available types are:

| Banned Type | Description |
| ----------- | ----------- |
| afs_banned_disqualified | A financial service provider banned or disqualified under section 922A(2) of Corporations Act 2001 |
| banned_futures | Banned futures representatives register (pre-AFS licences) |
| banned_securities | Banned securities representatives register (pre-AFS licences) |
| credit_banned_disqualified | Persons against whom a banning order or disqualification order is made under Part 2-4 of the NCCP Act |
| disqualified_director | The company directors and other office holders disqualified under 1274AA of Corporations Act 2001 |
| disqualified_smsf | Disqualified SMSF auditors for whom an order disqualifying the person from being an approved SMSF auditor is in force under 130F of the SIS Act |
| ato_disqualified_trustee | Persons disqualified from acting as a trustee of an SMSF |

## 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. The same names are seeded into both registers, so an unfiltered search for one of them will typically return a record from each.

**ASIC banned persons register**

| 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   |

**ATO disqualified trustees register** (returned as `banned_type: ato_disqualified_trustee`)

| First name | Middle name  | Last name | Suburb     | State | Disqualified |
|:-----------|:-------------|:----------|:-----------|:------|:-------------|
| John       | Michael      | Smith     | Shepparton | VIC   | 2021-02-01   |
| John       | Robert       | Smith     | Sydney     | NSW   | 2021-03-01   |
| Jane       | Penny Sally  | Roberts   | Camberwell | VIC   | 2021-04-01   |
| Jane       | -            | Roberts   | Camberwell | VIC   | 2021-05-01   |
| J          | S            | Roberts   | Melbourne  | VIC   | 2021-06-01   |
| P          | -            | Zao       | Woolongong | NSW   | 2021-07-01   |
| Simone     | N            | Zao       | -          | -     | 2021-08-01   |
| Adam       | Darren       | Halliday  | Illawong   | NSW   | 2021-09-01   |

## 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`, `disqualified_smsf`, `ato_disqualified_trustee` |
| `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: `banned_disqualified_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 | Document or reference 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 2 letter ISO 3166-2 country code Example: `AU` |
| `results[].matches[].comments` | string or null | Additional information associated with the banned or disqualified person. Example: `This is a comment` |
| `results[].matches[].source_url` | string or null | The URL of the document containing the ban or disqualification notice/order (if available). Example: `https://www.example.com/media/61424.pdf` |
| `results[].matches[].name_similarity` | number | The similarity percentage of the name of the individual to the search name. Example: `100` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "banned_disqualified_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": "AU",
                    "comments": "This is a comment",
                    "source_url": "https://www.example.com/media/61424.pdf",
                    "name_similarity": 100
                }
            ]
        }
    ]
}
```

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