> ## 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 Validasi Alamat: Verifikasi dan Normalisasi Alamat

> Didit POST /v3/address-validation/ memastikan alamat ada dan mengembalikannya ternormalisasi dengan koordinat. $0.10 per alamat.

Didit Address Validation API memastikan bahwa sebuah alamat pos ada, lalu mengembalikannya dalam bentuk yang sudah dinormalisasi, lengkap dengan baris pengiriman, komponen, dan koordinatnya. Gunakan `POST /v3/address-validation/` ketika backend Anda memiliki sebuah alamat dan perlu mengetahui apakah alamat itu ada, serta dalam bentuk normalisasi apa.

Address Validation hanya memastikan alamatnya. Layanan ini tidak pernah mengaitkan alamat dengan seseorang: hasil `verified` berarti tempatnya ada, bukan berarti ada orang yang tinggal di sana.

## Kirim alamat

Kirim alamat dalam satu baris di `address`, atau sebagai kolom terstruktur: `address_line_1` dan, jika Anda memilikinya, `address_line_2`, `city`, `region`, dan `postal_code`.
Jangan pernah mengirim kedua bentuk tersebut dalam satu permintaan.
`country` selalu wajib diisi, dalam kode ISO 3166-1 alpha-2 atau alpha-3.

## Menafsirkan respons

* `address_validation.status` adalah jawaban yang menjadi dasar keputusan Anda:
  * `verified`: alamat dikonfirmasi sampai ke tingkat gedung (atau unit apartemen atau kotak pos).
  * `partially_verified`: alamat hanya dikonfirmasi sampai ke tingkat jalan, atau sampai tingkat paling presisi yang dimiliki data referensi pos untuk tempat tersebut.
  * `not_verified`: hanya wilayah atau kota yang cocok, atau tidak ada yang cocok.
  * `unavailable`: validasi tidak dapat dijalankan. Coba lagi nanti.
* `address_validation.verification_level` adalah tingkat paling presisi yang cocok: `administrative_area`, `locality`, `thoroughfare`, `premise`, atau `delivery_point`.
* `address_validation.address` dan `address_validation.formatted_address` memuat alamat yang sudah dinormalisasi, ditulis sesuai cara negara tersebut menulis alamat.
* `address_validation.latitude` dan `address_validation.longitude` menunjukkan lokasi alamat yang cocok.
* `request_id` mengidentifikasi permintaan. Tidak ada sesi yang dibuat dan hasilnya hanya dikembalikan dalam respons ini, jadi simpan apa pun yang Anda butuhkan.

HTTP-nya adalah `200` untuk setiap permintaan yang selesai, termasuk `unavailable`.

## Address Validation di dalam alur kerja

Pemeriksaan yang sama tersedia sebagai add-on pada langkah alur kerja Verifikasi Identitas dan Bukti Alamat.
Aktifkan `address_validation_enabled` di pengaturan langkah tersebut, dan alamat yang diberikan pengguna (tercetak pada dokumen identitas, atau pada bukti alamat) akan divalidasi satu kali setelah unggahannya dibaca.
Hasilnya berupa objek `address_validation` dalam entri langkah tersebut pada keputusan sesi (`id_verifications[]` atau `poa_verifications[]`).
Alamat dengan status `partially_verified` atau `not_verified` memunculkan peringatan `ADDRESS_NOT_VERIFIED`, yang tindakannya mengikuti `address_not_verified_action` pada langkah tersebut (secara default `NO_ACTION`, yang hanya mencatat peringatan).
Validasi dengan status `unavailable` tidak pernah memunculkan peringatan tersebut dan tidak pernah mengubah verifikasi.

## Perilaku sandbox

Kunci sandbox memvalidasi permintaan dan selalu mengembalikan hasil `verified` yang deterministik, yang mengembalikan alamat yang Anda kirim. Kunci sandbox tidak menggunakan kredit.

## Penagihan

Satu panggilan Address Validation API dikenakan biaya $0.10 per alamat yang divalidasi.
Hasil `unavailable` tidak dikenakan biaya.
Dalam alur kerja, add-on dikenakan biaya $0.10 per alamat yang divalidasi oleh sebuah langkah.


## OpenAPI

