API & MCP-Integration

API

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

Eine API lässt Ihre Software direkt mit 123sanctions sprechen, ohne dass jemand sich dazwischen einloggen muss. Ihr System schickt eine JSON-Anfrage, bekommt strukturierte Ergebnisse zurück und arbeitet damit weiter.

Die vollständige Bewertungskette steht als JSON-Endpunkte zur Verfügung. Bewertungslogik, KI-Modelle und der nächtlich aktualisierte Sanktionsindex sind identisch mit dem, was die Weboberfläche nutzt. Gleiche Daten, gleiche Bewertungen, gleiche Quellen.

API-Zugang ist in jedem Konto enthalten. Schlüssel verwalten Sie in den Kontoeinstellungen unter „MCP & API“. Der kostenlose Tarif deckt 1 Schlüssel, 10 Anfragen pro Minute und 500 pro Monat ab — genug für Evaluierung und Proof of Concept. Bezahlte Tarife heben die Limits an.

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": 94331, "canonical_name": "Vladimir Vladimirovich Putin", "score": 100, "entity_type": "PERSON", "source_categories": ["pep", "sanctions"], "sources": ["AU_DFAT", "CA_SEMA", "CH_SECO", "CIA_WORLD_LEADERS", "EU_CONSOLIDATED", "UK_FCDO", "US_OFAC_SDN", "WIKIDATA_PEP"], "listing_count": 8, "is_sanctioned": true, "is_pep": true } ], "total_hits": 1, "screening_time_ms": 42 }

Batch-Screening

POST /api/v1/screen/batch

Prüfen Sie bis zu 50 Namen pro Anfrage. Jeder Name läuft durch die volle Bewertungskette; die Entitäts-Metadaten werden in einer Batch-Abfrage geladen. 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 Treffer rufen Sie das volle Profil ab — Aliasnamen, Einträge, biografische Daten — und gehen das Beziehungsnetzwerk durch: gemeinsame Adressen, gemeinsame Ausweise, Unternehmensverbindungen, 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, mit dem KI-Assistenten externe Werkzeuge aufrufen können. Damit prüft ein Assistent einen Namen, ruft ein Entitätsprofil ab oder geht ein Beziehungsnetzwerk durch — direkt im Chat, ohne Anwendungswechsel.

Der 123sanctions-MCP-Server stellt die Screening- und Entitätsinformations-API als MCP-Werkzeuge bereit. Compliance-Assistenten, KYC-Helfer und Sorgfaltspflicht-Agenten rufen sie direkt auf — 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": 100, "sources": ["AU_DFAT", "CA_SEMA", "CH_SECO", "CIA_WORLD_LEADERS", "EU_CONSOLIDATED", "UK_FCDO", "US_OFAC_SDN", "WIKIDATA_PEP"], "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.

ERP-Integration

Maßgeschneiderte Anbindung an Ihre Unternehmenssoftware

ERP, CRM, Zahlungs- und Onboarding-Systeme halten die Kunden-, Lieferanten- und Transaktionsdaten, die das Screening sehen muss. Screening wirkt am besten dort, wo diese Daten ohnehin entstehen — eingebettet ins System, nicht als separates Tool, das jemand aktiv öffnen muss.

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

Wir bauen die Anbindung für das System, das Sie tatsächlich einsetzen — ERP, CRM, Buchhaltung, eigene Inhouse-Tools. Sie wird gegen Ihr Datenmodell und Ihren bestehenden Workflow geschrieben, nicht als One-size-Plugin.

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