AML Screening (enhanced)

This article covers the enhanced AML Screening solution.

If you are using the previous PEP & Sanctions solution, contact your Solutions Engineer to upgrade to the enhanced solution.

Compared to the legacy solution, the enhanced AML Screening offers more customization options regarding which lists to screen against, how strictly names are matched and how results are filtered.

This solution can be used to meet and comply with Know-Your-Customer (KYC) and Anti-Money Laundering (AML) requirements, including adverse media checks and ongoing monitoring. The enhanced solution allows more customization regarding:

• which lists to screen against,

• how strictly names are matched,

• how results are filtered.

It is available via API, web flow, and native SDKs.

Contact your solutions engineer for info and configuration.

Endpoints and webhooks used in this solution

You call:

• POST /sessions - create the verification session

• PATCH /sessions/{sessionId} - submit the session for processing (non-IDV integrations)

• GET /sessions/{sessionId}/decision - retrieve the identity verification result (IDV integrations only)

• GET /sessions/{sessionId}/watchlist-screening - retrieve the screening result

• PATCH /sessions/{sessionId}/watchlist-screening - review a hit, acknowledge monitoring changes, or disable monitoring

• GET /sessions/{sessionId}/person - get more detail on a specific match (optional)

Veriff sends:

• decision webhook - the identity verification result (IDV integrations only)

• watchlist-screening webhook - the AML screening result, and updates detected by ongoing monitoring

Prerequisites

• You have an integration set up with Veriff

• You have the PEP & Sanctions feature configured by your Solutions Engineer

• You have webhook(s) configured to get responses from Veriff (see the Webhooks section for info)

End-user data sources

The “end-user data sources” refer to different origins from which the end-user’s information can be collected for database verification. There are two data sources: initData and document data.

InitData

This is data that you provide when creating a verification session, i.e. the parameters you specify in the POST /sessions request.

Parameters that can be sent via initData are:

• first name (required) in verification.person.firstName

• last name (required) in verification.person.lastName

• date of birth (optional) in verification.person.dateOfBirth

• end-user’s country (optional) in:

  • verification.document.country when the country should represent the document's issuing country

  • verification.address.country when the country should represent where the end-user actually resides

Date of birth and country info is used as part of screening data sent to do person search.

Document data

This is data that is extracted from the end-user’s document. Includes information like names, date of birth, country data etc.

Flow overview

The flow is a bit different, depending on whether you are using an IDV or non-IDV integration for the checks.

Using an IDV integration

This means that it is possible to run the identity verification checks related to document or document+selfie, and the PEP and Sanctions, Adverse Media and Ongoing Monitoring checks.

End-user’s data can be sent via both Veriff end-user flow and the API endpoints.

1. Once the IDV integration is set up, generate a verification session using the regular POST /sessions endpoint

2. After the end-user’s data has been passed and the session has been verified:

   1. The identity verification results are sent via decision webhook,

   2. The AML result will be sent in the Watchlist-screening webhook

      1. Veriff will send a new webhook if the ongoing monitoring reveals that the status of a verified person has changed

3. You can:

   1. Query the results of AML checks from GET /sessions/{sessionId}/watchlist-screening endpoint

      1. If you query it before screening completes, expect a 202 response

   2. Query the results of IDV checks from GET /sessions/{sessionId}/decision endpoint

      1. This endpoint always returns 200. While the decision is still processing, verification is null; check for that instead of a status code

   3. Or view them in the Veriff Customer Portal

Using a non-IDV integration

This means that it is possible to run only the PEP and Sanctions, Adverse Media and Ongoing Monitoring checks. End-user’s data can be sent only via the API endpoints.

1. Create a new session using the API keys and the baseURL of the integration you are (see the API Documentation and reference how to find these). Include the following fields in the request:

   1. Ensure you send mandatory verification.person.firstName

   2. Ensure you send mandatory verification.person.lastName

   3. You can also send optional verification.person.dateOfBirth

   4. You can also send optional country info (see End-user data sources above)

POST {baseURL}/v1/sessions
Type: object
Headers:
       X-AUTH-CLIENT: string (required) = API key
       Content-Type: application/json

curl -X POST \
  --url '/v1/sessions/' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-KEY' \
  -d '{
    "verification": {
        "person": {
            "firstName": "Eva",
            "lastName": "Nováková",
            "dateOfBirth": "1980-02-21"
        },
    }
}'

