Geben Sie Ihre Kundennummer und Ihr Passwort ein, um den Kundenbereich von easycompliance zu betreten. Sollten Sie Ihr Passwort vergessen haben, wenden Sie sich bitte an unseren Kundenservice!

API von easycompliance


Eigene Schnittstellen entwickeln

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 Mehr InfosHandbuch .

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.
3=Ausgabe der Treffer, die die Listenprüfung 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.
ref (varchar) Ihre Referenz. Bspw. Kunden-, Lieferanten-, oder Personalnummer. (Optional)

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 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' => '2',
    '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 nur zwei Arten von Fehlern zurück:

Permission Denied: Die Anfrage enthält keine POST-Elemente (HTTP-Statuscode: 405).

Wrong API-KEY or account suspended: Ungültiger oder fehlerhafter API-Key bzw. Account gesperrt oder keine POST-Elemente im Body (HTTP-Statuscode: 401).

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.

easycompliance - plattformunabhängige Compliance-Prüfung für Ihr Unternehmen

Kunde werden
Produktdemo