つなぎ方

POST /v1/verification_sessions
Authorization: Bearer <あなたの API キー>
Idempotency-Key: <任意>

{
  "assurance_level":     "document",      // age_only / document / identity_match
  "client_reference_id": "user_abc123",   // 256文字以内・個人情報は入れない
  "minimum_age":         18,              // 省略時 18
  "expires_in":          900,             // 秒。60〜604800（7日）・省略時 900
  "metadata":            { "plan": "take" }  // 任意。10キー・値は256文字以内
}

201 Created

{
  "id":         "vs_01JQ…",
  "object":     "verification_session",
  "status":     "requires_input",
  "url":        "https://…/s/<トークン>",   // これをアプリ内で開く
  "expires_at": "2026-09-15T12:15:00.000Z"
}

url に載るトークンは、平文で存在する唯一の場所です。 HANAUTA 側にはハッシュしか残りません。控えておかないと二度と出せません （そのときは新しいセッションを作り直します）。

返るもの

expires_in が上限を超えたときは、黙って15分に丸めず 400 を返します。「7日のリンクを送ったつもり」が静かに壊れるのを避けるためです。

200 OK

{
  "id":                  "vs_01JQ…",
  "object":              "verification_session",
  "status":              "verified",
  "assurance_level":     "document",
  "minimum_age":          18,
  "client_reference_id": "user_abc123",
  "created_at":          "2026-09-15T12:00:00.000Z",
  "expires_at":          "2026-09-15T12:15:00.000Z",
  "metadata":            { "plan": "take" },
  "first_opened_at":     "2026-09-15T12:01:10.000Z",  // 撮影画面を開いた時刻
  "submitted_at":        "2026-09-15T12:03:42.000Z",
  "reviewed_at":         "2026-09-15T15:42:00.000Z",
  "verified_outputs":    ["age_over_18", "document_valid"]
}

status は4つ

却下されたときは requires_input に戻り、last_error に理由（category / code / message）が付きます。 他社のセッションは 404 です （403 にすると ID が存在することだけ漏れるため）。

200 OK

{
  "object":       "artifact_download",
  "slot":         "front",
  "url":          "https://<取得用のホスト>/…?Expires=…&Signature=…",
  "expires_at":   "2026-09-15T15:44:00.000Z",   // 120秒
  "content_type": "image/jpeg"
}

画像は結果に添えて送りません。取りに来てもらいます。 送りつけると、受け取るつもりの無いサーバーにも届いてしまい、 経路上のログにも乗るためです。

呼び出しは成功も失敗も1行ずつ監査ログに残ります（1年）。 記録が書けなければ URL を出しません。

「一回限り」は1セッションにつき1本の意味で、 「1回開いたら無効」ではありません。撮り直しもリロードもあるので、 期限内なら何度でも開けます。

{ "slot": "front", "content_length": 123456, "document_type": "residence_card" }

→ 署名付きの PUT 先（5分で切れる）と、付けるべきヘッダが返る

画像はサーバーのプログラムを通りません。 返した URL でブラウザが置き場へ直接送ります。 置き場の鍵と長さ・型は署名に含まれているので、 宣言と違うものを送ると弾かれます。

種別ごとに、撮る面が決まっています

この表は画面ではなくサーバーが持っています。2箇所に分けると、 画面には枠が出るのに切符が降りてこないという直しようのない状態になります。 その種別で撮らない面を求めると 403 slot_not_allowed です。

{ "faces": [{ "x": 0.31, "y": 0.22, "w": 0.38, "h": 0.44, "score": 0.98 }] }

位置と大きさは画像に対する比率です。「枠に収まっているか」を決めるのは画面のほうで、 サーバーは事実だけ返します。画像は保存しませんし、この口は保存する権限を持ちません。 顔写真の照合が要る水準のときだけ動きます。

202 Accepted

{ "object": "capture_submission", "status": "processing", … }

提出した時点でトークンは無効になります（撮影画面もアップロードも自動的に閉じます）。 必要な画像が置き場に無ければ 400 documents_missing で、 どの面が足りないかを返します。