Langsung ke konten utama
POST
Python
Gunakan panduan ini untuk memilih jalur impor yang tepat saat Anda memindahkan data dari penyedia lain ke Didit. Ada dua pekerjaan berbeda yang sering disebut “impor” oleh pelanggan:
  • Impor riwayat pekerjaan verifikasi: membuat ulang catatan KYC, KYB, pemantauan transaksi, atau aturan alur kerja yang sudah selesai agar Didit menampilkan riwayat dari penyedia lama. Gunakan POST /v3/session/imports/.
  • Impor data operasional: membuat Pengguna, Bisnis, wajah profil, entri daftar blokir, atau entri daftar izin agar Didit dapat menggunakannya dalam pemeriksaan mendatang. Gunakan API entitas, wajah, dan daftar.
Impor verifikasi membuat catatan riwayat dengan session_type: "MIGRATED" untuk KYC dan KYB. Impor tersebut tidak mengirim email ke pengguna akhir, tidak mengarahkan pengguna ke alur yang di-hosting, dan tidak menjalankan ulang verifikasi asli. Catatan yang diimpor muncul di daftar sesi, profil entitas, tampilan transaksi, dan GET /v3/session/{session_id}/decision/ jika berlaku.

Impor mana yang harus Anda gunakan?

Jika Anda hanya memerlukan profil pengguna atau bisnis untuk pemeriksaan mendatang, jangan impor sesi verifikasi historis. Gunakan API entitas Pengguna atau Bisnis. Jika Anda ingin keputusan, kolom dokumen, peringatan, atau bukti dari penyedia lama muncul sebagai riwayat kepatuhan di Didit, gunakan POST /v3/session/imports/.

Apa yang bisa dimigrasikan dari setiap penyedia?

Didit menerima file CSV atau NDJSON kanonis, sehingga Anda dapat bermigrasi dari penyedia mana pun setelah mengekspor dan mengubah datanya. Kontrak impor selalu mengikuti skema kanonis Didit.

Alur migrasi

  1. Tentukan apakah Anda mengimpor riwayat, profil, wajah, daftar, transaksi, atau aturan.
  2. Ekspor data dari penyedia lama sendiri. Jangan kirim kunci API penyedia lama ke Didit.
  3. Ubah ekspor penyedia menjadi templat CSV atau NDJSON kanonis Didit yang sesuai.
  4. Untuk migrasi besar, utamakan NDJSON dan pisahkan ke dalam file yang dapat dicoba lagi secara independen.
  5. Buat tugas impor dan pantau progresnya.
  6. Ambil kesalahan pada baris, perbaiki hanya baris yang gagal, lalu coba lagi. Semua tugas impor bersifat idempoten berdasarkan ID eksternal alaminya.

Buat tugas impor

Buat tugas impor dengan satu permintaan multipart:
Gunakan CSV untuk migrasi kecil yang berbasis spreadsheet dan NDJSON untuk migrasi besar. Untuk 100k+ baris, NDJSON lebih mudah di-stream, dipisah, divalidasi, dan dicoba ulang. Sebuah aplikasi dapat menjalankan hingga 4 tugas impor sekaligus, jadi pecah migrasi besar menjadi beberapa file dan mulai satu tugas untuk setiap file. Setiap tugas mengunduh file media untuk setiap baris secara paralel. Tugas yang terhenti karena penerapan atau mulai ulang pekerja akan melanjutkan dari baris terakhir yang berhasil diimpor secara otomatis, sehingga Anda tidak perlu memulainya ulang. Untuk impor transaksi, hilangkan workflow_id:

Kolom permintaan

Cara catatan dilacak dan dideduplikasi

Tidak ada kolom permintaan untuk sumber data. Setiap impor menggunakan skema kanonis Didit. Setiap catatan yang diimpor menyimpan metadata.imported_from = "generic" untuk keperluan pelacakan. Impor user_verification dan business_verification mendeduplikasi baris berdasarkan external_id di dalam aplikasi, sehingga mencoba ulang file yang sama tidak akan membuat duplikat. Impor transactions mendeduplikasi berdasarkan transaction_id. Migrasi penyedia (source=provider) menyimpan setiap catatan sebagai <provider>:<id>, misalnya sumsub:5f8c0e2a9b1d4c3e2f1a0b9c. Impor file Verifikasi Pengguna yang mengirim ID penyedia tanpa awalan (5f8c0e2a9b1d4c3e2f1a0b9c) dikenali sebagai catatan yang sama, di kedua arah. Oleh karena itu, Anda dapat memulai migrasi melalui file dan menyelesaikannya dengan migrasi penyedia, atau sebaliknya, tanpa mengimpor catatan yang sama dua kali.

