# Adhoc check data fields

The body of `POST /v1/adhoc-checks` carries the subject to screen in a `data` object. Adhoc checks have no entity record to read from, so every required field has to be supplied in the request itself.

The required keys depend on which operations are listed in `check_types`. When multiple operations are launched together, each operation validates the same shared `data` object independently - every required field for every requested operation must be present.

Validation runs **before** any check rows are created or any credit is charged. A missing or malformed field returns `400 Bad Request` identifying the offending key (`data.first_name`, etc.).

Entity-driven launches (`POST /v1/entities/{uuid}/checks` and monitor runs) read the same fields from the saved entity record, not from the request body, so this section does not apply to them.

## Common field formats

These conventions show up across multiple operations:

| Field family | Format | Notes |
|---|---|---|
| Names (`first_name`, `middle_name`, `last_name`, `business_name`, etc.) | UTF-8 strings | Per-operation length and character-set constraints; see the operation tables below. |
| `dob` | `YYYY-MM-DD` (ISO 8601) or `DD/MM/YYYY` | Year range varies by operation: `pep_sanction_check` allows 1900-2099, `adc_check` and `adc_custodian_check` allow 1800-2099. |
| `address_country` | ISO 3166-1 alpha-2 country code | E.g. `AU`, `GB`, `US`. |
| `address_state` | AU state code | For Australian operations: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA`. |

For check types where multiple subject "kinds" are supported (individual, business, vessel) the per-operation table describes which fields belong to which kind. Mixing fields from two kinds in the same `data` object is rejected (e.g. supplying `business_name` together with `first_name` for `pep_sanction_check`).

## Per-operation field reference

### pep_sanction_check

Screens an individual, business or vessel against PEP and sanction watchlists. Exactly one of the three subject kinds must be supplied.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `full_name` | required for individual | string, max 255 | Use this **or** `first_name` + `last_name`. |
| `first_name` | required for individual | string, max 255 | When supplied, `last_name` must also be supplied (or `full_name` instead). |
| `middle_name` | optional | string, max 255 | Only valid alongside individual fields. |
| `last_name` | required for individual | string, min 2, max 255 | When supplied, `first_name` or `full_name` must also be supplied. |
| `dob` | optional | date | `YYYY-MM-DD` or `DD/MM/YYYY`, year 1900-2099. Individual subjects only. |
| `business_name` | required for business | string, max 255 | Mutually exclusive with all individual and vessel fields. |
| `vessel_name` | required for vessel | string, max 255 | Mutually exclusive with all individual and business fields. |
| `address_country` | optional | ISO country code | Used to scope the search. |

### adverse_media

Screens an individual or business for adverse media coverage. Exactly one subject kind must be supplied.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `first_name` | required for individual | string, min 1, max 50 | Letters, hyphens, apostrophes, periods, spaces. |
| `middle_name` | optional | string, min 1, max 50 | Same character set as `first_name`. |
| `last_name` | required for individual | string, min 1, max 50 | Same character set as `first_name`. |
| `dob` | optional | date | `YYYY-MM-DD` or `DD/MM/YYYY`. |
| `business_name` | required for business | string, min 1, max 100 | Mutually exclusive with the individual fields. |
| `address_country` | required | ISO country code | Adverse media is scoped per country. |

### adc_check

Australian death-certificate match. Individual subjects only.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `first_name` | required | string, min 1, max 50 | Letters, hyphens, apostrophes, periods, spaces. |
| `middle_name` | optional | string, min 1, max 50 | |
| `last_name` | required | string, min 1, max 50 | |
| `dob` | required | date | `YYYY-MM-DD` or `DD/MM/YYYY`, year 1800-2099. |
| `address_state` | optional | AU state code | One of `ACT`, `NT`, `NSW`, `QLD`, `SA`, `TAS`, `VIC`, `WA`. |

### adc_custodian_check

Custodian variant of the ADC check. Same fields and rules as `adc_check`.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `first_name` | required | string, min 1, max 50 | |
| `middle_name` | optional | string, min 1, max 50 | |
| `last_name` | required | string, min 1, max 50 | |
| `dob` | required | date | `YYYY-MM-DD` or `DD/MM/YYYY`, year 1800-2099. |
| `address_state` | optional | AU state code | One of `ACT`, `NT`, `NSW`, `QLD`, `SA`, `TAS`, `VIC`, `WA`. |

### banned_disqualified_persons

ASIC and ATO banned-or-disqualified registers. Individual subjects only.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `first_name` | required | string, min 1, max 50 | |
| `middle_name` | optional | string, min 1, max 50 | |
| `last_name` | required | string, min 1, max 50 | |
| `address_state` | optional | string, max 50 | |
| `address_country` | optional | ISO country code | |

### court_check

Australian court-record match. Either an individual or a business subject - the two are mutually exclusive.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `first_name` | required for individual | string, min 1, max 50 | |
| `middle_name` | optional | string, min 1, max 50 | |
| `last_name` | required for individual | string, min 1, max 50 | |
| `business_name` | required for business | string, min 1, max 512 | Mutually exclusive with the individual fields. |
| `address_state` | optional | AU state code | One of `ACT`, `NT`, `NSW`, `QLD`, `SA`, `TAS`, `VIC`, `WA`. |

### email_check

Verifies the deliverability of one to four email addresses.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `email1` | required (when `email2`-`email4` are empty) | RFC-compliant email, max 255 | At least one of `email1`-`email4` must be supplied. |
| `email2` | optional | RFC-compliant email, max 255 | |
| `email3` | optional | RFC-compliant email, max 255 | |
| `email4` | optional | RFC-compliant email, max 255 | |

Each populated email is billed and verified separately. Submitting all four addresses produces four billable units.

### phone_check

Verifies one to four Australian phone numbers.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `phone1` | required (when `phone2`-`phone4` are empty) | AU phone number | E.164 (`+61...`) or local (`0...`); landline area codes `02` / `03` / `07` / `08` or mobile `04`. |
| `phone2` | optional | AU phone number | |
| `phone3` | optional | AU phone number | |
| `phone4` | optional | AU phone number | |

Each populated phone number is billed and verified separately.

### business_check

Australian business / company lookup, driven by ABN or ACN.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `business_number_type` | required | `au_abn` or `au_acn` | |
| `business_number` | required | digits | 11 digits when `business_number_type` is `au_abn`, 9 digits when `au_acn`. ABN/ACN modulo checksums are also enforced at launch time. |
| `business_name` | optional | string, max 255 | Returned alongside the lookup result for traceability. |

### uk_business_check

UK Companies House lookup.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `business_number_type` | required | `uk_crn` | |
| `business_number` | required | 8-character alphanumeric | Case-insensitive. Uppercase prefixes such as `SC` (Scotland) are accepted. |
| `business_name` | optional | string, max 255 | |

### realestate_check

Australian property history lookup, driven by address.

| Field | Required | Type / format | Notes |
|---|---|---|---|
| `address_country` | required | `AU` | The real-estate dataset is Australia-only. |
| `address_line1` | required | string, min 4, max 100 | |
| `address_line2` | optional | string, max 100 | |
| `address_suburb` | required | string, min 3, max 60 | |
| `address_state` | required | AU state code | One of `ACT`, `NT`, `NSW`, `QLD`, `SA`, `TAS`, `VIC`, `WA`. |
| `address_postcode` | required | 3 or 4 digits | |

## Worked example

A multi-check launch combining a PEP/sanction screen, a court check and a phone check on the same individual:

```bash
curl -X POST https://portal.watcheye.com.au/api/v1/adhoc-checks \
  -H "Authorization: Bearer <key>|<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "check_types": ["pep_sanction_check", "court_check", "phone_check"],
    "config": {
      "court_check": { "listing": "all" }
    },
    "data": {
      "first_name": "John",
      "last_name": "Smith",
      "dob": "1980-06-23",
      "phone1": "+61412345678",
      "address_state": "VIC",
      "address_country": "AU"
    }
  }'
```

Because three check types were requested, the response is `202 Accepted` with a parent group adhoc-check UUID and one child entry per operation. Poll each child via its `detail_url` until `status` is `complete` or `failed`, then read the typed `details` block via the show adhoc check endpoint.