Cara Verifikasi KTP ke Dukcapil lewat API

API verifikasi KTP ke Dukcapil dalam satu panggilan

di beberapa kasus khususnya fintech pendaftar baru diwajibkan untuk mengisi NIK dan mengunggah foto KTP di aplikasimu. lalu, sebelum akunnya aktif, data itu harus cocok dengan catatan Dukcapil. API verifikasi KTP ke Dukcapil dari api.co.id menjawabnya dalam satu api call ke POST /id-verification/verify. Kamu tinggal mengirim NIK, nama, tanggal lahir, dan foto KTP sebagai multipart/form-data, lalu sistem akan memverifikasi dan mengirimkan result bernilai verified atau rejected. Dengan biaya hanya Rp4.000 per verifikasi kamu sudah bisa memvalidasi keabsahan dokumen ktp user kamu.

Hasil yang akan kamu terima adalah validasi apakah kombinasi NIK, nama, dan tanggal lahir cocok dengan catatan Dukcapil. Ini berbeda dari API yang hanya membaca teks di foto KTP dan mengembalikan data yang tertulis (OCR KTP). Endpoint ini bisa memverifikasi benar atau tidaknya data itu, lalu mengembalikan reference_number untuk audit trail.

Prasyarat sebelum memanggil API

Sebelum kamu bisa menggunakan api ini, ada beberapa hal yang harus kamu lakukan terlebih dulu, yaitu:

• Membuat akun di api.co.id
• Melakukan KYC Standar
• Memiliki Api key (kamu bisa ambil di dashboard)
• Memiliki saldo yang cukup

Kamu bisa mulai dengan daftar atau masuk di dashboard.api.co.id, lalu membuka halaman produk ID Verification di dashboard.api.co.id/products/id-verification untuk mengaktifkannya.

Begitu akun aktif, buat atau buat ulang API key di halaman dashboard.api.co.id/profile/credentials. API key inilah yang kamu pasang di header x-api-co-id pada setiap panggilan, jadi simpan nilainya di tempat yang aman.

Langkah terakhir, isi saldo lewat menu “Top Up Balance”. Pembayaran diproses melalui Midtrans dengan minimum top up Rp50.000, dan kamu bisa membayar dengan beberapa cara:

• kartu kredit
• transfer bank atau virtual account (BCA, Mandiri, BNI)
• e-wallet (GoPay, OVO, DANA)
• QRIS

Saldo masuk sebagai points dengan 1 point setara Rp1, dan modelnya bayar sesuai pemakaian (pay as you go) tanpa kuota gratis. Kamu bisa mengecek sisa saldo di dashboard.api.co.id/profile/balance dan melihat riwayatnya di menu “Riwayat Transaksi”.

Lolos KYC Standard dulu

Dari syarat-syarat tadi, KYC Standard perlu kamu urus terlebih dulu, karena endpoint ini hanya dapat diakses dari akun yang sudah lolos. Kamu bisa mengirim pengajuan KYC Standard lewat halaman dashboard.api.co.id/profile/kyc/kyc-standard, dengan melampirkan foto KTP, foto selfie, nomor telepon aktif, dan persetujuan untuk pemeriksaan manual. Kami akan melakukan pemeriksaan dokumen dalam waktu 1×24 jam, jadi siapkan dokumen yang jelas supaya prosesnya tidak tertahan. Selama menunggu approval, dashboard menampilkan status “Pengajuan sedang direview”. Begitu sudah disetujui, kamu menerima notifikasi bahwa KYC telah disetujui, dan endpoint /id-verification/verify bisa kamu panggil.

Kenapa tidak menggunakan Dukcapil langsung

Kamu mungkin ingin menggunakan api Dukcapil langsung. Ditjen Dukcapil menegaskan tidak ada channel atau aplikasi publik untuk mengecek NIK, seperti di panduan resmi cek NIK ke Dukcapil. Karena itu, saat kamu memanggil API ini, pemrosesannya berjalan lewat penyedia layanan Privy. Alasan regulasi yang mewajibkan verifikasi identitas bisa kamu baca di panduan kepatuhan KYC di Indonesia.