Impor foto dokumen, video, dan bukti swafoto

Untuk import_type=user_verification, Anda dapat mengimpor foto dokumen asli, video penangkapan dokumen dan liveness, serta gambar swafoto dari penyedia sebelumnya. Gunakan kolom kanonis berikut: Untuk migrasi besar, gunakan URL HTTPS. Didit mengunduh setiap file, memvalidasi bahwa URL aman, menyimpan salinan yang dimiliki Didit, lalu menautkannya ke sesi yang diimpor. Gambar dikompresi; video disimpan apa adanya. Base64 inline diterima untuk gambar pada impor kecil, tetapi video harus selalu disediakan sebagai URL, karena base64 akan membuat setiap video sekitar 33% lebih besar dan dengan cepat melampaui batas impor per file. Contoh baris NDJSON dengan URL media yang di-hosting penyedia:
Aturan media penting:
  • URL harus menggunakan https.
  • URL tidak boleh mengarah ke IP privat, localhost, rentang link-local, atau host metadata internal.
  • Gambar dapat menggunakan kolom URL atau kolom fallback *_base64-nya; base64 diutamakan jika keduanya diisi. Video hanya menggunakan URL, karena tidak ada kolom *_video_base64.
  • Video harus berformat mp4, webm, atau mov, dan setiap video maksimal 10 MB. File yang lebih besar atau file non-video akan ditolak sebagai error pada baris.
  • Didit menerapkan timeout koneksi/baca dan ukuran file maksimum, serta tidak melakukan percobaan ulang tanpa batas.
  • Kegagalan unduhan media disimpan sebagai error pada baris agar sisa impor tetap berjalan.
  • Jika Anda tidak memiliki media dari penyedia, kosongkan kolom-kolom ini. Didit tetap mengimpor keputusan terstruktur dan kolom dokumen.
  • Gambar dan video yang diimpor adalah bukti untuk peninjauan historis. Secara default, Didit tidak menjalankan ulang analisis OCR, liveness, atau deteksi kecurangan dokumen pada media historis yang diimpor.

Memantau progres

Respons menyertakan status, import_type, total_rows, processed_rows, created_count, updated_count, skipped_count, failed_count, dan checkpoint_row.

Mengunduh error baris

Setiap error menyertakan row_number, external_id, error, dan raw_row, sehingga Anda dapat memperbaiki hanya baris yang gagal dan mencobanya kembali.

Perlindungan dari penyalahgunaan

Job impor historis melalui POST /v3/session/imports/ dinonaktifkan secara default. Didit mengaktifkan kemampuan ini per organisasi setelah peninjauan, karena job ini dapat memproses jutaan baris dan mengunduh media. Impor data operasional normal dalam panduan ini, yaitu membuat Pengguna, membuat Bisnis, mengunggah wajah profil, mengunggah daftar blokir wajah, atau menambahkan entri daftar, tidak memerlukan pengaktifan migrasi khusus selain izin normal untuk kunci API, ketersediaan produk, dan batas laju untuk endpoint tersebut. Job impor historis juga berjalan pada pekerja yang terisolasi dengan batas ukuran file, batas jumlah baris, URL media yang hanya menggunakan HTTPS, pemblokiran URL jaringan privat, batas 4 job impor aktif per aplikasi, dan pencatatan error per baris.

Status kanonis

Idempotensi

Didit menggunakan external_id sebagai kunci idempotensi impor untuk impor Verifikasi Pengguna dan Verifikasi Bisnis, dibatasi per aplikasi. Impor transaksi menggunakan transaction_id per aplikasi. Mencoba ulang file yang sama akan melewati baris yang sudah diimpor dan membuat baris yang belum diproses.

