> ## 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: 주소 확인 및 정규화

> Didit의 POST /v3/address-validation/은 주소가 실제로 존재하는지 확인하고 좌표가 포함된 정규화된 주소를 반환합니다. 구조화된 입력과 한 줄 입력 모두 지원하며, 주소당 $0.10입니다.

Didit의 주소 검증 API는 우편 주소가 실제로 존재하는지 확인하고, 정규화된 형태를 배송 주소 행, 구성 요소, 좌표와 함께 반환합니다. 백엔드에 주소가 있고 그 주소가 존재하는지, 그리고 어떤 정규화된 형태인지 알아야 할 때 `POST /v3/address-validation/`를 사용하세요.

주소 검증은 주소만 확인합니다. 주소를 사람과 연결하지는 않습니다. `verified` 결과는 해당 장소가 존재한다는 뜻이며, 누군가 그곳에 살고 있다는 뜻은 아닙니다.

## 주소 전송

한 줄로 된 `address`로 보내거나, 구조화된 필드로 보낼 수 있습니다. 구조화된 필드는 `address_line_1`과, 가지고 있다면 `address_line_2`, `city`, `region`, `postal_code`입니다.
한 요청에 두 형식을 함께 보내지 마세요.
`country`는 항상 필수이며, ISO 3166-1 alpha-2 또는 alpha-3 코드로 입력합니다.

## 응답 해석

* `address_validation.status`는 판단의 기준이 되는 값입니다:
  * `verified`: 건물(또는 호실, 사서함)까지 주소가 확인되었습니다.
  * `partially_verified`: 도로까지만 확인되었거나, 해당 장소에 대해 우편 참조 데이터가 보유한 가장 정밀한 수준까지만 확인되었습니다.
  * `not_verified`: 지역 또는 도시만 일치했거나, 아무것도 일치하지 않았습니다.
  * `unavailable`: 검증을 실행할 수 없었습니다. 나중에 다시 시도하세요.
* `address_validation.verification_level`은 일치한 가장 정밀한 수준으로, `administrative_area`, `locality`, `thoroughfare`, `premise`, `delivery_point` 중 하나입니다.
* `address_validation.address`와 `address_validation.formatted_address`에는 해당 국가의 표기 방식에 맞춘 정규화된 주소가 담깁니다.
* `address_validation.latitude`와 `address_validation.longitude`는 일치한 주소의 위치를 나타냅니다.
* `request_id`는 요청을 식별합니다. 세션은 생성되지 않으며 결과는 이 응답으로만 반환되므로, 필요한 정보는 직접 저장해 두세요.

완료된 모든 요청의 HTTP 상태 코드는 `unavailable`을 포함해 `200`입니다.

## 워크플로 내 주소 검증

같은 검사는 신분증 인증 및 주소 증명 워크플로 단계의 추가 기능으로도 제공됩니다.
단계 설정에서 `address_validation_enabled`를 켜면, 사용자가 제공한 주소(신분증에 인쇄된 주소 또는 주소 증명 문서의 주소)가 업로드가 판독된 후 한 번 검증됩니다.
결과는 세션 결정의 해당 단계 항목(`id_verifications[]` 또는 `poa_verifications[]`)에 있는 `address_validation` 객체입니다.
`partially_verified` 또는 `not_verified` 주소는 `ADDRESS_NOT_VERIFIED` 경고를 발생시킵니다. 이 경고의 작업은 단계의 `address_not_verified_action`이며, 기본값은 `NO_ACTION`(경고를 기록만 함)입니다.
`unavailable` 검증은 이 경고를 발생시키지 않으며, 인증 결과를 절대 변경하지 않습니다.

## 샌드박스 동작

샌드박스 키는 요청을 검증하고, 전송한 주소를 그대로 되돌려 주는 결정론적 `verified` 결과를 항상 반환합니다. 크레딧은 소모되지 않습니다.

## 과금

주소 검증 API 호출은 검증된 주소당 $0.10입니다. `unavailable` 결과는 과금되지 않습니다.
워크플로에서 추가 기능은 단계가 검증한 주소당 $0.10입니다.


## OpenAPI

