> ## 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 필드 수정

> 기존 세션에서 OCR로 추출된 KYC, 주소 증명(POA), KYB 법인 등기 필드를 수정하세요. PATCH 엔드포인트 3개, 부분 업데이트, webhook 발송을 지원합니다. Didit 호출당 과금.



세션 데이터 업데이트 프롬프트
        프롬프트를 클립보드에 복사



      
      

\<pre>

\`Correct OCR-extracted fields on a finished Didit verification session — KYC identity, Proof of Address, or KYB company data.

There are THREE separate PATCH endpoints. Pick the one that matches the feature record you need to fix.

1\) Update KYC identity data
PATCH https://verification.didit.me/v3/session/{session_id}/update-data/
\- Auth: x-api-key (client) or user-auth token. Privilege: write:sessions.
\- Session status must be one of Approved, Declined, In Review, Kyc Expired.
\- Session must have a captured KYC feature record.
\- Optional query / body param node_id targets a specific KYC instance in multi-step workflows (e.g. node_id=feature_ocr_2).
\- Mutable fields: document_type ("P", "ID", "DL", "RP"), document_number, personal_number, date_of_birth (ISO date), date_of_issue, expiration_date, issuing_state (ISO 3166-1 alpha-3), first_name, last_name (full_name is auto-recomputed), gender ("M"|"F"|"X"), nationality, marital_status, place_of_birth, address (free-text — triggers re-geocoding), parsed_address (nested: address_type, city, region, street_1, street_2, postal_code, country [ISO 3166-1 alpha-2]), extra_fields (object — send null on a key to remove it).

2\) Update Proof of Address (POA) data
PATCH https://verification.didit.me/v3/session/{session_id}/update-poa-data/
\- Same auth + privilege + status gate as KYC.
\- Session must have a captured POA record. node_id supported.
\- Mutable fields: issuing_state (ISO-3), document_type ("utility_bill" | "bank_statement" | "lease_agreement"), document_language (ISO 639-1), issuer, issue_date (ISO date), poa_address (free-text — triggers re-geocoding), name_on_document, poa_parsed_address (same nested shape as KYC parsed_address), extra_fields (bank_account_number, bank_iban, bank_sort_code, bank_routing_number, bank_swift_bic, bank_branch_name, bank_branch_address, document_phone_number, additional_names).

3\) Update KYB company data
PATCH https://verification.didit.me/v3/session/{session_id}/kyb/{company_uuid}/update-data/
\- Privilege: write:businesses (NOT write:sessions).
\- No status gate — KYB company data can be corrected at any time.
\- company_uuid must belong to that session_id (else 404).
\- Mutable fields: company_name, registration_number, country_code (ISO-3), incorporation_date / registration_date / dissolution_date, tax_number, legal_address (lands on registered_address), company_type, registry_status ("active" | "dissolved" | "struck_off" | "inactive" | ...), verification_status ("verified" | "failed" | "unknown"), alternative_names, nature_of_business, registered_capital, website, email, phone, legal_entity_identifier, location_of_registration, control_scheme.
\- Edits BOTH the canonical column and registry_data. user_provided_data is never touched.

4\) Skip (or re-require) a Key People party
PATCH https://verification.didit.me/v3/session/{session_id}/kyb/parties/{party_uuid}/
\- Privilege: write:businesses.
\- Body: { "is_skipped": true } to exempt the party, { "is_skipped": false } to put it back in scope.
\- party_uuid must belong to that session_id (else 404).
\- Use it when a party can no longer finish its own check - most often because the linked individual KYC session was deleted - and the KYB is stuck in Awaiting User with nothing left that can move it.
\- Independent of the role's allow_skip setting: that flag limits what the applicant may skip in the hosted flow, not what you may override.
\- requires_verification is left untouched, so the override stays visible as requires_verification: true + is_skipped: true.
\- Recomputes the Key People check and the parent session status immediately, and fires data.updated with trigger: "console_key_people_skip".

Common contract for all four:
\- PATCH semantics — only fields you send are updated. Omit a field to leave it as-is. Send null on an extra_fields key to remove it.
\- A successful update fires a data.updated webhook (with session_kind: "user" or "business"). KYB company updates carry trigger: "console_registry_edit".
\- The audit trail records changed fields, previous + new values, and (for user-auth) the actor email.

KYC curl example:
curl -X PATCH "https://verification.didit.me/v3/session/<SESSION_ID>/update-data/" \
-H "x-api-key: <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-01-01",
"issuing_state": "ESP",
"extra_fields": { "municipality": "Madrid" }
}'

Response: the updated record (KYC / POA / KYB company shape — same fields as in the session decision).

Failure modes:
\- 401 — missing or invalid credentials.
\- 403 — { "detail": "You do not have permission to perform this action." } — caller lacks write:sessions (KYC/POA) or write:businesses (KYB company).
\- 404 — { "detail": "Not found." } — session, node_id, or company_uuid not found; OR the session does not carry the feature record you are patching (no KYC / no POA / no matching company).
\- 400 — validation error: invalid country code, unknown parsed_address key, extra_fields not an object, etc. Returned as { "<field>": ["..."] }.

When NOT to use these endpoints:
\- To ask the user to retake the document → use PATCH /v3/session/{id}/update-status/ with new_status: "Resubmitted" (see /sessions-api/update-status).
\- To change entity-level data → use /v3/users/{vendor_data}/ or /v3/businesses/{vendor_data}/.
\- To edit Key People names / roles / ownership - no public API; that data is submitted through the hosted flow. Only the is_skipped flag is patchable (endpoint 4).

Side effects:
\- Changes to KYC name / DOB / nationality can re-trigger AML if AML was still running.
\- Changes to address / poa_address re-run geocoding asynchronously (failures swallowed — they never fail the update).

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

\</pre>



      
      

붙여넣을 곳

OCR이 신분증, 공과금 고지서, 등기부 항목을 잘못 읽는 경우가 있습니다. Didit은 인증을 처음부터 다시 진행하지 않고도 추출된 데이터를 수정할 수 있도록 PATCH endpoint 세 개를 제공합니다.| Endpoint | 사용 시점 |
| - | - |
| [`PATCH /v3/session/{id}/update-data/`](#kyc-신원-데이터-업데이트) | **사용자 인증(KYC)** 세션에서 신분증 문서로부터 추출된 값을 수정할 때 |
| [`PATCH /v3/session/{id}/update-poa-data/`](#주소-증명-poa-데이터-업데이트) | **사용자 인증(KYC)** 세션에서 공과금 고지서, 은행 거래내역서, 임대차 계약서로부터 추출된 값을 수정할 때 |
| [`PATCH /v3/session/{id}/kyb/{company_uuid}/update-data/`](#kyb-기업-데이터-업데이트) | **기업 확인(KYB)** 세션에서 등기부로부터 추출된 필드를 수정할 때 |
| [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](#주요-인물-당사자-건너뛰기) | 주요 인물 당사자가 더 이상 자신의 확인을 완료할 수 없을 때 해당 당사자를 인증 대상에서 제외할 때 |네 endpoint 모두 **클라이언트 API 키** 또는 **사용자 권한 부여 헤더**를 받으며, 성공하면 모두 `data.updated` webhook을 발생시켜 시스템과 후속 분석 데이터가 동기화된 상태를 유지하도록 합니다.## 공통 요구 사항- **권한 부여**: 클라이언트 API 키(표준 `x-api-key` / `Authorization` 베어러) 또는 사용자 권한 부여 토큰.
- **권한**:
  * KYC 및 POA: `write:sessions`
  * KYB 기업 및 주요 인물 당사자: `write:businesses`
- **세션 상태**(KYC / POA 전용): `APPROVED`, `DECLINED`, `IN_REVIEW`, `KYC_EXPIRED` 중 하나여야 합니다. 검토 가능한 상태에 도달하지 않은 세션은 수정할 수 없습니다. KYB 기업 업데이트에는 상태 제한이 없습니다.
- **기능 레코드가 있어야 합니다**: KYC 필드는 세션에 KYC가 수집된 경우에만, POA 필드는 세션에 POA가 수집된 경우에만, KYB 기업 필드는 세션에 등기부 확인이 있는 경우에만 수정할 수 있습니다.
- **부분 업데이트**: 포함한 필드만 변경됩니다. 필드를 생략하면 현재 값이 그대로 유지됩니다. `extra_fields` 키를 지우려면 `null`을 보내세요.
- **webhook**: 업데이트가 성공하면 `session_kind: "user"` 또는 `"business"`와 함께 `data.updated`가 발생하며, 세션의 감사 로그에는 변경된 특정 필드와 변경한 사용자가 기록됩니다.## KYC 신원 데이터 업데이트**`PATCH /v3/session/{sessionId}/update-data/`**신분증 문서에서 추출된 필드를 모두 수정할 수 있습니다. 선택적 `node_id` 쿼리 파라미터 또는 본문 필드를 사용하면 그래프 기반 다중 인스턴스 워크플로를 지원합니다. 하나의 세션에 KYC 단계가 여러 개 있을 때 특정 KYC 레코드를 대상으로 지정하세요.### 수정 가능한 필드| 필드 | 참고 |
| - | - |
| `document_type` | ISO 문서 코드: `P`(여권), `ID`, `DL`, `RP`. |
| `document_number` | 문서에 인쇄된 문서 번호. |
| `personal_number` | 문서에 인쇄된 경우의 개인 번호 또는 납세자 번호. |
| `date_of_birth` | ISO 8601 형식의 생년월일. |
| `date_of_issue` / `expiration_date` | ISO 8601 형식의 발급일 / 만료일. |
| `issuing_state` | 발급 국가, ISO 3166-1 alpha-3. |
| `first_name` / `last_name` | `full_name`은 이 두 값으로부터 자동으로 다시 계산됩니다. |
| `gender` | 있는 경우 `M`, `F`, `X`. |
| `nationality` | 자유 형식 텍스트. |
| `marital_status` | 자유 형식 텍스트. |
| `place_of_birth` | 자유 형식 텍스트. |
| `address` | 문서의 자유 형식 주소. 재지오코딩이 실행됩니다. |
| `parsed_address` | 구조화된 주소. 아래 중첩 형식을 참고하세요. |
| `extra_fields` | 신분증의 임의 추가 필드(예: `blood_group`, `municipality`). 키를 제거하려면 `null`을 보내세요. |`parsed_address`는 다음 중첩 키만 허용합니다: `address_type`, `city`, `region`, `street_1`, `street_2`, `postal_code`, `country`(ISO 3166-1 **alpha-2**).### 예시```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/4c5c7f3a.../update-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01",
    "issuing_state": "ESP",
    "extra_fields": { "municipality": "Madrid" }
  }'
