Run an Individual screening
This developer guide takes you through the steps to run an Individual 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 available from your data provider, persons on a watchlist or internal watchlist, and instances of adverse media.
The Individual screening check can be run on the following task:
Assess PEPs, sanctions, and adverse media (
INDIVIDUAL_ASSESS_MEDIA_AND_POLITICAL_AND_SANCTIONS_EXPOSURE)
Choose a profile and get the profile ID
Individual 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, for example, 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 profile yet, follow the steps to create a profile using 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 /profiles/ 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": "202-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:
personal_details.given_names: The individual's first and, if applicable, middle names.personal_details.family_name: The individual's surname.
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.
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".
Run the Individual screening check
To run the Individual screening check, send a request to the following endpoint.
Request endpoint:
POST https://api.passfort.com/4.0/profiles/{profile_id}/checksBy default, the Individual screening check runs asynchronously. You can also 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 |
*Required string |
| The type of check that's being run. |
*Required Object | For a sample value, see the following sample request body. | Object to indicate which variant of the check will run. |
*Required string This key is optional if | Sample value:
| The check variant alias. |
Optional string This key is required if | Sample value:
| The unique identifier for the check variant. |
In the following example, we'll run the check.
Sample request body:
{
"check_type": "INDIVIDUAL_SCREENING",
"variant": {
"alias": "screening_individuals"
}
}Sample response:
{
"check_type": "INDIVIDUAL_SCREENING",
"disable_initial_screen": false,
"disable_monitoring": false,
"id": "66680144-df95-4953-bd25-57c3e5ca76a3",
"instructed_on": "2024-06-18 09:50:21",
"performed_on": "2024-06-18 09:50:21",
"providers": [],
"state": "PENDING",
"task_ids": [
"d6595d5e-37a5-4e01-9e4a-5e2b37fc05b1"
],
"variant": {
"id": "92387e8b-55f9-4f07-b097-5b888e874cb2",
"name": "Individual Screening"
}
}Take note of the check id in the response because you'll need it for the next steps to get the check result.
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 Individual screening.
Payloads from this webhook have several important keys:
secret: Authenticate the request by ensuring this secret matches your secret.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.data.check.check_type: The type of check that was run. When the Individual screening was run, the value will beINDIVIDUAL_SCREENING.data.check.result: The result of the check. Possible results for the Individual screening arePass,PEP,Sanction,Media,Refer,Watchlist,Internal Watchlist, orError. To learn what causes these check results, see the description for the Individual screening result.
In this example, the Individual screening check discovered at least one Sanction result for the individual.
Sample payload:
{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "CHECK_COMPLETED",
"secret": "yourSecret",
"timestamp": 1620300390,
"data": {
"check": {
"check_type": "INDIVIDUAL_SCREENING",
"id": "ea565b55-47d9-1858-4588-3a22a3838707",
"result": "Sanction",
"variant": {
"alias": "screening_individuals",
"id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
"name": "Individual 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.
Get more information about the check result
If you want to get more information about the check result, make a call to the following endpoint.
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": "INDIVIDUAL_SCREENING",
"completed_on": "2024-06-17 12:43:35",
"errors": [],
"id": "b7700dfb-ee32-4eb9-a28c-5748a762f13c",
"instructed_on": "2024-06-17 12:43:16",
"performed_on": "2024-06-17 12:43:35",
"providers": [
{
"instructed_on": "2024-06-17 12:43:17",
"provider_name": "Moody's Screening",
"variant_name": "Custom Individual Screening",
"primary": false
}
],
"started_on": "2024-06-17 12:43:16",
"state": "COMPLETE",
"task_ids": [
"d6595d5e-37a5-4e01-9e4a-5e2b37fc05b1"
],
"variant": {
"id": "92387e8b-55f9-4f07-b097-5b888e874cb2",
"name": "Individual Screening"
},
"result": "Sanction",
"decision": "FAIL",
"input_data": {
"entity_type": "INDIVIDUAL",
"personal_details": {
"name": {
"family_name": "Wheeler",
"given_names": [
"Alex"
]
}
}
},
"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.
See the latest matches
If you want to see the latest PEPs, sanctions, watchlist, internal watchlist, and adverse media matches an individual has, make a call to the following endpoint. In the API, matches are called events.
GET https://api.passfort.com/4.0/profiles/{profile_id}/checks/{check_id}/snapshots/latestIn this example, the individual has five matches.
Sample response:
{
"id": "08aa32da-6c23-4b90-aeda-d24ff34800ae",
"result": {
"decision": "FAIL"
},
"output_data": {
"entity_type": "INDIVIDUAL",
"screening_hits": [
{
"data": {
"confidence_score": 0.73,
"countries": [
{
"country": "GBR",
"type": "NATIONALITY"
}
],
"name": "Alexei Wheeler"
},
"flags": [
{
"detail_code": "DPP",
"id": "558e0c68-277b-5f49-a2d2-642e2ac1d502",
"ref": "F0001",
"source": {
"description": "Country A's Data Regulation Authority",
"name": "Data Regulator"
},
"stage": {
"date": "2019-08-29",
"stage_code": "FIM"
},
"type": "REFER"
}
],
"id": "fce9527e-6f04-5736-b2fe-81820b81d6d0",
"provider": {
"hit_id": "12345-A",
"label": "screening-ref",
"name": "Moody's Screening"
}
},
{
"data": {
"confidence_score": 0.36,
"countries": [
{
"country": "GBR",
"type": "NATIONALITY"
}
],
"name": "Alex John Wheeler",
"pep": {
"rating": "A",
"roles": [
{
"name": "Prime Minister",
"pep_classification_code": "HOS",
"tenure": {
"tenure_type": "CURRENT",
"start": "2018-07-22"
},
"tier": 1
},
{
"name": "Prime Minister",
"pep_classification_code": "LEG",
"tenure": {
"tenure_type": "FORMER",
"end": "2018-07-22",
"start": "2016-07-22"
},
"tier": 2
}
],
"tier": 1
}
},
"flags": [
{
"detail_code": "PEP",
"id": "beb6e0e6-8dfc-51a5-963a-78b06466af7d",
"ref": "F0002",
"source": {
"description": "A list of PEPs",
"name": "PEP List 1"
},
"stage": {
"date": "2019-08-29",
"stage_code": "ASC"
},
"type": "PEP"
}
],
"id": "90cae7a8-441c-5035-8bef-7c9c3085c460",
"provider": {
"hit_id": "12345-B",
"label": "screening-ref",
"name": "Moody's Screening"
}
},
{
"data": {
"confidence_score": 0.92,
"countries": [
{
"country": "USA",
"type": "NATIONALITY"
}
],
"media": [
{
"date": "2020-08-29",
"snippet": "https://www.thegardian.com/politics/2020/jun/24/minister-resigns",
"title": "Minister resigns after local voting",
"flag_ref": "F0004"
}
],
"name": "Alex Weeler"
},
"flags": [
{
"detail_code": "WLT",
"id": "f8803ac9-bea0-5f3e-8115-71a8b31b057c",
"ref": "F0003",
"source": {
"description": "List of UK Sanctioned entities",
"name": "UK HM Treasury Financial Sanctions Target List"
},
"stage": {
"date": "2019-08-29",
"stage_code": "SAN"
},
"type": "SANCTION"
},
{
"detail_code": "MIS",
"id": "e42a5f2c-9a62-5a6f-8b7b-26109072951c",
"ref": "F0004",
"source": {
"description": "Media Organisation A",
"name": "Media Org A"
},
"stage": {
"date": "2019-08-29",
"stage_code": "ALL"
},
"type": "ADVERSE_MEDIA"
}
],
"id": "b6b0c8f5-b28d-51d3-b6cd-7ca4286607ea",
"provider": {
"hit_id": "12345-C",
"label": "screening-ref",
"name": "Moody's Screening"
}
},
{
"data": {
"confidence_score": 0.85,
"countries": [
{
"country": "GBR",
"type": "NATIONALITY"
}
],
"name": "Andy Wheeler"
},
"flags": [
{
"id": "ca9898f9-da81-596c-be9d-328813072a3c",
"ref": "F0005",
"source": {
"description": "Customer's we don't do business with",
"name": "Example's Customer Blocklist"
},
"type": "INTERNAL_WATCHLIST"
}
],
"id": "fbf5a8d1-ba14-5763-ad35-d4f9ad089eec",
"provider": {
"hit_id": "12345-D",
"label": "screening-ref",
"name": "Moody's Screening"
}
},
{
"data": {
"confidence_score": 0.71,
"countries": [
{
"country": "CAN",
"type": "NATIONALITY"
}
],
"name": "Alice Wheeler"
},
"flags": [
{
"detail_code": "SEC",
"id": "2db76415-74e7-532d-8b89-775ad6763752",
"ref": "F0006",
"source": {
"description": "NGO's list of bad companies",
"name": "NGO Warning List",
"url": "https://www.ngo.com/12346"
},
"stage": {
"date": "2019-08-29",
"stage_code": "ARB"
},
"type": "WATCHLIST"
}
],
"id": "bd844cc2-e3d2-57b7-af41-ac8ae8f37361",
"provider": {
"hit_id": "12345-E",
"label": "screening-ref",
"name": "Moody's Screening"
}
}
]
},
"occurred_at": "2024-06-18T09:53:28Z",
"errors": [],
"warnings": [],
"external_resources": []
}
The information in the data object shows the match information returned by the data provider, including name, country of nationality, and confidence score. 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.
The response contains all the events for the profile, not just the latest results from your check.
Each of the flags objects in the response corresponds to a screening event for the match.
The flags type could be any of the following event categories:
PEP: The match is a politically exposed person (PEP).SANCTION: The match is a sanctioned person.ADVERSE_MEDIA: There is an instance of adverse media about the individual.WATCHLIST: There is a match from a government or other official watchlist.INTERNAL_WATCHLIST: There is a match from the client's own watchlist.REFER: The match does not fall into any of these categories. For example, the match has a criminal record.
Each of the flags objects may include the following additional details about the event:
detail_code: A three-letter event code to further define the event under the event category.stage_code: A three-letter stage code to indicate the event’s current phase.stage
date: The date the event changed to the current stage.
Your data provider may group adverse media matches with refer matches. For more information, see the information 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.
Monitored screening
Some data providers offer ongoing monitoring for any new matches that could be imported to the check results. 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 information for your data provider.