> ## 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.

# API de validation d'adresse : vérifier et normaliser

> Didit POST /v3/address-validation/ confirme qu'une adresse existe et la renvoie normalisée, avec coordonnées. $0.10 par adresse.

L'API Address Validation de Didit confirme qu'une adresse postale existe et la renvoie normalisée, avec ses lignes de livraison, ses composants et ses coordonnées. Utilisez `POST /v3/address-validation/` lorsque votre backend dispose d'une adresse et doit savoir si elle existe, et sous quelle forme normalisée.

Address Validation confirme uniquement l'adresse. Elle ne relie jamais l'adresse à une personne : un résultat `verified` signifie que le lieu existe, et non que quelqu'un y habite.

## Envoyer l'adresse

Envoyez-la sur une seule ligne dans `address`, ou sous forme de champs structurés : `address_line_1` et, si vous les avez, `address_line_2`, `city`, `region` et `postal_code`.
N'envoyez jamais les deux formats dans une même requête.
`country` est toujours obligatoire, sous forme de code ISO 3166-1 alpha-2 ou alpha-3.

## Interpréter la réponse

* `address_validation.status` est la réponse sur laquelle vous appuyer :
  * `verified` : l'adresse a été confirmée jusqu'au bâtiment (ou jusqu'à l'appartement ou à la boîte postale).
  * `partially_verified` : elle n'a été confirmée que jusqu'à la rue, ou jusqu'au niveau le plus précis que les données de référence postales contiennent pour ce lieu.
  * `not_verified` : seuls la région ou la ville correspondaient, ou rien ne correspondait.
  * `unavailable` : la validation n'a pas pu être exécutée. Réessayez plus tard.
* `address_validation.verification_level` correspond au niveau le plus précis obtenu : `administrative_area`, `locality`, `thoroughfare`, `premise` ou `delivery_point`.
* `address_validation.address` et `address_validation.formatted_address` contiennent l'adresse normalisée, écrite selon la manière dont le pays l'écrit.
* `address_validation.latitude` et `address_validation.longitude` situent l'adresse trouvée.
* `request_id` identifie la requête. Aucune session n'est créée et le résultat n'est renvoyé que dans cette réponse : conservez donc ce dont vous avez besoin.

Le code HTTP est `200` pour toute requête terminée, y compris lorsque le résultat est `unavailable`.

## Address Validation dans un workflow