```다중 인스턴스 그래프 워크플로에서 특정 KYC 레코드를 대상으로 지정하려면 URL에 `?node_id=feature_ocr_2`를 추가하거나 본문에 `"node_id": "feature_ocr_2"`를 전달하세요.## 주소 증명(POA) 데이터 업데이트**`PATCH /v3/session/{sessionId}/update-poa-data/`**주소 증명 문서에서 추출된 필드를 수정합니다. KYC 업데이트와 같은 상태 제한과 권한이 적용됩니다. 다중 인스턴스 워크플로를 위해 `node_id`도 지원합니다.### 수정 가능한 필드| 필드 | 참고 |
| - | - |
| `issuing_state` | 문서를 발급한 국가, ISO 3166-1 alpha-3. |
| `document_type` | 예: `utility_bill`, `bank_statement`, `lease_agreement`. |
| `document_language` | 문서의 ISO 639-1 언어 코드. |
| `issuer` | 공과금 서비스 제공업체, 은행, 집주인 등. |
| `issue_date` | ISO 8601 형식의 날짜. |
| `poa_address` | 문서에 인쇄된 주소(자유 형식 텍스트). 재지오코딩이 실행됩니다. |
| `name_on_document` | 문서에 인쇄된 전체 성명. |
| `poa_parsed_address` | 구조화된 주소. KYC `parsed_address`와 같은 중첩 형식입니다. |
| `extra_fields` | 문서별 추가 필드: 은행 정보(`bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`), `document_phone_number`, `additional_names`(목록 또는 `null`). |### 예시```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/4c5c7f3a.../update-poa-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "utility_bill",
    "issuer": "Iberdrola",
    "issue_date": "2026-03-15",
    "name_on_document": "Jane Doe",
    "poa_parsed_address": {
      "street_1": "Calle Mayor 10",
      "city": "Madrid",
      "postal_code": "28013",
      "country": "ES"
    }
  }'
