> ## 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 또는 KYB 인증 시작 > Didit의 세션 생성 API로 KYC 및 KYB 인증 세션을 시작하세요. POST /v3/session/ 단일 엔드포인트, 사용량 기반 요금, 2초 미만 추론, 월 $10 무료 크레딧을 제공합니다. 세션 생성 프롬프트 프롬프트를 클립보드에 복사 \

\`Create a verification session via Didit's REST API.

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

Authentication:
Use the x-api-key header with your Didit API key. The workflow's type (KYC or KYB) determines which kind of session is created — there is no separate endpoint for KYB.

Request body:
\- workflow_id (string, UUID, required) — Stable workflow UUID from /v3/workflows/. KYC workflows create User Verification sessions; KYB workflows create Business Verification sessions.
\- vendor_data (string, optional) — Your stable identifier for the entity (user or business). Strongly recommended: it binds the session to a User or Business entity and is used for duplicate detection across sessions.
\- callback (string, URL, optional): Where the hosted flow redirects the user when finished. Didit appends ?verificationSessionId={session_id}&status={status}. Falls back to the workflow default. When the application has allowed domains (allowed_domains on PATCH /v3/webhook/), an http or https callback must be on one of those origins (same scheme, host and port), otherwise creation fails with 400 on callback: "callback must be on one of the application's allowed domains: https://app.example.com". Custom URL schemes (app deep links such as myapp://) are always accepted. A workflow-default callback outside the allowed domains is not used for the redirect.
\- callback_method (string, optional, default "initiator") — One of "initiator", "completer", "both". Use "both" if the callback sometimes fails to fire.
\- metadata (object, optional) — Arbitrary JSON echoed back in responses and webhooks. Not shown to the user.
\- tags (array of strings, optional): Tags added to the session when it is created, by name, for example ["VIP", "ONBOARDING Q4"]. Up to 10, each up to 50 characters. Names are case-insensitive and stored in upper case; a name that does not exist yet in the application is created as a new tag. The tags show on the session in the console, where you can filter by them, and come back in the create response.
\- language (string, optional) — ISO 639-1 code for the verification UI (en, es, fr, de, pt, etc.). Defaults to browser detection.
\- contact_details (object, optional) — { email, send_notification_emails, email_lang, phone }. Pre-fills phone/email steps and (optionally) sends notification emails.
\- expected_details (object, optional) — Expected first_name, last_name, date_of_birth, nationality (ISO-3), id_country (ISO-3), expected_document_types (e.g. ["P","ID","DL","RP","SSC"]). Mismatches surface as decision warnings. For Business Verification (KYB) workflows, pass the business fields instead — company_name, registry_country, registration_number — to pre-fill the company registry search; registry_country is ISO 3166-1 alpha-2 and can include the state for state-level registries (e.g. "US-CA"), same format as the KYB Registry Search country_code. Person-level fields are ignored on KYB sessions.
\- portrait_image (string, base64, conditional) — Reference face for Biometric Authentication workflows (and graph workflows where Face Match runs before ID Verification). Max 2MB; JPEG, PNG, WebP, or TIFF. Optional when the vendor_data user already has a stored face: Didit reuses it automatically (approved liveness face, then ePassport chip photo, then ID document portrait, then a manually enrolled profile face). If omitted and no stored face exists, creation fails with 400. Ignored for other workflow types.
\- multi_account_segment (string, optional, max 64 chars) — Duplicate-detection realm inside your own organization. Duplicate face checks only compare this session against other sessions carrying the same segment, so an organization that runs separate account bases (personal vs business, or one per sub-client) does not see a person who legitimately holds one account in each reported as a duplicate. Omit it to use the single default realm — which is what every session uses today, so existing integrations are unaffected. Blocklist and allowlist matching ignore this field: a blocklisted face stays blocklisted in every segment.
\- sandbox_scenario (string, optional, sandbox applications only): Scenario slug from the sandbox catalog (GET /v1/sandbox/scenarios/). Expands the scenario's bundled magic values onto contact_details/expected_details so the session reproduces that outcome. Rejected with 400 on live applications. You can also arm or re-arm a scenario after create, as long as the session is still Not Started, via POST /v3/session/{session_id}/sandbox/arm/. See /integration/sandbox-testing.
\- user_state (string, optional, max 16 chars): Where the person lives, when you know it: an ISO 3166-2 code (US-IL) or a US state code or name (IL, Illinois). In Auto consent mode, Illinois, Texas or Colorado makes the flow ask for explicit biometric consent before the first face capture. 400 on an unrecognized value.
\- biometric_consent (object, optional): Consent you already collected: { given_at (ISO 8601, not in the future), text_version (max 64 chars) }. The flow does not ask again; the decision records it as given with trigger customer_collected.
\- sign (object, optional): { documents: [ { title, file_name, content_base64, fields } ], field_values: { : value } }. documents is for a workflow whose E-signature step takes documents from the session (signature_documents_source "session" or "both"). file_name ends in .pdf or .docx; content_base64 is the file in base64. Up to 20 documents and 50 MB in total; a PDF up to 20 MB and 100 pages, without a password, scripts or attachments; a Word file (.docx) up to 20 MB, converted to PDF while the request runs, at most 5 per session. fields is optional (up to 200 per document): signature, initials, full_name, date_signed, text, checkbox, email or data fields, each with a key unique in its document (^[a-z][a-z0-9_]{0,63}$), placed by page, x, y, width and height, or by anchor text ({ text, occurrence, offset_x, offset_y, width, height }). role defaults to the step's signer. field_values fills the fields whose prefill is "api.", on workflow and session documents alike: strings of 1 to 500 characters, booleans for checkboxes. 400 when the workflow has no E-signature step, takes workflow documents only and you sent documents, or needs session documents you didn't send; field_anchor_not_found, field_value_unknown, field_value_missing or field_value_invalid for fields and values. See /core-technology/electronic-signature/overview.

Idempotency:
Within one application, only one non-finished session can exist per (workflow_id, vendor_data). Calling create again with the same pair returns the existing session (and updates its callback + metadata, and adds any tags you send) instead of creating a duplicate. If you send sign again, its documents, fields and field values must be identical (same order, titles, file names, content, fields and values), or the call returns 400 { "sign": "signature_document_changed" }.

curl example:
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "",
"vendor_data": "user-42",
"callback": "https://yourapp.com/callback",
"metadata": { "plan": "premium" }
}'

Response (201 Created) — keys you must handle:
\- session_id (UUID) — use this on every subsequent /v3/session/{session_id}/... call.
\- session_kind ("user" | "business") — discriminator, dispatch on this.
\- session_number (int) — human-friendly per-application sequence.
\- session_token (string) — short-lived, embedded in the hosted URL. Treat as secret.
\- url (string) — hosted verification URL. Redirect the end user here. (Field name is "url", NOT "verification_url".)
\- status (string) — newly created sessions return "Not Started".
\- workflow_id, workflow_version, vendor_data, metadata, callback — echoed back.

See /reference/data-models for the full schema.

Failure modes:
\- 400 — { "workflow_id": ["Invalid workflow_id."] } when the UUID is unknown.
\- 400 — { "vendor_data": ["This user or business has been blocked and cannot create new verification sessions."] } when blocklisted.
\- 400 — { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } when out of credits.
\- 400 — { "portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first." } on a Face Match workflow when portrait_image is omitted and the vendor_data user has no stored face.
\- 401 — invalid or missing API key.
\- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks write:sessions.
\- 429 — rate limited (600 successful calls/minute per token/IP). Honour Retry-After.

Disclosure & consent:
This endpoint generates a URL — it does not record that you obtained user consent. Show your privacy notice and any biometric-specific consent in your own UX before redirecting to the hosted flow.
For people covered by Illinois, Texas or Colorado law, the hosted flow and native SDK 4.10.0 or later can ask for explicit biometric consent before the selfie; native SDKs below 4.10.0 cannot show that step. See /getting-started/biometric-consent.

Next step:
After the user finishes (status changes to Approved / Declined / In Review), call GET https://verification.didit.me/v3/session/{session_id}/decision/ for the full decision — see /sessions-api/retrieve-session.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\
붙여넣을 곳 ## KYC 및 KYB 지원하나의 endpoint로 사용자 인증(KYC) 세션과 기업 확인(KYB) 세션을 모두 생성합니다. **워크플로의 유형**에 따라 생성되는 세션의 종류가 결정됩니다.- KYC 워크플로의 `workflow_id`를 전달하면 사용자 인증(KYC) 세션이 생성됩니다. 응답에는 `session_kind: "user"`가 포함됩니다. - KYB 워크플로의 `workflow_id`를 전달하면 기업 확인(KYB) 세션이 생성됩니다. 응답에는 `session_kind: "business"`가 포함됩니다.워크플로는 *Workflows → Create workflow*에서 콘솔을 통해 구성합니다. 워크플로는 생성 시점에 KYC 또는 KYB 중 하나로 정해지며, 이후에는 유형을 바꿀 수 없습니다.## 예제> [tab] 사용자 인증(KYC) > > ```bash theme={null} > 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_KYC_WORKFLOW_ID", > "vendor_data": "user-42", > "callback": "https://yourapp.com/callback" > }' > ``` > > **응답 (201 Created):** > > ```json theme={null} > { > "session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a", > "session_kind": "user", > "session_number": 1024, > "session_token": "...", > "url": "https://verify.didit.me/session/...", > "status": "Not Started", > "workflow_id": "YOUR_KYC_WORKFLOW_ID", > "vendor_data": "user-42" > } > ```> [tab] 기업 확인(KYB) > > ```bash theme={null} > 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_KYB_WORKFLOW_ID", > "vendor_data": "biz-acme-001", > "callback": "https://yourapp.com/callback" > }' > ``` > > **응답 (201 Created):** > > ```json theme={null} > { > "session_id": "bs-01HJX1...", > "session_kind": "business", > "session_number": 89, > "session_token": "...", > "url": "https://verify.didit.me/session/...", > "status": "Not Started", > "workflow_id": "YOUR_KYB_WORKFLOW_ID", > "vendor_data": "biz-acme-001" > } > ```## 전자 서명 문서워크플로에 세션의 문서를 사용하는 [전자 서명](https://docs.didit.me/ko/core-technology/electronic-signature/overview.md) 단계가 있으면(`signature_documents_source`가 `session` 또는 `both`로 설정된 경우) 해당 문서를 `sign.documents`에 담아 보냅니다. 각 문서는 base64로 인코딩한 파일이므로, Didit이 URL에서 파일을 가져올 필요가 없습니다.```json theme={null} { "workflow_id": "YOUR_WORKFLOW_ID", "vendor_data": "user-42", "sign": { "documents": [ { "title": "Loan agreement", "file_name": "loan-agreement.pdf", "content_base64": "JVBERi0xLjcKJc...", "fields": [ { "key": "borrower_signature", "type": "signature", "label": "Borrower signature", "page": 3, "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.06 }, { "key": "date_signed", "type": "date_signed", "label": "Date", "page": 3, "x": 0.6, "y": 0.8, "width": 0.2, "height": 0.03, "date_format": "DD/MM/YYYY" }, { "key": "loan_amount", "type": "data", "label": "Loan amount", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.loan_amount" }, { "key": "initials", "type": "initials", "anchor": { "text": "[[initials]]", "occurrence": "all", "offset_x": 0, "offset_y": -0.005, "width": 0.12, "height": 0.04 } } ] } ], "field_values": { "loan_amount": "12,000 EUR" } } } ```| 필드 | 규칙 | | - | - | | `title` | 서명자에게 표시됩니다. 1\~255자입니다. 기본값은 `file_name`입니다. | | `file_name` | 필수입니다. `.pdf` 또는 `.docx`로 끝나야 합니다. 1\~255자입니다. | | `content_base64` | 필수입니다. PDF는 최대 20MB, 100페이지까지 가능하며 비밀번호, 스크립트 또는 첨부 파일이 없어야 합니다. Word 파일은 최대 20MB까지 가능하며, 요청이 처리되는 동안 PDF로 변환됩니다. 변환은 최대 25초 안에 완료되어야 하며, 변환된 PDF에도 같은 제한이 적용됩니다. 세션당 Word 파일은 최대 5개입니다. | | `fields` | 선택 사항입니다. 문서에 배치할 [필드](https://docs.didit.me/ko/core-technology/electronic-signature/overview.md#문서의-필드)를 최대 200개까지 `id`를 제외한 필드 형태로 보낼 수 있습니다. 각 필드에는 `key`와 `type`이 필요하며, 위치(`page`, `x`, `y`, `width`, `height`) 또는 [`anchor`](#앵커-텍스트로-필드-배치) 중 하나가 필요합니다. `role`의 기본값은 단계의 서명자이며, `required`와 `label`의 기본값은 유형에 따라 정해집니다. Didit은 필드가 놓인 위치로 `position`을 설정합니다. 페이지와 위치는 PDF를 기준으로 하며, Word 파일의 경우 변환된 PDF를 기준으로 합니다. |`fields`를 생략하면 서명자는 문서를 읽고 동의합니다.### 앵커 텍스트로 필드 배치위치 대신 필드에 `anchor`를 지정할 수 있습니다. 앵커는 필드가 놓일 위치를 표시하는 문서 내 텍스트입니다. 세션마다 생성하는 문서, 예를 들어 Word 템플릿으로 만든 문서에 적합합니다. 워크플로 문서의 경우에는 콘솔에서 필드를 배치하세요.| `anchor` 속성 | 규칙 | | - | - | | `text` | 1\~64자이며, 문서의 텍스트에서 검색합니다. Word 파일의 경우 변환된 PDF에서 검색합니다. | | `occurrence` | `first`(기본값)는 첫 번째 일치 위치에 필드 하나를 배치합니다. `all`은 일치하는 위치마다 필드 하나를 배치하며, 두 번째 이후 필드의 키에는 `_2`, `_3` 등이 붙습니다. | | `offset_x`, `offset_y` | 페이지에 대한 비율입니다. 필드의 왼쪽 위 모서리는 앵커 텍스트의 왼쪽 위 모서리에 이 오프셋을 더한 위치입니다. | | `width`, `height` | 필드의 크기이며, 페이지에 대한 비율입니다. |문서에 앵커 텍스트가 없으면 호출은 `400`과 함께 `field_anchor_not_found`, 그리고 해당 필드의 키를 반환합니다. Didit은 PDF에서 앵커 텍스트를 제거하지 않으므로, 페이지 배경과 같은 색으로 작성하세요.### 필드 값`sign.field_values`는 워크플로 문서와 세션 문서 모두에서 `prefill`이 `api.`인 모든 필드의 값을 설정합니다. 객체이며, 키는 이러한 `` 이름입니다. 값은 `text` 및 `data` 필드의 경우 1\~500자의 문자열이고, `checkbox` 필드의 경우 불리언입니다.```json theme={null} { "workflow_id": "YOUR_WORKFLOW_ID", "vendor_data": "user-42", "sign": { "field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" } } } ```| 오류(`400`) | 발생 조건 | | - | - | | `field_value_unknown` | 어떤 필드도 사용하지 않는 키입니다. | | `field_value_missing` | `api.`에 값이 없는 필수 필드입니다. | | `field_value_invalid` | 필드의 [검증](https://docs.didit.me/ko/core-technology/electronic-signature/overview.md#유효성-검사) 규칙에 맞지 않는 값입니다. |### 오류 및 반복 호출세션은 문서를 최대 20개, 총 50MB까지 받을 수 있습니다. 다음의 경우 호출은 `sign` 오류와 함께 `400`을 반환합니다.- 워크플로에 전자 서명 단계가 없는 경우 - `sign.documents`를 보냈는데 해당 단계가 워크플로 문서만 받는 경우 - 단계가 세션 문서만 받는데 세션 문서를 보내지 않았거나, 워크플로 문서가 없는데 세션 문서도 보내지 않은 경우 - 문서가 너무 크거나, 올바른 base64가 아니거나, 지원되지 않는 파일인 경우 - Word 파일이 `signature_document_not_supported`로 거부되었거나 변환할 수 없어 `signature_document_conversion_failed`를 반환하는 경우. 각 오류의 `reason`은 [지원 파일](https://docs.didit.me/ko/core-technology/electronic-signature/overview.md#지원되는-파일)에 나열되어 있습니다. - 필드가 잘못되었거나, 앵커를 찾을 수 없거나(`field_anchor_not_found`), [필드 값](#필드-값)이 거부된 경우같은 `workflow_id`와 `vendor_data`로 생성을 다시 호출하면 대기 중인 세션이 반환됩니다. 그 호출에 `sign`이 포함되어 있다면, 문서, 필드, 필드 값은 첫 번째 호출과 완전히 같아야 합니다(순서, 제목, 파일 이름, 내용, 필드, 값 모두 동일해야 합니다). 하나라도 다르면 `{"sign": "signature_document_changed"}`와 함께 `400`이 반환됩니다. 이 경우 다른 `vendor_data`를 사용하거나, 대기 중인 세션이 끝날 때까지 기다리세요.## 샌드박스 시나리오로 테스트샌드박스 모드 애플리케이션에서 `sandbox_scenario`를 전달하면, 실제 제공자나 잔액을 사용하지 않고 결정된 결과(승인, 특정 거부, 또는 검토 중 시나리오)를 미리 설정할 수 있습니다.```json theme={null} { "workflow_id": "YOUR_SANDBOX_WORKFLOW_ID", "sandbox_scenario": "decline_document_expired" } ````sandbox_scenario`는 라이브 애플리케이션에서 `400`으로 거부됩니다. 세션을 생성하는 시점에 결과를 아직 모른다면, 세션이 여전히 `Not Started` 상태일 때 나중에 `POST /v3/session/{session_id}/sandbox/arm/`로 시나리오를 설정(또는 다시 설정)할 수 있습니다. 호스티드 흐름의 사전 시나리오 선택기도 이 엔드포인트를 사용합니다. 전체 시나리오 목록, 매직 값 레지스트리, arm endpoint의 요청 및 응답 형식은 [샌드박스 및 테스트 데이터](https://docs.didit.me/ko/integration/sandbox-testing.md)에서 확인하세요.## `vendor_data`는 세션을 엔티티에 연결합니다- KYC 워크플로의 경우 [사용자 엔티티](https://docs.didit.me/ko/entities/users/overview.md)에 연결됩니다. 사용자가 없으면 자동으로 생성됩니다. - KYB 워크플로의 경우 [기업 엔티티](https://docs.didit.me/ko/entities/businesses/overview.md)에 연결됩니다. 새로운 기업이면 자동으로 생성됩니다.자세한 내용은 [vendor data 연결](https://docs.didit.me/ko/entities/vendor-data-linking.md)에서 확인하세요.## 일리노이주, 텍사스주 및 콜로라도주의 생체 인식 동의호스티드 흐름과 네이티브 SDK 4.10.0 이상은 애플리케이션의 동의 모드와 사용자가 있는 위치에 따라, 첫 얼굴 촬영 전에 명시적인 생체 인식 동의 단계를 표시할 수 있습니다. 이 판단에는 두 개의 선택적 필드가 사용됩니다.- `user_state`: 알고 있는 경우 사용자가 거주하는 지역입니다(`US-IL`, `IL` 또는 `Illinois`). 자동 모드에서는 해당 주가 적용 대상이면 흐름이 동의를 요청합니다. - `biometric_consent`: 이미 수집한 동의를 위한 객체이며, `given_at`과 `text_version`을 포함합니다. 흐름은 동의를 다시 요청하지 않습니다.4.10.0 미만의 네이티브 SDK에서는 이 단계를 표시할 수 없습니다. 이러한 세션은 기존과 같이 실행되며, 판단 결과에는 동의가 수집되지 않은 것으로 보고됩니다. 자세한 내용은 [생체 인식 동의](https://docs.didit.me/ko/getting-started/biometric-consent.md)를 참조하십시오.## 중요: 고지와 동의는 귀사의 제품에서 이루어집니다`Create Session`은 인증 URL과 세션 토큰을 생성합니다. 그 자체만으로는 사용자에게 고지 사항을 제공했다거나 특정 사용 사례에 필요한 동의를 받았다는 사실을 **증명하지 않습니다**.귀사의 애플리케이션, 웹사이트, SDK 래퍼 또는 화이트 라벨 흐름에서 Didit 세션을 시작하는 경우, 사용자가 촬영을 시작하기 전에 법적 사항은 귀사의 UX에서 직접 처리해야 합니다.## 사전 인증 체크리스트 권장 항목1. 이 인증을 **귀사**가 요청하고 있으며, 이 흐름을 제공하는 인증 제공업체이자 처리자가 **Didit**임을 사용자에게 알리십시오. 2. **귀사의 개인정보 처리방침**과 이 과정에 적용되는 컨트롤러 측 법적 약관에 링크하십시오. 3. Didit의 [인증 개인정보 처리방침](https://didit.me/terms/verification-privacy-notice)과 [신원 인증을 위한 최종 사용자 약관](https://didit.me/terms/identity-verification)에 링크하십시오. 4. 문서 촬영, 셀피 촬영, 라이브니스 또는 생체 인식이 워크플로에 포함되는 경우, 관련 법률이나 귀사의 법적 입장에서 요구하는 경우에는 **명시적인 적극적 동의**를 받으십시오. 5. 사용자 지정 UI, 사용자 지정 도메인 또는 API 전용 과정을 사용하는 경우, 사용자를 Didit 흐름으로 보내기 전에 귀사의 제품에 이러한 고지 사항을 표시하십시오. 6. 법무팀이 감사 추적을 요구하는 경우, 고지 및 동의 문구, 타임스탬프와 관련 메타데이터를 귀사의 기록으로 보관하십시오.> [!WARNING] > > 법적 요건은 관할 지역마다 다릅니다. 화이트 라벨 브랜딩이 있다고 해서 인증 흐름에서 Didit의 역할이 사라지지는 않습니다. 생체 인식 관련 특별 규정이 있는 관할 지역에서 운영하는 경우, 출시 전에 법률 전문가와 함께 구현을 검토하십시오. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/session/ 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/session/: post: tags: - Sessions summary: 인증 세션 생성 description: >- 사용자 인증(KYC) 또는 기업 확인(KYB) 세션을 생성하고 최종 사용자에게 리디렉션하거나 임베드할 수 있는 호스팅 인증 `url` 및 `session_token`을 받습니다. `workflow_id`에 따라 실행할 인증 단계와 세션이 KYC인지 KYB인지가 결정됩니다. 사용자나 기업의 인증이 필요할 때마다(회원가입 시, 민감한 작업 전 또는 재인증이 필요할 때) 백엔드에서 이 endpoint를 호출하세요(API 키는 비밀 정보이므로 브라우저에서는 절대 호출하지 마세요). 사전 요구 사항: 게시된 워크플로(콘솔 [Workflows](https://docs.didit.me/ko/console/workflows) 페이지에서 생성됨) 및 사용 가능한 크레딧이 있는 애플리케이션 API 키. 샌드박스 애플리케이션은 크레딧 확인을 건너뜁니다. **멱등성:** `vendor_data`가 제공되고 워크플로의 **현재 최신 게시 버전**에 동일한 `vendor_data`를 가진 완료되지 않은 세션(`Not Started`, `In Progress`, `Resubmitted` 또는 `Awaiting User`)이 이미 존재하며(해당 세션에 이미 호스팅 인증 URL이 있는 경우), 중복을 생성하는 대신 기존 세션이 반환(여전히 `201`)되며 `callback` 및 `metadata`가 새로 제공된 값으로 업데이트됩니다. 워크플로의 이전 버전(이후 다시 게시된 버전)에서 생성된 완료되지 않은 세션은 재사용되지 **않으며**, 최신 게시 버전에 고정된 새 세션이 대신 생성됩니다. `Approved`, `Declined`, `In Review`, `Expired`, `Abandoned` 또는 `Kyc Expired` 상태의 세션은 절대 재사용되지 않습니다. **부작용:** 호스팅 인증 URL이 생성되어 저장됩니다. `contact_details.send_notification_emails`가 `true`이고 이메일이 제공되면 인증 초대 이메일이 전송됩니다. 세션은 워크플로에 구성된 세션 만료 시간 후에 만료됩니다. KYB 워크플로의 경우 `contact_details.phone` 및 `expected_details`는 무시됩니다. operationId: post_v3_session_create requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: string format: uuid description: >- 세션에서 실행할 인증 단계를 정의하는 워크플로의 안정적인 식별자입니다. 워크플로는 콘솔의 [워크플로](/ko/console/workflows) 페이지에서 생성 및 관리됩니다. `workflow_id`는 세션이 KYC인지 KYB인지도 암시적으로 선택합니다. example: 11111111-2222-3333-4444-555555555555 x-readme-id: '0.0' vendor_data: type: string description: >- 인증 대상 사용자의 고유 식별자(UUID, 이메일, 내부 사용자 ID 등)입니다. 이 필드는 다음 용도로 사용됩니다. (1) **사용자 그룹화** — 동일한 vendor_data를 가진 세션은 Users 탭에서 동일한 사용자 프로필로 연결됩니다. (2) **세션 간 중복 감지** — 중복된 얼굴, 문서, 전화번호, 이메일, IP 주소 또는 기기 지문을 확인할 때 동일한 vendor_data를 가진 세션은 동일한 사용자로 처리되어 일치 항목에서 제외됩니다. vendor_data가 없으면 모든 세션이 고유한 사용자로 처리되어 모든 잠재적 중복 항목이 표시됩니다. 중복 감지의 노이즈를 줄이기 위해 항상 vendor_data를 제공하는 것을 강력히 권장합니다. example: user-123 x-readme-id: '0.1' multi_account_segment: type: string maxLength: 64 description: >- 조직 내의 선택적 중복 감지 영역입니다. 중복 얼굴 확인은 이 세션을 동일한 세그먼트를 가진 다른 세션들과만 비교하므로, 별도의 계정 기반(개인 및 기업 계정 또는 B2B 하위 고객사별 계정)이 있는 경우 양쪽에 정당하게 계정을 보유한 인물을 오탐 플래그로 지정하지 않습니다. 생략하면 현재 모든 세션이 사용하는 단일 기본 영역을 사용합니다. 차단 목록 및 허용 목록 매칭 시에는 이 필드가 무시됩니다. example: business-accounts callback: type: string description: >- 인증 완료 후 사용자를 리디렉션할 URL입니다. Didit은 `verificationSessionId` 및 `status`(Approved, Declined, In Review)를 쿼리 파라미터로 자동 추가합니다. 모바일 콜백을 위한 커스텀 URL 스킴(예: `myapp://`)이 지원됩니다. 생략하면 워크플로의 기본 `callback_url`이 사용됩니다. 애플리케이션에 허용된 도메인이 설정된 경우(`PATCH /v3/webhook/`의 `allowed_domains`), `http` 또는 `https` 콜백은 해당 오리진 중 하나에 있어야 하며(동일한 스킴, 호스트 및 포트), 그렇지 않으면 `callback`에서 400 오류와 함께 요청이 실패합니다: `callback must be on one of the application's allowed domains: https://app.example.com`. 커스텀 URL 스킴은 항상 허용됩니다. example: https://example.com/verification/callback x-readme-id: '0.2' callback_method: type: string description: >- 제공된 콜백 URL로의 리디렉션을 처리할 기기를 결정합니다. 흐름을 시작한 기기만 리디렉션하려면 `initiator`, 흐름을 완료하는 기기는 `completer`, 두 기기 중 어느 쪽이든 콜백을 트리거할 수 있도록 허용하려면 `both`를 사용하십시오. 콜백이 안정적으로 트리거되지 않는 문제가 발생할 경우 이 값을 `both`로 설정하는 것을 권장합니다. enum: - initiator - completer - both default: initiator example: both x-readme-id: '0.3' metadata: description: >- 세션과 함께 저장되며 응답 및 webhook에 그대로 반환되는 임의의 JSON입니다. 모든 JSON 값(객체, 문자열, 숫자, 배열)이 허용되지만, 키/값 쌍의 JSON 객체를 사용하는 것이 좋습니다. 최종 사용자에게는 표시되지 않습니다. 자체 상관 관계 ID, A/B 변형 또는 비즈니스 컨텍스트를 전달하는 데 사용하십시오. example: user_type: premium account_id: ABC123 x-readme-id: '0.4' tags: type: array items: type: string maxLength: 50 maxItems: 10 description: >- 세션이 생성될 때 이름별로 추가된 태그입니다. 최대 10개, 각각 최대 50자입니다. 이름은 대소문자를 구분하지 않으며 대문자로 저장됩니다. 애플리케이션에 아직 존재하지 않는 이름은 새 태그로 생성됩니다. 태그는 콘솔의 세션에 표시되며, 이를 기준으로 필터링할 수 있습니다. example: - VIP - ONBOARDING Q4 language: type: string description: >- 인증 프로세스 인터페이스의 언어 코드(ISO 639-1)입니다. 인증 중에 최종 사용자에게 표시되는 언어를 제어합니다. 제공되지 않으면 브라우저 언어가 자동으로 감지되어 사용됩니다. 지원되는 모든 언어는 [여기](/ko/integration/supported-languages)에서 확인하세요. enum: - en - ar - bg - bn - bs - ca - cnr - cs - da - de - el - es - et - fa - fi - fr - he - hi - hr - hu - hy - id - it - ja - ka - kk - ko - ky - lt - lv - mk - mn - ms - nl - 'no' - pl - pt-BR - pt - ro - ru - sk - sl - so - sq - sr - sv - th - tr - uk - uz - vi - zh-CN - zh-TW - zh example: en x-readme-id: '0.5' contact_details: type: object description: >- 알림, 인증 양식 자동 완성 및 전화번호 인증에 사용할 수 있는 사용자 연락처 정보입니다. 이메일 주소, 통신에 사용할 선호 언어 및 전화번호가 포함됩니다. example: email: john.doe@example.com send_notification_emails: true email_lang: en phone: '+14155552671' properties: email: type: string format: email description: >- [이메일 인증](/ko/core-technology/email-verification/overview) 단계에서 사용될 사용자의 이메일 주소(예: "john.doe@example.com")입니다. 제공되지 않으면 사용자가 인증 플로우 중에 직접 입력해야 합니다. example: john.doe@example.com x-readme-id: '1.0' send_notification_emails: type: boolean default: false description: >- true이고 이메일이 제공된 경우, Didit은 사용자 인증(KYC) 또는 기업 확인(KYB) 세션이 생성될 때 최초의 "신원을 인증하세요" 이메일을 비동기식으로 전송합니다. 또한 Didit은 수동 검토가 필요한 세션에 대해 인증 상태 알림을 제공된 이메일 주소로 전송합니다(예: 'In Review'에서 'Approved' 또는 'Declined'로 변경). 이를 통해 사용자가 인증 완료 후 애플리케이션으로 다시 돌아올 수 있도록 돕습니다. 세션에 화이트 라벨이 활성화되어 있는 경우 전송되는 이메일에 화이트 라벨이 적용됩니다. example: true x-readme-id: '1.1' email_lang: type: string description: >- 이메일 알림 언어 코드(ISO 639-1)입니다. 모든 이메일 커뮤니케이션의 언어를 제어합니다(예: "en", "es", "fr"). 저장된 기본값은 없습니다. 생략 시 발송 시점에 인증 초대 이메일이 영어(`en`)로 자동 대체됩니다. 아래 enum은 스냅샷이며, 허용되는 값의 실시간 기준은 [지원 언어](/ko/integration/supported-languages) 문서이므로 특정 코드를 사용하기 전에 항상 확인하세요. enum: - en - ar - bg - bn - bs - ca - cnr - cs - da - de - el - es - et - fa - fi - fr - he - hi - hr - hu - hy - id - it - ja - ka - kk - ko - ky - lt - lv - mk - mn - ms - nl - 'no' - pl - pt-BR - pt - ro - ru - sk - sl - so - sq - sr - sv - th - tr - uk - uz - vi - zh-CN - zh-TW - zh example: en x-readme-id: '1.2' phone: type: string description: >- [전화번호 인증](/ko/core-technology/phone-verification/overview) 단계에서 사용될 E.164 형식의 전화번호(예: "+14155552671")입니다. 제공되지 않으면 사용자가 인증 플로우 중에 직접 제공해야 합니다. 기업 확인(KYB) 워크플로에서는 무시됩니다. **중요:** 이 전화번호는 유효한 E.164 형식 전화번호인 경우에만 적용됩니다. 제공된 번호가 유효하지 않거나 파싱할 수 없는 경우 무시되며 사용자는 전화번호 인증 단계에서 유효한 전화번호를 자유롭게 입력할 수 있습니다. example: '+14155552671' x-readme-id: '1.3' x-readme-id: '0.4' expected_details: type: object description: >- 사용자의 신분증 문서, 주소 증명 및 기타 인증 단계에서 추출된 데이터와 교차 검증하는 데 사용되는 예상 사용자 세부정보입니다. 불일치 항목은 결정 시 경고로 표시되며, 일부 필드(예: `id_country`, `expected_document_types`)는 사용자 대상 플로우를 변경하기도 합니다. 기업 확인(KYB) 워크플로의 경우 기업 필드(`company_name`, `registry_country`, `registration_number`)만 사용되어 사용자를 위한 법인 등기부 검색을 미리 채우며, 모든 개인 단위 필드는 무시됩니다. example: first_name: John last_name: Doe date_of_birth: '1990-05-15' nationality: USA id_country: USA expected_document_types: - P - ID properties: first_name: type: string description: >- 사용자의 이름입니다. 예: `John`. 일치 여부는 퍼지 비교를 사용하며, 콘솔에서 신분증 및 주소 증명 워크플로 모두에 대해 이름 일치 점수 임계값을 설정하여 엄격도를 조정할 수 있습니다. example: John x-readme-id: '1.0' last_name: type: string description: >- 사용자의 성입니다. 예: `Doe`. 일치 여부는 퍼지 비교를 사용하며, 콘솔에서 신분증 및 주소 증명 워크플로 모두에 대해 이름 일치 점수 임계값을 설정하여 엄격도를 조정할 수 있습니다. example: Doe x-readme-id: '1.1' date_of_birth: type: string format: date description: '사용자의 생년월일 형식: YYYY-MM-DD. 예: `1990-05-15`.' example: '1990-05-15' x-readme-id: '1.2' gender: type: string nullable: true enum: - M - F default: null description: 사용자의 성별입니다. 'M', 'F' 또는 null이어야 합니다. example: M x-readme-id: '1.3' nationality: type: string description: >- 신청자의 출신 국가를 나타내는 ISO 3166-1 alpha-3 국가 코드입니다. 예: `USA`. [지원되는 국가 코드 전체 목록](https://docs.didit.me/ko/core-technology/id-verification/supported-documents-id-verification#국가별-지원-문서)을 참조하십시오. example: USA x-readme-id: '1.4' country: type: string description: >- 신분증 인증 및 주소 증명 국가 불일치 확인 모두에 대체 값으로 사용되는 ISO 3166-1 alpha-3 국가 코드입니다. `address`가 제공되고 `id_country`와 `poa_country`가 모두 설정되지 않은 경우 필수입니다. example: USA x-readme-id: 1.4.1 id_country: type: string description: >- 신청자의 신분증 문서의 예상 국가를 나타내는 ISO 3166-1 alpha-3 국가 코드이며, 국적과 다를 수 있습니다. 예: `GBR`. 신분증 인증 국가 불일치 확인 시 `country`보다 우선 적용됩니다. [지원되는 국가 코드 전체 목록](https://docs.didit.me/ko/core-technology/id-verification/supported-documents-id-verification#국가별-지원-문서)을 참조하십시오. example: GBR x-readme-id: '1.5' poa_country: type: string description: >- 주소 증명 문서의 예상 국가를 나타내는 ISO 3166-1 alpha-3 국가 코드입니다. 예: `USA`. POA 국가 불일치 확인 시 `country`보다 우선 적용됩니다. [지원되는 국가 코드 전체 목록](https://docs.didit.me/ko/core-technology/id-verification/supported-documents-id-verification#국가별-지원-문서)을 참조하십시오. example: USA x-readme-id: 1.5.1 address: type: string description: >- 가능한 한 많은 정보를 포함한 사람이 읽을 수 있는 형식의 주소입니다. 예를 들어 `123 Main St, San Francisco, CA 94105, USA`입니다. 제공할 경우 `country` 또는 `poa_country`도 함께 전달해야 하며, 그렇지 않으면 요청이 `400`으로 실패합니다. example: 123 Main St, San Francisco, CA 94105, USA x-readme-id: '1.6' identification_number: type: string description: 사용자의 문서 번호, 개인 식별 번호 또는 납세자 번호입니다. 예를 들어 `123456789`입니다. example: '123456789' x-readme-id: '1.7' ip_address: type: string description: >- IPv4 또는 IPv6 형식의 세션 예상 IP 주소입니다. 실제 IP 주소가 이 값과 다르면 경고가 기록됩니다. 예: `192.168.1.100` 또는 `2001:db8::1`. example: 192.168.1.100 x-readme-id: '1.8' expected_document_types: type: array description: >- 신분증 인증(OCR) 단계에서 사용자가 제시할 수 있는 문서 유형을 제한합니다. 설정하면 문서 선택 화면에 요청된 유형만 표시되고 반환되는 `documents_allowed`도 이에 따라 필터링됩니다. 값은 대소문자를 구분하지 않으며 중복이 제거됩니다. 알 수 없는 값은 `400`으로 거부됩니다. 허용되는 코드: `P`(여권), `ID`(국가 신분증), `DL`(운전면허증), `RP`(거주 허가증), `HIC`(건강보험증), `TC`(세금 카드), `SSC`(사회보장 카드). items: type: string enum: - P - ID - DL - RP - HIC - TC - SSC example: - P - ID x-readme-id: '1.9' company_name: type: string maxLength: 255 description: >- 인증 대상 기업의 예상 법적 명칭입니다. 예를 들어 `Tesco PLC`입니다. 기업 확인(KYB) 워크플로의 등기부 검색에서 회사명 필드를 미리 채웁니다. `registration_number`도 함께 제공되면 등기부 조회 시 두 식별자를 결합합니다. KYC 워크플로에서는 무시됩니다. example: Tesco PLC x-readme-id: '1.10' registry_country: type: string maxLength: 10 description: >- 기업이 등록된 법인 등기부의 국가에 해당하는 ISO 3166-1 alpha-2 코드입니다. 예를 들어 `GB`입니다. 법인 등기부가 주 또는 도 단위로 운영되는 경우 `XX-YY` 형식으로 ISO 3166-2 행정 구역 코드를 추가합니다. `US-CA`는 캘리포니아 등기부를 대상으로 합니다. [KYB Registry Search API](https://docs.didit.me/ko/standalone-apis/kyb-registry-search)의 `country_code`와 동일한 형식입니다. 기업 확인(KYB) 워크플로에서 등기부 국가를 미리 선택하며, KYC 워크플로에서는 무시됩니다. example: US-CA x-readme-id: '1.11' registration_number: type: string maxLength: 100 description: >- 법인 등기부상 기업의 예상 등록번호입니다. 예를 들어 `00445790`입니다. 기업 확인(KYB) 워크플로의 등기부 검색에서 등록번호 필드를 미리 채웁니다. `company_name`도 함께 제공되면 등기부 조회 시 두 식별자를 결합합니다. KYC 워크플로에서는 무시됩니다. example: '00445790' x-readme-id: '1.12' x-readme-id: '0.5' portrait_image: type: string format: byte description: >- 최종 사용자의 얼굴을 촬영한 Base64 인코딩된 인물 사진 이미지입니다(최대 2MB, JPEG, PNG, WebP 또는 TIFF). 워크플로가 얼굴 대조가 활성화된 `Biometric Authentication` 워크플로이거나, 얼굴 대조가 신분증 인증(OCR)보다 먼저 실행되는 그래프 워크플로인 경우 라이브니스 캡처와 대조할 기준 이미지로 사용됩니다. `vendor_data` 사용자에게 이미 저장된 얼굴 이미지가 있는 경우 선택 사항입니다. Didit은 승인된 라이브니스 얼굴, 전자여권(ePassport) 칩 사진, 신분증 인물 사진, 직접 등록한 프로필 얼굴 순으로 우선순위를 확인하여 자동으로 재사용합니다(승인된 세션의 얼굴 또는 직접 등록한 얼굴만 재사용됨). `portrait_image`가 제공되면 저장된 얼굴보다 항상 우선 적용됩니다. 생략되었고 저장된 얼굴도 없는 경우(또는 `vendor_data`가 전송되지 않은 경우) 세션 생성은 `400` 오류로 실패합니다. 다른 워크플로 유형에서는 무시됩니다. example: >- iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII= x-readme-id: '0.6' sandbox_scenario: type: string description: >- 샌드박스 전용 시나리오 slug입니다. API 키가 샌드박스 모드 애플리케이션에 속한 경우에만 허용되며, 프로덕션 애플리케이션에서는 거부됩니다. 설정 시 생성 흐름에서 시나리오에 번들된 매직 값을 세션의 입력 필드(contact_details, expected_details)로 확장하여 모의 제공업체가 실제 워크플로 파이프라인을 통해 시나리오 결과를 재현하도록 합니다. GET /v1/sandbox/scenarios/ 또는 [Sandbox & Test Data](/ko/integration/sandbox-testing)에서 시나리오 카탈로그를 확인하세요. 또한 세션이 아직 `Not Started` 상태인 경우 POST /v3/session/{sessionId}/sandbox/arm/을 통해 생성 후 시나리오를 준비(또는 재준비)할 수도 있습니다. 비문서 조회의 경우 `lookup_partial_match`, `lookup_no_match` 또는 `lookup_provider_error`를 사용하여 구성된 시도 예산 및 폴백을 테스트하세요. 신원 지갑의 경우 `wallet_cancelled`, `wallet_timeout` 또는 `wallet_provider_error`를 사용하세요. `approve`는 검증된 지갑을 시뮬레이션합니다. 프로덕션 애플리케이션에서 사용할 수 없는 방식을 포함하여 카탈로그의 모든 지갑을 샌드박스에서 테스트할 수 있습니다. 시뮬레이션된 시도에는 요금이 청구되지 않습니다. example: decline_document_expired sign: type: object description: >- 이 세션에 대한 전자 서명 입력값입니다. `documents`는 서명할 문서이며, 전자 서명 단계가 세션에서 문서를 가져오는 워크플로(`signature_documents_source`가 `session` 또는 `both`)의 경우 최대 20개 문서 및 총 50MB까지 가능합니다. `field_values`는 워크플로 및 세션 문서 모두에서 `prefill`이 `api.`인 필드를 채웁니다. 동일한 `workflow_id` 및 `vendor_data`로 세션을 다시 생성하면 대기 중인 세션이 반환됩니다. 해당 호출이 `sign`을 전송하는 경우 해당 문서, 필드 및 값은 첫 번째 호출과 동일해야 하며, 다를 경우 `{"sign": "signature_document_changed"}`와 함께 `400`이 반환됩니다. [전자 서명 문서](/ko/sessions-api/create-session#전자-서명-문서)를 참조하세요. properties: documents: type: array minItems: 1 maxItems: 20 items: $ref: '#/components/schemas/SessionSignDocument' field_values: type: object description: >- 각 `api.` 사전 채우기 소스의 ``를 키로 하는 값: `text` 및 `data` 필드의 경우 1~500자의 문자열, `checkbox`의 경우 불리언입니다. 어떤 필드에서도 사용하지 않는 키의 경우 `field_value_unknown`, 값이 없는 필수 필드의 경우 `field_value_missing`, 필드 검증에 실패한 값의 경우 `field_value_invalid`와 함께 `400`이 반환됩니다. additionalProperties: oneOf: - type: string minLength: 1 maxLength: 500 - type: boolean example: credit_limit: 3,000 EUR user_state: type: string maxLength: 16 description: >- 알려진 경우 해당 개인이 거주하는 위치: ISO 3166-2 세부 구역 코드(`US-IL`, `ES-M`) 또는 미국 주 코드나 이름(`IL`, `Illinois`). 법적으로 명시적인 생체 인증 동의를 요구하는 주(일리노이, 텍사스, 콜로라도)의 경우 인증 흐름에서 얼굴을 캡처하기 전에 `declared_state` 트리거와 함께 동의를 요청합니다. 인식할 수 없는 값은 `400`을 반환합니다. [생체 인증 동의](/ko/getting-started/biometric-consent)를 참고하십시오. example: US-IL biometric_consent: type: object description: >- 해당 인물로부터 이미 수집한 명시적 생체 인식 동의입니다. 요구사항을 충족하므로 인증 플로우에서 다시 묻지 않으며, 결정에는 트리거 `customer_collected`와 함께 `status: "given"`으로 기록됩니다. 사용자가 플로우에서 이미 제출한 답변은 대체되지 않습니다. [생체 인식 동의](/ko/getting-started/biometric-consent)를 참고하십시오. required: - given_at - text_version properties: given_at: type: string format: date-time description: 사용자가 명시적인 생체 인식 동의를 제공한 시점(ISO 8601)입니다. 미래 시점일 수 없습니다. text_version: type: string maxLength: 64 description: 자체 기록 내 사용자가 수락한 동의 텍스트의 버전 ID입니다. example: workflow_id: 11111111-2222-3333-4444-555555555555 vendor_data: user-123 callback: https://example.com/verification/callback callback_method: both metadata: user_type: premium account_id: ABC123 language: en contact_details: email: john.doe@example.com send_notification_emails: true email_lang: en phone: '+14155552671' expected_details: first_name: John last_name: Doe date_of_birth: '1990-05-15' id_country: USA expected_document_types: - P - ID examples: Create KYC session: summary: 사용자 인증(KYC) 세션에 대한 전체 정상 경로(happy-path) payload description: >- 자주 설정되는 모든 필드를 사용하는 실용적인 생성 호출 예시입니다: 워크플로 선택, 벤더 연동, 콜백 라우팅, 메타데이터, 로캘, 연락처 사전 입력, 예상 사용자 세부 정보. 위의 cURL 샘플에 그대로 복사하여 붙여넣으세요. value: workflow_id: 11111111-2222-3333-4444-555555555555 vendor_data: user-123 callback: https://example.com/verification/callback callback_method: both metadata: user_type: premium account_id: ABC123 language: en contact_details: email: john.doe@example.com send_notification_emails: true email_lang: en phone: '+14155552671' expected_details: first_name: John last_name: Doe date_of_birth: '1990-05-15' nationality: USA id_country: USA expected_document_types: - P - ID Create KYB session: summary: 기업 확인(KYB) 세션에 대한 정상 경로 payload description: >- KYC 호출과 동일한 형태입니다. 세션을 KYB로 만드는 것은 `workflow_id`입니다. `vendor_data`는 일반적으로 귀하의 시스템에서 회사를 참조하며, `contact_details.email`은 절차를 완료할 법정 대리인을 대상으로 합니다. `expected_details`는 법인 등기부 검색을 미리 채우는 기업 필드(`company_name`, `registry_country`, `registration_number`)를 허용합니다. 개인 수준 필드 및 `contact_details.phone`은 KYB 워크플로에서 무시됩니다. value: workflow_id: 33333333-4444-5555-6666-777777777777 vendor_data: company-acme-001 callback: https://example.com/kyb/callback callback_method: both metadata: tier: enterprise company_id: ACME-001 expected_details: company_name: Tesco PLC registry_country: GB registration_number: '00445790' language: en contact_details: email: legal-rep@acme.example.com send_notification_emails: true email_lang: en responses: '201': description: >- 세션이 생성되었습니다(또는 워크플로의 최신 게시 버전에 동일한 `vendor_data`를 가진 완료되지 않은 세션이 이미 존재하는 경우 해당 세션이 반환됨). 응답은 사용자를 리디렉션할 호스팅 인증 `url`을 포함하는 직렬화된 세션입니다. content: application/json: schema: type: object required: - session_id - session_number - session_token - url - vendor_data - metadata - status - workflow_id - workflow_version - callback properties: session_id: type: string format: uuid description: >- 인증 세션의 고유 식별자입니다. `GET /v3/session/{sessionId}/decision/`을 호출할 때 이 id를 사용합니다. example: 11111111-2222-3333-4444-555555555555 session_number: type: integer description: >- 애플리케이션 내에서 세션에 할당된 사람이 읽기 쉬운 순차 번호입니다. 고객 지원 및 대시보드에 유용합니다. example: 43762 session_token: type: string description: >- 최종 사용자가 `url`의 호스팅 인증 흐름에 접근할 수 있도록 권한을 부여하는 12자의 URL-safe token입니다. 세션이 만료될 때까지 유효합니다. 비밀 정보로 취급하십시오. 이 token을 보유한 사람은 누구나 해당 세션의 인증 흐름을 열 수 있습니다. example: 3FaJ9wLqX2Mz url: type: string format: uri description: >- 최종 사용자를 리디렉션할 호스팅 인증 URL입니다. URL에는 `session_token`이 포함되어 있으며, 구성된 경우 화이트 라벨 도메인을 사용합니다. 요청에 `language`가 포함되어 있으면 URL에 언어 경로 세그먼트(`https://verify.didit.me/{language}/session/{session_token}`, 예: `/es/session/...`)가 포함되고, `language`가 없으면 해당 세그먼트가 생략됩니다. example: https://verify.didit.me/session/3FaJ9wLqX2Mz vendor_data: type: string nullable: true description: >- 자체 시스템의 사용자 또는 기업과 세션을 연결하기 위해 요청에 전달한 식별자입니다. 입력한 그대로 반환됩니다. 제공되지 않은 경우 null입니다. example: user-123 metadata: description: >- 세션 생성 시 함께 저장한 임의의 JSON payload입니다. 보낸 JSON 값(객체, 문자열, 숫자, 배열)이 그대로 반환되지만, JSON 객체를 사용하는 것이 좋습니다. 최종 사용자에게는 표시되지 않습니다. 응답에 항상 포함되며, 생성 시 제공되지 않은 경우 `null`입니다. example: user_type: premium account_id: ABC123 tags: type: array items: type: string description: 세션의 태그를 이름으로 표시합니다. example: - VIP - ONBOARDING Q4 status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User description: >- 세션의 현재 상태입니다. 새로 생성된 세션은 `Not Started`를 반환합니다. 워크플로의 최신 게시 버전에 동일한 `vendor_data`를 가진 완료되지 않은 세션이 이미 존재하는 경우, 반환되는 상태에는 해당 기존 세션의 상태가 반영됩니다. example: Not Started callback: type: string format: uri nullable: true description: >- 사용자가 플로우를 완료한 후 이동하게 되는 최종 리디렉션 URL입니다. Didit은 이 URL에 `?verificationSessionId={session_id}&status={status}`를 추가합니다. 요청에서 제공되지 않은 경우 워크플로에 구성된 콜백 URL로 대체되며, 둘 다 설정되지 않은 경우 `null`입니다. 애플리케이션에 허용된 도메인이 설정되어 있고 이 URL이 해당 도메인 외의 웹 URL인 경우(예: 목록이 변경되기 전에 설정된 워크플로 기본값), 호스팅 플로우는 사용자를 해당 URL로 리디렉션하지 않습니다. example: https://example.com/verification/callback workflow_id: type: string format: uuid description: >- 이 세션이 실행되는 워크플로의 안정적인 식별자입니다. 항상 워크플로의 안정적인 그룹 식별자이며, 요청에서 특정 워크플로 버전 UUID를 참조했더라도(하위 호환성 조회) 응답에는 안정적인 `workflow_id`가 반환됩니다. 콘솔에서 구성한 워크플로와 세션을 연결하는 데 사용하세요. example: 11111111-2222-3333-4444-555555555555 workflow_version: type: integer description: >- 세션 생성 시 고정된 게시된 워크플로 버전의 버전 번호입니다. Didit은 세션이 생성될 때 `workflow_id`를 워크플로의 최신 게시 버전에 매핑하며, 이후 워크플로가 다시 게시되더라도 세션은 해당 버전을 계속 실행합니다. example: 3 examples: KYC session: summary: KYC 세션이 생성됨 value: session_id: 11111111-2222-3333-4444-555555555555 session_number: 43762 session_token: 3FaJ9wLqX2Mz url: https://verify.didit.me/en/session/3FaJ9wLqX2Mz vendor_data: user-123 metadata: user_type: premium account_id: ABC123 status: Not Started workflow_id: 11111111-2222-3333-4444-555555555555 workflow_version: 3 callback: https://example.com/verification/callback KYB session: summary: KYB 세션이 생성됨 value: session_id: 22222222-3333-4444-5555-666666666666 session_number: 43763 session_token: Yk7pQ2vN8aBc url: https://verify.didit.me/en/session/Yk7pQ2vN8aBc vendor_data: company-acme-001 metadata: tier: enterprise status: Not Started workflow_id: 33333333-4444-5555-6666-777777777777 workflow_version: 1 callback: https://example.com/kyb/callback '400': description: >- 잘못된 요청 — payload 유효성 검사에 실패했거나(`workflow_id` 누락 또는 알 수 없음, 잘못된 `language`, 차단 목록에 포함된 `vendor_data`, 잘못된 형식의 `portrait_image`, `country`/`poa_country`가 없는 `address`, 잘못된 `sandbox_scenario`, `signature_document_not_supported`, `signature_document_conversion_failed`, `field_anchor_not_found`, `field_value_missing` 등 워크플로의 전자 서명 단계에서 거부하는 `sign` 문서, 필드 또는 값) 조직에 세션을 시작하기 위한 크레딧이 부족합니다. 본문은 문제가 발생한 필드 이름을 키로 갖는 객체입니다(필드 외 오류의 경우 `detail`). 값은 입력 유효성 검사 실패(예: 필수 필드 누락, 잘못된 언어, 허용 크기를 초과한 인물 사진 이미지)의 경우 **문자열 배열**이며, 세션 생성 중 감지된 실패(알 수 없는 `workflow_id`, 차단 목록에 포함된 `vendor_data`, 얼굴 대조 워크플로에 사용 가능한 기준 얼굴 없음)의 경우 **일반 문자열**입니다. 두 형태를 모두 처리하십시오. content: application/json: schema: type: object additionalProperties: true properties: detail: type: string description: >- 필드 오류가 아닌 경우(예: 크레딧 부족)의 사람이 읽기 쉬운 오류 메시지입니다. 필드 수준의 오류는 대신 필드 이름을 키로 사용하며, 문자열 또는 문자열 배열 값을 가집니다. example: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me examples: Missing workflow_id: summary: 필수 필드가 누락됨(문자열 배열 형식) value: workflow_id: - This field is required. Invalid workflow_id: summary: 알 수 없는 workflow_id(일반 문자열 형식) value: workflow_id: Invalid workflow_id. Insufficient credits: summary: 조직의 크레딧이 부족합니다 value: detail: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me Blocklisted vendor_data: summary: vendor_data가 차단 목록에 있습니다 value: vendor_data: >- This user or business has been blocked and cannot create new verification sessions. Portrait image too large: summary: portrait_image 크기 유효성 검사 실패 value: portrait_image: - Image size exceeds 2MB. No stored face for vendor_data: summary: portrait_image가 없고 vendor_data 사용자에 대해 저장된 얼굴이 없는 얼굴 대조 워크플로 value: portrait_image: >- No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first. Portrait image required without vendor_data: summary: portrait_image 및 vendor_data가 없는 얼굴 대조 워크플로 value: portrait_image: >- A portrait image is required to perform face match for this workflow. Send a portrait_image, or provide the vendor_data of a user with a previously stored face image to reuse it. '403': description: >- 인증 또는 권한 부여에 실패했습니다. 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. `x-api-key` 헤더가 없거나, API 키가 유효하지만 클라이언트에 이 애플리케이션에서 세션을 생성할 수 있는 권한이 없는 경우(예: API 키가 다른 조직에 속한 경우) endpoint는 `403`을 반환합니다. 이러한 실패는 `{"detail": "You do not have permission to perform this action."}` 본문을 공유합니다. `x-api-key` 헤더가 존재하며 의도한 애플리케이션에 속하는지 확인하고, 필요한 경우 [Auth API](/ko/auth-api/get-credentials)를 통해 애플리케이션 API 키를 다시 가져와 재시도하십시오. **삭제된 애플리케이션:** 애플리케이션이 삭제된 후 몇 분 동안 해당 API 키 중 하나로 전송된 요청에 대해 `{"detail": "This application was deleted.", "code": "application_deleted"}` 응답이 반환될 수 있습니다. 재시도하지 마십시오. 해당 애플리케이션과 API 키는 더 이상 존재하지 않습니다. 이 몇 분이 지나면 키는 다른 유효하지 않은 키와 마찬가지로 거부됩니다. content: application/json: schema: type: object properties: detail: type: string example: You do not have permission to perform this action. code: type: string description: >- 기계 판독 가능한 사유로, 일부 실패 시에만 제공됩니다. `application_deleted`: API 키가 삭제된 애플리케이션에 속해 있습니다. example: application_deleted required: - detail examples: Missing or invalid API key: summary: '`x-api-key` 헤더가 없거나 잘못된 API 키입니다' value: detail: You do not have permission to perform this action. No permission: summary: 클라이언트가 세션을 생성할 수 없음 value: detail: You do not have permission to perform this action. Application deleted: summary: 삭제된 애플리케이션의 API 키 value: detail: This application was deleted. code: application_deleted '429': description: >- 속도 제한을 초과했습니다. 동일한 API 키 또는 IP에서 60초 동안 600회를 초과하는 세션 생성 요청이 발생했습니다. `Retry-After`를 확인하고 백오프 후 재시도하세요. **참고:** 소스 코드에는 `PAID_SESSION_RATE_LIMIT=600`과 함께 분당 10회 호출의 `FREE_SESSION_RATE_LIMIT`도 정의되어 있지만(`sessions/serializers/session.py`), 해당 무료 요금제 상한은 **이 V3 endpoint에는 적용되지 않습니다**. 속도 제한 미들웨어는 요금제와 관계없이 분당 600회의 `SESSION_CREATE_RATE_LIMIT`을 적용합니다. 여기서 적용되는 유일한 한도는 분당 600회입니다. headers: Retry-After: description: 호출자가 요청을 재시도하기 전에 대기해야 하는 시간(초). schema: type: integer minimum: 1 example: 42 X-RateLimit-Limit: description: >- 초과된 제한에 대해 현재 60초 윈도우에서 허용되는 최대 요청 수(세션 생성의 경우 600)입니다. 샌드박스 할당량 변형에는 없습니다. schema: type: integer example: 600 X-RateLimit-Remaining: description: 위반된 제한에 대해 현재 윈도우에서 여전히 허용되는 요청 수입니다. 샌드박스 쿼터 변형에는 표시되지 않습니다. schema: type: integer minimum: 0 example: 0 X-RateLimit-Reset: description: 현재 속도 제한 윈도우가 초기화되는 UTC 에포크 초입니다. 샌드박스 할당량 변형에서는 제공되지 않습니다. schema: type: integer minimum: 0 example: 1747497600 content: application/json: schema: type: object properties: detail: type: string description: >- 속도 제한 초과에 대한 사람이 읽기 쉬운 설명입니다. 이 메시지를 사용하여 세 가지 제한 중 어느 제한에 도달했는지 구분하십시오. example: >- Session creation rate limit exceeded. You can make up to 600 requests per minute. examples: Session-create limit: summary: 분당 600건을 초과하는 세션 생성 요청 발생 value: detail: >- Session creation rate limit exceeded. You can make up to 600 requests per minute. Sandbox session quota: summary: 샌드박스 애플리케이션이 24시간 내에 500개 세션을 초과했습니다 value: detail: >- Sandbox session quota exceeded (500 sessions per 24h). Wait for the window to reset. Expected available in 3600 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/session/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "workflow_id": "11111111-2222-3333-4444-555555555555", "vendor_data": "user-123", "callback": "https://example.com/verification/callback", "callback_method": "both", "metadata": {"user_type": "premium", "account_id": "ABC123"}, "language": "en", "contact_details": { "email": "john.doe@example.com", "send_notification_emails": true, "email_lang": "en", "phone": "+14155552671" }, "expected_details": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "id_country": "USA", "expected_document_types": ["P", "ID"] } }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.sessions.create( workflow_id="11111111-2222-3333-4444-555555555555", vendor_data="user-123", callback="https://example.com/verification/callback", callback_method="both", metadata={"user_type": "premium", "account_id": "ABC123"}, language="en", contact_details={ "email": "john.doe@example.com", "send_notification_emails": True, "email_lang": "en", "phone": "+14155552671", }, expected_details={ "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "nationality": "USA", "id_country": "USA", "expected_document_types": ["P", "ID"], }, ) 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.sessions.create({ workflow_id: "11111111-2222-3333-4444-555555555555", vendor_data: "user-123", callback: "https://example.com/verification/callback", callback_method: "both", metadata: { user_type: "premium", account_id: "ABC123" }, language: "en", contact_details: { email: "john.doe@example.com", send_notification_emails: true, email_lang: "en", phone: "+14155552671", }, expected_details: { first_name: "John", last_name: "Doe", date_of_birth: "1990-05-15", nationality: "USA", id_country: "USA", expected_document_types: ["P", "ID"], }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{\n\tWorkflowID: \"11111111-2222-3333-4444-555555555555\",\n\tVendorData: didit.String(\"user-123\"),\n\tCallback: didit.String(\"https://example.com/verification/callback\"),\n\tCallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod(\"both\")),\n\tMetadata: didit.Some[any](map[string]any{\"user_type\": \"premium\", \"account_id\": \"ABC123\"}),\n\tLanguage: didit.Some(didit.SessionsCreateParamsLanguage(\"en\")),\n\tContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{\n\t\tEmail: didit.String(\"john.doe@example.com\"),\n\t\tSendNotificationEmails: didit.Bool(true),\n\t\tEmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang(\"en\")),\n\t\tPhone: didit.String(\"+14155552671\"),\n\t}),\n\tExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{\n\t\tFirstName: didit.String(\"John\"),\n\t\tLastName: didit.String(\"Doe\"),\n\t\tDateOfBirth: didit.String(\"1990-05-15\"),\n\t\tNationality: didit.String(\"USA\"),\n\t\tIDCountry: didit.String(\"USA\"),\n\t\tExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{\"P\", \"ID\"}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import java.time.LocalDate; import java.util.List; import java.util.Map; import me.didit.Didit; import me.didit.types.SessionsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.sessions().create(SessionsCreateParams.builder() .workflowId("11111111-2222-3333-4444-555555555555") .vendorData("user-123") .callback("https://example.com/verification/callback") .callbackMethod(SessionsCreateParams.CallbackMethod.of("both")) .metadata(Map.of("user_type", "premium", "account_id", "ABC123")) .language(SessionsCreateParams.Language.of("en")) .contactDetails(SessionsCreateParams.ContactDetails.builder() .email("john.doe@example.com") .sendNotificationEmails(true) .emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en")) .phone("+14155552671") .build()) .expectedDetails(SessionsCreateParams.ExpectedDetails.builder() .firstName("John") .lastName("Doe") .dateOfBirth(LocalDate.parse("1990-05-15")) .nationality("USA") .idCountry("USA") .expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID"))) .build()) .build()); System.out.println(result); - lang: php label: PHP source: |- sessions->create([ 'workflow_id' => '11111111-2222-3333-4444-555555555555', 'vendor_data' => 'user-123', 'callback' => 'https://example.com/verification/callback', 'callback_method' => 'both', 'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'], 'language' => 'en', 'contact_details' => [ 'email' => 'john.doe@example.com', 'send_notification_emails' => true, 'email_lang' => 'en', 'phone' => '+14155552671', ], 'expected_details' => [ 'first_name' => 'John', 'last_name' => 'Doe', 'date_of_birth' => '1990-05-15', 'nationality' => 'USA', 'id_country' => 'USA', 'expected_document_types' => ['P', 'ID'], ], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.sessions.create( workflow_id: "11111111-2222-3333-4444-555555555555", vendor_data: "user-123", callback: "https://example.com/verification/callback", callback_method: "both", metadata: { user_type: "premium", account_id: "ABC123" }, language: "en", contact_details: { email: "john.doe@example.com", send_notification_emails: true, email_lang: "en", phone: "+14155552671", }, expected_details: { first_name: "John", last_name: "Doe", date_of_birth: "1990-05-15", nationality: "USA", id_country: "USA", expected_document_types: ["P", "ID"], } ) 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.Sessions.CreateAsync(new SessionsCreateParams { WorkflowId = "11111111-2222-3333-4444-555555555555", VendorData = "user-123", Callback = "https://example.com/verification/callback", CallbackMethod = new SessionsCreateParamsCallbackMethod("both"), Metadata = new Dictionary { ["user_type"] = "premium", ["account_id"] = "ABC123" }, Language = new SessionsCreateParamsLanguage("en"), ContactDetails = new SessionsCreateParamsContactDetails { Email = "john.doe@example.com", SendNotificationEmails = true, EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"), Phone = "+14155552671", }, ExpectedDetails = new SessionsCreateParamsExpectedDetails { FirstName = "John", LastName = "Doe", DateOfBirth = "1990-05-15", Nationality = "USA", IdCountry = "USA", ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" }, }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: SessionSignDocument: type: object required: - file_name - content_base64 properties: title: type: string minLength: 1 maxLength: 255 description: 서명자에게 표시되는 제목입니다. 기본값은 `file_name`입니다. file_name: type: string minLength: 1 maxLength: 255 description: '`.pdf` 또는 `.docx`로 끝나는 파일 이름입니다.' content_base64: type: string format: byte description: >- Base64로 인코딩된 파일입니다. PDF는 비밀번호, 스크립트 또는 첨부 파일 없이 최대 20MB 및 100페이지까지 가능합니다. Word 파일(`.docx`)은 최대 20MB까지 가능하며, 요청이 실행되는 동안 최대 25초 이내에 PDF로 변환됩니다. 변환된 PDF에도 동일한 제한이 적용됩니다. 세션당 최대 5개의 Word 파일을 지원합니다. 매크로, 변경 내용 추적, 외부 콘텐츠 링크 또는 포함된 개체가 있는 Word 파일은 `signature_document_not_supported`와 함께 거부되며, 변환할 수 없는 파일은 `signature_document_conversion_failed`를 반환하고 각각 `reason`이 포함됩니다. fields: type: array description: >- 이 문서에 배치할 선택적 필드로, 최대 200개까지 지정할 수 있습니다. 페이지 및 위치는 PDF 또는 Word 파일이 변환된 PDF를 기준으로 합니다. 필드가 없으면 서명자는 문서를 읽고 동의하게 됩니다. items: $ref: '#/components/schemas/SignatureField' maxItems: 200 SignatureField: type: object description: >- 세션 문서에 배치할 필드입니다. 어느 서명인이 어떻게, 어디에 채우는지를 지정합니다. 위치(`page`, `x`, `y`, `width`, `height`) 또는 `anchor` 중 하나를 제공하십시오. 위치는 표시되는 페이지의 왼쪽 상단 모서리를 기준으로 소수점 4자리까지 반올림된 비율 값이며, 필드는 페이지 내에 맞아야 합니다. 문서는 최대 200개의 필드를, 한 명의 서명인은 최대 500개까지 가질 수 있으며, 문서에 필드가 있는 모든 역할은 해당 문서에 `signature` 또는 `initials` 필드가 필요합니다. [문서의 필드](/ko/core-technology/electronic-signature/overview#문서의-필드)를 참조하십시오. required: - key - type properties: key: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: 결과 및 `sign.field_values`에서 필드를 지정합니다. 문서 내에서 고유해야 합니다. type: type: string enum: - signature - initials - full_name - date_signed - text - checkbox - email - data description: >- 필드에 포함되는 내용입니다. 서명자는 본인이 채택한 `signature` 및 `initials`를 적용하고, `text`를 입력하며, `checkbox`를 선택하고, 세션에 인증된 이메일이 없는 경우 `email`을 입력합니다. Didit은 `full_name`(인증된 성명), `date_signed`(서명자 시간대의 서명 날짜), `data`(`prefill`에서 가져옴) 및 인증된 `email`을 채우고 읽기 전용으로 표시합니다. 날짜 선택기 유형은 없으므로 `text`를 사용하십시오. role: type: string enum: - verified_person - legal_representative - key_people description: >- `signature_signer` 값을 사용하여 필드를 채우는 주체입니다. 단계는 자체 서명자의 필드만 작성하고 스탬프를 찍습니다. 기본값은 해당 단계의 서명자입니다. page: type: integer minimum: 1 description: 페이지 번호(1부터 문서의 전체 페이지 수까지)입니다. Word 문서의 경우 변환된 PDF의 페이지입니다. x: type: number minimum: 0 maximum: 1 description: 페이지 너비의 비율로 표시된 왼쪽 가장자리입니다. 'y': type: number minimum: 0 maximum: 1 description: 페이지 높이 비율 기준 상단 가장자리입니다. width: type: number minimum: 0.02 maximum: 1 description: 페이지 너비에 대한 비율로 나타낸 너비입니다. 서명 너비는 최소 `0.12`입니다. height: type: number minimum: 0.012 maximum: 1 description: 페이지 높이에 대한 비율로 나타낸 높이입니다. 서명은 최소 `0.035` 높이여야 합니다. anchor: $ref: '#/components/schemas/SignatureFieldAnchor' required: type: boolean description: >- `signature` and `initials` are required unless you set `false`. `full_name`, `date_signed` and `data` are always required. The signer can't finish a document until its required fields have a value, and a required checkbox must be ticked. label: type: string minLength: 1 maxLength: 80 description: 서명자와 결과에 표시됩니다. 유형에 따른 기본값이 적용됩니다. placeholder: type: string nullable: true maxLength: 80 description: '`text` 및 `email`만 해당합니다.' validation: $ref: '#/components/schemas/SignatureFieldValidation' prefill: type: string nullable: true description: >- 값의 출처: `identity.full_name`, `identity.first_name`, `identity.last_name`, `identity.date_of_birth`(`DD/MM/YYYY`), `identity.nationality`, `identity.document_number`, `identity.document_type`, `identity.issuing_country`, `identity.address`, `contact.email`, `contact.phone`, `company.name`, `company.registration_number`, `company.address`, `company.country`(KYB), `session.vendor_data`, `metadata.`(세션 `metadata`의 키) 또는 `api.`(`sign.field_values`의 키). `data`에 필수입니다. `full_name`은 항상 `identity.full_name`을 사용하고 `email`은 `contact.email`을 사용합니다. `data`, `full_name` 및 인증된 `email` 필드의 값은 서명자가 서명을 시작할 때 고정됩니다. editable_when_prefilled: type: boolean default: false description: '`text` 및 `email`만 해당: 서명자가 사전 입력된 값을 변경할 수 있습니다.' checked_by_default: type: boolean default: false description: '`checkbox` 전용: 확인란이 선택된 상태로 시작합니다.' date_format: type: string enum: - DD/MM/YYYY - MM/DD/YYYY - YYYY-MM-DD - D MMMM YYYY default: DD/MM/YYYY description: '`date_signed`만 해당합니다.' SignatureFieldAnchor: type: object description: >- 위치 대신 문서 내의 텍스트 일부를 기준으로 필드를 배치합니다. Didit은 PDF에서 해당 텍스트를 제거하지 않으므로 페이지 배경과 동일한 색상으로 작성하십시오. 텍스트를 찾을 수 없는 경우 호출 시 `field_anchor_not_found`와 함께 `400`이 반환됩니다. [앵커 텍스트로 필드 배치하기](/ko/sessions-api/create-session#앵커-텍스트로-필드-배치)를 참조하십시오. required: - text properties: text: type: string minLength: 1 maxLength: 64 description: 문서에서 검색된 텍스트입니다. Word 파일의 경우 변환된 PDF 내에서 검색됩니다. occurrence: type: string enum: - first - all default: first description: '`all`은 일치 항목당 하나의 필드를 배치합니다. 첫 번째 키 이후의 키에는 `_2`, `_3` 등이 붙습니다.' offset_x: type: number description: 페이지 너비의 비율로 텍스트의 왼쪽 가장자리에 추가됩니다. offset_y: type: number description: 페이지 높이의 비율로 텍스트의 위쪽 가장자리에 추가됩니다. width: type: number minimum: 0.02 maximum: 1 description: 페이지 너비에 대한 비율로 나타낸 필드 너비입니다. height: type: number minimum: 0.012 maximum: 1 description: 페이지 높이에 대한 비율로 나타낸 필드의 높이입니다. SignatureFieldValidation: type: object nullable: true description: '`text` 필드 값에 대한 규칙입니다. 콘솔 미리보기, 서명 워크플로 및 API는 동일한 규칙을 적용합니다.' properties: kind: type: string enum: - any - letters - number - email - pattern description: >- `letters`: 모든 문자 체계의 문자, 공백, 하이픈 및 아포스트로피입니다. `number`: 선택적 소수점 구분 기호가 포함된 숫자입니다. `pattern`: 값은 `pattern`과 일치해야 합니다. min_length: type: integer minimum: 0 maximum: 500 description: '`0`부터 `max_length`까지입니다.' max_length: type: integer minimum: 1 maximum: 500 default: 120 pattern: type: string nullable: true minLength: 1 maxLength: 200 description: >- `kind: "pattern"`인 경우 필수입니다. 전체 값이 일치해야 하는 정규식입니다. 전방/후방 탐색(Lookaround) 및 역참조(backreference)는 지원되지 않습니다. message: type: string nullable: true maxLength: 120 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.