> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.veriff.com/llms.txt > Use this file to discover all available pages before exploring further. # Update watchlist screening > ### Updates watchlist screening state for a specific verification session - Only available for customers using the [Veriff PEP and Sanctions services](https://devdocs.veriff.com/docs/aml-screening-solution) #### 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/{id}/watchlist-screening](https://devdocs.veriff.com/apidocs/v1sessionsidwatchlist-screening-1) 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/{id}/watchlist-screening](https://devdocs.veriff.com/apidocs/v1sessionsidwatchlist-screening-1) 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](https://devdocs.veriff.com/docs/hmac-authentication-and-endpoint-security#public-api-v1) authentication - Always ensure that you use the correct API URL to send requests. See the [API URL section](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#api-url) 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](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#backwards-compatible-changes) requirements. ## OpenAPI ````json PATCH /v1/sessions/{id}/watchlist-screening { "openapi": "3.0.0", "info": { "title": "Veriff Public API", "version": "1.0.0" }, "servers": [ { "url": "https://example-base-url" } ], "tags": [ { "name": "Session management", "description": "Create and manage verification sessions" }, { "name": "Data submission", "description": "Upload media and submit verification data during the session" }, { "name": "Session results", "description": "Retrieve verification decisions and results" }, { "name": "Media management", "description": "Access and download verification media files and media file-related data" }, { "name": "Database verification", "description": "Validate identity against national registries and databases" }, { "name": "Certificate management", "description": "Retrieve long-term preservation certificates and their source documents for a verification session" } ], "paths": { "/v1/sessions/{id}/watchlist-screening": { "patch": { "operationId": "updateWatchlistScreeningController", "summary": "Update watchlist screening", "description": "### Updates watchlist screening state for a specific verification session\n\n- Only available for customers using the [Veriff PEP and Sanctions services](https://devdocs.veriff.com/docs/aml-screening-solution)\n\n#### Supported operations\n\n- This endpoint supports three **mutually exclusive operations**. Each request must contain **exactly one**\nof the following top-level fields. Sending more than one in the same request results in a `400` error.\n\n##### Operation 1: review a hit (`hit` field)\n\n- Update a specific screening hit. Provide the hit `id` (from the [GET /v1/sessions/{id}/watchlist-screening](https://devdocs.veriff.com/apidocs/v1sessionsidwatchlist-screening-1) endpoint response). Send `matchStatus`, `riskLevel`, and `isWhitelisted` as optional fields depending on what you want to update.\n- You can combine these optional fields in the same request when the combination satisfies the validation rules below.\n\n- `matchStatus` values (optional):\n - `false_positive`: the hit is not a real match (e.g., common name coincidence)\n - `potential_match`: the hit requires further investigation (default value)\n - `true_match`: the hit is confirmed as a real match\n - `inconclusive`: unable to determine if the hit is a real match\n\n- `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):\n - `low`: the confirmed match represents low risk\n - `high`: the confirmed match represents high risk\n\n- `isWhitelisted` values (optional):\n - `true`: whitelist the hit and stop receiving ongoing monitoring updates for it\n - `false`: remove the hit from the whitelist\n\n- Whitelisting follows the review decision automatically:\n - Setting `matchStatus` to `false_positive` also whitelists the hit.\n - Changing a hit from `false_positive` to any other `matchStatus` removes it from the whitelist, unless you send `isWhitelisted: true` in the same request.\n - Changing between other `matchStatus` values (for example `potential_match` to `true_match`) keeps the current whitelisting.\n\n##### Operation 2: acknowledge monitoring changes (`hasUnacknowledgedChanges` field)\n\n- Acknowledge that all changes from ongoing monitoring have been reviewed. Only the value `false` is accepted.\n\n##### Operation 3: disable monitoring (`monitorStatus` field)\n\n- Disable ongoing monitoring for the session. Only the value `disabled` is accepted.\n- To check if ongoing monitoring is currently enabled, use the\n[GET /v1/sessions/{id}/watchlist-screening](https://devdocs.veriff.com/apidocs/v1sessionsidwatchlist-screening-1)\nendpoint and examine the `monitorStatus` parameter.\n\n#### Validation rules\n\n- Exactly one top-level field (`hit`, `hasUnacknowledgedChanges`, or `monitorStatus`) per request\n- 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\n- Un-whitelisting (`isWhitelisted: false`) a hit reviewed as `false_positive`, or sending `isWhitelisted: false` together with `matchStatus: false_positive`, returns a `400` error\n- `hasUnacknowledgedChanges` only accepts `false`\n- `monitorStatus` only accepts `disabled`\n- If monitoring is already disabled, the endpoint returns a `400` error\n\n#### Implementation notes\n\n- This endpoint requires session-level [HMAC signature](https://devdocs.veriff.com/docs/hmac-authentication-and-endpoint-security#public-api-v1) authentication\n- Always ensure that you use the correct API URL to send requests. See the [API URL section](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#api-url) for more info.\n- 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](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#backwards-compatible-changes) requirements.\n", "tags": [ "Session results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Verification session ID.", "schema": { "type": "string", "format": "uuid" }, "example": "f04bdb47-d3be-4b28-b028-a652feb060b5" }, { "name": "X-AUTH-CLIENT", "in": "header", "required": true, "description": "Your integration's API key (occasionally referred to as the \"Token\", \"API public key\" or \"Publishable key\").\nRequired for all API requests.\n\nYou can find your API key in the Veriff Customer Portal > Settings > API keys.\n", "schema": { "type": "string" }, "example": "your_api_key" }, { "name": "X-HMAC-SIGNATURE", "in": "header", "required": true, "description": "Request body signed with the shared secret key. Required to authenticate the request sender.", "schema": { "type": "string" }, "example": "f8e1e2d1c1b1a1234567890abcdef1234567890abcdef1234567890abcdef12" }, { "name": "Content-Type", "in": "header", "required": true, "description": "Request content type.", "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "requestBody": { "required": true, "description": "Watchlist screening update request. Exactly one of the three top-level fields must be provided.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchWatchlistScreeningRequestBody" }, "examples": { "update_hit_true_match": { "summary": "Review a hit as true match with high risk", "value": { "hit": { "id": "4KJL9THDX9ZNV4W", "matchStatus": "true_match", "riskLevel": "high" } } }, "update_hit_false_positive": { "summary": "Review a hit as false positive", "value": { "hit": { "id": "4KJL9THDX9ZNV4W", "matchStatus": "false_positive" } } }, "update_hit_potential_match": { "summary": "Review a hit as potential match", "value": { "hit": { "id": "4KJL9THDX9ZNV4W", "matchStatus": "potential_match" } } }, "whitelist_hit": { "summary": "Whitelist a hit", "value": { "hit": { "id": "4KJL9THDX9ZNV4W", "isWhitelisted": true } } }, "unwhitelist_hit": { "summary": "Remove a hit from the whitelist", "value": { "hit": { "id": "4KJL9THDX9ZNV4W", "isWhitelisted": false } } }, "update_risk_level_only": { "summary": "Update the risk level of a hit already reviewed as true match", "value": { "hit": { "id": "4KJL9THDX9ZNV4W", "riskLevel": "high" } } }, "acknowledge_changes": { "summary": "Acknowledge monitoring changes", "value": { "hasUnacknowledgedChanges": false } }, "disable_monitoring": { "summary": "Disable ongoing monitoring", "value": { "monitorStatus": "disabled" } } } } } }, "responses": { "200": { "description": "Watchlist screening updated successfully", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string" }, "example": "your_api_key" }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key. Required to authenticate the response sender.", "schema": { "type": "string" }, "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WatchlistResponse" }, { "$ref": "#/components/schemas/WatchlistMonitoringDisabledResponse" } ] }, "examples": { "update_success": { "$ref": "#/components/examples/WatchlistScreeningUpdateSuccess" }, "disable_monitoring_success": { "summary": "Monitoring disabled successfully", "value": { "status": "success", "data": { "attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7", "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5", "vendorData": "1234567890", "monitorStatus": "disabled" } } } } } } }, "400": { "description": "Bad request - validation error", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string" }, "example": "your_api_key" }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key. Required to authenticate the response sender.", "schema": { "type": "string" }, "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" }, "examples": { "mutually_exclusive_fields": { "$ref": "#/components/examples/WatchlistScreeningValidationError" }, "risk_level_without_true_match": { "summary": "Risk level without true match", "description": "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`.\n", "value": { "status": "fail", "code": "1104", "message": "Request includes invalid parameters" } }, "invalid_has_unacknowledged_changes": { "$ref": "#/components/examples/WatchlistScreeningValidationError" }, "invalid_hit_id": { "summary": "Invalid hit ID", "value": { "status": "fail", "code": "1104", "message": "Invalid hit ID" } }, "unwhitelist_false_positive": { "summary": "Un-whitelisting a false positive hit", "description": "Returned when `isWhitelisted: false` is sent for a hit reviewed as `false_positive`, or together with `matchStatus: false_positive`.\n", "value": { "status": "fail", "code": "1104", "message": "A false_positive hit cannot be un-whitelisted" } }, "monitoring_already_disabled": { "summary": "Monitoring already disabled", "value": { "status": "fail", "message": "Watchlist screening was already disabled" } } } } } }, "401": { "description": "Unauthorized - invalid or missing authentication credentials", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "examples": { "missing_api_key": { "summary": "Missing X-AUTH-CLIENT header", "value": { "status": "fail", "code": "1101", "message": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request." } }, "missing_hmac_signature": { "summary": "Missing or invalid X-HMAC-SIGNATURE header", "value": { "status": "fail", "code": "1815", "message": "Could not authenticate request." } } } } } }, "402": { "description": "Watchlist screening feature is not enabled for your integration" }, "404": { "description": "Verification session not found", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string" }, "example": "your_api_key" }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key. Required to authenticate the response sender.", "schema": { "type": "string" }, "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponse" }, "example": { "status": "fail", "code": "1101", "message": "Resource not found" } } } }, "500": { "description": "Internal server error", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string" }, "example": "your_api_key" }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key. Required to authenticate the response sender.", "schema": { "type": "string" }, "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistDisablingErrorResponse" }, "example": { "status": "fail", "message": "Something went wrong" } } } } }, "x-d360-narrative-responses": "



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

