Run a PEPs and sanctions screening (API)

This developer guide takes you through the steps to run a PEPs and sanctions screening check in the PassFort API 4.0 to get a list of an individual's potential matches to sanctioned persons, politically exposed persons (PEPs), and (if you have access to adverse media results through your data provider) instances of adverse media.

To learn more about data provider results, see the data provider articles linked at the bottom of the description of the PEPs and sanctions screening check.
If you're using the full PassFort product, you can run this check on the following tasks: Assess PEPs and sanctions (INDIVIDUAL_ASSESS_POLITICAL_AND_SANCTIONS_EXPOSURE) and Assess PEPs, sanctions, and adverse media (INDIVIDUAL_ASSESS_MEDIA_AND_POLITICAL_AND_SANCTIONS_EXPOSURE).

1. Get the profile's ID and confirm it has the required keys and values

First, choose a profile for the check and get the profile ID (more information below).

Once you have the profile ID, you can make sure the profile has the required fields for the PEPs and sanctions screening check to run successfully (documented below).

Get the profile's ID

PEPs and sanctions screening checks are always run on profiles with the INDIVIDUAL entity type.

Choose an individual profile to run the check on, and take note of the profile's ID number (e.g. a2c4393a-e219-67a4-5ab4-2186952e9038). You'll need it to confirm it has the required fields and also to run the check later.

If you haven't created the individual's profile yet, follow the steps to create a profile via the API.
If you have access to the full PassFort product, you can also create a profile via the portal. To get the profile ID, view the profile in the portal and copy the string of letters and numbers after /onboarding/ in the URL.

Confirm the profile has the required fields for the check

To see all data on the profile, make a request to the following endpoint.

Required endpoint:

GET https://api.passfort.com/4.0/profiles/{profile_id}

In this example, data is returned for an individual profile named "Alex Wheeler". 

Sample response: 

{
    "id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
    "creation_date": "2021-06-08 11:13:43",
    "role": "INDIVIDUAL_CUSTOMER",
    "collected_data": {
        "entity_type": "INDIVIDUAL",
        "personal_details": {
            "name": {
                "family_name": "Wheeler",
                "given_names": [
                    "Alex"
                ]
            }
        }
    },
    "events": [],
    "checks": []
}

Use the response to:

Confirm the profile has data for these required keys, which are in the collected_data object:

  1. personal_details.given_names: The individual's first name.
  2. personal_details.family_name: The individual's last name.

If the required fields do not exist on the profile or do not contain valid data, the check will return an error when you try to run it.

To learn how to add/update the fields in the profile's collected_data, see Update PassFort's profile data.

To learn which optional profile fields can be used for this check, see the article for your data provider: ComplyAdvantage, Dow Jones Risk and Compliance, Refinitiv World-Check One, and RDC.

If you're using the full PassFort product, you should also take this opportunity to confirm the profile has the tasks you want to run the check on and note the task ID (tasks.id). Use the corresponding task alias (tasks.variant.alias) to confirm you're looking at the right task. If there is more than one task with the same alias (which happens when a task has more than one version), use the task with "is_expired": "false".

2. Run the check

Sending the request

To run the check, make a request to the endpoint below.

Request endpoint: 

POST https://api.passfort.com/4.0/profiles/{profile_id}/checks

By default, the PEPs and sanctions screening runs asynchronously. You can send mode as a query parameter to run the check synchronously.

Body parameters:

When you make the POST request, include the following parameters in the body.

Key

Value

Description

check_type

Required

String

PEPS_AND_SANCTIONS_SCREEN

The type of check that's being run.

variant

Required

Object

For a sample value, see the sample request body below.

Object to indicate which variant of the check will run.

variant.alias

Required

String

This key is optional if variant.id is provided. We recommend sending the alias whenever possible.

Sample value:

screening_individuals

The check variant alias.

variant.id

Optional

String

This key is required if variant.alias is not provided.

