> ## 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 validació d'adreces: verifica i normalitza adreces

> POST /v3/address-validation/ de Didit confirma que una adreça existeix, la normalitza i retorna coordenades. $0.10 per adreça.

L'API d'Address Validation de Didit confirma que una adreça postal existeix i la retorna normalitzada, amb les seves línies de lliurament, components i coordenades. Fes servir `POST /v3/address-validation/` quan el teu backend tingui una adreça i necessiti saber si existeix i en quina forma normalitzada.

Address Validation només confirma l'adreça. Mai no vincula l'adreça amb una persona: un resultat `verified` vol dir que el lloc existeix, no que hi visqui ningú.

## Envia l'adreça

Envia-la en una sola línia a `address`, o bé com a camps estructurats: `address_line_1` i, si els tens, `address_line_2`, `city`, `region` i `postal_code`.
Mai no enviïs les dues formes en una mateixa sol·licitud.
`country` és sempre obligatori, com a codi ISO 3166-1 alpha-2 o alpha-3.

## Interpreta la resposta

* `address_validation.status` és la resposta en què pots basar-te:
  * `verified`: l'adreça s'ha confirmat fins a l'edifici (o el pis o l'apartat de correus).
  * `partially_verified`: s'ha confirmat només fins al carrer, o fins al nivell més precís que les dades de referència postals tenen per a aquell lloc.
  * `not_verified`: només ha coincidit la regió o la ciutat, o no ha coincidit res.
  * `unavailable`: la validació no ha pogut executar-se. Torna-ho a intentar més tard.
* `address_validation.verification_level` és el nivell més precís que ha coincidit: `administrative_area`, `locality`, `thoroughfare`, `premise` o `delivery_point`.
* `address_validation.address` i `address_validation.formatted_address` contenen l'adreça normalitzada, escrita com l'escriu el país.
* `address_validation.latitude` i `address_validation.longitude` situen l'adreça coincident.
* `request_id` identifica la sol·licitud. No es crea cap sessió i el resultat només es retorna en aquesta resposta, així que guarda el que necessitis.

El codi HTTP és `200` per a totes les sol·licituds completades, inclòs `unavailable`.

## Address Validation dins d'un flux de treball

