> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Adressvalidierungs-API: Adressen prüfen und normalisieren

> POST /v3/address-validation/ prüft, ob eine Adresse existiert, und liefert sie normalisiert mit Koordinaten. Didit, $0.10 pro Adresse.

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.


## OpenAPI

````yaml de/openapi-25.json POST /v3/address-validation/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API für Ausweisverifizierung. Authentifizierung über den x-api-key-Header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: Eine Adresse validieren
      description: >-
        Bestätigen Sie, dass eine Adresse existiert, und erhalten Sie sie
        normalisiert zurück: ihre Zustellzeilen, Komponenten und Koordinaten.
        Dies bestätigt ausschließlich die Adresse; es verknüpft die Adresse
        niemals mit einer Person.


        **Anfrage.** Senden Sie die Adresse in einer einzigen Zeile (`address`)
        oder als strukturierte Felder (`address_line_1` und optional
        `address_line_2`, `city`, `region`, `postal_code`), niemals beides, und
        stets ihr `country` (ISO 3166-1 Alpha-2 oder Alpha-3).


        **Ergebnis.** `address_validation.status` ist `verified` (bis zum
        Gebäude bestätigt), `partially_verified` (nur bis zur Straße oder höher
        bestätigt), `not_verified` (nur die Region oder Stadt stimmte überein
        oder gar nichts) oder `unavailable` (die Validierung konnte nicht
        ausgeführt werden). Der HTTP-Status ist `200` für jede abgeschlossene
        Anfrage, einschließlich `unavailable`; wiederholen Sie eine Anfrage mit
        dem Ergebnis `unavailable` später.


        **Abrechnung.** Ein Aufruf in der Produktionsumgebung kostet $0.10 pro
        validierter Adresse. Ein `unavailable`-Ergebnis wird nicht berechnet.
        Außer dem Nutzungsprotokoll wird nichts gespeichert: Es wird keine
        Sitzung erstellt und das Ergebnis wird nur in dieser Antwort
        zurückgegeben.


        **Sandbox.** Sandbox-Schlüssel validieren die Anfrage und geben immer
        ein deterministisches `verified`-Ergebnis zurück, das die gesendete
        Adresse widerspiegelt, ohne Credits zu verbrauchen.


        **Authentifizierung.** Senden Sie den API-Schlüssel Ihrer Anwendung in
        `x-api-key`. Fehlende oder ungültige Anmeldedaten geben `403` zurück –
        diese API gibt niemals `401` zurück.


        **Rate-Limit.** Geteiltes Schreibbudget von 300 Anfragen pro Minute pro
        API-Schlüssel über POST/PATCH/DELETE-Endpoints hinweg
        (Transaktionserstellungen und Ereignis-Ingestion haben ein separates
        Budget von 600).
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: Strukturierte Adressfelder
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: Die vollständige Adresse in einer Zeile
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            Die Validierung wurde abgeschlossen. Prüfen Sie
            `address_validation.status`; HTTP ist bei einer abgeschlossenen
            Anfrage immer `200`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: Eine echte Adresse, bis zum Gebäude bestätigt
                  value:
                    request_id: 6f7d2c1e-1c5a-4a1e-9b8f-2a1f0f4b9c3d
                    address_validation:
                      status: verified
                      verification_level: premise
                      address:
                        address_line_1: 1600 Amphitheatre Pkwy
                        address_line_2: null
                        city: Mountain View
                        region: CA
                        postal_code: 94043-1351
                        country: US
                      formatted_address: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351
                      latitude: 37.422022
                      longitude: -122.08429
                    created_at: '2026-10-27T11:20:00.000000+00:00'
                Not verified:
                  summary: 'Eine erfundene Straße: Nur die Stadt stimmte überein'
                  value:
                    request_id: 0b9e3f4a-6c2d-4e8b-a1f7-5d3c2b1a0e9f
                    address_validation:
                      status: not_verified
                      verification_level: locality
                      address:
                        address_line_1: Calle Inventada Que No Existe 99999 28046
                        address_line_2: null
                        city: Madrid
                        region: Madrid
                        postal_code: null
                        country: ES
                      formatted_address: >-
                        Calle Inventada Que No Existe 99999 28046, Madrid,
                        MADRID, SPAIN
                      latitude: 40.42603054
                      longitude: -3.68645331
                    created_at: '2026-10-27T11:21:00.000000+00:00'
                Unavailable:
                  summary: >-
                    Die Validierung konnte nicht ausgeführt werden; nicht
                    berechnet
                  value:
                    request_id: 3c1b2a0f-9e8d-4c7b-b6a5-1f0e9d8c7b6a
                    address_validation:
                      status: unavailable
                      verification_level: null
                      address: null
                      formatted_address: null
                      latitude: null
                      longitude: null
                    created_at: '2026-10-27T11:22:00.000000+00:00'
        '400':
          $ref: '#/components/responses/AddressValidationValidationError'
        '403':
          $ref: '#/components/responses/AddressValidationPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/address-validation/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "address_line_1": "1600 Amphitheatre Pkwy",
                "city": "Mountain View",
                "region": "CA",
                "postal_code": "94043",
                "country": "US"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.address_validation.validate(
                address_line_1="1600 Amphitheatre Pkwy",
                city="Mountain View",
                region="CA",
                postal_code="94043",
                country="US",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.addressValidation.validate({
              address_line_1: "1600 Amphitheatre Pkwy",
              city: "Mountain View",
              region: "CA",
              postal_code: "94043",
              country: "US",
            });
            console.log(result);
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.AddressValidationRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.addressValidation().validate(AddressValidationRequest.builder()
                    .addressLine1("1600 Amphitheatre Pkwy")
                    .city("Mountain View")
                    .region("CA")
                    .postalCode("94043")
                    .country("US")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->addressValidation->validate([
                'address_line_1' => '1600 Amphitheatre Pkwy',
                'city' => 'Mountain View',
                'region' => 'CA',
                'postal_code' => '94043',
                'country' => 'US',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.address_validation.validate(
              address_line_1: "1600 Amphitheatre Pkwy",
              city: "Mountain View",
              region: "CA",
              postal_code: "94043",
              country: "US"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await client.AddressValidation.ValidateAsync(new
            AddressValidationRequest

            {
                AddressLine1 = "1600 Amphitheatre Pkwy",
                City = "Mountain View",
                Region = "CA",
                PostalCode = "94043",
                Country = "US",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    AddressValidationRequest:
      type: object
      required:
        - country
      description: >-
        Eine Adresse: entweder einzeilig (`address`) oder als strukturierte
        Felder mit mindestens `address_line_1`, niemals beides.
      properties:
        address:
          type: string
          maxLength: 500
          description: Die vollständige Adresse in einer Zeile.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: Straße und Hausnummer.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: Wohnung, Suite, Etage oder Gebäude.
        city:
          type: string
          maxLength: 128
          description: Stadt oder Ortschaft.
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: Bundesland, Provinz oder Region.
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: ISO 3166-1-Alpha-2- oder Alpha-3-Code des Landes der Adresse.
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Kennung dieser Anfrage; geben Sie diese beim Support an. Es wird
            keine Sitzung erstellt.
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: >-
        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.
      required:
        - status
        - verification_level
        - address
        - formatted_address
        - latitude
        - longitude
      properties:
        status:
          type: string
          enum:
            - verified
            - partially_verified
            - not_verified
            - unavailable
          description: >-
            `verified`: Die Adresse wurde bis zum Gebäude (oder zur Wohnung bzw.
            zum Postfach) bestätigt. `partially_verified`: Sie wurde nur bis zur
            Straße oder bis zur genauesten Stufe bestätigt, die die
            Postreferenzdaten für diesen Ort enthalten. `not_verified`: Nur die
            Region oder die Stadt stimmte überein, oder gar nichts.
            `unavailable`: Die Validierung konnte nicht ausgeführt werden (z. B.
            hat der Referenzdienst nicht geantwortet); sie wird nicht
            abgerechnet und wirkt sich niemals auf eine Verifizierung aus.
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: >-
            Die genaueste Ebene, auf der die Adresse abgeglichen wurde. `null`,
            wenn keine Übereinstimmung vorliegt oder `status` auf `unavailable`
            steht.
        address:
          type: object
          nullable: true
          description: >-
            Die normalisierte Adresse. `null`, wenn `status` den Wert
            `unavailable` hat.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: >-
                Erste Zustellzeile, so geschrieben, wie im jeweiligen Land
                üblich.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: >-
                Zweite Adresszeile (Wohnung, Gebäude oder Stadtteil), sofern die
                Adresse eine enthält.
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: Bundesland, Provinz oder Region.
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: ISO 3166-1 Alpha-2-Ländercode.
              example: US
        formatted_address:
          type: string
          nullable: true
          description: Die normalisierte Adresse in einer Zeile.
          example: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351
        latitude:
          type: number
          nullable: true
          example: 37.422022
        longitude:
          type: number
          nullable: true
          example: -122.08429
  responses:
    AddressValidationValidationError:
      description: >-
        Der Anfrage-Body ist ungültig: ein fehlendes oder unbekanntes `country`,
        keine Adresse oder sowohl `address` als auch die strukturierten Felder
        angegeben.
      content:
        application/json:
          examples:
            Unknown country:
              value:
                country:
                  - >-
                    Use an ISO 3166-1 alpha-2 or alpha-3 country code, e.g. 'US'
                    or 'USA'.
            No address:
              value:
                address:
                  - >-
                    Send the address: 'address' on one line, or the structured
                    fields with 'address_line_1'.
            Both shapes:
              value:
                address:
                  - >-
                    Send either 'address' or the structured fields
                    (address_line_1, ...), not both.
    AddressValidationPermissionDenied:
      description: >-
        Der API-Schlüssel fehlt oder ist ungültig, ein berechtigungsbeschränkter
        Schlüssel verfügt nicht über Schreibzugriff auf `sessions` oder die
        Organisation kann die Validierung nicht abdecken. Diese API gibt niemals
        `401` zurück.
      content:
        application/json:
          examples:
            Missing or invalid API key:
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              value:
                detail: >-
                  You don't have enough credits to perform this request. Please
                  top up at https://business.didit.me
                code: insufficient_credits
    RateLimitedWrite:
      description: >-
        Das geteilte Schreiblimit von 300 Anfragen pro Minute pro API-Schlüssel
        wurde überschritten. Beachten Sie `Retry-After`, bevor Sie es erneut
        versuchen.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.