KYC Magic Link

MarkdownChatGPTClaude

別途地域契約が必要

このユースケースは 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)LivenessRisk Fraud ClassificationIdentity Verification

機能	必須	フローにおける役割
Document Capture	必須	INE 書類画像をキャプチャします。このユースケースでは書類の再利用は利用できません — セッションごとに新規キャプチャが必要です。
Liveness	必須	ライブネスチェック — プロセスの基点となる必須のセルフィー。
Risk Fraud Classification	必須	行動シグナルを照合し、CPF に関連する不正リスクにフラグを立てます。
Identity Verification	任意（契約済みの場合）	取引の顔が、Unico の本人確認ベースと追加シグナルを使用して、提供された政府発行識別子の保有者に属するかどうかを検証します。
RENAPO検証	任意（契約済みの場合）	ユーザーの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 で追跡されるものと同じステップを報告します — 詳細は以下のサポートされるステップの表を参照してください。

リクエスト例：

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	string	KYC プロセスを 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	string	Magic 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
• React Native: TrullyAI-ReactNativeMagicLink

4. 結果の受信

KYC プロセスの最終結果をどのように受け取るかは自由に選択できます — 自社システムのアーキテクチャに最も適した戦略を選んでください。結果を能動的にポーリングして取得する（GET）方法と、通知を通じて受動的に受信する（Webhook）方法があります。

オプション A — GET による能動的なポーリング

GET /v2/history/request?magic_link_token={token} を呼び出して結果を取得します（以下のGET によるポーリングを参照）。最終判定は data.response.unico.result に格納されます。

GET のベストプラクティス

リンク作成の時点から定期的にポーリングする代わりに、追跡用の Webhook（以下のWebhook V2を参照）を使用して、いつ問い合わせるべきかを正確に把握してください。form_decision_maker ステップを受信した時点が、この GET 呼び出しをトリガーする正確かつ安全なタイミングです。

オプション B — Webhook による自動受信

最終結果の準備ができ次第、システムに自動的に通知させます（以下の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	integer	HTTP ステータスコード。
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	string	API リクエストの一意識別子。

data.response.curp — RENAPO に対する CURP 検証：

フィールド	型	説明
curp	string	分析中の CURP 文字列。
government_valid	boolean	RENAPO によると CURP が有効かどうか。
government_name	string	公式データベースに登録された CURP に関連付けられたフルネーム。
name_to_CURP_valid	boolean	提供された名前が CURP と一致するかどうか。
is_mexican	boolean	CURP がメキシコ市民に対応するかどうか。
deceased	boolean	CURP が公式データベースで死亡として登録されているかどうか。
date_of_birth	string	CURP から読み取られた生年月日（DD/MM/YYYY）。
age	integer	計算されたユーザーの年齢。
gender	string	CURP から読み取られた性別（M または F）。
state_of_birth	string	CURP から読み取られた出生州。
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	string	MRZ から抽出された CIC 番号。
citizen_id	string	MRZ から読み取った市民識別番号。

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	datetime	UTC タイムゾーンのステップ開始時刻。
data.completed_on	datetime	UTC タイムゾーンのステップ完了時刻。
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	boolean	CURP が読み取れなかった場合（ine_front のみ）true。
data.invalid_back_ocr	boolean	MRZ コードが読み取れなかった場合（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）