> ## 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 Registri KYB: Pencarian dan Pemilihan Perusahaan

> Cari registri perusahaan di Didit, lalu ambil data sesuai tingkat Anda: Lite (select), Shareholders, atau UBO, dengan harga per negara.

## Endpoints dan penagihan

Pencarian mandiri yang berhasil menggunakan sumber data perusahaan berbayar dikenakan biaya **\$0.50 per permintaan**, berapa pun jumlah kandidatnya. Hasil kosong, pencarian yang gagal, dan hasil yang hanya berasal dari sumber lain tidak dikenakan biaya. Pengambilan profil berikutnya ditagih secara terpisah.

Pengambilan data dijual dalam tiga tingkat data, masing-masing dengan satu endpoint, dan harganya ditetapkan per negara ([harga per negara](https://docs.didit.me/id/getting-started/kyb-registry-pricing.md)):

| Endpoint | Yang Anda dapatkan | Harga |
| - | - | - |
| [`POST /v3/kyb/search/`](https://docs.didit.me/id/standalone-apis/kyb-registry-search) | Kandidat perusahaan: nama, nomor registrasi, status, jenis | \$0.50 saat hasil dari sumber berbayar dikembalikan |
| [`POST /v3/kyb/select/`](https://docs.didit.me/id/standalone-apis/kyb-registry-select) | **Lite**: profil perusahaan (identifikator, status, bentuk hukum, tanggal pendirian, alamat terdaftar, aktivitas, dan detail kontak) serta para pejabat perusahaan | Harga Lite: \$2.00-\$3.00 tergantung negara |
| [`POST /v3/kyb/shareholders/`](https://docs.didit.me/id/standalone-apis/kyb-registry-shareholders) | Lite ditambah pemegang saham langsung beserta rentang kepemilikannya | Harga Shareholders: \$5.00-\$22.00 tergantung negara |
| [`POST /v3/kyb/ubo/`](https://docs.didit.me/id/standalone-apis/kyb-registry-ubo) | Shareholders ditambah pemilik manfaat akhir (UBO) yang ditentukan melalui rantai kepemilikan | Harga UBO: \$9.00-\$96.00 tergantung negara |

`select` adalah tingkat Lite: inilah yang ditagihkan oleh alur kerja KYB yang di-hosting untuk pemeriksaan registri pada tingkat Lite, dan endpoint ini tetap mempertahankan kontraknya seperti sebelumnya. Eropa berarti EEA, Inggris, dan Swiss.

Pencarian Shareholders atau UBO meminta data dari sumber kepemilikan yang melayani tingkat tersebut. Ketika sumber itu menjawab bahwa ia tidak memiliki data perusahaan tersebut, pencarian juga meminta data dari sumber registri lain di negara tersebut, sehingga perusahaan yang tidak tercantum di sumber kepemilikan tetap ditawarkan sebagai kandidat dan tidak berakhir pada entri manual. Kandidat yang ditemukan dengan cara itu tetap mempertahankan tingkat yang Anda minta: saat diambil, sumber kepemilikan diperiksa ulang, dan jika tetap tidak mencatat perusahaan tersebut, profil Lite yang dikirim dan ditagihkan, dengan `registry_ownership_status: "not_held"`.

> [!NOTE]
>
> **Anda membayar untuk tingkat yang dikirim.** Setiap respons memuat `registry_tier_requested` dan `registry_tier_delivered`. Ketika registri di negara tersebut tidak memiliki data kepemilikan, atau registri tidak memiliki catatan kepemilikan untuk perusahaan yang dipilih, permintaan kepemilikan dikirim dan ditagihkan sebagai tingkat tertinggi yang tersedia (biasanya Lite), dan `registry_ownership_status` menjelaskan alasannya. Permintaan UBO yang laporan hasilnya tidak menyebutkan orang perseorangan sebagai pemilik manfaat dikirim dan ditagihkan sebagai Shareholders.

> [!NOTE]
>
> **Versi.** Endpoint Shareholders dan UBO hanya tersedia di `/v3/`. Biaya pencarian mandiri juga berlaku untuk `/v2/kyb/search/`; pengambilan profil ditagih secara terpisah.

## Status kepemilikan

`registry_ownership_status` menunjukkan apa yang terjadi pada bagian kepemilikan dari permintaan Shareholders atau UBO:

| Nilai | Arti |
| - | - |
| `not_requested` | Panggilan ini adalah pengambilan Lite, jadi tidak ada data kepemilikan yang diminta. |
| `delivered` | Registri menyajikan data kepemilikan, dan tingkat di `registry_tier_delivered` adalah tingkat yang Anda bayar. |
| `not_held` | Registri kepemilikan merespons dan tidak mencantumkan perusahaan ini, sehingga tidak memiliki catatan kepemilikan untuk disajikan. Perusahaan ditemukan oleh sumber registri lain di negara tersebut. Profil Lite disajikan dan ditagihkan sebagai gantinya, dengan `registry_data.ownership_error: "company_not_found"`. |
| `unavailable` | Data kepemilikan tidak disajikan karena alasan lain: catatan yang dimiliki registri tidak mencantumkan pemilik mana pun, atau registri tidak mengembalikan bagian kepemilikan sama sekali, atau registri tidak dapat diminta. `registry_data.ownership_error` menyebutkan alasannya. Profil Lite disajikan dan ditagihkan sebagai gantinya. |
| `pending` | Bagian kepemilikan belum diambil dari registri. Tidak ada yang ditagihkan dan `registry_tier_delivered` bernilai `null` sampai bagian ini diambil. |

`not_held` dan `unavailable` sama-sama disajikan dan ditagihkan sebagai Lite, tetapi keduanya bukan temuan yang sama: `not_held` berarti sumber kepemilikan tidak mencakup perusahaan tersebut, yaitu celah cakupan, sedangkan `unavailable` berarti data tidak disajikan karena gangguan atau bagian yang dikosongkan registri. `registry_data.ownership_error` menyebutkan alasannya. Seleksi yang sebelumnya melaporkan `unavailable` karena registri kepemilikan tidak mencantumkan perusahaan kini melaporkan `not_held`. Jika Anda bercabang berdasarkan status, perlakukan keduanya sebagai penyajian Lite yang sama. Dua nilai berikut memiliki arti berbeda dan tidak boleh dibaca sebagai temuan yang sama:

| `ownership_error` | Arti |
| - | - |
| `no_owners_on_record` | Registri merespons bagian kepemilikan dan tidak menyebutkan pemilik mana pun. Perusahaan tidak memiliki tabel kepemilikan saham (cap table) di registri tersebut. |
| `ownership_section_unavailable` | Registri tidak mengembalikan bagian kepemilikan, sehingga tidak ada yang disajikan untuk bagian ini. Daftarnya hilang, bukan kosong. Daftar ini tidak menyatakan apa pun tentang siapa pemilik perusahaan. |

Bagian yang tidak dikembalikan oleh registri juga dicatat secara terstruktur di `registry_data.section_errors`, dikelompokkan menurut bagian (`officers`, `shareholders`, `group_structure`) dengan status yang diberikan oleh registri:

```json theme={null}
{
  "section_errors": {
    "shareholders": {
      "status_code": 404
    }
  }
}
```

`section_errors` menggambarkan jawaban yang Anda pegang, bukan riwayat di baliknya. Bagian yang tidak dikembalikan pada permintaan pertama lalu disajikan pada pengambilan berikutnya (lihat pengambilan asinkron di bawah) akan kehilangan entrinya. Dengan begitu, `registry_ownership_status`, `ownership_error` dan `section_errors` selalu konsisten: bagian yang `delivered` tidak pernah memiliki entri, dan `no_owners_on_record` tidak pernah disertai entri untuk `shareholders`. Sebuah bagian juga tidak pernah disajikan sebagian. Jika registri menyajikan halaman pertama dari sebuah daftar lalu gagal menyajikan halaman berikutnya, pengambilan tidak selesai pada percobaan tersebut. Pengambilan yang `pending` dicoba ulang pada percobaan berikutnya, dan permintaan baru dijawab dengan error registri tidak tersedia. Oleh karena itu, daftar `officers` atau pemegang saham yang disajikan selalu merupakan daftar lengkap yang dimiliki registri. Perlakukan bagian yang tercantum di `section_errors` sebagai data yang tidak pernah disajikan, bukan sebagai hasil kosong. Daftar `officers` atau pemegang saham yang kosong beserta entri `section_errors` untuk bagian tersebut tidak menyatakan apa pun tentang perusahaan.

### Kepemilikan diambil secara asinkron

Beberapa registri dikueri sesuai kebutuhan. Permintaan pertama untuk perusahaan yang belum pernah ditelusuri dari sumber tersebut tidak mengembalikan bagian kepemilikan selagi data diambil, dan data tiba dalam beberapa menit. Melaporkannya sebagai "tidak ada kepemilikan tercatat" akan meremehkan perusahaan yang sebenarnya memiliki pemegang saham, sehingga permintaan dikembalikan dengan status `pending`.

Selama pengambilan `pending`, `fetch_status` juga `pending` dan status respons adalah `202 Accepted`. Didit mencoba ulang bagian tersebut secara mandiri dan menyelesaikan pengambilan tanpa panggilan tambahan dari Anda:

* Begitu data kepemilikan tiba, pemegang saham dan pemilik manfaat muncul pada pemeriksaan yang tersimpan, `registry_tier_delivered` menjadi tingkat yang disajikan, dan penggunaannya ditagihkan pada tingkat tersebut.
* Jika bagian masih kosong saat jendela percobaan ulang ditutup, statusnya menjadi `unavailable` dan permintaan disajikan serta ditagihkan sebagai Lite.

Simpan `request_id` dan lakukan polling ke `GET /v3/session/{request_id}/decision/` hingga `registry_checks[0].company.fetch_status` bernilai `resolved`. Jangan mengulangi permintaan pengambilan selama statusnya `pending`: setiap `POST` baru adalah permintaan terpisah yang ditagihkan secara terpisah.

Gunakan `POST /v3/kyb/search/` untuk mencari kandidat perusahaan. Pencarian tidak membuat pemeriksaan yang tersimpan. Input `tier` pada pencarian menentukan rantai yang dicari, lihat [tingkat pencarian](https://docs.didit.me/id/standalone-apis/kyb-registry-search.md#tingkat-pencarian).

Pencarian registri dapat memakan waktu sekitar 90 detik. Kirim `webhook_url` jika Anda ingin Didit segera merespons dan mengirim notifikasi ke URL Anda saat kandidat sudah siap. Callback pencarian sengaja tidak ditandatangani, jadi Anda tidak perlu mengonfigurasi rahasia bersama untuk notifikasi ringan ini.

Gunakan `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` atau `POST /v3/kyb/ubo/` dengan `kyb_response_id` yang dikembalikan untuk mengambil profil pada tingkat yang Anda butuhkan. Pengambilan ini ditagihkan dan menyimpan hasilnya sebagai Manual Check di Business Console.

## Alur umum

1. Cari berdasarkan nama perusahaan, nomor registrasi dan negara, pada `tier` yang ingin Anda beli (`basic` adalah rantai Lite default; `shareholders` dan `ubo` mencari rantai tingkat tersebut).
2. Jika `search_resolved=false`, tunggu callback `webhook_url` opsional alih-alih melakukan polling.
3. Tampilkan kandidat yang dikembalikan kepada operator atau pelanggan Anda.
4. Ambil `kyb_response_id` yang cocok pada tingkat yang Anda butuhkan (select untuk Lite, shareholders, atau ubo).
5. Simpan `request_id` yang dikembalikan dan gunakan untuk mengambil hasil verifikasi bisnis yang tersimpan.

## Callback pencarian

Ketika penyedia memberi tahu Didit bahwa pencarian telah selesai, Didit mengirimkan satu `POST` ke `webhook_url` Anda:

```json theme={null}
{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}
```

Perlakukan callback sebagai notifikasi pengiriman. Gunakan `kyb_response_id` yang dikembalikan dengan `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` atau `POST /v3/kyb/ubo/` untuk menjalankan pengambilan profil registri yang dikenakan biaya.


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