セッションを作成する

POST

/v1/verification-sessions

curl --request POST \
  --url https://api.trust.supa-stg.ai/v1/verification-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "callbackUrl": "https://example.com/kyc/return", "state": "c2FtcGxlLXN0YXRl", "metadata": { "userId": "user_0001" }, "preRegisteredInfo": { "birthDate": "1990-01-01", "lastName": "見本", "firstName": "花子", "address": "東京都見本区見本町1-2-3", "gender": "male" } }'

• staging

本人確認のセッションを作る。応答の verificationUrl へ利用者を送ると、利用者がスマートフォンで手続きを進める。結果は webhook で届き、個人情報を含む詳細は GET /v1/verification-sessions/{id} で取得する。verificationUrl はこの応答でしか返らない。API キーはサーバー側だけで使う

Authorizations

• bearer

Request Body^required

Media typeapplication/json

object

callbackUrl

利用者が手続きを終えたあとに戻す URL。テナントの許可リストに載った https の URL で、クエリ・フラグメントは付けない。戻すときにクエリ sessionId と state を付ける。このクエリは結果ではないので、結果は webhook か GET で確かめる

string

state

CallbackUrl へ戻すときにそのまま付ける値(自社側の相関や CSRF 対策に使う)。state を付けた復帰 URL 全体で 8000 バイトまで(callbackUrl が無ければ state 単体で)

string

metadata

自社側の相関用に渡す任意の JSON オブジェクト(自社のユーザー ID など)。JSON にして 8192 バイトまで。webhook にもそのまま載るので個人情報を入れない

object

preRegisteredInfo

事前に把握している本人の情報。書類の読み取り値・利用者の入力と照合する。1 項目以上。個人情報 — ログに出さない

object

birthDate

生年月日(YYYY-MM-DD)

/^\d{4}-\d{2}-\d{2}$/

lastName

姓

>= 1 characters

<= 128 characters

firstName

名

>= 1 characters

<= 128 characters

address

住所

>= 1 characters

<= 512 characters

gender

性別

string

Allowed values: male female

Responses

201

作成したセッション。verificationUrl へ利用者を送る

Media typeapplication/json

object

id

required

セッション ID(vs_ + 32 桁の 16 進)

/^vs_[0-9a-f]{32}$/

status

required

セッションの進み具合。created = 作成済み(利用者が未着手)/ collecting = 利用者が提出中 / deciding = 判定中 / reviewing = 手動レビュー待ち / completed = 判定が確定 / expired = 利用者が終えないまま期限切れ / failed = 回復できないエラーで終了。承認か否認かは status ではなく outcome.verdict で見る

string

Allowed values: created collecting deciding reviewing completed expired failed

verificationUrl

required

利用者を送る URL。1 回だけ開ける秘密の URL で、この応答でしか返らない(GET では返らない)。ログに出さず、本人以外に渡さない

string

verificationUrlExpiresAt

required

VerificationUrl を開ける期限

string

expiresAt

required

セッションの期限。created / collecting のままこの時刻を過ぎると expired になる

string

createdAt

required

作成日時

string

Example

{
  "id": "vs_00000000000000000000000000000001",
  "status": "created",
  "verificationUrlExpiresAt": "2026-08-02T12:34:56.000Z",
  "expiresAt": "2026-08-02T12:34:56.000Z",
  "createdAt": "2026-08-02T12:34:56.000Z"
}

400

CallbackUrl を受け付けられない(テナントの許可リストに無い・https でない・クエリかフラグメントが付いている) | テナントの設定ではセッションを作れない。settings_missing = 設定が無い / no_steps_enabled = 有効な確認手順が 1 つも無い。管理画面で確認の設定を見直す

Media typeapplication/json

Any of:

object

object

_tag

required

string

Allowed values: CallbackUrlNotAllowed

callbackUrl

required

string

object

object

_tag

required

string

Allowed values: TenantSettingsUnusable

reason

required

string

Allowed values: settings_missing no_steps_enabled

Example

{
  "_tag": "CallbackUrlNotAllowed"
}

401

API キーが無い・正しくない・失効している(理由は区別しない)。Authorization: Bearer <API キー> を確かめる

Media typeapplication/json

object

_tag

required

string

Allowed values: Unauthorized

message

required

string

Example

{
  "_tag": "Unauthorized"
}

403

テナントの IP 許可リストに無いアドレスからの呼び出し。API キーは有効。許可リストの設定を確かめる

Media typeapplication/json

object

_tag

required

string

Allowed values: IpNotAllowed

message

required

string

Example

{
  "_tag": "IpNotAllowed"
}

429

セッション作成の上限に当たった。時間をおいて作り直す(上限値と Retry-After は返さない)

Media typeapplication/json

object

_tag

required

string

Allowed values: RateLimited

message

required

string

Example

{
  "_tag": "RateLimited"
}