> ## 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 validazione indirizzi: verifica e normalizzazione

> POST /v3/address-validation/ di Didit verifica che un indirizzo esista e lo restituisce normalizzato con coordinate. $0.10 per indirizzo.

L'API Address Validation di Didit conferma che un indirizzo postale esiste e lo restituisce normalizzato, con le sue righe di recapito, le componenti e le coordinate. Usa `POST /v3/address-validation/` quando il tuo backend ha un indirizzo e deve sapere se esiste e in quale forma normalizzata.

Address Validation conferma solo l'indirizzo. Non collega mai l'indirizzo a una persona: un risultato `verified` indica che il luogo esiste, non che qualcuno vi abiti.

## Invia l'indirizzo

Invialo su una sola riga in `address`, oppure come campi strutturati: `address_line_1` e, se disponibili, `address_line_2`, `city`, `region` e `postal_code`.
Non inviare mai entrambe le forme nella stessa richiesta.
`country` è sempre obbligatorio, come codice ISO 3166-1 alpha-2 o alpha-3.

## Interpreta la risposta

* `address_validation.status` è la risposta su cui basarsi:
  * `verified`: l'indirizzo è stato confermato fino all'edificio (o all'appartamento o alla casella postale).
  * `partially_verified`: è stato confermato solo fino alla via, oppure al livello più preciso che i dati di riferimento postali contengono per quel luogo.
  * `not_verified`: hanno trovato corrispondenza solo la regione o la città, oppure nessun elemento.
  * `unavailable`: la validazione non è stata eseguita. Riprova più tardi.
* `address_validation.verification_level` è il livello più preciso trovato: `administrative_area`, `locality`, `thoroughfare`, `premise` o `delivery_point`.
* `address_validation.address` e `address_validation.formatted_address` contengono l'indirizzo normalizzato, scritto nel modo in cui lo scrive il paese.
* `address_validation.latitude` e `address_validation.longitude` indicano la posizione dell'indirizzo trovato.
* `request_id` identifica la richiesta. Non viene creata alcuna sessione e il risultato è restituito solo in questa risposta, quindi salva ciò che ti serve.

HTTP restituisce `200` per ogni richiesta completata, incluso `unavailable`.

## Address Validation all'interno di un workflow

Lo stesso controllo è un'aggiunta ai passaggi del workflow ID Verification e Proof of Address.
Attiva `address_validation_enabled` nelle impostazioni del passaggio: l'indirizzo fornito dalla persona (stampato sul documento d'identità o sulla prova di residenza) viene validato una volta elaborato il caricamento.
Il risultato è l'oggetto `address_validation` nella voce di quel passaggio all'interno della decisione della sessione (`id_verifications[]` o `poa_verifications[]`).
Un indirizzo `partially_verified` o `not_verified` genera l'avviso `ADDRESS_NOT_VERIFIED`, la cui azione è `address_not_verified_action` del passaggio (`NO_ACTION` per impostazione predefinita, che si limita a registrare l'avviso).
Una validazione `unavailable` non genera mai questo avviso e non modifica mai la verifica.

## Comportamento in sandbox

Le chiavi sandbox validano la richiesta e restituiscono sempre un risultato `verified` deterministico che riprende l'indirizzo inviato. Non consumano crediti.

## Fatturazione

Ogni chiamata all'API Address Validation costa $0.10 per indirizzo validato.
Un risultato `unavailable` non viene addebitato.
In un workflow, l'aggiunta costa $0.10 per ogni indirizzo validato da un passaggio.


## OpenAPI

