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.

Watchlist-screening webhook

  • Updated on Jul 8, 2026
  • Published on Jul 8, 2026
Prev Next

This webhook returns data from Veriff PEP and Sanctions, adverse media (AM) checks and ongoing monitoring (OGM) services. The payload is sent to Webhook watchlist screening URL, which you need to set up the webhook in the Veriff Customer Portal.

→ See Webhooks Guide > Set up webhooks sub-section for detailed overview of the setup process

In a nutshell: how AML Screening works

If you landed here first, here is the full picture before you dig into the payload details:

  1. Veriff runs the PEP, Sanctions, and Adverse Media check using your integration's configuration. If you are using an IDV integration (document or document+selfie), Veriff also runs the identity verification checks and sends that result via a separate decision webhook, alongside this one. See AML Screening (enhanced) for the full flow.

  2. Results are delivered to you via this webhook, or you can poll them via the GET /sessions/{sessionId}/watchlist-screening endpoint. The reviewStatus field tells you whether the person was found, and whether all hits have been reviewed. See the About reviewStatus field section in AML Screening (enhanced) for more info.

  3. If reviewStatus is potential_match, you review each hit and record your decision using the PATCH /sessions/{sessionId}/watchlist-screening endpoint. See Managing screening results in the AML Screening (enhanced) for the request format.

  4. If ongoing monitoring is enabled, Veriff periodically re-checks the person and sends a new webhook if anything changes, this can reset reviewStatus back to potential_match until you acknowledge the change.

When is watchlist-screening webhook sent?

The webhook is sent after the PEP and Sanctions, adverse media and OGM checks have been passed.

Note that a new webhook will be sent if the system detects that the person's status in the database has changed.

A webhook is also sent when reviewStatus changes from potential_match to reviewed, that is, once you have submitted a review decision for every hit and acknowledged any pending monitoring changes. See "Managing screening results" in the AML Screening (enhanced) or AML Screening (legacy) guide.

Prerequisites

  1.  Make sure you have access to the Veriff Customer Portal
    1. If you do not, see the Getting Started → Sign up and Log in articles
  2.  Set up webhook URL(s) on your side and have them at hand
    1. Make sure they match the Webhook URL requirements
    2. Make sure your system is able to handle Webhooks receipt, delivery and resending requirements
    3. Check the Webhooks headers and payload section for info
  3. Secure your communication, check the HMAC Authentication and Endpoint Security article
  4. Make sure your system is able to handle the Backwards compatible changes

  1. Proceed to Watchlist-screening webhook setup below

Watchlist-screening webhook setup

  1. Log in to the Veriff Customer Portal

  2. Navigate to the Integrations page via the top menu and open the integration used for the AML solution

  3. On the integration's page, select the Settings tab

  4. Under the title Integration settings you see a list of webhooks

  5. Fill in the Webhook watchlist screening URL

→ See Webhooks Guide > Set up webhooks sub-section for detailed overview of the setup process

Additional notes

String reviewStatus shows the overall review state of the screening result:

  • no_match indicates that the person was not found. The hits array is empty

  • potential_match indicates that one or more hits exist that have not yet been fully reviewed

  • reviewed indicates that all hits have been reviewed

Note: The matchStatus field at the top level of the payload is deprecated. Use reviewStatus instead.

reviewed is not a permanent state. If ongoing monitoring later detects a change, hasUnacknowledgedChanges becomes true and reviewStatus reverts to potential_match, even if every hit had already been reviewed. See "Managing screening results" in the AML Screening (enhanced) or AML Screening (legacy) guide for how to acknowledge changes and review new hits.

Sample request

The examples below use placeholder data to show the mandatory parameters and possible fields for this webhook. Your production payload will contain real screening data for the verified end-user, not these placeholder values.

Some fields may be empty or missing: the hits array is empty when no matches are found, and the lists, countries, exactMatch, matchThreshold, and excludeDeceased keys inside searchTerm only appear for the enhanced AML solution, not legacy.

Click to open a sample showing initial result, no match found

{
    "checkType": "initial_result",
    "attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
    "vendorData": "customer_ref_12345",
    "endUserId": "c1de400b-1877-4284-8494-071d37916197",
    "matchStatus": "no_match",
    "reviewStatus": "no_match",
    "hasUnacknowledgedChanges": false,
    "monitorStatus": "enabled",
    "searchTerm": {
        "name": "John Smith",
        "year": "1985",
        "lists": [
          "SANCTIONS",
          "PEP_CLASS_1"
        ],
        "countries": [
          "US"
        ],
        "exactMatch": false,
        "matchThreshold": 80,
        "excludeDeceased": true
    },
    "totalHits": 0,
    "createdAt": "2021-07-05T13:23:59.851Z",
    "hits": []
}

Click to open a sample showing initial result, match found

