API documentation: Sanctions Lists
Version 1.0
Authorization
Authorization to the API of the Sanctions Lists 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 Sanctions lists module enabled.
Correct API Key configuration for Sanctions lists
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 search query – sanctions lists for entities.
| Command | Single search for entitiesSingle query – checks on sanction lists for entities. |
| HTTP method | POST |
| URI | https://hyperflow.eu/api/route/sls/entity |
| Request format | JSON |
| Response format | JSON |
| Character encoding | UTF-8 |
| Parameters | name – company or organization name |
Request example:
{
"name":"Asadullah"
}
Response example:
{
"items": [
{
"name": "Asadullah",
"slsResponse": "Not listed on sanctions lists",
"issls": "N"
}
],
"consumeId": "8016",
"result": "ok"
}
Single search query – sanctions lists for natural persons.
| Command | Single search for natural personsSingle query – checks on sanction lists for natural persons. |
| HTTP method | POST |
| URI | https://hyperflow.eu/api/route/sls/person |
| Request format | JSON |
| Response format | JSON |
| Character encoding | UTF-8 |
| Parameters | name –first and last name of the verified person |
Request example:
{
"name":"Asadullah"
}
Response example:
{
"items": [
{
"name": "Asadullah",
"issls": "T",
"listType": "EU",
"objectType": "Natural person",
"src": "EU",
"reference": "EU.3997.31",
"name_aliases": [
"Asad",
"Asadullah",
"Abu Sa’d at-Trinidadi",
"Shane Dominic Crawford"
],
"birthyear_aliases": null,
"birthdate_aliases": [
"1986-02-22"
],
"comment": "Physical description: eye colour: brown; hair colour: dark; complexion: light brown; build: medium; height: 174cm; weight: 64kg; speaks English, Arabic.",
"slsResponse": "Listed on sanctions lists"
}
],
"consumeId": "8010",
"result": "ok"
}
Single search query – sanctions lists for entities and persons.
| Command | Single search for natural personsSingle query – checks on sanction lists for natural persons, organizations and companies. |
| HTTP method | POST |
| URI | https://hyperflow.eu/api/route/sls |
| Request format | JSON |
| Response format | JSON |
| Character encoding | UTF-8 |
| Parameters | name – name of the verified person or company/organization name |
Request example:
{
"name":"Asadullah"
}
Response example:
{
"items": [
{
"name": "Asadullah",
"issls": "T",
"listType": "EU",
"objectType": "Natural person",
"src": "EU",
"reference": "EU.3997.31",
"name_aliases": [
"Asad",
"Asadullah",
"Abu Sa’d at-Trinidadi",
"Shane Dominic Crawford"
],
"birthyear_aliases": null,
"birthdate_aliases": [
"1986-02-22"
],
"comment": "Physical description: eye colour: brown; hair colour: dark; complexion: light brown; build: medium; height: 174cm; weight: 64kg; speaks English, Arabic.",
"slsResponse": "Listed on sanctions lists”
}
],
"consumeId": "8010",
"result": "ok"
}
Implementation notes:
The name parameter is one string separated by spaces.
Batch query – sanctions lists for entities.
| Command | Batch query for entities |
| HTTP method | POST |
| URI | https://hyperflow.eu/api/route/slsbatch/entity |
| Request format | JSON |
| Response format | JSON |
| Character encoding | UTF-8 |
| Parameters | “batch”:[”entity name”,”entity name”,”entity name”] |
Request example:
{
"batch":["Abdul Karim","IG","John Doe"]
}
Response example:
{
"result": "ok",
"batch": [
{
"items": [
{
"name": "Abdul Karim",
"slsResponse": "Not listed on sanctions lists",
"issls": "N"
}
],
"consumeId": "8164",
"result": "ok"
},
{
"items": [
{
"name": "IG",
"issls": "T",
"listType": "EU",
"objectType": “Legal Person",
"name_aliases": [
"IG",
"Islamiska gruppen",
"Islamic Group - IG",
"Gama'a al-Islamiyya",
"Джамаа Ислямия",
"Grupo Islámico",
"Islámská skupina",
"Islamisk Gruppe",
"Islamische Gruppe",
"Islamirühmitus",
"Ισλαμική Ομάδα",
"Groupe islamique",
"Grúpa Ioslamach",
"Islamska skupina",
"Islamo grupuotė",
"Iszlám Csoport",
"il-Grupp Iżlamiku",
"Islamitische Groep",
"Grupa Islamska",
"Grupo Islâmico",
"Grupul Islamic",
"Islamská skupina",
"Islamistična skupina",
"Al-Gama'a al-Islamiyya"
],
"src": "EU",
"reference": "EU.3512.47",
"comment": "",
"slsResponse": "Listed on sanctions lists"
}
],
"consumeId": "8165",
"result": "ok"
},
{
"items": [
{
"name": "John Doe",
"slsResponse": Not listed on sanctions lists",
"issls": "N"
}
],
"consumeId": "8166",
"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.
Batch query – sanctions lists for natural persons.
| Command | Batch query – for natural persons. |
| HTTP method | POST |
| URI | https://hyperflow.eu/api/route/slsbatch/person |
| Request format | JSON |
| Response format | JSON |
| Character encoding | UTF-8 |
| Parameters | “batch”:[“first and last name of the verified person”,”first and last name of the verified person”,”first and last name of the verified person”] |
Request example:
{
"batch":["Abdul Karim","IG","John Doe"]
}
Response example:
{
"result": "ok",
"batch": [
{
"items": [
{
"name": "Abdul Karim",
"issls": "T",
"listType": "EU",
"objectType": "Natural person",
"src": "EU",
"reference": "EU.1518.29",
"name_aliases": [
"Abdul Hadi",
"Gun Gun Rusman Gunawan",
"Bukhory",
"Bukhori",
"Abdul Karim",
"Abd Al-Hadi",
"Rusman Gunawan"
],
"birthyear_aliases": null,
"birthdate_aliases": [
"1977-07-06"
],
"comment": "",
"slsResponse": "Listed on sanctions lists"
},
{
"name": "Abdul Karim",
"issls": "T",
"listType": "UN",
"objectType": Natural person",
"src": "UN",
"reference": "QDi.218",
"name_aliases": [
"GUN GUN RUSMAN GUNAWAN",
"Abd Al-Hadi",
"Abdul Hadi",
"Gunawan, Rusman",
"Bukhori",
"Abdul Karim",
"Bukhory"
],
"birthyear_aliases": null,
"birthdate_aliases": [
"1977-07-06"
],
"comment": "Brother of Nurjaman Riduan Isamuddin (QDi.087). Review pursuant to\nSecurity Council resolution 1822 (2008) was concluded on 8 Jun. 2010. Review pursuant to Security Council resolution 2368 (2017) was concluded on 4 Dec. 2019 INTERPOL-UN Security Council Special Notice web link: https://www.interpol.int/en/How-we-work/Notices/View-UN-Notices-Individuals",
"slsResponse": "Listed on sanctions lists"
}
],
"consumeId": "8167",
"result": "ok"
},
{
"items": [
{
"name": "IG",
"slsResponse": "Not listed on sanctions lists",
"issls": "N"
}
],
"consumeId": "8168",
"result": "ok"
},
{
"items": [
{
"name": "John Doe",
"slsResponse": "Not listed on sanctions lists",
"issls": "N"
}
],
"consumeId": "8169",
"result": "ok"
}
]
}
Batch query – sanctions lists for natural persons and entities.
| Command | Batch query |
| HTTP method | POST |
| URI | https://hyperflow.eu/api/route/slsbatch |
| Request format | JSON |
| Response format | JSON |
| Character encoding | UTF-8 |
| Parameters | “Batch”:[“first and last name”,”entity name”,”first and last name”,”entity name”] |
Request example:
{
"batch":["Abdul Karim","IG","John Doe"]
}
Response example:
{
"result": "ok",
"batch": [
{
"items": [
{
"name": "Abdul Karim",
"issls": "T",
"listType": "EU",
"objectType": "Natural person",
"src": "EU",
"reference": "EU.1518.29",
"name_aliases": [
"Abdul Hadi",
"Gun Gun Rusman Gunawan",
"Bukhory",
"Bukhori",
"Abdul Karim",
"Abd Al-Hadi",
"Rusman Gunawan"
],
"birthyear_aliases": null,
"birthdate_aliases": [
"1977-07-06"
],
"comment": "",
"slsResponse": "Listed on sanctions lists"
},
{
"name": "Abdul Karim",
"issls": "T",
"listType": "UN",
"objectType": "Natural person",
"src": "UN",
"reference": "QDi.218",
"name_aliases": [
"GUN GUN RUSMAN GUNAWAN",
"Abd Al-Hadi",
"Abdul Hadi",
"Gunawan, Rusman",
"Bukhori",
"Abdul Karim",
"Bukhory"
],
"birthyear_aliases": null,
"birthdate_aliases": [
"1977-07-06"
],
"comment": "Brother of Nurjaman Riduan Isamuddin (QDi.087). Review pursuant to\nSecurity Council resolution 1822 (2008) was concluded on 8 Jun. 2010. Review pursuant to Security Council resolution 2368 (2017) was concluded on 4 Dec. 2019 INTERPOL-UN Security Council Special Notice web link: https://www.interpol.int/en/How-we-work/Notices/View-UN
Notices-Individuals",
"slsResponse": "Listed on sanctions lists"
}
],
"consumeId": "8170",
"result": "ok"
},
{
"items": [
{
"name": "IG",
"issls": "T",
"listType": "EU",
"objectType": "Legal person",
"name_aliases": [
"IG",
"Islamiska gruppen",
"Islamic Group - IG",
"Gama'a al-Islamiyya",
"Джамаа Ислямия",
"Grupo Islámico",
"Islámská skupina",
"Islamisk Gruppe",
"Islamische Gruppe",
"Islamirühmitus",
"Ισλαμική Ομάδα",
"Groupe islamique",
"Grúpa Ioslamach",
"Islamska skupina",
"Islamo grupuotė",
"Iszlám Csoport",
"il-Grupp Iżlamiku",
"Islamitische Groep",
"Grupa Islamska",
"Grupo Islâmico",
"Grupul Islamic",
"Islamská skupina",
"Islamistična skupina",
"Al-Gama'a al-Islamiyya"
],
"src": "EU",
"reference": "EU.3512.47",
"comment": "",
"slsResponse": "Listed on sanctions lists"
}
],
"consumeId": "8171",
"result": "ok"
},
{
"items": [
{
"name": "John Doe",
"slsResponse": "Not listed on sanctions lists",
"issls": "N"
}
],
"consumeId": "8172",
"result": "ok"
}
]
}
Query from a remote file (own server source or Google Sheets)
| Command | Query 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/slsbatch |
| Request format | JSON |
| Response format | JSON |
| Character encoding | UTF-8 |
| Parameters | “hfFile”: { “name”: “your_file.csv”, “tmp_name”: “https://remotelocation.com/your_file.csv”} |
Request example:
{
"hfFile": {
"name": "your_file.csv",
"tmp_name": "https://remotelocation.com/your_file.csv”
}
}
Where the file contents look like this:
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
Using example with the RESTED client
Recommendations for queries
The recommended way of querying the API is to provide the first and last name, organization name or company name. In the case of an ambiguous answer – when the “hit” will involve more than one person/company – all results will be returned.
In the case of positive verification (listed on sanctions lists), all available information about a given person/company and sanctions imposed are always returned (in the case of a person: alternative dates of birth or year of birth, alternative names used; in the case of a company / organization: alternative names used; all responses include the type of sanctions list and its reference number).
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 Sanctions lists 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).