````yaml it/openapi-25.json POST /v3/address-validation/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: Valida un indirizzo
      description: >-
        Conferma che un indirizzo esiste e lo riceve normalizzato: righe di
        consegna, componenti e coordinate. Conferma solo l'indirizzo; non
        collega mai l'indirizzo a una persona.


        **Richiesta.** Invia l'indirizzo su una sola riga (`address`) o come
        campi strutturati (`address_line_1` e, facoltativamente,
        `address_line_2`, `city`, `region`, `postal_code`), mai entrambi, e
        sempre il rispettivo `country` (ISO 3166-1 alpha-2 o alpha-3).


        **Risultato.** `address_validation.status` è `verified` (confermato fino
        all'edificio), `partially_verified` (confermato solo fino alla via o a
        un livello superiore), `not_verified` (corrispondenza solo per regione o
        città, oppure nessuna corrispondenza) o `unavailable` (non è stato
        possibile eseguire la validazione). HTTP è `200` per ogni richiesta
        completata, inclusa `unavailable`; riprova più tardi in caso di
        risultato `unavailable`.


        **Fatturazione.** Una chiamata in ambiente di produzione costa $0.10 per
        indirizzo validato. Un risultato `unavailable` non viene addebitato. Non
        viene memorizzato nulla a parte il record di utilizzo: non viene creata
        alcuna sessione e il risultato viene restituito solo in questa risposta.


        **Sandbox.** Le chiavi sandbox validano la richiesta e restituiscono
        sempre un risultato deterministico `verified` che ripropone l'indirizzo
        inviato, senza consumare crediti.


        **Autenticazione.** Invia la chiave API della tua applicazione
        nell'intestazione `x-api-key`. Credenziali mancanti o non valide
        restituiscono `403`: questa API non restituisce mai `401`.


        **Limite di frequenza.** Budget di scrittura condiviso di 300 richieste
        al minuto per chiave API tra tutti gli endpoint POST/PATCH/DELETE (la
        creazione di transazioni e l'ingestione di eventi hanno un budget
        separato di 600).
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: Campi strutturati dell'indirizzo
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: L'indirizzo completo su una sola riga
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            La validazione è stata completata. Leggi
            `address_validation.status`; il codice HTTP è sempre `200` per una
            richiesta completata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: Un indirizzo reale, confermato a livello di edificio
                  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: 'Una via inventata: solo la città corrispondeva'
                  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: Impossibile eseguire la validazione; nessun addebito
                  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: >-
        Un indirizzo: su una riga (`address`) o come campi strutturati con
        almeno `address_line_1`, mai entrambi.
      properties:
        address:
          type: string
          maxLength: 500
          description: L'indirizzo completo su una sola riga.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: Via e numero civico.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: Appartamento, suite, piano o edificio.
        city:
          type: string
          maxLength: 128
          description: Città o località.
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: Stato, provincia o regione.
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: Codice ISO 3166-1 alpha-2 o alpha-3 del paese dell'indirizzo.
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Identificatore di questa richiesta; comunicalo all'assistenza. Non
            viene creata alcuna sessione.
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: >-
        Il risultato di una verifica dell'indirizzo (Address Validation): se
        l'indirizzo esiste e la sua forma normalizzata. Conferma esclusivamente
        l'indirizzo; non collega mai l'indirizzo a una persona.
      required:
        - status
        - verification_level
        - address
        - formatted_address
        - latitude
        - longitude
      properties:
        status:
          type: string
          enum:
            - verified
            - partially_verified
            - not_verified
            - unavailable
          description: >-
            `verified`: l'indirizzo è stato confermato fino all'edificio (o
            all'appartamento o alla casella postale). `partially_verified`: è
            stato confermato solo fino alla via, o al livello più preciso
            disponibile nei dati di riferimento postali per quel luogo.
            `not_verified`: corrisponde solo la regione o la città, oppure non
            corrisponde nulla. `unavailable`: non è stato possibile eseguire la
            validazione (ad esempio il servizio di riferimento non ha risposto);
            non viene addebitata e non influisce mai su una verifica.
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: >-
            Il livello più preciso a cui è stato associato l'indirizzo. `null`
            se non è stata trovata alcuna corrispondenza o se `status` è
            `unavailable`.
        address:
          type: object
          nullable: true
          description: L'indirizzo normalizzato. `null` quando `status` è `unavailable`.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: >-
                Prima riga di recapito, scritta secondo le convenzioni del
                paese.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: >-
                Seconda riga di recapito (appartamento, edificio o quartiere),
                se presente nell'indirizzo.
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: Stato, provincia o regione.
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: Codice paese ISO 3166-1 alpha-2.
              example: US
        formatted_address:
          type: string
          nullable: true
          description: L'indirizzo normalizzato su una riga.
          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: >-
        Il corpo della richiesta non è valido: `country` mancante o sconosciuto,
        nessun indirizzo, oppure sia `address` che i campi strutturati presenti
        contemporaneamente.
      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 chiave API è mancante o non valida, una chiave con ambito limitato
        non dispone dell'accesso in scrittura a `sessions`, oppure
        l'organizzazione non può coprire la validazione. Questa API non
        restituisce mai `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: >-
        Il limite di scrittura condiviso di 300 richieste al minuto per chiave
        API è stato superato. Rispetta `Retry-After` prima di riprovare.
      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 chiave API della tua applicazione, da Developers -> API keys nella
        Business Console. La chiave primaria ha accesso completo. Una chiave con
        nome può avere un ambito definito: nessuno, lettura o scrittura per
        risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco
        di indirizzi IP e a una data di scadenza. 401 indica che la chiave è
        errata, revocata o scaduta; 403 indica che non è stata inviata alcuna
        chiave, che la chiave non ha accesso a questa risorsa o azione, oppure
        che la richiesta proviene da un indirizzo non incluso nel suo elenco IP;
        404 su una route di sessione indica che la sessione non rientra nei
        workflow o negli stati previsti dalla chiave. Una chiave senza accesso
        ai media riceve gli URL di immagini, video e PDF come null, e una chiave
        senza permessi di scrittura sulle sessioni riceve link e token di
        sessione come null. Consulta https://docs.didit.me/console/api-keys.

````

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