Disable watchlist screening monitoring

Updated
  • Updated on Mar 9, 2026
  • Published on Feb 16, 2026
Prev Next
Patch
/v1/sessions/{id}/watchlist-screening

Disables the onging monitoring feature for a specific verification session

When to use this endpoint

  • Use this endpoint to disable ongoing monitoring for an end-user's verification session.
  • To check if ongoing monitoring is currently enabled for a specific end-user, use the GET /v1/sessions//watchlist-screening endpoint and examine the monitorStatus parameter in the response payload.

Request body content

  • The request body must contain the monitorStatus field set to disabled to turn off ongoing monitoring for the session.

Implementation notes

  • This endpoint requires session-level HMAC signature authentication
  • If monitoring is already disabled, the endpoint returns a 400 error.
  • Always ensure that you use the correct API URL to send requests. See the API URL section for more info.
  • The order of parameters in the real API response can differ from the order you see in this documentation. This is expected and part of the Backwards compatible changes requirements.
Header parameters
x-auth-client
stringRequired

Your integration's API key (occasionally referred to as the "Token", "API public key" or "Publishable key"). Required for all API requests.

You can find your API key in the Veriff Customer Portal > Settings > API keys.

Exampleyour_api_key
x-hmac-signature
stringRequired

Request body signed with the shared secret key. Required to authenticate the request sender.

Examplef8e1e2d1c1b1a1234567890abcdef1234567890abcdef1234567890abcdef12
Content-Type
stringRequired

Request content type.

Valid values[ "application/json" ]
Exampleapplication/json
Path parameters
id
string (uuid) Required

Verification session ID.

Examplef04bdb47-d3be-4b28-b028-a652feb060b5
Body parameters

Watchlist screening monitoring status update

{
  "monitorStatus": "disabled"
}
object
monitorStatus
string Required

New monitoring status. Must be set to disabled to turn off ongoing monitoring.

Valid values[ "disabled" ]
Exampledisabled
Responses
200

Monitoring disabled successfully

Headers
Content-Type
string
Response content type.
Valid values[ "application/json" ]
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
{
  "status": "success",
  "data": {
    "attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
    "vendorData": "1234567890",
    "monitorStatus": "disabled"
  }
}
Expand All
object
status
string

API request status

Valid values[ "success" ]
Examplesuccess
data
object (WatchlistDisablingData)
attemptId
string (uuid)

UUID v4 which identifies the session attempt.

Exampleaea9ba6d-1b47-47fc-a4fc-f72b6d3584a7
sessionId
string (uuid)

UUID v4 which identifies the verification session.

Examplef04bdb47-d3be-4b28-b028-a652feb060b5
vendorData
string

The unique identifier that you created for your end-user. It can be max 1,000 characters long and contain only non-semantic data that can not be resolved or used outside your systems or environments. Veriff returns it unmodified in webhooks and API response payloads, or as null if not provided.

Example1234567890
monitorStatus
string

New status of the ongoing monitoring feature.

Valid values[ "disabled" ]
Exampledisabled
400

Watchlist screening monitoring is already disabled for this session

Headers
Content-Type
string
Response content type.
Valid values[ "application/json" ]
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
{
  "status": "fail",
  "message": "Watchlist screening is already disabled"
}
object
status
string

API request status

Valid values[ "fail" ]
Examplefail
message
string

Details about the error while disabling watchlist screening

ExampleWatchlist screening is already disabled
401

Unauthorized - invalid or missing authentication credentials

Headers
Content-Type
string
Response content type.
Valid values[ "application/json" ]
{
  "status": "fail",
  "code": "1101",
  "message": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request."
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleMandatory X-AUTH-CLIENT header containing the API key is missing from the request.
402

Watchlist screening feature is not enabled for your integration

404

Verification session not found

Headers
Content-Type
string
Response content type.
Valid values[ "application/json" ]
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
{
  "status": "fail",
  "code": "1101",
  "message": "Resource not found"
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleResource not found
500

Internal server error

Headers
Content-Type
string
Response content type.
Valid values[ "application/json" ]
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
{
  "status": "fail",
  "message": "Something went wrong"
}
object
status
string

API request status

Valid values[ "fail" ]
Examplefail
message
string

Details about the error while disabling watchlist screening

ExampleWatchlist screening is already disabled



Changelog

Changelog

Date

Description

Mar 9, 2026

Documentation updated: parent categories rearranged, intro section expanded, request and response examples added

Feb 16, 2026

monitorStatus description updated

Jan 6, 2026

Documentation published

Related articles