> ## 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
> Didit APIを使うと、完了したKYCセッションの本人確認または住所証明の結果に、書類の裏面などの追加画像やPDFを添付できます。
セッションに画像を追加するAPI用プロンプト
プロンプトをクリップボードにコピー
\`Attach an extra image or PDF to a finished Didit User Verification (KYC) session through the API.
Endpoint:
PATCH [https://verification.didit.me/v3/session/\{session\_id}/add-images/](https://verification.didit.me/v3/session/\{session_id}/add-images/)
Authentication:
Send my Didit API key in the x-api-key header. A scoped key needs sessions: write.
Goal:
* Add evidence collected outside the verification flow (for example the back of an ID document, or a supporting letter) to the session's ID verification or Proof of Address result, so reviewers see it with the rest of the session.
Request (multipart/form-data):
* file (required): JPG, JPEG, PNG, WEBP, TIFF or PDF, at most 15 MB as uploaded. Didit compresses it and rejects it if it is still over 2 MB (2,097,152 bytes) after compression.
* model\_type (required): "kyc" for the ID verification, "poa" for the Proof of Address.
* file\_password (optional): the password of an encrypted PDF.
Behavior:
* The session must be Approved, Declined, In Review or Kyc Expired, and must have the result named by model\_type. Business (KYB) sessions are not supported.
* When the step ran more than once, the file goes to the most recent result.
* Each call adds one file and keeps the existing ones.
* The file then appears in extra\_files of id\_verifications\[] or poa\_verifications\[] in GET /v3/session/{session_id}/decision/.
* A FILE\_ADDED entry is added to the session's activity log. No webhook is sent and the session status does not change.
* Rate limit: 10 requests per minute per API key.
Example call:
curl -X PATCH "[https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/](https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/)" \
-H "x-api-key: YOUR\_API\_KEY" \
-F "file=@back-of-id.jpg" \
-F "model\_type=kyc"
What to read from the response:
* extra\_files: short-lived presigned links to every extra file of that result, including the new one. A scoped key without media: read receives them as null.
Failure modes:
* 400: file or model\_type missing, unsupported format, file too large before or after compression, encrypted PDF without the right file\_password.
* 401: the API key has expired.
* 403: missing key (a wrong, revoked or expired key gets 401), a key of another application, a scoped key without sessions: write, or a request from outside the key's IP allowlist.
* 404: the session does not exist, was deleted, is outside a scoped key's limits, is not in a reviewable status, or has no result of that model\_type.
* 429: more than 10 calls in a minute. Wait for Retry-After seconds.
Side effects: stores the file with the session and adds an activity entry.
For the full integration shape, see /integration/integration-prompt.\`
貼り付け先
`extra_files`の事前署名付きリンクには有効期限があります。後でファイルが必要になったときは、[セッションの判定](https://docs.didit.me/ja/sessions-api/retrieve-session.md)から新しいリンクを取得してください。書類から抽出されたデータを修正したい場合は、代わりに[セッションデータの更新](https://docs.didit.me/ja/sessions-api/update-data.md)を使用してください。
## OpenAPI
````yaml ja/openapi-25.json PATCH /v3/session/{sessionId}/add-images/
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/{sessionId}/add-images/:
patch:
tags:
- Sessions
summary: セッションに画像を追加
description: >-
完了したユーザー認証(KYC)セッションの本人確認(`model_type=kyc`)または住所証明(`model_type=poa`)の結果に、追加の画像またはPDFを1件添付します。たとえばフロー外で収集した証拠などです。セッションは`Approved`、`Declined`、`In
Review`、`Kyc
Expired`のいずれかで、`model_type`で指定した結果を持っている必要があります。法人確認(KYB)セッションには対応していません。呼び出しごとに1ファイルが追加され(ステップが複数回実行された場合は最新の結果に追加)、既存のファイルは保持され、セッションのアクティビティログに`FILE_ADDED`エントリが記録されます。アップロードによってWebhookは送信されず、セッションのステータスも変わりません。ファイルはアップロード時に圧縮され、セッション判定の`extra_files`で返されます。このエンドポイントはAPIキーごとに1分あたり10リクエストに制限されています。スコープ付きAPIキーには`sessions:
write`が必要で、`media: read`がない場合は`extra_files`のリンクが`null`として返されます。
operationId: patch_v3_session_add_images
parameters:
- name: sessionId
in: path
required: true
description: >-
ファイルを追加するユーザー認証 (KYC) セッションのUUID (`POST
/v3/session/`が返す`session_id`) です。法人確認 (KYB)
セッションのIDを指定すると`404`が返されます。
schema:
type: string
format: uuid
example: 11111111-2222-3333-4444-555555555555
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- model_type
properties:
file:
type: string
format: binary
description: >-
画像またはPDFです。使用できる拡張子は`jpg`、`jpeg`、`png`、`webp`、`tiff`、`pdf`です。アップロード時点で最大15MBです。その後ファイルは圧縮され、それでも2MB(2,097,152バイト)を超える場合は`400`で拒否されます。空のファイルは拒否されます。
model_type:
type: string
enum:
- kyc
- poa
description: '`kyc`はファイルを本人確認の結果に、`poa`は住所証明の結果に追加します。'
example: kyc
file_password:
type: string
description: 暗号化されたPDFのパスワード。パスワードがない場合や誤っている場合、暗号化されたPDFは`400`を返します。
example:
file: (binary)
model_type: kyc
responses:
'200':
description: ファイルが追加されました。新しいファイルを含め、その結果のすべての追加ファイルを返します。
content:
application/json:
schema:
type: object
required:
- extra_files
properties:
extra_files:
type: array
description: >-
`model_type`で指定された結果のすべての追加ファイルへの有効期間の短い署名付きリンク（古い順）。`media:
read`を持たないスコープ付きAPIキーでは、各リンクは`null`です。後から新しいリンクを取得するには、セッションの判定から読み取ってください。
items:
type: string
format: uri
nullable: true
example:
extra_files:
- >-
https://media.example.com/session/11111111-2222-3333-4444-555555555555/kyc-extra-files/66666666-7777-8888-9999-000000000000.jpg?expires=1789383731&signature=abc123
'400':
description: >-
バリデーションエラー。フィールドエラーは`{"":
[""]}`の形式で、暗号化PDFのエラーは`{"detail": "..."}`の形式で返されます。
content:
application/json:
examples:
Missing file:
summary: フォームにファイルパートがありません
value:
file:
- No file was submitted.
Missing model_type:
summary: model_typeが省略されている
value:
model_type:
- This field is required.
Invalid model_type:
summary: model_typeがkycでもpoaでもない
value:
model_type:
- '"passport" is not a valid choice.'
File too large:
summary: 15MBを超えるアップロード
value:
file:
- File size should not exceed 15 MB
Too large after compression:
summary: 圧縮後も2MBを超えています
value:
file:
- File size is too big. Max allowed size is 2097152 bytes.
Encrypted PDF:
summary: file_passwordなしの暗号化PDF
value:
detail: >-
The PDF is encrypted. Please upload a decrypted PDF or a
photo instead.
Wrong PDF password:
summary: file_passwordでPDFを開けません
value:
detail: >-
The PDF password is incorrect. Please provide the correct
password.
'401':
description: >-
スコープ付きAPIキーの有効期限が切れています。`401`が返されるのはこの場合のみです。キーが指定されていない場合、無効な場合、または取り消されている場合は`403`が返されます。
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: 人が読めるエラーメッセージ。
examples:
Expired key:
summary: キーの有効期限が過ぎています
value:
detail: This API key has expired.
'403':
description: >-
認証または認可に失敗しました。キーがない場合、別のアプリケーションのキーの場合、このエンドポイントに必要な権限を持たないスコープ付きキーの場合、キーのIP許可リスト外からのリクエストの場合は`403`を返し、誤った、失効した、または期限切れのキーの場合は`401`を返します。`detail`で区別してください。
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: 人が読めるエラーメッセージ。
examples:
Missing or invalid credentials:
summary: x-api-keyヘッダーがないか、キーの検証に失敗しました
value:
detail: >-
Authentication credentials were not provided or are
invalid.
Other application:
summary: セッションとは別のアプリケーションに属する有効なキー
value:
detail: You do not have permission to perform this action.
Scoped key without sessions write:
summary: 'スコープ付きキーにsessions: write権限がない'
value:
detail: This API key has no write access to sessions.
IP not allowed:
summary: キーのIP許可リスト外からのリクエスト
value:
detail: This API key can't be used from this IP address.
'404':
description: >-
セッションが存在しない、削除されている、またはスコープ付きキーの制限外である。KYBセッションである、または`Approved`、`Declined`、`In
Review`、`Kyc
Expired`のいずれでもない。あるいは、要求された`model_type`の結果がない（ファイルの検証前に確認されます）。セッションの照会は認証情報の確認より前に行われるため、有効なキーがなくても、不明な`sessionId`には`404`が返されます。
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: 人が読めるエラーメッセージ。
examples:
Unknown session:
summary: このIDのセッションが存在しないか、削除されています
value:
detail: Not found.
Outside key limits:
summary: セッションがスコープ付きキーのワークフローまたは承認済みのみの制限外です
value:
detail: Session not found.
Not eligible:
summary: セッションがまだ完了していないか、KYBセッションのIDです
value:
detail: No Session matches the given query.
No ID verification:
summary: 本人確認のないセッションでmodel_type=kycを指定した
value:
detail: The session does not have KYC data.
No Proof of Address:
summary: 住所証明のないセッションでmodel_type=poaを指定した
value:
detail: The session does not have POA data.
'429':
description: >-
レート制限を超過しました。画像追加リクエストはAPIキーごとに1分あたり10件までです（拒否されたリクエストもカウントされます）。1分あたり300件の書き込みリクエストという共通の上限も適用されます。`Retry-After`秒待ってから再試行してください。`X-RateLimit-*`ヘッダーで利用枠を確認できます。
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: 人が読めるエラーメッセージ。
examples:
Rate limited:
summary: 現在の1分間の上限を使い切りました
value:
detail: >-
Session add-images rate limit exceeded. You can make up to
10 requests per minute.
headers:
Retry-After:
description: 再試行までに待機する秒数。
schema:
type: integer
minimum: 1
example: 30
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X PATCH
'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/'
\
-H 'x-api-key: YOUR_API_KEY' \
-F 'file=@./back-of-id.jpg' \
-F 'model_type=kyc'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.add_images(
"11111111-2222-3333-4444-555555555555",
file=open("image.jpg", "rb"),
model_type="kyc",
)
print(result)
- lang: javascript
label: Node.js
source: >-
import Didit, { fileFromPath } from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await
didit.sessions.addImages("11111111-2222-3333-4444-555555555555", {
file: await fileFromPath("image.jpg"),
model_type: "kyc",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.AddImages(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsAddImagesParams{\n\tFile: didit.FileFromPath(\"image.jpg\"),\n\tModelType: \"kyc\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import java.nio.file.Path;
import me.didit.Didit;
import me.didit.types.SessionsAddImagesParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.sessions().addImages("11111111-2222-3333-4444-555555555555",
SessionsAddImagesParams.builder()
.file(Path.of("image.jpg"))
.modelType(SessionsAddImagesParams.ModelType.of("kyc"))
.build());
System.out.println(result);
- lang: php
label: PHP
source: >-
sessions->addImages('11111111-2222-3333-4444-555555555555',
[
'file' => File::fromPath('image.jpg'),
'model_type' => 'kyc',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.add_images(
"11111111-2222-3333-4444-555555555555",
file: Pathname("image.jpg"),
model_type: "kyc"
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await
client.Sessions.AddImagesAsync("11111111-2222-3333-4444-555555555555",
new SessionsAddImagesParams
{
File = FileUpload.FromPath("image.jpg"),
ModelType = "kyc",
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
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.