{
    "checkType": "initial_result",
    "attemptId": "54233318-f81c-4ec4-8e4c-413168a3f5e6",
    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "matchStatus": "possible_match",
    "reviewStatus": "potential_match",
    "hasUnacknowledgedChanges": false,
    "monitorStatus": "enabled",
    "searchTerm": {
        "name": "Mirko Kokki",
        "year": "1960",
        "lists": [
          "SANCTIONS",
          "PEP_CLASS_1",
          "PEP_CLASS_2"
        ],
        "countries": [
          "GB",
          "US",
          "FR"
        ],
        "exactMatch": false,
        "matchThreshold": 80,
        "excludeDeceased": true
    },
    "totalHits": 5,
    "createdAt": "2021-06-02T11:04:00.287Z",
    "hits": [{
        "id": "4KJL9THDX9ZNV4W",
        "matchStatus": "potential_match",
        "matchedName": "Miro kokkino",
        "countries": [
          "Australia",
          "Brazil"
        ],
        "dateOfBirth": "1960",
        "dateOfDeath": null,
        "matchTypes": [
          "aka_exact"
        ],
        "aka": [
          "Kokki Mirko",
          "Mirko Kokki"
        ],
        "associates": [
          "Desmon Lamela",
          "Fred Austin"
        ],
        "listingsRelatedToMatch": {
            "warnings": [
            {
                "sourceName": "FBI Most Wanted",
                "sourceUrl": "http://www.exampleUrl.com",
                "date": null
            }
            ],
            "sanctions": [
            {
                "sourceName": "Example Source",
                "sourceUrl": "https://www.exampleURL2.com",
                "date": null
            },
            {
                "sourceName": "Example Source 2",
                "sourceUrl": "https://www.exampleURL3.com",
                "date": null
            }
            ],
            "fitnessProbity": [
            {
              "sourceName": "Example Source 3",
              "sourceUrl": "https://www.exampleURL4.com"
            }
            ],
            "pep": [
            {
              "sourceName": "Example Source 4",
              "sourceUrl": "https://www.exampleURL5.com"
            }
            ],
            "adverseMedia": [
            {
              "date": "2020-09-23T00:00:00Z",
              "sourceName": "Example Source 5",
              "snippet": "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": "https://www.exampleURL6.com"
            }
            ]
        }
    }
    ]
  }

Click to open a sample showing monitoring update payload

Sent when ongoing monitoring detects a change in the person's status. checkType is updated_result and hasUnacknowledgedChanges is true.

{
    "checkType": "updated_result",
    "attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
    "vendorData": "customer_ref_12345",
    "endUserId": "c1de400b-1877-4284-8494-071d37916197",
    "matchStatus": "possible_match",
    "reviewStatus": "potential_match",
    "hasUnacknowledgedChanges": true,
    "monitorStatus": "enabled",
    "searchTerm": {
        "name": "Maria Santos",
        "year": "1978",
        "lists": [
          "SANCTIONS",
          "PEP_CLASS_1",
          "PEP_CLASS_2"
        ],
        "countries": [
          "BR",
          "US"
        ],
        "exactMatch": false,
        "matchThreshold": 80,
        "excludeDeceased": false
    },
    "totalHits": 1,
    "createdAt": "2021-07-15T08:45:22.123Z",
    "hits": [{
        "id": "7RMP2WNBY3KHQ8F",
        "matchStatus": "potential_match",
        "matchedName": "Maria Santos Silva",
        "countries": [
          "Brazil"
        ],
        "dateOfBirth": "1978",
        "dateOfDeath": null,
        "matchTypes": [
          "matching_name",
          "year_of_birth"
        ],
        "aka": [
          "Maria S. Silva"
        ],
        "associates": [],
        "listingsRelatedToMatch": {
            "warnings": [],
            "sanctions": [],
            "fitnessProbity": [],
            "pep": [
            {
                "sourceName": "Brazil Government Officials Database",
                "sourceUrl": null,
                "date": "2021-07-14"
            }
            ],
            "adverseMedia": [
            {
                "sourceName": "Local News Reports",
                "snippet": "Brazilian government official Maria Santos Silva appeared on a regional PEP watchlist following appointment to a federal oversight committee.",
                "sourceUrl": null,
                "date": "2021-07-10"
            }
            ]
        }
    }]
}

Click to open a sample showing a “reviewed” case

{
    "checkType": "updated_result",
    "attemptId": "9f3c2e71-6b84-4a2f-8e2a-3c1f7e5d9b0a",
    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
    "vendorData": "customer_ref_67890",
    "endUserId": "d2e510c6-2988-4395-9a15-7c3f28a37b62",
    "matchStatus": "possible_match",
    "reviewStatus": "reviewed",
    "hasUnacknowledgedChanges": false,
    "monitorStatus": "enabled",
    "searchTerm": {
        "name": "Mirko Kokki",
        "year": "1960",
        "lists": [
          "SANCTIONS",
          "PEP_CLASS_1"
        ],
        "countries": [
          "GB"
        ],
        "exactMatch": false,
        "matchThreshold": 80,
        "excludeDeceased": true
    },
    "totalHits": 1,
    "createdAt": "2021-06-05T09:12:41.502Z",
    "hits": [{
        "id": "4KJL9THDX9ZNV4W",
        "matchStatus": "true_match",
        "riskLevel": "high",
        "matchedName": "Miro Kokkino",
        "countries": ["Australia"],
        "dateOfBirth": "1960",
        "dateOfDeath": null,
        "matchTypes": ["aka_exact"],
        "aka": ["Kokki Mirko", "Mirko Kokki"],
        "associates": ["Desmon Lamela"],
        "listingsRelatedToMatch": {
            "warnings": [],
            "sanctions": [{
                "sourceName": "Example Source",
                "sourceUrl": "https://www.exampleURL2.com",
                "date": null
            }],
            "fitnessProbity": [],
            "pep": [],
            "adverseMedia": []
        }
    }]
}

