# Launch screening checks against an entity

`POST /entities/{entity_uuid}/checks`

- Base: `POST https://portal.watcheye.com.au/api/v1/entities/{entity_uuid}/checks`

Queues one or more screening checks against a saved entity and returns
`202 Accepted` with the parent (or single child) check UUID. The screening
runs in the background - poll `GET /v1/checks/{uuid}` and wait for `status`
to be `complete` or `failed` before reading the results.

Each requested check type is charged at launch time. If the upstream provider
returns an error, the check is marked as `failed` and the credit for that
individual check is refunded.

When a single check type is requested, the response describes that check.
When two or more types are requested, a parent group check is created and
returned, with one child per requested type.

## Pre-flight checks

The endpoint validates the request before any check rows are created or any
credit is charged:

* `404` - the entity was not found on the calling account
* `400` - the request body failed validation (missing or unknown check type)
* `403 Forbidden` - the calling account is not entitled to one or more of
  the requested check types (the product is not enabled for the account)
* `402 Payment Required` - the calling account has insufficient credit to
  cover the total projected cost across all requested check types

## Idempotency

This endpoint accepts the `Idempotency-Key` header so that retries on network
failure are safe. See the [Idempotency](/docs/guides/watcheye_api/idempotency)
section of the API guide for the full contract.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `entity_uuid` | path | string (uuid) | **Required.** The entity UUID |
| `Idempotency-Key` | header | string [max 255 characters] | Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the `Idempotent-Replay: true` response header. Honoured on `POST` requests only. See the [Idempotency](/docs/guides/watcheye_api/idempotency) section of the API guide for the full contract. Example: `8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f` |

## Request body

The launch parameters

