API & MCP-Integration

REST-API

Namen prüfen, Entitätsinformationen abrufen, Beziehungsnetzwerke erkunden

Eine API (Application Programming Interface, deutsch: Programmierschnittstelle) ermöglicht es Ihrer bestehenden Software, direkt mit 123sanctions zu kommunizieren — ohne manuelles Einloggen, ohne Kopieren und Einfügen, ohne menschliches Zutun. Ihre Systeme senden eine Anfrage, erhalten strukturierte Ergebnisse und verarbeiten diese automatisch.

Die API stellt die vollständige Screening-Pipeline als JSON-Endpunkte bereit. Jede Anfrage durchläuft dieselbe mehrschichtige Bewertungskette, dieselben ML-Modelle und denselben nächtlich aktualisierten Sanktionsindex wie die Weboberfläche. Keine separaten Daten, kein reduzierter Funktionsumfang.

API-Zugang ist in jedem 123sanctions-Konto enthalten. Erstellen Sie einen API-Schlüssel in Ihren Kontoeinstellungen und starten Sie sofort mit der Integration.

7Endpunkte

JSONAnfrage & Antwort

<250msDurchschn. Screening-Antwort

AES-256Verschlüsselung

Authentifizierung & Ratenbegrenzung

API-Schlüssel-Authentifizierung mit gleitendem Zeitfenster

Jede Anfrage (außer Gesundheitsprüfungen) erfordert einen API-Schlüssel im X-API-Key-Header. Schlüssel werden vor der Speicherung mit SHA-256 gehasht — der Rohschlüssel wird nie persistiert. Jeder Schlüssel hat ein konfigurierbares Ratenlimit, das über ein atomares Redis-Gleitfenster durchgesetzt wird.

Authentifizierungsdetails

Header	Beschreibung
`X-API-Key`	Ihr API-Schlüssel (erforderlich für alle Endpunkte außer `/health`)
`Content-Type`	`application/json` (erforderlich für POST-Anfragen)

Ratenlimit-Header werden in jeder Antwort mitgeliefert:

Header	Beschreibung
`X-RateLimit-Limit`	Maximale Anfragen pro Minute
`X-RateLimit-Remaining`	Verbleibende Anfragen im aktuellen Zeitfenster
`Retry-After`	Wartezeit in Sekunden (nur bei 429-Antworten)

Screening-Endpunkt

POST /api/v1/screen

Übermitteln Sie einen Namen und erhalten Sie passende Sanktionseinträge, sortiert nach Bewertung. Optionale Parameter für Entitätstyp, Geburtsdatum, Nationalität und Schwellenwert verfeinern die Ergebnisse. Die Antwort enthält bis zu 10 Treffer mit Entitäts-IDs, Quelleninformationen und Sanktionsstatus.

Anfrageparameter

Feld	Typ	Erforderlich	Beschreibung
`name`	String	Ja	Zu prüfender Name (max. 200 Zeichen)
`entity_type`	String	Nein	PERSON, ORGANIZATION, COMPANY, VESSEL, AIRCRAFT, SECURITY
`date_of_birth`	String	Nein	ISO-8601-Datum (JJJJ-MM-TT)
`nationality`	String	Nein	ISO-3166-1-Alpha-2-Ländercode
`threshold`	Integer	Nein	Mindestbewertung 0–100 (Standard: 80)

Beispielanfrage

POST /api/v1/screen Content-Type: application/json X-API-Key: sk_live_... { "name": "Wladimir Putin", "entity_type": "PERSON", "date_of_birth": "1952-10-07", "nationality": "RU", "threshold": 80 }

Beispielantwort

{ "request_id": "req_a1b2c3d4e5f6", "hits": [ { "entity_id": 12345, "canonical_name": "Vladimir Vladimirovich Putin", "score": 97, "entity_type": "PERSON", "sources": ["EU_CONSOLIDATED", "OFAC_SDN", "UK_FCDO"], "listing_count": 5, "is_sanctioned": true, "is_pep": true } ], "total_hits": 1, "screening_time_ms": 187 }

Batch-Screening

POST /api/v1/screen/batch

Prüfen Sie bis zu 50 Namen in einer einzigen Anfrage. Dieselbe Matching-Pipeline läuft für jeden Namen, aber Entitäts-Metadaten werden in einer einzigen Batch-Abfrage abgerufen. Jeder Name zählt als eine Anfrage gegen Ihr Monatslimit.

Anfrage-Format

POST /api/v1/screen/batch Content-Type: application/json X-API-Key: sk_live_... { "names": [ {"name": "Person A", "entity_type": "PERSON"}, {"name": "Person B", "date_of_birth": "1990-01-01"}, {"name": "Firma X", "entity_type": "COMPANY"} ], "threshold": 80 }