```## KYB 기업 데이터 업데이트**`PATCH /v3/session/{sessionId}/kyb/{companyUuid}/update-data/`**레지스트리에서 추출된 KYB 기업 필드의 잘못된 값을 수정합니다. 이 엔드포인트는 기업의 기준 열과 `registry_data`를 **모두** 수정하므로, 콘솔의 "Extracted from Registry" 보기에 수정 내용이 반영됩니다. `user_provided_data`(호스팅 흐름에서 최종 사용자가 확인한 값)는 변경되지 않습니다. `last_console_edit_at`이 기록되고, `trigger: "console_registry_edit"`와 함께 `data.updated` webhook이 발생합니다.### 요구 사항- **권한**: `write:businesses` (KYC / POA 권한과 다릅니다).
- URL의 `companyUuid`는 지정한 `sessionId`에 속해야 합니다. 그렇지 않으면 404 응답이 반환됩니다.
- 세션 상태 제한이 없습니다. KYB 기업 데이터는 언제든지 수정할 수 있습니다.### 변경 가능한 필드| 필드 | 비고 |
| - | - |
| `company_name` | 법적 명칭. |
| `registration_number` | 공식 등록번호. |
| `country_code` | 설립 국가, ISO 3166-1 alpha-3. |
| `incorporation_date` / `registration_date` / `dissolution_date` | ISO 8601 날짜. |
| `tax_number` | 납세자 번호. |
| `legal_address` | `registered_address`의 별칭입니다. 값은 기준 `registered_address` 열에 저장됩니다. |
| `company_type` | Ltd / LLC / PLC / SA / GmbH / SL 등. |
| `registry_status` | `active`, `dissolved`, `struck_off`, `inactive` 등. |
| `verification_status` | `verified`, `failed`, `unknown`. |
| `alternative_names` | 상호, 이전 명칭, DBA. |
| `nature_of_business` | 간단한 설명. |
| `registered_capital` | 수권 자본 / 발행 자본. |
| `website`, `email`, `phone` | 연락처 정보. |
| `legal_entity_identifier` | LEI. |
| `location_of_registration` | 도시 / 행정 구역. |
| `control_scheme` | 레지스트리에서 제공하는 경우의 지배 구조 체계. |생략한 필드는 변경되지 않습니다. 전송한 필드는 기준 열(해당 열이 있는 경우)에 기록되고 `registry_data`에 병합됩니다. `registry_data`에 병합될 때 날짜는 ISO 8601 문자열로 직렬화됩니다.### 예시```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/bs-01HJX1.../kyb/f7a9c1b2-4e6d.../update-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corporation Limited",
    "registration_number": "12345678",
    "registry_status": "active",
    "legal_address": "1 Main Street, London EC1A 1AA, United Kingdom",
    "alternative_names": "Acme Ltd, Acme Group"
  }'
