Returns PEP (Politically Exposed Person) and Sanctions screening results for a verification session
When to use this endpoint
Use this endpoint to retrieve comprehensive PEP and Sanctions screening result, including match details, confidence scores and source database information after a verification session has been completed.
Common use cases include:
- Accessing screening results for compliance and AML (Anti-Money Laundering) purposes
- Investigating potential PEP or sanctions matches flagged during verification
- Obtaining provider-specific match data including match confidence and source information
- Conducting enhanced due diligence based on screening results
- Retrieving ongoing monitoring status for the session
Response data
The response includes screening results such as match status, search parameters used, and detailed hit information when matches are found.
Key data returned:
matchStatus: indicates if matches were found (possible_matchorno_match)monitorStatus: shows if ongoing monitoring is enabled or disabled for this sessionsearchTerm: shows the exact search parameters used (name, year, lists checked, match threshold)totalHits: number of records matched in PEP and Sanctions databaseshits: array of detailed match data including matched names, countries, dates, match types, and related listings
If no matches are found in PEP or Sanctions databases, the
hitsarray will be empty andmatchStatuswill beno_match.For
matchTypes, see the data provider's documentation for more detailed info.
Screening availability
Screening timing: Results are typically available within seconds to minutes after session completion, depending on:
- Session submission and processing time
- Provider database response times
- Complexity of search parameters
Response status codes:
200= Screening results ready (either matches found or no matches)202= Screening still in progress, results not yet available402= PEP & Sanctions screening is not enabled for your integration- If you receive a
202response, wait a few seconds and retry the request.
Implementation notes
- This endpoint requires session-level HMAC signature authentication
- PEP & Sanctions screening must be enabled for your integration to receive results
- The
checkTypefield indicates if this is theinitial_resultor anupdated_resultfrom ongoing monitoring - Handle both
possible_matchandno_matchscenarios in your implementation - Always ensure that you use the correct API URL to send requests. See the API URL section for more info
- The order of parameters in the real API response can differ from the order you see in this documentation. This is expected and part of the Backwards compatible changes requirements
Your integration's API key (occasionally referred to as the "Token", "API public key" or "Publishable key"). Required for all API requests.
You can find your API key in the Veriff Customer Portal > Settings > API keys.
Session ID signed with the shared secret key. Required to authenticate the request sender.
Verification session ID.
Watchlist screening data
Example showing a possible match in PEP databases with detailed hit information
{
"status": "success",
"data": {
"attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
"sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
"vendorData": "customer_ref_12345",
"endUserId": "c1de400b-1877-4284-8494-071d37916197",
"checkType": "initial_result",
"matchStatus": "possible_match",
"monitorStatus": "enabled",
"searchTerm": {
"name": "GADDAFI",
"year": "1942",
"lists": [
"SANCTIONS",
"PEP_CLASS_1",
"PEP_CLASS_2"
],
"countries": [
"US",
"GB",
"FR"
],
"exactMatch": false,
"matchThreshold": 80,
"excludeDeceased": true
},
"totalHits": 1,
"createdAt": "2021-07-05T13:23:59.851Z",
"hits": [
{
"matchedName": "Mouammar Mohammed Abu Minyar Kadhafi",
"countries": [
"Libya",
"US"
],
"dateOfBirth": "1942",
"dateOfDeath": "2011",
"matchTypes": [
"matching_name"
],
"aka": [
"Moammar Qaddafi",
"Muammar Gaddafi"
],
"associates": [
"Saif al-Islam Gaddafi"
],
"listingsRelatedToMatch": {
"warnings": [],
"sanctions": [
{
"sourceName": "UN Security Council Sanctions",
"sourceUrl": "https://www.un.org/securitycouncil/sanctions",
"date": "2011-02-26"
}
],
"fitnessProbity": [],
"pep": [
{
"sourceName": "ComplyAdvantage PEP data",
"sourceUrl": null,
"date": null
}
],
"adverseMedia": [
{
"sourceName": "International Media Coverage",
"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": null,
"date": "2011-03-15"
}
]
}
}
]
}
}Example showing screening completed with no matches in any databases
{
"status": "success",
"data": {
"attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
"sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
"vendorData": "customer_ref_12345",
"endUserId": "c1de400b-1877-4284-8494-071d37916197",
"checkType": "initial_result",
"matchStatus": "no_match",
"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": []
}
}Example showing an updated result from ongoing monitoring after initial screening
{
"status": "success",
"data": {
"attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
"sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
"vendorData": "customer_ref_12345",
"endUserId": "c1de400b-1877-4284-8494-071d37916197",
"checkType": "updated_result",
"matchStatus": "possible_match",
"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": [
{
"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": "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": null,
"date": "2021-07-10"
}
]
}
}
]
}
}API request status.
Data containing PEP & Sanctions result details.
UUID v4 which identifies session attempt.
UUID v4 which identifies session.
The unique identifier that you created for your end-user. It can be max 1,000 characters long and contain only non-semantic data that can not be resolved or used outside your systems or environments. Veriff returns it unmodified in webhooks and API response payloads, or as null if not provided.
End-user-specific UUID created by the customer to identify the end-user. Returned unmodified in webhooks and public API calls, or as null if not provided.
Indicates if the response is for the initial check or a subsequent check. Relevant only if ongoing-monitoring has been enabled for your integration.
Indicates if there was a match in the database.
Indicates if monitoring is enabled or disabled for this session, or empty if status is unknown.
Data used to perform the check.
Full name used during the check.
Birth year used during the check.
List of watchlists against which the check was performed.
List of countries associated with the check.
Indicates whether the name used in the check required an exact match.
Configured matching percentage threshold.
Indicates whether deceased individuals were excluded from the check.
Total number of hits returned from the check.
Timestamp indicating when the check response was received.
As combined ISO 8601 date and time in UTC, YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset|Z
Array of records that were matched. Empty array if no hits were found.
The name that was matched in this hit based on the search term.
List of countries that the sources listed in relation to this hit.
Birth date of the person in the matched listings.
Death date of the person in the matched listings.
Array that shows the match type in the listings.
See the data provider's documentation for more detailed info.
Array of names that the matched person is also known as.
Array of names that the matched person is associated with.
Matched listings. Empty object if addon "PEP & Sanctions check" is not enabled.
Array of warning-related listings.
Source name of the related listing.
Source URL of the related listing.
Date of the related listing.
Array of sanctions-related listings.
Source name of the related listing.
Source URL of the related listing.
Date of the related listing.
Array of fitness and probity-related listings.
Source name of the related listing.
Source URL of the related listing.
Date of the related listing.
Array of PEP-related listings.
Source name of the related listing.
Source URL of the related listing.
Date of the related listing.
Array of adverse media-related listings.
Source name of the related listing.
Text snippet from the source listing.
Source URL of the related listing.
Date of the related listing.
Watchlist screening is in progress
{
"status": "pending",
"tracking": "https://example-base-url/v1/sessions/f04bdb47-d3be-4b28-b028-a652feb060b5/watchlist-screening"
}API request status.
Tracking URL to check screening progress.
Bad request
Unauthorized
PEP & Sanctions screening is not enabled for your integration
Session not found
Internal server error
Changelog
Date | Description |
|---|---|
Mar 9, 2026 | Documentation updated: parent categories rearranged, intro section expanded, request and response examples added |
Feb 16, 2026 | - "Article versioning" renamed to "Changelog" |
Feb 2, 2026 |
|
Jan 9, 2026 |
|
Oct 2, 2025 |
|
Aug 6, 2025 | Response headers added |
Mar 12, 2025 | Documentation published |