" } } }, "components": { "schemas": { "PatchWatchlistScreeningRequestBody": { "description": "Request body for updating watchlist screening. Exactly one of the three top-level fields must be provided per request.\nThe fields `hit`, `hasUnacknowledgedChanges`, and `monitorStatus` are mutually exclusive.\n", "oneOf": [ { "$ref": "#/components/schemas/PatchWatchlistScreeningHitReviewRequest" }, { "$ref": "#/components/schemas/PatchWatchlistScreeningAcknowledgeRequest" }, { "$ref": "#/components/schemas/PatchWatchlistScreeningDisableMonitoringRequest" } ] }, "WatchlistResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "API request status.", "example": "success" }, "data": { "description": "Data containing PEP & Sanctions result details.", "allOf": [ { "$ref": "#/components/schemas/WatchlistData" } ] } } }, "WatchlistMonitoringDisabledResponse": { "type": "object", "description": "Reduced response returned by the PATCH endpoint when ongoing monitoring is disabled. Confirms the identifiers of the affected session and the resulting monitoring state, and does not include the full screening result set.\n", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "description": "API request status.", "example": "success" }, "data": { "description": "Identifiers of the affected session and confirmation that monitoring is disabled.", "allOf": [ { "$ref": "#/components/schemas/WatchlistMonitoringDisabledData" } ] } } }, "BadRequestErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "code": { "type": "string", "example": "1101" }, "message": { "type": "string", "example": "Validation failed" } }, "required": [ "status", "code", "message" ] }, "UnauthorizedErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "code": { "type": "string", "example": "1101" }, "message": { "type": "string", "example": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request." } }, "required": [ "status", "code", "message" ] }, "NotFoundErrorResponse": { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "code": { "type": "string", "example": "1101" }, "message": { "type": "string", "example": "Resource not found" } } }, "WatchlistDisablingErrorResponse": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "string", "description": "API request status", "enum": [ "fail" ], "example": "fail" }, "message": { "type": "string", "description": "Details about the error while disabling watchlist screening", "example": "Watchlist screening is already disabled" } } }, "PatchWatchlistScreeningHitReviewRequest": { "type": "object", "description": "Update the review status of a specific hit.", "additionalProperties": false, "required": [ "hit" ], "properties": { "hit": { "type": "object", "description": "Object containing the hit review update. At least one of `matchStatus`, `riskLevel`, or `isWhitelisted` is required.\n", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the hit to review.", "example": "4KJL9THDX9ZNV4W" }, "matchStatus": { "type": "string", "description": "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`.\nSetting 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.\n", "enum": [ "false_positive", "potential_match", "true_match", "inconclusive" ], "example": "true_match" }, "riskLevel": { "type": "string", "description": "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.\n", "enum": [ "low", "high" ], "example": "high" }, "isWhitelisted": { "type": "boolean", "description": "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.\nTakes precedence over the automatic whitelisting that follows `matchStatus`.\n", "example": true } } } } }, "PatchWatchlistScreeningAcknowledgeRequest": { "type": "object", "description": "Acknowledge unacknowledged changes from ongoing monitoring.", "additionalProperties": false, "required": [ "hasUnacknowledgedChanges" ], "properties": { "hasUnacknowledgedChanges": { "type": "boolean", "description": "Must be set to `false` to acknowledge that all monitoring changes have been reviewed.\nOnly `false` is accepted as a value.\n", "enum": [ false ], "example": false } } }, "PatchWatchlistScreeningDisableMonitoringRequest": { "type": "object", "description": "Disable ongoing monitoring for this session.", "additionalProperties": false, "required": [ "monitorStatus" ], "properties": { "monitorStatus": { "type": "string", "description": "Must be set to `disabled` to turn off ongoing monitoring.", "enum": [ "disabled" ], "example": "disabled" } } }, "WatchlistData": { "type": "object", "required": [ "attemptId", "sessionId", "vendorData", "checkType", "matchStatus", "searchTerm", "totalHits", "createdAt", "hits" ], "properties": { "attemptId": { "type": "string", "format": "uuid", "description": "UUID v4 which identifies session attempt.", "example": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7" }, "sessionId": { "type": "string", "format": "uuid", "description": "UUID v4 which identifies session.", "example": "f04bdb47-d3be-4b28-b028-a652feb060b5" }, "vendorData": { "type": "string", "description": "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.\n", "example": "1234567890" }, "endUserId": { "type": "string", "format": "uuid", "description": "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.\n", "example": "c1de400b-1877-4284-8494-071d37916197" }, "checkType": { "type": "string", "description": "Indicates if the response is for the initial check or a subsequent check.\nRelevant only if ongoing-monitoring has been enabled for your integration.\n", "enum": [ "initial_result", "updated_result" ], "example": "initial_result" }, "matchStatus": { "type": "string", "deprecated": true, "description": "**Deprecated.** Use `reviewStatus` instead.\n\nIndicates if there was a match in the database.\n", "enum": [ "possible_match", "no_match" ], "example": "possible_match" }, "reviewStatus": { "type": "string", "description": "Overall review status of the watchlist screening hits.\n\n- `no_match`: no hits were found in PEP/Sanctions databases\n- `reviewed`: all hits have been reviewed by the customer\n- `potential_match`: hits exist that have not yet been fully reviewed\n", "enum": [ "no_match", "reviewed", "potential_match" ], "example": "reviewed" }, "hasUnacknowledgedChanges": { "type": "boolean", "description": "Indicates whether there are unacknowledged changes from ongoing monitoring that require attention.\n\nUse the PATCH endpoint with `hasUnacknowledgedChanges: false` to acknowledge changes.\n", "example": false }, "monitorStatus": { "type": "string", "description": "Indicates if monitoring is enabled or disabled for this session, or empty if status is unknown.", "enum": [ "enabled", "disabled" ], "example": "enabled" }, "searchTerm": { "description": "Data used to perform the check.", "allOf": [ { "$ref": "#/components/schemas/SearchTerm" } ] }, "totalHits": { "type": "integer", "description": "Total number of hits returned from the check.", "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the check response was received.\n\nAs combined ISO 8601 date and time in UTC. Format: YYYY-MM-DDTHH:MM:SS.sssZ.\n", "example": "2021-07-05T13:23:59.851Z" }, "hits": { "type": "array", "description": "Array of records that were matched. Empty array if no hits were found.", "items": { "$ref": "#/components/schemas/PepSanctionMatchHit" } } } }, "WatchlistMonitoringDisabledData": { "type": "object", "description": "Reduced response payload returned when ongoing monitoring is disabled via PATCH. It confirms the identifiers of the affected session and the resulting monitoring state, and does not include the full screening result set.\n", "additionalProperties": false, "required": [ "attemptId", "sessionId", "vendorData", "monitorStatus" ], "properties": { "attemptId": { "type": "string", "format": "uuid", "description": "UUID v4 which identifies session attempt.", "example": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7" }, "sessionId": { "type": "string", "format": "uuid", "description": "UUID v4 which identifies session.", "example": "f04bdb47-d3be-4b28-b028-a652feb060b5" }, "vendorData": { "type": "string", "description": "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.\n", "example": "1234567890" }, "monitorStatus": { "type": "string", "description": "Confirms that ongoing monitoring has been disabled for this session.", "enum": [ "disabled" ], "example": "disabled" } } }, "SearchTerm": { "type": "object", "required": [ "name", "year" ], "properties": { "name": { "type": "string", "description": "Full name used during the check.", "example": "GADDAFI" }, "year": { "type": "string", "description": "Birth year used during the check.", "example": "1942" }, "lists": { "type": "array", "description": "List of watchlists against which the check was performed. Available only for [enhanced AML solution](https://devdocs.veriff.com/docs/aml-screening-solution).", "items": { "type": "string" }, "example": [ "SANCTIONS", "PEP_CLASS_1", "PEP_CLASS_2" ] }, "countries": { "type": "array", "description": "List of countries associated with the check. Available only for [enhanced AML solution](https://devdocs.veriff.com/docs/aml-screening-solution).", "items": { "type": "string" }, "example": [ "US", "GB", "FR" ] }, "exactMatch": { "type": "boolean", "description": "Indicates whether the name used in the check required an exact match. Available only for [enhanced AML solution](https://devdocs.veriff.com/docs/aml-screening-solution).", "example": false }, "matchThreshold": { "type": "integer", "minimum": 0, "maximum": 100, "description": "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](https://devdocs.veriff.com/docs/aml-screening-solution).", "example": 80 }, "excludeDeceased": { "type": "boolean", "description": "Indicates whether deceased individuals were excluded from the check. Available only for [enhanced AML solution](https://devdocs.veriff.com/docs/aml-screening-solution).", "example": true } } }, "PepSanctionMatchHit": { "type": "object", "required": [ "id", "matchedName", "countries", "dateOfBirth", "dateOfDeath", "matchTypes", "aka", "associates", "listingsRelatedToMatch", "isWhitelisted" ], "properties": { "id": { "type": "string", "description": "Unique identifier of this hit.\nUse this ID when updating hit review status via the PATCH endpoint.\n", "example": "4KJL9THDX9ZNV4W" }, "matchStatus": { "type": "string", "description": "Review decision for this specific hit.\n", "enum": [ "false_positive", "potential_match", "true_match", "inconclusive" ], "example": "potential_match" }, "riskLevel": { "type": "string", "description": "Risk level assessment for this hit. Only present when hit-level `matchStatus` is `true_match`.\n", "enum": [ "low", "high" ], "example": "high" }, "isWhitelisted": { "type": "boolean", "description": "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.\nReviewing a hit as `false_positive` whitelists it automatically.\n", "example": false }, "matchedName": { "type": "string", "description": "The name that was matched in this hit based on the search term.", "example": "Mouammar Mohammed Abu Minyar Kadhafi" }, "countries": { "type": "array", "description": "List of countries that the sources listed in relation to this hit.", "items": { "type": "string" }, "example": [ "Australia", "Brazil" ] }, "dateOfBirth": { "type": "string", "description": "Birth date of the person in the matched listings.", "example": "1942" }, "dateOfDeath": { "type": "string", "nullable": true, "description": "Death date of the person in the matched listings.", "example": "2011" }, "matchTypes": { "type": "array", "description": "Array that shows the match type in the listings.\n\nSee the [data provider's documentation](https://docs.complyadvantage.com/) for more detailed info.\n", "items": { "type": "string" }, "example": [ "matching_name" ] }, "aka": { "type": "array", "description": "Array of names that the matched person is also known as.", "items": { "type": "string" }, "example": [ "Moamarr Qaddafi" ] }, "associates": { "type": "array", "description": "Array of names that the matched person is associated with.", "items": { "type": "string" }, "example": [] }, "listingsRelatedToMatch": { "description": "Matched listings. Empty object if addon \"PEP & Sanctions check\" is not enabled.", "allOf": [ { "$ref": "#/components/schemas/PepSanctionRelatedListings" } ] } } }, "PepSanctionRelatedListings": { "type": "object", "properties": { "warnings": { "type": "array", "description": "Array of warning-related listings.", "items": { "$ref": "#/components/schemas/RelatedListingsProperties1" } }, "sanctions": { "type": "array", "description": "Array of sanctions-related listings.", "items": { "$ref": "#/components/schemas/RelatedListingsProperties1" } }, "fitnessProbity": { "type": "array", "description": "Array of fitness and probity-related listings.", "items": { "$ref": "#/components/schemas/RelatedListingsProperties1" } }, "pep": { "type": "array", "description": "Array of PEP-related listings.", "items": { "$ref": "#/components/schemas/RelatedListingsProperties1" } }, "adverseMedia": { "type": "array", "description": "Array of adverse media-related listings.", "items": { "$ref": "#/components/schemas/RelatedListingsProperties2" } } } }, "RelatedListingsProperties1": { "type": "object", "required": [ "sourceName" ], "properties": { "sourceName": { "type": "string", "description": "Source name of the related listing.", "example": "ComplyAdvantage PEP data" }, "sourceUrl": { "type": "string", "nullable": true, "description": "Source URL of the related listing." }, "date": { "type": "string", "nullable": true, "description": "Date of the related listing." } } }, "RelatedListingsProperties2": { "type": "object", "required": [ "sourceName" ], "properties": { "sourceName": { "type": "string", "description": "Source name of the related listing.", "example": "ComplyAdvantage PEP data" }, "snippet": { "type": "string", "description": "Text snippet from the source listing.", "example": "Sang 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": { "type": "string", "nullable": true, "description": "Source URL of the related listing." }, "date": { "type": "string", "nullable": true, "description": "Date of the related listing." } } } }, "examples": { "WatchlistScreeningUpdateSuccess": { "summary": "Watchlist screening updated successfully", "description": "Response after a successful PATCH operation (hit review or acknowledge changes). Returns the current screening state.", "value": { "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": [] } } ] } } }, "WatchlistScreeningValidationError": { "summary": "Validation error", "description": "Response when request includes invalid parameters", "value": { "status": "fail", "code": "1104", "message": "Request includes invalid parameters" } } } } } ```` ## Related topics - [Watchlist-screening results](/apidocs/v1sessionsidwatchlist-screening-1.md)