Impor pengguna, wajah profil, dan daftar blokir

Gunakan jalur berikut jika Anda tidak sedang membuat ulang sesi verifikasi yang sudah selesai:

Impor profil pengguna

Buat pengguna dengan POST /v3/users/create/ atau impor CSV Business Console di Impor dan Ekspor Pengguna. Cara ini hanya membuat atau memperbarui profil VendorUser. Cara ini tidak membuat sesi verifikasi, keputusan KYC, laporan dokumen, peringatan, atau riwayat webhook. Gunakan cara ini jika Anda ingin Didit mengetahui bahwa pelanggan tersebut ada sebelum pemeriksaan berikutnya, atau jika Anda perlu melengkapi kolom mirip CRM, misalnya display_name, tag, atau metadata, pada data yang sudah ada.

Unggah wajah profil tepercaya

Setelah profil pengguna tersedia, unggah wajah profil tepercaya dengan POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/. Cara ini melampirkan bukti biometrik ke profil pengguna dan mengindeksnya untuk deteksi duplikat serta pencarian wajah. Cara ini tidak memasukkan wajah ke daftar blokir. Cara ini berguna jika Anda memiliki gambar profil tepercaya dari penyedia KYC sebelumnya dan ingin pemeriksaan Didit berikutnya membandingkannya dengan gambar tersebut.

Impor daftar blokir dan daftar izin wajah

Untuk memblokir atau mengizinkan wajah secara langsung, gunakan POST /v3/lists/{list_uuid}/entries/face-upload/ dengan daftar bertipe wajah. Didit mengekstrak embedding biometrik dan menyimpannya sebagai entri daftar. Gunakan cara ini untuk gambar penipu yang sudah diketahui, wajah dalam daftar izin tepercaya, atau migrasi daftar penipuan dari penyedia. Jika wajah berasal dari sesi Didit yang sudah ada, utamakan POST /v3/lists/{list_uuid}/entries/ dengan reference_session_id. Didit akan mengekstrak wajah yang tepat dari sesi tersebut dan menautkan entri kembali ke sumbernya.

Impor daftar pengguna, bisnis, dokumen, dompet, email, telepon, IP, atau perangkat

Gunakan POST /v3/lists/{list_uuid}/entries/ untuk nilai daftar selain wajah. Jalur ini tepat untuk daftar blokir dan daftar izin dari penyedia, daftar chargeback, alamat dompet, IP berisiko yang sudah diketahui, sidik jari perangkat, nomor dokumen, email, telepon, pengguna, atau bisnis.

Langkah berikutnya

Impor pengguna

Muat profil pengguna dan lampirkan wajah profil tepercaya.

Impor bisnis

Muat profil bisnis sebelum menjalankan KYB.

Unggah wajah profil

Lampirkan gambar wajah tepercaya ke pengguna yang sudah diimpor.

Unggah wajah ke daftar

Tambahkan wajah ke daftar blokir atau daftar izin.

Buat entri daftar

Impor telepon, email, dompet, dokumen, IP, perangkat, pengguna, atau bisnis ke dalam daftar.

Batas laju

Rancang loop migrasi dan coba lagi yang aman.

Otorisasi

x-api-key
string
header
wajib

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.

Body

import_type
enum<string>
default:user_verification

Apa yang akan diimpor: sesi Verifikasi Pengguna historis, sesi Verifikasi Bisnis (KYB) historis, aturan status kustom alur kerja, atau catatan pemantauan transaksi historis.

Opsi yang tersedia:
user_verification,
business_verification,
status_rules,
transactions
workflow_id
string<uuid>

UUID alur kerja tempat sesi yang diimpor atau aturan status harus ditautkan. Wajib diisi untuk user_verification, business_verification, dan status_rules. Abaikan untuk transaksi.

source_format
enum<string>

Opsional. Disimpulkan dari ekstensi file yang diunggah jika tidak diberikan.

Opsi yang tersedia:
csv,
ndjson
file
file

File CSV atau NDJSON kanonis. Gunakan NDJSON untuk impor berukuran besar. Ukuran unggahan maksimum 25 MB (gunakan source_file_url untuk file yang lebih besar). Saling eksklusif dengan source_file_url.

