KYC Magic Link

Kontrak regional terpisah

Kasus penggunaan ini tidak menggunakan endpoint Unico POST /v1/process maupun kontrak API/TCA. 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)

Liveness

Risk Fraud Classification

Identity Verification

Kemampuan	Diperlukan	Peran dalam alur
Document Capture	Diperlukan	Mengambil gambar dokumen INE. Penggunaan ulang dokumen tidak tersedia dalam kasus penggunaan ini — setiap sesi memerlukan pengambilan baru.
Liveness	Diperlukan	Pemeriksaan liveness — selfie wajib yang menjangkar proses.
Risk Fraud Classification	Diperlukan	Melakukan 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.

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:

Header	Diperlukan	Deskripsi
`x-api-key`	Ya	Kunci API yang disediakan oleh Manajer Proyek Onboarding Anda di Unico.
`Content-Type`	Ya	`application/json`

Body (application/json):

Field	Tipe	Diperlukan	Deskripsi
`external_id`	string	Tidak	Pengenal eksternal untuk permintaan, digunakan untuk tujuan pelacakan dan referensi.
`metadata`	object	Tidak	Wadah untuk parameter konfigurasi.
`metadata.phone`	string	Tidak	Nomor telepon pengguna dalam format internasional (mis., `521234567890`).
`metadata.redirect_url`	string	Tidak	URL untuk mengarahkan pengguna setelah proses KYC selesai.
`metadata.webhook_url`	string	Tidak	URL 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`	string	Tidak	URL 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.

Nilai yang mungkin untuk data.step (dikirim ke track_webhook_url):

Langkah	Deskripsi
`form_start`	Pengguna sedang memindai dokumen.
`form_document_front`	Pengguna telah mengambil bagian depan INE.
`form_document_back`	Pengguna telah mengambil bagian belakang INE.
`form_document`	Proses saat ini berada di langkah selfie.
`form_selfie`	Pengguna mencapai langkah terakhir operasi.
`form_decision_maker`	Operasi mengembalikan respons sistem.

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:

Field	Tipe	Deskripsi
`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`	boolean	Jika `true`, magic link aktif.
`data.token`	string	Token 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`	string	Versi magic link.
`version`	string	Versi API yang memproses permintaan, berguna untuk melacak perubahan dan kompatibilitas.
`status`	string	Representasi tekstual status respons, menunjukkan keberhasilan atau kegagalan operasi.
`status_code`	integer	Kode 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

Kode	Pesan	Deskripsi
`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.

4. Terima hasilnya

Polling via GET (diperlukan) — panggil GET /v2/history/request?magic_link_token={token} secara berkala hingga unico.result terisi. Lihat Polling via GET di bawah.
Webhook (opsional) — konfigurasikan dengan PM Onboarding Anda untuk menerima acara secara otomatis. Lihat Webhook di bawah.

Polling via GET

Endpoint: GET https://sandbox.trully.ai/v2/history/request

Parameter kueri:

Parameter	Tipe	Diperlukan	Deskripsi
`magic_link_token`	string	Ya	Token yang dikembalikan saat Magic Link dibuat.

Header:

Header	Diperlukan	Deskripsi
`x-api-key`	Ya	Kunci 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:

Field	Tipe	Deskripsi
`status`	string	Representasi tekstual status respons.
`status_code`	integer	Kode status HTTP.
`request_date`	string (date-time)	Tanggal dan waktu ketika permintaan dibuat.
`version`	string	Versi API yang memproses permintaan.
`data.user_id`	string	ID pengguna yang ditetapkan dalam permintaan asli.

data.images — Gambar yang diambil dalam format Base64:

Field	Tipe	Deskripsi
`data.images.document_image`	string	Gambar dalam format Base64 dari bagian depan dokumen.
`data.images.document_image_back`	string	Gambar dalam format Base64 dari bagian belakang dokumen.
`data.images.selfie`	string	Gambar selfie dalam format Base64 yang diambil selama verifikasi.

data.response.unico — Vonis yang dikonsolidasikan:

Field	Tipe	Deskripsi
`data.response.unico.process_id`	string (UUID)	Pengenal internal yang terkait dengan proses verifikasi.
`data.response.unico.result`	string	Hasil 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).

Hasil	Rekomendasi	Arti	Sinyal
`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:

Field	Tipe	Arti
`face_match`	boolean	Status pencocokan wajah antara dokumen dan selfie.
`document.front.face_analysis.match_fraud_flag`	boolean	Apakah wajah dokumen telah dikaitkan dengan aktivitas penipuan.
`selfie.match_fraud_flag`	boolean	Apakah wajah selfie telah dikaitkan dengan aktivitas penipuan.
`warnings.external_id`	string	Peringatan yang menunjukkan wajah pengguna dikaitkan dengan beberapa ID eksternal.

data.response — Sinyal hasil tingkat atas:

Field	Tipe	Deskripsi
`data.response.face_match`	boolean	Apakah 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`	string	Pengenal unik untuk permintaan API.

data.response.curp — Validasi CURP terhadap RENAPO:

Field	Tipe	Deskripsi
`curp`	string	String CURP yang dianalisis.
`government_valid`	boolean	Apakah CURP valid menurut RENAPO.
`government_name`	string	Nama lengkap yang terkait dengan CURP dalam basis data resmi.
`name_to_CURP_valid`	boolean	Apakah nama yang diberikan konsisten dengan CURP.
`is_mexican`	boolean	Apakah CURP sesuai dengan warga negara Meksiko.
`deceased`	boolean	Apakah CURP ditandai sebagai meninggal dalam basis data resmi.
`date_of_birth`	string	Tanggal lahir yang didekode dari CURP (DD/MM/YYYY).
`age`	integer	Usia yang dihitung untuk pengguna.
`gender`	string	Jenis kelamin yang didekode dari CURP (`M` atau `F`).
`state_of_birth`	string	Negara bagian kelahiran yang didekode dari CURP.
`state_iso`	string	Kode ISO 3166-2 untuk negara bagian kelahiran.

data.response.document.details — Deteksi dokumen dan forensik:

Field	Tipe	Deskripsi
`detected`	boolean	Apakah dokumen berhasil terdeteksi dalam gambar.
`document_id`	integer	Pengenal unik untuk dokumen yang diproses.
`forensics.is_valid`	string	Hasil 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):

Field	Deskripsi
`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:

Field	Tipe	Deskripsi
`face_id`	integer	Pengenal unik untuk instans wajah ini.
`face_id_v2`	integer	Pengenal unik (versi 2).
`unique_face_id_v2`	integer	Pengenal persisten untuk wajah fisik ini di semua permintaan.
`first_seen`	string	Stempel waktu pertama kali wajah ini pernah terlihat dalam sistem.
`last_seen`	string	Stempel waktu terbaru wajah ini terlihat di jaringan.
`last_seen_by_your_company`	string	Terakhir kali wajah ini terlihat dalam permintaan oleh perusahaan Anda.
`inquiry_date`	string	Stempel waktu permintaan verifikasi saat ini.
`match`	boolean	Apakah wajah ini merupakan kecocokan potensial dengan wajah lain dalam basis data.
`match_fraud_flag`	boolean	Apakah wajah ini telah dikaitkan dengan aktivitas penipuan.
`seen_by_your_company`	boolean	Apakah wajah ini sebelumnya terlihat oleh perusahaan Anda.
`seen_different_companies`	integer	Jumlah perusahaan lain dalam jaringan yang telah melihat wajah ini.
`times_seen_by_your_company`	integer	Total kali wajah ini terlihat dalam permintaan oleh perusahaan Anda.
`times_seen_last_month`	integer	Jumlah kali terlihat dalam sebulan terakhir di seluruh jaringan.
`warnings.external_id`	string	Peringatan jika wajah pengguna dikaitkan dengan beberapa ID eksternal.

data.response.document.back — Data MRZ dari bagian belakang INE:

Field	Tipe	Deskripsi
`mrz`	string	String Machine-Readable Zone lengkap.
`cic`	string	Nomor CIC yang diekstrak dari MRZ.
`citizen_id`	string	Nomor identifikasi warga negara dari MRZ.

data.response.selfie — Analisis selfie yang diambil:

Field	Tipe	Deskripsi
`face_id`	integer	Pengenal unik untuk instans wajah selfie.
`face_id_v2`	integer	Pengenal unik (versi 2).
`unique_face_id_v2`	integer	Pengenal persisten untuk wajah fisik ini di semua permintaan.
`first_seen`	string	Pertama kali wajah selfie ini pernah terlihat dalam sistem.
`first_seen_image`	boolean	Apakah ini pertama kalinya gambar yang sama persis terlihat.
`last_seen`	string	Paling baru kali wajah ini terlihat di jaringan.
`last_seen_by_your_company`	string	Paling baru kali wajah ini terlihat oleh perusahaan Anda.
`inquiry_date`	string	Stempel waktu permintaan verifikasi saat ini.
`match`	boolean	Apakah wajah selfie cocok dengan wajah lain dalam basis data.
`match_fraud_flag`	boolean	Apakah wajah selfie dikaitkan dengan aktivitas penipuan.
`seen_by_your_company`	boolean	Apakah wajah ini sebelumnya terlihat oleh perusahaan Anda.
`seen_different_companies`	integer	Jumlah perusahaan lain dalam jaringan yang telah melihat wajah ini.
`times_seen_by_your_company`	integer	Total kali wajah ini terlihat dalam permintaan oleh perusahaan Anda.
`times_seen_last_month`	integer	Jumlah kali terlihat dalam sebulan terakhir di seluruh jaringan.
`warnings`	object	Peringatan 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

Kode	Pesan	Deskripsi
`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

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"
}

Field	Tipe	Deskripsi
`data.step`	string	Nama langkah yang diselesaikan.
`data.user_id`	string (nullable)	ID eksternal yang ditetapkan dalam magic link.
`data.started_on`	datetime	Waktu mulai langkah dalam zona waktu UTC.
`data.completed_on`	datetime	Waktu selesai langkah dalam zona waktu UTC.
`event`	string	Pengenal tipe acara.
`magic_link_token`	uuid	Token magic link unik.
`user_id`	string (nullable)	Pengenal eksternal.
`date`	datetime	Stempel waktu acara.

Langkah yang didukung:

Langkah	Deskripsi
`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"
}

Field	Tipe	Deskripsi
`data.document_type`	string	Sisi 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`	string	Pengenal tipe acara.
`magic_link_token`	uuid	Token magic link unik.
`user_id`	string (nullable)	Pengenal eksternal.
`date`	datetime	Stempel 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 / V2

Jika 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)

Apa yang diselesaikan oleh kasus penggunaan ini​

Kemampuan yang terlibat​

Prasyarat​

Implementasi langkah demi langkah​

Polling via GET​

Webhook​

Kustomisasi​