````yaml ko/openapi-25.json POST /v3/address-validation/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: 주소 검증
      description: >-
        주소가 존재하는지 확인하고 정규화된 형태(배송 주소 행, 구성 요소, 좌표)로 반환받습니다. 주소 자체만 확인하며, 주소를 특정
        개인과 연결하지는 않습니다.


        **요청.** 주소를 한 줄(`address`) 또는 구조화된 필드(`address_line_1` 및 선택 사항인
        `address_line_2`, `city`, `region`, `postal_code`) 중 하나로 전송해야 하며(둘 다 전송
        불가), `country`(ISO 3166-1 alpha-2 또는 alpha-3)는 항상 포함해야 합니다.


        **결과.** `address_validation.status`는 `verified`(건물 단위까지 확인됨),
        `partially_verified`(도로명 단위 이상만 확인됨), `not_verified`(지역 또는 도시만 일치하거나
        일치하는 정보가 없음), `unavailable`(검증을 실행할 수 없음) 중 하나입니다. `unavailable`을 포함하여
        완료된 모든 요청에 대해 HTTP는 `200`입니다. `unavailable` 결과는 나중에 재시도하세요.


        **결제.** 프로덕션 호출은 검증된 주소당 $0.10가 청구됩니다. `unavailable` 결과에는 요금이 청구되지 않습니다.
        사용 기록 외에는 아무것도 저장되지 않습니다. 세션이 생성되지 않으며 결과는 이 응답에만 반환됩니다.


        **샌드박스.** 샌드박스 키는 요청을 검증하고 크레딧을 소비하지 않으면서 전송된 주소를 그대로 반영하는 결정론적
        `verified` 결과를 항상 반환합니다.


        **인증.** 애플리케이션의 API 키를 `x-api-key`에 넣어 전송하세요. 자격 증명이 누락되었거나 유효하지 않으면
        `403`이 반환됩니다. 이 API는 `401`을 반환하지 않습니다.


        **속도 제한.** API 키당 POST/PATCH/DELETE endpoint 전체에 분당 300건의 공유 쓰기 예산이
        적용됩니다(거래 생성 및 이벤트 수집에는 별도의 600건 예산 적용).
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: 구조화된 주소 필드
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: 한 줄로 작성된 전체 주소
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            검증이 완료되었습니다. `address_validation.status`를 확인하세요. 완료된 요청의 HTTP 상태는 항상
            `200`입니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: 건물 단위까지 확인된 실제 주소
                  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: '가상의 거리 이름: 도시만 일치함'
                  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: 검증을 실행할 수 없음. 요금 미청구
                  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: >-
        주소 1개입니다. 한 줄(`address`)로 입력하거나 최소 `address_line_1`을 포함하는 구조화된 필드로 입력할 수
        있으며, 두 방식을 동시에 사용할 수는 없습니다.
      properties:
        address:
          type: string
          maxLength: 500
          description: 한 줄로 작성된 전체 주소입니다.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: 도로명 및 번호.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: 아파트, 호수, 층 또는 건물입니다.
        city:
          type: string
          maxLength: 128
          description: 시 또는 지역입니다.
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: 주, 도 또는 지역입니다.
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: 주소 국가의 ISO 3166-1 alpha-2 또는 alpha-3 코드입니다.
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: 이 요청의 식별자입니다. 지원팀에 문의할 때 언급하십시오. 세션은 생성되지 않습니다.
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: >-
        단일 Address Validation 결과입니다. 주소의 존재 여부 및 정규화된 형태를 나타냅니다. 주소만 확인하며, 결코
        주소를 개인과 연결하지 않습니다.
      required:
        - status
        - verification_level
        - address
        - formatted_address
        - latitude
        - longitude
      properties:
        status:
          type: string
          enum:
            - verified
            - partially_verified
            - not_verified
            - unavailable
          description: >-
            `verified`: 주소가 건물(또는 호수, 사서함) 단위까지 확인되었습니다. `partially_verified`:
            도로명 단위까지 또는 해당 지역에 대해 우편 참조 데이터가 보유한 가장 정밀한 수준까지만 확인되었습니다.
            `not_verified`: 지역 또는 도시만 일치했거나 아무것도 일치하지 않았습니다. `unavailable`: 검증을
            실행할 수 없었습니다(예: 참조 서비스가 응답하지 않음). 비용이 청구되지 않으며 인증에 영향을 주지 않습니다.
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: >-
            주소가 일치한 가장 정밀한 수준입니다. 일치하는 항목이 없거나 `status`가 `unavailable`인 경우
            `null`입니다.
        address:
          type: object
          nullable: true
          description: 정규화된 주소입니다. `status`가 `unavailable`인 경우 `null`입니다.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: 해당 국가의 표기 방식에 따른 첫 번째 주소 라인입니다.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: 주소에 있는 경우 두 번째 배송 주소 라인(아파트, 건물 또는 주변 지역).
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: 주, 도 또는 지역입니다.
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: ISO 3166-1 alpha-2 국가 코드입니다.
              example: US
        formatted_address:
          type: string
          nullable: true
          description: 한 줄로 정규화된 주소입니다.
          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: >-
        요청 본문이 잘못되었습니다. `country`가 누락되었거나 알 수 없음, 주소 없음, 또는 `address`와 구조화된 필드가
        모두 포함되어 있습니다.
      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: >-
        API 키가 누락되었거나 유효하지 않음, 스코프 키에 `sessions` 쓰기 권한이 없음, 또는 조직이 검증 비용을 충당할 수
        없습니다. 이 API는 절대 `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: >-
        API 키당 분당 300개의 요청을 처리하는 공유 쓰기 속도 제한을 초과했습니다. 다시 시도하기 전에 `Retry-After`를
        준수하십시오.
      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: >-
        Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본
        키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며
        특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나
        만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된
        IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를
        벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write
        권한이 없는 키는 세션 링크와 token을 null로 수신합니다.
        https://docs.didit.me/console/api-keys 를 참고하십시오.

````

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