Dukcapil verdict ingest

Dukcapil (Direktorat Jenderal Kependudukan dan Pencatatan Sipil) is the Indonesian civil registry. They're the authoritative source for "is NIK X the same person as named on this KTP, and what's the official photo?"

We do not call Dukcapil from our side

Quantum Elixir is not a Dukcapil PKS partner. Dukcapil API access is granted directly to qualifying financial institutions via a separate licensing process (PKS Dukcapil). You call Dukcapil; we ingest your verdict.

Why this matters

When your org has Dukcapil access, you can offer the highest-assurance KYC flow in Indonesia:

Customer submits NIK.
Your backend calls Dukcapil with NIK + biographic claims.
Dukcapil returns: match verdict + the customer's official KTP photo.
You POST the verdict + photo to Identity Platform.
We embed the Dukcapil photo as the authoritative dukcapil-source face enrollment and bump KYC tier.

The Dukcapil photo then becomes the gold-standard reference for every subsequent face match — better than the KTP face crop (which can be glare-damaged) or a selfie (which has lighting variation).

The endpoint

POST/api/identity/nik/dukcapil

Auth · API keyScope · verifications:viewRate limit · 30/min

This endpoint is gated by a per-org dukcapilEnabled capability. Returns 403 if not enabled — contact support to turn it on after you've signed your Dukcapil PKS.

Request

customerIdstringRequired

CUID of the customer.

validbooleanRequired

true if Dukcapil confirmed the lookup, false if no match / declined.

photostring (base64)

Official Dukcapil photo (JPEG/PNG). Required when valid=true.

rawobject

Opaque pass-through of Dukcapil response envelope — stored for audit.

reasonstring

Human-readable reason (used when valid=false), surfaced in analyst dashboards.

Example: "NIK not found in central registry"

Response (success)

{
  "verification": {
    "id": "ver_01HXY...",
    "status": "verified",
    "score": 100
  },
  "enrolment": {
    "id": "fe_01HXY...",
    "source": "dukcapil",
    "fallbackStub": false
  }
}

The customer's KYC tier moves to standard immediately (or premium if they already had a passed face match).

Response (declined verdict)

{
  "verification": {
    "id": "ver_01HXY...",
    "status": "failed"
  },
  "enrolment": null
}

Tier doesn't change. The reason field becomes visible on the customer detail page in the dashboard.

Audit & retention

The raw field is stored verbatim and is never returned via the API again — it's strictly for forensic audit by your compliance team.
The Dukcapil photo is sealed at rest under the same AES-256-GCM scheme as all biometric content.
Verification rows from this endpoint carry method: "nik_dukcapil" — filter for them in GET /api/identity/attempts.

When to call this

The typical sequence:

1. Your onboarding form collects NIK + name + DOB
2. Your backend calls Dukcapil with those claims  ← outside Quantum Elixir
3. Dukcapil returns verdict + photo                ← outside Quantum Elixir
4. POST /api/identity/nik/dukcapil  ← you arrive here
5. POST /api/identity/document/ktp/capture (optional, redundant once Dukcapil verified)
6. POST /api/identity/face/flash-challenge → /face/liveness → /face/match
   (face match auto-prefers Dukcapil as reference source)

Some banks skip step 5 entirely once they have Dukcapil + face match — the Dukcapil photo is the authoritative reference, KTP capture adds little.

What if Dukcapil is down?

Their uptime is generally good but they do have planned outages. Recommended fallback chain:

Try Dukcapil.
On timeout/5xx, fall back to KTP capture only (tier = standard).
Surface the fallback path in your audit log so compliance can later upgrade the customer when Dukcapil is back.

Identity Platform does not currently expose a "retry Dukcapil" hook — you control retries on your side and call us only with final verdicts.

Continuous step-up auth KYC tiers