Sample value:

ea70ade9-3de3-1785-203b-68044cd3ecbb

The unique identifier for the check variant.

In the example below, we'll run the check.

Sample request body:

{
    "check_type": "PEPS_AND_SANCTIONS_SCREEN",
    "variant": {
        "alias": "screening_individuals"
    }
}

Sample response: 

{
    "check_type": "PEPS_AND_SANCTIONS_SCREEN",
    "id": "ea565b55-47d9-1858-4588-3a22a3838707",
    "instructed_on": "2021-06-08 11:13:43",
    "performed_on": "2021-06-08 11:13:43",
    "providers": [],
    "state": "PENDING",
    "task_ids": [],
    "variant": {
        "alias": "screening_individuals",
        "id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
        "name": "PEPs, sanctions, and adverse media screening"
    },
    "disable_initial_screen": false,
    "disable_monitoring": false
}

Take note of the check id in the response because you'll need it for the next steps to get the check result.

If you're using the full PassFort product, you should also include the task_ids in the request to indicate which task(s) the check should run on. If you don't provide a task_ids, the check will run on whichever applicable task(s) the profile has.
Because this check runs asynchronously, the check state is expected to be PENDING in the response.

Get the check result

Listen to the Check completed webhook to get a notification when the check is finished running and to learn what the result is.

This webhook sends a payload whenever results are returned from any check (including checks other than the PEPs and sanctions screening).

Payloads from this webhook have several important keys:

  1. secret: Authenticate the request by ensuring this secret matches your secret.
  2. id: The check ID. Use it to confirm the payload is for your check by matching it to the check ID you captured when you ran the check.
  3. data.check.check_type: The type of check that was run. When the PEPs and sanctions screening was run, the value will be PEPS_AND_SANCTIONS_SCREEN.
  4. data.check.result: The result of the check. Possible results for the PEPs and sanctions screening are Pass, PEP, Sanction, Media, Refer, or Error. To learn what causes these check results, see the description for the PEPs and sanctions screening result.

In this example, the PEPs and sanctions screening discovered at least one PEP result for the individual.

Sample payload:

{
    "id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
    "event": "CHECK_COMPLETED",
    "secret": "yourSecret",
    "timestamp": 1620300390,
    "data": {
        "check": {
            "check_type": "PEPS_AND_SANCTIONS_SCREEN",
            "id": "ea565b55-47d9-1858-4588-3a22a3838707",
            "result": "PEP",
            "variant": {
                "alias": "screening_individuals",
                "id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
                "name": "PEPs, sanctions, and adverse media screening"
            } 
        },
        "customer_ref": null,
        "profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
    }
}

See Get more information about the check result to learn which data was sent to the data provider and which data provider was used.

Get more information about the check result

If you want to get more information about the check result, make a call to the endpoint below.

In the request body, include the profile ID and the check ID.

Request endpoint:

GET https://api.passfort.com/4.0/profiles/{profile_id}/checks/{check_id}

Sample response:

{
    "check_type": "PEPS_AND_SANCTIONS_SCREEN",
    "completed_on": "2021-06-08 11:18:01",
    "errors": [ ],
    "id": "ea565b55-47d9-1858-4588-3a22a3838707",
    "instructed_on": "2021-06-08 11:13:43",
    "performed_on": "2021-06-08 11:13:43",
    "providers": [
        {
            "instructed_on": "2021-06-08 11:13:43",
            "is_monitored": false,
            "provider_name": "ComplyAdvantage",
            "variant_name": "complyadvantage"
        }
    ],
    "started_on": "2021-06-08 11:13:43",
    "state": "COMPLETE",
    "task_ids": [ ],
    "variant": {
        "alias": "screening_individuals",
        "id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
        "name": "Screening"
    },
    "result": "PEP",
    "decision": "WARN",
    "input_data": {
        "entity_type": "INDIVIDUAL",
        "personal_details": {
            "name": {
                "family_name": "Alex",
                "given_names": [
                    "Wheeler"
                ]
            }
        }
    },
    "output_data": {
        "entity_type": "INDIVIDUAL"
    },
    "disable_initial_screen": false,
    "disable_monitoring": false
}

