WatchEye
Browse guides
View as Markdown

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:

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.

Previous Billing and Account Management Next Rate Limiting