> ## 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 para listar sessões: filtre sessões de KYC e KYB
> Didit: GET /v3/sessions/ lista sessões de verificação com filtros por tipo, status, workflow e vendor data. API unificada KYC + KYB, pague por uso.
Prompt para listar sessões
Copiar o prompt para a área de transferência
\
\`List Didit verification sessions for your application with filters and pagination.
Endpoint:
GET https://verification.didit.me/v3/sessions
Authentication:
Use the x-api-key header with your Didit API key. The key must hold read:sessions.
Query parameters:
\- session_kind ("user" | "business" | "all", default "user") — chooses which kind to list. "user" returns only KYC sessions (backward-compatible default). "business" returns only KYB. "all" concatenates both (KYB rows are appended; not interleaved by timestamp).
\- vendor_data (string) — exact match on your stable identifier.
\- didit_internal_id (UUID) — matches vendor_user_id.
\- status (one or more, comma-separated) — Approved, Declined, In Review, In Progress, Not Started, Expired, Abandoned, Kyc Expired, Resubmitted, Awaiting User.
\- workflow_id (one or more UUIDs, comma-separated).
\- country (one or more ISO-3 codes, comma-separated) — issuing-state for KYC, country_code for KYB.
\- region (one or more, comma-separated).
\- document_type (one or more, comma-separated).
\- date_from, date_to (ISO 8601 date) — inclusive on created_at.
\- search (string) - a complete displayed reference such as S-0001 (user) or B-0001 (business) matches only that session number and kind, ignoring leading zeros and letter case.
Other input searches the existing name, contact, document, registration-number and vendor_data fields.
\- tags (comma-separated tag ids) — sessions that carry any of them.
\- decided_from, decided_to (ISO 8601 datetimes) — sessions whose status last changed at or after / before the value.
\- limit (int, default 50), offset (int, default 0) — limit/offset pagination. Both accept values up to 1000000; larger values return 400.
Per-kind filters (silently ignored on the other kind): is_kyc_to_be_reviewed, status_initialized_as_in_review, session_type, api_service, screened_full_name, document_name, warning.
curl example:
curl -G https://verification.didit.me/v3/sessions/ \
-H "x-api-key: " \
\--data-urlencode "session_kind=all" \
\--data-urlencode "status=Approved,In Review" \
\--data-urlencode "date_from=2026-01-01" \
\--data-urlencode "limit=50"
Response envelope:
\{
"count": , // exact up to 100, capped at 100 beyond that: paginate with next
"next": "",
"previous": "",
"results": [ ...rows ]
}
Every row has:
\- session_id (UUID), session_kind ("user" | "business"), session_number, status, vendor_data, created_at.
KYC row extras: portrait_image, document_type, full_name, country (issuing state), phone_number, email_address, features, didit_internal_id, assignee, waiting_since, sla_due_at, top_warnings, warnings_count.
KYB row extras: workflow_type, workflow_label, company_name, registration_number, country (incorporation).
Each row is a LIGHT projection. For the full feature payload of a row, call GET /v3/session/{session_id}/decision/ — see /sessions-api/retrieve-session.
Failure modes:
\- 401 — invalid API key.
\- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks read:sessions.
\- 400 — malformed UUIDs in filters are silently dropped (no error); malformed ISO dates return { "date_from": ["..."] }.
Common patterns:
\- Build a dashboard: paginate with limit + offset, sort newest-first (server orders by -session_number within each kind).
\- Find pending review queue: status=In Review.
\- Find a specific entity's sessions: vendor_data=.
\- Refresh ongoing AML hits: filter by workflow_id of your AML workflow.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
Colar em
## Filtro por tipo de sessãoUse o parâmetro de consulta `session_kind` para escolher o tipo de sessão a retornar:| Valor | Retorna |
| - | - |
| `user` (padrão) | Apenas sessões de Verificação de usuários (KYC). **Comportamento retrocompatível**: omita `session_kind` para obtê-lo. |
| `business` | Apenas sessões de Verificação de empresas (KYB). |
| `all` | Sessões de Verificação de usuários e de Verificação de empresas, concatenadas. |Cada linha da resposta inclui `session_kind: "user" | "business"`, para que seu cliente possa tratar o formato de cada linha conforme o tipo.## Filtros comunsEstes filtros se aplicam aos dois tipos (os filtros exclusivos de usuários são ignorados quando `session_kind=business`, e vice-versa):| Parâmetro de consulta | Descrição |
| - | - |
| `session_kind` | `user`, `business` ou `all`. Padrão: `user`. |
| `vendor_data` | Correspondência exata com o seu identificador. |
| `status` | Um ou mais status, separados por vírgula, escritos exatamente como a API os retorna: `Approved`, `Declined`, `In Review` e assim por diante (consulte [Status de verificação](https://docs.didit.me/pt-br/integration/verification-statuses.md)). |
| `workflow_id` | Filtra pelo fluxo de verificação (workflow) utilizado. |
| `country` | Filtro por código de país (usuário: `issuing_states`, empresa: `country_code`). |
| `date_from`, `date_to` | Intervalo da data de criação (ISO 8601). |
| `tags` | IDs de tags separados por vírgula. Retorna as sessões que tenham qualquer uma delas. |
| `decided_from`, `decided_to` | Datas e horas em ISO 8601. Retorna as sessões cujo status mudou pela última vez nesse intervalo (início inclusivo, fim exclusivo). Usam o horário da última mudança de status, não o horário de criação. |
| `search` | Uma referência completa exibida, como `S-0001` ou `B-0001`, corresponde apenas a esse número e tipo de sessão, ignorando zeros à esquerda e maiúsculas/minúsculas. Qualquer outra entrada pesquisa os campos existentes de nome, contato, documento, número de registro e `vendor_data`. |## Exemplos> [tab] Listar sessões de Verificação de usuários (KYC) (padrão)
>
> ```bash theme={null}
> curl -G https://verification.didit.me/v3/sessions/ \
> -H "x-api-key: YOUR_API_KEY" \
> --data-urlencode "vendor_data=user-42"
> ```
>
> **Resposta (truncada):**
>
> ```json theme={null}
> {
> "count": 3,
> "next": null,
> "previous": null,
> "results": [
> {
> "session_id": "...",
> "session_kind": "user",
> "session_number": 1024,
> "session_url": "...",
> "portrait_image": "...",
> "document_type": "Passport",
> "full_name": "John Doe",
> "country": "GBR",
> "status": "Approved",
> "vendor_data": "user-42",
> "didit_internal_id": "...",
> "created_at": "2026-04-10T09:00:00Z",
> "features": "ID_VERIFICATION,LIVENESS,FACE_MATCH,AML",
> "phone_number": "+14155550123",
> "email_address": "jane@example.com",
> "additional_details": null
> }
> ]
> }
> ```> [tab] Listar sessões de Verificação de empresas (KYB)
>
> ```bash theme={null}
> curl -G https://verification.didit.me/v3/sessions/ \
> -H "x-api-key: YOUR_API_KEY" \
> --data-urlencode "session_kind=business" \
> --data-urlencode "status=Approved"
> ```
>
> **Resposta (truncada):**
>
> ```json theme={null}
> {
> "count": 1,
> "next": null,
> "previous": null,
> "results": [
> {
> "session_id": "...",
> "session_kind": "business",
> "session_number": 89,
> "status": "Approved",
> "vendor_data": "biz-acme-001",
> "created_at": "2026-04-01T09:00:00Z",
> "workflow_id": "wf_kyb_standard",
> "workflow_type": "business",
> "workflow_label": "Standard KYB",
> "company_name": "Acme Corporation Limited",
> "registration_number": "12345678",
> "country": "GBR"
> }
> ]
> }
> ```> [tab] Listar os dois tipos
>
> ```bash theme={null}
> curl -G https://verification.didit.me/v3/sessions/ \
> -H "x-api-key: YOUR_API_KEY" \
> --data-urlencode "session_kind=all" \
> --data-urlencode "date_from=2026-04-01T00:00:00Z"
> ```
>
> Retorna linhas de Verificação de usuários e de Verificação de empresas em um único array `results`. Os consumidores devem tratar cada linha conforme `session_kind`.
>
> > [!NOTE]
> >
> > O modo `all` concatena os resultados em vez de intercalá-los por data e hora. Para percorrer grandes volumes de resultados mistos, chame cada tipo separadamente e faça a mesclagem no cliente.## O formato das linhas varia conforme o tipoAs linhas de Verificação de usuários (KYC) incluem: `portrait_image`, `document_type`, `full_name`, `country` (país emissor), `phone_number`, `email_address` e alguns campos de revisão: `assignee` (o revisor do Console responsável pela sessão, ou `null`), `waiting_since` e `sla_due_at` (definidos apenas enquanto a sessão está `In Review`), `top_warnings` (os avisos mais importantes, cada um com `risk`, `feature`, `log_type` e `short_description`) e `warnings_count`.As linhas de Verificação de empresas (KYB) incluem: `workflow_type`, `workflow_label`, `company_name`, `registration_number`, `country` (país de constituição).Ambas contêm: `session_id`, `session_kind`, `session_number`, `status`, `vendor_data`, `created_at`.Consulte a [visão geral de sessões](https://docs.didit.me/pt-br/sessions-api/overview.md) para ver a matriz completa de recursos.## PaginaçãoA paginação usa `limit` (padrão `50`) e `offset` (padrão `0`), com URLs absolutas `next` e `previous` na resposta. Os dois parâmetros aceitam valores até `1000000`; um valor maior retorna `400`.`count` é exato até `100` e permanece em `100` acima disso, portanto não o use como total. Continue fazendo requisições à URL `next` até que ela seja `null`. Com `session_kind=all`, `count` é a soma dos dois tipos, cada um limitado a `100`.## Relacionados- [Visão geral de sessões](https://docs.didit.me/pt-br/sessions-api/overview.md)
- [Obter sessão](https://docs.didit.me/pt-br/sessions-api/retrieve-session.md): decisão completa para uma linha específica
- [Visão geral de empresas](https://docs.didit.me/pt-br/entities/businesses/overview.md): a entidade Business agregada entre sessões
- [Visão geral de usuários](https://docs.didit.me/pt-br/entities/users/overview.md): a entidade User agregada entre sessões
## OpenAPI
````yaml pt-br/openapi-25.json GET /v3/sessions/
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/sessions/:
get:
tags:
- Sessions
summary: Listar sessões de verificação (KYC e/ou KYB) com filtros e paginação
description: >-
Retorna uma lista paginada das sessões de verificação da aplicação
identificada pela sua chave de API, das mais recentes para as mais
antigas (`session_number` em ordem decrescente).
**URL canônica:** a rota é `/v3/sessions/` (com barra final).
Requisições para `/v3/sessions` sem a barra recebem um redirecionamento
`301` para a URL com barra, com a query string preservada; a maioria dos
clientes HTTP segue esse redirecionamento de forma transparente em GET.
**Quando usar este endpoint e quando usar webhooks.** Use este endpoint
para painéis, buscas de back-office, conciliação e exportações em lote.
Não faça polling dele para acompanhar o andamento de verificações
individuais: configure [webhooks](/pt-br/integration/webhooks), que
enviam eventos `status.updated` no momento em que uma sessão muda. Para
o resultado completo de uma sessão, chame `GET
/v3/session/{sessionId}/decision/`.
**Sessões KYC e KYB.** `session_kind` define quais tipos são listados:
- `user` (padrão): somente sessões de Verificação de usuários (KYC).
Comportamento compatível com versões anteriores.
- `business`: somente sessões de Verificação de empresas (KYB). As
linhas têm um formato diferente e mais reduzido (veja o schema da
resposta).
- `all`: os dois tipos em uma única resposta: a página KYC e a página
KYB para os mesmos `limit`/`offset` são concatenadas em `results`
(linhas KYC primeiro), então uma página pode conter até `2 x limit`
linhas. `count` é a soma dos dois tipos e `next`/`previous` refletem a
paginação do lado KYC. Para uma paginação estrita de dados mistos, chame
`user` e `business` separadamente.
Cada linha traz um discriminador `session_kind` (`"user"` ou
`"business"`).
**Paginação.** Paginação padrão por limit/offset: `limit` (padrão 50) e
`offset` (padrão 0), com `next`/`previous` como URLs de página prontas.
Para linhas KYC, `count` é exato. Para linhas KYB, `count` é calculado
com uma varredura limitada e tem teto de 100: quando há mais de 100
correspondências, ele permanece em 100, então itere usando `next` (ou
verificando se uma página completa foi retornada) em vez de calcular o
total de páginas a partir de `count`.
**Semântica dos filtros.** Todos os filtros são combinados com AND e se
aplicam às linhas KYC. Quando `session_kind` é `business` ou `all`, o
lado KYB respeita os parâmetros compartilhados `vendor_data`, `status`,
`workflow_id`, `country` (código do país da empresa no registro),
`date_from`, `date_to`, `search` (nome da empresa, número de registro —
digite os números de registro sem separadores, por exemplo `DPC001` e
não `DPC-001` —, vendor_data, número da sessão ou UUID da sessão),
`warning` e `organization_name`; os demais filtros exclusivos de KYC são
ignorados nas linhas KYB. Parâmetros separados por vírgula (`status`,
`country`, `document_type`, `region`, `workflow_id`, `document_name`,
`warning`, `organization_name`, `session_type`) correspondem a qualquer
um dos valores listados (OR dentro do parâmetro). `vendor_data` é uma
correspondência exata: use `search` para correspondência parcial.
Valores desconhecidos em filtros de lista simplesmente não retornam
linhas (sem erro); valores tipados malformados (`date_from`, `date_to`,
`didit_internal_id`, `api_service`, `session_kind`) retornam `400` com
um objeto de erro por campo.
**Busca.** `search` se adapta à entrada: um UUID completo busca pelo
`session_id`; dígitos (opcionalmente com `+ - . space`) correspondem ao
prefixo do número da sessão, a números de documento ou pessoais, ao
prefixo do número de telefone ou a `vendor_data`; valores que contêm `@`
correspondem a prefixos de e-mail; qualquer outro texto corresponde a
nomes (sem diferenciar acentos) e a `vendor_data`.
Não há um limite de requisições fixo por endpoint, mas faça polling da
lista com pouca frequência e use webhooks para atualizações em tempo
real.
operationId: get_v3_sessions
parameters:
- name: session_kind
in: query
required: false
description: >-
Qual tipo de sessão listar: `user` (somente KYC, padrão), `business`
(somente KYB) ou `all` (ambos, concatenados - consulte a descrição
para a semântica da paginação combinada). A correspondência não
diferencia maiúsculas de minúsculas (`BUSINESS` funciona); qualquer
valor que não seja uma variação de maiúsculas e minúsculas de
`user`/`business`/`all` retorna `400`.
schema:
type: string
enum:
- user
- business
- all
default: user
example: all
- name: limit
in: query
required: false
description: >-
Número máximo de linhas por página (por tipo quando
`session_kind=all`). O padrão é 50.
schema:
type: integer
default: 50
minimum: 1
maximum: 1000000
example: 20
- name: offset
in: query
required: false
description: >-
Número de linhas a pular antes da primeira linha retornada. O padrão
é 0. Prefira seguir as URLs `next`/`previous` da resposta.
schema:
type: integer
maximum: 1000000
minimum: 0
default: 0
example: 20
- name: status
in: query
required: false
description: >-
Lista separada por vírgula de status de sessão a incluir, por
exemplo, `Approved,In Review`. Os valores diferenciam maiúsculas de
minúsculas; consulte [Status de
verificação](/pt-br/integration/verification-statuses). Valores
desconhecidos não correspondem a nada.
schema:
type: string
example: Approved,In Review
- name: vendor_data
in: query
required: false
description: >-
Filtro de correspondência exata no `vendor_data` que você enviou na
criação da sessão (seu próprio identificador de usuário/empresa).
Para correspondências parciais, use `search`.
schema:
type: string
example: your-user-id-123
- name: search
in: query
required: false
description: >-
Uma referência exibida completa, como `S-0001` (usuário) ou `B-0001`
(empresa), corresponde apenas àquele número e tipo de sessão; zeros
à esquerda e maiúsculas ou minúsculas não afetam a correspondência.
Busca inteligente de texto livre. Um UUID completo corresponde a
`session_id`; uma entrada numérica corresponde ao prefixo do número
da sessão, a números de documento ou pessoais, ao prefixo do
telefone ou a `vendor_data`; uma entrada contendo `@` corresponde a
prefixos de e-mail; outros textos correspondem a nomes (sem
diferenciar acentos) e a `vendor_data`. Um texto livre que contém
dígitos também corresponde aos campos de busca de número de
documento ou pessoal e a prefixos de número de sessão.
schema:
type: string
example: jane doe
- name: workflow_id
in: query
required: false
description: >-
UUIDs de fluxo separados por vírgula (encontre-os na página
Workflows do Console). UUIDs malformados na lista são ignorados; se
nenhum for válido, o resultado fica vazio.
schema:
type: string
example: 9f9b1234-aaaa-bbbb-cccc-1234567890ab
- name: date_from
in: query
required: false
description: >-
Somente sessões criadas nesta data ou depois dela (UTC), no formato
`YYYY-MM-DD`. Datas malformadas retornam `400`.
schema:
type: string
format: date
example: '2026-06-01'
- name: date_to
in: query
required: false
description: >-
Somente sessões criadas até esta data (UTC), no formato
`YYYY-MM-DD`. Para linhas de KYC, o dia inteiro é incluído; para
linhas de KYB, a comparação é `created_at <= date_to` (meia-noite),
então use a data do dia seguinte para incluir um dia completo de
sessões de KYB.
schema:
type: string
format: date
example: '2026-06-30'
- name: tags
in: query
required: false
schema:
type: string
description: >-
IDs de tags separados por vírgula (`tags` da sua aplicação). Retorna
as sessões que têm qualquer um deles. IDs que não são UUIDs válidos
são ignorados e, quando nenhum é válido, a lista fica vazia.
- name: decided_from
in: query
required: false
schema:
type: string
format: date-time
description: >-
Data e hora ISO 8601. Retorna as sessões cujo status mudou pela
última vez nesse momento ou depois dele. O filtro considera o
momento da última mudança de status, não o momento de criação.
- name: decided_to
in: query
required: false
schema:
type: string
format: date-time
description: >-
Data e hora ISO 8601. Retorna as sessões cujo status mudou pela
última vez antes desse momento. Combine com `decided_from` para
obter um intervalo semiaberto.
- name: country
in: query
required: false
description: >-
Filtro de país separado por vírgula. Para linhas de KYC: códigos ISO
3166-1 alpha-3 do Estado emissor do documento de identidade (por
exemplo, `ESP,USA`), que pode ser diferente da nacionalidade. Para
linhas de KYB: o código de país da empresa no registro de empresas.
schema:
type: string
example: ESP,USA
- name: document_type
in: query
required: false
description: >-
Códigos de tipo de documento de identidade verificados na sessão,
separados por vírgula (apenas linhas de KYC): `P` (passaporte), `ID`
(carteira de identidade), `DL` (carteira de motorista), `RP`
(autorização de residência), `SSC` (cartão de seguridade social),
`HIC` (cartão de plano de saúde), `WP` (autorização de trabalho),
`TC` (cartão fiscal), `VISA`, `PSC` (cartão de serviço público),
`BC` (certidão de nascimento), `OTHER`. Observe que o campo
`document_type` da resposta contém o nome de exibição, não o código.
schema:
type: string
example: P,ID
- name: document_name
in: query
required: false
description: >-
Nomes exatos de documentos; é possível passar vários nomes separados
por vírgula, mas o valor só é dividido nas vírgulas quando contém
mais de um separador ` - ` (um nome isolado com uma vírgula interna
é comparado por inteiro). Os nomes são os reconhecidos pela
verificação de documentos (frente ou verso), por exemplo `Spain - Id
Card (2021)`. Somente linhas de KYC.
schema:
type: string
example: Spain - Id Card (2021)
- name: region
in: query
required: false
description: >-
Valores de região/estado do documento separados por vírgula (para
documentos emitidos por região, como carteiras de motorista dos
EUA). Somente linhas de KYC.
schema:
type: string
example: CA,TX
- name: didit_internal_id
in: query
required: false
description: >-
Filtre pelo identificador interno de usuário da Didit (o campo de
resposta `didit_internal_id`) para listar todas as sessões de um
usuário verificado. Deve ser um UUID válido; valores malformados
retornam `400`. Somente linhas de KYC.
schema:
type: string
format: uuid
example: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147
- name: session_type
in: query
required: false
description: >-
Canais de criação de sessão separados por vírgula: `API`, `HOSTED`,
`MIGRATED`. O valor especial `ALL` (ou a omissão do parâmetro)
desativa o filtro. Somente linhas de KYC.
schema:
type: string
example: HOSTED
- name: api_service
in: query
required: false
description: >-
Filtra sessões de API avulsas por serviço. Valores inválidos
retornam `400`. Somente linhas de KYC.
schema:
type: string
enum:
- ID_VERIFICATION
- FACE_MATCH
- AGE_ESTIMATION
- FACE_SEARCH
- POA
- AML
- KYB_REGISTRY
- PASSIVE_LIVENESS
- DATABASE_VALIDATION
- PHONE_VERIFICATION
- EMAIL_VERIFICATION
example: AML
- name: screened_full_name
in: query
required: false
description: >-
Busca por nome sem distinção de acentos nos dados analisados por AML
e por validação de banco de dados. Quando combinada com
`api_service=AML` ou `api_service=DATABASE_VALIDATION`, a busca fica
restrita aos dados analisados desse recurso. Somente linhas de KYC.
schema:
type: string
example: Jane Doe
- name: warning
in: query
required: false
description: >-
Códigos de risco de aviso separados por vírgula; retorna as sessões
que geraram qualquer um deles (por exemplo, `POSSIBLE_FRAUD`). Os
códigos de risco estão listados por recurso na [documentação de
avisos](/pt-br/integration/webhooks). Aplica-se às linhas de KYC e,
com códigos de aviso de empresas, às linhas de KYB.
schema:
type: string
example: POSSIBLE_FRAUD
- name: status_initialized_as_in_review
in: query
required: false
description: >-
Quando `true`, apenas sessões cuja decisão caiu inicialmente em `In
Review` (útil para auditar o volume de revisão manual). Somente
linhas de KYC.
schema:
type: boolean
example: true
- name: is_kyc_to_be_reviewed
in: query
required: false
description: >-
`true` retorna as sessões cuja verificação de documento está
sinalizada para revisão manual; `false` retorna as sessões com a
verificação de documento explicitamente não sinalizada. Omita para
desativar. Apenas linhas de KYC.
schema:
type: boolean
example: true
- name: euuid
in: query
required: false
description: >-
Filtra pelo euuid do usuário final (UUID atribuído ao usuário em
verificação, usado pelos deep links do Console). Deve ser um UUID
válido; valores malformados retornam um erro de campo 400. Somente
linhas de KYC.
schema:
type: string
format: uuid
example: 0f8fad5b-d9cb-469f-a165-70867728950e
- name: organization_name
in: query
required: false
description: >-
Nomes de organização separados por vírgula. Voltado ao Console; com
uma chave de API (já restrita a uma aplicação), corresponde apenas
ao nome da sua própria organização.
schema:
type: string
example: Acme Inc
responses:
'200':
description: >-
Lista paginada de sessões. Os itens de `results` são linhas KYC,
linhas KYB ou ambas, dependendo de `session_kind`; diferencie-os
pelo campo `session_kind` de cada linha.
content:
application/json:
schema:
type: object
required:
- count
- next
- previous
- results
properties:
count:
type: integer
description: >-
Número de sessões que correspondem aos filtros: exato até
100 e limitado a 100 acima disso, portanto não o use como
total. Use `next` para saber se existem mais páginas. Para
`session_kind=all`, é a soma dos dois tipos, cada um
limitado a 100.
example: 2
next:
type: string
format: uri
nullable: true
description: >-
URL absoluta da próxima página, ou `null` na última
página.
example: >-
https://verification.didit.me/v3/sessions/?limit=20&offset=20
previous:
type: string
format: uri
nullable: true
description: >-
URL absoluta da página anterior, ou `null` na primeira
página.
example: null
results:
type: array
description: >-
Linhas de sessões, das mais recentes para as mais antigas.
Com `session_kind=all`, as linhas KYC vêm primeiro e
depois as linhas KYB.
items:
oneOf:
- $ref: '#/components/schemas/UserSessionListItem'
- $ref: '#/components/schemas/BusinessSessionListItem'
discriminator:
propertyName: session_kind
mapping:
user: '#/components/schemas/UserSessionListItem'
business: '#/components/schemas/BusinessSessionListItem'
examples:
KYC sessions (default):
summary: session_kind=user - uma sessão concluída e uma não iniciada
value:
count: 2
next: null
previous: null
results:
- session_id: 5b3720ed-d429-42ef-b67f-37ea805f48ee
session_kind: user
session_number: 720
session_url: https://verify.didit.me/session/CuXoBYCYVO5Y
portrait_image: >-
https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=...
document_type: Passport
full_name: Jane Marie Doe
country: ESP
status: Approved
vendor_data: your-user-id-123
didit_internal_id: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147
created_at: '2026-06-09T12:26:54.328364Z'
features:
- feature: ID_VERIFICATION
status: Approved
- feature: LIVENESS
status: Approved
- feature: FACE_MATCH
status: Approved
- feature: AML
status: Approved
- feature: IP_ANALYSIS
status: Approved
phone_number:
number: '+14155552671'
is_verified: true
email_address:
email: jane@example.com
is_verified: true
additional_details:
aml:
total_hits: 0
entity_type: person
is_adverse_media_fetched: false
liveness:
method: PASSIVE
score: 0.98
face_match:
score: 0.95
- session_id: 038ad62f-5ebd-46c2-afe9-4b2956bf687f
session_kind: user
session_number: 719
session_url: https://verify.didit.me/session/7RGKiO6ioGH6
portrait_image: null
document_type: null
full_name: null
country: null
status: Not Started
vendor_data: your-user-id-124
didit_internal_id: eb4e679d-ca4b-461f-9685-687bac29ebdb
created_at: '2026-06-09T08:02:23.343053Z'
features:
- feature: ID_VERIFICATION
status: Not Finished
- feature: LIVENESS
status: Not Finished
- feature: FACE_MATCH
status: Not Finished
- feature: AML
status: Not Finished
- feature: IP_ANALYSIS
status: Not Finished
phone_number: null
email_address: null
additional_details: null
Mixed KYC + KYB (session_kind=all):
summary: session_kind=all - linha de KYC seguida de uma linha de KYB
value:
count: 2
next: null
previous: null
results:
- session_id: 5b3720ed-d429-42ef-b67f-37ea805f48ee
session_kind: user
session_number: 720
session_url: https://verify.didit.me/session/CuXoBYCYVO5Y
portrait_image: null
document_type: Identity Card
full_name: Jane Marie Doe
country: ESP
status: In Review
vendor_data: your-user-id-123
didit_internal_id: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147
created_at: '2026-06-09T12:26:54.328364Z'
features:
- feature: ID_VERIFICATION
status: In Review
- feature: LIVENESS
status: Approved
phone_number: null
email_address: null
additional_details:
liveness:
method: PASSIVE
score: 0.98
- session_id: 8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52
session_kind: business
session_number: 42
status: Approved
vendor_data: your-company-id-77
created_at: '2026-06-08T09:14:02.118450Z'
workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab
workflow_type: kyb
workflow_label: Standard KYB
company_name: Acme Holdings S.L.
registration_number: B12345678
country: ES
'301':
description: >-
Redirecionamento para a URL canônica com barra final. Retornado
quando o caminho da requisição é `/v3/sessions` (sem barra final); o
cabeçalho `Location` aponta para `/v3/sessions/` com a query string
preservada. Clientes GET normalmente seguem o redirecionamento
automaticamente.
'400':
description: >-
Parâmetro de consulta inválido. O corpo é um objeto indexado pelo
parâmetro problemático.
content:
application/json:
examples:
Invalid session_kind:
summary: session_kind não é nenhum de user/business/all
value:
session_kind: Must be "user", "business", or "all".
Invalid date:
summary: date_from/date_to com formato inválido
value:
date_from:
- Enter a valid date.
Invalid didit_internal_id:
summary: didit_internal_id não é um UUID
value:
didit_internal_id:
- Enter a valid UUID.
Invalid api_service:
summary: api_service não está entre as opções permitidas
value:
api_service:
- >-
Select a valid choice. FOO is not one of the available
choices.
'403':
description: >-
Chave de API ausente, malformada ou revogada. Uma chave ausente
retorna `403`; uma chave incorreta, revogada ou expirada retorna
`401`.
**Aplicação excluída:** por alguns minutos após a exclusão de uma
aplicação, uma requisição feita com uma de suas chaves de API pode
responder `{"detail": "This application was deleted.", "code":
"application_deleted"}`. Não tente novamente: a aplicação e suas
chaves de API não existem mais. Passados esses minutos, a chave é
recusada como qualquer outra chave inválida.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: You do not have permission to perform this action.
code:
type: string
description: >-
Motivo legível por máquina, presente apenas em algumas
falhas. `application_deleted`: a chave de API pertence a
uma aplicação que foi excluída.
example: application_deleted
required:
- detail
examples:
Forbidden:
summary: x-api-key ausente ou inválido
value:
detail: You do not have permission to perform this action.
ApplicationDeleted:
summary: Chave de API de uma aplicação excluída
value:
detail: This application was deleted.
code: application_deleted
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -s
'https://verification.didit.me/v3/sessions/?status=Approved,In%20Review&date_from=2026-06-01&limit=20'
\
-H 'x-api-key: YOUR_API_KEY'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
for item in client.sessions.list():
print(item)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
for await (const item of didit.sessions.list()) {
console.log(item);
}
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListAutoPaging(ctx, didit.SessionsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}"
- lang: java
label: Java
source: |-
import me.didit.Didit;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
for (var item : client.sessions().list()) {
System.out.println(item);
}
- lang: php
label: PHP
source: |-
sessions->list() as $item) {
print_r($item);
}
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
didit.sessions.list.auto_paging_each do |item|
puts item.to_h
end
- lang: csharp
label: .NET
source: |-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
await foreach (var item in await client.Sessions.ListAsync())
{
Console.WriteLine(JsonSerializer.Serialize(item));
}
components:
schemas:
UserSessionListItem:
title: 'KYC session row (session_kind: user)'
type: object
description: >-
Linha de resumo de uma sessão de Verificação de usuários (KYC). Os
campos de identidade (`full_name`, `country`, `document_type`,
`portrait_image`, campos de contato) são preenchidos progressivamente à
medida que o usuário conclui as etapas de verificação e ficam `null` até
que a etapa correspondente termine. Os campos restringidos pela
configuração de atributos de resposta do fluxo também são retornados
como `null`.
required:
- session_id
- session_kind
- session_number
- session_url
- portrait_image
- document_type
- full_name
- country
- status
- vendor_data
- didit_internal_id
- created_at
- features
- phone_number
- email_address
- additional_details
properties:
session_id:
type: string
format: uuid
description: >-
Identificador único da sessão de verificação. Use-o com `GET
/v3/session/{sessionId}/decision/` para obter o payload completo da
decisão.
example: 5b3720ed-d429-42ef-b67f-37ea805f48ee
session_kind:
type: string
enum:
- user
description: >-
Discriminador de linha. Sempre `"user"` para linhas de KYC; as
linhas de Verificação de empresas (KYB) têm `"business"` e uma
estrutura diferente.
example: user
session_number:
type: integer
description: >-
Número sequencial de fácil leitura da sessão dentro da sua
aplicação. Também é considerado pelo parâmetro `search`.
example: 720
session_url:
type: string
nullable: true
description: >-
URL de verificação hospedada que o usuário final abre para concluir
o fluxo. `null` quando a sessão não tem URL hospedada.
example: https://verify.didit.me/session/CuXoBYCYVO5Y
portrait_image:
type: string
nullable: true
description: >-
URL temporária (pré-assinada) do melhor retrato disponível: a foto
do chip NFC quando disponível; caso contrário, o retrato do
documento de identidade; caso contrário, a imagem de referência da
prova de vida. `null` até que um deles exista. Faça o download
imediatamente, pois o link expira.
example: >-
https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=...
document_type:
type: string
nullable: true
enum:
- Passport
- Identity Card
- Driver's License
- Residence Permit
- Health Insurance Card
- Tax Card
description: >-
Tipo legível do documento de identidade verificado. `null` antes de
a verificação do documento ser concluída, e também `null` após a
conclusão quando o código verificado não tem um nome de exibição
mapeado (`SSC`, `WP`, `VISA`, `PSC`, `BC`, `OTHER`). Observação: o
parâmetro de consulta `document_type` filtra por códigos curtos
(`P`, `ID`, `DL`, `RP`, ...), não por esses valores de exibição.
example: Passport
full_name:
type: string
nullable: true
description: >-
Melhor nome completo disponível para a sessão, determinado nesta
ordem: OCR do documento de identidade, dados verificados na análise
AML, dados verificados na validação de banco de dados, documento de
comprovante de endereço e, por fim, os dados esperados informados na
criação da sessão. `null` quando nenhum estiver disponível ainda.
example: Jane Marie Doe
country:
type: string
nullable: true
description: >-
País ISO 3166-1 alpha-3 associado à sessão, definido nesta ordem:
estado emissor do documento de identidade, estado emissor da
validação de banco de dados, estado emissor do comprovante de
endereço, dados esperados e, por fim, o país do telefone verificado.
Pode ser diferente da nacionalidade.
example: ESP
status:
type: string
enum:
- Not Started
- In Progress
- Approved
- Declined
- In Review
- Expired
- Abandoned
- Kyc Expired
- Resubmitted
- Awaiting User
description: >-
Status geral da sessão. Consulte a página [Status de
verificação](/pt-br/integration/verification-statuses) para ver o
ciclo de vida.
example: Approved
vendor_data:
type: string
nullable: true
description: >-
Seu próprio identificador para o usuário final, retornado exatamente
como enviado na criação da sessão.
example: your-user-id-123
didit_internal_id:
type: string
format: uuid
nullable: true
description: >-
Identificador interno da Didit para o perfil de usuário verificado
associado a esta sessão. É estável entre várias sessões do mesmo
usuário e pode ser filtrado pelo parâmetro de consulta
`didit_internal_id`.
example: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147
created_at:
type: string
format: date-time
description: Timestamp em UTC de quando a sessão foi criada.
example: '2026-06-09T12:26:54.328364Z'
features:
type: array
description: >-
Status por recurso de cada etapa de verificação configurada no fluxo
da sessão, na ordem do fluxo.
items:
type: object
required:
- feature
- status
properties:
feature:
type: string
enum:
- ID_VERIFICATION
- NFC
- LIVENESS
- FACE_MATCH
- POA
- QUESTIONNAIRE
- EMAIL_VERIFICATION
- PHONE
- AML
- IP_ANALYSIS
- AGE_ESTIMATION
- DATABASE_VALIDATION
- GEOLOCATION
description: Identificador do recurso de verificação.
example: ID_VERIFICATION
status:
type: string
enum:
- Not Finished
- Approved
- Declined
- In Review
- Resub Requested
description: >-
Status deste recurso. `Not Finished` até que a etapa seja
concluída.
example: Approved
phone_number:
type: object
nullable: true
description: >-
Telefone associado à sessão: o telefone verificado quando a
verificação de telefone foi executada; caso contrário, o telefone de
contato informado na criação da sessão. `null` quando nenhum dos
dois existe.
required:
- number
- is_verified
properties:
number:
type: string
description: Número de telefone no formato E.164.
example: '+14155552671'
is_verified:
type: boolean
description: >-
`true` apenas quando o recurso de verificação de telefone
aprovou este número.
example: true
email_address:
type: object
nullable: true
description: >-
E-mail associado à sessão: o e-mail verificado quando a verificação
de e-mail foi executada; caso contrário, o e-mail de contato
informado na criação da sessão. `null` quando nenhum dos dois
existe.
required:
- email
- is_verified
properties:
email:
type: string
format: email
example: jane@example.com
is_verified:
type: boolean
description: >-
`true` apenas quando o recurso de verificação de e-mail aprovou
este endereço.
example: true
additional_details:
type: object
nullable: true
description: >-
Dados extras compactos por recurso. Somente os recursos que
produziram dados aparecem como chaves; `null` quando nenhum recurso
produziu dados extras. Os campos excluídos pela configuração de
atributos de resposta do fluxo são omitidos.
properties:
aml:
type: object
description: Presente quando a análise AML foi executada.
properties:
total_hits:
type: integer
description: Número de ocorrências da Análise AML.
example: 0
entity_type:
type: string
description: Tipo de entidade analisada.
example: person
is_adverse_media_fetched:
type: boolean
example: false
screened_data:
type: object
description: >-
Subconjunto dos dados que foram analisados. Somente chaves
não vazias são incluídas.
properties:
nationality:
type: string
example: ESP
document_number:
type: string
example: XX1234567
date_of_birth:
type: string
example: '1990-05-21'
database_validation:
type: object
description: Presente quando a validação de banco de dados foi executada.
properties:
validation_type:
type: string
example: DOCUMENT_VALIDATION
match_type:
type: string
example: FULL_MATCH
identification_number:
type: string
description: >-
Número fiscal, pessoal ou de documento que foi validado (o
primeiro disponível).
example: 12345678Z
poa:
type: object
description: Presente quando o comprovante de endereço foi executado.
properties:
document_type:
type: string
example: UTILITY_BILL
issuer:
type: string
example: Energy Co
address:
type: string
example: Calle Mayor 1, 28013 Madrid
name_on_document:
type: string
example: Jane Marie Doe
liveness:
type: object
description: Presente quando uma verificação de prova de vida foi executada.
properties:
method:
type: string
example: PASSIVE
score:
type: number
description: >-
Pontuação de confiança da prova de vida, arredondada para 2
casas decimais.
example: 0.98
face_match:
type: object
description: Presente quando a correspondência facial foi executada.
properties:
score:
type: number
description: >-
Pontuação de similaridade da correspondência facial,
arredondada para 2 casas decimais.
example: 0.95
source_image:
type: string
description: URL temporária (pré-assinada) da imagem facial de origem.
example: https:///faces/source.jpg?X-Amz-Expires=3600&...
target_image:
type: string
description: URL temporária (pré-assinada) da imagem facial de destino.
example: https:///faces/target.jpg?X-Amz-Expires=3600&...
phone_verification:
type: object
description: Presente quando a verificação de telefone foi executada.
properties:
country_code:
type: string
description: País do número de telefone, no formato ISO 3166-1 alpha-2.
example: US
is_temporary:
type: boolean
example: false
is_ported:
type: boolean
example: false
is_blocked:
type: boolean
example: false
email_verification:
type: object
description: Presente quando a verificação de e-mail foi executada.
properties:
is_breached:
type: boolean
example: false
is_disposable:
type: boolean
example: false
is_undeliverable:
type: boolean
example: false
is_blocklisted:
type: boolean
example: false
assignee:
type: object
nullable: true
description: >-
O revisor do Console a quem a sessão está atribuída, ou `null`
quando ninguém a detém.
properties:
email:
type: string
format: email
assigned_at:
type: string
format: date-time
nullable: true
waiting_since:
type: string
format: date-time
nullable: true
description: >-
Quando a sessão começou a aguardar revisão. `null`, a menos que a
sessão esteja `In Review`.
sla_due_at:
type: string
format: date-time
nullable: true
description: >-
Quando a revisão vence, com base no prazo de revisão definido para
sua aplicação no Console. `null`, a menos que a sessão esteja `In
Review` e um prazo esteja definido.
top_warnings:
type: array
description: >-
No máximo alguns dos avisos mais importantes da sessão, para uma
triagem rápida. A lista completa está na decisão.
items:
type: object
properties:
risk:
type: string
description: Código do aviso, por exemplo `FACE_MATCH_LOW_SIMILARITY`.
feature:
type: string
description: O recurso que o gerou.
log_type:
type: string
nullable: true
description: '`error` ou `warning`; `null` para uma entrada legada.'
short_description:
type: string
warnings_count:
type: integer
description: Número de avisos na sessão.
BusinessSessionListItem:
title: 'KYB session row (session_kind: business)'
type: object
description: >-
Linha de resumo de uma sessão de Verificação de empresas (KYB).
Retornada somente quando `session_kind` é `business` ou `all`.
required:
- session_id
- session_kind
- session_number
- status
- vendor_data
- created_at
- workflow_id
- workflow_type
- workflow_label
- company_name
- registration_number
- country
properties:
session_id:
type: string
format: uuid
description: Identificador único da sessão de verificação de empresas.
example: 8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52
session_kind:
type: string
enum:
- business
description: Discriminador de linha. Sempre `"business"` para linhas de KYB.
example: business
session_number:
type: integer
description: >-
Número sequencial de fácil leitura da sessão de empresa dentro da
sua aplicação. Numerado de forma independente das sessões de KYC.
example: 42
status:
type: string
enum:
- Not Started
- In Progress
- Approved
- Declined
- In Review
- Expired
- Abandoned
- Kyc Expired
- Resubmitted
- Awaiting User
description: >-
Status geral da sessão. Consulte a página [Status de
verificação](/pt-br/integration/verification-statuses).
example: Approved
vendor_data:
type: string
nullable: true
description: >-
Seu próprio identificador para a empresa, retornado exatamente como
enviado na criação da sessão.
example: your-company-id-77
created_at:
type: string
format: date-time
description: Timestamp em UTC de quando a sessão foi criada.
example: '2026-06-08T09:14:02.118450Z'
workflow_id:
type: string
format: uuid
nullable: true
description: >-
Identificador do fluxo de verificação (workflow) com o qual esta
sessão foi criada.
example: 9f9b1234-aaaa-bbbb-cccc-1234567890ab
workflow_type:
type: string
nullable: true
description: Tipo de fluxo. `kyb` para fluxos de empresas.
example: kyb
workflow_label:
type: string
nullable: true
description: Nome de exibição do fluxo.
example: Standard KYB
company_name:
type: string
nullable: true
description: >-
Nome da empresa sendo verificada, obtido da empresa do registro
vinculada à sessão. `null` até que uma empresa seja selecionada.
example: Acme Holdings S.L.
registration_number:
type: string
nullable: true
description: >-
Número de registro da empresa obtido da empresa do registro
vinculada à sessão.
example: B12345678
country:
type: string
nullable: true
description: Código do país da empresa do registro vinculada à sessão.
example: ES
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.