WatchEye
Browse endpoints
View as Markdown OpenAPI spec

Launch screening checks against an entity

POST /api/v1/entities/{entity_uuid}/checks operationId: check.launch

Base: 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 section of the API guide for the full contract.

Path parameters

FieldDescription
entity_uuidrequired string (uuid)

The entity UUID

Header parameters

FieldDescription
Idempotency-Key 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 section of the API guide for the full contract.

Example: 8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f

Request body

Content type application/json. The launch parameters

FieldDescription
check_typesrequired array of strings [min 1 items]

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

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.

application/json
FieldDescription
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)
422

Idempotency-Key was reused with a different request body

application/json
FieldDescription
message string

Example: Idempotency-Key was reused with a different request body.
Standard error responses: 400 401 402 403 404 429 5XX See common error responses
Previous Download a check as PDF Next List entities in a program