---
title: KYC Magic Link
description: メキシコでの本人確認プロセスを実行し、国民身分証明書（INE）と顔認証バイオメトリクスを、一意のリンクで配布されるホスト型フローを通じて収集します。
canonical: https://developer.unico.io/ja/dual-api/products/sign-up/kyc-magic-link/index
locale: ja
generated_by: markdown-export
---

- [/ja/](/ja/)
- [構築](/ja/dual-api/products/)
- 地域別ガイド
- KYC Magic Link

**このページの内容# KYC Magic Link

別途地域契約が必要このユースケースは `POST /v1/process` Unico エンドポイントや API 契約を**使用しません**。インテグレーション先は **Trully.ai**（ホスト: `api.trully.ai`）であり、Bearer JWT の代わりに **`x-api-key` による認証**と**独自のレスポンススキーマ**を使用します。他の国については、オンボーディング（グローバル）をご利用ください。
### このユースケースが解決する課題​

KYC Magic Link は、メキシコでの本人確認プロセスを実行し、国民身分証明書（INE）と顔認証バイオメトリクスを収集するという課題に対応します。Unico がホストするフローにより、WhatsApp、SMS、  メールなど独自のチャネルで送信するリンクを通じて、フロントエンド開発の手間を解消します。
**このユースケースを使用する場合：**

**メキシコ**で事業を展開しており、本人確認書類として **INE（必須）** を使用する場合。

**このユースケースを使用しない場合：**

ユーザーがメキシコ国外にいる場合や他の書類を使用する場合 → 他のオンボーディングユースケースをご参照ください。

### 使用される機能​

単一プロセス内で実行されるパイプライン：
[Document Capture (INE)](/ja/capabilities/document-reuse-and-capture)[Liveness](/ja/capabilities/liveness)[Risk Fraud Classification](/ja/capabilities/fraud-risk-classification)[Identity Verification](/ja/capabilities/identity-verification)
機能必須フローにおける役割**Document Capture**必須INE 書類画像をキャプチャします。このユースケースでは書類の再利用は**利用できません** — セッションごとに新規キャプチャが必要です。**Liveness**必須ライブネスチェック — プロセスの基点となる必須のセルフィー。**Risk Fraud Classification**必須行動シグナルを照合し、CPF に関連する不正リスクにフラグを立てます。**Identity Verification**任意（契約済みの場合）取引の顔が、Unico の本人確認ベースと追加シグナルを使用して、提供された政府発行識別子の保有者に属するかどうかを検証します。**[RENAPO検証](/ja/capabilities/renapo-verification)**任意（契約済みの場合）ユーザーのCURPを使ってメキシコの国民人口登録機関であるRENAPOに照会し、本人確認の結果とあわせて登録レコードを返します。
### 前提条件​

**API キー** — Unico のオンボーディングプロジェクトマネージャーが発行します。`x-api-key` ヘッダーで送信します。
**公開 HTTPS エンドポイント** — Webhook を受信するため（任意ですが推奨）。
**CORS 設定** — Webhook を受信するサーバーで、オリジン `https://verification.unico.app`（本番）と `https://verification.uat.unico.app`（サンドボックス）を許可してください。

### 実装手順​

他のユースケースとは異なり、Magic Link には `flow` フィールドが**ありません** — インテグレーションは Trully API と直接行います。エンドポイントは一意の検証リンクを作成し、独自のチャネルを通じてユーザーに配布します。
### 1. Magic Link の作成​