Use the response to see:

  • input_data: Shows which information about the individual was sent to the data provider.
  • providers: Shows which data provider was used to run the check.

3. See and update matches

See PEPs, sanctions, and adverse media matches

If you want to learn which PEPs, sanctions, and (if your data provider shows them) which adverse media matches an individual has, make a call to the endpoint below. In the API, matches are called events.

POST https://api.passfort.com/4.0/profiles/{profile_id}/events

In this example, the individual has one PEPs match and one adverse media match.

Sample response: 

[
    {
        "creation_date": "2021-06-08 11:18:01",
        "data": {
            "event_type": "PEP_FLAG",
            "aliases": [
                "Alex Wheeler",
                "Alexa Wheeler",
                "Darcy Wheeler"
            ],
            "associates": [
                {
                    "name": "Aaron Wheeler"
                },
                {
                    "name": "Hunter Sagal"
                }
            ],
            "deceased": true,
            "deceased_dates": [ … ],
            "details": [ … ],
            "match_dates": [ … ],
            "match_id": "F0WGP81952TJM5T",
            "match_name": "Alexandra Darcy Wheeler",
            "pep": {
                "match": true,
                "tier": 1
            },
            "provider_name": "Comply Advantage",
            "sources": [
                {
                    "name": "ComplyAdvantage PEP Data",
                    "url": "http://www.complyadvantage.com/"
                },
                { … }
            ]
        },
        "id": "c78b29ee-a324-4e74-8917-1a703f00eba4",
        "resolution": "UNRESOLVED"
    },
    {
        "creation_date": "2021-06-08 11:18:01",
        "data": {
            "event_type": "ADVERSE_MEDIA_FLAG",
            "aliases": [
                "Alex Wheeler",
                "Alexa Wheeler",
                "Darcy Wheeler"
            ],
            "associates": [
                {
                    "name": "Aaron Wheeler"
                },
                {
                    "name": "Hunter Sagal"
                }
            ],
            "deceased": true,
            "deceased_dates": [ … ],
            "details": [ … ],
            "match_dates": [ … ],
            "match_id": "F0WGP81952TJM5T",
            "match_name": "Alexander Darcy Wheeler",
            "media": [
                {
                    "date": "2018-10-27",
                    "snippet": "These measures were met by large protests. In 1994 he fulfilled his campaign promise and gave amnesty to Wheeler, who was in prison following her failed 1992 military rebellion. Evans retired from politics in his last years due to poor health caused by Parkinson's disease, and died on 24 December aged 93.",
                    "title": "Ex President Sandi Evans Dies | Example.com",
                    "url": "http://example.com/news/5036?utm_source=NET%20NEWS%20GLOBAL&quicktabs_2=0"
                },
                { … },
                { … }
            ],
            "provider_name": "Comply Advantage",
            "sources": [
                {
                    "name": "ComplyAdvantage PEP Data",
                    "url": "http://www.complyadvantage.com/"
                },
                { … }
            ]
        },
        "id": "033abcd3-33be-4166-9749-aee93b4c85e8",
        "resolution": "UNRESOLVED"
    }
]

Each object in the response corresponds to a PEPs, sanctions, or adverse media event. 

These are all the events for the profile, not just the latest results from your check. Use the creation_date to see which events were created recently and the event_type to find the events that are relevant to you. 

The event_type could be any of the following:

  • PEP_FLAG: The match is a politically exposed person (PEP).
  • SANCTION_FLAG: The match is a sanctioned person.
  • ADVERSE_MEDIA_FLAG: There is an instance of adverse media about the individual.
  • REFER_FLAG: The match does not fall into any of the categories above. For example, the match has a criminal record.
