Zum Hauptinhalt springen
POST
curl
Verwenden Sie POST /v3/ip/risk/, wenn Ihr Backend bereits eine IP-Adresse hat und eine serverseitige Risikoentscheidung benötigt. Die Antwort enthält Geolokalisierung, Netzwerkeigentum, VPN- und Tor-Kennzeichen, Rechenzentrumskennzeichen, Bedrohungsdaten sowie country_mismatch, wenn Sie ein angegebenes Land übermitteln.

Antwort interpretieren

  • status ist In Review, wenn das ermittelte Land nicht mit claimed_country übereinstimmt oder wenn die Adresse mit VPN-, Tor- oder Rechenzentrumsinfrastruktur in Verbindung steht. Andernfalls ist er Approved.
  • ip.ip_country_code enthält den ermittelten Ländercode. Vergleichen Sie Länder über ip.country_mismatch, statt rohe Länderzeichenfolgen selbst zu vergleichen.
  • ip.latitude und ip.longitude geben eine ungefähre Netzwerk-Geolokalisierung an und keine genaue Standortangabe des Geräts.
  • ip.is_vpn_or_tor, ip.is_data_center, ip.proxy_type und ip.threat liefern Nachweise für Netzwerkrisiken.
  • ip.asn_number, ip.asn_organization, ip.connection_type und ip.carrier beschreiben das Netzwerk, zu dem die Adresse gehört.
  • request_id ist die API-Sitzungs-ID. Speichern Sie sie zusammen mit vendor_data, wenn Sie das Ergebnis später mit Webhooks oder Aktivitäten in der Konsole abgleichen müssen.
Die IP-Anreicherung erfolgt nach dem Best-Effort-Prinzip. Wenn keine Anreicherungsquelle brauchbare Daten liefert, gibt der Endpoint eine genehmigte Antwort mit ip.ip_address: null, ip.country_mismatch: null und einem leeren ip.threat-Objekt zurück. Einzelne Anreicherungsfelder können ebenfalls null sein, wenn sie nicht verfügbar sind.

Geräteintelligenz

Die IP Risk API ist ein rein serverseitiger Endpoint. Geräte-Fingerprinting gehört nicht dazu, weil ein Backend Browser- oder Gerätesignale allein nicht beobachten kann. Für gehostete Abläufe und SDK-Sitzungen stellt Didit die bereits erfassten Gerätefelder in der Sitzungsantwort bereit, darunter device_fingerprint, Geräte- und Browserdetails, user_agent, Rohdaten des Geräts sowie sitzungsübergreifende Treffer.

Verhalten in der Sandbox

Sandbox-Schlüssel validieren die Anfrage und liefern deterministische, genehmigte Daten zurück. Sie kontaktieren keine externen Intelligence-Dienste, verbrauchen keine Credits, erstellen keine Sitzung und tragen nicht zu Networks bei.

Abrechnung

Ein Aufruf der IP Risk API kostet $0.02 zum Listenpreis. Eine Anfrage in der Produktionsumgebung ist abrechenbar, sobald die Abfrage startet.

Autorisierungen

x-api-key
string
header
erforderlich

Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese- oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde, der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als null. Siehe https://docs.didit.me/console/api-keys.

Body

application/json
ip_address
string<ip>
erforderlich

Zu bewertende IPv4- oder IPv6-Adresse.

Beispiel:

"8.8.8.8"

claimed_country
string

Optionales ISO 3166-1 alpha-2 oder alpha-3 Land, das vom Benutzer oder der Sitzung angegeben wurde. Wird zur Berechnung von country_mismatch verwendet.

Maximum string length: 3
Beispiel:

"ESP"

user_agent
string

Vom Backend erkannter User-Agent. Wird als Anfragekontext gespeichert; bietet kein Geräte-Fingerprinting.

Maximum string length: 512
vendor_data
string

Ihre stabile Referenz für diese Anfrage. Wird in der API-Sitzung gespeichert und in der Antwort zurückgegeben.

metadata
object | null

Ihre nicht sensiblen JSON-Metadaten. Werden in der API-Sitzung gespeichert und in der Antwort zurückgegeben.

Antwort

Die Risikobewertung wurde abgeschlossen. Prüfen Sie status für die Entscheidung; HTTP ist bei abgeschlossenen Abfragen immer 200.

request_id
string<uuid>
erforderlich

ID der API-Sitzung, die für diese Anfrage erstellt wurde. Speichern Sie sie zusammen mit vendor_data, wenn Sie das Ergebnis mit späteren Webhooks oder Konsolenaktivitäten korrelieren müssen.

status
enum<string>
erforderlich

Entscheidung für diese API-Sitzung: In Review bei Netzwerk- oder Länderabweichungsrisiko, andernfalls Approved.

Verfügbare Optionen:
Approved,
In Review
created_at
string<date-time>
erforderlich

Zeitstempel dieser Antwort.

vendor_data
string | null

Rückgabe der von Ihnen gesendeten vendor_data, null, wenn Sie keine gesendet haben.

metadata
object | null

Rückgabe der von Ihnen gesendeten metadata, null, wenn Sie keine gesendet haben.

ip
object

IP-Risikoergebnis. Einzelne Anreicherungsfelder können null sein, wenn die Abfrage keine verwertbaren Daten zurückgegeben hat.

Zuletzt geändert am 7. November 2026