> ## 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.
# Add Images to a Session
> Attach an extra image or PDF to the ID verification or Proof of Address result of a finished KYC session, for example a document's back side.
Add Images to a Session API Prompt
Copy prompt to clipboard
\`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 or invalid key, 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.\`
Paste into
The presigned links in `extra_files` expire. Read fresh ones from the [session decision](/sessions-api/retrieve-session.md) when you need the files later. To correct the data extracted from a document instead, use [Update session data](/sessions-api/update-data.md).
## OpenAPI
````yaml PATCH /v3/session/{sessionId}/add-images/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/{sessionId}/add-images/:
patch:
tags:
- Sessions
summary: Add an image to a session
description: >-
Attach one extra image or PDF to the ID verification (`model_type=kyc`)
or Proof of Address (`model_type=poa`) result of a finished User
Verification (KYC) session, for example evidence collected outside the
flow. The session must be `Approved`, `Declined`, `In Review` or `Kyc
Expired` and carry the result named by `model_type`; Business
Verification (KYB) sessions are not supported. Each call appends one
file (to the most recent result when the step ran more than once), keeps
the existing files and records a `FILE_ADDED` entry in the session
activity log; the upload sends no webhook and does not change the
session status. The file is compressed on upload and is returned in
`extra_files` of the session decision. This endpoint is limited to 10
requests per minute per API key. A scoped API key needs `sessions:
write`, and without `media: read` it receives the `extra_files` links as
`null`.
operationId: patch_v3_session_add_images
parameters:
- name: sessionId
in: path
required: true
description: >-
UUID of the User Verification (KYC) session to add the file to (the
`session_id` returned by `POST /v3/session/`). A Business
Verification (KYB) session ID returns `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: >-
The image or PDF. Allowed extensions: `jpg`, `jpeg`, `png`,
`webp`, `tiff`, `pdf`. At most 15 MB as uploaded; the file
is then compressed and rejected with `400` if it is still
larger than 2 MB (2,097,152 bytes). Empty files are
rejected.
model_type:
type: string
enum:
- kyc
- poa
description: >-
`kyc` adds the file to the ID verification result, `poa` to
the Proof of Address result.
example: kyc
file_password:
type: string
description: >-
Password of an encrypted PDF. Without it, or with a wrong
one, an encrypted PDF returns `400`.
example:
file: (binary)
model_type: kyc
responses:
'200':
description: >-
File added. Returns every extra file of that result, including the
new one.
content:
application/json:
schema:
type: object
required:
- extra_files
properties:
extra_files:
type: array
description: >-
Short-lived presigned links to all extra files of the
result named by `model_type`, oldest first. Each link is
`null` for a scoped API key without `media: read`. Read
fresh links from the session decision later.
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: >-
Validation error. Field errors arrive as `{"":
[""]}`; encrypted-PDF errors as `{"detail": "..."}`.
content:
application/json:
examples:
Missing file:
summary: No file part in the form
value:
file:
- No file was submitted.
Missing model_type:
summary: model_type omitted
value:
model_type:
- This field is required.
Invalid model_type:
summary: model_type is not kyc or poa
value:
model_type:
- '"passport" is not a valid choice.'
File too large:
summary: Upload over 15 MB
value:
file:
- File size should not exceed 15 MB
Too large after compression:
summary: Still over 2 MB after compression
value:
file:
- File size is too big. Max allowed size is 2097152 bytes.
Encrypted PDF:
summary: Encrypted PDF without file_password
value:
detail: >-
The PDF is encrypted. Please upload a decrypted PDF or a
photo instead.
Wrong PDF password:
summary: file_password does not open the PDF
value:
detail: >-
The PDF password is incorrect. Please provide the correct
password.
'401':
description: >-
The scoped API key has expired. This is the only case that returns
`401`: a missing, invalid or revoked key returns `403`.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Human-readable error message.
examples:
Expired key:
summary: The key's expiry date has passed
value:
detail: This API key has expired.
'403':
description: >-
Authentication or authorization failure. Missing, invalid and
revoked keys return `403` (not `401`); so do a key of another
application, a scoped key without the permission this endpoint
needs, and a request from outside the key's IP allowlist.
Distinguish them by `detail`.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Human-readable error message.
examples:
Missing or invalid credentials:
summary: No x-api-key header, or the key failed validation
value:
detail: >-
Authentication credentials were not provided or are
invalid.
Other application:
summary: >-
A valid key that belongs to a different application than the
session
value:
detail: You do not have permission to perform this action.
Scoped key without sessions write:
summary: 'Scoped key lacks sessions: write'
value:
detail: This API key has no write access to sessions.
IP not allowed:
summary: Request from outside the key's IP allowlist
value:
detail: This API key can't be used from this IP address.
'404':
description: >-
The session does not exist, was deleted or is outside a scoped key's
limits; it is a KYB session or not in `Approved`, `Declined`, `In
Review` or `Kyc Expired`; or it has no result of the requested
`model_type` (checked before the file is validated). The session
lookup runs before the credential check, so an unknown `sessionId`
returns `404` even without a valid key.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Human-readable error message.
examples:
Unknown session:
summary: No session with this ID exists, or it was deleted
value:
detail: Not found.
Outside key limits:
summary: >-
The session is outside a scoped key's workflow or
approved-only limits
value:
detail: Session not found.
Not eligible:
summary: Session not finished yet, or a KYB session ID
value:
detail: No Session matches the given query.
No ID verification:
summary: model_type=kyc on a session without ID verification
value:
detail: The session does not have KYC data.
No Proof of Address:
summary: model_type=poa on a session without Proof of Address
value:
detail: The session does not have POA data.
'429':
description: >-
Rate limit exceeded: 10 add-images requests per minute per API key
(rejected requests count too). The shared budget of 300 write
requests per minute also applies. Wait `Retry-After` seconds before
retrying; the `X-RateLimit-*` headers show the budget.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Human-readable error message.
examples:
Rate limited:
summary: Budget for the current minute exhausted
value:
detail: >-
Session add-images rate limit exceeded. You can make up to
10 requests per minute.
headers:
Retry-After:
description: Seconds to wait before retrying.
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: |-
import os
import requests
session_id = '11111111-2222-3333-4444-555555555555'
with open('back-of-id.jpg', 'rb') as fh:
resp = requests.patch(
f'https://verification.didit.me/v3/session/{session_id}/add-images/',
headers={'x-api-key': os.environ['DIDIT_API_KEY']},
files={'file': ('back-of-id.jpg', fh, 'image/jpeg')},
data={'model_type': 'kyc'},
timeout=10,
)
resp.raise_for_status()
print(resp.json()['extra_files'])
- lang: javascript
label: JavaScript
source: >-
import { readFile } from 'node:fs/promises';
const sessionId = '11111111-2222-3333-4444-555555555555';
const form = new FormData();
form.append('file', new Blob([await readFile('./back-of-id.jpg')], {
type: 'image/jpeg' }), 'back-of-id.jpg');
form.append('model_type', 'kyc');
const resp = await
fetch(`https://verification.didit.me/v3/session/${sessionId}/add-images/`,
{
method: 'PATCH',
headers: { 'x-api-key': process.env.DIDIT_API_KEY },
body: form,
});
if (!resp.ok) throw new Error(`Upload failed: ${resp.status}`);
const { extra_files: extraFiles } = await resp.json();
console.log(extraFiles);
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Your application's API key, from Developers -> API keys in the Business
Console. The primary key has full access. A named key can be scoped:
none, read or write per resource, limited to some workflows or to
approved sessions, to a list of IP addresses, and to an expiry date. 401
means the key is missing, wrong, revoked or expired; 403 means the key
has no access to this resource or action, or the request came from an
address outside its IP list; 404 on a session route means the session is
outside the key's workflows or statuses. A key without media access
receives image, video and PDF URLs as null, and a key without sessions
write receives session links and tokens as null. See
https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.