| Field | Type | Description |
|-------|------|-------------|
| `check_types` | array of strings [min 1 items] | **Required.** One or more operation names to launch. See the operation enum in the Check schema for the supported set. |
| `config` | object | Per-operation configuration map keyed by operation name. Each listed operation has defaults that apply when its key is omitted, so you only need to send a block when you want to override a default. The five operations not listed below (`adverse_media`, `phone_check`, `email_check`, `adc_check`, `adc_custodian_check`) take no configuration. |
| `config.pep_sanction_check` | object | Per-operation configuration for a `pep_sanction_check` launch. Every property is optional - any key you omit is filled with its default value before the check runs, and the resolved values are echoed back on the launch response so you can confirm what the check is using. |
| `config.pep_sanction_check.search_type` | string | Match strictness. `narrow_search` requires close name matches and returns the fewest false positives; `broad_search` returns more candidates for review; `medium_search` is the balanced default. Defaults to `medium_search`. Enum: `broad_search`, `medium_search`, `narrow_search` Example: `medium_search` |
| `config.pep_sanction_check.similarity_threshold` | string | Minimum name similarity percentage (10..100). Match candidates below this score are dropped. Sent as a string. Defaults to `"80"`. Enum: `10`, `20`, `30`, `40`, `50`, `60`, `70`, `80`, `90`, `100` Example: `80` |
| `config.pep_sanction_check.pep_countries` | array of strings | Two-letter ISO 3166-1 alpha-2 country codes (either case is accepted; returned in uppercase) to scope the PEP search. An empty array searches all PEP jurisdictions (the default). |
| `config.pep_sanction_check.sanction_countries` | array of strings | Two-letter ISO 3166-1 alpha-2 country codes (either case is accepted; returned in uppercase) to scope the sanction search. Defaults to `["AU", "CA", "NZ", "GB", "US"]`. |
| `config.pep_sanction_check.max_results` | integer | Maximum number of match candidates to return. Sent as an integer. Defaults to `25`. Enum: `10`, `15`, `20`, `25`, `50`, `100` Example: `25` |
| `config.pep_sanction_check.pep_sanction_extended_result` | boolean | When `true`, includes the extended biographical and source-list detail on each match. Defaults to `true`. Example: `true` |
| `config.banned_disqualified_persons` | object | Per-operation configuration for a `banned_disqualified_persons` launch. Every property is optional - any key you omit is filled with its default value before the check runs. |
| `config.banned_disqualified_persons.search_type` | string | Match strictness. `narrow_search` requires close name matches and returns the fewest false positives; `broad_search` returns more candidates for review; `medium_search` is the balanced default. Defaults to `medium_search`. Enum: `broad_search`, `medium_search`, `narrow_search` Example: `medium_search` |
| `config.banned_disqualified_persons.similarity_threshold` | string | Minimum name similarity percentage (10..100), sent as a string. Defaults to `"80"`. Enum: `10`, `20`, `30`, `40`, `50`, `60`, `70`, `80`, `90`, `100` Example: `80` |
| `config.banned_disqualified_persons.banned_types` | array of strings | Restrict the search to one or more specific banned/disqualified registers. An empty array (the default) searches every register. Enum: `afs_banned_disqualified`, `banned_futures`, `banned_securities`, `credit_banned_disqualified`, `disqualified_director`, `disqualified_smsf`, `ato_disqualified_trustee` |
| `config.court_check` | object | Per-operation configuration for a `court_check` launch. Every property is optional - any key you omit is filled with its default value before the check runs. |
| `config.court_check.listing` | string | Which court listings to search. `criminal` is the default; `civil` searches civil matters only; `all` searches both. Enum: `all`, `civil`, `criminal` Example: `criminal` |
| `config.court_check.search_party` | string | Whether the subject should be matched as the `defendant`, `plaintiff`, or `any` party to the case. Defaults to `defendant`. Enum: `any`, `plaintiff`, `defendant` Example: `defendant` |
| `config.business_check` | object | Per-operation configuration for a `business_check` launch. Every property is optional - any key you omit is filled with its default value before the check runs. Each property selects whether the corresponding business-record signal raises an alert (`yes`), is recorded for audit but does not raise an alert (`on_change`), or is skipped entirely (`no`); the recent-window properties select a months-back window instead. |
| `config.business_check.name_match` | string | How strictly the trading name on the entity must match the registered ASIC name. Defaults to `similar`. Enum: `exact`, `similar`, `no` Example: `similar` |
| `config.business_check.abn_active` | string | Alert when the ABN is not active. Defaults to `yes`. Enum: `yes`, `on_change`, `no` Example: `yes` |
| `config.business_check.acn_active` | string | Alert when the ACN is not active. Defaults to `yes`. Enum: `yes`, `on_change`, `no` Example: `yes` |
| `config.business_check.gst_registered` | string | Alert when GST registration changes. Defaults to `yes`. Enum: `yes`, `on_change`, `no` Example: `yes` |
| `config.business_check.recent_documents` | string | Alert when ASIC documents have been lodged within the last N months. `no` disables the check; `1`..`12` set the months-back window. Defaults to `"3"`. Enum: `no`, `1`, `2`, `3`, `6`, `12` Example: `3` |
| `config.business_check.recent_business_names` | string | Alert when registered business names have changed within the last N months. `no` disables the check; `1`..`12` set the months-back window. Defaults to `"3"`. Enum: `no`, `1`, `2`, `3`, `6`, `12` Example: `3` |
| `config.uk_business_check` | object | Per-operation configuration for a `uk_business_check` launch. Every property is optional - any key you omit is filled with its default value before the check runs. |
| `config.uk_business_check.name_match` | string | How strictly the trading name must match the Companies House record. Defaults to `similar`. Enum: `exact`, `similar`, `no` Example: `similar` |
| `config.uk_business_check.company_status` | string | Alert when the company status is not `active`. Defaults to `yes`. Enum: `yes`, `on_change`, `no` Example: `yes` |
| `config.uk_business_check.recent_filings` | string | Alert when filings have been lodged within the last N months. Defaults to `"3"`. Enum: `no`, `1`, `2`, `3`, `6`, `12` Example: `3` |
| `config.uk_business_check.officer_changes` | string | Alert when officers have changed within the last N months. Defaults to `"3"`. Enum: `no`, `1`, `2`, `3`, `6`, `12` Example: `3` |
| `config.uk_business_check.registered_address_change` | string | Whether to record registered address changes. Defaults to `on_change`. Enum: `on_change`, `no` Example: `on_change` |
| `config.uk_business_check.sic_codes_change` | string | Whether to record SIC code changes. Defaults to `on_change`. Enum: `on_change`, `no` Example: `on_change` |
| `config.realestate_check` | object | Per-operation configuration for a `realestate_check` launch. Every property is optional. |
| `config.realestate_check.date_from` | string (date) or null | ISO 8601 date (`YYYY-MM-DD`). When set, only listings on or after this date are considered. Omit to search all available history. Example: `2024-01-01` |

