API documentation: PEP Status List
Version 1.1.
Authorization
Authorization to the API of the PEP List module is done using the API Key sent in the request header called HFAPIKEY.
The generated key must have the status Active and have access to the PEP List module enabled.
Correct API Key configuration for PEP List
Details on API key configuration process are available in the HyperFlow Service Platform user documentation chapter 9. API keys.
Language selection
To change a response language please use the HTTP Header called HFLANG in each request. Supported values are:
- EN – for English language
- PL – for Polish language
Available API commands
Single PEP Check query
| Command | Single PEP status checkUsed to check one person per request |
| HTTP method | POST |
| URI | https://hyperflow.eu/api/route/pep |
| Request format | JSON |
| Response format | JSON |
| Character encoding | UTF-8 |
| Parameters | name – name of the verified person |
Request example:
{
"name": "Johan Lok"
}
Response example:
{
"items": [
{
"name": "Johan Lok",
"isPEP": "T",
"secondName": "Adriaan",
"position": [
"Member of court tribunal"
],
"bornCity": "",
"category": [
"P5"
],
"country": "CY",
"countryName": "Cyprus",
"pepRes": "Yes, this person is a PEP"
}
],
"result": "ok"
}
Implementation notes:
The name parameter is one string separated by spaces, adopting one of the possible options:
- First name <space> last name (any order)
np. John Smith
- First name <space> second name <space> last name (any order):
np. John Andrew Smith
- First name <space> last name <space> place of birth (any order):
np. John Smith Dublin
- First name <space> second name <space> last name <space> place of birth (any order):
np. John Andrew Smith Dublin
Example request without a hit:
{
"name": "John Doe"
}
Response example:
{
"items": [
{
"name": "John Doe",
"isPEP": "N",
"secondName": null,
"position": null,
"bornCity": null,
"category": null,
"country": null,
"pepRes": "No, this person is not a PEP "
}
],
"consumeId": "4825",
"result": "ok"
}
Batch PEP Check query
| Command | Batch PEP status checkUsed to check more than one person in one request |
| HTTP method | POST |
| URI | https://hyperflow.eu/api/route/pepbatch |
| Request format | JSON |
| Response format | JSON |
| Character encoding | UTF-8 |
| Parameters | “batch”:[“name”,”person 1 name”,name”,”person 2 name”] |
Request example:
{
"batch":["Adriana Banaszczyk","Kyriakos Mitsotakis","Bakir Izetbegović","Donald Tusk"]
}
Response example:
{
"result": "ok",
"batch": [
{
"items": [
{
"name": "Adriana Banaszczyk",
"isPEP": "T",
"secondName": "Maria",
"position": [
"Members of administrative, management or supervisory bodies of state enterprises"
],
"bornCity": "",
"category": [
"P7"
],
"country": "PL",
"countryName": "Poland",
"pepRes": "Yes, this person is a PEP"
}
],
"consumeId": "4827",
"result": "ok"
},
{
"items": [
{
"name": "Kyriakos Mitsotakis",
"isPEP": "T",
"secondName": "",
"position": [
"Prime Minister of Greece"
],
"bornCity": "",
"category": [
"P1"
],
"country": "GR",
"countryName": "Greece",
"pepRes": "Yes, this person is a PEP"
}
],
"consumeId": "4828",
"result": "ok"
},
{
"items": [
{
"name": "Bakir Izetbegović",
"isPEP": "T",
"secondName": "",
"position": [
"Presidency of Bosnia and Herzegovina"
],
"bornCity": "",
"category": [
"P1"
],
"country": "BA",
"countryName": "Bosnia and Herzegovina",
"pepRes": "Yes, this person is a PEP"
}
],
"consumeId": "4829",
"result": "ok"
},
{
"items": [
{
"name": "Donald Tusk",
"isPEP": "T",
"secondName": "Franciszek",
"position": [
"President of the European Council",
"Member of the governing bodies of political parties"
],
"bornCity": "Gdańsk",
"category": [
"P1",
"P3"
],
"country": "PL",
"countryName": "Poland",
"pepRes": "Yes, this person is a PEP"
}
],
"consumeId": "4830",
"result": "ok"
}
]
}
Implementation notes:
The batch parameter accepts a comma separated array of strings (JSONArray). Each string is constructed exactly on the same principles as a single name parameter, i.e. it accepts one of the possible scenarios :
- First name <space> last name (any order)
np. John Smith
- First name <space> second name <space> last name (any order):
np. John Andrew Smith
- First name <space> last name <space> place of birth (any order):
np. John Smith Dublin
- First name <space> second name <space> last name <space> place of birth (any order):
np. John Andrew Smith Dublin
Request example:
{
"batch":["Marc Hostert Luxembourg","Arturs Kariņš Krišjānis"]
}
Response example:
{
"result": "ok",
"batch": [
{
"items": [
{
"name": "Marc Hostert",
"isPEP": "T",
"secondName": "",
"position": [
"Member of court tribunal"
],
"bornCity": "Luxembourg",
"category": [
"P5"
],
"country": "LU",
"countryName": "Luxembourg",
"pepRes": "Yes, this person is a PEP"
}
],
"consumeId": "4831",
"result": "ok"
},
{
"items": [
{
"name": "Arturs Kariņš",
"isPEP": "T",
"secondName": "Krišjānis",
"position": [
"Prime Minister"
],
"bornCity": "",
"category": [
"P1"
],
"country": "LV",
"countryName": "Latvia",
"pepRes": "Yes, this person is a PEP"
},
{
"name": "Arturs Kariņš",
"isPEP": "T",
"secondName": "Krišjānis",
"position": [
"Prime minister of Latvia"
],
"bornCity": "Wilmington",
"category": [
"P1"
],
"country": "LV",
"countryName": "Latvia",
"pepRes": "Yes, this person is a PEP"
}
],
"consumeId": "4832",
"result": "ok"
}
]
}
Query from a remote file (own server source or Google Sheets)
| Command | PEP status check from a remote CSV fileUsed to check whole set of persons that are saved in remote CSV File |
| HTTP method | POST |
| URI | https://hyperflow.eu/api/route/pepbatch |
| Request format | JSON |
| Response format | JSON |
| Character encoding | UTF-8 |
| Parameters | “hfFile”: { “name”: “file.csv”, “tmp_name”: “https://your_remote_location.eu/your_file.csv”} |
Request example:
{
"hfFile": {
"name": "test_pep.csv",
"tmp_name": "https://remote_location.eu/test_pep.csv”
}
}
Where the remote file looks like the example below (1 single column with name) :
Requirements for the Remote CSV File:
- Encoded in UTF-8
- Available publicly or accessible via VPN Tunnel from the Hyperflow servers
- Comma separated CSV file where names are located in the first column (no header)
Notice for instant Google Sheets integration:
CSV FIle can be easy accessible directly from Link-Shared Google Sheet service using the following URL:
https://docs.google.com/spreadsheets/d/YOUR_GOOGLE_DOC_SECRECT_ID/export?format=csv
Response example:
{
"result": "ok",
"batch": [
{
"items": [
{
"name": "Paweł Księżak",
"isPEP": "T",
"secondName": "Sławomir",
"position": [
"Member of the high-level judicial body"
],
"bornCity": "",
"category": [
"P4"
],
"country": "PL",
"countryName": "Poland",
"pepRes": "Yes, this person is a PEP"
}
],
"consumeId": "4833",
"result": "ok"
},
{
"items": [
{
"name": "Ilze Fišere",
"isPEP": "T",
"secondName": "",
"position": [
"Judge, Kurzemes rajona tiesa (Ventspilī)"
],
"bornCity": "",
"category": [
"P4"
],
"country": "LV",
"countryName": "Latvia",
"pepRes": "Yes, this person is a PEP"
}
],
"consumeId": "4834",
"result": "ok"
},
{
"items": [
{
"name": "Miguel Skowron",
"isPEP": "T",
"secondName": "Antonio",
"position": [
"Polish Consul"
],
"bornCity": "",
"category": [
"P6"
],
"country": "AR",
"countryName": "Argentina",
"pepRes": "Yes, this person is a PEP"
}
],
"consumeId": "4835",
"result": "ok"
}
]
}
Usage recommendations
The recommended way to query the API is to provide only the first name and last name. In the case of an ambiguous answer – when the “hit” will affect more than one person – all results will be returned.
In the case of positive verification (this person is PEP), all available information about a given person is always returned (middle name, city of birth, position held) – if they appear in our database.
Using example with the RESTED client
Error Codes
Error:
{
"code": "0089",
"redirect": "",
"result": "err",
"msg": "No access to this service"
}
Cases:
- The user has used up the entire pool of purchased queries or the date by which the service has been purchased has expired,
- Inactive API key,
- The API key does not have the PEP List service enabled.
Error:
{
"code": "0404",
"redirect": "",
"result": "err",
"msg": "No file or file is empty"
}
Cases:
- The path provided is not valid,
- The file contains no data, is empty,
- Incorrect file format, the file is not a CSV file,
- Incorrectly entered parameter names: “name”, “tmp_name”.
Error:
{
"code": "0009",
"redirect": "",
"result": "err",
"msg": "Incorrect data"
}
Cases:
- Incorrectly entered parameter: “batch”, “hfFile”,
- Invalid parameter for URI request,
- “Batch”, “hfFile” parameter is empty,
- Missing parameter in request.
Error:
{
"code": "1233",
"redirect": "",
"result": "err",
"msg": "Unknown command"
}
Cases:
- Incorrect URI,
- The selected method is not valid for the query (POST / GET).
Error:
{
"code": "2002",
"redirect": "",
"result": "err",
"msg": "PeP name cannot be empty"
}
Cases:
- Parameter “name” is empty.