> ## 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: KYC 플로 구축 > Didit에서 순서가 지정된 기능으로 검증 워크플로를 프로그래밍 방식으로 생성하세요. KYC, KYB, AML, 생체 인증을 하나의 플로에서. 호출당 과금, 계약 불필요. 워크플로 생성 API 프롬프트 프롬프트를 클립보드에 복사 \

\`Create a simple Didit workflow through the Management API.

Endpoint:
POST https://verification.didit.me/v3/workflows/

Authentication:
Use the x-api-key header with my Didit API key.

Requirements:
\- Use the simple v3 API shape with features.
\- Send features in the exact order users should complete them.
\- Do not send workflow_graph, branches, actions, webhooks, or conditional logic.
\- Didit will convert the features array into a linear node-based workflow and add the final status step automatically.
\- Use uppercase feature values such as OCR, LIVENESS, FACE_MATCH, AML, QUESTIONNAIRE, EMAIL_VERIFICATION, PHONE_VERIFICATION, or PROOF_OF_ADDRESS.
\- Configure each feature with the fields from /management-api/workflows/feature-configs.
\- For an OCR feature, omit config.documents_allowed or send an empty object to allow every supported document type. Send config.documents_allowed only to restrict the allowed documents.
\- Put dependency features first. For example, put OCR before FACE_MATCH, NFC, DATABASE_VALIDATION, or user AML checks that depend on document data.
\- For a QUESTIONNAIRE feature, first create the questionnaire with POST /v3/questionnaires/ and use the returned questionnaire_id as config.questionnaire_uuid.
\- Store the workflow uuid returned by the response. Use it as workflow_id when creating sessions and as settings_uuid when updating this workflow.

Example KYC request body:
\{
"workflow_label": "Standard KYC",
"features": [
\{
  "feature": "OCR",
  "config": {
    "documents_allowed": {
      "USA": {
        "DL": {
          "enabled": 1,
          "sides": 2
        }
      }
    },
    "duplicated_user_action": "REVIEW"
  }
},
\{
  "feature": "LIVENESS",
  "config": {
    "face_liveness_method": "PASSIVE"
  }
},
\{
  "feature": "FACE_MATCH"
}
]
}

Example questionnaire workflow body:
\{
"workflow_label": "Source of Funds",
"features": [
\{
  "feature": "QUESTIONNAIRE",
  "config": {
    "questionnaire_uuid": "11111111-2222-3333-4444-555555555555",
    "review_questionnaire_manually": true
  }
}
]
}

Build the API call, handle validation errors, and return the workflow uuid from the response.`

