Returns information objects about a person associated with the specific session ID
When to use this endpoint
Use this endpoint to retrieve comprehensive information about a person
Common use cases include:
- Accessing person's data for record-keeping or compliance purposes
- Investigating potential PEP or sanctions matches flagged during verification (for example, when using Veriff's AML screening solution)
- Obtaining provider-specific match data including match confidence, source information, and associated records
- Conducting enhanced due diligence based on screening results
Response data
The response can include person data such as name, date of birth, nationality, and identification number, that have been extracted or input via initData.
When PEP or sanctions matches are found, the
pepSanctionMatchesarray contains detailed match information from screening providers including:- Match confidence and match types
- Source databases and listings
- Associated persons and alternative names
- Media references and supporting documentation
If no matches are found in PEP or sanctions databases, the
pepSanctionMatchesarray will be empty.
Note about "matchTypes", "matchTypeDetails" and "score" fields
- Match results include
matchTypes,matchTypesDetails, andscorefields that indicate why and how strongly a match occurred.- These values are provided by the screening data provider and reflect their matching algorithms and confidence calculations. Veriff returns this data as provided by the screening provider without modification.
- For
matchTypes, see the data provider's documentation for more detailed info.- It returns the first value that is true from the following values:
name_exact,aka_exact,name_fuzzy,aka_fuzzy,phonetic_name,phonetic_aka,equivalent_name,equivalent_aka,unknown. - If appropriate, the secondary match type is returned:
year_of_birth,removed_personal_title,removed_personal_suffix,removed_organisation_prefix,removed_organisation_suffix,removed_clerical_mark.
- It returns the first value that is true from the following values:
- For
matchTypeDetails, see the data provider's documentation for more detailed info.- The
matchTypeDetailsfield contains a detailed breakdown of why a hit occurred. For every name you matched on an entity, it will indicate how each term from your search matched it, as well other information about that name.
- The
- The
scorefield gives a relative indication of match relevance as calculated by the data provider, not an absolute ranking. For more information see the entry in the API FAQ article.
Null and missing fields
Fields may be
null, empty, or omitted depending on integration configuration and data availability:null= field is included in payload but has no value (data unavailable, feature disabled, or verification declined/expired)- Empty (
{}or[]) = field is included but returned no data (feature enabled but no results) - Omitted = field not part of payload (integration configuration or no results returned)
Always check field existence and
nullvalues before processing.
Implementation notes
- Always ensure that you use the correct API URL to send requests. See the API URL section for more info.
- This endpoint requires session-level HMAC signature authentication
- Person data is only available after the verification session has been submitted
- The
pepSanctionMatchesarray is populated only when AML screening has been enabled for your integration and matches are found - Handle
nullvalues gracefully - 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.
Person data
Person data with no PEP or sanctions matches
Response when person data is available but no matches were found in PEP or sanctions databases
{
"status": "success",
"person": {
"id": "b00a203e-2524-4ded-867b-b4e281a2c96b",
"firstName": "MUAMMAR GADDAFI",
"lastName": null,
"idCode": "062.449.269-94",
"dateOfBirth": "1942-09-22T00:00:00Z",
"gender": "M",
"nationality": "LY",
"placeOfBirth": null,
"citizenships": null,
"pepSanctionMatches": []
}
}Person data with PEP match found
Response showing complete PEP match structure including provider data, match details, sources, and associated information
{
"status": "success",
"person": {
"id": "b00a203e-2524-4ded-867b-b4e281a2c96b",
"firstName": "MUAMMAR GADDAFI",
"lastName": null,
"idCode": "062.449.269-94",
"dateOfBirth": "1942-09-22T00:00:00Z",
"gender": "M",
"nationality": "LY",
"placeOfBirth": null,
"citizenships": null,
"pepSanctionMatches": [
{
"provider": "Comply Advantage",
"numberOfMatches": 1,
"date": "2018-04-18T11:02:05.261Z",
"matches": [
{
"name": "Mouammar Mohammed Abu Minyar Kadhafi",
"nationality": "LIBYAN",
"category": "PEP"
}
],
"hits": [
{
"doc": {
"id": "4KJL9THDX9ZNV4W",
"lastUpdatedUtc": "2018-04-18T11:02:05.261Z",
"createdUtc": "2018-04-18T11:02:05.261Z",
"fields": [
{
"name": "Original Place of Birth Text",
"source": "world-bank-star-asset-recovery-watch",
"value": "European Union",
"tag": "origins",
"locale": "EN"
}
],
"types": [
"pep"
],
"name": "Mouammar Mohammed Abu Minyar Kadhafi",
"entityType": "person",
"aka": [
{
"name": "Muammer al Gaddafi"
}
],
"associates": [
{
"association": "spouse",
"name": "Fatiha al-Nuri"
}
],
"sources": [
"argentina-ministerio-de-relaciones-exteriores-y-culto-sanciones-de-la-onu",
"belarus-state-security-agency-list-of-organizations-and-individuals-involved-in-terrorist-activities"
],
"keywords": [],
"media": [
{
"date": "2022-04-18T11:02:05.261Z",
"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",
"title": "Justice at Last - Former Gaddafi Aide Found Liable for 1984 Police Officer Murder by UK High Court",
"url": "https://sputniknews.com/amp/20211116/justice-at-last-former-gaddafi-aide-found-liable-for-1984-police-officer-murder-by-uk-high-court-1090775876.html"
}
],
"assets": [
{
"publicURL": "http://complyadvantage-asset.s3.amazonaws.com/76993a49-2d1e-4397-9e35-1e20f2b7dfa8.pdf",
"source": "world-bank-star-asset-recovery-watch",
"type": "pdf"
}
],
"sourceNotes": [
{
"amlTypes": [
"sanction"
],
"countryCodes": [
"AR"
],
"listingStartedUtc": "2019-09-26T00:00:00Z",
"name": "Argentina Ministerio de Relaciones Exteriores y Culto Sanciones de la ONU",
"url": "https://www.cancilleria.gob.ar/es/politica-exterior/seguridad-internacional/comite-de-sanciones"
}
],
"matchTypes": [
"name_exact",
"year_of_birth"
],
"matchTypesDetails": [
{
"matchTypes": "matching_name",
"type": "exact_match"
}
],
"matchStatus": "potential_match",
"isWhiteListed": false,
"score": 24.46217
}
}
]
}
]
}
}API request status.
List of objects identifying the person associated with the search term.
The unique identifier of the person.
Person's first name.
Person's last name.
Person's ID number.
Person's date of birth.
Person's gender.
Person's nationality (country code, in capital letters).
Person's birth place.
Always returns empty array.
Array of objects identifying the PEP and Sanction values associated with the person.
The array is empty if there are no hits in the database.
Name of the data provider that identified the PEP and Sanctions match.
The total number of PEP and Sanctions matches found.
The date when the PEP and Sanctions match was identified.
As Combined ISO 8601 date and time in UTC, YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset+Z.
Array listing the results that match the search term.
The name of the person matched in the PEP and Sanctions list.
The nationality of the person matched in the PEP and Sanctions list.
The category of the PEP and Sanctions match, SIP (Special Interest Person) or PEP (Politcally Exposed Person).
Array of objects listing results that match the search term.
List of attributes identifying the info in the document about the person.
Document number, [a-zA-Z0-9] characters only.
The date when the PEP and Sanctions match was recently updated.
As Combined ISO 8601 date and time in UTC, YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset+Z.
The date when the PEP and Sanctions match was created.
As Combined ISO 8601 date and time in UTC, YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset+Z.
Array of objects describing the document fields.
Name of the document field.
Source of the information in the document.
Value in the document field.
Tag related to the name object.
Language.
Array of match types names as defined by the data provider.
Person's name in the document.
Type of the entity
Array of objects listing the alternative names of the person.
Person's alternative name.
Array of objects identifying associates of the person.
Type of association (relationship).
Associate's name.
Info about the information sources.
Always returns an empty array.
Array of objects containing media files about the person.
Media file date info.
In the format of combined ISO 8601 date and time in UTC, YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset|Z.
Text snippet about the person.
Title of the media file.
Web address to the media.
Array listing the info about media sources.
Web address.
Name of the source.
File format.
List of attributes identifying the information source.
List of types as defined by the data provider.
Country code capital letters, as ISO 1366-1 Alpha-2 code.
Starting date info about the source.
In the format of combined ISO 8601 date and time in UTC, YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset|Z
Name of the info source.
Web address of the info source.
Info about which data was matched.
List of more detailed breakdown of why a match happened.
More detailed info about why a hit occurred, for example - matching_name, sources, aml_types, name_matches, secondary_matches`.
Displays the type of the match_type that was matched.
Status of the match.
Indicates whether the entity has been whitelisted.
Availability depends on the configuration.
The request results match and ranking is computed via a score that is included as part of the metadata. It is not an absolute ranking of the document, only giving some relative indication of relevance.
This decimal value comes from the data provider.
Bad request
Unauthorized
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 |
Oct 2, 2025 |
|
Aug 6, 2025 | Response headers added |
Jun 27, 2025 | Added a note about the |
Mar 12, 2025 | Documentation published |