**Sample request**

```json
{
    "check_types": [
        "pep_sanction_check"
    ],
    "config": {
        "pep_sanction_check": {
            "search_type": "medium_search",
            "similarity_threshold": "80",
            "pep_countries": [],
            "sanction_countries": [
                "AU",
                "CA",
                "NZ",
                "GB",
                "US"
            ],
            "max_results": 25,
            "pep_sanction_extended_result": true
        },
        "banned_disqualified_persons": {
            "search_type": "medium_search",
            "similarity_threshold": "80",
            "banned_types": []
        },
        "court_check": {
            "listing": "criminal",
            "search_party": "defendant"
        },
        "business_check": {
            "name_match": "similar",
            "abn_active": "yes",
            "acn_active": "yes",
            "gst_registered": "yes",
            "recent_documents": "3",
            "recent_business_names": "3"
        },
        "uk_business_check": {
            "name_match": "similar",
            "company_status": "yes",
            "recent_filings": "3",
            "officer_changes": "3",
            "registered_address_change": "on_change",
            "sic_codes_change": "on_change"
        },
        "realestate_check": {
            "date_from": "2024-01-01"
        }
    }
}
```

## Responses

### 202 Check accepted - the parent (or single child) check has been queued for processing. Poll `GET /v1/checks/{uuid}` until `status` is `complete` or `failed`. The response shape depends on whether one check type or multiple were launched: * Single-check launch - the response describes that one check directly, with the resolved `config` block (defaults merged with user overrides) included so you can confirm exactly what the check is running with. `config` is `null` for operations that take no configuration. * Multi-check launch - the response describes the parent group check, with a `children[]` array carrying one entry per launched operation. Each child entry includes its own `uuid`, `status`, resolved `config`, and `detail_url` so you can start polling each child without first fetching the parent.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | object |  |
| `data.uuid` | string (uuid) |  |
| `data.check_number` | string |  |
| `data.check_type` | string | The operation name when a single type was launched, or `group` when multiple types were launched and a parent check was created. |
| `data.status` | string | Enum: `pending`, `processing`, `complete`, `failed` Example: `pending` |
| `data.config` | object (dynamic) or null | The resolved configuration for the launched check (defaults merged with any user-supplied values). Present on single-check launches; `null` for operations that take no configuration. Omitted on group launches - see `children[]` for per-child configs. |
| `data.detail_url` | string | Path to the check detail endpoint. Example: `/v1/checks/3e36e9ec-0c44-4d65-a2f7-37b1b0a4d57e` |
| `data.children` | array of objects | Returned on group launches (i.e. when `check_type = group`). One entry per launched operation, in the order they were requested. Each child has already been queued and can be polled independently via its `detail_url`. |
| `data.children[].uuid` | string (uuid) |  |
| `data.children[].check_type` | string | Example: `court_check` |
| `data.children[].status` | string | Enum: `pending`, `processing`, `complete`, `failed` Example: `pending` |
| `data.children[].config` | object (dynamic) or null | The resolved configuration for this child (defaults merged with any user-supplied values). `null` for operations that take no configuration. |
| `data.children[].detail_url` | string | Example: `/v1/checks/4d7e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `api_reference` | string (uuid) |  |

**Sample response**

```json
{
    "data": {
        "uuid": "00000000-0000-0000-0000-000000000000",
        "check_number": "string",
        "check_type": "string",
        "status": "pending",
        "config": null,
        "detail_url": "/v1/checks/3e36e9ec-0c44-4d65-a2f7-37b1b0a4d57e",
        "children": [
            {
                "uuid": "00000000-0000-0000-0000-000000000000",
                "check_type": "court_check",
                "status": "pending",
                "config": null,
                "detail_url": "/v1/checks/4d7e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f"
            }
        ]
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}
```

### 422 Idempotency-Key was reused with a different request body

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Example: `Idempotency-Key was reused with a different request body.` |

**Sample response**

```json
{
    "message": "Idempotency-Key was reused with a different request body."
}
```

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