> ## 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 de questionários KYC com formulários dinâmicos

> Os Questionários da Didit criam formulários KYC com construtor de arrastar e soltar, vários idiomas, lógica condicional e revisão manual. $0.10 por chamada.

Os Questionários da Didit permitem criar formulários estruturados e dinâmicos para coletar informações adicionais dos usuários durante a verificação. Use nosso construtor visual para arrastar e soltar elementos, organizar o conteúdo em seções, localizar os textos para vários idiomas e encaminhar os resultados para revisão manual quando necessário.

Prompt de integração de Questionários
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Questionnaires (custom KYC/KYB forms with conditional logic and manual-review routing) into your app.

\# Delivery mode
Questionnaires are **session-only**. The form is designed in the Business Console (drag-and-drop builder) and bound to a workflow via the QUESTIONNAIRE feature. There is no standalone questionnaire submission API — answers are collected through the hosted Didit flow.

\# Steps
1\. Build the questionnaire in the Business Console (Questionnaires tab). Define sections, fields, conditional visibility, multi-language labels, and **custom status rules** (e.g. "if source_of_funds = 'crypto' set status to In Review").
2\. Add the QUESTIONNAIRE feature to a workflow and select the questionnaire id (POST /v3/workflows/ or the Console).
3\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
4\. Open session.url for the user (or mount the Web/Mobile SDK) — the form renders inside the flow.
5\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

