Watchlist-screening webhook

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.

Same webhook is used for both legacy AML Sanctions and enhanced AML Sanctions solutions’ sessions.

Main difference between the solution versions is that enhanced AML Sanctions offers more customization options regarding which lists to screen against, how strictly names are matched and how results are filtered.

Therefore, the enhanced AML Sanctions session’s webhook payload contains more parameters in the searchTerm object: lists, countries, exactMatch, matchThreshold and excludeDeceased keys.

When is watchlist-screening webhook sent?

Prerequisites

5.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

Additional notes

About matchStatus field

The matchStatus field is the primary outcome indicator of the AML/PEP screening itself. It directly answers the compliance question "Is this person flagged on any watchlist?"

The field has two possible values:

• possible_match: the person was found in one or more listings/databases. The data.hits array is populated with data about the person.

• no_match:  the person was not found. The data.hits array is empty.

This is independent from the session decision (approved/declined), which is driven by IDV checks.

The confidence in the matchStatus is higher when combined with IDV, because the screening data was extracted from a verified document. In standalone mode, the accuracy of the screening depends on the quality of the data you input.

If you require more data, you can use the relevant sessionId and query the GET sessions/{sessionId}/person[↗] endpoint to find more detailed info about the match. Look for data in the person.pepSanctionMatches array.

Possible session outcomes

Session approved + matchStatus: no_match

This is the ideal outcome. The end-user’s identity was verified successfully and they were not found on any PEP/Sanctions/Adverse Media lists. You can proceed with onboarding, no further AML action needed.

Session approved + matchStatus: possible_match

The end-user’s identity is verified (the document and selfie are genuine), but they were found on one or more watchlists. Veriff only flags potential matches, you retain decisioning responsibility. Therefore, you need to perform manual review:

• Review the hits array to examine the matched listings (source names, URLs, match types, etc.).

• Determine whether the hit is a true match or a false positive (e.g., common name coincidence).

• Apply your own risk-based decision depending on your regulation and requirements (decline the end-user, apply enhanced due diligence, or escalate).

Sample request

{
   "id":"a3f8b2c1-1234-4abc-8def-0123456789ab",
   "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",
   "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":[
      {
         "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"
               }
            ]
         }
      }
   ]
}

Request properties

*Required field

• checkType: updated_result* Indicates if the succession of the check, one of intial_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* Indicates the result of the search, one of possible_match, no_match

• 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 of string List of watchlists against which the check was performed. Available only for enhanced AML solution.

  • countries: array of string 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

  • 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 doesn't 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 Date of the listing. Null if listing doesn't 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 doesn't 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 doesn't 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