Menyiapkan data verifikasi: NIK, nama, tanggal lahir, dan foto KTP

Begitu akunmu siap, kamu tinggal menyiapkan data yang akan kamu kirim ke endpoint. Inti request ada di field-field berikut:

Field	Isi
nik	NIK 16 digit, misalnya 1203122810970002
name	nama sesuai KTP
date_of_birth	format DD-MM-YYYY, jadi 1 Oktober 1990 menjadi 01-10-1990
identity	file foto KTP dalam format JPG atau PNG

Kamu wajib mengisi keempat field itu. Di luar itu ada satu field opsional, selfie, yang kamu isi dengan file foto selfie kalau ingin menyimpan foto diri bersama hasil verifikasi. Sebelum mengirim, ada baiknya kamu memvalidasi NIK 16 digit di sisi aplikasi, supaya request yang jelas salah formatnya tidak ikut memakan biaya.

Memanggil endpoint /id-verification/verify

Setelah datanya siap, kamu tinggal mengirimnya ke endpoint. Kirim request dengan metode POST ke /id-verification/verify, dan pasang header x-api-co-id berisi API key. Body-nya memakai multipart/form-data karena ada file foto di dalamnya. Contoh di bawah memakai host produksi use.api.co.id.

curl -X POST "https://use.api.co.id/id-verification/verify" \
  -H "x-api-co-id: YOUR_API_KEY" \
  -F "reference_number=TESTIDVERIF0001" \
  -F "nik=1203122810970002" \
  -F "name=User Info" \
  -F "date_of_birth=01-10-1990" \
  -F "email=testing@example.com" \
  -F "phone=+6281111111111" \
  -F "selfie=@selfie.jpg" \
  -F "identity=@ktp.jpg"

Selain keempat field inti tadi, contoh di atas juga mengirim reference_number, email, dan phone yang ketiganya opsional. Kamu bebas mengisi reference_number sendiri, lalu API mengembalikan nilainya di respons sehingga mudah kamu cocokkan dengan catatan di sistemmu.

Membaca respons verified dan rejected

Begitu request terkirim, API akan mengembalikan tiga result, yaitu is_success, message, dan data. Kalau API berhasil memproses requestmu, is_success bernilai true, dan keputusan sebenarnya ada di data.result yang bernilai verified atau rejected. Di dalam data kamu juga menemukan reference_number, channel_id, dan message.

{
  "is_success": true,
  "message": "Success",
  "data": {
    "reference_number": "TESTIDVERIF0001",
    "channel_id": "001",
    "result": "verified",
    "message": "digital certificate has been issued"
  }
}

value yang paling perlu kamu simpan adalah data.reference_number, karena itu yang akan dipakai untuk audit trail dan rekonsiliasi nanti. data.channel_id menandai kanal pemrosesan, contohnya 001. Kalau verifikasinya sukses, data.message mereturn digital certificate has been issued.

Menangani hasil rejected

Respons rejected memakai struktur respons yang sama. is_success tetap true karena API berhasil memproses requestmu, dan data berisi reference_number, channel_id, result, serta message, dengan data.result bernilai rejected. Saat hasilnya rejected, alasan penolakannya ada di data.message, jadi baca field itu untuk tahu kenapa API menolaknya. Dari situ kamu menentukan langkah lanjutan. Kalau sebabnya salah ketik atau foto buram, mengirim ulang dengan perbaikan biasanya cukup, misalnya mengunggah ulang foto KTP yang jelas. Kalau sebabnya tidak jelas, teruskan alasan penolakan itu ke tim operasional untuk pemeriksaan manual.

Error yang akan ditemui dan cara menanganinya

Selain hasil bisnis verified dan rejected tadi, API bisa menolak request lebih dulu sebelum verifikasi berjalan. Kalau itu terjadi, is_success bernilai false, message memuat sebabnya, dan data bernilai null.