2. Change the status of the session to submitted using the PATCH /sessions/{sessionId} endpoint.

   • This endpoint requires endpoint-level authentication via X-HMAC-SIGNATURE header. See HMAC Authentication and Endpoint Security article for general info about signature creation.

3. Receive the results from Veriff via Watchlist-screening webhook, query the results from GET /sessions/{sessionId}/watchlist-screening endpoint, or view them in the Veriff Customer Portal

   1. If you have set up the decision webhook, it will return session info, for example decision time, attempt id, and session status; but as no IDV checks were made, most of the fields will be null

   2. If you query the GET /sessions/{sessionId}/watchlist-screening endpoint right after submission, expect a 202 response while screening is still in progress.

Screening configuration

The screening parameters (which lists to check, match sensitivity, country filters, and other options) are configured on Veriff's side. The table below describes the available options.

To enable or adjust any of them, contact your Solutions Engineer.

You can see which configuration was applied to a specific check in the searchTerm object returned in the watchlist-screening webhook.

lists, countries, exactMatch, matchThreshold, and excludeDeceased in searchTerm are available only for the enhanced AML solution. If you are not seeing them in your payload, you are still using the legacy AML solution. Contact your Solutions Engineer to update.

lists categories and category descriptions

Understanding the screening result

Here is the general shape of the screening result as returned by the GET /sessions/{sessionId}/watchlist-screening endpoint:

{
  "data": {
    "reviewStatus": "no_match | potential_match | reviewed",
    "totalHits": 0,
    "hasUnacknowledgedChanges": false,
    "hits": [ /* ... */ ]
  }
}

The reviewStatus field

The reviewStatus field is the primary outcome indicator of the AML/PEP screening. It directly answers the compliance question "Is this person flagged on any watchlist, and has that flag been resolved?"

Note that in the GET /sessions/{sessionId}/watchlist-screening endpoint's response, this field is nested inside a data object (data.reviewStatus); in the watchlist-screening webhook payload, it appears at the top level, without the wrapper.

The field has three possible values:

• no_match: the person was not found in any of the configured lists/databases. The hits array is empty.

• potential_match: the person was found in one or more listings/databases, and at least one hit has not been reviewed yet. The hits array is populated with data about the person.

• reviewed: the person was found, and every hit has a review decision recorded. This is not permanent: if ongoing monitoring later detects a change, reviewStatus reverts to potential_match until you acknowledge the change and review any new hits (see Managing screening results below).

Deprecated: the matchStatus field (possible_match / no_match) is deprecated. Use reviewStatus instead.

totalHits shows the total number of hits returned by the check.

Each entry in hits also includes:

• id: unique identifier of the hit. Use it to submit a review decision via the PATCH endpoint, see Managing screening results below.

• matchStatus: the review decision for that specific hit, one of false_positive, potential_match (default until reviewed), true_match, inconclusive.

• riskLevel: risk assessment for the hit, one of low, high. Present only when the hit's matchStatus is true_match.

hasUnacknowledgedChanges indicates whether ongoing monitoring has produced changes you have not yet acknowledged, see Managing screening results below.

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

The confidence in the screening result 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. Its structure is different from the hits array documented above, see the GET /sessions/{sessionId}/person reference for the field list.

Possible session outcomes

Session approved + reviewStatus: 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.

{
  "data": {
    "reviewStatus": "no_match",
    "totalHits": 0,
    "hasUnacknowledgedChanges": false,
    "hits": []
  }
}

Session approved + reviewStatus: potential_match

The end-user's identity is verified (the document and selfie are genuine), but they were found on one or more watchlists, and at least one hit has not been reviewed yet. 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.), including each hit's id.

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

• Submit your review decision for each hit via the PATCH endpoint, see Managing screening results below.

{
  "data": {
    "attemptId": "54233318-f81c-4ec4-8e4c-413168a3f5e6",
    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "checkType": "initial_result",
    "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"
            }
          ]
        }
      }
    ]
  }
}

Session approved + reviewStatus: reviewed

This state only tells you that every hit already has a review decision. It does not tell you what that decision was. Unlike no_match, a reviewed session is not automatically "clean": always check the per-hit outcome before proceeding.

Check the per-hit matchStatus (and riskLevel, where present) in the hits array to see the actual outcome of each review:

• If every hit was reviewed as false_positive, no further AML action is needed.

• If any hit was reviewed as true_match, apply your own risk-based decision depending on your regulation and requirements (decline the end-user, apply enhanced due diligence, or escalate), informed by that hit's riskLevel.

