> ## 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ón de direcciones: verifica y normaliza

> La API de Didit confirma que una dirección existe y la devuelve normalizada con coordenadas. Entrada estructurada o en una línea; $0.10 por dirección.

La API de Validación de direcciones de Didit confirma que una dirección postal existe y la devuelve normalizada, con sus líneas de entrega, sus componentes y sus coordenadas. Usa `POST /v3/address-validation/` cuando tu backend tenga una dirección y necesite saber si existe y cuál es su forma normalizada.

La Validación de direcciones solo confirma la dirección. Nunca vincula la dirección con una persona: un resultado `verified` significa que el lugar existe, no que alguien viva allí.

## Envía la dirección

Envíala en una sola línea en `address`, o como campos estructurados: `address_line_1` y, cuando los tengas, `address_line_2`, `city`, `region` y `postal_code`.
Nunca envíes ambos formatos en una misma solicitud.
`country` siempre es obligatorio, como código ISO 3166-1 alfa-2 o alfa-3.

## Interpreta la respuesta

* `address_validation.status` es la respuesta sobre la que debes construir tu lógica:
  * `verified`: la dirección se confirmó hasta el edificio (o hasta la vivienda o el apartado postal).
  * `partially_verified`: se confirmó solo hasta la calle, o hasta el nivel más preciso que contienen los datos postales de referencia para ese lugar.
  * `not_verified`: solo coincidió la región o la ciudad, o no coincidió nada.
  * `unavailable`: no se pudo ejecutar la validación. Vuelve a intentarlo más tarde.
* `address_validation.verification_level` es el nivel más preciso en el que hubo coincidencia: `administrative_area`, `locality`, `thoroughfare`, `premise` o `delivery_point`.
* `address_validation.address` y `address_validation.formatted_address` contienen la dirección normalizada, escrita como se escribe en ese país.
* `address_validation.latitude` y `address_validation.longitude` ubican la dirección encontrada.
* `request_id` identifica la solicitud. No se crea ninguna sesión y el resultado solo se devuelve en esta respuesta, así que guarda lo que necesites.

El código HTTP es `200` para toda solicitud completada, `unavailable` incluido.

## Validación de direcciones dentro de un flujo de verificación

La misma comprobación es un complemento de los pasos de Verificación de identidad y Prueba de domicilio del flujo de verificación (workflow).
Activa `address_validation_enabled` en la configuración del paso y la dirección que aportó la persona (impresa en el documento de identidad o en la prueba de domicilio) se valida en cuanto se lee lo que subió.
El resultado es el objeto `address_validation` de la entrada de ese paso en la decisión de la sesión (`id_verifications[]` o `poa_verifications[]`).
Una dirección `partially_verified` o `not_verified` genera la advertencia `ADDRESS_NOT_VERIFIED`, cuya acción es la `address_not_verified_action` del paso (`NO_ACTION` por defecto, que solo registra la advertencia).
Una validación `unavailable` nunca la genera y nunca modifica la verificación.

## Comportamiento en sandbox

Las claves de sandbox validan la solicitud y siempre devuelven un resultado `verified` determinista que repite la dirección que enviaste. No consumen créditos.

## Facturación

Una llamada a la API de Validación de direcciones cuesta $0.10 por dirección validada.
Un resultado `unavailable` no se cobra.
En un flujo, el complemento cuesta $0.10 por cada dirección validada por un paso.


## OpenAPI