{
  "is_success": false,
  "message": "API key required in x-api-co-id header",
  "data": null
}

Respons di atas muncul dengan status 401 Unauthorized kalau kamu tidak mengirim header x-api-co-id. Kalau API key terkirim tapi tidak dikenal, pesannya berubah menjadi Invalid API key dengan status 401 yang sama, jadi periksa kembali nilai yang kamu salin dari dashboard.

{
  "is_success": false,
  "message": "Invalid API key",
  "data": null
}

Kalau saldomu tidak cukup, API membalas dengan status 402 Payment Required. Isi ulang saldo lewat menu “Top Up Balance” di dashboard sebelum kamu mencoba lagi. Di luar hasil rejected  ini, verifikasi mungkin juga tidak berjalan dalam beberapa kondisi:

• bisa jadi akun belum lolos KYC
• data yang kamu kirim tidak lengkap
• penyedia layanan sedang gangguan

Pada kondisi itu biaya ID Verification tidak dipotong.

Contoh lengkap: dari form sampai validasi

kita coba dengan contoh pelanggan dengan NIK 1203122810970002, nama User Info, lahir 01-10-1990, yang mengunggah ktp.jpg dan selfie.jpg. Request cURL di atas memakai nilai itu, dan respons di atas adalah balasannya. Versi PHP di bawah mengirim nilai yang sama, lalu membaca keputusannya.

<?php
$ch = curl_init("https://use.api.co.id/id-verification/verify");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-co-id: YOUR_API_KEY"]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    "reference_number" => "TESTIDVERIF0001",
    "nik"              => "1203122810970002",
    "name"            => "User Info",
    "date_of_birth"   => "01-10-1990",
    "email"           => "testing@example.com",
    "phone"           => "+6281111111111",
    "selfie"          => new CURLFile("selfie.jpg"),
    "identity"        => new CURLFile("ktp.jpg"),
]);
$response = json_decode(curl_exec($ch), true);

if ($response["data"]["result"] === "verified") {
    // simpan $response["data"]["reference_number"] ke audit trail
}

Kasus nyata: onboarding aplikasi pinjaman

Mari kita ambil contoh di aplikasi pinjaman online yang perlu memastikan pendaftar memakai KTP miliknya sendiri sebelum pencairan. Saat onboarding, backend mengumpulkan NIK, nama, tanggal lahir, dan foto KTP dari form pendaftaran, lalu memanggil POST /id-verification/verify. Kalau result bernilai verified, status pengguna naik ke “identitas terverifikasi” dan sistem menyimpan reference_number di tabel audit. Kalau hasilnya rejected, sistem meminta pengguna mengunggah ulang foto yang jelas, sambil memakai alasan penolakan sebagai petunjuk untuk tim operasional. Begitu verified, alur lanjut ke pencocokan selfie dengan foto KTP.

Harga, kuota, dan batas

Satu verifikasi yang menghasilkan result akan memotong saldo Rp4.000, baik hasilnya verified maupun rejected. Begitu API mengembalikan result, verifikasi itu terhitung berhasil diproses dan saldomu akan langsung terpotong. Jadi hasil rejected tetap kena biaya sama seperti verified karena penyedia layanan sudah memproses dan memberi result. namun bila api call mengembalikan is_success bernilai false maka kami tidak akan memotong saldo dari balance, contohnya seperti pada bagian error tadi.

Langkah berikutnya: isi otomatis dan cocokkan selfie

Setelah verifikasi berjalan, biasanya ada dua hal yang bisa kamu otomatisasi dengan api dari api.co.id yaitu. kamu bisa ekstrak data KTP otomatis dari foto, sehingga nik, name, dan date_of_birth terisi dari gambar tanpa kamu ketik manual dengan api ocr ktp atau Kamu bisa pakai Face Matching untuk cocokkan selfie dengan foto KTP, dan langkah ini biasanya kamu jalankan setelah status verified, seperti pada kasus pinjaman tadi. Kalau kamu menyusun proses identitas yang lebih besar, endpoint ini menempati satu titik dalam alur eKYC.