> ## 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.

# KYC 설문지 API: 동적 양식 빌더

> Didit의 드래그 앤 드롭 빌더로 맞춤형 KYC 설문지를 제작하세요. 다국어 지원, 조건부 로직, 수동 검토 라우팅을 지원합니다. 호출당 $0.10.

Didit의 설문지를 사용하면 구조화된 동적 양식을 설계하여 인증 과정에서 사용자로부터 추가 정보를 수집할 수 있습니다. 비주얼 빌더를 통해 요소를 드래그 앤 드롭하고, 콘텐츠를 섹션별로 구성하며, 여러 언어로 텍스트를 현지화하고, 필요한 경우 결과를 수동 검토로 라우팅할 수 있습니다.

설문지 연동 프롬프트
        프롬프트를 클립보드에 복사



      
      

\<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>



      
      

붙여넣을 곳

인증 결과 확인에 관한 Academy 강의 중 11:54 챕터에서 Document AI 및 설문지를 다룹니다.[Document AI 및 설문지 — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=714\&rel=0\&playsinline=1)***## 설문지를 작성하는 두 가지 방법Didit은 설문지 작성을 위한 **두 가지 서로 다른 접근 방식**을 제공하므로 필요에 맞는 복잡도를 선택할 수 있습니다.![Didit KYC questionnaire simple and advanced builder modes side by side](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. 단순 모드: 빠른 폼 빌더**단순 모드**는 간단한 폼을 빠르게 작성하는 데 적합합니다. 직관적인 드래그 앤 드롭 인터페이스를 통해 요소를 추가하고 필수 필드를 설정하여 몇 분 만에 게시할 수 있습니다.![Didit questionnaire simple mode drag-and-drop form builder interface](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-simple.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=8e777d8fc72ca16e8e2deb65a0a66e92)**적합한 사용 사례:**- 빠른 데이터 수집 폼
- 간단한 설문 및 증명
- 폼 작성을 처음 접하는 팀
- 단일 언어 설문지**작동 방식:**1) 설문지 빌더를 엽니다.
2) 팔레트에서 폼으로 요소를 드래그합니다.
3) 각 요소를 구성합니다(라벨, 필수 여부, 플레이스홀더).
4) 미리 확인하고 게시합니다.***### 2. 고급 모드: 시각적 그래프 빌더**고급 모드**는 **시각적 노드 기반 에디터**를 사용하여 복잡한 데이터 수집 시나리오에 필요한 강력한 기능을 제공합니다. 조건부 로직, 분기 경로, 흐름에 대한 완전한 제어를 통해 정교한 설문지를 작성할 수 있습니다.![Didit advanced questionnaire visual node-based graph editor with branching logic](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)**적합한 사용 사례:**- 다국어 설문지
- 조건부 분기가 있는 복잡한 폼
- 경로가 서로 다른 컴플라이언스 기반 데이터 수집
- 수동 검토 워크플로가 필요한 폼**주요 기능:**- **시각적 노드 에디터**: 무한 캔버스에서 노드를 드래그, 드롭하고 연결합니다.
- **스마트 연결**: 노드 핸들에서 빈 공간으로 드래그하여 새 노드를 즉시 생성하고 연결합니다.
- **조건부 분기**: 이전 답변을 기반으로 사용자를 서로 다른 질문으로 라우팅한 다음 [공통 단계에서 경로를 다시 합칩니다](#분기-경로를-공통-단계로-다시-합치기).
- **다국어 지원**: 사용자에게 표시되는 모든 콘텐츠를 번역합니다.
- **키보드 단축키**: 실행 취소(Ctrl/Cmd+Z), 다시 실행(Ctrl/Cmd+Shift+Z), 삭제(Delete/Backspace)
- **확대/축소 및 이동**: 스크롤로 확대/축소하고 드래그하여 이동하면서 복잡한 폼을 탐색합니다.#### 그래프 빌더 노드 유형| 노드 유형 | 색상 | 설명 | 사용 시점 |
| - | - | - | - |
| **질문 노드** | 파란색 | 사용자 데이터를 수집하는 입력 요소 | 텍스트 입력, 드롭다운, 파일 업로드, 날짜 등 |
| **텍스트 노드** | 녹색 | 사용자에게 표시되는 읽기 전용 콘텐츠 | 안내, 설명, 법적 텍스트 |
| **분기 노드** | 주황색 | 답변에 기반한 조건부 라우팅 | "국가가 미국인 경우 세무 양식 표시" |
| **섹션 노드** | 회색 | 관련된 요소의 시각적 그룹화 | 질문을 논리적 섹션으로 정리 |> **연결 규칙:** 섹션 노드와 텍스트 노드는 질문 노드 및 다른 텍스트 노드에 연결할 수 있지만, 분기 노드에는 직접 연결할 수 없습니다. 분기 노드는 모든 노드 유형에 연결할 수 있습니다.#### 조건 연산자분기 조건은 이전 답변을 특정 값과 비교합니다.
여러 조건을 `and` 또는 `or`로 결합할 수 있습니다.| 연산자 | 답변이 다음 조건에 해당할 때 일치 |
| - | - |
| `equals` | 값과 같은 경우 |
| `not_equals` | 값과 같지 않은 경우 |
| `contains` | 값을 포함하는 경우 |
| `greater_than` | 값보다 큰 경우 |
| `greater_than_or_equals` | 값보다 크거나 같은 경우 |
| `less_than` | 값보다 작은 경우 |
| `less_than_or_equals` | 값보다 작거나 같은 경우 |
| `in` | 값 목록 중 하나에 해당하는 경우 |
| `not_in` | 값 목록 중 어느 것에도 해당하지 않는 경우 |
| `is_empty` | 비어 있는 경우 |
| `is_not_empty` | 입력된 경우 |#### 분기 경로를 공통 단계로 다시 합치기분기가 반드시 일방통행일 필요는 없습니다. 여러 경로의 끝을 동일한 하위 노드에 연결하여 설문지가 해당 지점부터 한 번만 이어지도록 할 수 있습니다. 이를 통해 공통 질문을 모든 경로의 끝마다 반복하지 않고 한 곳에서 작성하고 관리할 수 있습니다.**실습 예시: '예' 선택 시 추가 질문 표시 후 공통 후속 단계 진행**1) '예'와 '아니요'를 제공하는 **단일 선택** 질문이 포함된 **질문 노드**를 추가한 다음, 그 뒤에 `Yes` 경로와 `No` 경로가 있는 **분기 노드**를 추가합니다.
2) `Yes` 경로에는 답변이 '예'일 때만 적용되는 추가 질문을 추가합니다.
3) 해당 경로의 끝에 분기 이후 모든 응답자가 답해야 하는 첫 번째 질문(공통 후속 단계의 시작점)을 추가합니다.
4) `No` 경로가 해당 질문을 가리키도록 설정합니다. `No` 경로 끝에 있는 **+** 메뉴를 열고 **기존 단계에 연결**을 선택하거나, `No` 경로의 커넥터에서 드래그하여 공통 질문의 상단 가장자리에 놓습니다. 캔버스는 카드 상단의 작은 연결 대상 영역에만 연결되므로 카드 중앙에 놓으면 아무 작업도 수행되지 않습니다.
5) 첫 번째 질문 뒤에 나머지 공통 질문을 계속 추가한 후 게시합니다. 캔버스는 공통 후속 단계를 해당 단계로 이어지는 경로 아래에 한 번만 표시합니다.이러한 방식으로 경로를 이미 존재하는 노드에 합칠 수 있으며, 여러 경로가 동일한 노드를 가리킬 수도 있습니다. 합치기를 통해 해당 경로가 이어지는 위치가 설정되므로, 경로가 그곳에서 끝나면 **+** 메뉴에 **기존 단계에 연결**이 표시됩니다. 이전 노드로 되돌아가는 루프를 형성하는 연결은 거부됩니다.응답자는 어느 경로를 거쳤든 공통 질문에 한 번만 답변하며, 거치지 않은 경로의 질문은 건너뜁니다. 결정 payload도 동일한 규칙을 따르므로 `questionnaire_responses[].sections[].items`에는 응답자가 진행한 경로의 항목만 나열됩니다. [조건부 표시](https://docs.didit.me/ko/core-technology/questionnaires/report-questionnaire.md#조건부-가시성)를 참고하십시오.***## 설문지 템플릿템플릿을 사용하면 일반적인 사용 사례에 맞게 미리 구성된 양식으로 빠르게 시작할 수 있습니다. 그대로 사용하거나 필요에 맞게 맞춤 설정할 수 있습니다.![자금 출처 및 KYC 컴플라이언스를 위한 Didit 설문지 사전 구축 템플릿](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-template.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=97a45bd55692379ffc057e11f4530a54)### 사전 구축 템플릿| 템플릿 | 설명 | 일반적인 요소 |
| - | - | - |
| **자금 출처** | 소득 출처 및 증빙 서류 수집 | 드롭다운, 긴 텍스트, 파일 업로드 |
| **고용 정보** | 직책, 고용주, 소득 범위 수집 | 짧은 텍스트, 드롭다운, 숫자 |
| **계정 목적** | 의도된 계정 사용 목적 파악 | 단일 선택, 다중 선택, 긴 텍스트 |
| **실소유권** | 실소유자(UBO) 및 소유 구조 파악 | 짧은 텍스트, 숫자, 파일 업로드 |
| **세금 거주지** | 세무 관련 신고서 수집 | 국가, 동의, 파일 업로드 |
| **위험 평가** | 위험 관련 정보 수집 | 다중 선택, 드롭다운, 긴 텍스트 |***## 작동 방식Didit의 설문지 워크플로는 유연성과 감사 가능성을 고려하여 설계되었습니다.### 1. 콘솔에서 구축(노코드)- 요소를 드래그 앤 드롭하여 설문지 생성
- 명확성을 위해 콘텐츠를 여러 섹션으로 구성
- 요소를 필수 또는 선택 항목으로 표시
- 플레이스홀더 및 도움말 설명 구성
- 드롭다운 및 단일 선택에 대한 선택지 추가(선택적 자유 텍스트 후속 입력 추가 가능)
- 요소당 파일/이미지 업로드 제한 구성### 2. 콘텐츠 현지화- 설문지의 `default_language`로 콘텐츠를 한 번만 작성
- 지원할 `languages` 정의 — 게시 시 모든 제목, 설명, 플레이스홀더, 선택지 라벨 및 검증 메시지가 해당 언어로 **자동 번역**
- 빌더에서 원하는 번역을 수동으로 미세 조정 가능; 수동 편집 내용은 원본 텍스트가 변경될 때까지 보존됨
- 최종 사용자에게 지원 가능한 최적의 언어로 콘텐츠가 자동 표시### 3. 게시 및 수집- 설문지를 활성화하고 인증 흐름에 삽입
- 최종 사용자가 섹션을 완료하고 답변 제출
- 파일 업로드(문서, 이미지)가 저장되고 응답에 연결### 4. 검토 및 결정* 응답은 `status`가 `Approved`, `In Review` 또는 `Not Finished`인 상태로 저장됨
* 모든 설문지 응답이 `In Review` 상태가 되도록 강제하여 담당자가 수동으로 승인하도록 설정 가능
* 콘솔에서 답변과 파일을 검토한 후 `Approved`로 표시> 참고: 설문지에서는 위험 경고가 생성되지 않습니다. 거버넌스는 필수 필드, 검증 및 검토 워크플로를 통해 이루어집니다.***## 주요 기능| 기능 | 간편 모드 | 고급 모드 |
| - | - | - |
| 드래그 앤 드롭 빌더 | ✅ | ✅ |
| 필수/선택 필드 | ✅ | ✅ |
| 플레이스홀더 및 설명 | ✅ | ✅ |
| 여러 섹션 | ✅ | ✅ |
| 파일 업로드 제한 | ✅ | ✅ |
| 시각적 그래프 편집기 | ❌ | ✅ |
| 조건부 분기 | ❌ | ✅ |
| 다국어 번역 | ❌ | ✅ |
| 선택 로직(텍스트 필수 입력) | ❌ | ✅ |
| 수동 검토 강제 | ❌ | ✅ |
| 실행 취소/다시 실행 지원 | ❌ | ✅ |
| 키보드 단축키 | ❌ | ✅ |**전체 기능 목록:**- **시각적 빌더**: 직관적인 드래그 앤 드롭 편집기로 설문지 생성 및 관리
- **섹션**: 관련된 질문들을 그룹화; 사용자를 안내하기 위한 헤더 및 구분선 추가
- **자동 번역**: 한 언어로 콘텐츠를 작성하면 게시 시 모든 사용자 대면 텍스트가 선택한 다른 모든 언어로 번역되며 수동 미세 조정 지원
- **검증**: 필드를 필수로 표시; 업로드 요소당 최대 파일 수 적용
- **선택 로직**: 드롭다운/단일 선택의 경우, 선택한 옵션별로 추가 텍스트를 선택적으로 요구
- **업로드**: 파일 수 제한(예: 최대 3개 파일)과 함께 문서 및 이미지 수집
- **수동 검토**: 사람의 승인을 대기하도록 모든 응답을 선택적으로 `In Review`로 강제 설정
- **활성화 토글**: 애플리케이션별로 설문지 활성화 또는 비활성화
- **워크플로 연동**: 설문지를 KYC에 추가하거나 독립형 설문지 인증 워크플로로 실행
- **API 및 webhook**: API를 통해 구조화된 결과를 읽고 업데이트 수신***## 요소 유형빌더에서 다음 요소 유형을 추가할 수 있습니다(콘솔에서 선택 가능).### 입력 요소| 요소 | 설명 | 구성 옵션 |
| - | - | - |
| **SHORT\_TEXT** | 한 줄 자유 텍스트 | 플레이스홀더, 필수 |
| **LONG\_TEXT** | 여러 줄 자유 텍스트 | 플레이스홀더, 필수 |
| **NUMBER** | 숫자 입력 | 플레이스홀더, 필수 |
| **EMAIL** | 유효성 검사가 포함된 이메일 입력 | 플레이스홀더, 필수 |
| **PHONE** | 전화번호 입력 | 플레이스홀더, 필수 |
| **ADDRESS** | 주소 입력 | 플레이스홀더, 필수 |
| **DATE\_PICKER** | 날짜 선택 | 플레이스홀더, 필수 |
| **TIME** | 시간 입력 | 플레이스홀더, 필수 |### 선택 요소| 요소 | 설명 | 구성 옵션 |
| - | - | - |
| **DROPDOWN** | 목록에서 단일 선택 | 선택지, 선택지별 `requires_text_input` |
| **SINGLE\_CHOICE** | 라디오 버튼 스타일 단일 선택 | 선택지, 선택지별 `requires_text_input` |
| **MULTIPLE\_CHOICE** | 다중 선택 체크리스트 | 선택지 |
| **COUNTRY** | 국가 선택기 | 필수 |
| **CONSENT** | 체크박스 또는 확인 | 필수, 사용자 지정 레이블 |### 업로드 요소| 요소 | 설명 | 구성 옵션 |
| - | - | - |
| **IMAGE** | 이미지 업로드 | `max_files` (1-5), 필수 |
| **FILE\_UPLOAD** | 문서 업로드 | `max_files` (1-5), 필수 |### 레이아웃 요소| 요소 | 설명 | 참고 사항 |
| - | - | - |
| **PARAGRAPH** | 읽기 전용 설명 텍스트 | 응답 불가 |
| **SECTION\_HEADER** | 시각적 섹션 헤더 | 응답 불가, 필수 설정 미적용 |
| **SEPARATOR** | 시각적 구분선 | 응답 불가, 필수 설정 미적용 |**동작 관련 참고 사항:**- `SECTION_HEADER` 및 `SEPARATOR`는 화면 표시 전용 요소입니다. 필수 여부, 플레이스홀더, 선택지, 파일 수 제한 등의 설정은 무시됩니다.
- 선택 요소의 경우 선택지를 `{ label, value, requires_text_input? }` 형태로 정의합니다.
- 업로드 요소의 경우 `max_files`(1\~5)를 설정하여 첨부할 수 있는 파일 수를 제어합니다.***## 수동 검토 강제일부 컴플라이언스 워크플로에서는 모든 응답에 대해 담당자의 직접 검토가 필요합니다. 콘솔에서 설문지 결과가 항상 `In Review` 상태가 되도록 설정할 수 있습니다. 이후 검토자가 승인하거나 변경을 요청하며, 완료되면 응답 상태가 `Approved`로 전환됩니다.**수동 검토를 사용하는 경우:**- 고위험 고객 온보딩
- 민감한 데이터 수집(자금 출처, UBO 신고)
- 사람의 감독을 요구하는 규제 요건
- 초기 도입 단계에서의 품질 보증***## 활용 사례 예시### 자금 출처소득원과 금액을 파악하고 증빙 문서(예: 급여 명세서, 거래 명세서)를 업로드하도록 합니다. 드롭다운, 여러 줄 텍스트, 파일 업로드를 조합하여 구성할 수 있습니다.**일반적인 구성:**- 섹션 1: 고용 상태(드롭다운)
- 섹션 2: 소득원(다중 선택 + 여러 줄 텍스트)
- 섹션 3: 증빙 문서(파일 업로드)
- 섹션 4: 서약(동의)***### 소속 또는 멤버십소속 단체, 직책, 멤버십 증명을 기록하고, 확인 서약을 위한 동의 요소를 포함합니다.**일반적인 구성:**- 조직명(한 줄 텍스트)
- 역할/직책(드롭다운)
- 멤버십 기간(날짜 선택기)
- 멤버십 증명(파일 업로드)
- 서약(동의)***### 관계 목적 및 예상 계정 활동계좌 개설 목적, 예상 거래량, 활동 국가, 예상 거래 상대방 정보를 수집합니다. 단일/다중 선택, 숫자 입력, 맥락을 제공하기 위한 문단을 활용할 수 있습니다.**일반적인 구성:**- 섹션 1: 계정 목적(다중 선택)
- 섹션 2: 예상 월간 거래량(숫자 + 통화 선택 드롭다운)
- 섹션 3: 활동 국가(국가 - 복수 선택)
- 섹션 4: 거래 유형(다중 선택)
- 섹션 5: 추가 정보(여러 줄 텍스트)***## Simple 모드와 Advanced 모드: 각각 언제 사용해야 하는가| 시나리오 | 권장 모드 |
| - | - |
| 단일 언어 기반의 기본 양식 | Simple |
| 다국어 지원 필요 | Advanced |
| 빠른 내부 설문조사 | Simple |
| 컴플라이언스 설문지 | Advanced |
| 일회성 데이터 수집 | Simple |
| 조건부 분기 경로 | Advanced |
| 수동 검토 강제 | Advanced |
| 복잡한 다중 섹션 양식 | Advanced |***## 시작하기1. **설문지를 처음 사용하시나요?** 빌더 사용법을 익히려면 **Simple Mode**로 시작하세요.
2. **번역이나 조건부 로직이 필요하신가요?** 시각적 그래프 편집기를 제공하는 **Advanced Mode**로 전환하세요.> 결과가 어떻게 구조화되는지는 [설문지 보고서](https://docs.didit.me/ko/core-technology/questionnaires/report-questionnaire.md) 페이지에서 확인할 수 있습니다.


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