Request properties

  • checkType: string Indicates the succession of the check, one of initial_result, updated_result

  • attemptId: string UUID v4 which identifies session attempt

  • sessionId: string UUID v4 which identifies session

  • vendorData: string | null The unique identifier that you created for your end-user

  • endUserId: string | null The UUID that you created for your end-user

  • matchStatus: string Deprecated. Use reviewStatus instead. Indicates if there was a match in the database, one of possible_match, no_match

  • reviewStatus: string Overall review state of the screening result, one of no_match, potential_match, reviewed

  • hasUnacknowledgedChanges: boolean Indicates whether there are unacknowledged changes from ongoing monitoring that require attention

  • monitorStatus: string Indicates if ongoing monitoring is enabled or disabled for this session, one of enabled, disabled

  • searchTerm: object Data used to perform the check

    • name: string Full name used during the check

    • year: string Birth year used during the check

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

    • countries: array List of countries associated with the check, as ISO 3166-1 Alpha-2 country code. Available only for enhanced AML solution

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

    • matchThreshold: integer Configured matching percentage threshold. Available only for enhanced AML solution

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

  • totalHits: integer Total number of hits returned from the check

  • createdAt: string Timestamp indicating when the check was performed

  • hits: array Check response hits array of matched records. Empty array if no hits were found

    • id: string Unique identifier of this hit. Use this ID when submitting review decisions via the PATCH endpoint

    • matchStatus: string Review decision for this specific hit, one of false_positive, potential_match, true_match, inconclusive

    • riskLevel: string Risk level for this hit, one of low, high. Only present when hit-level matchStatus is true_match

    • matchedName: string The name that was matched in this hit based on the search term

    • countries: array List of countries that sources listed in relation to this hit

    • dateOfBirth: string Birth date of the person in the matched listings

    • dateOfDeath: string Death date of the person in the matched listings

    • matchTypes: array Array that shows the match type in the listings. See data provider's documentation[↗] for possible values

    • aka: array Array of names that the matched person is also known as

    • associates: array Array of names that the matched person is associated with

    • listingsRelatedToMatch: object Matched listings. Optional, empty object if "PEP & Sanctions" add-on is not enabled

      • warnings: array Array of warning matches. Empty array if no warnings were found

        • sourceName: string Name of the listing

        • sourceUrl: string URL of the listing

        • date: string | null Date of the listing. null if listing does not have a date

      • sanctions: array Array of sanctions matches. Empty array if no sanctions were found

        • sourceName: string Name of the listing

        • sourceUrl: string URL of the listing

        • date: string | null Date of the listing. null if listing does not have a date

      • fitnessProbity: array Array of fitness probity matches. Empty array if no fitness probities were found

        • sourceName: string Name of the listing

        • sourceUrl: string URL of the listing

        • date: string | null Date of the listing. null if listing does not have a date

      • pep: array Array of PEP matches. Empty array if no PEP matches were found

        • sourceName: string Name of the listing

        • sourceUrl: string URL of the listing

        • date: string | null Date of the listing. null if listing does not have a date

      • adverseMedia: array Array of media matches. Empty array if no media were found

        • sourceName: string Name of the listing

        • snippet: string Text snippet of the related listing

        • sourceUrl: string URL of the listing

        • date: string | null Date of the listing. null if listing does not have a date

Changelog

Date

Description

Jul 8, 2026

  • New fields added: reviewStatus (replaces deprecated matchStatus as the primary screening outcome indicator), monitorStatus, and hasUnacknowledgedChanges.

  • Each hit in the hits array now includes id, matchStatus (per-hit review decision), and riskLevel.

  • Added an "In a nutshell" orientation section linking to the AML Screening guides and API docs, a note on the reviewStatus-change webhook trigger, and a note that reviewed can revert to potential_match.

Feb 10, 2026

searchTerm object updated with lists, countries, exactMatch, matchThreshold and excludeDeceased keys

Feb 2, 2026

New string snippet added to listingsRelatedToMatch.adverseMedia object

Jun 6, 2025

Heading “Article versioning” changed to “Changelog”

Apr 12, 2025

Link added to matchType array, to provide access to array’s possible values

Mar 12, 2025

Documentation published

Related articles