Update watchlist screening

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

Updates watchlist screening state for a specific verification session

Supported operations

  • This endpoint supports three mutually exclusive operations. Each request must contain exactly one of the following top-level fields. Sending more than one in the same request results in a 400 error.
Operation 1: review a hit (hit field)

  • Update a specific screening hit. Provide the hit id (from the GET /v1/sessions//watchlist-screening endpoint response). Send matchStatus, riskLevel, and isWhitelisted as optional fields depending on what you want to update.

  • You can combine these optional fields in the same request when the combination satisfies the validation rules below.

  • matchStatus values (optional):

    • false_positive: the hit is not a real match (e.g., common name coincidence)
    • potential_match: the hit requires further investigation (default value)
    • true_match: the hit is confirmed as a real match
    • inconclusive: unable to determine if the hit is a real match

  • riskLevel values (optional; can be sent together with matchStatus: true_match, or on its own to update the risk level of a hit that is already reviewed as true_match; sending it for any other hit returns a 400 error):

    • low: the confirmed match represents low risk
    • high: the confirmed match represents high risk

  • isWhitelisted values (optional):

    • true: whitelist the hit and stop receiving ongoing monitoring updates for it
    • false: remove the hit from the whitelist

  • Whitelisting follows the review decision automatically:

    • Setting matchStatus to false_positive also whitelists the hit.
    • Changing a hit from false_positive to any other matchStatus removes it from the whitelist, unless you send isWhitelisted: true in the same request.
    • Changing between other matchStatus values (for example potential_match to true_match) keeps the current whitelisting.
Operation 2: acknowledge monitoring changes (hasUnacknowledgedChanges field)
  • Acknowledge that all changes from ongoing monitoring have been reviewed. Only the value false is accepted.
Operation 3: disable monitoring (monitorStatus field)
  • Disable ongoing monitoring for the session. Only the value disabled is accepted.
  • To check if ongoing monitoring is currently enabled, use the GET /v1/sessions//watchlist-screening endpoint and examine the monitorStatus parameter.

Validation rules

  • Exactly one top-level field (hit, hasUnacknowledgedChanges, or monitorStatus) per request
  • Sending riskLevel is optional and is accepted with matchStatus: true_match, or on its own for a hit that is already reviewed as true_match; if the resulting hit review state is not true_match, the endpoint returns a 400 error
  • Un-whitelisting (isWhitelisted: false) a hit reviewed as false_positive, or sending isWhitelisted: false together with matchStatus: false_positive, returns a 400 error
  • hasUnacknowledgedChanges only accepts false
  • monitorStatus only accepts disabled
  • If monitoring is already disabled, the endpoint returns a 400 error

Implementation notes

  • This endpoint requires session-level HMAC signature authentication
  • 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 update request. Exactly one of the three top-level fields must be provided.

update_hit_true_match

Review a hit as true match with high risk

{
  "hit": {
    "id": "4KJL9THDX9ZNV4W",
    "matchStatus": "true_match",
    "riskLevel": "high"
  }
}
update_hit_false_positive

Review a hit as false positive

{
  "hit": {
    "id": "4KJL9THDX9ZNV4W",
    "matchStatus": "false_positive"
  }
}
update_hit_potential_match

Review a hit as potential match

{
  "hit": {
    "id": "4KJL9THDX9ZNV4W",
    "matchStatus": "potential_match"
  }
}
whitelist_hit

Whitelist a hit

{
  "hit": {
    "id": "4KJL9THDX9ZNV4W",
    "isWhitelisted": true
  }
}
unwhitelist_hit

Remove a hit from the whitelist

{
  "hit": {
    "id": "4KJL9THDX9ZNV4W",
    "isWhitelisted": false
  }
}
update_risk_level_only

Update the risk level of a hit already reviewed as true match

{
  "hit": {
    "id": "4KJL9THDX9ZNV4W",
    "riskLevel": "high"
  }
}
acknowledge_changes

Acknowledge monitoring changes

{
  "hasUnacknowledgedChanges": false
}
disable_monitoring

Disable ongoing monitoring

{
  "monitorStatus": "disabled"
}
Expand All

Request body for updating watchlist screening. Exactly one of the three top-level fields must be provided per request. The fields hit, hasUnacknowledgedChanges, and monitorStatus are mutually exclusive.

OneOf
PatchWatchlistScreeningHitReviewRequest
object (PatchWatchlistScreeningHitReviewRequest)
hit
object Required

Object containing the hit review update. At least one of matchStatus, riskLevel, or isWhitelisted is required.

id
string Required

The unique identifier of the hit to review.

Example4KJL9THDX9ZNV4W
matchStatus
string

The review decision for this hit. Optional when you are updating only riskLevel for a hit that is already reviewed as true_match, or only isWhitelisted. Setting it to false_positive also whitelists the hit; changing a false_positive hit to another value removes it from the whitelist, unless isWhitelisted: true is sent in the same request.

Valid values[ "false_positive", "potential_match", "true_match", "inconclusive" ]
Exampletrue_match
riskLevel
string

Risk level assessment for this hit. Optional; can be sent together with matchStatus: true_match, or on its own to update the risk level of a hit that is already reviewed as true_match; sending it for any other hit returns a 400 error.

Valid values[ "low", "high" ]
Examplehigh
isWhitelisted
boolean

Set to true to whitelist the hit and stop receiving ongoing monitoring updates for it, false to remove it from the whitelist; removing a hit reviewed as false_positive from the whitelist is not allowed. Takes precedence over the automatic whitelisting that follows matchStatus.

Exampletrue
PatchWatchlistScreeningAcknowledgeRequest
object (PatchWatchlistScreeningAcknowledgeRequest)
hasUnacknowledgedChanges
boolean Required

Must be set to false to acknowledge that all monitoring changes have been reviewed. Only false is accepted as a value.

Valid values[ false ]
Examplefalse
PatchWatchlistScreeningDisableMonitoringRequest
object (PatchWatchlistScreeningDisableMonitoringRequest)
monitorStatus
string Required

Must be set to disabled to turn off ongoing monitoring.

Valid values[ "disabled" ]
Exampledisabled
Responses
200

Watchlist screening updated successfully

Headers
Content-Type
string
Response content type.
Valid values[ "application/json" ]
Exampleapplication/json
X-AUTH-CLIENT
string
API key echoed back in response.
Exampleyour_api_key
X-HMAC-SIGNATURE
string
Response body signed with the shared secret key. Required to authenticate the response sender.
Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
update_success

Watchlist screening updated successfully

Response after a successful PATCH operation (hit review or acknowledge changes). Returns the current screening state.

{
  "status": "success",
  "data": {
    "attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
    "vendorData": "customer_ref_12345",
    "endUserId": "c1de400b-1877-4284-8494-071d37916197",
    "checkType": "initial_result",
    "matchStatus": "possible_match",
    "reviewStatus": "reviewed",
    "hasUnacknowledgedChanges": false,
    "monitorStatus": "enabled",
    "searchTerm": {
      "name": "GADDAFI",
      "year": "1942",
      "lists": [
        "SANCTIONS",
        "PEP_CLASS_1"
      ],
      "countries": [
        "US",
        "GB"
      ],
      "exactMatch": false,
      "matchThreshold": 80,
      "excludeDeceased": true
    },
    "totalHits": 1,
    "createdAt": "2021-07-05T13:23:59.851Z",
    "hits": [
      {
        "id": "4KJL9THDX9ZNV4W",
        "matchStatus": "true_match",
        "riskLevel": "high",
        "isWhitelisted": false,
        "matchedName": "Mouammar Mohammed Abu Minyar Kadhafi",
        "countries": [
          "Libya",
          "US"
        ],
        "dateOfBirth": "1942",
        "dateOfDeath": "2011",
        "matchTypes": [
          "matching_name"
        ],
        "aka": [
          "Moammar Qaddafi"
        ],
        "associates": [
          "Saif al-Islam Gaddafi"
        ],
        "listingsRelatedToMatch": {
          "warnings": [],
          "sanctions": [
            {
              "sourceName": "UN Security Council Sanctions",
              "sourceUrl": "https://www.un.org/securitycouncil/sanctions",
              "date": "2011-02-26"
            }
          ],
          "fitnessProbity": [],
          "pep": [
            {
              "sourceName": "ComplyAdvantage PEP data",
              "sourceUrl": null,
              "date": null
            }
          ],
          "adverseMedia": []
        }
      }
    ]
  }
}
disable_monitoring_success

Monitoring disabled successfully

{
  "status": "success",
  "data": {
    "attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
    "vendorData": "1234567890",
    "monitorStatus": "disabled"
  }
}
Expand All
OneOf
WatchlistResponse
object (WatchlistResponse)
status
string

API request status.

Examplesuccess
data
object

Data containing PEP & Sanctions result details.

attemptId
string (uuid)

UUID v4 which identifies session attempt.

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

UUID v4 which identifies 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
endUserId
string (uuid)

End-user-specific UUID created by the customer to identify the end-user. Returned unmodified in webhooks and public API calls, or as null if not provided.

Examplec1de400b-1877-4284-8494-071d37916197
checkType
string

Indicates if the response is for the initial check or a subsequent check. Relevant only if ongoing-monitoring has been enabled for your integration.

Valid values[ "initial_result", "updated_result" ]
Exampleinitial_result
matchStatus
string Deprecated

Deprecated. Use reviewStatus instead.

Indicates if there was a match in the database.

Valid values[ "possible_match", "no_match" ]
Examplepossible_match
reviewStatus
string

Overall review status of the watchlist screening hits.

  • no_match: no hits were found in PEP/Sanctions databases
  • reviewed: all hits have been reviewed by the customer
  • potential_match: hits exist that have not yet been fully reviewed
Valid values[ "no_match", "reviewed", "potential_match" ]
Examplereviewed
hasUnacknowledgedChanges
boolean

Indicates whether there are unacknowledged changes from ongoing monitoring that require attention.

Use the PATCH endpoint with hasUnacknowledgedChanges: false to acknowledge changes.

Examplefalse
monitorStatus
string

Indicates if monitoring is enabled or disabled for this session, or empty if status is unknown.

Valid values[ "enabled", "disabled" ]
Exampleenabled
searchTerm
object

Data used to perform the check.

name
string

Full name used during the check.

ExampleGADDAFI
year
string

Birth year used during the check.

Example1942
lists
Array of string

List of watchlists against which the check was performed. Available only for enhanced AML solution.

Example[ "SANCTIONS", "PEP_CLASS_1", "PEP_CLASS_2" ]
string
countries
Array of string

List of countries associated with the check. Available only for enhanced AML solution.

Example[ "US", "GB", "FR" ]
string
exactMatch
boolean

Indicates whether the name used in the check required an exact match. Available only for enhanced AML solution.

Examplefalse
matchThreshold
integer

Name match sensitivity on a 0–100 scale, indicates how much variation should be allowed from the end-user's data in the results. Available only for enhanced AML solution.

Minimum0
Maximum100
Example80
excludeDeceased
boolean

Indicates whether deceased individuals were excluded from the check. Available only for enhanced AML solution.

Exampletrue
totalHits
integer

Total number of hits returned from the check.

Example1
createdAt
string (date-time)

Timestamp indicating when the check response was received.

As combined ISO 8601 date and time in UTC. Format: YYYY-MM-DDTHH:MM:SS.sssZ.

Example2021-07-05T13:23:59.851Z
hits
Array of object (PepSanctionMatchHit)

Array of records that were matched. Empty array if no hits were found.

object
id
string

Unique identifier of this hit. Use this ID when updating hit review status via the PATCH endpoint.

Example4KJL9THDX9ZNV4W
matchStatus
string

Review decision for this specific hit.

Valid values[ "false_positive", "potential_match", "true_match", "inconclusive" ]
Examplepotential_match
riskLevel
string

Risk level assessment for this hit. Only present when hit-level matchStatus is true_match.

Valid values[ "low", "high" ]
Examplehigh
isWhitelisted
boolean

Indicates whether you have whitelisted this hit. When true, ongoing monitoring no longer sends you updates for this hit. Returned as false when the hit is not whitelisted. Reviewing a hit as false_positive whitelists it automatically.

Examplefalse
matchedName
string

The name that was matched in this hit based on the search term.

ExampleMouammar Mohammed Abu Minyar Kadhafi
countries
Array of string

List of countries that the sources listed in relation to this hit.

Example[ "Australia", "Brazil" ]
string
dateOfBirth
string

Birth date of the person in the matched listings.

Example1942
dateOfDeath
string | null

Death date of the person in the matched listings.

Example2011
matchTypes
Array of string

Array that shows the match type in the listings.

See the data provider's documentation for more detailed info.

Example[ "matching_name" ]
string
aka
Array of string

Array of names that the matched person is also known as.

Example[ "Moamarr Qaddafi" ]
string
associates
Array of string

Array of names that the matched person is associated with.

Example[]
string
listingsRelatedToMatch
object

Matched listings. Empty object if addon "PEP & Sanctions check" is not enabled.

warnings
Array of object (RelatedListingsProperties1)

Array of warning-related listings.

object
sourceName
string

Source name of the related listing.

ExampleComplyAdvantage PEP data
sourceUrl
string | null

Source URL of the related listing.

date
string | null

Date of the related listing.

sanctions
Array of object (RelatedListingsProperties1)

Array of sanctions-related listings.

object
sourceName
string

Source name of the related listing.

ExampleComplyAdvantage PEP data
sourceUrl
string | null

Source URL of the related listing.

date
string | null

Date of the related listing.

fitnessProbity
Array of object (RelatedListingsProperties1)

Array of fitness and probity-related listings.

object
sourceName
string

Source name of the related listing.

ExampleComplyAdvantage PEP data
sourceUrl
string | null

Source URL of the related listing.

date
string | null

Date of the related listing.

pep
Array of object (RelatedListingsProperties1)

Array of PEP-related listings.

object
sourceName
string

Source name of the related listing.

ExampleComplyAdvantage PEP data
sourceUrl
string | null

Source URL of the related listing.

date
string | null

Date of the related listing.

adverseMedia
Array of object (RelatedListingsProperties2)

Array of adverse media-related listings.

object
sourceName
string

Source name of the related listing.

ExampleComplyAdvantage PEP data
snippet
string

Text snippet from the source listing.

ExampleSang Tan Judges in the High Court in London have ruled that Saleh Ibrahim Mabrouk, a former aide of Libyan leader Colonel Muammar Gaddafi, was partly to blame for the murder of PC Yvonne Fletcher. The gunman
sourceUrl
string | null

Source URL of the related listing.

date
string | null

Date of the related listing.

WatchlistMonitoringDisabledResponse
object (WatchlistMonitoringDisabledResponse)
status
string

API request status.

Examplesuccess
data
object

Identifiers of the affected session and confirmation that monitoring is disabled.

attemptId
string (uuid)

UUID v4 which identifies session attempt.

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

UUID v4 which identifies 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

Confirms that ongoing monitoring has been disabled for this session.

Valid values[ "disabled" ]
Exampledisabled
400

Bad request - validation error

Headers
Content-Type
string
Response content type.
Valid values[ "application/json" ]
Exampleapplication/json
X-AUTH-CLIENT
string
API key echoed back in response.
Exampleyour_api_key
X-HMAC-SIGNATURE
string
Response body signed with the shared secret key. Required to authenticate the response sender.
Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
mutually_exclusive_fields

Validation error

Response when request includes invalid parameters

{
  "status": "fail",
  "code": "1104",
  "message": "Request includes invalid parameters"
}
risk_level_without_true_match

Risk level without true match

Returned when riskLevel is sent with a matchStatus other than true_match, or on its own for a hit that is not already reviewed as true_match.

{
  "status": "fail",
  "code": "1104",
  "message": "Request includes invalid parameters"
}
invalid_has_unacknowledged_changes

Validation error

Response when request includes invalid parameters

{
  "status": "fail",
  "code": "1104",
  "message": "Request includes invalid parameters"
}
invalid_hit_id

Invalid hit ID

{
  "status": "fail",
  "code": "1104",
  "message": "Invalid hit ID"
}
unwhitelist_false_positive

Un-whitelisting a false positive hit

Returned when isWhitelisted: false is sent for a hit reviewed as false_positive, or together with matchStatus: false_positive.

{
  "status": "fail",
  "code": "1104",
  "message": "A false_positive hit cannot be un-whitelisted"
}
monitoring_already_disabled

Monitoring already disabled

{
  "status": "fail",
  "message": "Watchlist screening was already disabled"
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleValidation failed
401

Unauthorized - invalid or missing authentication credentials

Headers
Content-Type
string
Response content type.
Valid values[ "application/json" ]
Exampleapplication/json
missing_api_key

Missing X-AUTH-CLIENT header

{
  "status": "fail",
  "code": "1101",
  "message": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request."
}
missing_hmac_signature

Missing or invalid X-HMAC-SIGNATURE header

{
  "status": "fail",
  "code": "1815",
  "message": "Could not authenticate 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" ]
Exampleapplication/json
X-AUTH-CLIENT
string
API key echoed back in response.
Exampleyour_api_key
X-HMAC-SIGNATURE
string
Response body signed with the shared secret key. Required to authenticate the response sender.
Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
{
  "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" ]
Exampleapplication/json
X-AUTH-CLIENT
string
API key echoed back in response.
Exampleyour_api_key
X-HMAC-SIGNATURE
string
Response body signed with the shared secret key. Required to authenticate the response sender.
Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
{
  "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

Date

Description

Sep 30, 2026

isWhitelisted info and examples added

Jul 8, 2026

Two new operations added to the endpoint: review a hit and acknowledge monitoring changes, including relevant request and response examples.

Apr 24, 2026

Headers capitalization harmonized

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