Launch screening checks against an entity
/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.
Example Request
POSTRequest Schema
entity_uuid
The entity UUID
Idempotency-Key
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
check_types
One or more operation names to launch. See the operation enum in the Check schema for the supported set.
config
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
config.pep_sanction_check
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
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`.
config.pep_sanction_check.similarity_threshold
Minimum name similarity percentage (10..100). Match candidates below this score are dropped. Sent as a string. Defaults to `"80"`.
config.pep_sanction_check.pep_countries
Two-letter ISO country codes (lowercase) to scope the PEP search. An empty array searches all PEP jurisdictions (the default).
config.pep_sanction_check.sanction_countries
Two-letter ISO country codes (lowercase) to scope the sanction search. Defaults to `["au", "ca", "nz", "gb", "us"]`.
config.pep_sanction_check.max_results
Maximum number of match candidates to return. Sent as an integer. Defaults to `25`.
config.pep_sanction_check.pep_sanction_extended_result
When `true`, includes the extended biographical and source-list detail on each match. Defaults to `true`.
config.banned_disqualified_persons
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
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`.
config.banned_disqualified_persons.similarity_threshold
Minimum name similarity percentage (10..100), sent as a string. Defaults to `"80"`.
config.banned_disqualified_persons.banned_types
Restrict the search to one or more specific banned/disqualified registers. An empty array (the default) searches every register.
config.court_check
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
Which court listings to search. `criminal` is the default; `civil` searches civil matters only; `all` searches both.
config.court_check.search_party
Whether the subject should be matched as the `defendant`, `plaintiff`, or `any` party to the case. Defaults to `defendant`.
config.business_check
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
config.business_check.name_match
How strictly the trading name on the entity must match the registered ASIC name. Defaults to `similar`.
config.business_check.abn_active
Alert when the ABN is not active. Defaults to `yes`.
config.business_check.acn_active
Alert when the ACN is not active. Defaults to `yes`.
config.business_check.gst_registered
Alert when GST registration changes. Defaults to `yes`.
config.business_check.recent_documents
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"`.
config.business_check.recent_business_names
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"`.
config.uk_business_check
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
How strictly the trading name must match the Companies House record. Defaults to `similar`.
config.uk_business_check.company_status
Alert when the company status is not `active`. Defaults to `yes`.
config.uk_business_check.recent_filings
Alert when filings have been lodged within the last N months. Defaults to `"3"`.
config.uk_business_check.officer_changes
Alert when officers have changed within the last N months. Defaults to `"3"`.
config.uk_business_check.registered_address_change
Whether to record registered address changes. Defaults to `on_change`.
config.uk_business_check.sic_codes_change
Whether to record SIC code changes. Defaults to `on_change`.
config.realestate_check
Per-operation configuration for a `realestate_check` launch. Every property is optional.
config.realestate_check.date_from
ISO 8601 date (`YYYY-MM-DD`). When set, only listings on or after this date are considered. Omit to search all available history.
Available Response Data
8 Data Pointsuuid uuid
check_number string
check_type string
The operation name when a single type was launched, or
status enum
pending, processing, complete, failed
config object
The resolved configuration for the launched check
detail_url string
Path to the check detail endpoint
children array (Returned on group launches (i.e. when check_type = group))
api_reference uuid
unique request identifier for log tracing and audit
API Data Scale & Coverage tag
Unmatched data depth to power your compliance and verification workflows.
Sandbox Environment
Build and test against a sandbox account. Sandbox is a separate account with its own UUID and its own API keys, and the environment is fixed at the account level, so you cannot switch an existing key between live and sandbox with a parameter or header. Both share the same base URL, so the account behind your key is what determines which environment you are in. GET /v1/account returns an environment field of live or sandbox, and that is the authoritative answer.
Calls on a sandbox key are not billed. Every endpoint, response shape, error envelope, idempotency and rate-limit behaviour mirrors live, so the only change when you move to production should be the credentials. Sandbox accounts are provisioned by your Global Data account manager.
In sandbox the upstream providers are replaced with simulators that return deterministic results from a fixed set of test inputs. Any subject details will exercise the request and response plumbing, but to drive a specific outcome (a match, an explicit non-match, a provider error) you need to use one of the documented sandbox names. Any other name returns an empty result set.
Technical Use Cases tag
Screening inside your own workflow
Trigger PEP, sanction, business, court, adverse media and similar screening tied to an entity from your application at the exact point your process calls for it, instead of asking staff to run it separately in the portal.
Queue now, collect later
The call returns 202 Accepted with the new UUID. The work runs in the background and you poll the show endpoint until it reaches a terminal state, which suits batch launches.
Safe retries
Send an Idempotency-Key so an ambiguous network failure can be retried without running the check twice or being billed twice.
Compliance & Security tag
Enterprise-grade infrastructure audited against the standards your regulators require.
Common Questions tag
Everything you need to know about implementation details and compliance infrastructure.
rocket_launch Implementation
How do I know when the work has finished?
add
How do I know when the work has finished?
This endpoint returns 202 Accepted, which confirms the work is queued, not complete. Poll the corresponding show endpoint until it reaches a terminal value.
For checks and adhoc checks that means status becomes complete or failed. For a monitor run it means process_status becomes null, failed or paused.
A reasonable cadence is every 2 to 5 seconds for the first 30 seconds, backing off to every 15 to 30 seconds after that. Most screening checks finish within a few seconds; a monitor run across thousands of entities can take several minutes.
rocket_launch Implementation
Is it safe to retry this call?
add
Is it safe to retry this call?
Yes, if you send an Idempotency-Key header. A connection can drop after WatchEye has processed a request but before the response reaches you, and a blind retry would risk a duplicate record or a double charge.
The key is any string of your choosing up to 255 characters, unique per logical operation, and a fresh UUID per request is the usual approach. Sending the same key again returns the original response byte for byte, with no new database changes and no new billable charge.
The header is honoured on POST only. It is silently ignored on GET, PATCH and DELETE, which are already idempotent at the HTTP level.
help_center General
Is this call billed?
add
Is this call billed?
Yes. This is a chargeable endpoint, and the fee is billed to your account at the time of the request. Your rates are set per account and confirmed by your Global Data account manager.
If your balance reaches zero or an agreed call limit is reached, further chargeable requests return 402 Payment Required until the account is topped up. Calls made with a key on a sandbox account are never charged.
Ready to integrate Launch screening checks against an entity?
Talk to our team about credentials, sandbox access and the right combination of endpoints for your workflow.