Jeder Eintrag unterstützt dieselben Parameter wie der einzelne Screening-Endpunkt. Der globale threshold gilt für alle Einträge, sofern nicht pro Eintrag überschrieben.

Antwort-Format

{ "request_id": "req_b4c5d6e7f8g9", "results": [ {"name_index": 0, "hits": [...], "total_hits": 3}, {"name_index": 1, "hits": [], "total_hits": 0}, {"name_index": 2, "hits": [...], "total_hits": 1} ], "total_names": 3, "screening_time_ms": 420 }

Entitäts- & Netzwerk-Endpunkte

Detaillierte Entitätsinformationen und Beziehungsnetzwerke

Nach einem Screening-Treffer können Sie das vollständige Entitätsprofil abrufen — Aliasnamen, Einträge in allen Quellen, biografische Daten — und das Beziehungsnetzwerk der Entität erkunden: gemeinsame Adressen, Ausweisdokumente, Unternehmensverbindungen und Familienbeziehungen.

Verfügbare Endpunkte

GET /api/v1/entities/{entity_id}

Gibt das vollständige Entitätsprofil zurück: kanonischer Name, Typ, Sanktions-/PEP-Status, alle Aliasnamen und Namensvarianten, aktive Einträge mit Quelle und Programm, Geburtsdatum, Nationalitäten und Verbindungsanzahl.

GET /api/v1/entities/{entity_id}/network

Gibt paginierte Entitätsverbindungen mit Typfilterung zurück. Verbindungstypen umfassen shared_address, shared_identifier, corporate_officer, corporate_owner, family_member, explicit_associate und weitere. Jede Verbindung enthält eine Konfidenzbewertung und Nachweise.

GET /api/v1/sources

Listet alle aktiven Sanktionsquellen mit letztem Importzeitpunkt, Entitätsanzahl und Eintragsanzahl. 5 Minuten gecacht.

GET /api/v1/usage

Gibt API-Nutzungsstatistiken für Ihren Schlüssel zurück: Gesamtanfragen, durchschnittliche Antwortzeit, Aufschlüsselung nach Endpunkt und Volumen der letzten 24 Stunden.

GET /api/v1/health

Öffentliche Gesundheitsprüfung. Keine Authentifizierung erforderlich.

Netzwerk-Antwortbeispiel

{ "entity_id": 12345, "canonical_name": "Vladimir Vladimirovich Putin", "connections_count": 127, "connections": [ { "connected_entity_id": 54321, "connected_entity_name": "Verbundene Entität", "connection_type": "explicit_associate", "confidence": 95, "connected_is_sanctioned": true } ], "pagination": { "limit": 100, "offset": 0, "total": 127, "has_more": true } }

Fehlerbehandlung & Datenminimierung

Einheitliches Fehlerformat. Keine unnötige Datenpreisgabe.

Alle Fehler werden als JSON-Objekt mit einem einzelnen error-Feld zurückgegeben. HTTP-Statuscodes folgen der Standardsemantik: 400 für ungültige Eingaben, 401 für fehlende oder ungültige API-Schlüssel, 403 für PEP-geschützten Zugriff, 404 für unbekannte Entitäten, 429 für Ratenbegrenzung und 503 für vorübergehende Nichtverfügbarkeit.

Der Screening-Endpunkt gibt niemals Eingabedaten in der Antwort zurück. PEP-exklusive Entitäten in Netzwerkergebnissen werden für API-Schlüssel ohne PEP-Zugang anonymisiert — Entitäts-IDs und Namen werden durch Platzhalter ersetzt, um eine indirekte Identifizierung zu verhindern. Die Nutzungsprotokollierung erfasst nur Endpunktnamen und Antwortzeiten, niemals Anfrage- oder Antwortinhalte.

HTTP-Statuscodes

Code	Bedeutung
`200`	Erfolg
`400`	Ungültige Anfrageparameter
`401`	Fehlender oder ungültiger API-Schlüssel
`403`	PEP-exklusive Entität ohne PEP-Zugang
`404`	Entität nicht gefunden
`429`	Ratenlimit überschritten
`503`	Dienst vorübergehend nicht verfügbar

MCP-Server

Sanktionsprüfung als Werkzeug für KI-Agenten

Das Model Context Protocol (MCP) ist ein offener Standard, der KI-Assistenten die Interaktion mit externen Werkzeugen und Datenquellen ermöglicht. Statt zwischen Anwendungen zu wechseln, kann ein KI-Assistent einen Namen prüfen, ein Entitätsprofil abrufen oder ein Beziehungsnetzwerk erkunden — so selbstverständlich wie eine Frage zu stellen.