source_file_url
string<uri>

Alternatif untuk unggahan file. Harus berupa URL HTTPS yang mengarah ke alamat publik (jaringan privat/loopback ditolak). Saling eksklusif dengan file.

source
enum<string>

provider menandakan ini adalah migrasi dari penyedia verifikasi identitas lain. Jangan sertakan untuk impor file.

Opsi yang tersedia:
file,
provider
provider
enum<string>

Sumber migrasi, dari GET /v3/session/imports/providers/. Wajib diisi jika source adalah provider.

Opsi yang tersedia:
sumsub,
jumio,
veriff,
onfido,
persona,
metamap,
socure,
idnow,
shufti,
idenfy,
ondato,
trulioo,
au10tix,
complycube,
other
credentials
object

Kunci hanya-baca penyedia, dengan nama kolom yang tercantum dalam credential_fields. Dienkripsi saat disimpan, tidak pernah dikembalikan, dan dihapus saat impor selesai. Kirim sebagai string JSON dalam multipart.

options
object
status_mapping
object

Pengeditan pada pemetaan status default penyedia: status sumber ke status Didit. Not Finished dan Abandoned dilewati dan dihitung, tidak pernah diimpor.

dry_run
boolean
default:false

Hitung apa yang akan diimpor oleh migrasi (berdasarkan status, sudah ada di Didit, orang yang sama, belum selesai) dan tidak menulis apa pun. Pekerjaan berakhir dengan status READY; mulai dengan POST /v3/session/imports/{importId}/start/.

face_templates
boolean
default:false

Buat templat wajah dari swafoto yang diimpor dan cari terhadap wajah serta daftar blokir aplikasi. Kecocokan hanya ditandai untuk ditinjau. Memerlukan lawful_basis_confirmed.

lawful_basis_confirmed
boolean
default:false

Mengonfirmasi bahwa Anda memiliki dasar hukum untuk membagikan swafoto ini kepada Didit sebagai pemroses.

Respons

Pekerjaan impor diterima. Lakukan polling pada uuid yang dikembalikan hingga status menjadi COMPLETED atau FAILED.

uuid
string<uuid>
wajib

ID pekerjaan impor. Gunakan nilai ini untuk melakukan polling progres dan mengambil kesalahan pada baris.

status
enum<string>
wajib
Opsi yang tersedia:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
wajib
Opsi yang tersedia:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
wajib
Opsi yang tersedia:
csv,
ndjson
source_filename
string
wajib
total_rows
integer<int64>
wajib
processed_rows
integer<int64>
wajib
created_count
integer<int64>
wajib
updated_count
integer<int64>
wajib
skipped_count
integer<int64>
wajib
failed_count
integer<int64>
wajib
checkpoint_row
integer<int64>
total_media_bytes
integer<int64>
last_error
string | null
created_at
string<date-time>
updated_at
string<date-time>
started_at
string<date-time> | null
completed_at
string<date-time> | null
state
enum<string>

Status tugas seperti yang ditampilkan konsol; errors adalah tugas selesai dengan baris yang ditolak.

Opsi yang tersedia:
ready,
queued,
running,
paused,
completed,
errors,
failed,
cancelled
source
enum<string>
Opsi yang tersedia:
file,
api,
provider
provider
string

Sumber migrasi; kosong untuk impor file atau API.

provider_options
object
credential_hint
string

Karakter-karakter pertama dari kunci yang disimpan oleh migrasi. Kunci itu sendiri tidak pernah dikembalikan.

credentials_expires_at
string<date-time> | null
resumes_at
string<date-time> | null

Saat tugas yang dijeda oleh batas laju penyedia dilanjutkan kembali secara otomatis.

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

Hasil yang ditemukan oleh dry run: total, by_status, already_in_didit, same_person, not_finished, failed, unmapped_statuses.

face_templates_enabled
boolean
lawful_basis_confirmed_at
string<date-time> | null
not_finished_count
integer<int64>
same_person_count
integer<int64>
face_templates_count
integer<int64>
face_duplicates_count
integer<int64>
face_blocklist_hits_count
integer<int64>
created_by_name
string | null
created_by_email
string | null
Terakhir diubah pada 7 November 2026