````yaml es/openapi-25.json POST /v3/address-validation/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificación de identidad. Autentícate con el encabezado x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: Validar una dirección
      description: >-
        Confirma que una dirección existe y obtenla normalizada: sus líneas de
        entrega, sus componentes y sus coordenadas. Solo confirma la dirección;
        nunca la vincula a una persona.


        **Solicitud.** Envía la dirección en una sola línea (`address`) o como
        campos estructurados (`address_line_1` y, de forma opcional,
        `address_line_2`, `city`, `region`, `postal_code`), nunca ambas cosas, y
        siempre su `country` (ISO 3166-1 alfa-2 o alfa-3).


        **Resultado.** `address_validation.status` es `verified` (confirmada
        hasta el edificio), `partially_verified` (confirmada solo hasta la calle
        o un nivel superior), `not_verified` (solo coincidió la región o la
        ciudad, o no coincidió nada) o `unavailable` (no se pudo ejecutar la
        validación). El código HTTP es `200` para toda solicitud completada,
        incluido `unavailable`; vuelve a intentarlo más tarde si obtienes un
        resultado `unavailable`.


        **Facturación.** Una llamada en producción cuesta $0.10 por dirección
        validada. Un resultado `unavailable` no se cobra. No se almacena nada
        aparte del registro de uso: no se crea ninguna sesión y el resultado
        solo se devuelve en esta respuesta.


        **Sandbox.** Las claves de sandbox validan la solicitud y siempre
        devuelven un resultado `verified` determinista que repite la dirección
        enviada, sin consumir créditos.


        **Autenticación.** Envía la clave de API de tu aplicación en
        `x-api-key`. Si las credenciales faltan o no son válidas, se devuelve
        `403`: esta API nunca devuelve `401`.


        **Límite de solicitudes.** Presupuesto de escritura compartido de 300
        solicitudes por minuto por clave de API entre todos los endpoints
        POST/PATCH/DELETE.
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: Campos estructurados de la dirección
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: La dirección completa en una sola línea
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            La validación se completó. Lee `address_validation.status`; el
            código HTTP es siempre `200` para una solicitud completada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: Una dirección real, confirmada hasta el 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 calle inventada: solo coincidió la ciudad'
                  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: No se pudo ejecutar la validación; no se cobra
                  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 dirección: en una sola línea (`address`) o como campos estructurados
        con al menos `address_line_1`, nunca ambas cosas.
      properties:
        address:
          type: string
          maxLength: 500
          description: La dirección completa en una sola línea.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: Calle y número.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: Apartamento, oficina, planta o edificio.
        city:
          type: string
          maxLength: 128
          description: Ciudad o localidad.
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: Estado, provincia o región.
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: Código ISO 3166-1 alpha-2 o alpha-3 del país de la dirección.
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Identificador de esta solicitud; indícalo al contactar con soporte.
            No se crea ninguna sesión.
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: >-
        El resultado de una validación de dirección: si la dirección existe y su
        forma normalizada. Solo confirma la dirección; nunca la vincula 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`: la dirección se confirmó hasta el edificio (o el piso o
            el apartado de correos). `partially_verified`: se confirmó solo
            hasta la calle, o hasta el nivel más preciso que contienen los datos
            postales de referencia para ese lugar. `not_verified`: solo
            coincidió la región o la ciudad, o no coincidió nada. `unavailable`:
            la validación no pudo ejecutarse (por ejemplo, el servicio de
            referencia no respondió); no se cobra y nunca afecta a una
            verificación.
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: >-
            El nivel más preciso con el que coincidió la dirección. `null`
            cuando no hubo ninguna coincidencia o `status` es `unavailable`.
        address:
          type: object
          nullable: true
          description: La dirección normalizada. `null` cuando `status` es `unavailable`.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: >-
                Primera línea de la dirección de entrega, escrita según el
                formato del país.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: >-
                Segunda línea de entrega (un piso, edificio o barrio), cuando la
                dirección la tiene.
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: Estado, provincia o región.
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: Código de país ISO 3166-1 alfa-2.
              example: US
        formatted_address:
          type: string
          nullable: true
          description: La dirección normalizada en una sola línea.
          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 cuerpo de la solicitud no es válido: falta `country` o es
        desconocido, no hay dirección, o se enviaron tanto `address` como los
        campos estructurados.
      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 clave de API o no es válida, una clave con alcance limitado no
        tiene acceso de escritura a `sessions`, o la organización no puede
        cubrir la validación. Esta API nunca devuelve `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: >-
        Se superó el límite de escritura compartido de 300 solicitudes por
        minuto por clave de API. Respeta `Retry-After` antes 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 clave de API de tu aplicación, que encontrarás en Developers -> API
        keys en la Business Console. La clave principal tiene acceso completo.
        Una clave con nombre puede tener un alcance limitado: ninguno, lectura o
        escritura por recurso, limitada a algunos flujos o a sesiones aprobadas,
        a una lista de direcciones IP y a una fecha de caducidad. 401 significa
        que la clave es incorrecta, se revocó o expiró; 403 significa que no se
        envió ninguna clave, que la clave no tiene acceso a este recurso o
        acción, o que la solicitud provino de una dirección fuera de su lista de
        IP; 404 en una ruta de sesión significa que la sesión está fuera de los
        flujos o estados de la clave. Una clave sin acceso a contenido
        multimedia recibe las URL de imágenes, videos y PDF como null, y una
        clave sin permiso de escritura en sesiones recibe los enlaces y tokens
        de sesión como null. Consulta https://docs.didit.me/console/api-keys.

````

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