API von easycompliance
Eigene Schnittstellen entwickeln: Die REST-API ermöglicht Anwendungen aller Art den direkten Zugriff auf die Sanktionslistenprüfung und PEP-Prüfung von easycompliance.
Die API von easycompliance ermöglicht es Anwendungen aller Art, direkt auf die Sanktionslistenprüfung oder PEP-Prüfung von easycompliance zuzugreifen. So können bspw. Onlineshops noch während des Bestellvorgangs den Kunden gegen die aktuellsten Sanktionslisten prüfen. Ebenso kann die Prüfung in alle anderen (Web-)Anwendungen direkt integriert werden. Prozessbeschreibungen zur Anbindung eines CRM-/ERP-Systems oder eines Onlineshops finden Sie in unserem Handbuch . Für die Workflow-Automatisierung n8n steht eine eigene Schritt-für-Schritt-Anleitung bereit; KI-Agenten wie Claude oder ChatGPT nutzen die API am einfachsten über unseren MCP-Server.
Die Preise für die Nutzung unserer API finden Sie hier. Sie können zwischen unserem maximal flexiblen Pay-as-you-go-Tarif und günstigen Kontingentpaketen wählen. Sie können die API auch vorab unverbindlich ausprobieren: Im kostenlosen Testaccount ist der API-Zugriff (bis zu 100 Testabfragen gegen die Testsanktionslisten) bereits enthalten.
Parameter
Die API ist sehr einfach aufgebaut und kann über Parameter gesteuert werden. Die folgenden Parameter stehen zur Verfügung:
| Parameter | Wert | Beschreibung |
|---|---|---|
| api_key | (varchar) | Eindeutiger Schlüssel für die Authentifizierung. Wird Ihnen vom Kundendienst mitgeteilt. Ohne API-Key ist ein Zugriff auf die API nicht möglich |
| method | (int) 1, 2, 3, 4 oder 5 | 1=Einzelprüfung. 2=Prüfung und Name wird auf die Liste für die automatische Listenprüfung gesetzt (Monitoring). 3=Ausgabe der Treffer, die die Listenprüfung (Monitoring) innerhalb der letzten 24h generiert hat. 4=Datum des letzten Sanktionslisten bzw. PEP-Listenupdates im Format dd.mm.yyyy. 5=Namen von Listenprüfung entfernen. |
| accuracy | (int) Wert > 50 | Suchgenauigkeit. Wert kann zwischen 50 und 100 liegen (Ganzzahl). Ist kein Wert definiert oder liegt dieser unter 50, wird das eingestellte Suchmuster des Kunden übernommen |
| name | (varchar) | Name der zu prüfenden Organisation oder Person (utf8). Bitte beachten Sie die Hinweise zur Datenqualität aus unserem Handbuch. Bei method=5 wird der hier übermittelte Name aus der Liste der automatisch zu prüfenden Namen entfernt (bei duplicate_by=ref stattdessen der Eintrag mit der übermittelten Referenz). |
| ref | (varchar) | Ihre Referenz. Bspw. Kunden-, Lieferanten-, oder Personalnummer. (Optional) |
| duplicate_by | (varchar) name, ref | Standard: name Bei method=2: Duplikaterkennung über "name" oder "ref". Bei method=5: Löschung des Eintrags über "name" oder "ref". (Optional) |
| permutation | (int) 0, 1 | Standard: 0 (deaktiviert) Prüfung auch von Namensvarianten / Permutationen (zum Handbuch). (Optional) Hinweis: Bei Nutzung dieser Option kann die Antwort der API deutlich mehr Zeit in Anspruch nehmen. Wird method=2 zusammen mit permutation=1 genutzt, erfolgt die Prüfung bei der API-Anfrage mit aktivierter Option. Das nachfolgende Monitoring im Hintergrund findet jedoch mit der Einstellung des Kundenbereichs statt (standardmäßig ist im Monitoring die Option deaktiviert). |
| single_word_search | (int) 0, 1 | Ein-Wort-Suche (optional) Bei method=1 standardmäßig 1 (aktiviert) Bei method=2 wird der Wert übernommen, der im Kundenbereich unter „Stammdaten / Einstellungen“ bei „Ein-Wort-Suche im Monitoring aktivieren?“ gesetzt ist (standardmäßig 0=deaktiviert). Die API-Anfrage kann diesen Wert für die gestellte Anfrage überschreiben: Ist die Option im Kundenbereich deaktiviert, aber die API-Abfrage nutzt dennoch single_word_search=1, gilt diese Option nur für die Abfrage und nicht für das fortlaufende Monitoring des importierten Namens. Bitte beachten Sie unser Handbuch. |
Funktionsweise
Auf Grund der unterschiedlichen Daten, die auf den Sanktionslisten und PEP-Listen verzeichnet sind, bieten wir zwei API-Instanzen an: Eine API für die Sanktionslistenprüfung und eine API für die PEP-Prüfung. Wollen Sie also einen Geschäftspartner sowohl gegen die Sanktionslisten als auch gegen die PEP-Listen prüfen, müssen Sie zwei Abfragen tätigen.
Eine Abfrage wird initialisiert, indem ein POST-Request (per HTTPS) an die jeweilige API-URL gesendet wird. Hierbei ist es wichtig, dass sich die POST-Elemente im Body befinden und nicht etwa im Head. Die Parameter können dabei form-encodiert (application/x-www-form-urlencoded) oder als JSON-Body (Content-Type: application/json) übermittelt werden. Der api_key kann alternativ auch im HTTP-Header X-API-Key übergeben werden – ein im Body übermittelter Key hat Vorrang. Die API-URL erhalten Sie zusammen mit Ihrem API-Key vom Kundenservice. Die oben genannten Parameter werden durch die POST-Methode zur Verarbeitung an easycompliance übergeben. Als Rückantwort erhalten Sie eine Ausgabe im JSON-Format (bei method=1, 2 oder 3) bzw. als plain text (bei method=4). Zusätzlich werden HTTP-Statuscodes übergeben. Bei method=5 erfolgt ausschließlich die Rückgabe eines HTTP-Statuscodes (200=Name war vorhanden und wurde entfernt, 204=kein übermittelter Name auf der Liste).
Ausgabe (method=1 oder 2)
Ist die Ausgabe leer, wurde kein Treffer gefunden (HTTP-Statuscode: 204). Andernfalls erhalten Sie folgendes JSON-Objekt (bei Treffern auf mehreren Sanktionslisten bzw. PEP-Listen stellt jede Sanktionsliste ein eigenständiges Objekt dar; HTTP-Statuscode: 200). Klicken Sie auf die folgenden Optionen, um sich die Beispielausgabe anzeigen zu lassen:
[
{
"percent": 100,
"data": {
"header": {
"validFrom": "2003-07-07",
"validTo": "4000-01-01",
"entryDate": "2003-07-07",
"entityType": "P",
"datAkt": "2003-07-07",
"source": "1210/2003 (OJ L169)",
"comm": "(UNSC RESOLUTION 1483 BASIS)",
"commEn": "http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2003:169:0006:0023:EN:PDF",
"dob": "1942",
"pob": "al-Dur",
"status": "i",
"passport": ""
},
"name": [
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Izzat Ibrahim al-Duri",
"nationality": "",
"passNo": "",
"identNo": ""
},
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Abu Brays",
"nationality": "",
"passNo": "",
"identNo": ""
},
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Abu Ahmad",
"nationality": "",
"passNo": "",
"identNo": ""
},
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Izzat Ibrahim al-Duri",
"nationality": "",
"passNo": "",
"identNo": ""
},
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Izzat Ibrahim al-Duri",
"nationality": "",
"passNo": "",
"identNo": ""
},
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Abu Brays",
"nationality": "",
"passNo": "",
"identNo": ""
},
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Abu Brays",
"nationality": "",
"passNo": "",
"identNo": ""
},
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Abu Ahmad",
"nationality": "",
"passNo": "",
"identNo": ""
},
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Abu Ahmad",
"nationality": "",
"passNo": "",
"identNo": ""
},
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Izzat Ibrahim Al-Duri",
"nationality": "",
"passNo": "",
"identNo": ""
},
{
"datAkt": "2003-07-08",
"status": "i",
"name": "Izzat Ibrahim al-Douri",
"nationality": "",
"passNo": "",
"identNo": ""
}
]
}
}
][
{
"percent": 100,
"data": [
{
"person": {
"Title": "Mr.",
"Gender": "Male",
"First_Name": "Olaf",
"Last_Name": "Scholz",
"Full_Name": "",
"Other_Names": "",
"Function": "Office of the Federal Chancellor (BKAmt), Federal Chancellor, CATEGORY: Heads of State, Major Government Offices and Support; OTHER FUNCTION: Asian Infrastructure Investment Bank (AIIB), Board of Governors, Governor, Germany, CATEGORY: International Organizations; OTHER FUNCTION: Bundesrat, Ex Member, Hamburg, NOT IN CHARGE SINCE: 13.03.2018, CATEGORY: Ex PEPs, Legislative Functions, Parliaments; OTHER FUNCTION: Bundestag, Member (Party: SPD), CATEGORY: Legislative Functions, Parliaments; OTHER FUNCTION: European Bank for Reconstruction and Development (EBRD), Board of Governors, Governor, CATEGORY: International Organizations; OTHER FUNCTION: European Council, Member, CATEGORY: State Executive Functions, Government, Ministries; OTHER FUNCTION: European Investment Bank, Board of Governors, Member, CATEGORY: Central, National Banks, Monetary Authorities; OTHER FUNCTION: Federal Ministry of Finance, Ex Federal Minister, NOT IN CHARGE SINCE: 08.12.2021, CATEGORY: Ex PEPs, State Executive Functions, Government, Ministries; OTHER FUNCTION: Federal Ministry of Labor and Social Affairs, Ex Federal Minister, NOT IN CHARGE SINCE: 11.2009, CATEGORY: Ex PEPs, State Executive Functions, Government, Ministries; OTHER FUNCTION: International Monetary Fund (IMF), Board of Governors, Ex Alternate Governor, NOT IN CHARGE SINCE: 15.03.2022, CATEGORY: Ex PEPs, International Organizations; OTHER FUNCTION: Kreditanstalt für Wiederaufbau (KfW), Ex Deputy Chairperson of the Supervisory Board, NOT IN CHARGE SINCE: 25.02.2022, CATEGORY: Ex PEPs, Companies, Authorities and Organizations; OTHER FUNCTION: National Security Council, Chairperson, CATEGORY: Heads of State, Major Government Offices and Support; OTHER FUNCTION: Office of the Federal Chancellor (BKAmt), Ex Vice Federal Chancellor, NOT IN CHARGE SINCE: 08.12.2021, CATEGORY: Ex PEPs, Heads of State, Major Government Offices and Support; OTHER FUNCTION: Regional Government, Hamburg (Senate), Ex President of the Senate and First Mayor, NOT IN CHARGE SINCE: 14.03.2018, CATEGORY: Ex PEPs, Regional and Local Functions; Executive Functions; OTHER FUNCTION: Regional Parliament, Hamburgische Bürgerschaft, Ex Member (Party: SPD), NOT IN CHARGE SINCE: 2018, CATEGORY: Ex PEPs, Regional and Local Functions; Legislative Functions; OTHER FUNCTION: Social Democratic Party (SPD), Ex Vice Chairperson, NOT IN CHARGE SINCE: 12.2019, CATEGORY: Ex PEPs, Political Leaders; OTHER FUNCTION: Social Democratic Party (SPD), Ex Chairperson ad interim, NOT IN CHARGE SINCE: 01.04.2017, CATEGORY: Ex PEPs, Political Leaders; OTHER FUNCTION: Social Democratic Party (SPD), Ex General Secretary, NOT IN CHARGE SINCE: 21.03.2004, CATEGORY: Ex PEPs, Political Leaders",
"Category": "Central, National Banks, Monetary Authorities; Ex PEPs, Companies, Authorities and Organizations; Ex PEPs, Heads of State, Major Government Offices and Support; Ex PEPs, International Organizations; Ex PEPs, Legislative Functions, Parliaments; Ex PEPs, Political Leaders; Ex PEPs, Regional and Local Functions; Executive Functions; Ex PEPs, Regional and Local Functions; Legislative Functions; Ex PEPs, State Executive Functions, Government, Ministries; Heads of State, Major Government Offices and Support; International Organizations; Legislative Functions, Parliaments; State Executive Functions, Government, Ministries",
"DOB": "14.06.1958",
"POB": "Osnabrück, Germany",
"Country": "Germany",
"Code": "DEU",
"Additional_Information": "",
"Country_of_Origin": "Germany; Hamburg",
"Country_of_Activity": "China; European Union; Germany; IMF; United States of America; United Kingdom",
"Address_Type": "Private Residence 2022",
"Address_Main": "",
"Address_Street_Number": "",
"Address_Main_Additional": "",
"Address_Zipcode": "",
"Address_City": "Potsdam",
"Address_Region": "",
"Address_Country": "Germany"
},
"relatives": [
{
"Title": "Mrs.",
"Gender": "Female",
"First_Name": "Britta",
"Last_Name": "Ernst",
"Full_Name": ""
},
{
"Title": "Mr.",
"Gender": "Male",
"First_Name": "Ingo",
"Last_Name": "Scholz",
"Full_Name": ""
},
{
"Title": "Prof. Dr. Mr.",
"Gender": "Male",
"First_Name": "Jens",
"Last_Name": "Scholz",
"Full_Name": ""
},
{
"Title": "Mrs.",
"Gender": "Female",
"First_Name": "Christel",
"Last_Name": "Scholz",
"Full_Name": ""
},
{
"Title": "Mr.",
"Gender": "Male",
"First_Name": "Gerhard",
"Last_Name": "Scholz",
"Full_Name": ""
}
]
}
]
}
]Bei method=3 befinden sich die o.g. Daten im JSON-Objekt "result". Ferner werden noch weitere Daten ausgegeben:
| Parameter | Typ | Beschreibung |
|---|---|---|
| name | string | Name, der durch die Listenprüfung geprüft wurde |
| ref | string | Referenznummer (bspw. Ihre Kunden- oder Lieferantennummer). Wenn leer ist die Ausgabe null |
| time | int | Zeitstempel des Treffers im UNIX-Format |
Erklärung der generellen Rückgabeparameter
| Parameter | Typ | Beschreibung |
|---|---|---|
| percent | string | Enthält die prozentuale Übereinstimmung des gesuchten Namens mit dem Treffer |
| data | objekt | Enthält alle Informationen der Sanktionsliste |
| header | objekt | Enthält die "Kopfdaten" der Sanktionsliste |
| name | array | Enthält alle zugeordneten Namen und Namensinformationen als Objekt |
| address | array | Enthält alle zugeordneten Adressen und Adressinformationen als Objekt |
Detailbeschreibung
Die einzelnen Parameter innerhalb der Rückgabeobjekte und -arrays erklären sich i.d.R. von selbst. Diese sind bei der Sanktionslisten-API aus den HADDEX-Sanktionslisten von Reguvis und bei der PEP-API aus der PEP-DESK™ von info4c übernommen. Eine Erklärung benötigen die folgenden Übergabewerte:
| Parameter | Wert | Beschreibung |
|---|---|---|
| validTo | Datum im Format: YYYY-MM-DD | Wenn Datum = 4000-01-01 dann ist die Sanktion unbegrenzt gültig |
| dob | 1991-01-30 - 1991-01-30 oder... | Geburtsdaten (date of birth) |
| pob | (varchar) | Geburtsort (place of birth) |
| status | i oder u | i=Initialeintrag; u=aktualisierter Datensatz |
Beispielanfrage mit cURL in PHP
Im Folgenden wird eine Anfrage mittels cURL in PHP dargestellt. So können bspw. Onlineshops an die Sanktionslistenprüfung angebunden werden. Bitte beachten Sie, dass Sie den API-Key und die API-Url durch die Daten ersetzen, die Ihnen vom Kundenservice mitgeteilt wurden.
//POST-Parameter definieren
$query_vals = array(
'api_key' => 'IHR-API-KEY',
'method' => '1',
'accuracy' => '90',
'name' => 'NAME FÜR PRÜFUNG',
'ref' => '12345'
);
//POST-String generieren
foreach($query_vals as $key => $value) {
$request .= $key.'='.urlencode($value).'&';
}
$request = rtrim($request, '&');
//cURL mit API-URL initialisieren und Anfrage senden
$ch = curl_init("https://www.easycompliance-api-url.de");
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 4);
curl_setopt($ch, CURLOPT_TIMEOUT, 8);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
$response = curl_exec($ch);
curl_close ($ch);
//Ergebnis ausgeben
echo $response;Beispielanfrage mit Postman
Auf dem Screenshot von Postman sehen Sie, wie Sie eine Anfrage an die API mit Postman realisieren. Bitte beachten Sie, dass Sie den API-Key und die API-Url durch die Daten ersetzen, die Ihnen vom Kundenservice mitgeteilt wurden.
Fehlerbehandlung
Die API gibt die folgenden Fehler zurück:
Permission Denied: Die Anfrage wurde nicht als POST-Request gesendet (HTTP-Statuscode: 405).
Wrong API-KEY or account suspended: Ungültiger, fehlerhafter oder fehlender API-Key bzw. Account gesperrt (HTTP-Statuscode: 401).
Invalid JSON body: Der Request deklariert Content-Type application/json, der Body ist aber kein gültiges JSON-Objekt oder enthält Parameterwerte, die nicht Text/Zahl/Boolean sind – optionale Felder bitte weglassen statt null zu senden (HTTP-Statuscode: 400).
{"error": "Sanctions list API not booked for this account"}: Ihr Vertrag umfasst die Sanktionslisten-API nicht (HTTP-Statuscode: 403; JSON-Objekt als Antwort). Bitte wenden Sie sich an den Kundenservice, um die Schnittstelle zu buchen.
{"error": "PEP API not booked for this account"}: Ihr Vertrag umfasst die PEP-API nicht (HTTP-Statuscode: 403; JSON-Objekt als Antwort). Die PEP-Prüfung ist ein eigenes Produkt mit eigenen Preisen und kann jederzeit zugebucht werden.
{"error": "Monitoring methods (method 2/3/5) are not included in your API plan"}: Ihr API-Tarif enthält kein Monitoring – die Methoden 2 (Aufnahme in die automatische Prüfung), 3 (Trefferabruf) und 5 (Entfernen) stehen in reinen API-Tarifen ohne Monitoring nicht zur Verfügung (HTTP-Statuscode: 403; JSON-Objekt als Antwort). Einzelprüfung (method=1) und Datenstandsabfrage (method=4) sind unverändert nutzbar.
{"error": "Test period expired"}: Ihr siebentägiger Testzeitraum ist abgelaufen – der Test-API-Key (Präfix test-) ist nicht mehr gültig (HTTP-Statuscode: 403; JSON-Objekt als Antwort; betrifft nur Test-Zugänge aus dem kostenlosen Testaccount).
{"error": "Test request limit reached (100 requests per test period)"}: Das Kontingent von 100 API-Abfragen im Testzeitraum ist aufgebraucht (HTTP-Statuscode: 429; JSON-Objekt als Antwort; betrifft nur Test-Zugänge aus dem kostenlosen Testaccount).Es ist empfehlenswert, grundsätzliche Fehler, die im Zusammenhang mit API-Abfragen auftreten können, in der zu entwickelnden Schnittstelle zu beachten. So sollte, um beim Beispiel mit cURL zu bleiben, curl_error() genutzt werden. So kann bspw. ausgeschlossen werden, dass die API-URL nicht erreichbar ist (Hinweis: Im o.g. Beispiel werden hierzu CONNECTTIMEOUT und TIMEOUT verwendet. Die Nichterreichbarkeit der API behindert somit bspw. keine Bestellprozesse).
Ferner sollte beachtet werden, dass bei einer korrekten Abfrage eine leere Rückgabe der API bedeutet, dass kein Treffer auf den Sanktionslisten gefunden wurde. Da eine fehlerhafte Abfrage bei unzureichendem Error Handling in zu entwickelnden Schnittstellen jedoch auch eine leere Rückgabe erzeugen kann, sollten allgemeine Fehler und vor allem die übersandten HTTP-Statuscodes vor der Auswertung der API-Rückgabe beachtet werden.
Verlässlichkeit in Zahlen
Kundenzufriedenheit: laufende interne Kundenbefragungen und Qualitätssicherung – seit 2012, auf Basis von über 3.000 Kunden.