Zum Hauptinhalt springen
POST
curl
Didit’s Address Validation API confirms that a postal address exists and returns it normalised, with its delivery lines, components and coordinates. Verwenden Sie POST /v3/address-validation/, wenn Ihr Backend eine Adresse hat und wissen muss, ob sie existiert und in welcher normalisierten Form. Address Validation bestätigt nur die Adresse. Sie verknüpft die Adresse nie mit einer Person: Ein Ergebnis verified bedeutet, dass der Ort existiert, nicht dass dort jemand wohnt.

Adresse senden

Senden Sie sie in einer Zeile in address oder als strukturierte Felder: address_line_1 und, falls vorhanden, address_line_2, city, region und postal_code. Senden Sie niemals beide Formen in einer Anfrage. country ist immer erforderlich, als ISO-3166-1-Code mit zwei oder drei Buchstaben (alpha-2 oder alpha-3).

Antwort auswerten

  • address_validation.status ist das Ergebnis, auf dem Sie aufbauen:
    • verified: Die Adresse wurde bis auf das Gebäude bestätigt (oder bis auf die Wohnung oder das Postfach).
    • partially_verified: Sie wurde nur bis zur Straße bestätigt oder bis zur genauesten Ebene, die die Postreferenzdaten für diesen Ort enthalten.
    • not_verified: Nur die Region oder die Stadt stimmte überein, oder nichts davon.
    • unavailable: Die Validierung konnte nicht ausgeführt werden. Versuchen Sie es später erneut.
  • address_validation.verification_level ist die genaueste übereinstimmende Ebene: administrative_area, locality, thoroughfare, premise oder delivery_point.
  • address_validation.address und address_validation.formatted_address enthalten die normalisierte Adresse, so, wie es im jeweiligen Land üblich ist.
  • address_validation.latitude und address_validation.longitude verorten die übereinstimmende Adresse.
  • request_id identifiziert die Anfrage. Es wird keine Sitzung erstellt, und das Ergebnis wird nur in dieser Antwort zurückgegeben. Speichern Sie daher, was Sie benötigen.
Der HTTP-Status ist 200 für jede abgeschlossene Anfrage, auch für unavailable.

Adressvalidierung innerhalb eines Workflows

Dieselbe Prüfung ist ein Add-on der Workflow-Schritte Ausweisverifizierung und Adressnachweis. Aktivieren Sie address_validation_enabled in den Einstellungen des Schritts. Die Adresse, die die Person angegeben hat (auf dem Ausweisdokument oder auf dem Adressnachweis aufgedruckt), wird dann einmal validiert, sobald der Upload ausgelesen wurde. Das Ergebnis ist das Objekt address_validation im Eintrag dieses Schritts in der Sitzungsentscheidung (id_verifications[] oder poa_verifications[]). Eine Adresse mit partially_verified oder not_verified löst die Warnung ADDRESS_NOT_VERIFIED aus. Ihre Aktion ist der Wert von address_not_verified_action des Schritts (standardmäßig NO_ACTION, was die Warnung nur protokolliert). Eine unavailable-Validierung löst diese Warnung nie aus und verändert die Verifizierung nicht.

Sandbox-Verhalten

Sandbox-API-Schlüssel validieren die Anfrage und liefern immer ein deterministisches Ergebnis verified, das die von Ihnen gesendete Adresse wiedergibt. Sie verbrauchen keine Credits.

Abrechnung

Ein Aufruf der Address Validation API kostet $0.10 pro validierter Adresse. Ein Ergebnis `unavailable` wird nicht berechnet. Im Workflow kostet das Add-on $0.10 pro Adresse, die ein Schritt validiert hat.

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

Eine Adresse: entweder einzeilig (address) oder als strukturierte Felder mit mindestens address_line_1, niemals beides.

country
string
erforderlich

ISO 3166-1-Alpha-2- oder Alpha-3-Code des Landes der Adresse.

Maximum string length: 3
Beispiel:

"US"

address
string

Die vollständige Adresse in einer Zeile.

Maximum string length: 500
Beispiel:

"Paseo de la Castellana 259, 28046 Madrid"

address_line_1
string

Straße und Hausnummer.

Maximum string length: 255
Beispiel:

"1600 Amphitheatre Pkwy"

address_line_2
string

Wohnung, Suite, Etage oder Gebäude.

Maximum string length: 255
city
string

Stadt oder Ortschaft.

Maximum string length: 128
Beispiel:

"Mountain View"

region
string

Bundesland, Provinz oder Region.

Maximum string length: 128
Beispiel:

"CA"

postal_code
string
Maximum string length: 32
Beispiel:

"94043"

Antwort

Die Validierung wurde abgeschlossen. Prüfen Sie address_validation.status; HTTP ist bei einer abgeschlossenen Anfrage immer 200.

request_id
string<uuid>
erforderlich

Kennung dieser Anfrage; geben Sie diese beim Support an. Es wird keine Sitzung erstellt.

address_validation
object
erforderlich

Das Ergebnis einer Adressvalidierung: ob die Adresse existiert und ihre normalisierte Form. Sie bestätigt nur die Adresse; sie verknüpft die Adresse niemals mit einer Person.

created_at
string<date-time>
erforderlich
Zuletzt geändert am 7. November 2026