Der 123sanctions-MCP-Server stellt die vollständige Screening- und Entitätsinformations-API als MCP-Werkzeuge bereit. KI-Agenten in Compliance-Arbeitsabläufen können Namen prüfen, Entitätsprofile abrufen und Beziehungsnetzwerke erkunden — ohne eigenen Integrationscode.

Verfügbare MCP-Werkzeuge

screen_name — Einen Namen gegen alle aktiven Sanktionslisten prüfen. Gibt bewertete Treffer mit Entitätstyp, Quelle und Sanktionsstatus zurück.
get_entity — Das vollständige Profil einer sanktionierten Entität abrufen: Aliasnamen, Einträge, biografische Daten und Verbindungsanzahl.
get_entity_network — Das Beziehungsnetzwerk einer Entität erkunden: Unternehmensverbindungen, gemeinsame Adressen, Familienbeziehungen und gemeinsame Listeneinträge.
list_sources — Alle aktiven Sanktionsquellen mit Metadaten und letzten Aktualisierungszeitpunkten auflisten.

Anwendungsfälle

KYC-Assistent: Ein KI-Assistent prüft Kundennamen während des Onboardings, ruft Entitätsdetails für markierte Ergebnisse ab und erstellt Compliance-Berichte — alles über MCP-Werkzeugaufrufe.
Transaktionsüberwachung: KI-Agenten in Zahlungsverarbeitungs-Workflows prüfen Gegenparteinamen in Echtzeit und eskalieren Treffer mit vollständigem Entitätskontext.
Sorgfaltspflicht-Automatisierung: KI-gestützte Recherchetools erkunden Entitätsnetzwerke, identifizieren sanktionierte Verbindungen und erstellen Beziehungskarten für Compliance-Beauftragte.
Regulatorische Berichterstattung: KI-Assistenten erstellen Sanktionsexposure-Berichte durch Abfrage von Entitätsdaten und Verbindungsgraphen über Jurisdiktionen hinweg.

So funktioniert es

Der MCP-Server läuft als leichtgewichtiger Prozess, der sich mit der 123sanctions-API verbindet. KI-Agenten erkennen verfügbare Werkzeuge über den MCP-Protokoll-Handshake und rufen sie dann mit strukturierten Parametern auf. Der Server übernimmt Authentifizierung, Ratenbegrenzung und Antwortformatierung transparent.

// Beispiel: KI-Agent prüft einen Namen über MCP { "tool": "screen_name", "arguments": { "name": "Wladimir Putin", "entity_type": "PERSON" } } // MCP-Server gibt strukturiertes Ergebnis zurück { "hits": [ { "canonical_name": "Vladimir Vladimirovich Putin", "score": 97, "sources": ["EU_CONSOLIDATED", "US_OFAC_SDN", "UK_FCDO", "CH_SECO", "AU_DFAT", "CA_SEMA"], "is_sanctioned": true } ] }

Zur Verbindung erstellen Sie einen API-Schlüssel in Ihren Kontoeinstellungen unter „MCP & API" und fügen die Server-URL in Ihre MCP-Client-Konfiguration ein. Kompatibel mit Claude Desktop, Cursor und jedem MCP-fähigen KI-Tool.

API-Zugang

Jedes Konto beinhaltet API- und MCP-Zugang. Schlüssel in den Kontoeinstellungen erstellen.

Erstellen und verwalten Sie API-Schlüssel direkt in Ihren Kontoeinstellungen unter „MCP & API“.

Der kostenlose Tarif umfasst 1 API-Schlüssel, 10 Anfragen pro Minute und 500 Anfragen pro Monat — genug, um die API zu testen und einen Proof of Concept zu erstellen. Höhere Limits sind in kostenpflichtigen Tarifen verfügbar.

ERP-Integration

Maßgeschneiderte Anbindung an Ihre Unternehmenssoftware

ERP-Systeme (Enterprise Resource Planning) sind das Rückgrat der meisten Unternehmen — sie verwalten Kunden, Lieferanten, Transaktionen und Stammdaten. Sanktionsprüfung ist am wirksamsten, wenn sie dort läuft, wo die Daten entstehen: in Ihrem ERP-System, Ihrem CRM, Ihrem Zahlungssystem oder Ihrem Onboarding-Workflow.

Bei 123sanctions ist die ERP-Integration kein separates Produkt. Wir entwickeln sie für Sie.

Wir entwickeln eine maßgeschneiderte Integration für Ihre spezifische Softwareumgebung — ob Warenwirtschaftssystem, Kundenverwaltung, Buchhaltungssoftware oder jede andere Geschäftsanwendung. Das ist kein generisches Plugin. Es ist eine zweckgebundene Anbindung, konzipiert für Ihr Datenmodell, Ihre Arbeitsabläufe und Ihre Compliance-Anforderungen.

Wir entwickeln diese Integrationen im Rahmen unserer Entwicklungskapazität nach Eingang der Anfrage.