\
붙여넣을 곳 이 엔드포인트를 사용하면 워크플로 노드를 직접 구성하지 않고도 API로 워크플로를 만들 수 있습니다. 사용자가 확인을 완료해야 하는 순서대로 `features` 배열을 보내십시오. Didit이 이를 내부적으로 노드 기반 워크플로로 변환하고 마지막 상태 단계를 자동으로 추가합니다.이 `POST /v3/workflows/` 엔드포인트는 **단순하고 선형적인** 워크플로만 생성하며, 평평한 `features` 목록만 지원합니다. **분기, 조건부 라우팅, Document AI, 거부 및 결정 노드**가 필요하다면 아래에 설명된 노드 [그래프 형식](#분기-및-노드-기반-워크플로-그래프)을 사용하십시오. 이 형식은 콘솔의 시각적 빌더와 [Didit MCP](https://docs.didit.me/ko/integration/mcp/overview.md) 워크플로 도구를 지원합니다.지원되는 각 기능의 모든 `config` 필드는 [워크플로 기능 구성](https://docs.didit.me/ko/management-api/workflows/feature-configs.md)을 참조하십시오.## 기본 KYC 워크플로```json theme={null} { "workflow_label": "Standard KYC", "features": [ { "feature": "OCR", "config": { "documents_allowed": { "USA": { "DL": { "enabled": 1, "sides": 2 } } }, "duplicated_user_action": "REVIEW" } }, { "feature": "LIVENESS", "config": { "face_liveness_method": "PASSIVE" } }, { "feature": "FACE_MATCH" } ] } ```## 설문지 워크플로먼저 `POST /v3/questionnaires/`로 설문지를 생성하십시오. 그다음 반환된 `questionnaire_id`를 `questionnaire_uuid`로 사용하십시오.```json theme={null} { "workflow_label": "Source of Funds", "features": [ { "feature": "QUESTIONNAIRE", "config": { "questionnaire_uuid": "11111111-2222-3333-4444-555555555555", "review_questionnaire_manually": true } } ] } ```기능 순서가 중요합니다. 예를 들어 `OCR`은 `FACE_MATCH`, `NFC`, `DATABASE_VALIDATION` 또는 문서 데이터에 의존하는 사용자 AML 검사보다 앞에 두십시오.## 기능 구성 참조각 `features[]` 항목은 다음과 같은 형태를 가집니다:```json theme={null} { "feature": "OCR", "label": "ID Verification", "config": {} } ```정확한 `config` 객체는 기능마다 다릅니다. 전체 필드 목록, 기본값, 필수 설정, 값 범위 및 예시는 [워크플로 기능 구성](https://docs.didit.me/ko/management-api/workflows/feature-configs.md)에서 확인하십시오.`OCR`의 경우 `config.documents_allowed`를 생략하거나, `null`을 보내거나, `{}`를 보내면 지원되는 모든 문서 유형을 허용합니다. 워크플로를 특정 국가 또는 문서 유형으로 제한하려는 경우에만 이 값을 포함하십시오. `QUESTIONNAIRE`의 경우 `config.questionnaire_uuid`는 필수입니다.## 선택적 워크플로 설정워크플로를 생성할 때 다음 최상위 필드를 포함하여 세션 동작을 제어할 수 있습니다. 모든 필드는 선택 사항이며, 생략하면 워크플로 기본값이 적용됩니다.| 필드 | 유형 | 설명 | | - | - | - | | `is_white_label_enabled` | 불리언 | 이 워크플로로 생성된 세션의 화이트 라벨 커스터마이징을 활성화합니다. 기본값은 `false`입니다. | | `is_desktop_allowed` | 불리언 | 데스크톱 브라우저에서 인증 흐름을 실행할 수 있도록 허용합니다. 기본값은 `false`입니다. | | `max_retry_attempts` | 정수 (0–10) | 거부된 인증 이후 허용되는 최대 재시도 횟수입니다. `0`이면 첫 거부 후 사용자를 차단합니다. 기본값은 `3`입니다. | | `retry_window_days` | 정수 (1–365) 또는 `null` | 재시도 횟수를 계산하는 데 사용되는 롤링 기간(일 단위)입니다(`null` = 전체 기간 한도). 기본값은 `7`입니다. | | `session_expiration_time` | 정수 (3600–2419200) | 완료되지 않은 세션이 만료되기까지의 시간(초 단위)입니다. 최소 1시간, 최대 4주입니다. 기본값은 `604800`(7일)입니다. | | `response_attributes` | 객체 또는 `null` | 기능별로 반환되는 필드를 제한합니다. 예: `{"id_verifications": ["full_name", "document_number"], "face_matches": null}`. `null`이거나 키가 없으면 모든 필드를 반환합니다. 빈 목록이면 `status`, `warnings`, `node_id`, `is_nfc_skipped`, `skip_reason`만 반환되며, 다른 필드는 `null`로 반환됩니다. |```json theme={null} { "workflow_label": "Standard KYC", "is_white_label_enabled": true, "is_desktop_allowed": true, "max_retry_attempts": 5, "retry_window_days": 14, "session_expiration_time": 86400, "features": [ { "feature": "OCR" }, { "feature": "LIVENESS" }, { "feature": "FACE_MATCH" } ] } ```## 분기 및 노드 기반 워크플로(그래프)단순한 `features` 목록으로는 "X이면 Y"와 같은 조건을 표현할 수 없습니다. **조건부 분기**(특정 상태에서 거부, 추출된 필드에 따라 경로 지정, 일치 여부에 따라 단계를 조건부로 실행), **Document AI** 요청 단계, 또는 최종 **거부/결정** 노드를 사용하려면 Didit 워크플로가 **노드 그래프**를 사용해야 합니다. 콘솔의 시각적 빌더가 생성하는 구조와 같습니다.> [!NOTE] > > 노드 그래프 워크플로를 가장 쉽게 만드는 방법은 \*\*[Didit MCP](https://docs.didit.me/ko/integration/mcp/overview.md)\*\*를 사용하는 것입니다. 자연어로 에이전트에게 요청하면(예: "신분증 인증 후 직업이 ≈ 'Software Engineer'이면 자금 증명 단계를 추가해 줘") 그래프를 구성하고, 검증하고, 저장해 줍니다. 아래 구조는 이 도구들과 콘솔이 생성하는 구조입니다.### 그래프 구조그래프는 `{ start_node, nodes }`입니다. `nodes`는 노드 ID에서 노드로의 매핑입니다. 엣지는 암묵적으로 정의됩니다. 각 노드는 `next`(무조건) 및/또는 `branches[].goto`(조건부)를 통해 다음 노드를 가리킵니다.| 노드 유형 | 구조 | | - | - | | `feature` | `{ "node_type": "feature", "feature": "OCR", "config": {…}, "next": "", "branches": [] }` | | `branch` | `{ "node_type": "branch", "branches": [ { "id", "logic": "and"\|"or", "rules": [], "goto": "" } ], "next": "" }` | | `status` (종료) | `{ "node_type": "status", "session_status": "Approved"\|"Declined"\|"In Review"\|"Determine" }` | | `action` | `{ "node_type": "action", "actions": [ { "type": "add_tag"\|"add_review"\|… } ], "next": "" }` | | `webhook` | `{ "node_type": "webhook", "config": { "url", "method" }, "branches": [], "next": "" }` |`start_node`은 반드시 기능 노드여야 합니다. 분기는 순서대로 평가되며, **가장 먼저 일치하는 분기가 적용됩니다**. `rules: []`인 빈 분기는 모든 경우에 해당하는 기본(else) 분기이므로 마지막에 두어야 합니다. `session_status: "Determine"`은 결합된 기능 결과를 바탕으로 자동으로 결정합니다.> [!WARNING] > > **모든 분기 노드에는 명시적인 else 분기가 있어야 합니다.** 즉 어떤 조건에도 해당하지 않는 세션을 라우팅하는 `rules: []` 분기가 필요합니다. 분기 노드의 `next`를 기본 경로로 간주하지 마십시오. 단독 `next`는 빌더에서 모호한 엣지로 표시되며 쉽게 누락됩니다. `next`가 있고 else 분기가 없는 분기 노드를 보내면 API가 그 `next`를 명시적인 else 분기로 **변환**합니다(예: `{ …, "branches": [], "next": "liveness" }`는 `branches: [, { "id": "else", "rules": [], "goto": "liveness" }]`로 저장됩니다). else 분기는 직접 작성하여 명확하게 하십시오. 이 변환은 안전장치이며 명시적 작성을 대신하지 않습니다.### 분기 규칙 및 연산자각 규칙은 **연산자**를 사용해 **필드**와 **값**을 비교합니다.```json theme={null} { "field": "kyc.extra_fields.profession", "operator": "fuzzy_match", "value": "Software Engineer", "score": 80 } ```- **필드**는 기능 결과(`kyc.status`, `aml.status`, `document_ai.status`, `face_match.score` 등) 또는 추출된 값(`kyc.full_name`, `kyc.age`, `kyc.nationality`, `kyc.extra_fields.profession`, Document AI 필드 `document_ai.`, `expected_details.*`)을 가리킵니다. 분기는 해당 경로에 도달하는 모든 경로에서 실행된 기능의 필드만 읽을 수 있습니다. - **연산자:** `equals`, `not_equals`, `greater_than(_or_equals)`, `less_than(_or_equals)`, `contains`, `not_contains`, `in`, `not_in`, `is_empty`, `is_not_empty`, `regex`, 그리고 **`fuzzy_match`**(문자열 필드에만 사용 가능하며, 0\~100 범위의 `score`가 필요합니다. 유사도 임계값이며, 예를 들어 직업이 "Software Engineer"와 80% 이상 유사함을 뜻합니다).### NFC가 실행되지 않은 이유에 따른 분기`NFC` 노드 뒤에서 `nfc.skip_reason`을 `equals` 또는 `in`과 함께 사용하면 칩 판독이 이루어지지 않은 이유에 따라 세션을 라우팅할 수 있습니다. 이 필드에는 안정적인 값 일곱 개가 있습니다.- `USER_SKIPPED` - `DOCUMENT_WITHOUT_CHIP` - `CHIP_CERTIFICATE_UNAVAILABLE` - `DEVICE_WITHOUT_NFC` - `INTEGRATION_WITHOUT_NFC_ACCESS` - `MRZ_KEY_UNAVAILABLE` - `JPKI_UNAVAILABLE`각 값의 의미는 [NFC 건너뛰기 사유](https://docs.didit.me/ko/core-technology/nfc-verification/warnings-nfc-verification.md#건너뛰기-이유)를 참조하십시오. NFC가 성공하면 `nfc.skip_reason`은 `null`이므로, 건너뛰기 사유에 대한 `equals`나 `in` 규칙은 어느 것도 일치하지 않습니다.이 필드는 **게이트에 의해 건너뛴** NFC 노드에도 값을 제공합니다. 여기에는 NFC 보고서나 경고가 존재하지 않는 경우, 그리고 `allow_nfc_skip`이 `false`이지만 문서 또는 기기 게이트 때문에 NFC가 실행되지 않은 경우가 포함됩니다. 따라서 `nfc_verifications[]` 항목에 의존하지 않고도 이러한 세션을 라우팅할 수 있습니다.> [!NOTE] > > NFC 기능이 3상태로 바뀌기 전에 저장된 세션은 `has_device_nfc_support: false`를 가질 수 있습니다. 따라서 이전 웹 세션은 `INTEGRATION_WITHOUT_NFC_ACCESS` 대신 `DEVICE_WITHOUT_NFC`로 판정될 수 있습니다.이 그래프는 사용자가 건너뛴 경우에는 `equals`를, 게이트 또는 기능 지원 여부에 따라 건너뛴 경우에는 `in`을 사용하며, NFC가 성공한 경우를 위한 명시적 else 분기를 둡니다. 분기는 `NFC` 노드 뒤에 오며, 모든 목적지는 종료 노드를 향해 앞으로 이동합니다.```json theme={null} { "start_node": "ocr", "nodes": { "ocr": { "node_type": "feature", "feature": "OCR", "next": "nfc" }, "nfc": { "node_type": "feature", "feature": "NFC", "config": { "allow_nfc_skip": false }, "next": "route_nfc" }, "route_nfc": { "node_type": "branch", "branches": [ { "id": "user_skipped", "logic": "and", "rules": [ { "field": "nfc.skip_reason", "operator": "equals", "value": "USER_SKIPPED" } ], "goto": "manual_review" }, { "id": "nfc_unavailable", "logic": "and", "rules": [ { "field": "nfc.skip_reason", "operator": "in", "value": [ "DOCUMENT_WITHOUT_CHIP", "CHIP_CERTIFICATE_UNAVAILABLE", "DEVICE_WITHOUT_NFC", "INTEGRATION_WITHOUT_NFC_ACCESS", "MRZ_KEY_UNAVAILABLE", "JPKI_UNAVAILABLE" ] } ], "goto": "manual_review" }, { "id": "else", "logic": "and", "rules": [], "goto": "approved" } ] }, "manual_review": { "node_type": "status", "session_status": "In Review" }, "approved": { "node_type": "status", "session_status": "Approved" } } } ```"알려진 이유로 NFC가 수행되지 않은 경우"를 표현하려면 **일곱 개 값 모두**를 `in`에 넣으십시오. NFC 성공(`nfc.skip_reason: null`)을 위한 명시적 else 분기와, 그래프가 아직 인식하지 못하는 향후 값을 위한 else 분기를 유지하십시오.### Document AI(예: 자금 증명)`DOCUMENT_AI` 기능 노드는 하나 이상의 문서를 요청하고 이름이 지정된 필드를 추출합니다.```json theme={null} { "node_type": "feature", "feature": "DOCUMENT_AI", "label": "Proof of Funds", "config": { "document_ai_documents": [ { "document_key": "proof_of_funds", "title": "Proof of Funds", "description": "Upload a recent bank statement.", "fields": [ { "key": "account_holder", "name": "Account holder", "instruction": "The full name of the account holder as printed on the statement.", "type": "text", "required": true, "is_full_name": true }, { "key": "closing_balance", "name": "Closing balance", "instruction": "The closing balance amount.", "type": "number", "required": true } ] } ], "document_ai_missing_required_fields_action": "REVIEW", "document_ai_name_mismatch_action": "REVIEW" }, "next": "final_decision" } ```설정된 각 필드는 분기에서 사용할 수 있는 값 `document_ai.`가 되며, 이 단계의 결과는 `document_ai.status`입니다.문서 소지자의 성명이 들어 있는 필드에는 `"is_full_name": true`를 설정하십시오. 추출된 값은 검증된 신원의 성명(OCR/신분증 인증 이름 또는 세션의 예상 세부 정보)과 비교되며, 일치 점수가 `document_ai_name_match_score_threshold` 미만일 때 수행할 불일치 동작을 `document_ai_name_mismatch_action`이 결정합니다. 이 플래그는 **선택 사항**입니다. 문서에서 어떤 필드도 이 플래그로 표시하지 않을 수도 있으며, **문서 하나당 최대 한 개의 필드**만 이 플래그를 설정할 수 있습니다. Document AI의 모든 설정 필드는 [워크플로 기능 설정 → Document AI](https://docs.didit.me/ko/management-api/workflows/feature-configs.md#document-ai)를 참조하십시오.### 엔드포인트 및 초안 수명 주기그래프 편집은 애플리케이션 단위로 이루어지며 콘솔/관리 엔드포인트를 사용합니다(사용자 Bearer + `read:workflows`/`write:workflows`). 그래프는 **초안** 버전에서만 편집할 수 있으므로 수명 주기는 **초안 생성 → 그래프 설정 → 게시**입니다.| 메서드 | 경로 | 용도 | | - | - | - | | `GET` | `…/verification-settings/{settings_uuid}/workflow-graph/` | 현재 그래프 + `status`/`is_editable` | | `POST` | `…/application/{app}/workflow-graph/validate/` (body `{ "graph": … }`) | 드라이런 검증 | | `GET` | `…/application/{app}/workflow-graph/field-definitions/` | 분기에 사용할 수 있는 필드 및 유효한 연산자 | | `POST` | `…/verification-settings/{settings_uuid}/create-draft/` | 게시된 버전에서 만든 편집 가능한 초안 | | `PUT` | `…/verification-settings/{settings_uuid}/workflow-graph/` (body `{ "graph": … }`) | 그래프 저장 | | `PATCH` | `…/verification-settings/{settings_uuid}/` (body `{ "status": "published" }`) | 초안 게시 |#### 검증 경고검증 endpoint는 `{ "is_valid": true, "graph": …, "warnings": [] }` 형식으로 응답합니다. 경고는 **참고용**입니다. 그래프는 유효하며, 경고가 있어도 저장과 게시가 가능합니다. 각 항목에는 해당하는 분기 노드와 분기 가지가 포함되므로, 빌더가 정확한 조건을 확인할 수 있습니다:```json theme={null} { "type": "branch_outcome_contradiction", "node_id": "after_ocr", "branch_id": "b1", "severity": "warning", "message": "Branch 1 only matches sessions where ID Verification Status is Approved or In Review, but every path from it ends in the session outcome \"Declined\". Check the condition or the outcome.", "params": { "branchNumber": 1, "field": "ID Verification Status", "allowed": "Approved or In Review", "outcome": "Declined" } } ```| `type` | 의미 | | - | - | | `branch_outcome_contradiction` | 분기 가지의 조건과, 그 가지에서 도달하는 모든 경로의 결과가 서로 모순됩니다. 예를 들어 `kyc.status NOT EQUALS Declined`가 `Declined` 결과로 연결되는 경우가 여기에 해당합니다. 결과는 경로에서 몇 단계 더 아래에 있을 수도 있습니다. | | `branch_condition_unreachable` | 이 분기에 도달하는 모든 경로가 이미 해당 상태 필드를 조건이 제외하는 값으로만 제한하므로, 이 분기 가지는 절대 일치하지 않습니다. | | `else_branch_unreachable` | 다른 분기 가지들이 여기서 필드가 가질 수 있는 모든 값을 이미 포함하므로, else 가지는 절대 실행되지 않습니다. |유효하지 않은 그래프는 `400`으로 응답하며, `errors`와 **함께** 가능한 범위에서 생성한 `warnings` 목록을 반환합니다. 저장을 막는 것은 `errors`뿐입니다.### 예시: 소프트웨어 엔지니어에게 자금 증명을 요청하도록 라우팅> 신분증 인증 후, 결과가 **거부됨**이면 세션을 거부합니다. 소지자의 **직업 ≈ "Software Engineer"**(≥80% 유사)이면 **자금 증명** 문서를 요청합니다. 그다음 최종 결정을 내립니다.```json theme={null} { "start_node": "ocr_1", "nodes": { "ocr_1": { "node_type": "feature", "feature": "OCR", "label": "ID Verification", "next": "after_ocr" }, "after_ocr": { "node_type": "branch", "label": "Route after ID verification", "branches": [ { "id": "declined", "logic": "or", "rules": [ { "field": "kyc.status", "operator": "equals", "value": "Declined" } ], "goto": "decline" }, { "id": "software_engineer", "logic": "and", "rules": [ { "field": "kyc.extra_fields.profession", "operator": "fuzzy_match", "value": "Software Engineer", "score": 80 } ], "goto": "proof_of_funds" }, { "id": "else", "logic": "and", "rules": [], "goto": "final_decision" } ] }, "proof_of_funds": { "node_type": "feature", "feature": "DOCUMENT_AI", "label": "Proof of Funds", "config": { "document_ai_documents": [ { "document_key": "proof_of_funds", "title": "Proof of Funds", "description": "Upload a recent bank statement.", "fields": [ { "key": "account_holder", "name": "Account holder", "type": "text", "required": true }, { "key": "closing_balance", "name": "Closing balance", "type": "number", "required": true } ] } ], "document_ai_missing_required_fields_action": "REVIEW" }, "next": "final_decision" }, "final_decision": { "node_type": "status", "session_status": "Determine", "label": "Final decision" }, "decline": { "node_type": "status", "session_status": "Declined", "label": "Declined" } } } ```마지막 노드는 `session_status: "Determine"`을 사용합니다. 이 노드는 세션에서 실제로 실행된 기능을 바탕으로 **자동으로 결정**(승인 / 거부 / 검토 중)합니다. 따라서 자금 증명 경로와 else 경로 모두, 어떤 분기도 `document_ai.status`를 읽지 않아도 올바르게 처리됩니다. Document AI를 건너뛰는 경로에는 이 필드가 존재하지 않기 때문입니다. 기억하세요: 분기는 *모든* 경로에서 실행된 기능의 필드만 읽을 수 있습니다.먼저 검증한 다음, `{ "graph": }` 형태로 `…/workflow-graph/` endpoint에 전송합니다. 처음부터 **새** 워크플로를 만들려면 MCP의 `didit_workflow_set_graph`를 사용하세요. 기존 워크플로를 **수정**하려면 `didit_workflow_edit_graph`를 사용하세요. 이 도구는 작은 작업 단위로 적용되며, 기존 노드와 허용 목록을 보존합니다. 자세한 내용은 [Didit MCP](https://docs.didit.me/ko/integration/mcp/tools.md)를 참고하세요. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/workflows/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/workflows/: post: tags: - Workflows summary: 워크플로 생성 description: >- 단순한 워크플로를 생성합니다. `features`를 실행 순서대로 전송하십시오(순서 지정 규칙 적용). 기본값은 `published` v1입니다. 본문에는 `SimpleWorkflowRequest`에 나열된 필드만 허용됩니다. 다른 모든 키(`workflow_type` 포함)는 400으로 거부됩니다. 멱등성이 없습니다. 각 호출은 새 워크플로를 생성합니다. 애플리케이션당 최대 50개의 워크플로를 지원합니다. operationId: create_workflow requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SimpleWorkflowRequest' examples: Simple KYC: summary: 신분증 인증, 라이브니스 감지 및 얼굴 대조 선형 워크플로 value: workflow_label: Standard KYC features: - feature: OCR config: duplicated_user_action: review - feature: LIVENESS config: face_liveness_method: passive - feature: FACE_MATCH config: face_match_score_decline_threshold: 40 face_match_score_review_threshold: 60 KYC + AML: summary: 신분증 인증 후 AML 실행 value: workflow_label: KYC with AML features: - feature: OCR - feature: AML config: aml_score_review_threshold: 70 aml_score_approve_threshold: 30 Questionnaire workflow: summary: POST /v3/questionnaires/로 생성된 설문지 실행 value: workflow_label: Source of Funds features: - feature: QUESTIONNAIRE config: questionnaire_uuid: 11111111-2222-3333-4444-555555555555 review_questionnaire_manually: true responses: '201': description: >- 워크플로가 생성되었습니다. 응답 본문은 축약된 목록 항목이 아닌, 전체 워크플로 구성(`GET /v3/workflows/{settings_uuid}/`에서 반환되는 동일한 원시 `VerificationSettings` 직렬화 형태: 모든 기능 토글, 임계값, 작업 및 생성된 `workflow_graph`를 포함한 약 190개 필드)입니다. 나중에 세션 생성 호출에서 참조할 수 있도록 `uuid`(`workflow_id`로도 제공됨)를 저장하십시오. 참고: `features`는 `" + "`로 연결된 문자열이며 가격은 JSON 숫자입니다. content: application/json: schema: $ref: '#/components/schemas/WorkflowDetail' examples: Created (abbreviated): summary: 전체 구성 객체의 주요 필드 value: uuid: c3d4e5f6-7890-12cd-ef34-333333333333 workflow_id: c3d4e5f6-7890-12cd-ef34-333333333333 workflow_label: Standard KYC workflow_type: null is_default: false is_archived: false total_price: 0.15 min_price: 0.15 max_price: 0.15 features: OCR + LIVENESS + FACE_MATCH is_simple_workflow: false is_editable: false workflow_url: https://verify.didit.me/u/w9TkPOx8RWG3UAz5ZRQGVQ workflow_graph: start_node: ocr nodes: ... one node per feature plus a final status node ... max_retry_attempts: 3 retry_window_days: 7 session_expiration_time: 604800 version: 1 status: published published_at: '2026-05-17T10:30:00Z' created_at: '2026-05-17T10:30:00Z' updated_at: '2026-05-17T10:30:00Z' '400': description: >- 유효성 검사 오류입니다. 일반적인 원인: 허용된 화이트리스트 외의 최상위 키(예: `workflow_type`), 알 수 없는 `feature` 값, 종속성보다 앞에 배치된 기능(예: `OCR` 앞에 `FACE_MATCH`), 첫 번째 단계로 사용된 수동적 기능(`AML`, `IP_ANALYSIS`, `DATABASE_VALIDATION`, `KYB_KEY_PEOPLE`), 해당 애플리케이션에 존재하지 않는 `config.questionnaire_uuid`를 가진 `QUESTIONNAIRE` 기능, 서명할 문서 없이 프로덕션에 배포되는 `SIGNATURE` 기능, Advanced(AES)를 사용할 수 없는 상태에서 `signature_level: "aes"`로 설정된 `SIGNATURE` 기능(`aes_not_available`, 워크플로의 `signature_availability` 참조), 또는 범위를 벗어난 임계값입니다. 본문은 DRF 유효성 검사 오류 객체이며, 키는 필드 이름이고 값은 사람이 읽을 수 있는 메시지 배열입니다. content: application/json: examples: Advanced (AES) not available: value: features: signature_level: - >- Node 'signature': Advanced (AES) is not available yet (aes_not_available). Signature step with no document: value: features: non_field_errors: - >- Node 'signature': Add a document to sign, or let each session bring its own. Missing feature: value: features: - At least one feature is required. Unknown top-level field: value: workflow_type: - >- The v3 workflow API only accepts `workflow_label`, `is_default`, `status`, `features`, `is_white_label_enabled`, `is_desktop_allowed`, `max_retry_attempts`, `retry_window_days`, `session_expiration_time`, `face_liveness_max_attempts`, `face_match_max_attempts`. Unknown feature: value: features: - >- Invalid feature 'FOO'. Allowed values: AGE_ESTIMATION, AML, DATABASE_VALIDATION, EMAIL_VERIFICATION, FACE_MATCH, IP_ANALYSIS, KYB_DOCUMENTS, KYB_KEY_PEOPLE, KYB_REGISTRY, LIVENESS, NFC, OCR, PHONE_VERIFICATION, PROOF_OF_ADDRESS, QUESTIONNAIRE. Ordering: value: features: - 'Feature ''FACE_MATCH'' must appear after one of: OCR.' Questionnaire not found: value: features: >- Questionnaire '11111111-2222-3333-4444-555555555555' was not found for this application. Create the questionnaire first, then use its questionnaire_id. '403': description: >- API 키가 누락되었거나, 형식이 잘못되었거나, 만료되었거나, 다른 애플리케이션으로 스코프가 지정되었습니다. [Auth API](/ko/auth-api/get-credentials)를 통해 갱신하고 다시 시도해 주세요. content: application/json: examples: Invalid token: value: detail: You do not have permission to perform this action. '415': description: >- 지원되지 않는 미디어 유형입니다. `Content-Type: application/json`으로 설정하고 JSON 본문을 전송하십시오. '429': description: 속도 제한을 초과했습니다. 지수 백오프로 재시도하세요. '500': description: 워크플로를 생성하는 동안 예기치 않은 서버 오류가 발생했습니다. 안전하게 재시도할 수 있습니다. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/workflows/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "workflow_label": "Standard KYC", "features": [ {"feature": "OCR"}, {"feature": "LIVENESS", "config": {"face_liveness_method": "passive"}}, {"feature": "FACE_MATCH", "config": {"face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60}} ] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.workflows.create( workflow_label="Standard KYC", features=[{ "feature": "OCR", "config": {"duplicated_user_action": "review"}, }, { "feature": "LIVENESS", "config": {"face_liveness_method": "passive"}, }, { "feature": "FACE_MATCH", "config": {"face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60}, }], ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.workflows.create({ workflow_label: "Standard KYC", features: [{ feature: "OCR", config: { duplicated_user_action: "review" }, }, { feature: "LIVENESS", config: { face_liveness_method: "passive" }, }, { feature: "FACE_MATCH", config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 }, }], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Create(ctx, didit.SimpleWorkflowRequest{\n\tWorkflowLabel: didit.String(\"Standard KYC\"),\n\tFeatures: []didit.SimpleWorkflowFeature{{\n\t\tFeature: \"OCR\",\n\t\tConfig: didit.Some(map[string]any{\"duplicated_user_action\": \"review\"}),\n\t}, {\n\t\tFeature: \"LIVENESS\",\n\t\tConfig: didit.Some(map[string]any{\"face_liveness_method\": \"passive\"}),\n\t}, {\n\t\tFeature: \"FACE_MATCH\",\n\t\tConfig: didit.Some(map[string]any{\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import java.util.Map; import me.didit.Didit; import me.didit.types.SimpleWorkflowFeature; import me.didit.types.SimpleWorkflowRequest; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.workflows().create(SimpleWorkflowRequest.builder() .workflowLabel("Standard KYC") .features(List.of( SimpleWorkflowFeature.builder() .feature(SimpleWorkflowFeature.Feature.of("OCR")) .config(Map.of("duplicated_user_action", "review")) .build(), SimpleWorkflowFeature.builder() .feature(SimpleWorkflowFeature.Feature.of("LIVENESS")) .config(Map.of("face_liveness_method", "passive")) .build(), SimpleWorkflowFeature.builder() .feature(SimpleWorkflowFeature.Feature.of("FACE_MATCH")) .config(Map.of("face_match_score_decline_threshold", 40, "face_match_score_review_threshold", 60)) .build())) .build()); System.out.println(result); - lang: php label: PHP source: |- workflows->create([ 'workflow_label' => 'Standard KYC', 'features' => [[ 'feature' => 'OCR', 'config' => ['duplicated_user_action' => 'review'], ], [ 'feature' => 'LIVENESS', 'config' => ['face_liveness_method' => 'passive'], ], [ 'feature' => 'FACE_MATCH', 'config' => ['face_match_score_decline_threshold' => 40, 'face_match_score_review_threshold' => 60], ]], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.workflows.create( workflow_label: "Standard KYC", features: [{ feature: "OCR", config: { duplicated_user_action: "review" }, }, { feature: "LIVENESS", config: { face_liveness_method: "passive" }, }, { feature: "FACE_MATCH", config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 }, }] ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Workflows.CreateAsync(new SimpleWorkflowRequest { WorkflowLabel = "Standard KYC", Features = new SimpleWorkflowFeature[] { new() { Feature = "OCR", Config = new Dictionary { ["duplicated_user_action"] = "review" }, }, new() { Feature = "LIVENESS", Config = new Dictionary { ["face_liveness_method"] = "passive" }, }, new() { Feature = "FACE_MATCH", Config = new Dictionary { ["face_match_score_decline_threshold"] = 40, ["face_match_score_review_threshold"] = 60 }, }, }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: SimpleWorkflowRequest: type: object description: >- 단순한 선형 워크플로를 생성합니다. API는 이 기능 목록을 내부적으로 노드 기반 워크플로 그래프로 변환합니다. 엄격한 필드 허용 목록: 여기에 나열되지 않은 모든 키(`workflow_type` 포함)는 400으로 거부됩니다. required: - features properties: workflow_label: type: string maxLength: 50 default: ID Verification description: >- 워크플로의 표시 이름(최대 50자)입니다. 생략 시 기본값은 `"ID Verification"`입니다 — 워크플로를 구분할 수 있도록 항상 설정하세요. example: Standard KYC is_default: type: boolean description: 이 워크플로를 새 세션의 기본값으로 설정합니다. status: type: string enum: - draft - published description: >- 세션에 바로 사용할 수 있도록 게시된 워크플로를 생성하려면 이 필드를 생략하세요. 게시하지 않고 저장하려는 경우에만 `draft`를 사용하세요. features: type: array minItems: 1 description: 실행 순서에 따른 인증 기능입니다. API는 각 항목을 다음 항목에 연결하고 마지막 상태 노드 하나를 자동으로 추가합니다. items: $ref: '#/components/schemas/SimpleWorkflowFeature' is_white_label_enabled: type: boolean description: 이 워크플로로 생성된 세션에 화이트 라벨 맞춤 설정을 활성화합니다. default: false is_desktop_allowed: type: boolean description: 데스크톱 브라우저에서 인증 워크플로가 실행되도록 허용합니다. default: false max_retry_attempts: type: integer minimum: 0 maximum: 10 default: 3 description: 거부된 인증 후 허용되는 최대 재시도 횟수입니다. `0`은 첫 번째 거부 후 사용자를 차단합니다. retry_window_days: type: integer minimum: 1 maximum: 365 nullable: true default: 7 description: 재시도 횟수를 계산하는 데 사용되는 롤링 윈도우 일수. `null`은 전체 기간 제한을 적용합니다. face_liveness_max_attempts: type: integer minimum: 1 maximum: 3 default: 3 description: >- 세션당 최대 라이브니스 제출 횟수입니다. 기본값은 3(초기 시도 1회 + 재시도 2회)입니다. 기능 수준 구성에서 이를 재정의하지 않는 한, 이 값은 생성된 라이브니스 및 연령 추정 워크플로 노드에도 복사됩니다. face_match_max_attempts: type: integer minimum: 1 maximum: 3 default: 3 description: >- 세션당 최대 얼굴 대조 제출 횟수입니다. 기본값은 3(초기 시도 1회 + 재시도 2회)입니다. 기능 수준 구성에서 이를 재정의하지 않는 한, 이 값은 생성된 얼굴 대조 워크플로 노드에도 복사됩니다. session_expiration_time: type: integer minimum: 3600 maximum: 2419200 default: 604800 description: 완료되지 않은 세션이 만료되기까지 남은 시간(초)입니다. 최소 1시간(3600), 최대 4주(2419200). WorkflowDetail: type: object description: >- 아래 필드는 타입이 지정되어 있습니다. 또한 이 객체는 워크플로 설정의 다른 모든 열(기능 토글, 임계값, 경고 작업, 허용된 문서, 콜백)을 추가 속성으로 전달합니다. `workflow_type`에 적용되지 않는 필드는 `null`입니다. properties: uuid: type: string format: uuid description: 버전별 식별자(`settings_uuid`)입니다. 워크플로의 모든 버전에는 고유한 식별자가 있습니다. workflow_id: type: string format: uuid description: 워크플로의 모든 버전에서 공유되는 안정적인 식별자입니다. 이 식별자로 생성된 세션은 게시된 최신 버전을 사용합니다. workflow_label: type: string description: 워크플로의 표시 이름입니다. workflow_type: type: string nullable: true enum: - kyc - kyb - adaptive_age_verification - biometric_authentication - address_verification - questionnaire_verification - email_verification - phone_verification - null description: 워크플로 템플릿입니다. 템플릿 없이 생성된 그래프 워크플로의 경우 `null`입니다. is_default: type: boolean description: 이 워크플로가 애플리케이션의 기본 워크플로인지 여부입니다. is_archived: type: boolean description: 보관된 워크플로는 새 세션을 시작할 수 없습니다. version: type: integer description: 워크플로 내의 버전 번호입니다. status: type: string enum: - draft - published description: 초안 버전은 편집할 수 있으며, 게시된 버전은 변경할 수 없고 새 세션에 사용됩니다. published_at: type: string format: date-time nullable: true description: 이 버전이 게시된 시점입니다. 초안의 경우 `null`입니다. is_simple_workflow: type: boolean description: 워크플로에 사용자 지정 `workflow_graph`가 없는 경우 `true`입니다. is_editable: type: boolean description: '`draft` 버전인 경우에만 `true`입니다.' workflow_url: type: string format: uri description: 이 워크플로로 세션을 시작하는 공개 URL입니다. workflow_graph: type: object nullable: true additionalProperties: true description: 워크플로의 그래프 구조(노드 및 에지)입니다. 단순 워크플로의 경우 `null`입니다. features: type: string description: '`" + "`로 연결된 활성화된 기능입니다(예: `"OCR + LIVENESS"`).' total_price: type: number nullable: true description: 세션당 가격입니다. 그래프 워크플로의 경우 가장 비싼 경로의 가격입니다. min_price: type: number nullable: true description: 워크플로에서 가장 저렴한 경로의 가격입니다. max_price: type: number nullable: true description: 워크플로에서 가장 비싼 경로의 가격입니다. special_add_on_prices: type: object nullable: true additionalProperties: true description: 조직별 부가 기능 가격이며, 설정되지 않은 경우 `null`입니다. max_retry_attempts: type: integer description: 거부된 인증 후 허용되는 재시도 횟수입니다. retry_window_days: type: integer nullable: true description: 재시도가 허용되는 일수. session_expiration_time: type: integer description: 완료되지 않은 세션이 만료되기까지 남은 시간(초). questionnaire: type: object nullable: true additionalProperties: true description: 워크플로에 연결된 설문지 또는 `null`입니다. kyb_role_settings: type: array items: type: object additionalProperties: true description: KYB 주요 인물에 대한 역할별 인증 설정입니다. created_at: type: string format: date-time updated_at: type: string format: date-time signature_availability: type: object description: >- 현재 서명 가능한 전자 서명 등급입니다. `signature_level`을 설정하기 전에 확인하십시오. `kyc`, `kyb` 및 그래프 워크플로에서 반환됩니다. properties: simple: type: boolean description: Simple은 항상 사용할 수 있습니다. aes: type: boolean description: >- 고급 전자 서명(AES)으로 지금 서명할 수 있는지 여부입니다. `false`인 동안 `signature_level: "aes"`로 새 단계를 저장하면 `aes_not_available` 오류와 함께 거부됩니다. qes: type: boolean description: 적격 전자 서명(QES)으로 지금 서명할 수 있는지 여부입니다. 적격 제공업체가 연결될 때까지 `false`입니다. is_bank_verification_enabled: type: boolean description: >- 단순 KYC 또는 KYB 워크플로가 은행 확인을 실행하는지 여부입니다. 연락처 단계(및 위치 확인) 이후, 데이터베이스 검증, AML 및 IP 분석 이전에 실행됩니다. 은행 확인은 아직 일반에 공개되지 않았으며, 활성화되지 않은 환경에서 켜려고 하면 거부됩니다. bank_verification_config: type: object additionalProperties: true description: >- `BANK_VERIFICATION` 노드가 사용하는 것과 동일한 키(예: `bank_countries` 및 `bank_method_order`)를 사용하는 단순 워크플로의 은행 인증 설정입니다. 알 수 없는 키는 삭제됩니다. 모든 키는 선택 사항이며 누락된 키는 기본값을 유지하므로 `{}`는 모든 기본값을 의미합니다. [은행 인증 설정](/ko/management-api/workflows/feature-configs#은행-인증)을 참조하십시오. example: {} is_geolocation_enabled: type: boolean description: >- 단순 KYC 워크플로가 위치 확인을 실행하는지 여부입니다. 연락처 단계 이후, 은행 확인 및 데이터베이스 검증 이전에 실행됩니다. 기업(KYB) 워크플로에서는 실행할 수 없습니다. geolocation_config: type: object additionalProperties: true description: >- 간단한 워크플로의 위치 확인 설정으로, `GEOLOCATION` 노드가 사용하는 것과 동일한 키(예: `is_geolocation_geofencing_enabled` 및 `geolocation_max_attempts`)를 갖습니다. 알 수 없는 키는 삭제됩니다. 모든 키는 선택 사항이며 누락된 키는 기본값을 유지하므로 `{}`는 모든 기본값을 의미합니다. example: {} additionalProperties: true SimpleWorkflowFeature: type: object required: - feature properties: feature: type: string description: 실행할 기능입니다. 여기에 표시된 대문자 값을 사용하십시오. enum: - OCR - NFC - LIVENESS - FACE_MATCH - PROOF_OF_ADDRESS - QUESTIONNAIRE - DOCUMENT_AI - PHONE_VERIFICATION - EMAIL_VERIFICATION - DATABASE_VALIDATION - AML - IP_ANALYSIS - AGE_ESTIMATION - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - SIGNATURE config: type: object description: >- 기능별 설정입니다. `QUESTIONNAIRE`의 경우 설문지 생성 endpoint에서 반환된 `questionnaire_id`와 함께 `questionnaire_uuid`를 포함합니다. `SIGNATURE`의 경우 라이브로 전환되는 워크플로에 서명할 문서가 필요합니다. 각 세션이 자체 문서를 가져올 수 있도록 `signature_documents_source`를 `session` 또는 `both`로 설정하거나, `status: "draft"`를 전송하고 게시하기 전에 문서를 추가하세요. 워크플로에서 `signature_availability.aes`가 `false`인 동안에는 `signature_level: "aes"`가 `aes_not_available` 오류와 함께 거부됩니다. `OCR`의 경우 `methods`는 각 국가에서 사용할 수 있는 신분증 인증 방법을 선택합니다(문서 촬영, 정부 또는 기타 공신력 있는 출처를 통한 비문서 조회, 디지털 신원 지갑). 생략할 경우 모든 국가는 문서 촬영 전용이 됩니다. `SIGNATURE`의 경우 [전자 서명 설정](/ko/management-api/workflows/feature-configs#전자-서명)을 참조하세요. 현재 `signature_level`은 `simple`(기본값, 신분증 인증, 이메일 또는 전화번호 불필요) 및 `aes`를 허용하며, 워크플로 문서 및 해당 필드는 콘솔에서 관리되므로 API를 통해 세션당 문서 및 필드를 `signature_documents_source: "session"`으로 전송하세요. additionalProperties: true label: type: string description: 이 워크플로 노드에 대한 선택적 내부 라벨입니다. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.