---
title: KYC Magic Link
description: Menjalankan proses identifikasi di Meksiko, mengumpulkan dokumen identitas nasional (INE) dan biometrik wajah melalui perjalanan yang dihosting yang didistribusikan lewat tautan unik.
canonical: https://developer.unico.io/id/dual-api/products/sign-up/kyc-magic-link/index
locale: id
generated_by: markdown-export
---

- [/id/](/id/)
- [Bangun](/id/dual-api/products/)
- Panduan Regional
- KYC Magic Link

**Di halaman ini# KYC Magic Link

Kontrak regional terpisahKasus penggunaan ini **tidak menggunakan** endpoint Unico `POST /v1/process` maupun kontrak API. Integrasinya adalah dengan **Trully.ai** (host `api.trully.ai`), dengan **autentikasi via `x-api-key`** alih-alih Bearer JWT, dan **skema respons proprietary**. Untuk negara lain, gunakan Onboarding (Global).
### Apa yang diselesaikan oleh kasus penggunaan ini​

KYC Magic Link mengatasi tantangan menjalankan proses identifikasi di Meksiko, mengumpulkan dokumen identitas nasional (INE) dan biometrik wajah. Dengan perjalanan yang dihosting oleh Unico, Anda menghilangkan hambatan pengembangan front-end melalui tautan yang dikirim melalui saluran Anda sendiri (WhatsApp, SMS, email).
**Gunakan kasus penggunaan ini ketika:**

Anda beroperasi di **Meksiko** dan dokumen identitas yang digunakan adalah **INE (wajib)**.

**Jangan gunakan kasus penggunaan ini ketika:**

Pengguna berada di luar Meksiko atau menggunakan dokumen lain → lihat kasus penggunaan onboarding lainnya.

### Kemampuan yang terlibat​

Pipeline yang dijalankan dalam satu proses:
[Pengambilan Dokumen (INE)](/id/capabilities/document-reuse-and-capture)[Liveness](/id/capabilities/liveness)[Klasifikasi Risiko Penipuan](/id/capabilities/fraud-risk-classification)[Identity Verification](/id/capabilities/identity-verification)
KemampuanDiperlukanPeran dalam alur**Document Capture**DiperlukanMengambil gambar dokumen INE. Penggunaan ulang dokumen **tidak tersedia** dalam kasus penggunaan ini — setiap sesi memerlukan pengambilan baru.**Liveness**DiperlukanPemeriksaan liveness — selfie wajib yang menjangkar proses.**Klasifikasi Risiko Penipuan**DiperlukanMelakukan referensi silang sinyal perilaku untuk menandai risiko penipuan yang terkait dengan CPF.**Identity Verification**Opsional (jika dikontrakkan)Memvalidasi apakah wajah dalam transaksi milik pemegang pengenal pemerintah yang diberikan, menggunakan basis identitas Unico dan sinyal tambahan.**[RENAPO Verification](/id/capabilities/renapo-verification)**Opsional (jika dikontrakkan)Melakukan kueri ke RENAPO, registri kependudukan nasional Meksiko, dengan CURP pengguna dan mengembalikan data registri bersama hasil Verifikasi Identitas.
### Prasyarat​

**Kunci API** — disediakan oleh Manajer Proyek Onboarding Anda di Unico. Dikirim di header `x-api-key`.
**Endpoint HTTPS publik** untuk menerima webhook (opsional, tetapi direkomendasikan).
**Konfigurasi CORS** — izinkan origin `https://verification.unico.app` (produksi) dan `https://verification.uat.unico.app` (sandbox) di server yang menerima webhook.

### Implementasi langkah demi langkah​

Berbeda dengan kasus penggunaan lainnya, Magic Link **tidak memiliki field `flow`** — integrasinya langsung dengan API Trully. Endpoint membuat tautan verifikasi unik yang Anda distribusikan ke pengguna melalui saluran Anda sendiri.
### 1. Buat Magic Link​