• If a hit was reviewed as inconclusive, make a risk-based decision in line with your own policy and regulatory obligations about what additional verification is needed to determine whether this is a true match.

• If the hit it still shows potential_match after review, then the hit has not yet received a conclusive review. Treat it as unresolved until it moves to one of the statuses above.

reviewed is also 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 below.

{
  "data": {
    "reviewStatus": "reviewed",
    "hits": [
      {
        "id": "4KJL9THDX9ZNV4W",
        "matchStatus": "true_match",
        "riskLevel": "high"
      }
    ]
  }
}

Find decision and/or session related info

You can get the data from three sources:

• Receive the webhook. The webhook is different, depending on whether you are using the AML solution with or without an IDV integration

• Poll the results via GET /sessions/{sessionId}/watchlist-screening API endpoint

• View the session in Veriff Customer Portal > All Verifications > session > Webhooks tab

Webhook payload

API call response payload

You can use the GET /sessions/{sessionId}/watchlist-screening endpoint, which contains the same data as the watchlist-screening webhook, wrapped inside a data object (see The reviewStatus field field above).

Screening can take a few seconds to minutes to complete after session submission, so the endpoint can return:

• 200: screening results are ready, either matches were found or not

• 202: screening is still in progress. Wait a few seconds and retry the request

• 402: PEP & Sanctions screening is not enabled for your integration. Contact your Solutions Engineer

Veriff Customer Portal

You can find the verification session related info, including the decision, in the Veriff Customer Portal, under the Verifications tab.

Status and reason codes

For an approved session, see the verification.code and verification.status parameters.

If the session was declined or resubmission_requested, you can find additional information by checking the verification.status, verification.code, verification.reason and verification.reasonCode data objects.

For more info about the codes you are seeing, refer to:

• Verification session status codes (table)

• Verification session decision codes (table)

• Granular reason codes (table)

Managing screening results

Use the PATCH /sessions/{sessionId}/watchlist-screening endpoint to record a review decision on a hit, acknowledge monitoring changes, or disable ongoing monitoring for a specific end-user, identified by sessionId.

These three operations are mutually exclusive per request. Each request must contain exactly one of hit, hasUnacknowledgedChanges, or monitorStatus. To perform more than one, send separate requests. Sending more than one field in the same request results in a 400 error.

Review a hit

Submit your review decision for a specific hit in the hits array:

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

• hit.id: the hit's id, from the GET /sessions/{sessionId}/watchlist-screening response.

• hit.matchStatus: your review decision, one of false_positive, potential_match (default until reviewed), true_match, inconclusive.

• optional hit.riskLevel: only accepted when matchStatus is true_match, one of low, high. Must not be sent for any other matchStatus value.

A hit's matchStatus can be changed at any time; there is no restriction on which transitions are allowed, for example from true_match back to false_positive if you need to revise an earlier decision.

Once every hit in the hits array has a review decision, reviewStatus changes to reviewed, and Veriff sends an updated watchlist-screening webhook to reflect this.

If ongoing monitoring later detects a change, hasUnacknowledgedChanges becomes true again and reviewStatus reverts to potential_match, even if every hit was previously reviewed. Acknowledge the change and review any new hits to return to reviewed.

Acknowledge monitoring changes

If ongoing monitoring detects a change, hasUnacknowledgedChanges becomes true. Acknowledge it with:

{
  "hasUnacknowledgedChanges": false
}

Only the value false is accepted.

Disable monitoring

1. If unsure whether monitoring is enabled, check the monitorStatus parameter in the GET sessionId/watchlist-screening response payload.

2. If monitorStatus is enabled or empty, set it to disabled using the PATCH /sessions/{sessionId}/watchlist-screening endpoint:

   {
     "monitorStatus": "disabled"
   }
   

   If monitoring is already disabled, the endpoint returns a 400 error:

   {
     "status": "fail",
     "message": "Watchlist screening is already disabled"
   }
   

3. If you wish to re-enable ongoing monitoring for an end-user, contact your Solutions Engineer.

All three operations require endpoint-level HMAC signature authentication.

FAQ

Additional info

→ Log in to your Veriff account to see the PEP, Sanctions, Watchlists, and Adverse Media & Information checks[↗] article in Veriff Knowledge Base for more information about the Anti-Money Laundering solutions

→ Log in to your Veriff account to see What is PEP?[↗] article in Veriff Knowledge Base for more detailed insight into Politically Exposed Persons

Changelog