メインコンテンツへスキップ
POST
curl

概要

セッションを実行する前に、Userエンティティを明示的に作成します。 返されるエンティティは、別途指定しない限りACTIVEステータスになります。 オプションで、同じ呼び出しで本人に認証リンクをメール送信することもできます(認証リンクを送信するを参照)。

利用する場面

  • メタデータの事前登録(レベル、登録経路、社内タグ)を、顧客が認証を行う前に行う場合。
  • 他ベンダーからの移行: 既存のユーザー一覧をDiditで再作成し、履歴と分析を既知の基準から開始する場合。
  • 信頼済みのプロフィール用顔画像のインポート: まずUserを作成し、返されたdidit_internal_idを使ってユーザー顔画像のアップロードを呼び出します。
  • 取引のみのユースケース: vendor_dataを指定してUserを登録し、ユーザー認証(KYC)セッションを一度も実行せずに取引を送信できるようにする場合。
  • 認証への招待: 1回の呼び出しで本人を作成し、認証リンクをメールで送信する場合。

連絡先情報

プロフィールフィールドとあわせて、本人の連絡先情報を送信できます。 full_nameを送信しない場合、first_nameとlast_nameがスペースで連結されてfull_nameになります。 emailとphone_numberはmetadata.contactに、countryはmetadata.addressに保存されます。 countryにはISO 3166コード(alpha-2またはalpha-3、ESまたはESP)を指定でき、指定した値は大文字に変換されて保存されます。 送信するmetadataにJSONオブジェクトではないcontactまたはaddressの値がすでに含まれている場合、Diditはそれを上書きせず、該当する連絡先フィールドに対して400を返します。

認証リンクを送信する

同じ呼び出しで本人に認証を依頼するには、send_verification_linkをtrueに設定します。 Diditはworkflow_idのワークフローで本人の認証セッションを作成し、email宛てにリンクをメール送信します。 メールの言語はlanguageで選択します。省略した場合は英語になります。
  • リンクを送信する場合はemailとworkflow_idが必須で、ワークフローは個人を認証するものでなければなりません。法人確認 (KYB)ワークフローを指定すると400が返されます。
  • セッションにはセッションの作成と同じチェックが適用されます。 vendor_dataがブロックリストに登録されている場合やクレジットが不足している場合は400が返されます。
  • 本人とセッションは一緒に作成されるか、どちらも作成されないかのいずれかです。 いずれかのチェックに失敗した場合、何も書き込まれず、メールも送信されません。
  • レスポンスにはverification_linkが含まれ、セッションのsession_id、session_number、status、url、workflow_id、および送信先のemailが入ります。 リンクを送信しない場合、verification_linkはnullです。

注意事項

  • vendor_dataは必須で、アプリケーションごとに一意でなければなりません。重複して作成しようとすると競合エラーが返されます。既存のユーザーを更新するにはPATCH /v3/users/{vendor_data}/を使用してください。
  • vendor_dataには2000バイト(UTF-8エンコード)の厳格な上限があります。上限を超える値は受け付けられず、400バリデーションエラーが返されます。
  • 通常は認証済みセッションから導出されるフィールド(full_name、date_of_birth)はここで事前登録できますが、最初に承認済みとなったユーザー認証(KYC)セッションによって上書きされる場合があります。
  • このエンドポイントは顔画像を受け付けません。信頼できるインポート済みの顔画像を紐付けるには、このエンドポイントがdidit_internal_idを返した後にPOST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/を使用してください。
  • 作成自体ではWebhookは送信されません。その後のユーザーに対する変更ではuser.data.updatedまたはuser.status.updatedが送信されます。
  • send_verification_linkを指定した場合、新しいセッションが同じリクエスト内でユーザーを更新するため、user.data.updatedが送信されます。

権限

プライマリシークレットとフルアクセスのAPIキーは、常にこのエンドポイントを呼び出せます。 カスタムアクセスのキーには、People(users)の書き込み権限が必要です。 send_verification_link: trueを指定する場合は、呼び出しがセッションを作成してそのリンクを発行するため、Sessionsの書き込み権限も必要です。 この権限がない場合、呼び出しはThis API key has no write access to sessions.とともに403を返し、何も書き込まれません。 一部のワークフローまたは承認済みセッションに限定されたキーは、このエンドポイントにアクセスできません。 Consoleの役割と権限は、チームメンバーがConsoleで実行できる操作を決定するものです。 APIキーによるリクエストでは評価されません。

関連項目

承認

x-api-key
string
header
必須

お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権(なし、読み取り、書き込み)、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys

ボディ

application/json
vendor_data
string
必須

このユーザーに対するお客様独自の識別子です(自由形式の文字列で、UUIDではありません)。アプリケーションのユーザーの間で一意である必要があり、送信されたとおりに完全一致で照合されます。

full_name
string | null

ユーザーの法的な氏名。

Maximum string length: 512
display_name
string | null

コンソールに表示されるわかりやすい表示名(UI表示ではfull_nameより優先されます)。

Maximum string length: 255
date_of_birth
string<date> | null

YYYY-MM-DD形式の生年月日。

status
enum<string>
デフォルト:ACTIVE

初期のライフサイクルステータス。デフォルトはACTIVEです。

利用可能なオプション:
ACTIVE,
FLAGGED,
BLOCKED
metadata
object | null

ユーザーに付与する任意のJSONオブジェクト。デフォルトは{}です。

approved_emails
string[]

このユーザーについて事前に信頼済みとするメールアドレス。例: ["john@example.com"]。

approved_phones
string[]

