Skip to navigation
Identity verification APIEntity Actions

Switch ongoing screening on or off

Turns ongoing watchlist screening on or off for one entity. On enrols the entity in any applicable screening it is not yet enrolled in and resumes paused screenings, so it is screened again on your configured cadence. Off pauses them; past results, reviews and cleared matches are kept.

The call is idempotent: asking for the state the entity is already in changes nothing and reports changed: 0. Screening is billed per screen run in production and is free in sandbox. The call is recorded in your audit log.

Error codes

errorStatusMeaning
invalid_request400The body failed validation. details carries the field-level breakdown.
entity_not_found404No live entity has this reference in this organisation and environment.
secret_key_required403A publishable key was used. This API accepts secret keys only.
environment_mismatch403The key belongs to an environment this host does not serve.
rate_limited429The request rate limit for this key was reached. Retry after a short wait.
rate_limit_store_unavailable503Rate limiting is temporarily unavailable. Retry shortly.

A missing or unknown key returns 401 with a plain sentence in error rather than a code.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer
Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Path parameters

externalUserIdstringRequired
Your own stable reference for the person or business, as sent when the entity was registered.

Request

This endpoint expects an object.
ongoingbooleanRequired

True to enrol the entity and resume its screening; false to pause it.

Response

Success
ongoingboolean
The state you asked for, echoed back.
activeboolean
False when screening does not run for your organisation or is paused for this entity, in which case nothing was enrolled.
changedinteger
How many of the screenings of the entity actually changed state.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
503
Service Unavailable Error