> ## 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.
# Adicionar imagens a uma sessão via API
> Anexe com a Didit uma imagem ou PDF extra, como o verso do documento, ao resultado de ID ou comprovante de endereço de uma sessão KYC concluída.
Prompt da API para adicionar imagens a uma sessão
Copiar o prompt para a área de transferência
\`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.\`
Colar em
Os links pré-assinados em `extra_files` expiram. Obtenha links novos na [decisão da sessão](https://docs.didit.me/pt-br/sessions-api/retrieve-session.md) quando precisar dos arquivos mais tarde. Para corrigir os dados extraídos de um documento, use [Atualizar dados da sessão](https://docs.didit.me/pt-br/sessions-api/update-data.md).
## OpenAPI
````yaml pt-br/openapi-25.json PATCH /v3/session/{sessionId}/add-images/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/{sessionId}/add-images/:
patch:
tags:
- Sessions
summary: Adicionar uma imagem a uma sessão
description: >-
Anexe uma imagem ou um PDF adicional ao resultado da Verificação de
identidade (`model_type=kyc`) ou do Comprovante de endereço
(`model_type=poa`) de uma sessão de Verificação de usuários (KYC)
finalizada, por exemplo, evidências coletadas fora do fluxo. A sessão
deve estar como `Approved`, `Declined`, `In Review` ou `Kyc Expired` e
conter o resultado indicado por `model_type`; sessões de Verificação de
empresas (KYB) não são suportadas. Cada chamada adiciona um arquivo (ao
resultado mais recente quando a etapa foi executada mais de uma vez),
mantém os arquivos existentes e registra uma entrada `FILE_ADDED` no
registro de atividades da sessão; o envio não dispara nenhum webhook e
não altera o status da sessão. O arquivo é comprimido no envio e é
retornado em `extra_files` da decisão da sessão. Este endpoint é
limitado a 10 requisições por minuto por chave de API. Uma chave de API
com escopo precisa de `sessions: write` e, sem `media: read`, recebe os
links de `extra_files` como `null`.
operationId: patch_v3_session_add_images
parameters:
- name: sessionId
in: path
required: true
description: >-
UUID da sessão de Verificação de usuários (KYC) à qual o arquivo
será adicionado (o `session_id` retornado por `POST /v3/session/`).
Um ID de sessão de Verificação de empresas (KYB) retorna `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: >-
A imagem ou o PDF. Extensões permitidas: `jpg`, `jpeg`,
`png`, `webp`, `tiff`, `pdf`. No máximo 15 MB no envio; o
arquivo é então comprimido e rejeitado com `400` se ainda
for maior que 2 MB (2.097.152 bytes). Arquivos vazios são
rejeitados.
model_type:
type: string
enum:
- kyc
- poa
description: >-
`kyc` adiciona o arquivo ao resultado da verificação de
identidade, `poa` ao resultado do Comprovante de endereço.
example: kyc
file_password:
type: string
description: >-
Senha de um PDF criptografado. Sem ela, ou com uma senha
errada, um PDF criptografado retorna `400`.
example:
file: (binary)
model_type: kyc
responses:
'200':
description: >-
Arquivo adicionado. Retorna todos os arquivos extras desse
resultado, incluindo o novo.
content:
application/json:
schema:
type: object
required:
- extra_files
properties:
extra_files:
type: array
description: >-
Links pré-assinados de curta duração para todos os
arquivos extras do resultado indicado por `model_type`, do
mais antigo para o mais recente. Cada link é `null` para
uma chave de API com escopo sem `media: read`. Obtenha
links novos a partir da decisão da sessão posteriormente.
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: >-
Erro de validação. Os erros de campo chegam como `{"":
[""]}`; os erros de PDF criptografado, como `{"detail":
"..."}`.
content:
application/json:
examples:
Missing file:
summary: Nenhuma parte de arquivo no formulário
value:
file:
- No file was submitted.
Missing model_type:
summary: model_type omitido
value:
model_type:
- This field is required.
Invalid model_type:
summary: model_type não é kyc nem poa
value:
model_type:
- '"passport" is not a valid choice.'
File too large:
summary: Upload acima de 15 MB
value:
file:
- File size should not exceed 15 MB
Too large after compression:
summary: Ainda acima de 2 MB após a compressão
value:
file:
- File size is too big. Max allowed size is 2097152 bytes.
Encrypted PDF:
summary: PDF criptografado sem file_password
value:
detail: >-
The PDF is encrypted. Please upload a decrypted PDF or a
photo instead.
Wrong PDF password:
summary: file_password não abre o PDF
value:
detail: >-
The PDF password is incorrect. Please provide the correct
password.
'401':
description: >-
A chave de API com escopo expirou. Este é o único caso que retorna
`401`: uma chave ausente, inválida ou revogada retorna `403`.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Mensagem de erro legível.
examples:
Expired key:
summary: A data de validade da chave já passou
value:
detail: This API key has expired.
'403':
description: >-
Falha de autenticação ou autorização. Uma chave ausente retorna
`403`, assim como uma chave de outra aplicação, uma chave com escopo
sem a permissão exigida por este endpoint e uma requisição de fora
da lista de IPs permitidos da chave; uma chave incorreta, revogada
ou expirada retorna `401`. Diferencie-as pelo `detail`.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Mensagem de erro legível.
examples:
Missing or invalid credentials:
summary: Cabeçalho x-api-key ausente, ou a chave falhou na validação
value:
detail: >-
Authentication credentials were not provided or are
invalid.
Other application:
summary: >-
Uma chave válida que pertence a uma aplicação diferente da
aplicação da sessão
value:
detail: You do not have permission to perform this action.
Scoped key without sessions write:
summary: 'Chave com escopo sem sessions: write'
value:
detail: This API key has no write access to sessions.
IP not allowed:
summary: Requisição de fora da lista de IPs permitidos da chave
value:
detail: This API key can't be used from this IP address.
'404':
description: >-
A sessão não existe, foi excluída ou está fora dos limites de uma
chave com escopo; é uma sessão KYB ou não está em `Approved`,
`Declined`, `In Review` ou `Kyc Expired`; ou não tem resultado do
`model_type` solicitado (verificado antes da validação do arquivo).
A busca da sessão é feita antes da verificação da credencial, então
um `sessionId` desconhecido retorna `404` mesmo sem uma chave
válida.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Mensagem de erro legível.
examples:
Unknown session:
summary: Não existe nenhuma sessão com este ID, ou ela foi excluída
value:
detail: Not found.
Outside key limits:
summary: >-
A sessão está fora dos limites de fluxo ou de somente
aprovadas de uma chave com escopo
value:
detail: Session not found.
Not eligible:
summary: Sessão ainda não concluída, ou ID de uma sessão KYB
value:
detail: No Session matches the given query.
No ID verification:
summary: model_type=kyc em uma sessão sem verificação de identidade
value:
detail: The session does not have KYC data.
No Proof of Address:
summary: model_type=poa em uma sessão sem Comprovante de endereço
value:
detail: The session does not have POA data.
'429':
description: >-
Limite de requisições excedido: 10 requisições de adição de imagens
por minuto por chave de API (requisições rejeitadas também contam).
A cota compartilhada de 300 requisições de escrita por minuto também
se aplica. Aguarde `Retry-After` segundos antes de tentar novamente;
os cabeçalhos `X-RateLimit-*` mostram a cota.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Mensagem de erro legível.
examples:
Rate limited:
summary: Orçamento do minuto atual esgotado
value:
detail: >-
Session add-images rate limit exceeded. You can make up to
10 requests per minute.
headers:
Retry-After:
description: Segundos de espera antes de tentar novamente.
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: >-
Chave de API da sua aplicação, em Developers -> API keys no Business
Console. A chave principal tem acesso total. Uma chave nomeada pode ter
escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada
a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a
uma data de validade. 401 significa que a chave está errada, revogada ou
expirada; 403 significa que nenhuma chave foi enviada, que a chave não
tem acesso a este recurso ou ação, ou que a requisição veio de um
endereço fora da sua lista de IPs; 404 em uma rota de sessão significa
que a sessão está fora dos fluxos ou status da chave. Uma chave sem
acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave
sem permissão de escrita em sessões recebe links e tokens de sessão como
null. Consulte https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.