**エンドポイント：** `POST https://sandbox.trully.ai/v2/magic-link`
**ヘッダー：**
ヘッダー必須説明`x-api-key`はいUnico のオンボーディングプ  ロジェクトマネージャーが発行した API キー。`Content-Type`はい`application/json`
**ボディ（application/json）：**
フィールド型必須説明`external_id`stringいいえリクエストの外部識別子。追跡と参照に使用します。`metadata`objectいいえ設定パラメータのコンテナ。`metadata.phone`stringいいえ国際形式のユーザーの電話番号（例：`521234567890`）。`metadata.redirect_url`stringいいえKYC プロセス完了後にユーザーをリダイレクトする URL。`metadata.webhook_url`stringいいえKYC プロセス完了後にデータを送信する URL。この Webhook はクライアント側で呼び出されます。セキュリティ上の理由から、エンドポイントには HTTPS を使用してください。コンポーネントは Webhook サーバーの応答を 1 分間待機します。それを超えると通信を終了します。プロセス自体は Webhook の通信に影響されません。本番環境とサンドボックスそれぞれで `https://verification.unico.app` と `https://verification.uat.unico.app` を CORS 設定で許可してください。`metadata.track_webhook_url`stringいいえユーザーが処理した各 KYC ステップを送信する URL（以下の Webhook イベントを参照）。この Webhook はクライアント側で呼び出されます。セキュリティ上の理由から、エンドポイントには HTTPS を使用してください。コンポーネントは Webhook サーバーの応答を 1 分間待機します。それを超えると通信を終了します。プロセス自体は Webhook の通信に影響されません。本番環境とサンドボックスそれぞれで `https://verification.unico.app` と `https://verification.uat.unico.app` を CORS 設定で許可してください。
`data.step`（`track_webhook_url` に送信）は Webhook V2 で追跡されるものと同じステップを報告します — 詳細は以下の[サポートされるステップの表](#webhook-v2)を参照してください。
**リクエスト例：**
```
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. トークンとリンク URL の受信​

**レスポンスフィールド：**
フィールド型説明`data.external_id`string（nullable）リクエストの外部識別子。追跡と参照に使用します。`data.created_on`string（date-time）Magic Link が作成された日時。`data.is_active`boolean`true` の場合、Magic Link はアクティブです。`data.token`stringKYC プロセスを Magic Link に紐付けるために使用される Magic Link のトークン。`data.magic_link_url`string（URI）KYC プロセスを開始するための Magic URL リンク。`data.metadata.redirect_url`string（nullable）KYC プロセス完  了後にユーザーをリダイレクトする URL。`data.metadata.webhook_url`string（nullable）KYC プロセス完了後にデータを送信する URL。この Webhook はクライアント側で呼び出されます。`data.metadata.track_webhook_url`string（nullable）ユーザーが処理した各 KYC ステップを送信する URL。この Webhook はクライアント側で呼び出されます。`data.version`stringMagic Link のバージョン。`version`stringリクエストを処理した API のバージョン。変更の追跡と互換性に役立ちます。`status`stringレスポンスステータスのテキスト表現。操作の成功または失敗を示します。`status_code`integerレスポンスの HTTP ステータスコード。リクエスト結果の標準的な指標を提供します。`request_date`string（date-time）リクエストが行われた日時（ISO 8601 形式）。`request.metadata.redirect_url`string（nullable）KYC プロセス完了後にユーザーをリダイレクトする URL（リクエストのエコー）。`request.metadata.webhook_url`string（nullable）完了後にデータを送信する URL（リクエストのエコー）。`request.metadata.track_webhook_url`string（nullable）ユーザーが処理した各 KYC ステップを送信する URL（リクエストのエコー）。
**レスポンス例：**
```
{  "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    }  }}
```

**エラーレスポンス — POST /v2/magic-link**コードメッセージ説明`400 Bad Request``data provided in the field is invalid`リクエストペイロードのデータ構造またはフィールド値が無効です。必須フィールドとフォーマットを  確認してください。`403 Forbidden``Forbidden`API キーが欠落、期限切れ、または権限がありません。`x-api-key` ヘッダーを確認してください。`500 Internal Server Error``internal server error`サーバー側の処理エラーです。指数バックオフで再試行してください。問題が続く場合はサポートにご連絡ください。**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. magic_link_url をユーザーに配布​

WhatsApp、SMS、メールで送信するか、埋め込んでください。ユーザーは自分のデバイスでリンクにアクセスし、ホスト型フローを完了します。
ブラウザでリンクを開く代わりに、フローを自社アプリ内に埋め込みたい場合は、WebView または CustomTab を使用して実現できます。参考 PoC：

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

### 4. 結果の受信​

KYC プロセスの最終結果をどのように受け取るかは自由に選択できます — 自社システムのアーキテクチャに最も適した戦略を選んでください。結果を能動的にポーリングして取得する（GET）方法と、通知を通じて受動的に受信する（Webhook）方法があります。
**オプション A — GET による能動的なポーリング**
`GET /v2/history/request?magic_link_token={token}` を呼び出して結果を取得します（以下の[GET によるポーリング](#polling-via-get)を参照）。最終判定は `data.response.unico.result` に格納されます。
GET のベストプラクティスリンク作成の時点から定期的にポーリングする代わりに、追跡用の Webhook（以下の[Webhook V2](#webhook-v2)を参照）を使用して、いつ問い合わせるべきかを正確に把握してください。`form_decision_maker` ステップを受信した時点が、この GET 呼び出しをトリガーする正確かつ安全なタイミングです。
**オプション B — Webhook による自動受信**
最終結果の準備ができ次第、システムに自動的に通知させます（以下の[Webhook V2](#webhook-v2)を参照）。2 つのバージョンが利用可能です：

**Webhook V1** — トークン作成時に `metadata.webhook_url` で送信した URL で結果を受信します。
**Webhook V2** — オンボーディング PM と事前に設定します。`MAGIC_LINK_RESULTS` イベントをリッスンすることで最終判定を受信します。

レジリエンス — フォールバックWebhook（オプション B）を主な方法として使用する場合でも、フォールバックとして GET クエリ（オプション A）も実装してください。これにより、ネットワーク障害、一時的なサーバー停止、または Webhook の処理失敗が発生した場合でも、照合ルーチンを通じて結果を復旧できます。

### GET によるポーリング​

**エンドポイント：** `GET https://sandbox.trully.ai/v2/history/request`
**クエリパラメータ：**
パラメータ型必須説明`magic_link_token`stringはいMagic Link 作成時に返されたトークン。
**ヘッダー：**
ヘッダー必須説明`x-api-key`はいUnico のオンボーディングプロジェクトマネージャーが発行した API キー。
**リクエスト例：**
```
curl "https://sandbox.trully.ai/v2/history/request?magic_link_token=$TOKEN" \  -H "x-api-key: $TRULLY_API_KEY"
```

**レスポンス例：**
```
{  "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"}
```

**レスポンスフィールド：**
**ルートレベル：**
フィールド型説明`status`stringレスポンスステータスのテキスト表現。`status_code`integerHTTP ステータスコード。`request_date`string（date-time）リクエストが行われた日時。`version`stringリクエストを処理した API バージョン。`data.user_id`string元のリクエストに設定されたユーザー ID。
**`data.images`** — Base64 エンコードされたキャプチャ画像：
フィールド型説明`data.images.document_image`string書類表面の Base64 エンコード画像。`data.images.document_image_back`string書類裏面の Base64 エンコード画像。`data.images.selfie`string検証中にキャプチャされた Base64 エンコードのセルフィー画像。
**`data.response.unico`** — 統合された判定：
フィールド型説明`data.response.unico.process_id`string（UUID）検証プロセスに関連する内部識別子。`data.response.unico.result`stringプロセスの結果。使用可能な値は以下を参照。
**`data.response.unico.result` の使用可能な値：**
結果値は 3 つの評価次元のいずれかをエンコードします：

**身元評価** — 撮影した顔が書類所持者のものかどうか（`PROCESS_RESULT_VERIFIED`、`PROCESS_RESULT_NOT_APPROVED`）。
**不正行動** — 行動またはネットワークシグナルが不正リスクを示すかどうか（`PROCESS_RESULT_LIVE`、`PROCESS_RESULT_HIGH_RISK`、`PROCESS_RESULT_CRITICAL_RISK`、`PROCESS_RESULT_NOT_APPROVED`）。
**Liveness** — 撮影時に生きた顔が検出されたかどうか（`PROCESS_RESULT_NOT_LIVE`）。

結果推奨意味シグナル`PROCESS_RESULT_ERROR`**拒否**プロセスがエラーで終了。システム`PROCESS_RESULT_VERIFIED`**承認**キャプチャ時にユーザーが生存確認済み。ID 保有者の顔であり、不正の証拠なし。身元：確認済み`PROCESS_RESULT_LIVE`**レビュー / 承認**キャプチャ時にユーザーが生存確認済み。ID 保有者であることを保証する十分な証拠がなく、不正の証拠もなし。身元：不確定 · 不正：なし`PROCESS_RESULT_HIGH_RISK`**拒否推奨**強い不正の証拠が少なくとも 1 件発見。最終判断はお客様に委ねられます。不正行動：強いシグナル 1 件`PROCESS_RESULT_CRITICAL_RISK`**拒否推奨**強い不正の証拠が少なくとも 2 件発見。最終判断はお客様に委ねられます。不正行動：強いシグナル 2 件以上`PROCESS_RESULT_NOT_APPROVED`**拒否**複数の不正の兆候が検出されたため拒否推奨。身元：拒否 · 不正行動：複数のシグナル`PROCESS_RESULT_NOT_LIVE`**最大 2 回の再試行を許可**キャプチャ時にユーザーが生存確認できなかったが、他の不正の兆候はなし。Liveness：顔が生きていない
メモ`PROCESS_RESULT_VERIFIED` は**有効化が必要**です。デフォルトではこの結果は**アクティブではありません** — 有効化を希望する場合は Unico プロジェクトマネージャーにご相談ください。
**判断を補助する追加シグナル：**
`LIVE`、`HIGH_RISK`、`CRITICAL_RISK` の場合は、以下のフィールドで 判断を補完してください：
フィールド型意味`face_match`boolean書類とセルフィーの顔照合ステータス。`document.front.face_analysis.match_fraud_flag`boolean書類の顔が不正行為に関連付けられているかどうか。`selfie.match_fraud_flag`booleanセルフィーの顔が不正行為に関連付けられているかどうか。`warnings.external_id`stringユーザーの顔が複数の外部 ID に関連付けられていることを示す警告。
**`data.response`** — トップレベルの結果シグナル：
フィールド型説明`data.response.face_match`booleanセルフィーの顔が書類の顔と一致するかどうか。`data.response.label`string（nullable）特定のサブプロセスの結果に使用。該当しない場合は `null`。`data.response.reason`string（nullable）割り当てられたラベルの理由。`data.response.request_id`stringAPI リクエストの一意識別子。
**`data.response.curp`** — RENAPO に対する CURP 検証：
フィールド型説明`curp`string分析中の CURP 文字列。`government_valid`booleanRENAPO によると CURP が有効かどうか。`government_name`string公式データベースに登録された CURP に関連付けられたフルネーム。`name_to_CURP_valid`boolean提供された名前が CURP と一致するかどうか。`is_mexican`booleanCURP がメキシコ市民に対応するかどうか。`deceased`booleanCURP が公式データベースで死亡として登録されているかどうか。`date_of_birth`stringCURP から読み取られた生年月日（DD/MM/YYYY）。`age`integer計算されたユーザーの年齢。`gender`stringCURP から読み取られた性別（`M` または `F`）。`state_of_birth`stringCURP から読み取られた出生州。`state_iso`string出生州の ISO 3166-2 コード。
**`data.response.document.details`** — 書類検出と鑑定：
フィールド型説明`detected`boolean画像から書類が正常に検出されたかどうか。`document_id`integer処理された書類の一意識別子。`forensics.is_valid`string鑑定分析の結果：`yes`、`no`、または `inconclusive`。
**`data.response.document.front.information`** — INE 表面から OCR で抽出されたフィールド。各フィールドには `text`（抽出された値）と `valid`（構造的に検証できたかどうか）が含まれます：
フィールド説明`name`名。`last_name`父方の姓。`mother_last_name`母方の姓。`complete_name`フルネーム。`birthdate`生年月日（DD/MM/YYYY）。`sex`性別（`H` または `M`）。`curp`書類から抽出された CURP。`electoral_key`選挙人名簿番号。`address`住所。`registration_year`書類が登録された年。`valid_thru`書類の有効期限年。
**`data.response.document.front.face_analysis`** — INE 上の顔の分析：
フィールド型説明`face_id`integerこの顔インスタンスの一意識別子。`face_id_v2`integer一意識別子（バージョン 2）。`unique_face_id_v2`integerすべての照会にわたってこの物理的な顔の永続的識別子。`first_seen`stringこの顔がシステムで最初に確認された日時のタイムスタンプ。`last_seen`stringネットワーク全体でこの顔が最後に確認された日時のタイムスタンプ。`last_seen_by_your_company`string自社の照会でこの顔が最後に確認された日時。`inquiry_date`string現在の検証照会のタイムスタンプ。`match`booleanこの顔がデータベース内の他の顔 と一致する可能性があるかどうか。`match_fraud_flag`booleanこの顔が不正行為に関連付けられているかどうか。`seen_by_your_company`booleanこの顔が以前に自社で確認されたかどうか。`seen_different_companies`integerネットワーク内でこの顔を確認した他の企業数。`times_seen_by_your_company`integer自社の照会でこの顔が確認された合計回数。`times_seen_last_month`integer先月ネットワーク全体で確認された回数。`warnings.external_id`stringユーザーの顔が複数の外部 ID に関連付けられている場合の警告。
**`data.response.document.back`** — INE 裏面の MRZ データ：
フィールド型説明`mrz`string完全な機械読み取り可能ゾーン文字列。`cic`stringMRZ から抽出された CIC 番号。`citizen_id`stringMRZ から読み取った市民識別番号。
**`data.response.selfie`** — キャプチャされたセルフィーの分析：
フィールド型説明`face_id`integerセルフィーの顔インスタンスの一意識別子。`face_id_v2`integer一意識別子（バージョン 2）。`unique_face_id_v2`integerすべての照会にわたってこの物理的な顔の永続的識別子。`first_seen`stringこのセルフィーの顔がシステムで最初に確認された日時。`first_seen_image`booleanこの画像が最初に確認されたかどうか。`last_seen`stringネットワーク全体でこの顔が最後に確認された日時。`last_seen_by_your_company`string自社でこの顔が最後に確認された日時。`inquiry_date`string現在の検証照会のタイムスタンプ。`match`booleanセルフィーの顔がデータベース内の他の顔と一致するかどうか。`match_fraud_flag`booleanセルフィーの顔が不正行為に関連付けられているかどうか。`seen_by_your_company`booleanこの顔が以前に自社で確認されたかどうか。`seen_different_companies`integerネットワーク内でこの顔を確認した他の企業数。`times_seen_by_your_company`integer自社の照会でこの顔が確認された合計回数。`times_seen_last_month`integer先月ネットワーク全体で確認された回数。`warnings`objectセルフィー分析に関連する警告（document の face_analysis と同じ構造）。
**指数バックオフ**を使用したポーリングを実施してください — タイトなループで呼び出さないでください。
**エラーレスポンス — GET /v2/history/request**コードメッセージ説明`400 Bad Request``Input should be a valid UUID, invalid group length...``magic_link_token` パラメータが不正な形式か、有効な UUID 形式ではありません。`404 Not Found``This magic link have no requests associated`提供されたトークンは存在しますが、紐付けられた KYC プロセスがありません。ユーザーがまだフローを完了していない可能性があります。`500 Internal Server Error``internal server error`サーバー側の処理エラーです。指数バックオフで再試行してください。問題が続く場合はサポートにご連絡ください。**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"}
```

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

**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​

3 種類の Webhook イベントが利用可能です。有効化するには、オンボーディングプロジェクトマネージャーに以下を提供してセットアップを依頼してください：エンドポイント **URL**（HTTPS 必須）、**認証タイプ**（`basic_auth`、`api_key`、`oauth2`、`NoAuth`）、**認証設定**、**最大再試行回数**、**再試行間隔（秒）**、**タイムアウト（秒）**。
MAGIC_LINK_RESULTS
このイベントはフロー終了時、Decision Maker が送信された情報の処理を完了したときに送信されます。
```
{  "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
これらのイベントはユーザーがアクションを完了したときに受信されます。たとえば、`form_start` は最初の画面をクリックして完了したこと、つまりユーザーが書類の表面を撮影中であることを意味します。
```
{  "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"}
```

フィールド型説明`data.step`string完了したステップの名前。`data.user_id`string（nullable）Magic Link に設定された外部 ID。`data.started_on`datetimeUTC タイムゾーンのステップ開始時刻。`data.completed_on`datetimeUTC タイムゾーンのステップ完了時刻。`event`stringイベントタイプ識別子。`magic_link_token`uuid一意の Magic Link トークン。`user_id`string（nullable）外部識別子。`date`datetimeイベントタイムスタンプ。
**サポートされるステップ：**
ステップ説明`form_start`ユーザーが最初の Magic Link ボタンをクリック。`form_document_front`ユーザーが INE 表面のキャプチャを完了。`form_document_back`ユーザーが INE 裏面のキャプチャを完了。`form_document`ユーザーが表面と裏面の両プロセスを完了。`form_selfie`ユーザーがライブネスプロセスを完了。`form_decision_maker`ユーザーがフロー全体を完了。
MAGIC_LINK_DOCUMENT_RETAKE_REASONS
このイベントは、表面または裏面のプロセス中に書類の再キャプチャが必要な場合に送信されます。INE の重要なデータが読み取れなかったことを示します。
```
{  "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"}
```

フィールド型説明`data.document_type`string書類の面：`ine_front` または `ine_back`。`data.invalid_document`booleanキャプチャした画像が有効な INE でない場合（表裏いずれか）`true`。`data.invalid_curp`booleanCURP が読み取れなかった場合（`ine_front` のみ）`true`。`data.invalid_back_ocr`booleanMRZ コードが読み取れなかった場合（`ine_back` のみ）`true`。`event`stringイベントタイプ識別子。`magic_link_token`uuid一意の Magic Link トークン。`user_id`string（nullable）外部識別子。`date`datetimeイベントタイムスタンプ。
ペイロードは、各書類面につき**1 つ**のエラー（`true`）のみが受信されるよう設計されています。
**INE 表面の失敗シナリオ：**

無効な書類 → `invalid_document: true` のみ
CURP 読み取り失敗 → `invalid_curp: true` のみ

**INE 裏面の失敗シナリオ：**

無効な書類 → `invalid_document: true` のみ
MRZ 読み取り失敗 → `invalid_back_ocr: true` のみ

V1 / V2 互換性リクエストの `metadata` に `webhook_url` を送信し続けている場合（Webhook V1）、その設定がグローバル V2 より**優先されます**。移行するには、`metadata` から `webhook_url` を削除し、オンボーディング PM と共に V2 を設定してください。

### カスタマイズ​

ホスト型 Magic Link ページはクライアントによる**ビジュアルカスタマイズをサポートしません** — デフォルトの Unico/Trully ビジュアルアイデンティティに従います。フロー（ロゴ、カラー、テキスト）をカスタマイズするには、SDK または Web を使用したオンボーディング（グローバル）をご利用ください。
**提供地域：** メキシコ · **エンドポイント：** `POST https://api.trully.ai/v2/magic-link` · **書類：** INE · **認証：** `x-api-key`（Trully）最終更新 2026年10月8日**に