El mateix control és un complement dels passos dels fluxos de treball de Verificació d'identitat i de Comprovant de domicili.
Activa `address_validation_enabled` a la configuració del pas, i l'adreça que ha facilitat la persona (impresa al document d'identitat o al comprovant de domicili) es validarà un cop s'hagi llegit la càrrega.
El resultat és l'objecte `address_validation` de l'entrada d'aquell pas dins de la decisió de la sessió (`id_verifications[]` o `poa_verifications[]`).
Una adreça `partially_verified` o `not_verified` activa l'advertència `ADDRESS_NOT_VERIFIED`, l'acció de la qual és el valor de `address_not_verified_action` del pas (`NO_ACTION` per defecte, que només registra l'advertència).
Una validació `unavailable` mai no activa aquesta advertència i mai no canvia la verificació.

## Comportament del sandbox

Les claus de sandbox validen la sol·licitud i retornen sempre un resultat `verified` determinista que retorna l'adreça que has enviat. No consumeixen crèdits.

## Facturació

Una crida a l'API d'Address Validation costa $0.10 per adreça validada.
Un resultat `unavailable` no es cobra.
En un flux de treball, el complement costa $0.10 per cada adreça que un pas hagi validat.


## OpenAPI

````yaml ca/openapi-25.json POST /v3/address-validation/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: Valida una adreça
      description: >-
        Confirma que una adreça existeix i rep-la normalitzada: les seves línies
        de lliurament, components i coordenades. Només confirma l'adreça; mai
        vincula l'adreça a una persona.


        **Sol·licitud.** Envia l'adreça en una línia (`address`) o com a camps
        estructurats (`address_line_1` i, opcionalment, `address_line_2`,
        `city`, `region`, `postal_code`), mai tots dos, i sempre el seu
        `country` (ISO 3166-1 alfa-2 o alfa-3).


        **Resultat.** `address_validation.status` és `verified` (confirmat fins
        a l'edifici), `partially_verified` (confirmat només fins al carrer o
        superior), `not_verified` (només han coincidit la regió o ciutat, o no
        ha coincidit res) o `unavailable` (la validació no s'ha pogut executar).
        L'estat HTTP és `200` per a cada sol·licitud completada, `unavailable`
        inclòs; reintenta un resultat `unavailable` més tard.


        **Facturació.** Una crida en producció costa $0.10 per adreça validada.
        Un resultat `unavailable` no es cobra. No s'emmagatzema res a part del
        registre d'ús: no es crea cap sessió i el resultat es retorna només en
        aquesta resposta.


        **Sandbox.** Les claus de sandbox validen la sol·licitud i sempre
        retornen un resultat determinista `verified` que reprodueix l'adreça
        enviada, sense consumir crèdits.


        **Autenticació.** Envia la clau d'API de la teva aplicació a
        `x-api-key`. Les credencials absents o no vàlides retornen `403` -
        aquesta API mai retorna `401`.


        **Límit de freqüència.** Pressupost compartit d'escriptura de 300
        sol·licituds per minut per clau d'API entre els endpoints
        POST/PATCH/DELETE (les creacions de transaccions i la ingesta
        d'esdeveniments tenen un pressupost separat de 600).
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: Camps d'adreça estructurada
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: Tota l'adreça en una sola línia
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            La validació s'ha completat. Llegeix `address_validation.status`;
            HTTP és sempre `200` per a una sol·licitud completada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: Una adreça real, confirmada fins al nivell de l'edifici
                  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: 'Un carrer inventat: només ha coincidit la ciutat'
                  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 validació no s'ha pogut executar; no s'ha cobrat
                  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: >-
        Una adreça: en una sola línia (`address`) o com a camps estructurats amb
        almenys `address_line_1`, mai tots dos alhora.
      properties:
        address:
          type: string
          maxLength: 500
          description: Tota l'adreça en una sola línia.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: Carrer i número.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: Apartament, suite, planta o edifici.
        city:
          type: string
          maxLength: 128
          description: Ciutat o localitat.
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: Estat, província o regió.
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: Codi ISO 3166-1 alpha-2 o alpha-3 del país de l'adreça.
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Identificador d'aquesta sol·licitud; indica'l a l'equip de suport.
            No s'ha creat cap sessió.
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: >-
        El resultat d'una Address Validation: si l'adreça existeix i la seva
        forma normalitzada. Només confirma l'adreça; mai vincula l'adreça 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'adreça s'ha confirmat fins a l'edifici (o el pis o
            l'apartat de correus). `partially_verified`: s'ha confirmat només
            fins al carrer, o fins al nivell més precís que tenen les dades
            postals de referència per a aquest lloc. `not_verified`: només ha
            coincidit la regió o la ciutat, o no ha coincidit res.
            `unavailable`: la validació no s'ha pogut executar (per exemple, el
            servei de referència no ha respost); no es cobra i no afecta mai una
            verificació.
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: >-
            El nivell més precís amb què s'ha fet coincidir l'adreça. `null`
            quan no hi ha cap coincidència o `status` és `unavailable`.
        address:
          type: object
          nullable: true
          description: L'adreça normalitzada. `null` quan `status` és `unavailable`.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: >-
                Primera línia de lliurament, escrita de la manera habitual del
                país.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: >-
                Segona línia de lliurament (un pis, edifici o barri), quan
                l'adreça en tingui.
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: Estat, província o regió.
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: Codi de país ISO 3166-1 alfa-2.
              example: US
        formatted_address:
          type: string
          nullable: true
          description: L'adreça normalitzada en una línia.
          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: >-
        El cos de la sol·licitud no és vàlid: falta o no es coneix `country`, no
        hi ha cap adreça, o s'han proporcionat tant `address` com els camps
        estructurats.
      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: >-
        Falta la clau d'API o no és vàlida, una clau amb abast restringit no té
        accés d'escriptura a `sessions`, o l'organització no pot cobrir la
        validació. Aquesta API mai no retorna `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: >-
        S'ha superat el límit compartit d'escriptura de 300 sol·licituds per
        minut per clau d'API. Respecta `Retry-After` abans de reintentar.
      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 clau d'API de la teva aplicació, des de Developers -> API keys a la
        Business Console. La clau primària té accés complet. Una clau amb nom
        pot tenir l'abast limitat: cap, lectura o escriptura per recurs,
        limitada a determinats fluxos de treball o a sessions aprovades, a una
        llista d'adreces IP i a una data de caducitat. 401 significa que la clau
        és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap
        clau, que la clau no té accés a aquest recurs o acció, o que la
        sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una
        ruta de sessió significa que la sessió està fora dels fluxos de treball
        o estats de la clau. Una clau sense accés a fitxers multimèdia rep els
        URL d'imatge, vídeo i PDF com a null, i una clau sense permís
        d'escriptura de sessions rep els enllaços de sessió i els tokens com a
        null. Consulta https://docs.didit.me/console/api-keys.

````

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