Membuat prosesPOST

Mulai proses dan dapatkan Human Token serta intelligence orang tersebut.

Markdown

POST /v1/processes

Memulai proses dengan salah satu flow dan menjawab dengan id, state, dan hasil di data: Human Token dan intelligence orang tersebut, data.ndocs.

Sebelum memanggil

• Human Plugin sedang berjalan dan GET /health/ready menjawab 200.
• Access key Anda diaktifkan untuk flow yang Anda gunakan.
• Jika Anda mengirim dokumen, type-nya ada di katalog atribut.

Flow

Field flow menentukan apa yang dilakukan proses. Human Plugin menjalankan flow berikut, dalam dua model integrasi:

• API Only: back-end Anda mengirim selfie di imageBase64, dan pembuatan langsung menjawab dengan hasilnya.
• Human Token Journey: orang tersebut mengambil selfie di journey pengambilan dan kembali ke callbackUri Anda. Pembuatan menjawab dengan token dan link, dan Anda membaca hasilnya dengan Mengambil proses.

Flow	Description	Possible result	Integration components required	Example
api+humantoken	Menerima selfie melalui back-end Anda dan menghasilkan Human Token, pengenal wajah yang unik. Jawabannya final: tanpa pengambilan, tanpa panggilan kedua.	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	Mengambil selfie di journey pengambilan, dengan pemeriksaan deteksi kehidupan, dan menghasilkan Human Token. Pembuatan mengembalikan `token` dan `link`; baca hasilnya saat pengambilan selesai.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb
humantoken+revalidation	Mengambil selfie dan membandingkan wajah dengan Human Token yang Anda harapkan. Mengembalikan apakah orangnya sama atau tidak, misalnya sebelum tindakan sensitif.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb

clientId, correlationId, dan credential sama di setiap flow.

Permintaan

{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<selfie base64>"
}

Field umum

Field	Wajib	Batas (byte)	Catatan
flow	Ya	64	Salah satu dari flow
clientId	Ya	128	Id klien milik Anda. Intelligence menghitung nilai yang berbeda
correlationId	Ya	128	Referensi Anda untuk proses ini. Unik: nilai yang sudah dimiliki proses lain, apa pun statusnya, ditolak dengan 409
credential	Ya, tetapi boleh kosong		Key harus ada. Lihat di bawah
credential.type	Dengan dokumen		Kode dari katalog atribut, persis dan peka huruf besar/kecil
credential.value	Dengan dokumen	64	Nomor dokumen

flow, clientId, dan correlationId harus berupa string, tanpa karakter kontrol dan tanpa spasi di awal atau akhir. Nilai yang tidak valid ditolak, tidak pernah ditulis ulang.

Field credential

• Dengan dokumen: objek dengan tepat type dan value, keduanya string, dikirim bersamaan.
• Tanpa dokumen: null atau {}. Proses tetap dihitung sebagai transaksi dan sebagai klien dalam intelligence.
• Dihilangkan, atau objek dengan string kosong: ditolak dengan 400 MISSING_CREDENTIAL_TYPE. Ini menangkap key yang salah eja sebelum apa pun diproses.
• Key lain apa pun di dalam credential ditolak.

Field flow

Apa yang ditambahkan setiap flow ke field umum:

Field	Flow	Wajib	Nilai
imageBase64	api+humantoken	Ya	Selfie dalam base64. PNG, JPEG, atau WebP, hingga 800 KB
callbackUri	humantoken, humantoken+revalidation	Ya	Tempat orang tersebut kembali saat pengambilan selesai: halaman milik Anda, atau URL scheme aplikasi Anda
references	humantoken+revalidation	Ya	Satu item berisi Human Token yang Anda harapkan, seperti pada contoh di atas

Human Plugin tidak menyimpan field ini, dan field opsional yang salah eja dapat diabaikan tanpa error.

Gunakan selfie frontal dengan pencahayaan baik berisi satu wajah untuk api+humantoken. Nilai yang bukan gambar ditolak, dan proses disimpan sebagai gagal: lihat Penolakan flow.

Dengan humantoken+revalidation, hasilnya memiliki humanTokenMatch sebagai ganti humanToken:

• "true": orangnya sama. Proses dihitung untuk orang tersebut, dan ndocs menggambarkannya.
• Nilai lain apa pun, atau pengambilan yang tidak live: tidak terkonfirmasi. Proses tidak dihitung untuk siapa pun, dan tidak ada ndocs.

PROCESS_STATE_FINISHED dijawab pada kedua kasus: baca humanTokenMatch. Lihat Mengambil proses.