**Endpoint:** `POST https://sandbox.trully.ai/v2/magic-link`
**Header:**
HeaderDiperlukanDeskripsi`x-api-key`YaKunci API yang disediakan oleh Manajer Proyek Onboarding Anda di Unico.`Content-Type`Ya`application/json`
**Body (application/json):**
FieldTipeDiperlukanDeskripsi`external_id`stringTidakPengenal eksternal untuk permintaan, digunakan untuk tujuan pelacakan dan referensi.`metadata`objectTidakWadah untuk parameter konfigurasi.`metadata.phone`stringTidakNomor telepon pengguna dalam format internasional (mis., `521234567890`).`metadata.redirect_url`stringTidakURL untuk mengarahkan pengguna setelah proses KYC selesai.`metadata.webhook_url`stringTidakURL untuk mengirim data proses KYC setelah proses KYC selesai. Webhook ini akan dipanggil di sisi klien. Untuk alasan keamanan, endpoint harus menggunakan HTTPS. Komponen akan menunggu satu menit agar server webhook Anda merespons — setelah itu, komunikasi akan dihentikan. Proses tidak akan terpengaruh dengan cara apa pun oleh komunikasi webhook. Pastikan untuk mengizinkan `https://verification.unico.app` dan `https://verification.uat.unico.app` dalam konfigurasi CORS Anda masing-masing untuk produksi dan sandbox.`metadata.track_webhook_url`stringTidakURL untuk mengirim setiap langkah KYC yang diproses oleh pengguna (lihat acara webhook di bawah). Webhook ini akan dipanggil di sisi klien. Untuk alasan keamanan, endpoint harus menggunakan HTTPS. Komponen akan menunggu satu menit agar server webhook Anda merespons — setelah itu, komunikasi akan dihentikan. Proses tidak akan terpengaruh dengan cara apa pun oleh komunikasi webhook. Pastikan untuk mengizinkan `https://verification.unico.app` dan `https://verification.uat.unico.app` dalam konfigurasi CORS Anda masing-masing untuk produksi dan sandbox.
`data.step` (dikirim ke `track_webhook_url`) melaporkan langkah-langkah yang sama yang dilacak oleh Webhook V2 — lihat [tabel Langkah yang didukung](#webhook-v2) di bawah.
**Contoh permintaan:**
```
curl -X POST https://sandbox.trully.ai/v2/magic-link \  -H "x-api-key: $TRULLY_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "external_id": "user-mx-12345",    "metadata": {      "phone": "521234567890",      "redirect_url": "https://app.client.com.mx/kyc-done",      "webhook_url": "https://app.client.com.mx/webhook/result",      "track_webhook_url": "https://app.client.com.mx/webhook/track"    }  }'
```

### 2. Terima token dan URL tautan​

**Field respons:**
FieldTipeDeskripsi`data.external_id`string (nullable)Pengenal eksternal untuk permintaan, digunakan untuk tujuan pelacakan dan referensi.`data.created_on`string (date-time)Tanggal ketika magic link dibuat.`data.is_active`booleanJika `true`, magic link aktif.`data.token`stringToken magic link yang akan digunakan untuk menghubungkan proses KYC ke magic link.`data.magic_link_url`string (URI)URL magic link untuk memulai proses KYC.`data.metadata.redirect_url`string (nullable)URL untuk mengarahkan pengguna setelah proses KYC selesai.`data.metadata.webhook_url`string (nullable)URL untuk mengirim data proses KYC setelah proses KYC selesai. Webhook ini akan dipanggil di sisi klien.`data.metadata.track_webhook_url`string (nullable)URL untuk mengirim setiap langkah KYC yang diproses oleh pengguna. Webhook ini akan dipanggil di sisi klien.`data.version`stringVersi magic link.`version`stringVersi API yang memproses permintaan, berguna untuk melacak perubahan dan kompatibilitas.`status`stringRepresentasi tekstual status respons, menunjukkan keberhasilan atau kegagalan operasi.`status_code`integerKode status HTTP dari respons, memberikan indikator standar hasil permintaan.`request_date`string (date-time)Tanggal dan waktu ketika permintaan dibuat, dalam format ISO 8601.`request.metadata.redirect_url`string (nullable)URL untuk mengarahkan pengguna setelah proses KYC selesai (gema permintaan).`request.metadata.webhook_url`string (nullable)URL untuk mengirim data proses KYC setelah selesai (gema permintaan).`request.metadata.track_webhook_url`string (nullable)URL untuk mengirim setiap langkah KYC yang diproses oleh pengguna (gema permintaan).
**Contoh respons:**
```
{  "data": {    "external_id": null,    "created_on": "2025-07-28T18:11:54.430048399Z",    "is_active": true,    "token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",    "magic_link_url": "https://verification.uat.unico.app/link/v2/3f6dbcc1-49ba-4935-be90-dd8dd59b5530",    "metadata": {      "redirect_url": null,      "webhook_url": null,      "track_webhook_url": null    },    "version": "v2"  },  "version": "v1.4.2",  "status": "ok",  "status_code": 200,  "request_date": "2025-07-28T18:11:54+0000",  "request": {    "metadata": {      "redirect_url": null,      "webhook_url": null,      "track_webhook_url": null    }  }}
```

**Respons kesalahan — POST /v2/magic-link**KodePesanDeskripsi`400 Bad Request``data provided in the field is invalid`Struktur data atau nilai field tidak valid dalam payload permintaan. Periksa field yang diperlukan dan formatnya.`403 Forbidden``Forbidden`Kunci API hilang, kedaluwarsa, atau tidak memiliki izin. Verifikasi header `x-api-key`.`500 Internal Server Error``internal server error`Kegagalan pemrosesan di sisi server. Coba lagi dengan exponential backoff. Jika terus terjadi, laporkan ke dukungan.**Contoh respons 400:**```
{  "data": {    "error": "data provided in the field is invalid"  },  "version": "v1.4.2",  "status": "bad request",  "status_code": 400,  "request_date": "2025-07-28T20:22:29+0000",  "request": {    "metadata": null  }}
```

### 3. Distribusikan magic_link_url ke pengguna​

Kirim melalui WhatsApp, SMS, email, atau tanamkan. Pengguna mengakses tautan di perangkat mereka sendiri dan menyelesaikan perjalanan yang dihosting.
Jika Anda lebih memilih untuk menanamkan perjalanan ini di dalam aplikasi Anda sendiri alih-alih membuka tautan di browser, Anda dapat melakukannya melalui WebView atau CustomTab. PoC referensi:

**Android/Kotlin:** [TrullyAi-AndroidMagicLink](https://github.com/unico-labs/TrullyAi-AndroidMagicLink)
**React Native:** [TrullyAI-ReactNativeMagicLink](https://github.com/unico-labs/TrullyAI-ReactNativeMagicLink)

### 4. Terima hasilnya​

Anda memiliki fleksibilitas penuh untuk memutuskan cara menerima hasil akhir dari proses KYC — pilih strategi yang paling sesuai dengan arsitektur sistem Anda. Anda dapat secara aktif melakukan polling untuk hasil (GET) atau menerimanya secara pasif melalui notifikasi (Webhook).
**Opsi A — Polling aktif via GET**
Ambil hasilnya dengan memanggil `GET /v2/history/request?magic_link_token={token}` (lihat [Polling via GET](#polling-via-get) di bawah). Keputusan akhir terisi dalam `data.response.unico.result`.
Praktik terbaik untuk GETAlih-alih melakukan polling secara berkala sejak tautan dibuat, gunakan webhook pelacakan (lihat [Webhook V2](#webhook-v2) di bawah) untuk mengetahui persis kapan harus melakukan query. Setelah Anda menerima langkah `form_decision_maker`, itu adalah momen yang tepat dan aman untuk memicu panggilan GET ini.
**Opsi B — Penerimaan otomatis via Webhook**
Buat sistem Anda diberi tahu secara otomatis segera setelah hasil akhir siap (lihat [Webhook V2](#webhook-v2) di bawah). Dua versi tersedia:

**Webhook V1** — Anda menerima hasil di URL yang dikirim dalam `metadata.webhook_url` saat membuat token.
**Webhook V2** — dikonfigurasi terlebih dahulu dengan PM Onboarding Anda. Anda menerima vonis akhir dengan mendengarkan acara `MAGIC_LINK_RESULTS`.

Ketahanan — fallbackJika Webhook (Opsi B) adalah metode utama Anda, terapkan juga query GET (Opsi A) sebagai fallback. Ini memungkinkan Anda memulihkan hasil melalui rutinitas rekonsiliasi jika terjadi kegagalan jaringan, gangguan server sementara, atau webhook yang gagal diproses dengan benar.

### Polling via GET​

**Endpoint:** `GET https://sandbox.trully.ai/v2/history/request`
**Parameter kueri:**
ParameterTipeDiperlukanDeskripsi`magic_link_token`stringYaToken yang dikembalikan saat Magic Link dibuat.
**Header:**
HeaderDiperlukanDeskripsi`x-api-key`YaKunci API yang disediakan oleh Manajer Proyek Onboarding Anda di Unico.
**Contoh permintaan:**
```
curl "https://sandbox.trully.ai/v2/history/request?magic_link_token=$TOKEN" \  -H "x-api-key: $TRULLY_API_KEY"
```

**Contoh respons:**
```
{  "data": {    "images": {      "document_image": "/9j/4ASu7bmV[...]fyPjOKfgif//Z",      "document_image_back": "/9j/4ASu7bmV[...]fyPjOKfgif//Z",      "selfie": "/9j/4ASu7bmV[...]fyPjOKfgif//Z"    },    "response": {      "curp": {        "age": 58,        "curp": "GOCJ850627HDFRRL09",        "date_of_birth": "14/11/1956",        "deceased": false,        "gender": "M",        "government_name": "LUKE SKYWALKER",        "government_valid": true,        "is_mexican": true,        "name_to_CURP_valid": true,        "state_iso": "MX-NLE",        "state_of_birth": "Nuevo León"      },      "document": {        "back": {          "cic": "237457894",          "citizen_id": "237457894",          "mrz": "IDMEX999999999999<9 VADER<SKYWALKER<<LUKE"        },        "details": {          "detected": true,          "document_id": 229928,          "forensics": { "is_valid": "no" }        },        "front": {          "face_analysis": {            "face_id": 237437,            "face_id_v2": 199068,            "first_seen": "12/22/2022, 18:54:09",            "inquiry_date": "07/28/2025, 20:53:12",            "last_seen": "07/28/2025, 18:47:46",            "last_seen_by_your_company": "07/24/2025, 21:38:21",            "match": true,            "match_fraud_flag": true,            "seen_by_your_company": true,            "seen_different_companies": 46,            "times_seen_by_your_company": 3,            "times_seen_last_month": 111,            "unique_face_id_v2": 126880,            "warnings": {              "external_id": "User found in the company with other external_ids: ['abc-123']"            }          },          "information": {            "address": { "text": "DOMICILIO/ADDRESS, HARLINGEN, TX 78552", "valid": false },            "birthdate": { "text": "14/11/1956", "valid": true },            "complete_name": { "text": "LUKE SKYWALKER", "valid": true },            "curp": { "text": "GOCJ850627HDFRRL09", "valid": true },            "electoral_key": { "text": "GRCRSN82031007M500", "valid": true },            "last_name": { "text": "SKYWALKER", "valid": true },            "mother_last_name": { "text": "ORGANA", "valid": true },            "name": { "text": "LUKE", "valid": true },            "registration_year": { "text": "1998", "valid": true },            "sex": { "text": "H", "valid": true },            "valid_thru": { "text": "2027", "valid": true }          }        }      },      "face_match": false,      "label": null,      "reason": null,      "request_id": "d1kxp9ah8f0s71uv9zx0",      "selfie": {        "face_id": 237436,        "face_id_v2": 4378,        "first_seen": "02/05/2025, 02:36:19",        "first_seen_image": true,        "inquiry_date": "07/28/2025, 20:52:49",        "last_seen": "07/28/2025, 20:52:51",        "last_seen_by_your_company": "07/23/2025, 18:14:27",        "match": true,        "match_fraud_flag": true,        "seen_by_your_company": true,        "seen_different_companies": 2,        "times_seen_by_your_company": 2,        "times_seen_last_month": 7,        "unique_face_id_v2": 494,        "warnings": {}      },      "unico": {        "process_id": "d333dfac-9ddb-4066-8e2c-44eaf4c86b4a",        "result": "PROCESS_RESULT_LIVE"      }    },    "user_id": ""  },  "request_date": "2025-07-28T20:53:38",  "status": "Request fulfilled, document follows",  "status_code": 200,  "version": "v3.6.0"}
```

**Field respons:**
**Tingkat root:**
FieldTipeDeskripsi`status`stringRepresentasi tekstual status respons.`status_code`integerKode status HTTP.`request_date`string (date-time)Tanggal dan waktu ketika permintaan dibuat.`version`stringVersi API yang memproses permintaan.`data.user_id`stringID pengguna yang ditetapkan dalam permintaan asli.
**`data.images`** — Gambar yang diambil dalam format Base64:
FieldTipeDeskripsi`data.images.document_image`stringGambar dalam format Base64 dari bagian depan dokumen.`data.images.document_image_back`stringGambar dalam format Base64 dari bagian belakang dokumen.`data.images.selfie`stringGambar selfie dalam format Base64 yang diambil selama verifikasi.
**`data.response.unico`** — Vonis yang dikonsolidasikan:
FieldTipeDeskripsi`data.response.unico.process_id`string (UUID)Pengenal internal yang terkait dengan proses verifikasi.`data.response.unico.result`stringHasil proses. Nilai yang mungkin dijelaskan di bawah.
**Nilai yang mungkin untuk `data.response.unico.result`:**
Nilai hasil mengodekan salah satu dari tiga dimensi evaluasi:

**Penilaian identitas** — apakah wajah yang diambil milik pemegang dokumen (`PROCESS_RESULT_VERIFIED`, `PROCESS_RESULT_NOT_APPROVED`).
**Perilaku penipuan** — apakah sinyal perilaku atau jaringan mengindikasikan risiko penipuan (`PROCESS_RESULT_LIVE`, `PROCESS_RESULT_HIGH_RISK`, `PROCESS_RESULT_CRITICAL_RISK`, `PROCESS_RESULT_NOT_APPROVED`).
**Liveness** — apakah wajah hidup terdeteksi pada saat pengambilan (`PROCESS_RESULT_NOT_LIVE`).

HasilRekomendasiArtiSinyal`PROCESS_RESULT_ERROR`**Tolak**Proses selesai dengan kesalahan.Sistem`PROCESS_RESULT_VERIFIED`**Terima**Pengguna aktif pada saat pengambilan; ini adalah wajah pemegang ID dan tidak ditemukan bukti terkait penipuan.Identitas: dikonfirmasi`PROCESS_RESULT_LIVE`**Tinjau / Terima**Pengguna aktif pada saat pengambilan; kami tidak menemukan bukti yang cukup untuk memastikan bahwa mereka adalah pemegang ID dan tidak ada bukti penipuan.Identitas: tidak konklusif · Penipuan: tidak ada`PROCESS_RESULT_HIGH_RISK`**Rekomendasikan penolakan**Kami menemukan setidaknya satu bukti kuat penipuan. Keputusan akhir ada pada Anda.Perilaku penipuan: 1 sinyal kuat`PROCESS_RESULT_CRITICAL_RISK`**Rekomendasikan penolakan**Kami menemukan setidaknya 2 bukti kuat penipuan. Keputusan akhir ada pada Anda.Perilaku penipuan: 2+ sinyal kuat`PROCESS_RESULT_NOT_APPROVED`**Tolak**Penolakan direkomendasikan karena beberapa indikasi penipuan terdeteksi.Identitas: ditolak · Perilaku penipuan: beberapa sinyal`PROCESS_RESULT_NOT_LIVE`**Izinkan hingga 2 percobaan ulang**Pengguna tidak aktif pada saat pengambilan, meskipun kami tidak menemukan indikasi penipuan lainnya.Liveness: wajah tidak hidup
catatan`PROCESS_RESULT_VERIFIED` **memerlukan aktivasi**. Secara default, hasil ini **tidak aktif** — selaraskan dengan Manajer Proyek Unico Anda jika Anda ingin mengaktifkannya.
**Sinyal tambahan untuk keputusan Anda:**
Untuk kasus `LIVE`, `HIGH_RISK`, atau `CRITICAL_RISK`, lengkapi keputusan Anda dengan field-field berikut:
FieldTipeArti`face_match`booleanStatus pencocokan wajah antara dokumen dan selfie.`document.front.face_analysis.match_fraud_flag`booleanApakah wajah dokumen telah dikaitkan dengan aktivitas penipuan.`selfie.match_fraud_flag`booleanApakah wajah selfie telah dikaitkan dengan aktivitas penipuan.`warnings.external_id`stringPeringatan yang menunjukkan wajah pengguna dikaitkan dengan beberapa ID eksternal.
**`data.response`** — Sinyal hasil tingkat atas:
FieldTipeDeskripsi`data.response.face_match`booleanApakah wajah selfie cocok dengan wajah dokumen.`data.response.label`string (nullable)Dicadangkan untuk hasil dari sub-proses tertentu; `null` jika tidak berlaku.`data.response.reason`string (nullable)Alasan untuk label yang ditetapkan.`data.response.request_id`stringPengenal unik untuk permintaan API.
**`data.response.curp`** — Validasi CURP terhadap RENAPO:
FieldTipeDeskripsi`curp`stringString CURP yang dianalisis.`government_valid`booleanApakah CURP valid menurut RENAPO.`government_name`stringNama lengkap yang terkait dengan CURP dalam basis data resmi.`name_to_CURP_valid`booleanApakah nama yang diberikan konsisten dengan CURP.`is_mexican`booleanApakah CURP sesuai dengan warga negara Meksiko.`deceased`booleanApakah CURP ditandai sebagai meninggal dalam basis data resmi.`date_of_birth`stringTanggal lahir yang didekode dari CURP (DD/MM/YYYY).`age`integerUsia yang dihitung untuk pengguna.`gender`stringJenis kelamin yang didekode dari CURP (`M` atau `F`).`state_of_birth`stringNegara bagian kelahiran yang didekode dari CURP.`state_iso`stringKode ISO 3166-2 untuk negara bagian kelahiran.
**`data.response.document.details`** — Deteksi dokumen dan forensik:
FieldTipeDeskripsi`detected`booleanApakah dokumen berhasil terdeteksi dalam gambar.`document_id`integerPengenal unik untuk dokumen yang diproses.`forensics.is_valid`stringHasil analisis forensik: `yes`, `no`, atau `inconclusive`.
**`data.response.document.front.information`** — Field yang diekstrak OCR dari bagian depan INE. Setiap field berisi `text` (nilai yang diekstrak) dan `valid` (apakah dapat divalidasi secara struktural):
FieldDeskripsi`name`Nama depan.`last_name`Nama belakang ayah.`mother_last_name`Nama belakang ibu.`complete_name`Nama lengkap.`birthdate`Tanggal lahir (DD/MM/YYYY).`sex`Jenis kelamin (`H` atau `M`).`curp`CURP yang diekstrak dari dokumen.`electoral_key`Kunci pemilihan.`address`Alamat.`registration_year`Tahun dokumen didaftarkan.`valid_thru`Tahun kedaluwarsa dokumen.
**`data.response.document.front.face_analysis`** — Analisis wajah yang ditemukan di INE:
FieldTipeDeskripsi`face_id`integerPengenal unik untuk instans wajah ini.`face_id_v2`integerPengenal unik (versi 2).`unique_face_id_v2`integerPengenal persisten untuk wajah fisik ini di semua permintaan.`first_seen`stringStempel waktu pertama kali wajah ini pernah terlihat dalam sistem.`last_seen`stringStempel waktu terbaru wajah ini terlihat di jaringan.`last_seen_by_your_company`stringTerakhir kali wajah ini terlihat dalam permintaan oleh perusahaan Anda.`inquiry_date`stringStempel waktu permintaan verifikasi saat ini.`match`booleanApakah wajah ini merupakan kecocokan potensial dengan wajah lain dalam basis data.`match_fraud_flag`booleanApakah wajah ini telah dikaitkan dengan aktivitas penipuan.`seen_by_your_company`booleanApakah wajah ini sebelumnya terlihat oleh perusahaan Anda.`seen_different_companies`integerJumlah perusahaan lain dalam jaringan yang telah melihat wajah ini.`times_seen_by_your_company`integerTotal kali wajah ini terlihat dalam permintaan oleh perusahaan Anda.`times_seen_last_month`integerJumlah kali terlihat dalam sebulan terakhir di seluruh jaringan.`warnings.external_id`stringPeringatan jika wajah pengguna dikaitkan dengan beberapa ID eksternal.
**`data.response.document.back`** — Data MRZ dari bagian belakang INE:
FieldTipeDeskripsi`mrz`stringString Machine-Readable Zone lengkap.`cic`stringNomor CIC yang diekstrak dari MRZ.`citizen_id`stringNomor identifikasi warga negara dari MRZ.
**`data.response.selfie`** — Analisis selfie yang diambil:
FieldTipeDeskripsi`face_id`integerPengenal unik untuk instans wajah selfie.`face_id_v2`integerPengenal unik (versi 2).`unique_face_id_v2`integerPengenal persisten untuk wajah fisik ini di semua permintaan.`first_seen`stringPertama kali wajah selfie ini pernah terlihat dalam sistem.`first_seen_image`booleanApakah ini pertama kalinya gambar yang sama persis terlihat.`last_seen`stringPaling baru kali wajah ini terlihat di jaringan.`last_seen_by_your_company`stringPaling baru kali wajah ini terlihat oleh perusahaan Anda.`inquiry_date`stringStempel waktu permintaan verifikasi saat ini.`match`booleanApakah wajah selfie cocok dengan wajah lain dalam basis data.`match_fraud_flag`booleanApakah wajah selfie dikaitkan dengan aktivitas penipuan.`seen_by_your_company`booleanApakah wajah ini sebelumnya terlihat oleh perusahaan Anda.`seen_different_companies`integerJumlah perusahaan lain dalam jaringan yang telah melihat wajah ini.`times_seen_by_your_company`integerTotal kali wajah ini terlihat dalam permintaan oleh perusahaan Anda.`times_seen_last_month`integerJumlah kali terlihat dalam sebulan terakhir di seluruh jaringan.`warnings`objectPeringatan khusus terkait analisis selfie (struktur sama dengan face_analysis dokumen).
Gunakan polling dengan **exponential backoff** — jangan panggil dalam loop yang ketat.
**Respons kesalahan — GET /v2/history/request**KodePesanDeskripsi`400 Bad Request``Input should be a valid UUID, invalid group length...`Parameter `magic_link_token` tidak valid atau bukan format UUID yang valid.`404 Not Found``This magic link have no requests associated`Token yang diberikan ada tetapi tidak ada proses KYC yang selesai yang terhubung dengannya. Pengguna mungkin belum menyelesaikan perjalanan.`500 Internal Server Error``internal server error`Kegagalan pemrosesan di sisi server. Coba lagi dengan exponential backoff. Jika terus terjadi, laporkan ke dukungan.**Contoh respons 400:**```
{  "data": {    "error": [      {        "attribute": ["magic_link_token"],        "message": "Input should be a valid UUID, invalid group length in group 4: expected 12, found 11",        "type": "uuid_parsing"      }    ]  },  "request_date": "2025-07-28T20:43:34",  "status": "There are some errors in the request",  "status_code": 400,  "version": "v3.6.0"}
```

**Contoh respons 404:**```
{  "data": {    "error": "This magic link have no requests associated"  },  "request_date": "2025-07-28T20:40:50",  "status": "Nothing matches the given URI",  "status_code": 404,  "version": "v3.6.0"}
```

**Contoh respons 500:**```
{  "data": {    "error": "internal server error"  },  "version": "v1.4.2",  "status": "bad request",  "status_code": 400,  "request_date": "2025-07-28T20:22:29+0000",  "request": {    "metadata": null  }}
```

### Webhook V2​

Tiga acara webhook tersedia. Untuk mengaktifkan, minta pengaturan dari Manajer Proyek Onboarding Anda dengan menyediakan: **URL** endpoint (HTTPS diperlukan), **tipe autentikasi** (`basic_auth`, `api_key`, `oauth2`, atau `NoAuth`), **konfigurasi autentikasi**, **jumlah percobaan ulang maksimum**, **interval percobaan ulang (detik)**, dan **batas waktu (detik)**.
MAGIC_LINK_RESULTS
Acara ini dikirim di akhir alur, ketika Decision Maker telah selesai memproses informasi yang dikirimkan.
```
{  "data": {    "images": {      "document_image": "base64str",      "document_image_back": "base64str",      "selfie": "base64str"    },    "response": {      "document": {        "details": {          "detected": true,          "forensics": {            "is_valid": "yes"          },          "document_id": 123        },        "front": {          "information": {            "birthdate": { "text": "14/11/1956", "valid": true },            "sex": { "text": "H", "valid": true },            "registration_year": { "text": "1998", "valid": true },            "name": { "text": "LUKE", "valid": true },            "mother_last_name": { "text": "ORGANA", "valid": true },            "last_name": { "text": "SKYWALKER", "valid": true },            "electoral_key": { "text": "GRCRSN82031007M500", "valid": true },            "curp": { "text": "GOCJ850627HDFRRL09", "valid": true },            "address": { "text": "DOMICILIO/ADDRESS, HARLINGEN, TX 78552", "valid": false },            "complete_name": { "text": "LUKE SKYWALKER", "valid": true },            "valid_thru": { "text": "2027", "valid": true }          },          "face_analysis": {            "face_id": 237437,            "first_seen": "12/22/2022, 18:54:09",            "unique_face_id_v2": 126880,            "face_id_v2": 199068,            "inquiry_date": "07/28/2025, 20:53:12",            "last_seen": "07/28/2025, 18:47:46",            "last_seen_by_your_company": "07/24/2025, 21:38:21",            "match": true,            "match_fraud_flag": true,            "seen_by_your_company": true,            "seen_different_companies": 46,            "times_seen_by_your_company": 3,            "times_seen_last_month": 111,            "warnings": {              "external_id": "User found in the company with other external_ids: ['abc-123']"            }          }        },        "back": {          "mrz": "IDMEX999999999999<9 VADER<SKYWALKER<<LUKE",          "cic": "237457894"        }      },      "selfie": {        "face_id": 237436,        "first_seen": "02/05/2025, 02:36:19",        "unique_face_id_v2": 494,        "face_id_v2": 4378,        "inquiry_date": "07/28/2025, 20:52:49",        "last_seen": "07/28/2025, 20:52:51",        "last_seen_by_your_company": "07/23/2025, 18:14:27",        "match": true,        "match_fraud_flag": true,        "seen_by_your_company": true,        "seen_different_companies": 2,        "times_seen_by_your_company": 2,        "times_seen_last_month": 7,        "warnings": {          "external_id": "User found in the company with other external_ids: ['abc-123']"        },        "first_seen_image": true      },      "face_match": false,      "curp": {        "curp": "GOCJ850627HDFRRL09",        "state_of_birth": "Nuevo León",        "state_iso": "MX-NLE",        "date_of_birth": "14/11/1956",        "age": 58,        "gender": "M",        "is_mexican": true,        "name_to_CURP_valid": true,        "government_valid": true,        "government_name": "LUKE SKYWALKER",        "deceased": false      },      "unico": {        "process_id": "d333dfac-9ddb-4066-8e2c-44eaf4c86b4a",        "result": "PROCESS_RESULT_LIVE"      },      "label": null,      "reason": null,      "request_id": "d1kxp9ah8f0s71uv9zx0"    },    "user_id": null  },  "event": "MAGIC_LINK_RESULTS",  "magic_link_token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",  "user_id": null,  "date": "2025-10-03T21:15:41.299815"}
```

MAGIC_LINK_TRACK
Acara-acara ini diterima ketika pengguna menyelesaikan suatu tindakan. Misalnya, `form_start` akan diterima ketika pengguna sedang mengambil dokumen bagian depan, yang berarti pengguna telah mengklik dan menyelesaikan layar pertama.
```
{  "data": {    "completed_on": "Fri, 03 Oct 2025 21:15:35 GMT",    "started_on": "Fri, 03 Oct 2025 21:15:30 GMT",    "step": "form_start",    "user_id": null  },  "event": "MAGIC_LINK_TRACK",  "magic_link_token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",  "user_id": null,  "date": "2025-10-03T21:15:41.299815"}
```

FieldTipeDeskripsi`data.step`stringNama langkah yang diselesaikan.`data.user_id`string (nullable)ID eksternal yang ditetapkan dalam magic link.`data.started_on`datetimeWaktu mulai langkah dalam zona waktu UTC.`data.completed_on`datetimeWaktu selesai langkah dalam zona waktu UTC.`event`stringPengenal tipe acara.`magic_link_token`uuidToken magic link unik.`user_id`string (nullable)Pengenal eksternal.`date`datetimeStempel waktu acara.
**Langkah yang didukung:**
LangkahDeskripsi`form_start`Pengguna mengklik tombol magic link awal.`form_document_front`Pengguna menyelesaikan pengambilan bagian depan INE.`form_document_back`Pengguna menyelesaikan pengambilan bagian belakang INE.`form_document`Pengguna menyelesaikan kedua proses depan dan belakang.`form_selfie`Pengguna menyelesaikan proses liveness.`form_decision_maker`Pengguna menyelesaikan seluruh alur.
MAGIC_LINK_DOCUMENT_RETAKE_REASONS
Acara ini dikirim ketika pengambilan ulang dokumen diperlukan, baik selama proses depan maupun belakang. Ini menunjukkan bahwa data penting dari INE tidak dapat dibaca.
```
{  "data": {    "document_type": "ine_front",    "invalid_back_ocr": false,    "invalid_curp": false,    "invalid_document": true  },  "event": "MAGIC_LINK_DOCUMENT_RETAKE_REASONS",  "magic_link_token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",  "user_id": null,  "date": "2025-10-03T21:12:00.000Z"}
```

FieldTipeDeskripsi`data.document_type`stringSisi dokumen: `ine_front` atau `ine_back`.`data.invalid_document`boolean`true` jika gambar yang diambil bukan INE yang valid (salah satu sisi).`data.invalid_curp`boolean`true` jika CURP tidak dapat dibaca (hanya `ine_front`).`data.invalid_back_ocr`boolean`true` jika kode MRZ tidak dapat dibaca (hanya `ine_back`).`event`stringPengenal tipe acara.`magic_link_token`uuidToken magic link unik.`user_id`string (nullable)Pengenal eksternal.`date`datetimeStempel waktu acara.
Payload dirancang sehingga hanya **satu** kesalahan (`true`) yang diterima untuk setiap sisi dokumen.
**Skenario kegagalan — bagian depan INE:**

Dokumen tidak valid → hanya `invalid_document: true`
Kegagalan pembacaan CURP → hanya `invalid_curp: true`

**Skenario kegagalan — bagian belakang INE:**

Dokumen tidak valid → hanya `invalid_document: true`
Kegagalan pembacaan MRZ → hanya `invalid_back_ocr: true`

Kompatibilitas V1 / V2Jika Anda masih mengirim `webhook_url` dalam `metadata` permintaan (Webhook V1), konfigurasi tersebut **mengambil prioritas** atas V2 global. Untuk bermigrasi, hapus `webhook_url` dari `metadata` dan konfigurasikan V2 dengan PM Onboarding Anda.

### Kustomisasi​

Halaman Magic Link yang dihosting **tidak mendukung kustomisasi visual** oleh klien — halaman ini mengikuti identitas visual Unico/Trully default. Untuk menyesuaikan perjalanan (logo, warna, teks), gunakan Onboarding (Global) dengan SDK atau Web.
**Ketersediaan:** Meksiko · **Endpoint:** `POST https://api.trully.ai/v2/magic-link` · **Dokumen:** INE · **Auth:** `x-api-key` (Trully)Terakhir diperbarui pada 8 Okt 2026**