La même vérification est un module complémentaire des étapes de workflow Vérification d'identité et Justificatif de domicile.
Activez `address_validation_enabled` dans les paramètres de l'étape : l'adresse fournie par la personne (imprimée sur le document d'identité ou sur le justificatif de domicile) est validée une fois son envoi lu.
Le résultat est l'objet `address_validation` de l'entrée de cette étape dans la décision de session (`id_verifications[]` ou `poa_verifications[]`).
Une adresse `partially_verified` ou `not_verified` déclenche l'avertissement `ADDRESS_NOT_VERIFIED`, dont l'action est celle définie dans `address_not_verified_action` de l'étape (`NO_ACTION` par défaut, qui se contente d'enregistrer l'avertissement).
Une validation `unavailable` ne déclenche jamais cet avertissement et ne modifie jamais la vérification.

## Comportement en sandbox

Les clés sandbox valident la requête et renvoient toujours un résultat `verified` déterministe qui reprend l'adresse envoyée. Elles ne consomment pas de crédits.

## Facturation

Un appel à l'API Address Validation coûte $0.10 par adresse validée.
Un résultat `unavailable` n'est pas facturé.
Dans un workflow, le module complémentaire coûte $0.10 par adresse validée par une étape.


## OpenAPI

````yaml fr/openapi-25.json POST /v3/address-validation/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de vérification d'identité. Authentifiez-vous avec l'en-tête x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: Valider une adresse
      description: >-
        Confirmez qu'une adresse existe et recevez-la normalisée : ses lignes de
        livraison, ses composants et ses coordonnées. Cela confirme uniquement
        l'adresse ; cela ne lie jamais l'adresse à une personne.


        **Requête.** Envoyez l'adresse sur une seule ligne (`address`) ou sous
        forme de champs structurés (`address_line_1` et, facultativement,
        `address_line_2`, `city`, `region`, `postal_code`), jamais les deux, et
        toujours son `country` (ISO 3166-1 alpha-2 ou alpha-3).


        **Résultat.** `address_validation.status` est `verified` (confirmée
        jusqu'au bâtiment), `partially_verified` (confirmée uniquement jusqu'à
        la rue ou au-dessus), `not_verified` (seule la région ou la ville
        correspondait, ou rien ne correspondait) ou `unavailable` (la validation
        n'a pas pu être exécutée). Le statut HTTP est `200` pour chaque requête
        terminée, y compris `unavailable` ; réessayez ultérieurement en cas de
        résultat `unavailable`.


        **Facturation.** Un appel en production coûte $0.10 par adresse validée.
        Un résultat `unavailable` n'est pas facturé. Rien n'est stocké en dehors
        de l'enregistrement d'utilisation : aucune session n'est créée et le
        résultat est renvoyé uniquement dans cette réponse.


        **Sandbox.** Les clés sandbox valident la requête et renvoient toujours
        un résultat déterministe `verified` qui reprend l'adresse envoyée, sans
        consommer de crédits.


        **Authentification.** Envoyez la clé API de votre application dans
        `x-api-key`. Des identifiants manquants ou invalides renvoient `403` -
        cette API ne renvoie jamais `401`.


        **Limite de débit.** Budget d'écriture partagé de 300 requêtes par
        minute par clé API sur l'ensemble des endpoints POST/PATCH/DELETE (les
        créations de transactions et l'ingestion d'événements disposent d'un
        budget distinct de 600).
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: Champs d'adresse structurée
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: L'adresse complète sur une seule ligne
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            La validation est terminée. Consultez `address_validation.status` ;
            le code HTTP est toujours `200` pour une requête terminée.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: Une adresse réelle, confirmée au niveau du bâtiment
                  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: 'Une rue inventée : seule la ville correspondait'
                  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: La validation n'a pas pu être exécutée ; non facturée
                  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: >-
        Une adresse : sur une seule ligne (`address`) ou sous forme de champs
        structurés avec au moins `address_line_1`, jamais les deux.
      properties:
        address:
          type: string
          maxLength: 500
          description: L'adresse complète sur une seule ligne.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: Rue et numéro.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: Appartement, suite, étage ou bâtiment.
        city:
          type: string
          maxLength: 128
          description: Ville ou localité.
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: État, province ou région.
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: Code ISO 3166-1 alpha-2 ou alpha-3 du pays de l'adresse.
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Identifiant de cette requête ; indiquez-le au support. Aucune
            session n'est créée.
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: "Le résultat d'une Address Validation\_: indique si l'adresse existe, ainsi que sa forme normalisée. Cela confirme uniquement l'adresse\_; cela ne lie jamais l'adresse à une personne."
      required:
        - status
        - verification_level
        - address
        - formatted_address
        - latitude
        - longitude
      properties:
        status:
          type: string
          enum:
            - verified
            - partially_verified
            - not_verified
            - unavailable
          description: "`verified`\_: l'adresse a été confirmée jusqu'au bâtiment (ou à l'appartement ou à la boîte postale). `partially_verified`\_: elle a été confirmée uniquement jusqu'à la rue, ou au niveau le plus précis contenu dans les données de référence postales pour ce lieu. `not_verified`\_: seule la région ou la ville correspondait, ou rien ne correspondait. `unavailable`\_: la validation n'a pas pu être exécutée (par exemple, le service de référence n'a pas répondu)\_; elle n'est pas facturée et n'affecte jamais une vérification."
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: >-
            Le niveau le plus précis auquel l'adresse a été mise en
            correspondance. `null` si aucune correspondance n'a été trouvée ou
            si `status` est `unavailable`.
        address:
          type: object
          nullable: true
          description: L'adresse normalisée. `null` lorsque `status` est `unavailable`.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: Première ligne de livraison, rédigée selon le format du pays.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: >-
                Deuxième ligne de livraison (appartement, bâtiment ou quartier),
                si l'adresse en comporte une.
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: État, province ou région.
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: Code pays ISO 3166-1 alpha-2.
              example: US
        formatted_address:
          type: string
          nullable: true
          description: L'adresse normalisée sur une seule ligne.
          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: >-
        Le corps de la requête n'est pas valide : un `country` manquant ou
        inconnu, aucune adresse, ou à la fois `address` et les champs
        structurés.
      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: >-
        La clé API est manquante ou invalide, une clé restreinte ne dispose pas
        de l'accès en écriture à `sessions`, ou l'organisation ne peut pas
        couvrir la validation. Cette API ne renvoie jamais `401`.
      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: >-
        La limite d'écriture partagée de 300 requêtes par minute et par clé API
        a été dépassée. Respectez l'en-tête `Retry-After` avant de réessayer.
      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: >-
        La clé API de votre application, issue de Développeurs -> Clés API dans
        la Business Console. La clé principale dispose d'un accès complet. Une
        clé nommée peut être restreinte : aucun, lecture ou écriture par
        ressource, limitée à certains workflows ou aux sessions approuvées, à
        une liste d'adresses IP et à une date d'expiration. 401 signifie que la
        clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a
        été envoyée, que la clé n'a pas accès à cette ressource ou action, ou
        que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur
        une route de session signifie que la session est hors des workflows ou
        des statuts de la clé. Une clé sans accès aux médias reçoit les URL
        d'images, de vidéos et de PDF à null, et une clé sans accès en écriture
        aux sessions reçoit les liens et tokens de session à null. Voir
        https://docs.didit.me/console/api-keys.

````

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