curl (create session):
\```bash
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-1234",
"callback": "https://yourapp.com/post-kyc"
}'
\```

\# Decision surface
The result lands under `questionnaire_responses[]` on the decision payload (one entry per questionnaire node). Each entry includes:
\- `status` — final status for this questionnaire instance (driven by your custom status rules).
\- `answers` — array of { question_id, question_label, value } pairs (or nested sections).
\- `warnings` — any rule-triggered warnings.

\# Status enum (per questionnaire_responses[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.QUESTIONNAIRE)
The dominant risk code is CUSTOM_STATUS_RULE_TRIGGERED — emitted whenever an answer matches a Console-configured rule that escalates the status. The warning's `additional_data` carries the rule id and matched answer so reviewers can see why the session was routed.

Full catalogue: questionnaire warnings are documented inside the report page — see /core-technology/questionnaires/report-questionnaire.

\# Failure modes to handle
\- questionnaire_responses[] empty — user abandoned the form. The session status will reflect "Abandoned"; treat per your retention policy.
\- status="In Review" with CUSTOM_STATUS_RULE_TRIGGERED — answers crossed your manual-review rule; surface the relevant answers in your reviewer UI.
\- status="Declined" — answers crossed a decline rule (e.g. user declared they are a sanctioned-country resident); do not approve.

\# See also
\- Canonical schema: /reference/data-models#questionnaire-response
\- Per-feature report: /core-technology/questionnaires/report-questionnaire
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Paste into

Na lição da Academy sobre como ler o resultado de uma verificação, o capítulo de 11:54 aborda o Document AI e os questionários.[Document AI e questionários — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=714\&rel=0\&playsinline=1)***## Duas formas de criar questionáriosA Didit oferece **duas abordagens distintas** para criar questionários, para que você escolha o nível de complexidade adequado às suas necessidades:![Modos simples e avançado do construtor de questionários KYC da Didit, lado a lado](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-simple-and-complex.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=71d18d67b4684cca46c7809ba43cfcb6)### 1. Modo simples: construtor rápido de formuláriosO **Modo simples** é ideal para criar formulários diretos com rapidez. Use nossa interface intuitiva de arrastar e soltar para adicionar elementos, definir campos obrigatórios e publicar em minutos.![Interface do construtor de formulários de arrastar e soltar do modo simples de questionários da Didit](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-simple.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=8e777d8fc72ca16e8e2deb65a0a66e92)**Ideal para:**- Formulários de coleta rápida de dados
- Pesquisas simples e declarações
- Equipes que estão começando com construtores de formulários
- Questionários em um único idioma**Como funciona:**1) Abra o Construtor de Questionários
2) Arraste elementos da paleta para o formulário
3) Configure cada elemento (rótulo, obrigatório, placeholder)
4) Visualize e publique***### 2. Modo avançado: construtor visual de grafosO **Modo avançado** libera recursos poderosos para cenários complexos de coleta de dados usando um **editor visual baseado em nós**. Crie questionários sofisticados com lógica condicional, caminhos ramificados e controle total sobre o fluxo.![Editor visual de grafos baseado em nós do questionário avançado da Didit, com lógica de ramificação](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-node-based.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=7ff0c1d79f500ed3f78dca4ff89b0698)**Ideal para:**- Questionários multilíngues
- Formulários complexos com ramificações condicionais
- Coleta de dados orientada à conformidade, com caminhos diferentes
- Formulários que exigem fluxos de revisão manual**Principais recursos:**- **Editor visual de nós**: arraste, solte e conecte nós em um canvas infinito
- **Conexões inteligentes**: arraste do ponto de conexão de um nó até um espaço vazio para criar e conectar um novo nó instantaneamente
- **Ramificação condicional**: direcione os usuários para perguntas diferentes com base nas respostas anteriores e depois [reúna os caminhos em uma etapa compartilhada](#reunindo-caminhos-ramificados-em-uma-etapa-compartilhada)
- **Suporte multilíngue**: traduza todo o conteúdo exibido ao usuário
- **Atalhos de teclado**: desfazer (Ctrl/Cmd+Z), refazer (Ctrl/Cmd+Shift+Z), excluir (Delete/Backspace)
- **Zoom e movimentação**: navegue por formulários complexos com zoom pela rolagem e movimentação arrastando#### Tipos de nó do construtor de grafos| Tipo de nó | Cor | Descrição | Quando usar |
| - | - | - | - |
| **Nós de pergunta** | Azul | Elementos de entrada que coletam dados do usuário | Campos de texto, listas suspensas, envio de arquivos, datas etc. |
| **Nós de texto** | Verde | Conteúdo somente leitura exibido aos usuários | Instruções, explicações, texto legal |
| **Nós de ramificação** | Laranja | Roteamento condicional com base nas respostas | "Se o país for EUA, mostrar o formulário fiscal" |
| **Nós de seção** | Cinza | Agrupamento visual de elementos relacionados | Organizar as perguntas em seções lógicas |> **Regras de conexão:** os nós de seção e de texto podem se conectar a nós de pergunta e a outros nós de texto, mas não diretamente a nós de ramificação. Os nós de ramificação podem se conectar a qualquer tipo de nó.#### Reunindo caminhos ramificados em uma etapa compartilhadaA ramificação não precisa ser de mão única. O final de vários caminhos pode se conectar ao mesmo nó seguinte, e o questionário continua a partir dali uma única vez. As perguntas compartilhadas são criadas e mantidas em um só lugar, em vez de se repetirem no final de cada caminho.**Exemplo prático: perguntas extras para Sim e depois um trecho final compartilhado**1) Adicione um **nó de pergunta** com uma pergunta de **Escolha Única** com as opções Sim e Não e, depois dele, um **nó de ramificação** com um caminho `Yes` e um caminho `No`.
2) No caminho `Yes`, adicione as perguntas extras que só se aplicam quando a resposta é Sim.
3) No final desse caminho, adicione a primeira pergunta que todo respondente deve responder depois da ramificação: o início do trecho final compartilhado.
4) Aponte o caminho `No` para essa pergunta: abra o menu **+** no final do caminho `No` e escolha **Conectar a uma etapa existente**, ou arraste a partir do conector do caminho `No` e solte na borda superior da pergunta compartilhada. O canvas só se conecta ao pequeno alvo na parte superior do cartão, então soltar sobre o meio do cartão não faz nada.
5) Continue adicionando as demais perguntas compartilhadas depois da primeira e, em seguida, publique. O canvas desenha o trecho final compartilhado uma única vez, abaixo dos caminhos que levam até ele.Um caminho pode se juntar a um nó que já existe dessa forma, e vários caminhos podem apontar para o mesmo nó. Juntar define onde esse caminho continua, por isso o menu **+** oferece **Conectar a uma etapa existente** enquanto o caminho termina ali. Uma conexão que fecharia um ciclo de volta a um nó anterior é recusada.Os respondentes respondem às perguntas compartilhadas uma única vez, no caminho que seguiram; as perguntas do caminho que não seguiram são ignoradas. O payload da decisão segue a mesma regra: `questionnaire_responses[].sections[].items` lista apenas os itens do caminho que o respondente seguiu. Veja [Visibilidade condicional](https://docs.didit.me/core-technology/questionnaires/report-questionnaire.md#conditional-visibility).***## Modelos de questionárioOs modelos ajudam você a começar rapidamente, com formulários pré-configurados para casos de uso comuns. Você pode usá-los como estão ou personalizá-los conforme suas necessidades.![Modelos prontos de questionário da Didit para origem dos recursos e conformidade KYC](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-template.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=97a45bd55692379ffc057e11f4530a54)### Modelos prontos| Modelo | Descrição | Elementos típicos |
| - | - | - |
| **Origem dos recursos** | Captura fontes de renda e a documentação comprobatória | Lista suspensa, texto longo, envio de arquivo |
| **Dados de emprego** | Coleta cargo, empregador e faixa de renda | Texto curto, lista suspensa, número |
| **Finalidade da conta** | Entende o uso pretendido da conta | Escolha única, múltipla escolha, texto longo |
| **Beneficiário final** | Identifica os UBOs e a estrutura societária | Texto curto, número, envio de arquivo |
| **Residência fiscal** | Coleta declarações de natureza fiscal | País, consentimento, envio de arquivo |
| **Avaliação de risco** | Reúne informações relevantes para o risco | Múltipla escolha, lista suspensa, texto longo |***## Como funcionaNosso fluxo de questionários foi projetado para ser flexível e auditável:### 1. Crie no Console (sem código)- Arraste e solte elementos para criar seu questionário
- Organize o conteúdo em várias seções para maior clareza
- Marque os elementos como obrigatórios ou opcionais
- Configure placeholders e descrições de apoio
- Adicione opções (com complemento opcional em texto livre) para listas suspensas e escolha única
- Configure os limites de envio de arquivos e imagens por elemento### 2. Localize o conteúdo- Escreva seu conteúdo uma única vez no `default_language` do questionário
- Defina os `languages` compatíveis: ao publicar, todo título, descrição, placeholder, rótulo de opção e mensagem de validação é **traduzido automaticamente** para todos eles
- Ajuste qualquer tradução manualmente no construtor; as edições manuais são preservadas até que o texto de origem mude
- O usuário final vê o conteúdo automaticamente no melhor idioma disponível### 3. Publique e colete- Ative o questionário e incorpore-o ao seu fluxo de verificação
- Os usuários finais preenchem as seções e enviam as respostas
- Os arquivos enviados (documentos, imagens) são armazenados e vinculados à resposta### 4. Revise e decida* As respostas são salvas com um `status`: `Approved`, `In Review` ou `Not Finished`
* Você pode forçar todas as respostas do questionário a ficarem em `In Review`, para que uma pessoa as aprove manualmente
* Revise as respostas e os arquivos no console e marque como `Approved`> Observação: os Questionários não geram alertas de risco. A governança é obtida por meio de campos obrigatórios, validação e fluxos de revisão.***## Principais recursos| Recurso | Modo simples | Modo avançado |
| - | - | - |
| Construtor de arrastar e soltar | ✅ | ✅ |
| Campos obrigatórios/opcionais | ✅ | ✅ |
| Placeholders e descrições | ✅ | ✅ |
| Várias seções | ✅ | ✅ |
| Limites de envio de arquivos | ✅ | ✅ |
| Editor visual de grafos | ❌ | ✅ |
| Ramificação condicional | ❌ | ✅ |
| Traduções para vários idiomas | ❌ | ✅ |
| Lógica de opções (exigir texto) | ❌ | ✅ |
| Forçar revisão manual | ❌ | ✅ |
| Suporte a desfazer/refazer | ❌ | ✅ |
| Atalhos de teclado | ❌ | ✅ |**Lista completa de recursos:**- **Construtor visual**: crie e gerencie questionários com um editor intuitivo de arrastar e soltar
- **Seções**: agrupe perguntas relacionadas; adicione cabeçalhos e separadores para orientar os usuários
- **Traduções automáticas**: escreva o conteúdo em um idioma e todo o texto exibido ao usuário é traduzido para os demais idiomas selecionados ao publicar, com ajuste manual possível
- **Validação**: marque campos como obrigatórios; defina o máximo de arquivos por elemento de envio
- **Lógica de opções**: em listas suspensas e escolha única, exija opcionalmente um texto adicional por opção selecionada
- **Envios de arquivos**: colete documentos e imagens com limite de quantidade de arquivos (por exemplo, até 3 arquivos)
- **Revisão manual**: force opcionalmente todas as respostas para `In Review` até a aprovação de uma pessoa
- **Chave de ativação**: ative ou desative o questionário por aplicação
- **Integração com fluxos**: adicione questionários ao KYC ou execute-os de forma independente como um fluxo de verificação de questionário (workflow)
- **APIs e webhooks**: leia os resultados estruturados via API e receba atualizações***## Tipos de elementoVocê pode adicionar os seguintes tipos de elemento no construtor (selecionáveis a partir do console):### Elementos de entrada| Elemento | Descrição | Opções de configuração |
| - | - | - |
| **SHORT\_TEXT** | Texto livre de uma linha | Placeholder, obrigatório |
| **LONG\_TEXT** | Texto livre de várias linhas | Placeholder, obrigatório |
| **NUMBER** | Entrada numérica | Placeholder, obrigatório |
| **EMAIL** | Entrada de e-mail com validação | Placeholder, obrigatório |
| **PHONE** | Entrada de número de telefone | Placeholder, obrigatório |
| **ADDRESS** | Entrada de endereço | Placeholder, obrigatório |
| **DATE\_PICKER** | Seleção de data | Placeholder, obrigatório |
| **TIME** | Entrada de horário | Placeholder, obrigatório |### Elementos de escolha| Elemento | Descrição | Opções de configuração |
| - | - | - |
| **DROPDOWN** | Seleção única em uma lista | Opções, `requires_text_input` por opção |
| **SINGLE\_CHOICE** | Seleção única estilo botão de rádio | Opções, `requires_text_input` por opção |
| **MULTIPLE\_CHOICE** | Lista de seleção múltipla | Opções |
| **COUNTRY** | Seletor de país | Obrigatório |
| **CONSENT** | Caixa de seleção ou confirmação | Obrigatório, rótulo personalizado |### Elementos de envio| Elemento | Descrição | Opções de configuração |
| - | - | - |
| **IMAGE** | Envio de imagem | `max_files` (1-5), obrigatório |
| **FILE\_UPLOAD** | Envio de documento | `max_files` (1-5), obrigatório |### Elementos de layout| Elemento | Descrição | Observações |
| - | - | - |
| **PARAGRAPH** | Texto explicativo somente leitura | Não respondível |
| **SECTION\_HEADER** | Cabeçalho visual de seção | Não respondível, não obrigatório |
| **SEPARATOR** | Divisor visual | Não respondível, não obrigatório |**Observações de comportamento:**- `SECTION_HEADER` e `SEPARATOR` servem apenas para apresentação. Ignoram obrigatório, placeholder, opções e limites de arquivos.
- Para elementos de escolha, defina as opções como `{ label, value, requires_text_input? }`.
- Para elementos de envio, defina `max_files` (1–5) para controlar quantos arquivos podem ser anexados.***## Forçar a revisão manualAlguns fluxos de conformidade exigem a revisão humana de cada resposta. No console, você pode configurar os questionários para resultarem sempre em `In Review`. Um revisor então aprova ou solicita alterações, e depois disso a resposta passa a `Approved`.**Quando usar a revisão manual:**- Onboarding de clientes de alto risco
- Coleta de dados sensíveis (origem dos recursos, declarações de UBO)
- Exigências regulatórias de supervisão humana
- Garantia de qualidade durante a implantação inicial***## Exemplos de casos de uso### Origem dos recursosCapture fontes de renda, valores e envie documentos comprobatórios (por exemplo, holerites e extratos). Combine listas suspensas, texto longo e envio de arquivos.**Estrutura típica:**- Seção 1: situação profissional (lista suspensa)
- Seção 2: fontes de renda (múltipla escolha + texto longo)
- Seção 3: documentos comprobatórios (envio de arquivo)
- Seção 4: declaração (consentimento)***### Associação ou filiaçãoRegistre vínculos, funções e comprovante de filiação; inclua elementos de consentimento para as declarações.**Estrutura típica:**- Nome da organização (texto curto)
- Função/cargo (lista suspensa)
- Tempo de filiação (seletor de data)
- Comprovante de filiação (envio de arquivo)
- Declaração (consentimento)***### Finalidade do relacionamento e atividade esperada da contaColete a intenção, os volumes esperados de transações, os países de atividade e as contrapartes previstas. Use escolha única/múltipla, campos numéricos e parágrafos para dar contexto.**Estrutura típica:**- Seção 1: finalidade da conta (múltipla escolha)
- Seção 2: volume mensal esperado (número + lista suspensa para a moeda)
- Seção 3: países de atividade (país - múltiplo)
- Seção 4: tipos de transação (múltipla escolha)
- Seção 5: informações adicionais (texto longo)***## Modo simples ou avançado: quando usar cada um| Cenário | Modo recomendado |
| - | - |
| Formulário básico em um único idioma | Simples |
| Necessidade de suporte a vários idiomas | Avançado |
| Pesquisa interna rápida | Simples |
| Questionário de conformidade | Avançado |
| Coleta de dados pontual | Simples |
| Caminhos de ramificação condicional | Avançado |
| Forçar revisão manual | Avançado |
| Formulários complexos com várias seções | Avançado |***## Primeiros passos1. **Novo em questionários?** Comece pelo **Modo simples** para aprender o construtor
2. **Precisa de traduções ou lógica condicional?** Passe para o **Modo avançado** e use o editor visual de grafos> Veja como os resultados são estruturados na página do [Relatório de Questionários](https://docs.didit.me/core-technology/questionnaires/report-questionnaire.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.