このユーザーについて事前に信頼済みとする電話番号。例: ["+14155551234"]。

issuing_states
string[]

事前登録された発行国(ISO 3166-1 alpha-3)。例: ["USA"]。

first_name
string

名。full_nameが送信されない場合、Diditはfirst_nameとlast_nameをスペースで結合してfull_nameにします。個別のフィールドとしては返されません。

Maximum string length: 255
last_name
string

姓。full_nameが送信されない場合、first_nameと結合してfull_nameになります。個別のフィールドとしては返されません。

Maximum string length: 255
email
string<email>

連絡先メールアドレス。metadata.contact.emailに保存されます(metadata.contact内で送信したemailは置き換えられます)。send_verification_linkがtrueの場合は必須で、リンクはこのアドレスに送信されます。metadata.contactがJSONオブジェクトでない場合、このフィールドについて400が返されます。

phone_number
string

連絡先電話番号。metadata.contact.phone_numberに保存されます。metadata.contactがJSONオブジェクトでない場合、このフィールドについて400が返されます。

Maximum string length: 32
country
string

ISO 3166コード(alpha-2またはalpha-3)で指定する国(ESまたはESP)。大文字に変換されてmetadata.address.countryに保存されます。metadata.addressがJSONオブジェクトでない場合、このフィールドについて400が返されます。

Maximum string length: 3

trueの場合、Diditはworkflow_idのワークフローでその人物の認証セッションを作成し、email宛てにリンクをメールで送信します。emailとworkflow_idが必須です。スコープ付きAPIキーの場合は、sessionsの書き込み権限も必要です。

workflow_id
string<uuid>

検証セッションのワークフロー。send_verification_linkがtrueの場合は必須です。個人を検証するワークフローである必要があり、法人確認 (KYB)のワークフローは拒否されます。それ以外の場合は無視されます。

language
string

認証メールの言語。対応言語のコードで指定します。省略した場合は英語です。send_verification_linkがtrueでない場合は無視されます。

Maximum string length: 10

レスポンス

ユーザーが作成されました。ユーザーの完全なレコード(Get Userと同じ形式)に加えて、verification_linkを返します。これはsend_verification_linkがtrueの場合にDiditがメールで送信した認証セッションで、それ以外の場合はnullです。

ユーザーの完全な詳細。UserListItemを拡張し、メタデータ、コメント、updated_atを追加します。

Diditが作成し、本人にメールで送信した認証セッション。常に含まれます。send_verification_linkがtrueでなかった場合はnullです。

didit_internal_id
string<uuid>

このユーザーに対するDiditの安定した内部UUIDです。

vendor_data
string | null

このユーザーに対するお客様独自の識別子です(セッション作成時に渡されたもの)。ベンダー識別子が指定されなかった場合はnullになることがあります。

display_name
string | null

お客様が設定したカスタム表示名

full_name
string | null

認証済みの書類から抽出された氏名

date_of_birth
string<date> | null
effective_name
string | null

利用可能な最適な名前:display_nameが設定されていればそれを、設定されていなければfull_nameを使用

status
enum<string>

ユーザーレコードのライフサイクルステータス(セッションのステータスではありません)。ACTIVEがデフォルトで、FLAGGEDはユーザーを手動での確認対象としてマークし、BLOCKEDはこのvendor_dataでの新規セッションを禁止します。

利用可能なオプション:
ACTIVE,
FLAGGED,
BLOCKED
portrait_image_url
string | null

ユーザーの顔写真の署名付きURL(数時間後に期限切れ)

session_count
integer

このユーザーの認証セッションの総数

approved_count
integer

承認済みセッションの数

declined_count
integer

却下されたセッションの数

in_review_count
integer

レビュー中のセッション数

issuing_states
string[]

このユーザーの承認済み身分証明書類で確認された発行国のISO 3166-1 alpha-3コード。例: ["USA", "ESP"]。該当がない場合は空の配列です。

approved_emails
string[]

このユーザーの承認済みセッションから収集された認証済みメールアドレス。例: ["john@example.com"]。

approved_phones
string[]

このユーザーの承認済みセッションから収集された認証済み電話番号。例: ["+14155551234"]。

features
object

このユーザーのすべてのセッションを通じた、機能ごとの集計ステータスです。取り得るキーはID_VERIFICATION、NFC、LIVENESS、FACE_MATCH、POA、QUESTIONNAIRE、EMAIL_VERIFICATION、PHONE、AML、IP_ANALYSIS、AGE_ESTIMATION、DATABASE_VALIDATIONです。取り得る値はApproved、Declined、In Review、Not Finished、Resub Requestedです。

features_list
object[]

featuresと同じデータを、{feature, status}オブジェクトの順序付き配列で表したもの。

last_session_at
string<date-time> | null

直近のセッションの日時

first_session_at
string<date-time> | null

最初のセッションの日時

last_activity_at
string<date-time> | null

このユーザーの直近のアクティビティ(セッション、取引、ステータス変更、データ編集など)の日時。

tags
object[]

タグの割り当て。注意: 詳細レスポンスでは、各エントリはタグのリンクオブジェクト({uuid, tag: {...}, added_by_email, added_by_name, created_at})であり、一覧レスポンスで使われるフラットな{uuid, name, color}形式とは異なります。

created_at
string<date-time>
metadata
object

このユーザーに付加したカスタムメタデータJSON。デフォルトは{}です。

comments
object[]

このユーザーのアクティビティログとコメント(ステータスの変更、プロフィールの編集、手動メモ)。

updated_at
string<date-time>
最終更新日 2026年11月1日