Launch an ID check against an entity
/entities/{entity_uuid}/id-checks
Runs a synchronous identification check against a saved entity and returns **200 OK**
with the full completed check payload inline. Unlike screening checks, ID checks do not
queue for background processing and do not expose a status field.
Each launch is charged at run time after a successful upstream verification call.
Example Request
POSTRequest Schema
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
id_type
Identification type to run. See SELECTABLE_ID_TYPES in the portal field reference.
consent_obtained
Must be `true`. Asserts that your system has obtained express, demonstrable consent from the individual being verified before this check is launched, and that the exact wording shown has been retained by your system for audit and compliance purposes. The specific wording you must show and the record
data
Per-type input fields inside the launch request. Document numbers are never returned in responses. Date of birth must be supplied as `birth_date` in `YYYY-MM-DD` format when required for the selected `id_type`. Other date fields (`card_expiry`, `acquisition_date`, `event_date`, `registration_date`)
data.birth_date
Date of birth in `YYYY-MM-DD` format.
oac
The DVS OAC code to use for this check. Must be one of the OAC codes configured on your account. Required when your account is configured with more than one OAC. When your account has a single OAC this may be omitted and that OAC is used.
Available Response Data
13 Data Pointsuuid uuid
check_number string
id_type string
id_type_name string
check_type string
check_type_name string
outcome enum
pass, fail, pending
outcome_summary string
data_summary string
checked_at timestamp
archived_at timestamp (ISO 8601 timestamp at which the identification check was archived (null if not archived))
program object
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.
Identity verification works end to end in sandbox using the same endpoints and response shapes as live. No real SMS is sent for an IDPass delivered by SMS on a sandbox account; the message is recorded instead of delivered.
Technical Use Cases tag
Screening inside your own workflow
Trigger identity document verification 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.
A synchronous answer in the request
The check runs against the upstream provider before the response returns, so the outcome is final when you receive it. There is no pending state to poll.
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
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.
rocket_launch Implementation
What are the rate limits?
add
What are the rate limits?
600 requests per minute by default, enforced with a 60-second fixed window. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining.
Exceeding the limit returns 429 Too Many Requests with a Retry-After header giving the number of seconds to wait, and X-RateLimit-Reset giving the reset timestamp. Schedule retries from Retry-After instead of a fixed sleep, and slow down before you hit zero, not after.
Higher limits can be arranged case by case through WatchEye support.
Ready to integrate Launch an ID check against an entity?
Talk to our team about credentials, sandbox access and the right combination of endpoints for your workflow.