````yaml id/openapi-25.json POST /v3/address-validation/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API Verifikasi Identitas. Lakukan autentikasi dengan header x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: Validasi alamat
      description: >-
        Konfirmasikan bahwa suatu alamat memang ada dan dapatkan kembali dalam
        bentuk dinormalisasi: baris pengiriman, komponen, dan koordinatnya. Ini
        hanya mengonfirmasi alamat; tidak pernah menautkan alamat ke seseorang.


        **Permintaan.** Kirim alamat dalam satu baris (`address`) atau sebagai
        kolom terstruktur (`address_line_1` dan, secara opsional,
        `address_line_2`, `city`, `region`, `postal_code`), jangan pernah
        keduanya, dan selalu sertakan `country`-nya (ISO 3166-1 alpha-2 atau
        alpha-3).


        **Hasil.** `address_validation.status` bernilai `verified`
        (terkonfirmasi hingga ke bangunan), `partially_verified` (hanya
        terkonfirmasi hingga ke jalan atau di atasnya), `not_verified` (hanya
        wilayah atau kota yang cocok, atau tidak ada yang cocok) atau
        `unavailable` (validasi tidak dapat dijalankan). HTTP bernilai `200`
        untuk setiap permintaan yang selesai, termasuk `unavailable`; coba lagi
        hasil `unavailable` nanti.


        **Penagihan.** Panggilan produksi berbiaya $0.10 per alamat yang
        divalidasi. Hasil `unavailable` tidak dikenakan biaya. Tidak ada yang
        disimpan selain catatan penggunaan: tidak ada sesi yang dibuat dan
        hasilnya hanya dikembalikan dalam respons ini.


        **Sandbox.** Kunci sandbox memvalidasi permintaan dan selalu
        mengembalikan hasil deterministik `verified` yang mencerminkan alamat
        yang dikirim, tanpa menghabiskan kredit.


        **Autentikasi.** Kirim kunci API aplikasi Anda di `x-api-key`.
        Kredensial yang hilang atau tidak valid mengembalikan `403` - API ini
        tidak pernah mengembalikan `401`.


        **Batas laju.** Anggaran penulisan bersama sebesar 300 permintaan per
        menit per kunci API di seluruh endpoint POST/PATCH/DELETE (pembuatan
        transaksi dan penyerapan event memiliki anggaran terpisah sebesar 600).
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: Kolom alamat terstruktur
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: Seluruh alamat dalam satu baris
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            Validasi selesai. Baca `address_validation.status`; HTTP selalu
            `200` untuk permintaan yang selesai.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: Alamat riil, terkonfirmasi hingga tingkat bangunan
                  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: 'Jalan yang dibuat-buat: hanya kota yang cocok'
                  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: Validasi tidak dapat dijalankan; tidak dikenakan biaya
                  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: >-
        Satu alamat: dalam satu baris (`address`) atau sebagai kolom terstruktur
        dengan setidaknya `address_line_1`, tidak boleh keduanya.
      properties:
        address:
          type: string
          maxLength: 500
          description: Seluruh alamat dalam satu baris.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: Jalan dan nomor.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: Apartemen, suite, lantai, atau gedung.
        city:
          type: string
          maxLength: 128
          description: Kota atau lokalitas.
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: Negara bagian, provinsi, atau wilayah.
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: Kode ISO 3166-1 alpha-2 atau alpha-3 dari negara alamat.
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Pengenal permintaan ini; kutip ke tim dukungan. Tidak ada sesi yang
            dibuat.
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: >-
        Hasil dari satu Validasi Alamat: apakah alamat tersebut ada, dan bentuk
        yang telah dinormalisasi. Ini hanya mengonfirmasi alamat; ini tidak
        pernah menautkan alamat ke seseorang.
      required:
        - status
        - verification_level
        - address
        - formatted_address
        - latitude
        - longitude
      properties:
        status:
          type: string
          enum:
            - verified
            - partially_verified
            - not_verified
            - unavailable
          description: >-
            `verified`: alamat dikonfirmasi hingga ke bangunan (atau apartemen
            atau kotak pos). `partially_verified`: alamat hanya dikonfirmasi
            hingga ke jalan, atau hingga tingkat paling tepat yang dimiliki data
            referensi pos untuk tempat tersebut. `not_verified`: hanya wilayah
            atau kota yang cocok, atau tidak ada yang cocok. `unavailable`:
            validasi tidak dapat dijalankan (misalnya layanan referensi tidak
            merespons); validasi ini tidak dikenai biaya dan tidak pernah
            memengaruhi verifikasi.
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: >-
            Tingkat paling presisi yang dicocokkan dengan alamat. `null` jika
            tidak ada yang cocok atau `status` bernilai `unavailable`.
        address:
          type: object
          nullable: true
          description: >-
            Alamat yang dinormalisasi. `null` jika `status` adalah
            `unavailable`.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: >-
                Baris pengiriman pertama, ditulis sesuai dengan format penulisan
                di negara tersebut.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: >-
                Baris pengiriman kedua (apartemen, gedung, atau lingkungan
                sekitar), jika alamat memilikinya.
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: Negara bagian, provinsi, atau wilayah.
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: Kode negara ISO 3166-1 alpha-2.
              example: US
        formatted_address:
          type: string
          nullable: true
          description: Alamat yang dinormalisasi dalam satu baris.
          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: >-
        Body permintaan tidak valid: `country` tidak ada atau tidak dikenal,
        tidak ada alamat, atau menyertakan `address` sekaligus kolom
        terstruktur.
      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: >-
        Kunci API tidak ada atau tidak valid, kunci dengan cakupan terbatas
        tidak memiliki akses tulis `sessions`, atau organisasi tidak dapat
        menanggung biaya validasi. API ini tidak pernah mengembalikan `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: >-
        Batas tulis bersama sebesar 300 permintaan per menit per kunci API telah
        terlampaui. Patuhi `Retry-After` sebelum mencoba lagi.
      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: >-
        Kunci API aplikasi Anda, dari Developers -> API keys di Business
        Console. Kunci utama memiliki akses penuh. Kunci bernama dapat diberi
        cakupan: none, read, atau write per sumber daya, dibatasi pada beberapa
        alur kerja atau pada sesi yang disetujui, pada daftar alamat IP, dan
        pada tanggal kedaluwarsa. 401 berarti kuncinya salah, dicabut, atau
        kedaluwarsa; 403 berarti tidak ada kunci yang dikirimkan, kunci tidak
        memiliki akses ke sumber daya atau tindakan ini, atau permintaan datang
        dari alamat di luar daftar IP-nya; 404 pada rute sesi berarti sesi
        berada di luar alur kerja atau status kunci tersebut. Kunci tanpa akses
        media menerima URL gambar, video, dan PDF sebagai null, dan kunci tanpa
        izin tulis sesi menerima tautan sesi dan token sebagai null. Lihat
        https://docs.didit.me/console/api-keys.

````

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