Beberapa nama dicadangkan oleh Human Plugin dan ditolak dengan 400 INVALID_REQUEST, seperti clientReference. Begitu pula ejaan lain dari field milik Human Plugin sendiri, seperti client_id, correlation_id, atau Flow: hanya flow, clientId, correlationId, dan credential yang dibaca, dengan ejaan persis seperti itu.

Aturan body

• Satu objek JSON, maksimal 2 MiB (kira-kira cukup untuk selfie dalam base64). Body yang lebih besar ditolak dengan 400 REQUEST_TOO_LARGE.
• Tidak boleh ada apa pun setelah objek JSON.

Respons

201 Created, dengan Location: /v1/processes/<id>.

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

• id adalah UUID dari Human Plugin. Setiap permintaan yang diterima membuat yang baru.
• state adalah status lokal. Lihat siklus hidup.
• humantoken dan humantoken+revalidation menjawab PROCESS_STATE_CREATED dengan token dan link. Keduanya dikembalikan sekali saja dan tidak pernah disimpan: simpanlah. Lihat Human Token Journey dan panduan pengambilan untuk platform Anda.
• data.ndocs adalah intelligence orang tersebut. Bisa saja tidak ada: lihat Intelligence.

Hasil di data

Proses yang selesai memiliki field berikut di data. Flow Journey mengembalikannya saat Anda membaca proses setelah pengambilan.

Field	Kapan	Nilai
humanToken	api+humantoken, humantoken	Siapa orang tersebut: value adalah Human Token, dan status bernilai validated bila berhasil dihasilkan
humanTokenMatch	humantoken+revalidation	"true" bila orangnya sama dengan Human Token di references
liveness	Flow yang memeriksa deteksi kehidupan, seperti flow Journey	value bernilai live bila pengambilan berasal dari orang yang hidup, atau not_live bila tidak; status bernilai validated bila pemeriksaan berjalan
ndocs	Bila ada intelligence untuk orang tersebut	Intelligence orang tersebut

Hasil Journey tampak seperti ini:

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}

Periksa liveness sebelum memercayai hasilnya: dengan not_live, anggap pengambilan gagal dan minta orang tersebut mencoba lagi. Proses dengan not_live tidak dihitung dalam intelligence siapa pun.

Error

Status	message	Arti
400	INVALID_REQUEST, REQUEST_TOO_LARGE	Bukan satu objek JSON, field yang dicadangkan, tipe salah, atau body lebih dari 2 MiB
400	MISSING_<FIELD>, INVALID_<FIELD>	Field wajib tidak ada atau formatnya salah, seperti MISSING_CLIENT_ID
401	Kosong ("")	Unico menolak access key Anda: tidak ada, salah, atau sudah tidak berlaku. Proses disimpan sebagai gagal. Periksa HUMAN_API_ACCESS_KEY
409	CORRELATION_ID_ALREADY_USED	Proses lain sudah memiliki correlationId tersebut. Tidak ada yang disimpan atau dikirim
422	ATTRIBUTE_TYPE_NOT_SUPPORTED	credential.type tidak ada di katalog. Tidak ada yang disimpan atau dikirim
4xx	message dari flow	Flow menolak permintaan, misalnya gambar tidak valid. Lihat Penolakan flow
502	UPSTREAM_UNAVAILABLE	Proses tidak dapat dikonfirmasi tepat waktu
503	DATABASE_UNAVAILABLE	Database gagal. Tidak ada yang diproses
500	INTERNAL	Error tak terduga

Penolakan flow

Ketika flow menolak permintaan, pembuatan menjawab 4xx dengan alasan di message, dalam envelope yang biasa. Yang paling umum:

message	Penyebab
invalid flow	flow bukan flow yang diaktifkan untuk akun Anda
INVALID_IMAGE (400)	api+humantoken tanpa imageBase64
INVALID_REQUEST (400)	imageBase64 bukan gambar dalam base64
IMAGE_TOO_LARGE	Gambar lebih dari 800 KB
UNSUPPORTED_IMAGE_FORMAT	Gambar bukan PNG, JPEG, atau WebP
PERMISSION_DENIED (403)	Access key Anda tidak diaktifkan untuk flow ini

Proses yang ditolak disimpan sebagai gagal. Perbaiki permintaan dan buat proses baru dengan correlationId baru.

Baca Error dan percobaan ulang sebelum menambahkan logika percobaan ulang: percobaan baru memerlukan correlationId baru.

Berikutnya

Mengambil proses