> ## 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 Buat Sesi Verifikasi: Mulai Verifikasi KYC atau KYB
> POST /v3/session/ memulai sesi verifikasi Didit. Endpoint KYC + KYB terpadu, bayar per penggunaan, inferensi sub-2 detik, kredit gratis $10/bulan.
Prompt Pembuatan Sesi
Salin prompt ke papan klip
\
\`Create a verification session via Didit's REST API.
Endpoint:
POST https://verification.didit.me/v3/session/
Authentication:
Use the x-api-key header with your Didit API key. The workflow's type (KYC or KYB) determines which kind of session is created — there is no separate endpoint for KYB.
Request body:
\- workflow_id (string, UUID, required) — Stable workflow UUID from /v3/workflows/. KYC workflows create User Verification sessions; KYB workflows create Business Verification sessions.
\- vendor_data (string, optional) — Your stable identifier for the entity (user or business). Strongly recommended: it binds the session to a User or Business entity and is used for duplicate detection across sessions.
\- callback (string, URL, optional): Where the hosted flow redirects the user when finished. Didit appends ?verificationSessionId={session_id}&status={status}. Falls back to the workflow default. When the application has allowed domains (allowed_domains on PATCH /v3/webhook/), an http or https callback must be on one of those origins (same scheme, host and port), otherwise creation fails with 400 on callback: "callback must be on one of the application's allowed domains: https://app.example.com". Custom URL schemes (app deep links such as myapp://) are always accepted. A workflow-default callback outside the allowed domains is not used for the redirect.
\- callback_method (string, optional, default "initiator") — One of "initiator", "completer", "both". Use "both" if the callback sometimes fails to fire.
\- metadata (object, optional) — Arbitrary JSON echoed back in responses and webhooks. Not shown to the user.
\- tags (array of strings, optional): Tags added to the session when it is created, by name, for example ["VIP", "ONBOARDING Q4"]. Up to 10, each up to 50 characters. Names are case-insensitive and stored in upper case; a name that does not exist yet in the application is created as a new tag. The tags show on the session in the console, where you can filter by them, and come back in the create response.
\- language (string, optional) — ISO 639-1 code for the verification UI (en, es, fr, de, pt, etc.). Defaults to browser detection.
\- contact_details (object, optional) — { email, send_notification_emails, email_lang, phone }. Pre-fills phone/email steps and (optionally) sends notification emails.
\- expected_details (object, optional) — Expected first_name, last_name, date_of_birth, nationality (ISO-3), id_country (ISO-3), expected_document_types (e.g. ["P","ID","DL","RP","SSC"]). Mismatches surface as decision warnings. For Business Verification (KYB) workflows, pass the business fields instead — company_name, registry_country, registration_number — to pre-fill the company registry search; registry_country is ISO 3166-1 alpha-2 and can include the state for state-level registries (e.g. "US-CA"), same format as the KYB Registry Search country_code. Person-level fields are ignored on KYB sessions.
\- portrait_image (string, base64, conditional) — Reference face for Biometric Authentication workflows (and graph workflows where Face Match runs before ID Verification). Max 2MB; JPEG, PNG, WebP, or TIFF. Optional when the vendor_data user already has a stored face: Didit reuses it automatically (approved liveness face, then ePassport chip photo, then ID document portrait, then a manually enrolled profile face). If omitted and no stored face exists, creation fails with 400. Ignored for other workflow types.
\- multi_account_segment (string, optional, max 64 chars) — Duplicate-detection realm inside your own organization. Duplicate face checks only compare this session against other sessions carrying the same segment, so an organization that runs separate account bases (personal vs business, or one per sub-client) does not see a person who legitimately holds one account in each reported as a duplicate. Omit it to use the single default realm — which is what every session uses today, so existing integrations are unaffected. Blocklist and allowlist matching ignore this field: a blocklisted face stays blocklisted in every segment.
\- sandbox_scenario (string, optional, sandbox applications only): Scenario slug from the sandbox catalog (GET /v1/sandbox/scenarios/). Expands the scenario's bundled magic values onto contact_details/expected_details so the session reproduces that outcome. Rejected with 400 on live applications. You can also arm or re-arm a scenario after create, as long as the session is still Not Started, via POST /v3/session/{session_id}/sandbox/arm/. See /integration/sandbox-testing.
\- user_state (string, optional, max 16 chars): Where the person lives, when you know it: an ISO 3166-2 code (US-IL) or a US state code or name (IL, Illinois). In Auto consent mode, Illinois, Texas or Colorado makes the flow ask for explicit biometric consent before the first face capture. 400 on an unrecognized value.
\- biometric_consent (object, optional): Consent you already collected: { given_at (ISO 8601, not in the future), text_version (max 64 chars) }. The flow does not ask again; the decision records it as given with trigger customer_collected.
\- sign (object, optional): { documents: [ { title, file_name, content_base64, fields } ], field_values: { : value } }. documents is for a workflow whose E-signature step takes documents from the session (signature_documents_source "session" or "both"). file_name ends in .pdf or .docx; content_base64 is the file in base64. Up to 20 documents and 50 MB in total; a PDF up to 20 MB and 100 pages, without a password, scripts or attachments; a Word file (.docx) up to 20 MB, converted to PDF while the request runs, at most 5 per session. fields is optional (up to 200 per document): signature, initials, full_name, date_signed, text, checkbox, email or data fields, each with a key unique in its document (^[a-z][a-z0-9_]{0,63}$), placed by page, x, y, width and height, or by anchor text ({ text, occurrence, offset_x, offset_y, width, height }). role defaults to the step's signer. field_values fills the fields whose prefill is "api.", on workflow and session documents alike: strings of 1 to 500 characters, booleans for checkboxes. 400 when the workflow has no E-signature step, takes workflow documents only and you sent documents, or needs session documents you didn't send; field_anchor_not_found, field_value_unknown, field_value_missing or field_value_invalid for fields and values. See /core-technology/electronic-signature/overview.
Idempotency:
Within one application, only one non-finished session can exist per (workflow_id, vendor_data). Calling create again with the same pair returns the existing session (and updates its callback + metadata, and adds any tags you send) instead of creating a duplicate. If you send sign again, its documents, fields and field values must be identical (same order, titles, file names, content, fields and values), or the call returns 400 { "sign": "signature_document_changed" }.
curl example:
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "",
"vendor_data": "user-42",
"callback": "https://yourapp.com/callback",
"metadata": { "plan": "premium" }
}'
Response (201 Created) — keys you must handle:
\- session_id (UUID) — use this on every subsequent /v3/session/{session_id}/... call.
\- session_kind ("user" | "business") — discriminator, dispatch on this.
\- session_number (int) — human-friendly per-application sequence.
\- session_token (string) — short-lived, embedded in the hosted URL. Treat as secret.
\- url (string) — hosted verification URL. Redirect the end user here. (Field name is "url", NOT "verification_url".)
\- status (string) — newly created sessions return "Not Started".
\- workflow_id, workflow_version, vendor_data, metadata, callback — echoed back.
See /reference/data-models for the full schema.
Failure modes:
\- 400 — { "workflow_id": ["Invalid workflow_id."] } when the UUID is unknown.
\- 400 — { "vendor_data": ["This user or business has been blocked and cannot create new verification sessions."] } when blocklisted.
\- 400 — { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } when out of credits.
\- 400 — { "portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first." } on a Face Match workflow when portrait_image is omitted and the vendor_data user has no stored face.
\- 401 — invalid or missing API key.
\- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks write:sessions.
\- 429 — rate limited (600 successful calls/minute per token/IP). Honour Retry-After.
Disclosure & consent:
This endpoint generates a URL — it does not record that you obtained user consent. Show your privacy notice and any biometric-specific consent in your own UX before redirecting to the hosted flow.
For people covered by Illinois, Texas or Colorado law, the hosted flow and native SDK 4.10.0 or later can ask for explicit biometric consent before the selfie; native SDKs below 4.10.0 cannot show that step. See /getting-started/biometric-consent.
Next step:
After the user finishes (status changes to Approved / Declined / In Review), call GET https://verification.didit.me/v3/session/{session_id}/decision/ for the full decision — see /sessions-api/retrieve-session.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
Tempel ke
## Dukungan KYC dan KYBSatu endpoint membuat sesi Verifikasi Pengguna dan Verifikasi Bisnis sekaligus. **Jenis alur kerja** menentukan jenis sesi yang dibuat:- Kirim `workflow_id` **alur kerja KYC** → sesi Verifikasi Pengguna (KYC) dibuat. Respons `session_kind: "user"`.
- Kirim `workflow_id` **alur kerja KYB** → sesi Verifikasi Bisnis (KYB) dibuat. Respons `session_kind: "business"`.Atur alur kerja di konsol pada *Alur kerja → Buat alur kerja*. Alur kerja adalah KYC atau KYB saat dibuat, dan jenisnya tidak dapat diubah setelah itu.## Contoh> [tab] Verifikasi Pengguna (KYC)
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "workflow_id": "YOUR_KYC_WORKFLOW_ID",
> "vendor_data": "user-42",
> "callback": "https://yourapp.com/callback"
> }'
> ```
>
> **Respons (201 Dibuat):**
>
> ```json theme={null}
> {
> "session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
> "session_kind": "user",
> "session_number": 1024,
> "session_token": "...",
> "url": "https://verify.didit.me/session/...",
> "status": "Not Started",
> "workflow_id": "YOUR_KYC_WORKFLOW_ID",
> "vendor_data": "user-42"
> }
> ```> [tab] Verifikasi Bisnis (KYB)
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "workflow_id": "YOUR_KYB_WORKFLOW_ID",
> "vendor_data": "biz-acme-001",
> "callback": "https://yourapp.com/callback"
> }'
> ```
>
> **Respons (201 Dibuat):**
>
> ```json theme={null}
> {
> "session_id": "bs-01HJX1...",
> "session_kind": "business",
> "session_number": 89,
> "session_token": "...",
> "url": "https://verify.didit.me/session/...",
> "status": "Not Started",
> "workflow_id": "YOUR_KYB_WORKFLOW_ID",
> "vendor_data": "biz-acme-001"
> }
> ```## Dokumen Tanda Tangan ElektronikJika alur kerja memiliki langkah [Tanda Tangan Elektronik](https://docs.didit.me/id/core-technology/electronic-signature/overview.md) yang mengambil dokumen dari sesi (`signature_documents_source` diatur ke `session` atau `both`), kirimkan dokumen tersebut di `sign.documents`. Setiap dokumen berupa file dalam base64, sehingga Didit tidak perlu mengambilnya dari URL.```json theme={null}
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"documents": [
{
"title": "Loan agreement",
"file_name": "loan-agreement.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"fields": [
{ "key": "borrower_signature", "type": "signature", "label": "Borrower signature", "page": 3, "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.06 },
{ "key": "date_signed", "type": "date_signed", "label": "Date", "page": 3, "x": 0.6, "y": 0.8, "width": 0.2, "height": 0.03, "date_format": "DD/MM/YYYY" },
{ "key": "loan_amount", "type": "data", "label": "Loan amount", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.loan_amount" },
{ "key": "initials", "type": "initials", "anchor": { "text": "[[initials]]", "occurrence": "all", "offset_x": 0, "offset_y": -0.005, "width": 0.12, "height": 0.04 } }
]
}
],
"field_values": { "loan_amount": "12,000 EUR" }
}
}
```| Kolom | Aturan |
| - | - |
| `title` | Ditampilkan kepada penandatangan. 1 sampai 255 karakter. Nilai default adalah `file_name`. |
| `file_name` | Wajib. Berakhiran `.pdf` atau `.docx`. 1 sampai 255 karakter. |
| `content_base64` | Wajib. PDF dapat berukuran hingga 20 MB dan 100 halaman, tanpa kata sandi, skrip, atau file terlampir. File Word dapat berukuran hingga 20 MB dan dikonversi menjadi PDF selama permintaan berjalan, dalam paling lama 25 detik; PDF hasil konversi tersebut mengikuti batas yang sama. Hingga 5 file Word per sesi. |
| `fields` | Opsional. Hingga 200 [kolom](https://docs.didit.me/id/core-technology/electronic-signature/overview.md#kolom-pada-dokumen) untuk ditempatkan pada dokumen, dengan bentuk kolom tanpa `id`. Setiap kolom wajib memiliki `key` dan `type`, serta salah satu dari posisi (`page`, `x`, `y`, `width`, dan `height`) atau [`anchor`](#menempatkan-kolom-dengan-teks-penanda). `role` secara default mengikuti penandatangan langkah tersebut, dan `required` serta `label` secara default mengikuti jenisnya. Didit mengatur `position` berdasarkan lokasi kolom. Halaman dan posisi mengacu pada PDF, atau pada PDF hasil konversi untuk file Word. |Tanpa `fields`, penandatangan membaca dokumen dan menyetujuinya.### Menempatkan kolom dengan teks penandaAlih-alih posisi, kolom dapat memuat `anchor`: potongan teks dalam dokumen yang menandai tempat kolom diletakkan. Penanda cocok untuk dokumen yang Anda buat untuk setiap sesi, misalnya dari templat Word. Untuk dokumen alur kerja, tempatkan kolom di konsol.| Properti `anchor` | Aturan |
| - | - |
| `text` | 1 sampai 64 karakter, dicari dalam teks dokumen. Untuk file Word, dicari dalam PDF hasil konversi. |
| `occurrence` | `first` (default) menempatkan satu kolom pada kecocokan pertama. `all` menempatkan satu kolom pada setiap kecocokan, dan kunci setelah yang pertama mendapat `_2`, `_3`, dan seterusnya. |
| `offset_x`, `offset_y` | Pecahan dari halaman. Sudut kiri atas kolom adalah sudut kiri atas teks penanda ditambah offset ini. |
| `width`, `height` | Ukuran kolom, sebagai pecahan dari halaman. |Jika teks tidak ada dalam dokumen, panggilan mengembalikan `400` dengan `field_anchor_not_found` dan kunci kolom tersebut. Didit tidak menghapus teks penanda dari PDF, jadi tulis teks tersebut dengan warna yang sama dengan latar belakang halaman.### Nilai kolom`sign.field_values` mengatur nilai setiap kolom yang `prefill`-nya adalah `api.`, baik pada dokumen alur kerja maupun dokumen sesi. Nilainya berupa objek yang diindeks dengan nama `` tersebut. Nilai berupa string 1 sampai 500 karakter untuk kolom `text` dan `data`, dan boolean untuk `checkbox`.```json theme={null}
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" }
}
}
```| Error (`400`) | Kapan terjadi |
| - | - |
| `field_value_unknown` | Kunci yang tidak digunakan oleh kolom mana pun. |
| `field_value_missing` | Kolom wajib yang `api.`-nya tidak memiliki nilai. |
| `field_value_invalid` | Nilai yang tidak lolos [validasi](https://docs.didit.me/id/core-technology/electronic-signature/overview.md#validasi) kolomnya. |### Error dan panggilan berulangSesi menampung hingga 20 dokumen dan total 50 MB. Panggilan mengembalikan `400` dengan error `sign` ketika:- Alur kerja tidak memiliki langkah Tanda Tangan Elektronik.
- Anda mengirim `sign.documents`, sedangkan langkah tersebut hanya mengambil dokumen alur kerja.
- Langkah tersebut hanya mengambil dokumen sesi dan Anda tidak mengirim dokumen apa pun, atau langkah tersebut tidak memiliki dokumen alur kerja dan Anda tidak mengirim dokumen apa pun.
- Dokumen terlalu besar, bukan base64 yang valid, atau bukan file yang didukung.
- File Word ditolak dengan `signature_document_not_supported`, atau tidak dapat dikonversi dan mengembalikan `signature_document_conversion_failed`, masing-masing dengan `reason` yang tercantum di [File yang didukung](https://docs.didit.me/id/core-technology/electronic-signature/overview.md#file-yang-didukung).
- Kolom tidak valid, penandanya tidak ditemukan (`field_anchor_not_found`), atau [nilai kolom](#nilai-kolom) ditolak.Memanggil operasi pembuatan lagi untuk `workflow_id` dan `vendor_data` yang sama akan mengembalikan sesi yang tertunda. Jika panggilan tersebut mengirim `sign`, dokumen, kolom, dan nilai kolomnya harus sama persis dengan yang pertama (urutan, judul, nama file, konten, kolom, dan nilainya). Perbedaan apa pun akan mengembalikan `400` dengan `{"sign": "signature_document_changed"}`. Dalam kasus itu, gunakan `vendor_data` yang berbeda, atau tunggu sampai sesi yang tertunda selesai.## Pengujian dengan skenario sandboxPada aplikasi mode sandbox, kirimkan `sandbox_scenario` untuk memuat hasil yang deterministik (setujui, penolakan tertentu, atau skenario dalam peninjauan) tanpa menyentuh penyedia sungguhan atau saldo Anda:```json theme={null}
{
"workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
"sandbox_scenario": "decline_document_expired"
}
````sandbox_scenario` ditolak dengan `400` pada aplikasi produksi. Jika Anda belum mengetahui hasilnya saat pembuatan sesi, aktifkan (atau aktifkan ulang) nanti melalui `POST /v3/session/{session_id}/sandbox/arm/`, selama sesi masih `Not Started`. Pemilih skenario sebelum alur pada halaman verifikasi yang di-hosting menggunakan endpoint yang sama. Lihat [Sandbox & Data Pengujian](https://docs.didit.me/id/integration/sandbox-testing.md) untuk katalog skenario lengkap, registri nilai khusus, dan bentuk permintaan serta respons endpoint pengaktifan.## `vendor_data` mengikat sesi ke entitas- Untuk alur kerja KYC: mengikat ke [entitas pengguna](https://docs.didit.me/id/entities/users/overview.md). Jika pengguna belum ada, entitas tersebut dibuat otomatis.
- Untuk alur kerja KYB: mengikat ke [entitas bisnis](https://docs.didit.me/id/entities/businesses/overview.md). Dibuat otomatis jika entitas tersebut baru.Pelajari selengkapnya di [penautan data vendor](https://docs.didit.me/id/entities/vendor-data-linking.md).## Persetujuan biometrik di Illinois, Texas, dan ColoradoAlur yang di-hosting dan SDK native 4.10.0 atau yang lebih baru dapat menampilkan langkah persetujuan biometrik yang eksplisit sebelum pengambilan wajah pertama, bergantung pada mode persetujuan aplikasi dan lokasi orang tersebut. Dua kolom opsional memengaruhi keputusan ini:- `user_state`: lokasi tempat tinggal orang tersebut, jika Anda mengetahuinya (`US-IL`, `IL` atau `Illinois`). Dalam mode Auto, negara bagian yang tercakup membuat alur meminta persetujuan.
- `biometric_consent`: objek dengan `given_at` dan `text_version`, untuk persetujuan yang sudah Anda kumpulkan. Alur tidak akan meminta persetujuan lagi.SDK native di bawah 4.10.0 tidak dapat menampilkan langkah ini: sesinya berjalan seperti biasa dan hasil keputusan menunjukkan bahwa persetujuan belum dikumpulkan. Lihat [Persetujuan biometrik](https://docs.didit.me/id/getting-started/biometric-consent.md).## Penting: pengungkapan dan persetujuan tetap dilakukan di produk Anda`Create Session` menghasilkan URL verifikasi dan token sesi. Endpoint ini **tidak** dengan sendirinya membuktikan bahwa Anda telah menyampaikan pemberitahuan kepada pengguna atau memperoleh persetujuan yang diwajibkan untuk kasus penggunaan spesifik Anda.Jika Anda memulai sesi Didit dari aplikasi, situs web, pembungkus SDK, atau alur White Label Anda sendiri, Anda sebaiknya menangani lapisan hukum di UX Anda sendiri sebelum pengguna mulai pengambilan data.## Daftar periksa pra-verifikasi yang direkomendasikan1. Beri tahu pengguna bahwa **perusahaan Anda** meminta verifikasi ini dan bahwa **Didit** adalah penyedia verifikasi / prosesor yang mendukung alur ini.
2. Tautkan ke **pemberitahuan privasi Anda** dan ketentuan hukum dari pihak pengendali data yang berlaku untuk proses ini.
3. Tautkan ke [Pemberitahuan Privasi Verifikasi](https://didit.me/terms/verification-privacy-notice) dan [Ketentuan Pengguna Akhir untuk Verifikasi Identitas](https://didit.me/terms/identity-verification) milik Didit.
4. Jika alur Anda mencakup pengambilan dokumen, swafoto, liveness, atau biometrik, kumpulkan **persetujuan tegas yang eksplisit** di mana pun hukum yang berlaku atau posisi hukum Anda mewajibkannya.
5. Jika Anda menggunakan UI kustom, domain kustom, atau alur yang hanya menggunakan API, tampilkan pengungkapan ini di produk Anda sendiri sebelum mengarahkan pengguna ke alur Didit.
6. Simpan catatan Anda sendiri tentang teks pemberitahuan / persetujuan, stempel waktu, dan metadata terkait jika tim hukum Anda memerlukan jejak audit.> [!WARNING]
>
> Persyaratan hukum berbeda-beda di setiap yurisdiksi. Branding White Label tidak menghapus peran Didit dalam alur verifikasi. Tinjau implementasi Anda bersama penasihat hukum sebelum peluncuran jika Anda beroperasi di yurisdiksi dengan aturan khusus biometrik.
## OpenAPI
````yaml id/openapi-25.json POST /v3/session/
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/session/:
post:
tags:
- Sessions
summary: Buat sesi verifikasi
description: >-
Buat sesi Verifikasi Pengguna (KYC) atau Verifikasi Bisnis (KYB) dan
terima `url` verifikasi yang di-hosting beserta `session_token` untuk
dialihkan atau disematkan bagi pengguna akhir Anda. `workflow_id`
memilih langkah verifikasi mana yang dijalankan dan apakah sesi tersebut
merupakan KYC atau KYB.
Panggil ini dari backend Anda (jangan pernah dari browser — kunci API
bersifat rahasia) kapan pun pengguna atau bisnis perlu diverifikasi:
saat pendaftaran, sebelum tindakan sensitif, atau ketika verifikasi
ulang diperlukan. Prasyarat: alur kerja yang dipublikasikan (dibuat di
halaman [Workflows](https://docs.didit.me/id/console/workflows) Console)
dan kunci API aplikasi dengan kredit yang tersedia. Aplikasi sandbox
melewati pemeriksaan kredit.
**Idempotensi:** ketika `vendor_data` diberikan dan sesi yang belum
selesai (`Not Started`, `In Progress`, `Resubmitted`, atau `Awaiting
User`) dengan `vendor_data` yang sama sudah ada pada **versi publikasi
terbaru saat ini** dari alur kerja tersebut (dan sesi tersebut sudah
memiliki URL verifikasi yang di-hosting), sesi yang sudah ada akan
dikembalikan (tetap `201`) alih-alih membuat duplikat — dengan
`callback` dan `metadata` diperbarui ke nilai baru yang diberikan. Sesi
yang belum selesai yang dibuat pada versi alur kerja yang lebih lama
(versi yang telah dipublikasikan ulang sejak saat itu) **tidak**
digunakan kembali; sesi baru yang disematkan ke versi publikasi terbaru
akan dibuat sebagai gantinya. Sesi dalam `Approved`, `Declined`, `In
Review`, `Expired`, `Abandoned`, atau `Kyc Expired` tidak pernah
digunakan kembali.
**Efek samping:** URL verifikasi yang di-hosting dibuat dan disimpan;
jika `contact_details.send_notification_emails` bernilai `true` dan
email diberikan, email undangan verifikasi akan dikirimkan. Sesi
kedaluwarsa setelah waktu kedaluwarsa sesi yang dikonfigurasi pada alur
kerja. Untuk alur kerja KYB, `contact_details.phone` dan
`expected_details` diabaikan.
operationId: post_v3_session_create
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- workflow_id
properties:
workflow_id:
type: string
format: uuid
description: >-
Pengidentifikasi stabil dari alur kerja yang menentukan
langkah verifikasi mana yang akan dijalankan oleh sesi
tersebut. Alur kerja dibuat dan dikelola di halaman
[Workflows](/id/console/workflows) pada Konsol.
`workflow_id` juga secara implisit memilih apakah sesi
tersebut adalah KYC atau KYB.
example: 11111111-2222-3333-4444-555555555555
x-readme-id: '0.0'
vendor_data:
type: string
description: >-
Pengidentifikasi unik untuk pengguna yang sedang
diverifikasi, seperti UUID, email, atau ID pengguna
internal. Kolom ini digunakan untuk: (1) **Pengelompokan
pengguna** — sesi dengan vendor_data yang sama ditautkan ke
profil pengguna yang sama di tab Pengguna. (2) **Deteksi
duplikat lintas-sesi** — saat memeriksa duplikasi wajah,
dokumen, nomor telepon, email, alamat IP, atau sidik jari
perangkat, sesi dengan vendor_data yang sama diperlakukan
sebagai pengguna yang sama dan dikecualikan dari kecocokan.
Tanpa vendor_data, setiap sesi diperlakukan sebagai pengguna
unik dan semua potensi duplikat ditampilkan. Kami sangat
menyarankan untuk selalu menyertakan vendor_data guna
mengurangi derau dalam deteksi duplikat.
example: user-123
x-readme-id: '0.1'
multi_account_segment:
type: string
maxLength: 64
description: >-
Realm deteksi duplikat opsional di dalam organisasi Anda.
Pemeriksaan wajah duplikat hanya membandingkan sesi ini
dengan sesi lain yang memiliki segmen yang sama, sehingga
basis akun yang terpisah (akun pribadi dan bisnis, atau satu
per sub-klien B2B) tidak menandai seseorang yang secara sah
memiliki satu akun di masing-masing basis akun. Abaikan
untuk menggunakan realm default tunggal, yang saat ini
digunakan oleh setiap sesi. Pencocokan daftar blokir dan
allowlist mengabaikan kolom ini.
example: business-accounts
callback:
type: string
description: >-
URL untuk mengarahkan pengguna setelah verifikasi selesai.
Didit secara otomatis menambahkan `verificationSessionId`
dan `status` (Approved, Declined, In Review) sebagai
parameter kueri. Skema URL kustom (misalnya `myapp://`)
didukung untuk callback seluler. Jika tidak disertakan,
`callback_url` default milik alur kerja akan digunakan. Jika
aplikasi memiliki domain yang diizinkan (`allowed_domains`
pada `PATCH /v3/webhook/`), callback `http` atau `https`
harus berada di salah satu origin tersebut (skema, host, dan
port yang sama), jika tidak, permintaan gagal dengan 400
pada `callback`: `callback must be on one of the
application's allowed domains: https://app.example.com`.
Skema URL kustom selalu diterima.
example: https://example.com/verification/callback
x-readme-id: '0.2'
callback_method:
type: string
description: >-
Menentukan perangkat mana yang harus menangani pengalihan ke
URL callback yang diberikan. Gunakan `initiator` untuk
mengalihkan hanya perangkat yang memulai alur, `completer`
untuk perangkat yang menyelesaikannya, atau `both` untuk
mengizinkan salah satu perangkat memicu callback. Jika Anda
mendapati callback tidak terpicu secara andal, kami sarankan
untuk menyetel nilai ini ke `both`.
enum:
- initiator
- completer
- both
default: initiator
example: both
x-readme-id: '0.3'
metadata:
description: >-
JSON arbitrer yang disimpan bersama sesi dan dikembalikan
dalam respons serta webhook. Nilai JSON apa pun diterima
(objek, string, angka, array), tetapi objek JSON yang berisi
pasangan kunci/nilai disarankan. Tidak ditampilkan kepada
pengguna akhir. Gunakan ini untuk meneruskan ID korelasi
Anda sendiri, varian A/B, atau konteks bisnis.
example:
user_type: premium
account_id: ABC123
x-readme-id: '0.4'
tags:
type: array
items:
type: string
maxLength: 50
maxItems: 10
description: >-
Tag yang ditambahkan ke sesi saat dibuat, berdasarkan nama.
Hingga 10 tag, masing-masing hingga 50 karakter. Nama tidak
membedakan huruf besar/kecil dan disimpan dalam huruf besar.
Nama yang belum ada di aplikasi akan dibuat sebagai tag
baru. Tag ditampilkan pada sesi di konsol, tempat Anda dapat
memfilternya.
example:
- VIP
- ONBOARDING Q4
language:
type: string
description: >-
Kode bahasa (ISO 639-1) untuk antarmuka proses verifikasi.
Mengontrol bahasa yang ditampilkan kepada pengguna akhir
selama verifikasi. Jika tidak diberikan, bahasa browser akan
terdeteksi dan digunakan secara otomatis. Periksa semua
bahasa yang didukung [di
sini](/id/integration/supported-languages).
enum:
- en
- ar
- bg
- bn
- bs
- ca
- cnr
- cs
- da
- de
- el
- es
- et
- fa
- fi
- fr
- he
- hi
- hr
- hu
- hy
- id
- it
- ja
- ka
- kk
- ko
- ky
- lt
- lv
- mk
- mn
- ms
- nl
- 'no'
- pl
- pt-BR
- pt
- ro
- ru
- sk
- sl
- so
- sq
- sr
- sv
- th
- tr
- uk
- uz
- vi
- zh-CN
- zh-TW
- zh
example: en
x-readme-id: '0.5'
contact_details:
type: object
description: >-
Informasi kontak pengguna yang dapat digunakan untuk
notifikasi, pra-pengisian formulir verifikasi, dan
verifikasi telepon. Ini mencakup alamat email, bahasa
pilihan untuk komunikasi, dan nomor telepon.
example:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
properties:
email:
type: string
format: email
description: >-
Alamat email pengguna (misalnya, "john.doe@example.com")
yang akan digunakan selama langkah [Verifikasi
Email](/id/core-technology/email-verification/overview).
Jika tidak diberikan, pengguna harus memberikannya
selama alur verifikasi.
example: john.doe@example.com
x-readme-id: '1.0'
send_notification_emails:
type: boolean
default: false
description: >-
Jika true dan email diberikan, Didit mengirimkan email
awal "Verifikasi identitas Anda" secara asinkron saat
sesi Verifikasi Pengguna (KYC) atau Verifikasi Bisnis
(KYB) dibuat. Didit juga mengirimkan notifikasi status
verifikasi untuk sesi yang memerlukan peninjauan manual
ke alamat email yang diberikan (misalnya, dari 'In
Review' ke 'Approved' atau 'Declined'). Hal ini membantu
pengguna kembali ke aplikasi Anda setelah verifikasi
mereka selesai. Jika Anda mengaktifkan White Label untuk
sesi tersebut, email yang dikirim akan menggunakan White
Label.
example: true
x-readme-id: '1.1'
email_lang:
type: string
description: >-
Kode bahasa (ISO 639-1) untuk notifikasi email.
Mengontrol bahasa semua komunikasi email (misalnya,
"en", "es", "fr"). Tidak ada default tersimpan — jika
diabaikan, email undangan verifikasi akan beralih ke
bahasa Inggris (`en`) pada saat pengiriman. Enum di
bawah ini adalah snapshot; sumber kebenaran langsung
untuk nilai yang diterima adalah dokumen [bahasa yang
didukung](/id/integration/supported-languages) — selalu
baca dokumen tersebut sebelum mengandalkan kode
tertentu.
enum:
- en
- ar
- bg
- bn
- bs
- ca
- cnr
- cs
- da
- de
- el
- es
- et
- fa
- fi
- fr
- he
- hi
- hr
- hu
- hy
- id
- it
- ja
- ka
- kk
- ko
- ky
- lt
- lv
- mk
- mn
- ms
- nl
- 'no'
- pl
- pt-BR
- pt
- ro
- ru
- sk
- sl
- so
- sq
- sr
- sv
- th
- tr
- uk
- uz
- vi
- zh-CN
- zh-TW
- zh
example: en
x-readme-id: '1.2'
phone:
type: string
description: >-
Nomor telepon dalam format E.164 (misalnya,
"+14155552671") yang akan digunakan selama langkah
[Verifikasi
Telepon](/id/core-technology/phone-verification/overview).
Jika tidak diberikan, pengguna harus memberikannya
selama alur verifikasi. Diabaikan untuk alur kerja
Verifikasi Bisnis (KYB). **Penting:** Nomor telepon ini
hanya diterapkan jika merupakan nomor telepon E.164 yang
valid. Jika nomor yang diberikan tidak valid atau tidak
dapat diurai, nomor tersebut akan diabaikan dan pengguna
akan dapat memasukkan nomor telepon valid apa pun selama
langkah Verifikasi Telepon.
example: '+14155552671'
x-readme-id: '1.3'
x-readme-id: '0.4'
expected_details:
type: object
description: >-
Detail pengguna yang diharapkan yang digunakan untuk
validasi silang terhadap data yang diekstraksi dari dokumen
identitas pengguna, Bukti Alamat, dan langkah verifikasi
lainnya. Ketidakcocokan dimunculkan sebagai peringatan pada
keputusan; beberapa kolom (misalnya `id_country`,
`expected_document_types`) juga mengubah alur bagi pengguna.
Untuk alur kerja Verifikasi Bisnis (KYB), hanya kolom bisnis
(`company_name`, `registry_country`, `registration_number`)
yang digunakan — kolom-kolom ini mengisi otomatis pencarian
registri perusahaan untuk pengguna — dan semua kolom tingkat
orang diabaikan.
example:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
nationality: USA
id_country: USA
expected_document_types:
- P
- ID
properties:
first_name:
type: string
description: >-
Nama depan pengguna. Misalnya, `John`. Pencocokan
menggunakan perbandingan fuzzy, dan Anda dapat
menyesuaikan tingkat ketatnya dengan mengonfigurasi
ambang batas skor kecocokan nama di Konsol untuk alur
kerja Dokumen Identitas dan Bukti Alamat.
example: John
x-readme-id: '1.0'
last_name:
type: string
description: >-
Nama belakang pengguna. Misalnya, `Doe`. Pencocokan
menggunakan perbandingan fuzzy, dan Anda dapat
menyesuaikan tingkat ketatnya dengan mengonfigurasi
ambang batas skor kecocokan nama di Konsol untuk alur
kerja Dokumen Identitas dan Bukti Alamat.
example: Doe
x-readme-id: '1.1'
date_of_birth:
type: string
format: date
description: >-
Tanggal lahir pengguna dengan format: YYYY-MM-DD.
Misalnya, `1990-05-15`.
example: '1990-05-15'
x-readme-id: '1.2'
gender:
type: string
nullable: true
enum:
- M
- F
default: null
description: >-
Jenis kelamin pengguna. Harus berupa 'M', 'F', atau
null.
example: M
x-readme-id: '1.3'
nationality:
type: string
description: >-
Kode negara ISO 3166-1 alpha-3 yang mewakili negara asal
pemohon. Misalnya, `USA`. Lihat [daftar lengkap kode
negara yang
didukung](https://docs.didit.me/id/core-technology/id-verification/supported-documents-id-verification#dokumen-yang-didukung-per-negara).
example: USA
x-readme-id: '1.4'
country:
type: string
description: >-
Kode negara ISO 3166-1 alpha-3 yang digunakan sebagai
cadangan untuk pemeriksaan ketidakcocokan negara
Verifikasi Identitas dan Bukti Alamat. Wajib diisi jika
`address` diberikan dan baik `id_country` maupun
`poa_country` tidak diatur.
example: USA
x-readme-id: 1.4.1
id_country:
type: string
description: >-
Kode negara ISO 3166-1 alpha-3 yang mewakili negara yang
diharapkan dari dokumen ID pemohon, yang mungkin berbeda
dari kewarganegaraan. Misalnya, `GBR`. Mengambil
prioritas di atas `country` untuk pemeriksaan
ketidakcocokan negara Verifikasi Identitas. Lihat
[daftar lengkap kode negara yang
didukung](https://docs.didit.me/id/core-technology/id-verification/supported-documents-id-verification#dokumen-yang-didukung-per-negara).
example: GBR
x-readme-id: '1.5'
poa_country:
type: string
description: >-
Kode negara ISO 3166-1 alpha-3 yang mewakili negara
dokumen Bukti Alamat yang diharapkan. Misalnya, `USA`.
Memiliki prioritas di atas `country` untuk pemeriksaan
ketidakcocokan negara POA. Lihat [daftar lengkap kode
negara yang
didukung](https://docs.didit.me/id/core-technology/id-verification/supported-documents-id-verification#dokumen-yang-didukung-per-negara).
example: USA
x-readme-id: 1.5.1
address:
type: string
description: >-
Alamat dalam format yang dapat dibaca manusia,
menyertakan sebanyak mungkin informasi. Misalnya, `123
Main St, San Francisco, CA 94105, USA`. Jika diberikan,
Anda juga harus meneruskan `country` atau `poa_country`,
jika tidak, permintaan gagal dengan `400`.
example: 123 Main St, San Francisco, CA 94105, USA
x-readme-id: '1.6'
identification_number:
type: string
description: >-
Nomor dokumen, nomor pribadi, atau nomor pajak pengguna.
Misalnya, `123456789`.
example: '123456789'
x-readme-id: '1.7'
ip_address:
type: string
description: >-
Alamat IP yang diharapkan untuk sesi, dalam format IPv4
atau IPv6. Jika alamat IP sebenarnya berbeda dari nilai
ini, peringatan akan dicatat. Misalnya, `192.168.1.100`
atau `2001:db8::1`.
example: 192.168.1.100
x-readme-id: '1.8'
expected_document_types:
type: array
description: >-
Membatasi jenis dokumen yang dapat ditunjukkan pengguna
selama langkah verifikasi identitas (OCR). Jika diatur,
layar pemilihan dokumen hanya menampilkan jenis yang
diminta dan `documents_allowed` yang dikembalikan
difilter sesuai pengaturan tersebut. Nilai tidak peka
huruf besar/kecil dan dideduplikasi; nilai yang tidak
dikenal ditolak dengan `400`. Kode yang diizinkan: `P`
(paspor), `ID` (kartu identitas nasional), `DL` (SIM),
`RP` (izin tinggal), `HIC` (kartu asuransi kesehatan),
`TC` (kartu pajak), `SSC` (kartu jaminan sosial).
items:
type: string
enum:
- P
- ID
- DL
- RP
- HIC
- TC
- SSC
example:
- P
- ID
x-readme-id: '1.9'
company_name:
type: string
maxLength: 255
description: >-
Nama resmi yang diharapkan dari bisnis yang sedang
diverifikasi. Misalnya, `Tesco PLC`. Mengisi otomatis
kolom nama perusahaan pada pencarian registri di alur
kerja Verifikasi Bisnis (KYB); jika
`registration_number` juga disediakan, pencarian
registri menggabungkan kedua pengidentifikasi. Diabaikan
untuk alur kerja KYC.
example: Tesco PLC
x-readme-id: '1.10'
registry_country:
type: string
maxLength: 10
description: >-
Kode ISO 3166-1 alpha-2 untuk negara tempat bisnis
terdaftar di registri perusahaannya. Misalnya, `GB`.
Jika registri perusahaan beroperasi di tingkat negara
bagian atau provinsi, tambahkan kode subdivisi ISO
3166-2 sebagai `XX-YY`: `US-CA` menargetkan registri
California. Format yang sama seperti `country_code` pada
[API Pencarian Registri
KYB](https://docs.didit.me/id/standalone-apis/kyb-registry-search).
Memilih negara registri terlebih dahulu dalam alur kerja
Verifikasi Bisnis (KYB); diabaikan untuk alur kerja KYC.
example: US-CA
x-readme-id: '1.11'
registration_number:
type: string
maxLength: 100
description: >-
Nomor registrasi bisnis yang diharapkan di registri
perusahaan. Misalnya, `00445790`. Mengisi otomatis kolom
nomor registrasi pada pencarian registri di alur kerja
Verifikasi Bisnis (KYB); jika `company_name` juga
disediakan, pencarian registri menggabungkan kedua
pengidentifikasi. Diabaikan untuk alur kerja KYC.
example: '00445790'
x-readme-id: '1.12'
x-readme-id: '0.5'
portrait_image:
type: string
format: byte
description: >-
Gambar potret wajah pengguna akhir yang di-encode Base64
(maks 2MB; JPEG, PNG, WebP, atau TIFF). Digunakan sebagai
gambar referensi untuk dicocokkan dengan tangkapan liveness
saat alur kerja merupakan alur kerja `Biometric
Authentication` dengan Pencocokan Wajah diaktifkan, atau
alur kerja graf apa pun di mana Pencocokan Wajah berjalan
sebelum Verifikasi Identitas (OCR). Opsional jika pengguna
`vendor_data` sudah memiliki gambar wajah yang tersimpan:
Didit menggunakannya kembali secara otomatis, ditentukan
berdasarkan urutan prioritas: wajah liveness yang disetujui,
foto chip ePassport, potret dokumen identitas, wajah profil
yang didaftarkan secara manual (hanya wajah dari sesi yang
disetujui atau wajah yang Anda daftarkan sendiri yang
digunakan kembali). Jika diberikan, `portrait_image` selalu
diutamakan daripada wajah yang tersimpan. Jika dihilangkan
dan tidak ada wajah tersimpan yang ditemukan (atau
`vendor_data` tidak dikirim), pembuatan sesi gagal dengan
`400`. Diabaikan untuk jenis alur kerja lainnya.
example: >-
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=
x-readme-id: '0.6'
sandbox_scenario:
type: string
description: >-
Slug skenario khusus sandbox. Hanya diterima jika kunci API
milik aplikasi mode sandbox; ditolak pada aplikasi produksi.
Saat disetel, alur pembuatan akan menyematkan nilai ajaib
yang dibundel skenario ke dalam kolom input sesi
(contact_details, expected_details) sehingga penyedia tiruan
menghasilkan hasil skenario tersebut melalui alur kerja
nyata. Lihat katalog skenario di GET /v1/sandbox/scenarios/
atau [Sandbox & Data Uji](/id/integration/sandbox-testing).
Anda juga dapat mengaktifkan (atau mengaktifkan ulang)
skenario setelah pembuatan melalui POST
/v3/session/{sessionId}/sandbox/arm/, selama sesi masih `Not
Started`. Untuk pencarian non-dokumen, gunakan
`lookup_partial_match`, `lookup_no_match`, atau
`lookup_provider_error` untuk menguji anggaran percobaan dan
fallback yang dikonfigurasi. Untuk dompet identitas, gunakan
`wallet_cancelled`, `wallet_timeout`, atau
`wallet_provider_error`; `approve` mensimulasikan dompet
yang terverifikasi. Semua dompet katalog dapat diuji di
sandbox, termasuk skema yang tidak tersedia di aplikasi
produksi. Percobaan yang disimulasikan tidak dikenakan
biaya.
example: decline_document_expired
sign:
type: object
description: >-
Input Tanda Tangan Elektronik untuk sesi ini. `documents`
adalah dokumen yang akan ditandatangani, untuk alur kerja
yang langkah Tanda Tangan Elektronik-nya mengambil dokumen
dari sesi (`signature_documents_source` `session` atau
`both`): hingga 20 dokumen dan total 50 MB. `field_values`
mengisi kolom yang `prefill`-nya adalah `api.`, baik
pada dokumen alur kerja maupun sesi. Membuat sesi kembali
untuk `workflow_id` dan `vendor_data` yang sama akan
mengembalikan sesi yang tertunda; jika panggilan tersebut
mengirimkan `sign`, dokumen, kolom, dan nilainya harus
identik dengan yang pertama, dan perbedaan apa pun
mengembalikan `400` dengan `{"sign":
"signature_document_changed"}`. Lihat [Dokumen Tanda Tangan
Elektronik](/id/sessions-api/create-session#dokumen-tanda-tangan-elektronik).
properties:
documents:
type: array
minItems: 1
maxItems: 20
items:
$ref: '#/components/schemas/SessionSignDocument'
field_values:
type: object
description: >-
Nilai yang diindeks berdasarkan `` dari setiap
sumber pra-isi `api.`: string sepanjang 1 hingga
500 karakter untuk kolom `text` dan `data`, boolean
untuk `checkbox`. `400` dengan `field_value_unknown`
untuk kunci yang tidak digunakan oleh kolom mana pun,
`field_value_missing` untuk kolom wajib tanpa nilainya,
dan `field_value_invalid` untuk nilai yang gagal dalam
validasi kolomnya.
additionalProperties:
oneOf:
- type: string
minLength: 1
maxLength: 500
- type: boolean
example:
credit_limit: 3,000 EUR
user_state:
type: string
maxLength: 16
description: >-
Tempat tinggal individu tersebut, jika Anda mengetahuinya:
kode subdivisi ISO 3166-2 (`US-IL`, `ES-M`) atau kode atau
nama negara bagian AS (`IL`, `Illinois`). Negara bagian yang
hukumnya mewajibkan persetujuan biometrik eksplisit
(Illinois, Texas, Colorado) membuat alur verifikasi
memintanya sebelum mengambil wajah, dengan pemicu
`declared_state`. Nilai yang tidak dikenali mengembalikan
`400`. Lihat [Persetujuan
biometrik](/id/getting-started/biometric-consent).
example: US-IL
biometric_consent:
type: object
description: >-
Persetujuan biometrik eksplisit yang telah Anda kumpulkan
dari orang tersebut. Ini memenuhi persyaratan, sehingga alur
verifikasi tidak meminta lagi, dan keputusan mencatatnya
sebagai `status: "given"` dengan pemicu
`customer_collected`. Jawaban yang sudah diberikan oleh
orang tersebut dalam alur tidak pernah digantikan. Lihat
[Persetujuan
biometrik](/id/getting-started/biometric-consent).
required:
- given_at
- text_version
properties:
given_at:
type: string
format: date-time
description: >-
Waktu pengguna memberikan persetujuan biometrik
eksplisit (ISO 8601). Tidak boleh di masa mendatang.
text_version:
type: string
maxLength: 64
description: >-
ID versi dari teks persetujuan yang disetujui individu
tersebut, dalam catatan Anda sendiri.
example:
workflow_id: 11111111-2222-3333-4444-555555555555
vendor_data: user-123
callback: https://example.com/verification/callback
callback_method: both
metadata:
user_type: premium
account_id: ABC123
language: en
contact_details:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
expected_details:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
id_country: USA
expected_document_types:
- P
- ID
examples:
Create KYC session:
summary: >-
Payload alur sukses lengkap untuk sesi Verifikasi Pengguna
(KYC)
description: >-
Panggilan pembuatan realistis yang menggunakan setiap kolom
yang umum diatur: pemilihan alur kerja, tautan vendor,
perutean callback, metadata, pengaturan lokal, pra-pengisian
kontak, dan detail pengguna yang diharapkan. Salin dan tempel
ini langsung ke contoh cURL di atas.
value:
workflow_id: 11111111-2222-3333-4444-555555555555
vendor_data: user-123
callback: https://example.com/verification/callback
callback_method: both
metadata:
user_type: premium
account_id: ABC123
language: en
contact_details:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
expected_details:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
nationality: USA
id_country: USA
expected_document_types:
- P
- ID
Create KYB session:
summary: Payload alur sukses untuk sesi Verifikasi Bisnis (KYB)
description: >-
Struktur yang sama dengan panggilan KYC — `workflow_id` adalah
penentu yang menjadikan sesi sebagai KYB. `vendor_data`
biasanya mereferensikan perusahaan di sistem Anda dan
`contact_details.email` ditujukan kepada perwakilan hukum yang
akan menyelesaikan alur; `expected_details` menerima kolom
bisnis (`company_name`, `registry_country`,
`registration_number`), yang digunakan untuk mengisi pencarian
registri perusahaan terlebih dahulu; kolom tingkat individu
dan `contact_details.phone` diabaikan untuk alur kerja KYB.
value:
workflow_id: 33333333-4444-5555-6666-777777777777
vendor_data: company-acme-001
callback: https://example.com/kyb/callback
callback_method: both
metadata:
tier: enterprise
company_id: ACME-001
expected_details:
company_name: Tesco PLC
registry_country: GB
registration_number: '00445790'
language: en
contact_details:
email: legal-rep@acme.example.com
send_notification_emails: true
email_lang: en
responses:
'201':
description: >-
Sesi dibuat (atau dikembalikan, jika sesi yang belum selesai dengan
`vendor_data` yang sama sudah ada pada versi alur kerja terbaru yang
dipublikasikan). Responsnya adalah sesi yang diserialisasi, termasuk
`url` verifikasi yang di-hosting untuk mengarahkan pengguna.
content:
application/json:
schema:
type: object
required:
- session_id
- session_number
- session_token
- url
- vendor_data
- metadata
- status
- workflow_id
- workflow_version
- callback
properties:
session_id:
type: string
format: uuid
description: >-
Pengenal unik sesi verifikasi. Gunakan id ini saat
memanggil `GET /v3/session/{sessionId}/decision/`.
example: 11111111-2222-3333-4444-555555555555
session_number:
type: integer
description: >-
Nomor urut yang mudah dibaca manusia dan ditetapkan ke
sesi di dalam aplikasi Anda. Berguna untuk dukungan dan
dasbor.
example: 43762
session_token:
type: string
description: >-
Token 12 karakter yang aman untuk URL yang mengizinkan
pengguna akhir untuk mengakses alur verifikasi yang
di-hosting di `url`. Berlaku sampai sesi kedaluwarsa.
Perlakukan sebagai rahasia — siapa pun yang memilikinya
dapat membuka alur verifikasi untuk sesi ini.
example: 3FaJ9wLqX2Mz
url:
type: string
format: uri
description: >-
URL verifikasi yang di-hosting untuk mengarahkan pengguna
akhir. URL ini menyematkan `session_token` dan, jika
dikonfigurasi, menggunakan domain White Label Anda. Jika
permintaan menyertakan `language`, URL tersebut berisi
segmen jalur bahasa -
`https://verify.didit.me/{language}/session/{session_token}`
(misalnya `/es/session/...`); tanpa `language`, segmen
tersebut dihilangkan.
example: https://verify.didit.me/session/3FaJ9wLqX2Mz
vendor_data:
type: string
nullable: true
description: >-
Pengenal yang Anda teruskan dalam permintaan untuk
menautkan sesi ke pengguna atau bisnis di sistem Anda
sendiri. Dikembalikan secara persis sama. Bernilai null
jika tidak diberikan.
example: user-123
metadata:
description: >-
Payload JSON arbitrer yang Anda simpan bersama sesi pada
saat pembuatan. Dikembalikan persis apa adanya — nilai
JSON apa pun yang Anda kirim (objek, string, angka, array)
dikembalikan sebagaimana mestinya, meskipun objek JSON
disarankan. Tidak ditampilkan kepada pengguna akhir.
Selalu ada dalam respons; `null` jika tidak diberikan pada
saat pembuatan.
example:
user_type: premium
account_id: ABC123
tags:
type: array
items:
type: string
description: Tag pada sesi, berdasarkan nama.
example:
- VIP
- ONBOARDING Q4
status:
type: string
enum:
- Not Started
- In Progress
- Approved
- Declined
- In Review
- Expired
- Abandoned
- Kyc Expired
- Resubmitted
- Awaiting User
description: >-
Status sesi saat ini. Sesi yang baru dibuat mengembalikan
`Not Started`. Jika sesi yang belum selesai sudah ada
untuk `vendor_data` yang sama pada versi publikasi terbaru
dari alur kerja, status yang dikembalikan mencerminkan
sesi yang sudah ada tersebut.
example: Not Started
callback:
type: string
format: uri
nullable: true
description: >-
URL pengalihan akhir tempat pengguna diarahkan setelah
menyelesaikan alur. Didit menambahkan
`?verificationSessionId={session_id}&status={status}` ke
URL ini. Kembali ke URL callback alur kerja yang
dikonfigurasi jika tidak diberikan dalam permintaan;
`null` jika keduanya tidak diatur. Jika aplikasi memiliki
domain yang diizinkan dan URL ini adalah URL web di luar
domain tersebut (misalnya default alur kerja yang diatur
sebelum daftar diubah), alur yang di-hosting tidak
mengalihkan pengguna ke URL tersebut.
example: https://example.com/verification/callback
workflow_id:
type: string
format: uuid
description: >-
Pengidentifikasi stabil dari alur kerja tempat sesi ini
berjalan. Selalu merupakan pengidentifikasi grup stabil
dari alur kerja — meskipun Anda mereferensikan UUID versi
alur kerja tertentu dalam permintaan (pencarian yang
kompatibel dengan versi sebelumnya), respons tetap membawa
`workflow_id` yang stabil. Gunakan ini untuk
mengorelasikan sesi dengan alur kerja yang Anda
konfigurasikan di Konsol.
example: 11111111-2222-3333-4444-555555555555
workflow_version:
type: integer
description: >-
Nomor versi dari versi alur kerja yang dipublikasikan
tempat sesi disematkan saat pembuatan. Didit menentukan
versi alur kerja terbaru yang dipublikasikan untuk
`workflow_id` saat sesi dibuat, dan sesi tetap menjalankan
versi tersebut bahkan jika alur kerja dipublikasikan ulang
nanti.
example: 3
examples:
KYC session:
summary: Sesi KYC dibuat
value:
session_id: 11111111-2222-3333-4444-555555555555
session_number: 43762
session_token: 3FaJ9wLqX2Mz
url: https://verify.didit.me/en/session/3FaJ9wLqX2Mz
vendor_data: user-123
metadata:
user_type: premium
account_id: ABC123
status: Not Started
workflow_id: 11111111-2222-3333-4444-555555555555
workflow_version: 3
callback: https://example.com/verification/callback
KYB session:
summary: Sesi KYB dibuat
value:
session_id: 22222222-3333-4444-5555-666666666666
session_number: 43763
session_token: Yk7pQ2vN8aBc
url: https://verify.didit.me/en/session/Yk7pQ2vN8aBc
vendor_data: company-acme-001
metadata:
tier: enterprise
status: Not Started
workflow_id: 33333333-4444-5555-6666-777777777777
workflow_version: 1
callback: https://example.com/kyb/callback
'400':
description: >-
Permintaan tidak valid — payload gagal validasi (`workflow_id` tidak
ada atau tidak dikenal, `language` tidak valid, `vendor_data` masuk
daftar blokir, `portrait_image` salah bentuk, `address` tanpa
`country`/`poa_country`, `sandbox_scenario` tidak valid, dokumen,
kolom, atau nilai `sign` ditolak oleh langkah Tanda Tangan
Elektronik alur kerja, seperti `signature_document_not_supported`,
`signature_document_conversion_failed`, `field_anchor_not_found`,
atau `field_value_missing`, dll.) atau organisasi Anda tidak
memiliki cukup kredit untuk memulai sesi.
Isi respons berupa objek dengan kunci nama kolom yang bermasalah
(atau `detail` untuk kesalahan di luar kolom). Nilai berupa **larik
string** untuk kegagalan validasi input (misalnya kolom wajib yang
hilang, bahasa tidak valid, gambar potret melebihi batas ukuran) dan
**string biasa** untuk kegagalan yang terdeteksi saat membuat sesi
(`workflow_id` tidak dikenal, `vendor_data` masuk daftar blokir,
tidak ada wajah referensi yang tersedia untuk alur kerja Pencocokan
Wajah). Tangani kedua bentuk respons tersebut.
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
detail:
type: string
description: >-
Pesan kesalahan yang mudah dibaca manusia untuk kesalahan
non-kolom (mis. kredit tidak mencukupi). Kegagalan tingkat
kolom menggunakan nama kolom sebagai kunci, dengan nilai
string atau array yang berisi string.
example: >-
You don't have enough credits to perform this request.
Please top up at https://business.didit.me
examples:
Missing workflow_id:
summary: Kolom wajib tidak disertakan (bentuk array string)
value:
workflow_id:
- This field is required.
Invalid workflow_id:
summary: workflow_id tidak dikenal (bentuk string biasa)
value:
workflow_id: Invalid workflow_id.
Insufficient credits:
summary: Organisasi kehabisan kredit
value:
detail: >-
You don't have enough credits to perform this request.
Please top up at https://business.didit.me
Blocklisted vendor_data:
summary: vendor_data masuk dalam daftar blokir
value:
vendor_data: >-
This user or business has been blocked and cannot create
new verification sessions.
Portrait image too large:
summary: portrait_image gagal dalam validasi ukuran
value:
portrait_image:
- Image size exceeds 2MB.
No stored face for vendor_data:
summary: >-
Alur kerja Pencocokan Wajah tanpa portrait_image dan tanpa
wajah tersimpan untuk pengguna vendor_data
value:
portrait_image: >-
No stored face image was found for this user. Send a
portrait_image, or complete an approved verification with
face liveness or an ID document for this vendor_data
first.
Portrait image required without vendor_data:
summary: >-
Alur kerja Pencocokan Wajah tanpa portrait_image dan tanpa
vendor_data
value:
portrait_image: >-
A portrait image is required to perform face match for
this workflow. Send a portrait_image, or provide the
vendor_data of a user with a previously stored face image
to reuse it.
'403':
description: >-
Autentikasi atau otorisasi gagal. Kunci yang salah, dicabut, atau
kedaluwarsa mengembalikan `401`. Endpoint mengembalikan `403` jika
header `x-api-key` tidak ada atau kunci API valid tetapi klien tidak
memiliki izin untuk membuat sesi di aplikasi ini (misalnya kunci API
milik organisasi yang berbeda). Kegagalan ini memiliki body respons
yang sama: `{"detail": "You do not have permission to perform this
action."}`. Periksa apakah header `x-api-key` ada dan milik aplikasi
yang dimaksud, ambil kembali kunci API aplikasi melalui [Auth
API](/id/auth-api/get-credentials) jika diperlukan, lalu coba lagi.
**Aplikasi yang dihapus:** selama beberapa menit setelah aplikasi
dihapus, permintaan yang dibuat dengan salah satu kunci API-nya
dapat mengembalikan `{"detail": "This application was deleted.",
"code": "application_deleted"}`. Jangan coba lagi: aplikasi dan
kunci API-nya sudah tidak ada. Setelah beberapa menit tersebut,
kunci akan ditolak seperti kunci tidak valid lainnya.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: You do not have permission to perform this action.
code:
type: string
description: >-
Alasan yang dapat dibaca mesin, hanya ada pada beberapa
kegagalan. `application_deleted`: kunci API milik aplikasi
yang telah dihapus.
example: application_deleted
required:
- detail
examples:
Missing or invalid API key:
summary: Tidak ada header `x-api-key` atau kunci API tidak valid
value:
detail: You do not have permission to perform this action.
No permission:
summary: Klien tidak dapat membuat sesi
value:
detail: You do not have permission to perform this action.
Application deleted:
summary: Kunci API dari aplikasi yang dihapus
value:
detail: This application was deleted.
code: application_deleted
'429':
description: >-
Batas laju terlampaui — lebih dari 600 permintaan pembuatan sesi
dalam jendela 60 detik dari kunci API / IP yang sama. Periksa
`Retry-After` dan lakukan backoff sebelum mencoba lagi.
**Catatan:** Kode sumber juga mendefinisikan
`FREE_SESSION_RATE_LIMIT` sebesar 10 panggilan/menit bersama dengan
`PAID_SESSION_RATE_LIMIT=600` (`sessions/serializers/session.py`),
tetapi batas atas paket gratis tersebut **tidak diterapkan pada
endpoint V3 ini** — middleware batas laju memberlakukan
`SESSION_CREATE_RATE_LIMIT` 600/menit apa pun paketnya. 600/menit
adalah satu-satunya batasan yang dapat Anda capai di sini.
headers:
Retry-After:
description: >-
Detik yang harus ditunggu pemanggil sebelum mencoba lagi
mengirimkan permintaan.
schema:
type: integer
minimum: 1
example: 42
X-RateLimit-Limit:
description: >-
Jumlah permintaan maksimum yang diizinkan dalam jendela 60 detik
saat ini untuk batas yang terlampaui (600 untuk pembuatan sesi).
Tidak ada pada varian kuota sandbox.
schema:
type: integer
example: 600
X-RateLimit-Remaining:
description: >-
Jumlah permintaan yang masih diizinkan pada jendela saat ini
untuk batas yang dilanggar. Tidak ada pada varian kuota sandbox.
schema:
type: integer
minimum: 0
example: 0
X-RateLimit-Reset:
description: >-
Detik epoch UTC saat jendela batas laju saat ini disetel ulang.
Tidak ada pada varian kuota sandbox.
schema:
type: integer
minimum: 0
example: 1747497600
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: >-
Penjelasan pelanggaran batas laju yang mudah dibaca
manusia. Gunakan pesan ini untuk membedakan batas mana
dari ketiga batas yang terlampaui.
example: >-
Session creation rate limit exceeded. You can make up to
600 requests per minute.
examples:
Session-create limit:
summary: Lebih dari 600 permintaan pembuatan sesi per menit
value:
detail: >-
Session creation rate limit exceeded. You can make up to
600 requests per minute.
Sandbox session quota:
summary: Aplikasi sandbox melebihi 500 sesi dalam 24 jam
value:
detail: >-
Sandbox session quota exceeded (500 sessions per 24h).
Wait for the window to reset. Expected available in 3600
seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
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.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{\n\tWorkflowID: \"11111111-2222-3333-4444-555555555555\",\n\tVendorData: didit.String(\"user-123\"),\n\tCallback: didit.String(\"https://example.com/verification/callback\"),\n\tCallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod(\"both\")),\n\tMetadata: didit.Some[any](map[string]any{\"user_type\": \"premium\", \"account_id\": \"ABC123\"}),\n\tLanguage: didit.Some(didit.SessionsCreateParamsLanguage(\"en\")),\n\tContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{\n\t\tEmail: didit.String(\"john.doe@example.com\"),\n\t\tSendNotificationEmails: didit.Bool(true),\n\t\tEmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang(\"en\")),\n\t\tPhone: didit.String(\"+14155552671\"),\n\t}),\n\tExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{\n\t\tFirstName: didit.String(\"John\"),\n\t\tLastName: didit.String(\"Doe\"),\n\t\tDateOfBirth: didit.String(\"1990-05-15\"),\n\t\tNationality: didit.String(\"USA\"),\n\t\tIDCountry: didit.String(\"USA\"),\n\t\tExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{\"P\", \"ID\"}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: |-
import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new
SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
SessionSignDocument:
type: object
required:
- file_name
- content_base64
properties:
title:
type: string
minLength: 1
maxLength: 255
description: >-
Judul yang ditampilkan kepada penandatangan. Defaultnya adalah
`file_name`.
file_name:
type: string
minLength: 1
maxLength: 255
description: Nama file, berakhiran `.pdf` atau `.docx`.
content_base64:
type: string
format: byte
description: >-
File, berenkode base64. PDF dapat berukuran hingga 20 MB dan 100
halaman, tanpa kata sandi, skrip, atau file terlampir. File Word
(`.docx`) dapat berukuran hingga 20 MB dan dikonversi ke PDF saat
permintaan berjalan, maksimal dalam 25 detik; PDF tersebut kemudian
memiliki batas yang sama. Hingga 5 file Word per sesi. File Word
dengan makro, perubahan terlacak, tautan ke konten eksternal, atau
objek yang disematkan akan ditolak dengan
`signature_document_not_supported`, dan file yang tidak dapat
dikonversi mengembalikan `signature_document_conversion_failed`,
masing-masing disertai `reason`.
fields:
type: array
description: >-
Kolom opsional untuk ditempatkan pada dokumen ini, hingga 200.
Halaman dan posisi merujuk ke PDF, atau ke PDF hasil konversi untuk
file Word. Tanpa kolom, penandatangan membaca dokumen dan
menyetujuinya.
items:
$ref: '#/components/schemas/SignatureField'
maxItems: 200
SignatureField:
type: object
description: >-
Kolom yang akan ditempatkan pada dokumen sesi: penandatangan mana yang
mengisinya, bagaimana caranya, dan di mana posisinya. Berikan posisi
(`page`, `x`, `y`, `width`, dan `height`) atau sebuah `anchor`. Posisi
berupa pecahan dari halaman seperti yang ditampilkan, dari sudut kiri
atasnya, dibulatkan ke 4 desimal, dan kolom harus pas di dalam halaman.
Sebuah dokumen dapat memuat hingga 200 kolom dan satu penandatangan
hingga 500, serta setiap peran dengan kolom pada dokumen memerlukan
kolom `signature` atau `initials` di sana. Lihat [Kolom pada
dokumen](/id/core-technology/electronic-signature/overview#kolom-pada-dokumen).
required:
- key
- type
properties:
key:
type: string
pattern: ^[a-z][a-z0-9_]{0,63}$
description: >-
Nama kolom dalam hasil dan dalam `sign.field_values`. Unik di dalam
dokumen.
type:
type: string
enum:
- signature
- initials
- full_name
- date_signed
- text
- checkbox
- email
- data
description: >-
Apa yang dimuat oleh kolom ini. Penandatangan menerapkan `signature`
dan `initials` yang mereka gunakan, mengetik `text`, mencentang
`checkbox`, dan mengetik `email` saat sesi tidak memiliki email
terverifikasi. Didit mengisi `full_name` (nama terverifikasi),
`date_signed` (tanggal penandatanganan, dalam zona waktu
penandatangan), `data` (dari `prefill`), dan `email` terverifikasi,
lalu menampilkannya sebagai hanya-baca. Tidak ada jenis pemilih
tanggal: gunakan `text`.
role:
type: string
enum:
- verified_person
- legal_representative
- key_people
description: >-
Pihak yang mengisi kolom, dengan nilai `signature_signer`. Suatu
langkah hanya mengisi dan membubuhkan stempel pada kolom
penandatangan miliknya sendiri. Default ke penandatangan langkah
tersebut.
page:
type: integer
minimum: 1
description: >-
Nomor halaman, dari 1 hingga jumlah halaman dokumen. Untuk dokumen
Word, halaman dari PDF yang dikonversi.
x:
type: number
minimum: 0
maximum: 1
description: Tepi kiri, sebagai fraksi dari lebar halaman.
'y':
type: number
minimum: 0
maximum: 1
description: Tepi atas, sebagai fraksi dari tinggi halaman.
width:
type: number
minimum: 0.02
maximum: 1
description: >-
Lebar, sebagai fraksi dari lebar halaman. Tanda tangan memiliki
lebar minimal `0.12`.
height:
type: number
minimum: 0.012
maximum: 1
description: >-
Tinggi, sebagai fraksi dari tinggi halaman. Tanda tangan memiliki
tinggi minimal `0.035`.
anchor:
$ref: '#/components/schemas/SignatureFieldAnchor'
required:
type: boolean
description: >-
`signature` and `initials` are required unless you set `false`.
`full_name`, `date_signed` and `data` are always required. The
signer can't finish a document until its required fields have a
value, and a required checkbox must be ticked.
label:
type: string
minLength: 1
maxLength: 80
description: >-
Ditampilkan kepada penandatangan dan di dalam hasil. Nilai default
diambil dari jenisnya.
placeholder:
type: string
nullable: true
maxLength: 80
description: Hanya `text` dan `email`.
validation:
$ref: '#/components/schemas/SignatureFieldValidation'
prefill:
type: string
nullable: true
description: >-
Asal nilai: `identity.full_name`, `identity.first_name`,
`identity.last_name`, `identity.date_of_birth` (`DD/MM/YYYY`),
`identity.nationality`, `identity.document_number`,
`identity.document_type`, `identity.issuing_country`,
`identity.address`, `contact.email`, `contact.phone`,
`company.name`, `company.registration_number`, `company.address`,
`company.country` (KYB), `session.vendor_data`, `metadata.`
(kunci dari `metadata` sesi), atau `api.` (kunci dari
`sign.field_values`). Wajib diisi untuk `data`. `full_name` selalu
menggunakan `identity.full_name` dan `email` menggunakan
`contact.email`. Nilai kolom `data`, `full_name`, dan `email`
terverifikasi ditetapkan saat penandatangan mulai menandatangani.
editable_when_prefilled:
type: boolean
default: false
description: >-
Hanya `text` dan `email`: penandatangan dapat mengubah nilai yang
telah diisi sebelumnya.
checked_by_default:
type: boolean
default: false
description: 'Hanya `checkbox`: kotak dimulai dalam keadaan dicentang.'
date_format:
type: string
enum:
- DD/MM/YYYY
- MM/DD/YYYY
- YYYY-MM-DD
- D MMMM YYYY
default: DD/MM/YYYY
description: Hanya `date_signed`.
SignatureFieldAnchor:
type: object
description: >-
Menempatkan kolom berdasarkan penggalan teks dalam dokumen, bukan
berdasarkan posisi. Didit tidak menghapus teks dari PDF, jadi tuliskan
teks tersebut dengan warna yang sama seperti latar belakang halaman.
Jika teks tidak ditemukan, panggilan mengembalikan `400` dengan
`field_anchor_not_found`. Lihat [Menempatkan kolom berdasarkan teks
jangkar](/id/sessions-api/create-session#menempatkan-kolom-dengan-teks-penanda).
required:
- text
properties:
text:
type: string
minLength: 1
maxLength: 64
description: >-
Teks yang dicari dalam dokumen. Untuk file Word, dalam PDF yang
dikonversi.
occurrence:
type: string
enum:
- first
- all
default: first
description: >-
`all` menempatkan satu kolom per kecocokan; kunci setelah yang
pertama mendapatkan `_2`, `_3`, dan seterusnya.
offset_x:
type: number
description: Ditambahkan ke tepi kiri teks, sebagai fraksi dari lebar halaman.
offset_y:
type: number
description: Ditambahkan ke tepi atas teks, sebagai fraksi dari tinggi halaman.
width:
type: number
minimum: 0.02
maximum: 1
description: Lebar kolom, sebagai fraksi dari lebar halaman.
height:
type: number
minimum: 0.012
maximum: 1
description: Tinggi kolom, sebagai fraksi dari tinggi halaman.
SignatureFieldValidation:
type: object
nullable: true
description: >-
Aturan untuk nilai kolom `text`. Pratinjau konsol, alur penandatanganan,
dan API menerapkan aturan yang sama.
properties:
kind:
type: string
enum:
- any
- letters
- number
- email
- pattern
description: >-
`letters`: huruf dalam aksara apa pun, spasi, tanda hubung, dan
apostrof. `number`: digit dengan pemisah desimal opsional.
`pattern`: nilai harus cocok dengan `pattern`.
min_length:
type: integer
minimum: 0
maximum: 500
description: Dari `0` hingga `max_length`.
max_length:
type: integer
minimum: 1
maximum: 500
default: 120
pattern:
type: string
nullable: true
minLength: 1
maxLength: 200
description: >-
Wajib diisi dengan `kind: "pattern"`. Ekspresi reguler yang harus
cocok dengan keseluruhan nilai. Lookaround dan backreference tidak
didukung.
message:
type: string
nullable: true
maxLength: 120
description: Ditampilkan kepada penandatangan alih-alih error default.
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.