Run a monitor on demand
/monitors/{monitor_uuid}/run
Queues an immediate run of the monitor and returns 202 Accepted once the run has been
scheduled. The actual screening happens in the background - poll
GET /monitors/{monitor_uuid} and wait for process_status to transition out of
pending / processing before reading the results.
Example Request
POSTRequest Schema
monitor_uuid
The monitor 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
run_type
Which entities to process. See the description above for the difference between `new` and `all`.
Available Response Data
13 Data Pointsuuid uuid
The monitor's UUID
monitor_number string (A short obfuscated public identifier for the monitor (e.g. "M-12-34-56"))
monitor_name string
The display name of the monitor
monitor_check_type string
The screening operation this monitor runs
monitor_check_type_name string (Human-readable name for monitor_check_type (e.g. "PEP & Sanction Check"))
status enum
Lifecycle status: active, paused
process_status enum
In-flight run state, or null when the monitor is idle: pending, processing, failed, paused
process_status_comment string (Optional human-readable detail accompanying process_status (e.g. failure message))
schedule enum
How often the monitor runs unattended: manual, every_day, weekdays, weekends, monday, tuesday, …
schedule_name string (Human-readable description of the schedule (e.g. "Every Day (Mon-Sun)"))
config object
Per-operation configuration
last_run_at timestamp
ISO 8601 timestamp of the most recent run, or null if the monitor has never run
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 scheduled or on-demand screening jobs 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 Run a monitor on demand?
Talk to our team about credentials, sandbox access and the right combination of endpoints for your workflow.