> ## 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 세션의 신분증 인증 또는 주소 증명 결과에 추가 이미지나 PDF(예: 문서 뒷면)를 첨부합니다. Didit에서 제공하는 API입니다.
세션에 이미지 추가 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/ko/sessions-api/retrieve-session.md)에서 새 링크를 다시 가져오십시오. 대신 문서에서 추출된 데이터를 수정하려면 [세션 데이터 업데이트](https://docs.didit.me/ko/sessions-api/update-data.md)를 사용하십시오.
## OpenAPI
````yaml ko/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개를 추가하고(해당 단계가 2회 이상 실행된
경우 가장 최근 결과에 추가), 기존 파일을 유지하며, 세션 활동 로그에 `FILE_ADDED` 항목을 기록합니다. 업로드 시
webhook은 전송되지 않으며 세션 상태도 변경되지 않습니다. 파일은 업로드 시 압축되며 세션 결정의 `extra_files`로
반환됩니다. 이 endpoint는 API 키당 분당 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`. 업로드 시 최대 15 MB이며, 이후 파일이 압축되고 압축 후에도 2
MB(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: >-
인증 또는 권한 부여에 실패했습니다. 키가 누락된 경우 `403`이 반환되며, 다른 애플리케이션의 키, 이
endpoint에 필요한 권한이 없는 범위 지정 키, 키의 IP 허용 목록 외부에서 보낸 요청의 경우에도 마찬가지입니다.
잘못되었거나 취소되었거나 만료된 키는 `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 키당 분당 10회의 이미지 추가 요청으로 제한됩니다(거부된 요청도 포함). 분당
300회의 쓰기 요청 공유 한도도 적용됩니다. 재시도하기 전에 `Retry-After`초 동안 대기하세요.
`X-RateLimit-*` 헤더에 한도 정보가 표시됩니다.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: 사람이 읽기 쉬운 오류 메시지입니다.
examples:
Rate limited:
summary: 현재 분에 할당된 예산이 소진되었습니다
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
'503':
$ref: '#/components/responses/DocumentProcessingBusy'
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:
responses:
DocumentProcessingBusy:
description: >-
현재 너무 많은 문서가 처리 중이므로 이 업로드가 처리되지 않았습니다. 아무것도 저장되지 않았으며 시도 횟수도 사용되지
않았습니다. `Retry-After`의 시간(초)이 지난 후 동일한 파일을 다시 전송하세요. 메시지 텍스트가 아닌 `code`를
기준으로 분기하세요.
headers:
Retry-After:
description: 동일한 요청을 다시 전송하기 전에 대기해야 하는 시간(초)입니다.
schema:
type: integer
example: 10
content:
application/json:
schema:
type: object
required:
- detail
- code
properties:
detail:
type: string
code:
type: string
enum:
- document_processing_busy
example:
detail: We are busy processing documents. Please try again in a moment.
code: document_processing_busy
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본
키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며
특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나
만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된
IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를
벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write
권한이 없는 키는 세션 링크와 token을 null로 수신합니다.
https://docs.didit.me/console/api-keys 를 참고하십시오.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.