> ## 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. # Listar sessões API: filtrar sessões KYC e KYB > Liste sessões de verificação com GET /v3/sessions/ e filtre por tipo, estado, fluxo e dados do fornecedor. API KYC e KYB unificada da Didit. 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ões a devolver:| Valor | Devolve | | - | - | | `user` (predefinido) | Apenas sessões de Verificação de utilizadores (KYC). **Comportamento compatível com versões anteriores**: omita `session_kind` para obter este resultado. | | `business` | Apenas sessões de Verificação de empresas (KYB). | | `all` | Sessões de Verificação de utilizadores e de Verificação de empresas, concatenadas. |Cada linha da resposta inclui `session_kind: "user" | "business"`, para que o seu cliente possa tratar a estrutura de cada linha de acordo com o tipo.## Filtros comunsEstes filtros aplicam-se aos dois tipos (os filtros exclusivos de utilizadores são ignorados quando `session_kind=business`, e vice-versa):| Parâmetro de consulta | Descrição | | - | - | | `session_kind` | `user`, `business` ou `all`. Predefinido `user`. | | `vendor_data` | Correspondência exata com o seu identificador. | | `status` | Um ou mais estados, separados por vírgulas, escritos exatamente como a API os devolve: `Approved`, `Declined`, `In Review`, e assim por diante (ver [Estados de verificação](https://docs.didit.me/pt/integration/verification-statuses.md)). | | `workflow_id` | Filtra pelo fluxo utilizado. | | `country` | Filtro por código de país (utilizadores: `issuing_states`, empresas: `country_code`). | | `date_from`, `date_to` | Intervalo de datas de criação (ISO 8601). | | `tags` | IDs de etiquetas separados por vírgulas. Devolve as sessões que tenham qualquer uma delas. | | `decided_from`, `decided_to` | Datas e horas ISO 8601. Devolve as sessões cujo estado foi alterado pela última vez nesse intervalo (início inclusive, fim exclusivo). Usam a data e hora da última alteração de estado, não a data de criação. | | `search` | Uma referência completa tal como é apresentada, como `S-0001` ou `B-0001`, corresponde apenas a esse número e tipo de sessão, ignorando zeros à esquerda e diferenças entre maiúsculas e minúsculas. Qualquer outro valor é pesquisado nos campos existentes de nome, contacto, documento, número de registo e `vendor_data`. |## Exemplos> [tab] Listar sessões de Verificação de utilizadores (KYC) (predefiniçã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 ambos os 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" > ``` > > Devolve linhas de Verificação de utilizadores e de Verificação de empresas num único array `results`. Os consumidores devem tratar cada linha de acordo com `session_kind`. > > > [!NOTE] > > > > O modo `all` concatena os resultados em vez de os intercalar por data e hora. Para consultas de grande volume com tipos misturados, chame cada tipo separadamente e junte os resultados do lado do cliente.## A estrutura das linhas varia por tipoAs linhas de Verificação de utilizadores (KYC) incluem: `portrait_image`, `document_type`, `full_name`, `country` (estado emissor), `phone_number`, `email_address` e alguns campos de revisão: `assignee` (o revisor da Console que detém a sessão, ou `null`), `waiting_since` e `sla_due_at` (definidos apenas enquanto a sessão estiver `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).Ambos incluem: `session_id`, `session_kind`, `session_number`, `status`, `vendor_data`, `created_at`.Consulte a [visão geral das sessões](https://docs.didit.me/pt/sessions-api/overview.md) para a matriz completa de funcionalidades.## PaginaçãoA paginação usa `limit` (predefinido `50`) e `offset` (predefinido `0`), com URLs absolutas `next` e `previous` na resposta. Ambos os parâmetros aceitam valores até `1000000`; um valor superior devolve `400`.`count` é exato até `100` e fica em `100` acima desse valor, por isso não o use como total. Continue a pedir a URL `next` até que seja `null`. Com `session_kind=all`, `count` é a soma dos dois tipos, limitada a `100` em cada um.## Relacionados- [Visão geral das sessões](https://docs.didit.me/pt/sessions-api/overview.md) - [Obter sessão](https://docs.didit.me/pt/sessions-api/retrieve-session.md): decisão completa de uma única linha - [Visão geral das empresas](https://docs.didit.me/pt/entities/businesses/overview.md): a entidade Empresa agregada nas sessões - [Visão geral dos utilizadores](https://docs.didit.me/pt/entities/users/overview.md): a entidade Utilizador agregada nas sessões ## OpenAPI ````yaml pt/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: >- Devolve uma lista paginada de sessões de verificação para a aplicação identificada pela sua chave de API, as mais recentes primeiro (`session_number` descendente). **URL canónico:** a rota é `/v3/sessions/` (barra final). Os pedidos para `/v3/sessions` sem a barra recebem um redirecionamento `301` para o URL com barra preservando a cadeia de consulta; a maioria dos clientes HTTP segue-o de forma transparente em GET. **Quando utilizar este endpoint vs webhooks.** Utilize este endpoint para painéis, pesquisa de back-office, reconciliação e exportações em lote. Não faça polling deste endpoint para acompanhar o progresso de verificações individuais - em vez disso, configure [webhooks](/pt/integration/webhooks), que enviam eventos `status.updated` no momento em que uma sessão é alterada. Para obter o resultado completo de uma sessão, chame `GET /v3/session/{sessionId}/decision/`. **Sessões de KYC e KYB.** `session_kind` seleciona quais os tipos listados: - `user` (predefinição) - apenas sessões de Verificação de utilizadores (KYC). Comportamento retrocompatível. - `business` - apenas sessões de Verificação de empresas (KYB). As linhas têm uma estrutura diferente e menor (consulte o esquema da resposta). - `all` - ambos os tipos numa única resposta: a página de KYC e a página de KYB para os mesmos `limit`/`offset` são concatenadas em `results` (linhas de KYC primeiro), pelo que uma página pode conter até `2 x limit` linhas. `count` é a soma de ambos os tipos e `next`/`previous` refletem a paginação do lado do KYC. Para uma paginação estrita de dados mistos, chame `user` e `business` separadamente. Cada linha inclui um discriminador `session_kind` (`"user"` ou `"business"`). **Paginação.** Paginação padrão limit/offset: `limit` (predefinição 50) e `offset` (predefinição 0), com URLs de páginas pré-construídas `next`/`previous`. Para linhas de KYC, `count` é exato. Para linhas de KYB, `count` é calculado com uma análise delimitada e está limitado a 100 - quando houver mais de 100 correspondências, mantém-se em 100, pelo que deve iterar utilizando `next` (ou verificando se foi devolvida uma página completa) em vez de calcular o total de páginas a partir de `count`. **Semântica dos filtros.** Todos os filtros combinam-se com AND e aplicam-se a linhas de KYC. Quando `session_kind` for `business` ou `all`, o lado de KYB respeita os parâmetros partilhados `vendor_data`, `status`, `workflow_id`, `country` (código do país do registo da empresa), `date_from`, `date_to`, `search` (nome da empresa, número de registo — introduza números de registo sem separadores, por exemplo `DPC001` e não `DPC-001` —, vendor_data, número de sessão ou UUID da sessão), `warning` e `organization_name`; os restantes filtros exclusivos de KYC são ignorados para linhas de KYB. Parâmetros separados por vírgulas (`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 - utilize `search` para correspondência parcial. Valores desconhecidos em filtros de lista simplesmente não devolvem linhas (sem erro); valores tipados malformados (`date_from`, `date_to`, `didit_internal_id`, `api_service`, `session_kind`) devolvem `400` com um objeto de erro por campo. **Pesquisa.** `search` adapta-se à entrada: um UUID completo procura por `session_id`; dígitos (com `+ - . space` opcionais) correspondem ao prefixo do número da sessão, números de documento/identificação pessoal, prefixo de número de telefone ou `vendor_data`; valores contendo `@` correspondem a prefixos de e-mail; qualquer outro texto corresponde a nomes (insensível a acentos) e `vendor_data`. Não é aplicado nenhum limite de pedidos fixo por endpoint, mas mantenha o polling de listas pouco frequente e confie em webhooks para atualizações em tempo real. operationId: get_v3_sessions parameters: - name: session_kind in: query required: false description: >- Qual o tipo de sessões a listar: `user` (apenas KYC, predefinição), `business` (apenas KYB) ou `all` (ambas, concatenadas - consulte a descrição para a semântica de paginação combinada). A correspondência não diferencia maiúsculas de minúsculas (`BUSINESS` funciona); qualquer valor que não seja uma variante de maiúsculas/minúsculas de `user`/`business`/`all` devolve `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 valor predefinido é 50. schema: type: integer default: 50 minimum: 1 maximum: 1000000 example: 20 - name: offset in: query required: false description: >- Número de linhas a ignorar antes da primeira linha devolvida. O valor predefinido é 0. Prefira seguir os 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írgulas de estados de sessão a incluir, por exemplo, `Approved,In Review`. Os valores são sensíveis a maiúsculas e minúsculas; consulte [Estados de verificação](/pt/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 enviou na criação da sessão (o seu próprio identificador de utilizador/empresa). Para correspondências parciais, utilize `search` em alternativa. schema: type: string example: your-user-id-123 - name: search in: query required: false description: >- Uma referência completa apresentada, como `S-0001` (utilizador) ou `B-0001` (empresa), corresponde apenas a esse número e tipo de sessão; os zeros à esquerda e maiúsculas/minúsculas não afetam a correspondência. Pesquisa inteligente de texto livre. Um UUID completo corresponde a `session_id`; uma entrada numérica corresponde ao prefixo do número da sessão, números de documento/pessoais, prefixo de telefone ou `vendor_data`; entradas que contenham `@` correspondem a prefixos de e-mail; outro texto corresponde a nomes (não sensível a acentos) e a `vendor_data`. O texto livre que contenha dígitos corresponde adicionalmente a campos de pesquisa de número de documento/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 fluxos separados por vírgulas (encontre-os na página Fluxos na Consola). 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: >- Apenas sessões criadas nesta data ou após a mesma (UTC), formato `YYYY-MM-DD`. Datas malformadas devolvem `400`. schema: type: string format: date example: '2026-06-01' - name: date_to in: query required: false description: >- Apenas sessões criadas até esta data (UTC), 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), pelo que deve utilizar 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 etiquetas separados por vírgulas (`tags` da sua aplicação). Devolve as sessões que contenham qualquer uma delas. Os IDs que não sejam UUIDs válidos são ignorados e, quando nenhum for 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. Devolve as sessões cujo estado mudou pela última vez nesse momento ou depois. Filtra pela hora da última alteração de estado, não pela hora de criação. - name: decided_to in: query required: false schema: type: string format: date-time description: >- Data e hora ISO 8601. Devolve as sessões cujo estado mudou pela última vez antes dessa data. Combine com `decided_from` para um intervalo semiaberto. - name: country in: query required: false description: >- Filtro de países separados por vírgulas. Para linhas KYC: códigos ISO 3166-1 alfa-3 do país emissor do documento de identificação (por exemplo, `ESP,USA`), que podem diferir da nacionalidade. Para linhas KYB: o código de país do registo comercial da empresa. schema: type: string example: ESP,USA - name: document_type in: query required: false description: >- Códigos de tipo de documento de identificação verificados na sessão, separados por vírgulas (apenas linhas KYC): `P` (Passaporte), `ID` (Cartão de Cidadão / Bilhete de Identidade), `DL` (Carta de Condução), `RP` (Título de Residência), `SSC` (Cartão de Segurança Social), `HIC` (Cartão de Seguro de Saúde), `WP` (Autorização de Trabalho), `TC` (Cartão de Contribuinte), `VISA`, `PSC` (Cartão de Serviços Públicos), `BC` (Certidão de Nascimento), `OTHER`. Tenha em atenção que o campo de resposta `document_type` contém o nome de apresentação, não o código. schema: type: string example: P,ID - name: document_name in: query required: false description: >- Nomes exatos de documentos; podem ser transmitidos vários nomes separados por vírgulas, mas o valor só é dividido por vírgulas quando contém mais do que um separador ` - ` (um nome isolado com uma vírgula incorporada é correspondido por inteiro). Os nomes são conforme reconhecidos pela verificação de documentos (frente ou verso), por ex., `Spain - Id Card (2021)`. Apenas 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írgulas (para documentos emitidos por região, como cartas de condução dos EUA). Apenas linhas KYC. schema: type: string example: CA,TX - name: didit_internal_id in: query required: false description: >- Filtrar pelo identificador interno de utilizador da Didit (o campo de resposta `didit_internal_id`) para listar todas as sessões de um utilizador verificado. Tem de ser um UUID válido; valores malformados devolvem `400`. Apenas 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írgulas: `API`, `HOSTED`, `MIGRATED`. O valor especial `ALL` (ou omitir o parâmetro) desativa o filtro. Apenas linhas de KYC. schema: type: string example: HOSTED - name: api_service in: query required: false description: >- Filtrar sessões da API autónoma por serviço. Valores inválidos devolvem `400`. Apenas 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: >- Pesquisa de nomes insensível a acentos nos dados analisados por AML e validação de base de dados. Quando combinada com `api_service=AML` ou `api_service=DATABASE_VALIDATION`, a pesquisa fica restrita aos dados analisados dessa funcionalidade. Apenas 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írgulas; devolve as sessões que geraram qualquer um deles (por exemplo, `POSSIBLE_FRAUD`). Os códigos de risco estão listados por funcionalidade na [documentação de avisos](/pt/integration/webhooks). Aplica-se a linhas de KYC e, com códigos de aviso empresariais, a linhas de KYB. schema: type: string example: POSSIBLE_FRAUD - name: status_initialized_as_in_review in: query required: false description: >- Quando `true`, apenas as sessões cuja decisão inicialmente terminou em `In Review` (útil para auditar o volume de revisão manual). Apenas linhas de KYC. schema: type: boolean example: true - name: is_kyc_to_be_reviewed in: query required: false description: >- `true` devolve sessões cuja verificação de documentos está sinalizada para revisão manual; `false` devolve sessões com verificação de documentos explicitamente não sinalizada. Omita para desativar. Apenas linhas de KYC. schema: type: boolean example: true - name: euuid in: query required: false description: >- Filtrar pelo euuid do utilizador final (UUID atribuído ao utilizador em verificação, utilizado pelas ligações diretas da Console). Tem de ser um UUID válido; valores mal formatados devolvem um erro de campo 400. Apenas 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ções separados por vírgulas. Orientado para a consola; 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 de sessões paginada. Os itens de `results` são linhas de KYC, linhas de KYB, ou ambos, dependendo de `session_kind`; diferencie através do 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 além disso, pelo que não deve ser usado como total. Use `next` para saber se existem mais páginas. Para `session_kind=all`, é a soma de ambos os tipos, cada um limitado a 100. example: 2 next: type: string format: uri nullable: true description: >- URL absoluto da página seguinte, 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 absoluto da página anterior, ou `null` na primeira página. example: null results: type: array description: >- Linhas de sessão, as mais recentes primeiro. Com `session_kind=all`, as linhas KYC surgem primeiro, seguidas pelas 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 sessão 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 por 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 o URL canónico com barra final. Devolvido quando o caminho do pedido é `/v3/sessions` (sem barra final); o cabeçalho `Location` aponta para `/v3/sessions/` preservando a cadeia de consulta. Os clientes GET normalmente seguem-no automaticamente. '400': description: >- Parâmetro de consulta inválido. O corpo é um objeto com uma chave correspondente ao parâmetro problemático. content: application/json: examples: Invalid session_kind: summary: session_kind não é um dos valores user/business/all value: session_kind: Must be "user", "business", or "all". Invalid date: summary: date_from/date_to mal formatados 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 em falta, malformada ou revogada. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`. **Aplicação eliminada:** durante alguns minutos após uma aplicação ser eliminada, um pedido efetuado com uma das suas chaves de API pode responder `{"detail": "This application was deleted.", "code": "application_deleted"}`. Não tente novamente: a aplicação e as suas chaves de API já não existem. Decorridos 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 eliminada. example: application_deleted required: - detail examples: Forbidden: summary: x-api-key em falta ou inválido value: detail: You do not have permission to perform this action. ApplicationDeleted: summary: Chave de API de uma aplicação eliminada 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 para uma sessão de Verificação de utilizadores (KYC). Os campos de identidade (`full_name`, `country`, `document_type`, `portrait_image`, campos de contacto) são preenchidos progressivamente à medida que o utilizador conclui os passos de verificação, ficando com valor `null` até à conclusão do passo relevante. Os campos restringidos pela configuração de response-attributes do fluxo também são devolvidos 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. Utilize-o com `GET /v3/session/{sessionId}/decision/` para obter o payload de decisão completo. 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 legível da sessão dentro da sua aplicação. Também utilizado pelo parâmetro `search` para fazer correspondências. example: 720 session_url: type: string nullable: true description: >- URL de verificação alojado que o utilizador final abre para concluir o fluxo. `null` quando a sessão não tem URL alojado. example: https://verify.didit.me/session/CuXoBYCYVO5Y portrait_image: type: string nullable: true description: >- URL temporário (pré-assinado) do melhor retrato disponível: a fotografia do chip NFC quando disponível, caso contrário o retrato do documento de identificação, caso contrário a imagem de referência da prova de vida. `null` até que um deles exista. Transfira prontamente; a ligação 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 por humanos do documento de identificação verificado. `null` antes da conclusão da verificação do documento, e também `null` após a conclusão quando o código verificado não tem mapeamento de apresentação (`SSC`, `WP`, `VISA`, `PSC`, `BC`, `OTHER`). Nota: o parâmetro de consulta `document_type` filtra por códigos curtos (`P`, `ID`, `DL`, `RP`, ...), não por estes valores de apresentação. example: Passport full_name: type: string nullable: true description: >- Melhor nome completo disponível para a sessão, resolvido pela ordem: OCR do documento de identificação, dados analisados na triagem AML, dados analisados na validação de base de dados, documento de comprovativo de morada e, em seguida, os detalhes esperados fornecidos na criação da sessão. `null` quando nenhum estiver ainda disponível. example: Jane Marie Doe country: type: string nullable: true description: >- País ISO 3166-1 alfa-3 associado à sessão, resolvido por ordem: estado emissor do documento de identificação, estado emissor da validação de base de dados, estado emissor do comprovativo de morada, detalhes esperados e, por fim, o país do telefone verificado. Pode diferir da nacionalidade. example: ESP status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User description: >- Estado global da sessão. Consulte a página [Estados de verificação](/pt/integration/verification-statuses) para o ciclo de vida. example: Approved vendor_data: type: string nullable: true description: >- O seu próprio identificador para o utilizador final, devolvido exatamente como foi 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 utilizador verificado associado a esta sessão. Estável entre múltiplas sessões do mesmo utilizador; filtrável através do parâmetro de consulta `didit_internal_id`. example: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147 created_at: type: string format: date-time description: Marca temporal UTC da criação da sessão. example: '2026-06-09T12:26:54.328364Z' features: type: array description: >- Estado por funcionalidade para cada passo de verificação configurado no fluxo da sessão, pela 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 da funcionalidade de verificação. example: ID_VERIFICATION status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: >- Estado desta funcionalidade. `Not Finished` até o passo estar concluído. 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 contacto fornecido na criação da sessão. `null` quando nenhum existir. 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 a funcionalidade de verificação de telefone tiver aprovado 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 contacto fornecido na criação da sessão. `null` quando nenhum existe. required: - email - is_verified properties: email: type: string format: email example: jane@example.com is_verified: type: boolean description: >- `true` apenas quando a funcionalidade de verificação de e-mail tiver aprovado este endereço. example: true additional_details: type: object nullable: true description: >- Dados adicionais compactos por funcionalidade. Apenas as funcionalidades que produziram dados aparecem como chaves; `null` quando nenhuma funcionalidade produziu dados adicionais. Os campos excluídos pela configuração dos atributos da resposta do fluxo são omitidos. properties: aml: type: object description: Presente quando a Triagem AML foi executada. properties: total_hits: type: integer description: Número de correspondências de triagem AML. example: 0 entity_type: type: string description: Tipo de entidade submetida a triagem. example: person is_adverse_media_fetched: type: boolean example: false screened_data: type: object description: >- Subconjunto dos dados analisados. Apenas são incluídas chaves não vazias. 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 base 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 do documento que foi validado (primeiro disponível). example: 12345678Z poa: type: object description: >- Presente quando foi efetuada a verificação do comprovativo de morada. 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 a 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 semelhança da correspondência facial, arredondada a 2 casas decimais. example: 0.95 source_image: type: string description: URL temporário (pré-assinado) da imagem facial de origem. example: https:///faces/source.jpg?X-Amz-Expires=3600&... target_image: type: string description: URL temporário (pré-assinado) 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 ISO 3166-1 alfa-2 do número de telefone. 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 da consola ao qual a sessão está atribuída, ou `null` quando não está atribuída a ningué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 deve ser concluída, a partir do prazo de revisão definido para a sua aplicação na Console. `null` a menos que a sessão esteja `In Review` e um prazo esteja definido. top_warnings: type: array description: >- Até alguns dos avisos mais importantes da sessão, para uma vista rápida de triagem. A lista completa está na decisão. items: type: object properties: risk: type: string description: Código de aviso, por exemplo `FACE_MATCH_LOW_SIMILARITY`. feature: type: string description: A funcionalidade 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 para uma sessão de Verificação de empresas (KYB). Devolvida apenas quando `session_kind` for `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 (KYB). 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 legível 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: >- Estado global da sessão. Consulte a página [Estados de verificação](/pt/integration/verification-statuses). example: Approved vendor_data: type: string nullable: true description: >- O seu próprio identificador para a empresa, devolvido exatamente como foi enviado na criação da sessão. example: your-company-id-77 created_at: type: string format: date-time description: Marca temporal UTC da criação da sessão. example: '2026-06-08T09:14:02.118450Z' workflow_id: type: string format: uuid nullable: true description: Identificador do fluxo 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 apresentação do fluxo. example: Standard KYB company_name: type: string nullable: true description: >- Nome da empresa que está a ser verificada, proveniente da empresa do registo associada à sessão. `null` até que uma empresa seja selecionada. example: Acme Holdings S.L. registration_number: type: string nullable: true description: Número de registo da empresa do registo associada à sessão. example: B12345678 country: type: string nullable: true description: Código de país da empresa do registo associada à sessão. example: ES securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.