> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# セッション作成API：KYC・KYB認証を開始
> DiditのPOST /v3/session/で認証セッションを開始できます。KYCとKYBを統合したエンドポイントで、従量課金、2秒未満の推論、毎月$10の無料クレジット付き。
セッション作成プロンプト
プロンプトをクリップボードにコピー
\
\`Create a verification session via Didit's REST API.
Endpoint:
POST https://verification.didit.me/v3/session/
Authentication:
Use the x-api-key header with your Didit API key. The workflow's type (KYC or KYB) determines which kind of session is created — there is no separate endpoint for KYB.
Request body:
\- workflow_id (string, UUID, required) — Stable workflow UUID from /v3/workflows/. KYC workflows create User Verification sessions; KYB workflows create Business Verification sessions.
\- vendor_data (string, optional) — Your stable identifier for the entity (user or business). Strongly recommended: it binds the session to a User or Business entity and is used for duplicate detection across sessions.
\- callback (string, URL, optional): Where the hosted flow redirects the user when finished. Didit appends ?verificationSessionId={session_id}&status={status}. Falls back to the workflow default. When the application has allowed domains (allowed_domains on PATCH /v3/webhook/), an http or https callback must be on one of those origins (same scheme, host and port), otherwise creation fails with 400 on callback: "callback must be on one of the application's allowed domains: https://app.example.com". Custom URL schemes (app deep links such as myapp://) are always accepted. A workflow-default callback outside the allowed domains is not used for the redirect.
\- callback_method (string, optional, default "initiator") — One of "initiator", "completer", "both". Use "both" if the callback sometimes fails to fire.
\- metadata (object, optional) — Arbitrary JSON echoed back in responses and webhooks. Not shown to the user.
\- tags (array of strings, optional): Tags added to the session when it is created, by name, for example ["VIP", "ONBOARDING Q4"]. Up to 10, each up to 50 characters. Names are case-insensitive and stored in upper case; a name that does not exist yet in the application is created as a new tag. The tags show on the session in the console, where you can filter by them, and come back in the create response.
\- language (string, optional) — ISO 639-1 code for the verification UI (en, es, fr, de, pt, etc.). Defaults to browser detection.
\- contact_details (object, optional) — { email, send_notification_emails, email_lang, phone }. Pre-fills phone/email steps and (optionally) sends notification emails.
\- expected_details (object, optional) — Expected first_name, last_name, date_of_birth, nationality (ISO-3), id_country (ISO-3), expected_document_types (e.g. ["P","ID","DL","RP","SSC"]). Mismatches surface as decision warnings. For Business Verification (KYB) workflows, pass the business fields instead — company_name, registry_country, registration_number — to pre-fill the company registry search; registry_country is ISO 3166-1 alpha-2 and can include the state for state-level registries (e.g. "US-CA"), same format as the KYB Registry Search country_code. Person-level fields are ignored on KYB sessions.
\- portrait_image (string, base64, conditional) — Reference face for Biometric Authentication workflows (and graph workflows where Face Match runs before ID Verification). Max 2MB; JPEG, PNG, WebP, or TIFF. Optional when the vendor_data user already has a stored face: Didit reuses it automatically (approved liveness face, then ePassport chip photo, then ID document portrait, then a manually enrolled profile face). If omitted and no stored face exists, creation fails with 400. Ignored for other workflow types.
\- multi_account_segment (string, optional, max 64 chars) — Duplicate-detection realm inside your own organization. Duplicate face checks only compare this session against other sessions carrying the same segment, so an organization that runs separate account bases (personal vs business, or one per sub-client) does not see a person who legitimately holds one account in each reported as a duplicate. Omit it to use the single default realm — which is what every session uses today, so existing integrations are unaffected. Blocklist and allowlist matching ignore this field: a blocklisted face stays blocklisted in every segment.
\- sandbox_scenario (string, optional, sandbox applications only): Scenario slug from the sandbox catalog (GET /v1/sandbox/scenarios/). Expands the scenario's bundled magic values onto contact_details/expected_details so the session reproduces that outcome. Rejected with 400 on live applications. You can also arm or re-arm a scenario after create, as long as the session is still Not Started, via POST /v3/session/{session_id}/sandbox/arm/. See /integration/sandbox-testing.
\- user_state (string, optional, max 16 chars): Where the person lives, when you know it: an ISO 3166-2 code (US-IL) or a US state code or name (IL, Illinois). In Auto consent mode, Illinois, Texas or Colorado makes the flow ask for explicit biometric consent before the first face capture. 400 on an unrecognized value.
\- biometric_consent (object, optional): Consent you already collected: { given_at (ISO 8601, not in the future), text_version (max 64 chars) }. The flow does not ask again; the decision records it as given with trigger customer_collected.
\- sign (object, optional): { documents: [ { title, file_name, content_base64, fields } ], field_values: { : value } }. documents is for a workflow whose E-signature step takes documents from the session (signature_documents_source "session" or "both"). file_name ends in .pdf or .docx; content_base64 is the file in base64. Up to 20 documents and 50 MB in total; a PDF up to 20 MB and 100 pages, without a password, scripts or attachments; a Word file (.docx) up to 20 MB, converted to PDF while the request runs, at most 5 per session. fields is optional (up to 200 per document): signature, initials, full_name, date_signed, text, checkbox, email or data fields, each with a key unique in its document (^[a-z][a-z0-9_]{0,63}$), placed by page, x, y, width and height, or by anchor text ({ text, occurrence, offset_x, offset_y, width, height }). role defaults to the step's signer. field_values fills the fields whose prefill is "api.", on workflow and session documents alike: strings of 1 to 500 characters, booleans for checkboxes. 400 when the workflow has no E-signature step, takes workflow documents only and you sent documents, or needs session documents you didn't send; field_anchor_not_found, field_value_unknown, field_value_missing or field_value_invalid for fields and values. See /core-technology/electronic-signature/overview.
Idempotency:
Within one application, only one non-finished session can exist per (workflow_id, vendor_data). Calling create again with the same pair returns the existing session (and updates its callback + metadata, and adds any tags you send) instead of creating a duplicate. If you send sign again, its documents, fields and field values must be identical (same order, titles, file names, content, fields and values), or the call returns 400 { "sign": "signature_document_changed" }.
curl example:
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "",
"vendor_data": "user-42",
"callback": "https://yourapp.com/callback",
"metadata": { "plan": "premium" }
}'
Response (201 Created) — keys you must handle:
\- session_id (UUID) — use this on every subsequent /v3/session/{session_id}/... call.
\- session_kind ("user" | "business") — discriminator, dispatch on this.
\- session_number (int) — human-friendly per-application sequence.
\- session_token (string) — short-lived, embedded in the hosted URL. Treat as secret.
\- url (string) — hosted verification URL. Redirect the end user here. (Field name is "url", NOT "verification_url".)
\- status (string) — newly created sessions return "Not Started".
\- workflow_id, workflow_version, vendor_data, metadata, callback — echoed back.
See /reference/data-models for the full schema.
Failure modes:
\- 400 — { "workflow_id": ["Invalid workflow_id."] } when the UUID is unknown.
\- 400 — { "vendor_data": ["This user or business has been blocked and cannot create new verification sessions."] } when blocklisted.
\- 400 — { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } when out of credits.
\- 400 — { "portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first." } on a Face Match workflow when portrait_image is omitted and the vendor_data user has no stored face.
\- 401 — invalid or missing API key.
\- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks write:sessions.
\- 429 — rate limited (600 successful calls/minute per token/IP). Honour Retry-After.
Disclosure & consent:
This endpoint generates a URL — it does not record that you obtained user consent. Show your privacy notice and any biometric-specific consent in your own UX before redirecting to the hosted flow.
For people covered by Illinois, Texas or Colorado law, the hosted flow and native SDK 4.10.0 or later can ask for explicit biometric consent before the selfie; native SDKs below 4.10.0 cannot show that step. See /getting-started/biometric-consent.
Next step:
After the user finishes (status changes to Approved / Declined / In Review), call GET https://verification.didit.me/v3/session/{session_id}/decision/ for the full decision — see /sessions-api/retrieve-session.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
貼り付け先
## KYCとKYBへの対応1つのエンドポイントで、ユーザー認証と法人確認 (KYB)の両方のセッションを作成できます。どちらが作成されるかは**ワークフローのタイプ**で決まります。- **KYCワークフロー**の`workflow_id`を渡す → ユーザー認証 (KYC)のセッションが作成されます。レスポンスは`session_kind: "user"`です。
- **KYBワークフロー**の`workflow_id`を渡す → 法人確認 (KYB)のセッションが作成されます。レスポンスは`session_kind: "business"`です。ワークフローはコンソールの*Workflows → Create workflow*で設定します。ワークフローは作成時にKYCかKYBのどちらかに決まり、後からタイプを切り替えることはできません。## 例> [tab] ユーザー認証 (KYC)
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "workflow_id": "YOUR_KYC_WORKFLOW_ID",
> "vendor_data": "user-42",
> "callback": "https://yourapp.com/callback"
> }'
> ```
>
> **レスポンス (201 Created):**
>
> ```json theme={null}
> {
> "session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
> "session_kind": "user",
> "session_number": 1024,
> "session_token": "...",
> "url": "https://verify.didit.me/session/...",
> "status": "Not Started",
> "workflow_id": "YOUR_KYC_WORKFLOW_ID",
> "vendor_data": "user-42"
> }
> ```> [tab] 法人確認 (KYB)
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "workflow_id": "YOUR_KYB_WORKFLOW_ID",
> "vendor_data": "biz-acme-001",
> "callback": "https://yourapp.com/callback"
> }'
> ```
>
> **レスポンス (201 Created):**
>
> ```json theme={null}
> {
> "session_id": "bs-01HJX1...",
> "session_kind": "business",
> "session_number": 89,
> "session_token": "...",
> "url": "https://verify.didit.me/session/...",
> "status": "Not Started",
> "workflow_id": "YOUR_KYB_WORKFLOW_ID",
> "vendor_data": "biz-acme-001"
> }
> ```## 電子署名の書類セッションから書類を受け取る[電子署名](https://docs.didit.me/ja/core-technology/electronic-signature/overview.md)ステップ(`signature_documents_source`が`session`または`both`)がワークフローにある場合は、`sign.documents`で書類を送信します。各書類はファイルをbase64で表したものなので、DiditがURLから書類を取得する必要はありません。```json theme={null}
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"documents": [
{
"title": "Loan agreement",
"file_name": "loan-agreement.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"fields": [
{ "key": "borrower_signature", "type": "signature", "label": "Borrower signature", "page": 3, "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.06 },
{ "key": "date_signed", "type": "date_signed", "label": "Date", "page": 3, "x": 0.6, "y": 0.8, "width": 0.2, "height": 0.03, "date_format": "DD/MM/YYYY" },
{ "key": "loan_amount", "type": "data", "label": "Loan amount", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.loan_amount" },
{ "key": "initials", "type": "initials", "anchor": { "text": "[[initials]]", "occurrence": "all", "offset_x": 0, "offset_y": -0.005, "width": 0.12, "height": 0.04 } }
]
}
],
"field_values": { "loan_amount": "12,000 EUR" }
}
}
```| フィールド | ルール |
| - | - |
| `title` | 署名者に表示されます。1〜255文字。デフォルトは`file_name`です。 |
| `file_name` | 必須。末尾は`.pdf`または`.docx`です。1〜255文字。 |
| `content_base64` | 必須。PDFは最大20MB・100ページまでで、パスワード、スクリプト、添付ファイルを含まないものに限ります。Wordファイルは最大20MBまでで、リクエストの処理中に最大25秒でPDFに変換され、変換後のPDFにも同じ制限が適用されます。Wordファイルはセッション1件あたり最大5件までです。 |
| `fields` | 任意。書類上に配置する[フィールド](https://docs.didit.me/ja/core-technology/electronic-signature/overview.md#書類上のフィールド)を最大200個まで、`id`を除いたフィールド形式で指定します。各フィールドには`key`と`type`が必要で、さらに位置(`page`、`x`、`y`、`width`、`height`)または[`anchor`](#アンカーテキストでフィールドを配置する)のいずれかが必要です。`role`のデフォルトはステップの署名者で、`required`と`label`のデフォルトはタイプによって決まります。`position`はフィールドの配置場所に基づいてDiditが設定します。ページと位置はPDFを基準とし、Wordファイルの場合は変換後のPDFを基準とします。 |`fields`がない場合、署名者は書類を読んで同意します。### アンカーテキストでフィールドを配置するフィールドには位置の代わりに`anchor`を指定できます。これは書類内のテキストで、フィールドを配置する場所の目印になります。アンカーは、Wordテンプレートなどからセッションごとに生成する書類に適しています。ワークフローの書類では、コンソールでフィールドを配置してください。| `anchor`のプロパティ | ルール |
| - | - |
| `text` | 1〜64文字で、書類のテキスト内で検索されます。Wordファイルの場合は変換後のPDF内で検索されます。 |
| `occurrence` | `first`(デフォルト)は最初に一致した箇所に1つのフィールドを配置します。`all`は一致した箇所ごとに1つずつフィールドを配置し、2つ目以降のキーには`_2`、`_3`のように番号が付きます。 |
| `offset_x`, `offset_y` | ページに対する割合です。フィールドの左上隅は、アンカーテキストの左上隅にこれらのオフセットを加えた位置になります。 |
| `width`, `height` | フィールドのサイズで、ページに対する割合で指定します。 |テキストが書類内にない場合、呼び出しは`400`と`field_anchor_not_found`、およびそのフィールドのキーを返します。DiditはPDFからアンカーテキストを削除しないため、アンカーテキストはページの背景と同じ色で記述してください。### フィールドの値`sign.field_values`は、`prefill`が`api.`であるすべてのフィールドの値を、ワークフローの書類とセッションの書類のどちらでも設定します。これらの``名をキーとするオブジェクトです。値は、`text`と`data`のフィールドでは1〜500文字の文字列、`checkbox`ではブール値です。```json theme={null}
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" }
}
}
```| エラー (`400`) | 発生条件 |
| - | - |
| `field_value_unknown` | どのフィールドも使用していないキー。 |
| `field_value_missing` | 必須フィールドの`api.`に値がない。 |
| `field_value_invalid` | 値がフィールドの[バリデーション](https://docs.didit.me/ja/core-technology/electronic-signature/overview.md#検証)を満たさない。 |### エラーと繰り返しの呼び出し1つのセッションで受け付けられる書類は最大20件、合計50MBまでです。次の場合、呼び出しは`sign`エラーとともに`400`を返します。- ワークフローに電子署名ステップがない。
- `sign.documents`を送信したが、ステップがワークフローの書類のみを受け付ける。
- ステップがセッションの書類のみを受け付けるのに書類を送信していない、またはステップにワークフローの書類がないのに書類を送信していない。
- 書類が大きすぎる、有効なbase64ではない、またはサポートされていないファイルである。
- Wordファイルが`signature_document_not_supported`で拒否された、または変換できず`signature_document_conversion_failed`が返された。いずれも[サポートされているファイル](https://docs.didit.me/ja/core-technology/electronic-signature/overview.md#対応ファイル)に記載の`reason`が付きます。
- フィールドが無効である、アンカーが見つからない(`field_anchor_not_found`)、または[フィールドの値](#フィールドの値)が拒否された。同じ`workflow_id`と`vendor_data`で再度createを呼び出すと、保留中のセッションが返されます。その呼び出しで`sign`を送信する場合、書類、フィールド、フィールドの値は最初の呼び出しと同一(順序、タイトル、ファイル名、内容、フィールド、値がすべて同じ)でなければなりません。異なる場合は`{"sign": "signature_document_changed"}`とともに`400`が返されます。別の`vendor_data`を使用するか、保留中のセッションが完了するまでお待ちください。## サンドボックスシナリオでのテストサンドボックスモードのアプリケーションでは、`sandbox_scenario`を渡すことで、実際のプロバイダーや残高に影響を与えずに、あらかじめ決まった結果(承認、特定の却下、またはレビュー中のシナリオ)を事前に設定できます。```json theme={null}
{
"workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
"sandbox_scenario": "decline_document_expired"
}
```本番環境のアプリケーションでは、`sandbox_scenario`は`400`で拒否されます。作成時点で結果が決まっていない場合は、セッションがまだ`Not Started`である限り、後から`POST /v3/session/{session_id}/sandbox/arm/`で有効化(または再有効化)できます。ホスト型フローの開始前に表示されるシナリオ選択画面も、このエンドポイントを使用しています。シナリオの全一覧、マジック値の一覧、armエンドポイントのリクエストとレスポンスの形式については、[サンドボックスとテストデータ](https://docs.didit.me/ja/integration/sandbox-testing.md)を参照してください。## `vendor_data`でセッションをエンティティに紐付ける- KYCワークフローの場合: [ユーザーエンティティ](https://docs.didit.me/ja/entities/users/overview.md)に紐付けられます。ユーザーが存在しない場合は自動的に作成されます。
- KYBワークフローの場合: [企業エンティティ](https://docs.didit.me/ja/entities/businesses/overview.md)に紐付けられます。新規の場合は自動的に作成されます。詳しくは[vendor dataの紐付け](https://docs.didit.me/ja/entities/vendor-data-linking.md)をご覧ください。## イリノイ州、テキサス州、コロラド州における生体認証の同意ホスト型フローとネイティブSDK 4.10.0以降では、アプリケーションの同意モードと本人の所在地に応じて、最初の顔撮影の前に生体認証に関する明示的な同意ステップを表示できます。この判定には、次の2つの任意フィールドが使われます。- `user_state`: 本人の居住地がわかっている場合に指定します(`US-IL`、`IL`、`Illinois`)。Autoモードでは、対象州の場合にフローが同意を求めます。
- `biometric_consent`: すでに取得済みの同意を表す、`given_at`と`text_version`を含むオブジェクトです。この場合、フローは再度同意を求めません。4.10.0未満のネイティブSDKでは、このステップを表示できません。それらのセッションは従来どおり実行され、判定では同意が未取得として報告されます。詳しくは[生体認証の同意](https://docs.didit.me/ja/getting-started/biometric-consent.md)を参照してください。## 重要: 開示と同意は引き続き自社プロダクト内で行う`Create Session`は、検証URLとセッショントークンを生成します。ただし、それだけで、お客様固有のユースケースに必要な開示をユーザーに示したことや、必要な同意を取得したことを証明するものでは**ありません**。自社のアプリケーション、Webサイト、SDKラッパー、またはホワイトラベルのフローからDiditのセッションを開始する場合は、ユーザーが撮影を始める前に、自社のUX内で法的な対応を行ってください。## 推奨される検証前チェックリスト1. **自社**が検証を依頼していること、そして**Didit**がそのフローを提供する検証プロバイダー/処理者であることをユーザーに伝えます。
2. **自社のプライバシー通知**と、そのジャーニーに適用されるデータ管理者側の法的条件へのリンクを掲載します。
3. Diditの[検証に関するプライバシー通知](https://didit.me/terms/verification-privacy-notice)と[本人確認に関するエンドユーザー利用規約](https://didit.me/terms/identity-verification)へのリンクを掲載します。
4. ワークフローに書類の撮影、セルフィーの撮影、ライブネス、または生体認証が含まれる場合は、適用される法律または自社の法的見解で必要とされるときに、**明示的な意思表示による同意**を取得します。
5. カスタムUI、カスタムドメイン、またはAPIのみのジャーニーを使用する場合は、ユーザーをDiditのフローに送る前に、これらの開示を自社のプロダクト内で表示します。
6. 法務チームが監査証跡を求める場合は、通知/同意の文言、タイムスタンプ、関連するメタデータの記録を自社で保管します。> [!WARNING]
>
> 法的要件は法域によって異なります。ホワイトラベルのブランディングを使用しても、検証フローにおけるDiditの役割がなくなるわけではありません。生体認証に特有の規制がある法域で事業を行う場合は、ローンチ前に弁護士と実装内容を確認してください。
## OpenAPI
````yaml ja/openapi-25.json POST /v3/session/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: 本人確認API。x-api-keyヘッダーで認証します。
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/:
post:
tags:
- Sessions
summary: 認証セッションを作成
description: >-
ユーザー認証（KYC）または法人確認（KYB）のセッションを作成し、エンドユーザーのリダイレクト先または埋め込み用として、ホスト型検証`url`と`session_token`を受け取ります。`workflow_id`によって、実行される検証ステップと、セッションがKYCかKYBかが決まります。
このエンドポイントはバックエンドから呼び出してください（APIキーはシークレットのため、ブラウザからは決して呼び出さないでください）。ユーザーや企業の認証が必要になったとき、たとえばサインアップ時、機密性の高いアクションの前、再検証が必要なときに呼び出します。前提条件:
公開済みのワークフロー（コンソールの[ワークフロー](https://docs.didit.me/ja/console/workflows)ページで作成）と、利用可能なクレジットがあるアプリケーションのAPIキー。サンドボックスのアプリケーションではクレジットチェックは行われません。
**冪等性:** `vendor_data`が指定され、同じ`vendor_data`を持つ未完了のセッション（`Not
Started`、`In Progress`、`Resubmitted`、`Awaiting
User`）がワークフローの**現在の最新公開バージョン**上にすでに存在する場合（かつそのセッションにホスト型検証URLがすでにある場合）、重複を作成せずに既存のセッションが返されます（ステータスは`201`のまま）。その際、`callback`と`metadata`は新たに指定された値に更新されます。ワークフローの古いバージョン（その後に再公開されたもの）で作成された未完了のセッションは再利用**されません**。代わりに、最新公開バージョンに固定された新しいセッションが作成されます。`Approved`、`Declined`、`In
Review`、`Expired`、`Abandoned`、`Kyc Expired`のセッションが再利用されることはありません。
**副作用:**
ホスト型検証URLが生成され、保存されます。`contact_details.send_notification_emails`が`true`でメールアドレスが指定されている場合は、認証の招待メールが送信されます。セッションは、ワークフローで設定されたセッション有効期限が経過すると期限切れになります。KYBワークフローでは、`contact_details.phone`と`expected_details`は無視されます。
operationId: post_v3_session_create
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- workflow_id
properties:
workflow_id:
type: string
format: uuid
description: >-
セッションで実行する認証ステップを定義するワークフローの不変の識別子。ワークフローはコンソールの[ワークフロー](/ja/console/workflows)ページで作成・管理します。`workflow_id`によって、セッションがKYCかKYBかも暗黙的に決まります。
example: 11111111-2222-3333-4444-555555555555
x-readme-id: '0.0'
vendor_data:
type: string
description: >-
認証対象のユーザーの一意の識別子(UUID、メールアドレス、社内ユーザーIDなど)。このフィールドは次の用途に使用されます。(1)
**ユーザーのグループ化**:
同じvendor_dataを持つセッションは、Usersタブで同じユーザープロフィールに紐付けられます。(2)
**セッション間の重複検出**:
重複する顔、書類、電話番号、メールアドレス、IPアドレス、デバイスフィンガープリントを確認する際、同じvendor_dataを持つセッションは同一ユーザーとして扱われ、一致の対象から除外されます。vendor_dataがない場合、すべてのセッションが別々のユーザーとして扱われ、重複の可能性があるものがすべて表示されます。重複検出のノイズを減らすため、常にvendor_dataを指定することを強く推奨します。
example: user-123
x-readme-id: '0.1'
multi_account_segment:
type: string
maxLength: 64
description: >-
組織内で重複検知を行う任意の領域（レルム）です。重複顔チェックでは、このセッションを同じセグメントを持つ他のセッションとのみ比較します。そのため、別々のアカウント基盤（個人アカウントと法人アカウント、またはB2Bのサブクライアントごと）でそれぞれ1つずつ正当にアカウントを持つ人物がフラグ付けされることはありません。省略すると単一のデフォルト領域が使用されます。現在はすべてのセッションがこの領域を使用しています。ブロックリストと許可リストの照合では、このフィールドは無視されます。
example: business-accounts
callback:
type: string
description: >-
認証完了後にユーザーをリダイレクトするURL。Diditは`verificationSessionId`と`status`(Approved、Declined、In
Review)をクエリパラメーターとして自動的に付加します。モバイルのコールバックにはカスタムURLスキーム(例:
`myapp://`)を使用できます。省略した場合は、ワークフローのデフォルトの`callback_url`が使用されます。アプリケーションに許可ドメイン(`PATCH
/v3/webhook/`の`allowed_domains`)が設定されている場合、`http`または`https`のコールバックはそのいずれかのオリジン(同一のスキーム、ホスト、ポート)上にある必要があります。そうでない場合、リクエストは`callback`について400で失敗します:
`callback must be on one of the application's allowed
domains: https://app.example.com`。カスタムURLスキームは常に受け付けられます。
example: https://example.com/verification/callback
x-readme-id: '0.2'
callback_method:
type: string
description: >-
指定したコールバックURLへのリダイレクトを、どのデバイスで処理するかを決定します。フローを開始したデバイスのみをリダイレクトするには`initiator`、フローを完了するデバイスをリダイレクトするには`completer`、どちらのデバイスでもコールバックをトリガーできるようにするには`both`を使用します。コールバックが確実にトリガーされない場合は、この値を`both`に設定することをおすすめします。
enum:
- initiator
- completer
- both
default: initiator
example: both
x-readme-id: '0.3'
metadata:
description: >-
セッションとともに保存され、レスポンスとWebhookでそのまま返される任意のJSON。任意のJSON値（オブジェクト、文字列、数値、配列）を受け付けますが、キーと値のペアからなるJSONオブジェクトを推奨します。エンドユーザーには表示されません。独自の相関ID、A/Bテストのバリアント、ビジネス上のコンテキストを渡すために使用します。
example:
user_type: premium
account_id: ABC123
x-readme-id: '0.4'
tags:
type: array
items:
type: string
maxLength: 50
maxItems: 10
description: >-
セッション作成時に名前で付与するタグ。最大10個、各50文字以内です。名前は大文字と小文字を区別せず、大文字で保存されます。アプリケーションにまだ存在しない名前は、新しいタグとして作成されます。タグはコンソールのセッションに表示され、タグでフィルターできます。
example:
- VIP
- ONBOARDING Q4
language:
type: string
description: >-
認証プロセスのインターフェースの言語コード(ISO
639-1)。認証中にエンドユーザーに表示される言語を指定します。指定しない場合、ブラウザの言語が自動的に検出されて使用されます。対応言語の一覧は[こちら](/ja/integration/supported-languages)で確認してください。
enum:
- en
- ar
- bg
- bn
- bs
- ca
- cnr
- cs
- da
- de
- el
- es
- et
- fa
- fi
- fr
- he
- hi
- hr
- hu
- hy
- id
- it
- ja
- ka
- kk
- ko
- ky
- lt
- lv
- mk
- mn
- ms
- nl
- 'no'
- pl
- pt-BR
- pt
- ro
- ru
- sk
- sl
- so
- sq
- sr
- sv
- th
- tr
- uk
- uz
- vi
- zh-CN
- zh-TW
- zh
example: en
x-readme-id: '0.5'
contact_details:
type: object
description: >-
通知、認証フォームの事前入力、電話番号検証に使用できるユーザーの連絡先情報。メールアドレス、連絡に使用する希望言語、電話番号が含まれます。
example:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
properties:
email:
type: string
format: email
description: >-
[メールアドレス認証](/ja/core-technology/email-verification/overview)ステップで使用されるユーザーのメールアドレス（例："john.doe@example.com"）。指定しない場合、ユーザーは認証フロー中に入力する必要があります。
example: john.doe@example.com
x-readme-id: '1.0'
send_notification_emails:
type: boolean
default: false
description: >-
trueに設定し、メールアドレスを指定した場合、ユーザー認証(KYC)または法人確認(KYB)のセッション作成時に、Diditは最初の「Verify
your
identity」メールを非同期で送信します。また、手動レビューが必要なセッションについては、認証ステータスの通知(例:
'In
Review'から'Approved'または'Declined'への変更)も指定したメールアドレスに送信します。これにより、ユーザーは認証完了後にアプリケーションへ戻りやすくなります。セッションでホワイトラベルが有効な場合、送信されるメールもホワイトラベル化されます。
example: true
x-readme-id: '1.1'
email_lang:
type: string
description: >-
メール通知の言語コード(ISO 639-1)。すべてのメール連絡の言語を指定します(例:
"en"、"es"、"fr")。保存されるデフォルト値はありません。省略した場合、認証招待メールは送信時に英語(`en`)にフォールバックします。以下のenumはスナップショットであり、受け付ける値の最新かつ正式な情報源は[対応言語](/ja/integration/supported-languages)のドキュメントです。特定のコードを利用する前に必ず確認してください。
enum:
- en
- ar
- bg
- bn
- bs
- ca
- cnr
- cs
- da
- de
- el
- es
- et
- fa
- fi
- fr
- he
- hi
- hr
- hu
- hy
- id
- it
- ja
- ka
- kk
- ko
- ky
- lt
- lv
- mk
- mn
- ms
- nl
- 'no'
- pl
- pt-BR
- pt
- ro
- ru
- sk
- sl
- so
- sq
- sr
- sv
- th
- tr
- uk
- uz
- vi
- zh-CN
- zh-TW
- zh
example: en
x-readme-id: '1.2'
phone:
type: string
description: >-
[電話番号検証](/ja/core-technology/phone-verification/overview)ステップで使用される、E.164形式の電話番号(例:
"+14155552671")。指定しない場合、ユーザーは検証フロー中に入力する必要があります。法人確認
(KYB)のワークフローでは無視されます。**重要:**
この電話番号は、有効なE.164形式の電話番号である場合にのみ強制適用されます。指定された番号が無効または解析できない場合は無視され、ユーザーは電話番号検証ステップで任意の有効な電話番号を入力できます。
example: '+14155552671'
x-readme-id: '1.3'
x-readme-id: '0.4'
expected_details:
type: object
description: >-
ユーザーの身分証明書類、住所証明、その他の検証ステップから抽出されたデータとの照合に使用される、想定されるユーザー情報です。不一致は判定上の警告として示されます。一部のフィールド（例:
`id_country`、`expected_document_types`）は、ユーザー向けのフローも変更します。法人確認
(KYB)ワークフローでは企業フィールド（`company_name`、`registry_country`、`registration_number`）のみが使用され、ユーザー向けの法人登記検索に事前入力されます。個人レベルのフィールドはすべて無視されます。
example:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
nationality: USA
id_country: USA
expected_document_types:
- P
- ID
properties:
first_name:
type: string
description: >-
ユーザーの名。例:
`John`。照合にはあいまい比較が使用されます。本人確認書類と住所証明の両方のワークフローについて、コンソールで氏名の一致スコアのしきい値を設定することで、厳密さを調整できます。
example: John
x-readme-id: '1.0'
last_name:
type: string
description: >-
ユーザーの姓。例:
`Doe`。照合にはあいまい比較が使用されます。本人確認書類と住所証明の両方のワークフローについて、コンソールで氏名の一致スコアのしきい値を設定することで、厳密さを調整できます。
example: Doe
x-readme-id: '1.1'
date_of_birth:
type: string
format: date
description: 'ユーザーの生年月日（形式: YYYY-MM-DD）。例: `1990-05-15`。'
example: '1990-05-15'
x-readme-id: '1.2'
gender:
type: string
nullable: true
enum:
- M
- F
default: null
description: ユーザーの性別。'M'、'F'、nullのいずれかである必要があります。
example: M
x-readme-id: '1.3'
nationality:
type: string
description: >-
申請者の出身国を示すISO 3166-1 alpha-3コード。例:
`USA`。[対応している国コードの一覧](https://docs.didit.me/ja/core-technology/id-verification/supported-documents-id-verification#国別の対応書類)を参照してください。
example: USA
x-readme-id: '1.4'
country:
type: string
description: >-
本人確認と住所証明の両方の国の不一致チェックでフォールバックとして使用されるISO 3166-1
alpha-3コード。`address`を指定し、`id_country`と`poa_country`のどちらも設定されていない場合は必須です。
example: USA
x-readme-id: 1.4.1
id_country:
type: string
description: >-
申請者の身分証明書類の想定される国を示すISO 3166-1
alpha-3コード。国籍とは異なる場合があります。例:
`GBR`。本人確認の国の不一致チェックでは`country`より優先されます。[対応している国コードの一覧](https://docs.didit.me/ja/core-technology/id-verification/supported-documents-id-verification#国別の対応書類)を参照してください。
example: GBR
x-readme-id: '1.5'
poa_country:
type: string
description: >-
住所証明書類の想定される国を示すISO 3166-1 alpha-3コード。例:
`USA`。住所証明の国の不一致チェックでは`country`より優先されます。[対応している国コードの一覧](https://docs.didit.me/ja/core-technology/id-verification/supported-documents-id-verification#国別の対応書類)を参照してください。
example: USA
x-readme-id: 1.5.1
address:
type: string
description: >-
人が読める形式の住所。できるだけ多くの情報を含めてください。例: `123 Main St, San
Francisco, CA 94105,
USA`。指定する場合は、`country`または`poa_country`も渡す必要があります。渡さない場合、リクエストは`400`で失敗します。
example: 123 Main St, San Francisco, CA 94105, USA
x-readme-id: '1.6'
identification_number:
type: string
description: 'ユーザーの書類番号、個人番号、または納税者番号。例: `123456789`。'
example: '123456789'
x-readme-id: '1.7'
ip_address:
type: string
description: >-
セッションで想定されるIPアドレス（IPv4またはIPv6形式）です。実際のIPアドレスがこの値と異なる場合、警告がログに記録されます。例:
`192.168.1.100`または`2001:db8::1`。
example: 192.168.1.100
x-readme-id: '1.8'
expected_document_types:
type: array
description: >-
本人確認（OCR）ステップでユーザーが提示できる書類の種類を制限します。設定すると、書類選択画面には指定した種類のみが表示され、返される`documents_allowed`もそれに応じて絞り込まれます。値は大文字と小文字を区別せず、重複は除外されます。不明な値は`400`で拒否されます。使用できるコード：`P`（パスポート）、`ID`（国民IDカード）、`DL`（運転免許証）、`RP`（在留カード）、`HIC`（健康保険証）、`TC`（税務カード）、`SSC`（社会保障カード）。
items:
type: string
enum:
- P
- ID
- DL
- RP
- HIC
- TC
- SSC
example:
- P
- ID
x-readme-id: '1.9'
company_name:
type: string
maxLength: 255
description: >-
確認対象企業の想定される正式名称です。例: `Tesco PLC`。法人確認
(KYB)ワークフローで、法人登記検索の企業名フィールドに事前入力されます。`registration_number`も指定されている場合、登記照会では両方の識別子を組み合わせて検索します。KYCワークフローでは無視されます。
example: Tesco PLC
x-readme-id: '1.10'
registry_country:
type: string
maxLength: 10
description: >-
企業が登記されている法人登記の国を示すISO 3166-1 alpha-2コード。例:
`GB`。法人登記が州や省のレベルで運営されている場合は、ISO
3166-2の地域区分コードを`XX-YY`の形式で付加します。`US-CA`はカリフォルニア州の登記を対象とします。[KYB
Registry Search
API](https://docs.didit.me/ja/standalone-apis/kyb-registry-search)の`country_code`と同じ形式です。法人確認
(KYB)ワークフローで登記国を事前選択します。KYCワークフローでは無視されます。
example: US-CA
x-readme-id: '1.11'
registration_number:
type: string
maxLength: 100
description: >-
法人登記における企業の想定される登記番号です。例: `00445790`。法人確認
(KYB)ワークフローで、法人登記検索の登記番号フィールドに事前入力されます。`company_name`も指定されている場合、登記照会では両方の識別子を組み合わせて検索します。KYCワークフローでは無視されます。
example: '00445790'
x-readme-id: '1.12'
x-readme-id: '0.5'
portrait_image:
type: string
format: byte
description: >-
エンドユーザーの顔のBase64エンコードされたポートレート画像です（最大2MB、JPEG、PNG、WebPまたはTIFF）。ワークフローが顔照合を有効にした`Biometric
Authentication`ワークフローである場合、または本人確認（OCR）の前に顔照合を実行するグラフワークフローの場合に、ライブネスのキャプチャと照合する参照画像として使用されます。`vendor_data`のユーザーに保存済みの顔画像がある場合は任意です。Diditはその顔画像を自動的に再利用し、次の優先順位で決定します:
承認済みのライブネスの顔、ePassportのチップ写真、身分証明書の顔写真、手動で登録したプロフィールの顔（承認済みセッションの顔、またはお客様自身が登録した顔のみが再利用されます）。`portrait_image`を指定した場合は、常に保存済みの顔よりも優先されます。省略した場合に保存済みの顔が存在しないとき（または`vendor_data`を送信していないとき）は、セッションの作成が`400`で失敗します。その他のワークフロータイプでは無視されます。
example: >-
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=
x-readme-id: '0.6'
sandbox_scenario:
type: string
description: >-
サンドボックス専用のシナリオスラッグです。APIキーがサンドボックスモードのアプリケーションに属する場合にのみ受け付けられ、本番環境のアプリケーションでは拒否されます。設定すると、作成フローはシナリオに同梱されたマジック値をセッションの入力フィールド（contact_details、expected_details）に展開し、モック化されたプロバイダーが実際のワークフローパイプラインを通じてシナリオの結果を再現します。シナリオカタログはGET
/v1/sandbox/scenarios/または[サンドボックスとテストデータ](/ja/integration/sandbox-testing)を参照してください。セッションがまだ`Not
Started`である限り、作成後にPOST
/v3/session/{sessionId}/sandbox/arm/でシナリオを有効化（または再有効化）することもできます。書類以外の照会では、`lookup_partial_match`、`lookup_no_match`、または`lookup_provider_error`を使用して、設定された試行回数の上限とフォールバックをテストできます。IDウォレットでは、`wallet_cancelled`、`wallet_timeout`、または`wallet_provider_error`を使用します。`approve`は検証済みのウォレットをシミュレートします。カタログのすべてのウォレットは、本番環境のアプリケーションでは利用できないスキームも含め、サンドボックスでテストできます。シミュレートされた試行は課金されません。
example: decline_document_expired
sign:
type: object
description: >-
このセッションの電子署名の入力。`documents`は署名対象の書類で、電子署名ステップがセッションから書類を取得するワークフロー（`signature_documents_source`が`session`または`both`）で使用します。最大20件、合計50MBまでです。`field_values`は、`prefill`が`api.`であるフィールドに値を入力します。ワークフローの書類とセッションの書類のどちらにも適用されます。同じ`workflow_id`と`vendor_data`でセッションを再度作成すると、保留中のセッションが返されます。その呼び出しで`sign`を送信する場合、書類、フィールド、値は最初のものと同一でなければならず、異なる場合は`{"sign":
"signature_document_changed"}`とともに`400`が返されます。[電子署名の書類](/ja/sessions-api/create-session#電子署名の書類)を参照してください。
properties:
documents:
type: array
minItems: 1
maxItems: 20
items:
$ref: '#/components/schemas/SessionSignDocument'
field_values:
type: object
description: >-
各`api.`事前入力ソースの``をキーとする値です。`text`および`data`フィールドには1〜500文字の文字列、`checkbox`にはブール値を指定します。どのフィールドも使用していないキーには`field_value_unknown`、値のない必須フィールドには`field_value_missing`、フィールドのバリデーションに失敗した値には`field_value_invalid`とともに`400`が返されます。
additionalProperties:
oneOf:
- type: string
minLength: 1
maxLength: 500
- type: boolean
example:
credit_limit: 3,000 EUR
user_state:
type: string
maxLength: 16
description: >-
判明している場合の、本人の居住地です。ISO
3166-2の地域区分コード（`US-IL`、`ES-M`）、または米国の州コードもしくは州名（`IL`、`Illinois`）を指定します。明示的な生体認証の同意を法律で義務付けている州（イリノイ州、テキサス州、コロラド州）の場合、検証フローは顔を撮影する前に同意を求め、トリガーは`declared_state`となります。認識されない値は`400`を返します。[生体認証の同意](/ja/getting-started/biometric-consent)を参照してください。
example: US-IL
biometric_consent:
type: object
description: >-
本人からすでに取得済みの、生体認証に関する明示的な同意です。この要件を満たすため、認証フローで再度確認されることはなく、判定には`status:
"given"`、トリガー`customer_collected`として記録されます。本人がフロー内ですでに回答した内容が置き換えられることはありません。[生体認証の同意](/ja/getting-started/biometric-consent)を参照してください。
required:
- given_at
- text_version
properties:
given_at:
type: string
format: date-time
description: 本人が生体認証について明示的な同意を行った日時（ISO 8601）。未来の日時は指定できません。
text_version:
type: string
maxLength: 64
description: 本人が同意した同意文の、自社の記録におけるバージョンID。
example:
workflow_id: 11111111-2222-3333-4444-555555555555
vendor_data: user-123
callback: https://example.com/verification/callback
callback_method: both
metadata:
user_type: premium
account_id: ABC123
language: en
contact_details:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
expected_details:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
id_country: USA
expected_document_types:
- P
- ID
examples:
Create KYC session:
summary: ユーザー認証（KYC）セッションの正常系における完全なペイロード
description: >-
よく設定されるすべてのフィールドを使用した、実践的な作成リクエストの例です。ワークフローの選択、ベンダーとの紐付け、コールバックのルーティング、メタデータ、ロケール、連絡先の事前入力、想定されるユーザー情報が含まれます。上記のcURLサンプルにそのままコピー&ペーストできます。
value:
workflow_id: 11111111-2222-3333-4444-555555555555
vendor_data: user-123
callback: https://example.com/verification/callback
callback_method: both
metadata:
user_type: premium
account_id: ABC123
language: en
contact_details:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
expected_details:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
nationality: USA
id_country: USA
expected_document_types:
- P
- ID
Create KYB session:
summary: 法人確認 (KYB)セッションの正常系ペイロード
description: >-
KYCの呼び出しと同じ形式です。セッションをKYBにするのは`workflow_id`です。`vendor_data`は通常、自社システム内の企業を参照し、`contact_details.email`はフローを完了する法定代理人を指定します。`expected_details`は企業のフィールド（`company_name`、`registry_country`、`registration_number`）を受け付け、これらは法人登記の検索に事前入力されます。KYBワークフローでは、個人レベルのフィールドと`contact_details.phone`は無視されます。
value:
workflow_id: 33333333-4444-5555-6666-777777777777
vendor_data: company-acme-001
callback: https://example.com/kyb/callback
callback_method: both
metadata:
tier: enterprise
company_id: ACME-001
expected_details:
company_name: Tesco PLC
registry_country: GB
registration_number: '00445790'
language: en
contact_details:
email: legal-rep@acme.example.com
send_notification_emails: true
email_lang: en
responses:
'201':
description: >-
セッションが作成されました（ワークフローの最新公開バージョンに同じ`vendor_data`の未完了セッションが既に存在する場合は、そのセッションが返されます）。レスポンスはシリアライズされたセッションで、ユーザーのリダイレクト先となるホスト型検証ページの`url`を含みます。
content:
application/json:
schema:
type: object
required:
- session_id
- session_number
- session_token
- url
- vendor_data
- metadata
- status
- workflow_id
- workflow_version
- callback
properties:
session_id:
type: string
format: uuid
description: >-
認証セッションの一意の識別子。`GET
/v3/session/{sessionId}/decision/`を呼び出す際にこのIDを使用します。
example: 11111111-2222-3333-4444-555555555555
session_number:
type: integer
description: アプリケーション内でセッションに割り当てられる、人が読みやすい連番。サポートやダッシュボードで役立ちます。
example: 43762
session_token:
type: string
description: >-
`url`のホスト型検証フローへのアクセスをエンドユーザーに許可する、12文字のURLセーフなトークン。セッションの有効期限まで有効です。シークレットとして扱ってください。このトークンを持つ人は誰でも、このセッションの検証フローを開くことができます。
example: 3FaJ9wLqX2Mz
url:
type: string
format: uri
description: >-
エンドユーザーのリダイレクト先となるホスト型検証URLです。URLには`session_token`が埋め込まれ、設定されている場合はホワイトラベルドメインが使用されます。リクエストに`language`が含まれる場合、URLには言語のパスセグメントが含まれます(`https://verify.didit.me/{language}/session/{session_token}`、例:
`/es/session/...`)。`language`がない場合、このセグメントは省略されます。
example: https://verify.didit.me/session/3FaJ9wLqX2Mz
vendor_data:
type: string
nullable: true
description: >-
自社システム内のユーザーまたは企業とセッションを紐付けるためにリクエストで渡した識別子。そのままの形で返されます。指定しなかった場合はnullです。
example: user-123
metadata:
description: >-
セッション作成時に保存した任意のJSONペイロード。そのまま返されます。送信したJSON値（オブジェクト、文字列、数値、配列）は変更されずに返されますが、JSONオブジェクトの使用を推奨します。エンドユーザーには表示されません。レスポンスには常に含まれ、作成時に指定しなかった場合は`null`になります。
example:
user_type: premium
account_id: ABC123
tags:
type: array
items:
type: string
description: セッションに付いているタグ。名前で示されます。
example:
- VIP
- ONBOARDING Q4
status:
type: string
enum:
- Not Started
- In Progress
- Approved
- Declined
- In Review
- Expired
- Abandoned
- Kyc Expired
- Resubmitted
- Awaiting User
description: >-
セッションの現在のステータス。新規作成されたセッションは`Not
Started`を返します。ワークフローの最新公開バージョンで同じ`vendor_data`の未完了セッションがすでに存在する場合、返されるステータスはその既存セッションのものです。
example: Not Started
callback:
type: string
format: uri
nullable: true
description: >-
フローの完了後にユーザーが送られる最終的なリダイレクトURLです。DiditはこのURLに`?verificationSessionId={session_id}&status={status}`を付加します。リクエストで指定されていない場合は、ワークフローに設定されたコールバックURLが使用されます。どちらも設定されていない場合は`null`です。アプリケーションに許可ドメインが設定されており、このURLがその範囲外のWeb
URLである場合（例えば、リストが変更される前に設定されたワークフローのデフォルト）、ホスト型フローはユーザーをこのURLにリダイレクトしません。
example: https://example.com/verification/callback
workflow_id:
type: string
format: uuid
description: >-
このセッションが実行されるワークフローの不変の識別子。常にワークフローの不変のグループ識別子です。リクエストで特定のワークフローバージョンのUUIDを参照した場合(後方互換の検索)でも、レスポンスには不変の`workflow_id`が含まれます。コンソールで設定したワークフローとセッションを関連付けるために使用します。
example: 11111111-2222-3333-4444-555555555555
workflow_version:
type: integer
description: >-
セッション作成時に固定された、公開済みワークフローバージョンのバージョン番号。Diditはセッション作成時に`workflow_id`をワークフローの最新の公開バージョンに解決し、後でワークフローが再公開された場合でも、セッションはそのバージョンで実行され続けます。
example: 3
examples:
KYC session:
summary: KYCセッションが作成されました
value:
session_id: 11111111-2222-3333-4444-555555555555
session_number: 43762
session_token: 3FaJ9wLqX2Mz
url: https://verify.didit.me/en/session/3FaJ9wLqX2Mz
vendor_data: user-123
metadata:
user_type: premium
account_id: ABC123
status: Not Started
workflow_id: 11111111-2222-3333-4444-555555555555
workflow_version: 3
callback: https://example.com/verification/callback
KYB session:
summary: KYBセッションが作成されました
value:
session_id: 22222222-3333-4444-5555-666666666666
session_number: 43763
session_token: Yk7pQ2vN8aBc
url: https://verify.didit.me/en/session/Yk7pQ2vN8aBc
vendor_data: company-acme-001
metadata:
tier: enterprise
status: Not Started
workflow_id: 33333333-4444-5555-6666-777777777777
workflow_version: 1
callback: https://example.com/kyb/callback
'400':
description: >-
不正なリクエストです。ペイロードの検証に失敗した（`workflow_id`の欠落または不明、無効な`language`、ブロックリストに登録された`vendor_data`、不正な形式の`portrait_image`、`country`/`poa_country`のない`address`、無効な`sandbox_scenario`、ワークフローの電子署名ステップが受け付けない`sign`の書類・フィールド・値（`signature_document_not_supported`、`signature_document_conversion_failed`、`field_anchor_not_found`、`field_value_missing`など）など）か、組織にセッションを開始するのに十分なクレジットがありません。
ボディは問題のあるフィールド名（フィールド以外のエラーの場合は`detail`）をキーとするオブジェクトです。値は、入力検証の失敗（必須フィールドの欠落、無効な言語、サイズ超過のポートレート画像など）では**文字列の配列**、セッション作成中に検出された失敗（不明な`workflow_id`、ブロックリストに登録された`vendor_data`、顔照合ワークフローで参照用の顔が利用できない）では**単純な文字列**になります。両方の形式に対応してください。
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
detail:
type: string
description: >-
フィールド以外のエラー（クレジット不足など）に対する人が読めるエラーメッセージ。フィールド単位のエラーでは、代わりにフィールド名がキーとなり、値は文字列または文字列の配列になります。
example: >-
You don't have enough credits to perform this request.
Please top up at https://business.didit.me
examples:
Missing workflow_id:
summary: 必須フィールドが省略されています（文字列配列の形式）
value:
workflow_id:
- This field is required.
Invalid workflow_id:
summary: 不明なworkflow_id（プレーン文字列形式）
value:
workflow_id: Invalid workflow_id.
Insufficient credits:
summary: 組織のクレジットが不足しています
value:
detail: >-
You don't have enough credits to perform this request.
Please top up at https://business.didit.me
Blocklisted vendor_data:
summary: vendor_dataがブロックリストに登録されています
value:
vendor_data: >-
This user or business has been blocked and cannot create
new verification sessions.
Portrait image too large:
summary: portrait_imageがサイズ検証に失敗した
value:
portrait_image:
- Image size exceeds 2MB.
No stored face for vendor_data:
summary: portrait_imageがなく、vendor_dataのユーザーに保存済みの顔もない顔照合ワークフロー
value:
portrait_image: >-
No stored face image was found for this user. Send a
portrait_image, or complete an approved verification with
face liveness or an ID document for this vendor_data
first.
Portrait image required without vendor_data:
summary: portrait_imageもvendor_dataもない顔照合ワークフロー
value:
portrait_image: >-
A portrait image is required to perform face match for
this workflow. Send a portrait_image, or provide the
vendor_data of a user with a previously stored face image
to reuse it.
'403':
description: >-
認証または認可に失敗しました。誤った、失効した、または期限切れのキーの場合は`401`を返します。`x-api-key`ヘッダーがない場合、またはAPIキーは有効だがクライアントにこのアプリケーションでセッションを作成する権限がない場合（たとえばAPIキーが別の組織に属している場合）、このエンドポイントは`403`を返します。これらの失敗はいずれも同じボディ`{"detail":
"You do not have permission to perform this
action."}`を返します。`x-api-key`ヘッダーが存在し、対象のアプリケーションに属していることを確認し、必要に応じて[Auth
API](/ja/auth-api/get-credentials)でアプリケーションのAPIキーを再取得してから再試行してください。
**削除されたアプリケーション：**アプリケーションの削除後数分間は、そのAPIキーを使ったリクエストに対して`{"detail":
"This application was deleted.", "code":
"application_deleted"}`が返されることがあります。再試行しないでください。アプリケーションとそのAPIキーはすでに存在しません。その数分が経過した後は、他の無効なキーと同様にキーが拒否されます。
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: You do not have permission to perform this action.
code:
type: string
description: >-
機械可読な理由で、一部の失敗時にのみ含まれます。`application_deleted`：APIキーが削除済みのアプリケーションに属しています。
example: application_deleted
required:
- detail
examples:
Missing or invalid API key:
summary: '`x-api-key`ヘッダーがないか、APIキーが無効です'
value:
detail: You do not have permission to perform this action.
No permission:
summary: クライアントがセッションを作成できない
value:
detail: You do not have permission to perform this action.
Application deleted:
summary: 削除されたアプリケーションのAPIキー
value:
detail: This application was deleted.
code: application_deleted
'429':
description: >-
レート制限を超過しました。同じAPIキー/IPから60秒間に600件を超えるセッション作成リクエストが送信されました。`Retry-After`を確認し、待機してから再試行してください。
**注:**
ソースコードには`PAID_SESSION_RATE_LIMIT=600`とともに、1分あたり10回の`FREE_SESSION_RATE_LIMIT`も定義されています（`sessions/serializers/session.py`）が、この無料枠の上限は**このV3エンドポイントには適用されません**。レート制限ミドルウェアは、プランに関係なく1分あたり600件の`SESSION_CREATE_RATE_LIMIT`を適用します。ここで達する可能性がある制限は1分あたり600件のみです。
headers:
Retry-After:
description: 呼び出し元がリクエストを再試行するまでに待機する必要がある秒数。
schema:
type: integer
minimum: 1
example: 42
X-RateLimit-Limit:
description: >-
超過した制限について、現在の60秒ウィンドウで許可される最大リクエスト数（セッション作成の場合は600）です。サンドボックスのクォータに関するバリアントには含まれません。
schema:
type: integer
example: 600
X-RateLimit-Remaining:
description: 超過した制限について、現在のウィンドウ内でまだ送信できるリクエストの数です。サンドボックスのクォータ版には含まれません。
schema:
type: integer
minimum: 0
example: 0
X-RateLimit-Reset:
description: 現在のレート制限ウィンドウがリセットされるUTCエポック秒。サンドボックスのクォータ版では含まれません。
schema:
type: integer
minimum: 0
example: 1747497600
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: レート制限超過を人が読める形で説明したもの。このメッセージを使って、3つの制限のうちどれに達したかを区別します。
example: >-
Session creation rate limit exceeded. You can make up to
600 requests per minute.
examples:
Session-create limit:
summary: 1分あたり600件を超えるセッション作成リクエスト
value:
detail: >-
Session creation rate limit exceeded. You can make up to
600 requests per minute.
Sandbox session quota:
summary: サンドボックスアプリケーションが24時間で500セッションを超えました
value:
detail: >-
Sandbox session quota exceeded (500 sessions per 24h).
Wait for the window to reset. Expected available in 3600
seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{\n\tWorkflowID: \"11111111-2222-3333-4444-555555555555\",\n\tVendorData: didit.String(\"user-123\"),\n\tCallback: didit.String(\"https://example.com/verification/callback\"),\n\tCallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod(\"both\")),\n\tMetadata: didit.Some[any](map[string]any{\"user_type\": \"premium\", \"account_id\": \"ABC123\"}),\n\tLanguage: didit.Some(didit.SessionsCreateParamsLanguage(\"en\")),\n\tContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{\n\t\tEmail: didit.String(\"john.doe@example.com\"),\n\t\tSendNotificationEmails: didit.Bool(true),\n\t\tEmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang(\"en\")),\n\t\tPhone: didit.String(\"+14155552671\"),\n\t}),\n\tExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{\n\t\tFirstName: didit.String(\"John\"),\n\t\tLastName: didit.String(\"Doe\"),\n\t\tDateOfBirth: didit.String(\"1990-05-15\"),\n\t\tNationality: didit.String(\"USA\"),\n\t\tIDCountry: didit.String(\"USA\"),\n\t\tExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{\"P\", \"ID\"}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: |-
import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new
SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
SessionSignDocument:
type: object
required:
- file_name
- content_base64
properties:
title:
type: string
minLength: 1
maxLength: 255
description: 署名者に表示されるタイトル。デフォルトは`file_name`です。
file_name:
type: string
minLength: 1
maxLength: 255
description: '`.pdf`または`.docx`で終わるファイル名。'
content_base64:
type: string
format: byte
description: >-
ファイルをbase64エンコードしたものです。PDFは最大20MB・100ページまでで、パスワード、スクリプト、添付ファイルを含まないものに限ります。Wordファイル（`.docx`）は最大20MBまでで、リクエストの処理中に最大25秒でPDFに変換されます。変換後のPDFにも同じ制限が適用されます。Wordファイルはセッション1件あたり最大5件です。マクロ、変更履歴、外部コンテンツへのリンク、埋め込みオブジェクトを含むWordファイルは`signature_document_not_supported`で拒否され、変換できないファイルは`signature_document_conversion_failed`を返します。いずれも`reason`が付きます。
fields:
type: array
description: >-
この書類に配置する任意のフィールドです（最大200件）。ページと位置はPDFを基準とし、Wordファイルの場合は変換後のPDFを基準とします。フィールドがない場合、署名者は書類を読んで同意します。
items:
$ref: '#/components/schemas/SignatureField'
maxItems: 200
SignatureField:
type: object
description: >-
セッション書類に配置するフィールド。どの署名者が、どのように、どこに入力するかを指定します。位置(`page`、`x`、`y`、`width`、`height`)または`anchor`のいずれかを指定してください。位置は、表示されたページの左上隅を起点とするページに対する割合で、小数点以下4桁に丸められます。フィールドはページ内に収まる必要があります。1つの書類には最大200個、1人の署名者には最大500個のフィールドを設定でき、書類上にフィールドを持つすべての役割には、その書類上に`signature`または`initials`フィールドが必要です。[書類上のフィールド](/ja/core-technology/electronic-signature/overview#書類上のフィールド)を参照してください。
required:
- key
- type
properties:
key:
type: string
pattern: ^[a-z][a-z0-9_]{0,63}$
description: 結果および`sign.field_values`におけるフィールドの名前になります。書類内で一意です。
type:
type: string
enum:
- signature
- initials
- full_name
- date_signed
- text
- checkbox
- email
- data
description: >-
フィールドが保持する内容です。署名者は採用した`signature`と`initials`を適用し、`text`を入力し、`checkbox`にチェックを入れ、セッションに認証済みのメールアドレスがない場合は`email`を入力します。Diditは`full_name`（認証済みの氏名）、`date_signed`（署名者のタイムゾーンでの署名日）、`data`（`prefill`から取得）、認証済みの`email`を入力し、読み取り専用で表示します。日付選択の種類はありません。`text`を使用してください。
role:
type: string
enum:
- verified_person
- legal_representative
- key_people
description: >-
フィールドに入力する人。`signature_signer`の値で指定します。ステップは自身の署名者のフィールドのみ入力・押印します。デフォルトはステップの署名者です。
page:
type: integer
minimum: 1
description: ページ番号（1から書類のページ数まで）。Word文書の場合は、変換後のPDFのページです。
x:
type: number
minimum: 0
maximum: 1
description: 左端。ページ幅に対する割合で表します。
'y':
type: number
minimum: 0
maximum: 1
description: ページの高さに対する割合で表した上端。
width:
type: number
minimum: 0.02
maximum: 1
description: 幅。ページ幅に対する割合で指定します。署名の幅は最低`0.12`です。
height:
type: number
minimum: 0.012
maximum: 1
description: 高さです。ページの高さに対する比率で指定します。署名の高さは最低`0.035`です。
anchor:
$ref: '#/components/schemas/SignatureFieldAnchor'
required:
type: boolean
description: >-
`signature` and `initials` are required unless you set `false`.
`full_name`, `date_signed` and `data` are always required. The
signer can't finish a document until its required fields have a
value, and a required checkbox must be ticked.
label:
type: string
minLength: 1
maxLength: 80
description: 署名者と結果に表示されます。デフォルト値はタイプから設定されます。
placeholder:
type: string
nullable: true
maxLength: 80
description: '`text`と`email`のみです。'
validation:
$ref: '#/components/schemas/SignatureFieldValidation'
prefill:
type: string
nullable: true
description: >-
値の取得元です。`identity.full_name`、`identity.first_name`、`identity.last_name`、`identity.date_of_birth`（`DD/MM/YYYY`）、`identity.nationality`、`identity.document_number`、`identity.document_type`、`identity.issuing_country`、`identity.address`、`contact.email`、`contact.phone`、`company.name`、`company.registration_number`、`company.address`、`company.country`（KYB）、`session.vendor_data`、`metadata.`（セッションの`metadata`のキー）、または`api.`（`sign.field_values`のキー）のいずれかです。`data`では必須です。`full_name`は常に`identity.full_name`を、`email`は`contact.email`を使用します。`data`、`full_name`、および検証済みの`email`フィールドの値は、署名者が署名を開始した時点で確定します。
editable_when_prefilled:
type: boolean
default: false
description: '`text`と`email`のみです。署名者は事前入力された値を変更できます。'
checked_by_default:
type: boolean
default: false
description: '`checkbox`のみ：ボックスは最初からチェックされた状態になります。'
date_format:
type: string
enum:
- DD/MM/YYYY
- MM/DD/YYYY
- YYYY-MM-DD
- D MMMM YYYY
default: DD/MM/YYYY
description: '`date_signed`のみ。'
SignatureFieldAnchor:
type: object
description: >-
位置ではなく、書類内のテキストを基準にフィールドを配置します。DiditはPDFからそのテキストを削除しないため、ページの背景と同じ色で記述してください。テキストが見つからない場合、呼び出しは`field_anchor_not_found`とともに`400`を返します。[アンカーテキストでフィールドを配置する](/ja/sessions-api/create-session#アンカーテキストでフィールドを配置する)を参照してください。
required:
- text
properties:
text:
type: string
minLength: 1
maxLength: 64
description: 書類内で検索するテキスト。Wordファイルの場合は、変換後のPDF内で検索します。
occurrence:
type: string
enum:
- first
- all
default: first
description: '`all`は一致ごとに1つのフィールドを配置します。最初のキー以降には`_2`、`_3`などが付きます。'
offset_x:
type: number
description: テキストの左端に加算される値で、ページ幅に対する割合で表します。
offset_y:
type: number
description: テキストの上端に加算される値で、ページの高さに対する割合で表します。
width:
type: number
minimum: 0.02
maximum: 1
description: フィールドの幅。ページ幅に対する割合で指定します。
height:
type: number
minimum: 0.012
maximum: 1
description: フィールドの高さです。ページの高さに対する比率で指定します。
SignatureFieldValidation:
type: object
nullable: true
description: '`text`フィールドの値に対するルール。コンソールのプレビュー、署名フロー、APIはすべて同じルールを適用します。'
properties:
kind:
type: string
enum:
- any
- letters
- number
- email
- pattern
description: >-
`letters`: 任意の文字体系の文字、スペース、ハイフン、アポストロフィ。`number`:
数字（小数点区切り文字は任意）。`pattern`: 値が`pattern`に一致する必要があります。
min_length:
type: integer
minimum: 0
maximum: 500
description: '`0`から`max_length`まで。'
max_length:
type: integer
minimum: 1
maximum: 500
default: 120
pattern:
type: string
nullable: true
minLength: 1
maxLength: 200
description: >-
`kind:
"pattern"`の場合は必須です。値全体が一致する必要がある正規表現です。先読み・後読みと後方参照はサポートされていません。
message:
type: string
nullable: true
maxLength: 120
description: デフォルトのエラーの代わりに署名者に表示されます。
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API
keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権（なし、読み取り、書き込み）、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください:
https://docs.didit.me/console/api-keys
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.