Your data provider may group adverse media matches with refer matches. For more information, see the article for your data provider.

The data provider returns potential matches, and it's up to you to decide if these are true matches to the profile or if they should be ignored. The event's resolution shows whether the event is:

  • UNRESOLVED: This is a potential match for the individual.
  • MATCH: The match is confirmed for the individual. 
  • MISMATCH: The match does not correspond to the individual. This can happen when a user ignores the match via the Portal, when the match is updated as a mismatch via the API, or when PassFort marks the match as a false positive.
IGNORE and CREATED_TASK are not used for the PEPs and sanctions screening.

The information in the data object shows all the match information returned by the data provider. For example, it could show the aliases used by the match (aliases), the associates of the match (associates), or the sources used to get the information about the match (sources). This information should help you make your decision about whether the match is a true match to the individual or whether it should be ignored.

For a list of all the possible fields that can be returned in the data object, see the response for Get a list of profile events in the Full PassFort API reference or the PassFort Connect API reference.

Update PEPs, sanctions, and adverse media matches

Once you've used the information in the data object to determine whether the match is a true match to the individual or whether it should be ignored, you can update the event with the new resolution.

To update the event, send the new resolution to the endpoint below. The resolution can be one of the following:

  • MATCH: The match is confirmed as a true match to the individual.
  • MISMATCH: The match does not correspond to the individual.
To learn more about the other resolution options, see the steps above.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/events/{event_id}

In this example we'll update the match for Alexandra Darcy Wheeler to be a true match to the individual.

Sample request body:

{
     "resolution": "MATCH"
}

Sample response:

{
     "creation_date": "2021-06-08 11:18:01",
     "data": {
         "event_type": "PEP_FLAG",
         "aliases": [ … ],
         "associates": [ … ],
         "deceased": true,
         "deceased_dates": [ … ],
         "details": [ … ],
         "match_dates": [ … ],
         "match_id": "F0WGP81952TJM5T",
         "match_name": "Alexandra Darcy Wheeler",
         "pep": { … },
         "provider_name": "Comply Advantage",
         "sources": [ … ]
     },
     "id": "c78b29ee-a324-4e74-8917-1a703f00eba4",
     "resolution": "MATCH"
}

Ongoing monitoring

Some data providers offer ongoing monitoring for the PEPs and sanctions screening. This means that after the check has been run the first time, the profile is monitored for any new matches that could be imported to the check results.

To find out how to enable ongoing monitoring in the Policy Builder, see the article for your data provider.

To update the profile with any new matches that your data provider discovers, first ensure you're listening to the Events created webhook.

Your data provider may also update a match. For example, if the match's job changes, the data provider may update their status. To handle any updated matches that your data provider discovers, ensure you're listening to the Events updated webhook.

You can choose which webhooks to listen to by logging into the Portal following these steps

After this:

  1. If the data provider discovers new matches for the profile, the Events created webhook will be fired. If the data provider discovers updated matches for the profile, the Events updated webhook will be fired. Either webhook will have one of these values for the event_type: PEP_FLAG, SANCTION_FLAG, ADVERSE_MEDIA_FLAG, or REFER_FLAG. You can see sample payloads in the API Resources.
  2. When you receive the payload, take note of the profile_id to learn which profile is impacted and events.id to get the ID of the new event.
  3. Make a call to the following endpoint to get the details of the event: POST https://api.passfort.com/4.0/profiles/{profile_id}/events/{event_id}
  4. Follow the steps above to update the match resolution to indicate whether it's a true match or a mismatch.
The Events updated webhook also fires when you update the resolution of a match. Make sure you only act on the payload when it shows that the data returned does not match an event you've just updated. 
It's important to look at the event_type in the payload because the Events created and Events updated webhooks fire for any check type with ongoing monitoring (including checks other than the PEPs and sanctions screening). 


How did we do?


Powered by HelpDocs (opens in a new tab)