```응답: 전체 KYB 기업 객체입니다. 형식은 [세션 결정](https://docs.didit.me/ko/sessions-api/retrieve-session.md#기업-확인-kyb)의 `registry_checks[].company`와 동일합니다.## 주요 인물 당사자 건너뛰기**`PATCH /v3/session/{sessionId}/kyb/parties/{partyUuid}/`**자체 확인을 끝낼 수 없는 당사자를 인증에서 제외합니다. 이는 비상 수단입니다. 일반적인 원인은 자식 세션 삭제입니다. UBO 또는 이사에게 전달된 개인 KYC가 삭제되면 상태가 고정되어 결코 완료되지 않으며, KYB에는 `Awaiting User` 상태에서 벗어나게 할 방법이 없습니다. 당사자를 건너뛰면 주요 인물 집계에서 제외되고, 확인이 즉시 다시 계산되어 세션이 완료되고 승인 또는 거부될 수 있습니다.### 요구 사항- **권한**: `write:businesses`.
- URL의 `partyUuid`는 지정한 `sessionId`에 속해야 합니다. 그렇지 않으면 404 응답이 반환됩니다.
- **`allow_skip`의 제한을 받지 않습니다.** 이 역할 설정은 신청자가 호스팅 주요 인물 화면을 작성하는 동안 건너뛸 수 있는 항목을 제한합니다. 이 엔드포인트는 운영자가 사용하는 재정의이므로, 신청자가 건너뛸 수 없었던 역할에서도 작동합니다.### 요청 본문| 필드 | 유형 | 비고 |
| - | - | - |
| `is_skipped` | boolean | `true`는 당사자를 제외합니다. `false`는 당사자를 다시 대상에 포함하며, 확인 절차가 해당 당사자를 다시 기다리게 됩니다. |`requires_verification`은 의도적으로 변경되지 않으므로, 재정의된 당사자는 `requires_verification: true` 그리고 `is_skipped: true`로 표시됩니다. 이 기록은 규칙이 확인을 요구했다는 사실을 계속 보여 줍니다.### 예시```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/bs-01HJX1.../kyb/parties/0a3f1e2c-7c2f.../" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_skipped": true }'
```응답: 업데이트된 당사자입니다. 형식은 [세션 결정](https://docs.didit.me/ko/business-verification/response-schema.md#key_people_checks)의 `key_people_checks[].submitted.parties[]` 항목과 동일합니다.`trigger: "console_key_people_skip"`와 함께 `data.updated` webhook이 발생합니다.> [!NOTE]
>
> 자식 세션이 삭제된 당사자는 결정 페이로드에 `kyc_session_deleted: true`(법인 당사자의 경우 `kyb_sub_session_deleted: true`)로 표시되며, 링크가 더 이상 연결되지 않으므로 `kyc_session_url` / `kyb_sub_session_url`은 `null`로 반환됩니다. 자식 세션을 삭제해도 그것만으로 당사자가 승인되지는 않습니다. 주요 인물 확인이 `In Review` 상태가 되어 사람이 판단하도록 합니다.## 업데이트 후 발생하는 일- **Webhook**: 세션에 대해 `data.updated`가 발생하며, 페이로드에는 세션의 `session_kind`(`"user"` 또는 `"business"`)가 포함됩니다. 대상 수준에서 한 번 구독하고 `session_kind`를 기준으로 라우팅합니다.
- **감사 추적**: 세션에는 변경된 필드, 이전 값과 새 값, 그리고(사용자 인증 호출의 경우) 작업자 이메일이 정확히 기록됩니다. 콘솔의 Events 탭에서 확인할 수 있습니다.
- **주소 재지오코딩**: `address` / `poa_address`를 변경하는 KYC 및 POA 업데이트의 경우, Didit은 백그라운드에서 지오코딩을 다시 실행합니다. 실패는 무시되므로 지오코딩 문제로 업데이트가 실패하지 않습니다.
- **AML 재평가**: 세션에서 AML이 완료되지 않았다면, 이름, 생년월일 또는 국적을 변경하는 KYC 업데이트가 AML 스크리닝을 다시 트리거할 수 있습니다. 결과는 세션 결정에 표시됩니다.## 이 엔드포인트를 사용하지 말아야 할 경우- **전체 인증 다시 실행**: 고객이 신분증 사진을 다시 찍거나 문서를 다시 업로드해야 한다면, 세션을 `Resubmitted`로 이동하려면 [update-status](https://docs.didit.me/ko/sessions-api/update-status.md)를 사용하십시오.
- **사용자 또는 기업 엔티티의 프로필 필드 변경**: [`PATCH /v3/users/{vendor_data}/`](https://docs.didit.me/ko/management-api/users/update) 또는 [`PATCH /v3/businesses/{vendor_data}/`](https://docs.didit.me/ko/management-api/businesses/update)를 사용하십시오. 이 엔드포인트들은 세션 수준이 아닌 엔티티 수준 데이터를 업데이트합니다.
- **주요 인물 세부 정보 편집**: 당사자의 이름, 역할 또는 소유권을 패치하는 공개 API는 없습니다. 해당 데이터는 호스팅 흐름을 통해 제출됩니다. 패치할 수 있는 유일한 필드는 `is_skipped`입니다([주요 인물 당사자 건너뛰기](#주요-인물-당사자-건너뛰기) 참조).## 오류| 상태 코드 | 의미 |
| - | - |
| `401` | 자격 증명이 없거나 잘못되었습니다. |
| `403` | 호출자에게 필요한 권한(`write:sessions` 또는 `write:businesses`)이 없습니다. |
| `404` | 세션을 찾을 수 없거나, 세션에 업데이트하려는 레코드가 없습니다(KYC 없음, POA 없음, 일치하는 기업 없음, 일치하는 당사자 없음, 또는 다른 세션에 속한 당사자). |
| `400` | 검증 오류입니다. 잘못된 국가 코드, 알 수 없는 `parsed_address` 키, 객체가 아닌 `extra_fields` 등이 해당합니다. |## 다음 단계> [card] [세션 조회](https://docs.didit.me/ko/sessions-api/retrieve-session.md)
>
> 업데이트된 필드를 확인하려면 전체 결정을 가져오세요.> [card] [상태 업데이트](https://docs.didit.me/ko/sessions-api/update-status.md)
>
> 데이터 수정 후 세션을 승인, 거부 또는 다시 열 수 있습니다.> [card] [webhook](https://docs.didit.me/ko/integration/webhooks.md)
>
> `data.updated` 이벤트를 구독하세요.


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