메인 콘텐츠로 건너뛰기
GET
cURL

KYC 및 KYB 지원

이 엔드포인트는 사용자 인증(KYC) 세션과 기업 확인(KYB) 세션 모두에서 작동합니다. 응답에는 항상 최상위 session_kind 필드가 포함됩니다.
  • "user": 사용자 인증(KYC) 세션입니다. 응답에 id_verifications, liveness_checks, face_matches, nfc_verifications, poa_verifications, database_validations가 포함됩니다.
  • "business": 기업 확인(KYB) 세션입니다. 응답에 registry_checks, document_verifications, key_people_checks가 포함됩니다.
두 유형 모두 aml_screenings, phone_verifications, email_verifications, questionnaire_responses, ip_analyses, document_ai_documents, bank_verifications, reviews, contact_details를 공유하며, 공통 최상위 필드(session_id, session_number, session_url, status, workflow_id, vendor_data, metadata, callback, features, expected_details, created_at, expires_at)도 함께 포함됩니다. Didit는 session_id를 두 세션 유형 모두에서 조회합니다. 먼저 사용자 인증(KYC) 세션을, 다음으로 기업 확인(KYB) 세션을 확인하고 일치하는 결과를 반환합니다. UUID는 애플리케이션마다 고유하므로 혼동될 여지가 없습니다. 유형별 기능의 전체 목록은 세션 개요를 참조하십시오.

예시

응답(일부 생략):

응답을 클라이언트에서 처리하기

상태, 결정 추적 및 검토 필드

모든 결정에는 status가 어떻게 도출되었는지가 설명되어 있습니다.

생체 데이터 보존

biometric_retention은 항상 포함됩니다. deletes_at은 세션의 활성 생체 데이터가 삭제되는 날짜이고, jurisdictions는 해당 사용자에 대해 생체 정보 규정이 삭제 기한을 정한 미국 주 목록입니다(주를 알 수 없는 경우 US). 적용되는 날짜가 아직 없으면 deletes_at은 null입니다.

위치 확인

워크플로에 위치 확인 단계가 있으면 결정 결과에 두 개의 배열이 포함됩니다. geolocation_checks[]에는 단계마다 하나의 항목이 있으며, 승인된 시도의 결과, 좌표와 정확도, IP 위치 및 등록된 주소와의 대조 결과, 해당 단계의 warnings가 포함됩니다. geolocation_attempts[]에는 모든 단계의 모든 시도가 가장 오래된 순서로 나열되며, 각 시도를 수신한 시각이 함께 표시됩니다. 워크플로에 해당 단계가 없으면 두 값 모두 null로 반환됩니다. 모든 필드와 결과는 위치 확인 보고서에 설명되어 있습니다.

워크플로 라우팅 이벤트

?include=events는 세션의 이벤트 타임라인을 추가합니다. 단계 및 상태 변경 이벤트와 함께, 분기 노드를 거치는 워크플로는 라우팅 결정마다 이벤트를 하나씩 남깁니다. 따라서 연동 시스템이나 Console 타임라인에서 워크플로 그래프를 직접 따라가지 않고도 세션이 특정 결과로 끝난 이유를 설명할 수 있습니다. 두 이벤트 모두 다른 이벤트와 마찬가지로 밀리초 단위의 sent_at을 포함하며, component, feature_step, step은 포함하지 않습니다. 사용자 기기가 아니라 워크플로 엔진에서 발생하기 때문입니다. 조건이 없는 “else” 분기는 일치한 분기로 간주합니다. fallback은 어떤 분기도 일치하지 않았을 때만 true입니다. 출구 간선이 하나뿐인 노드는 결정을 내리지 않으며 이벤트도 남기지 않습니다. 같은 구조에는 workflow_terminal_node_id도 포함됩니다. 이 값은 세션 상태를 설정한 마지막 워크플로 상태 노드의 node_id이며, 그런 노드 ID가 기록되지 않았다면 null입니다. 이는 워크플로의 과거 경로 정보입니다. 수동 승인, 거부, 재제출은 이 값을 지우지 않으며, 이후 워크플로 상태 노드가 나타나면 그 노드로 교체됩니다. 예를 들어 워크플로가 세션을 In Review 노드로 보냈고 검토자가 나중에 승인했다면, 현재 status는 Approved이지만 workflow_terminal_node_id는 여전히 In Review 노드를 가리킵니다. 재제출이 진행 중일 때도 이 값이 계속 채워져 있을 수 있습니다. 워크플로에 따른 결과와 이후의 수동 결정을 구분하려면 현재 status와 이벤트 및 activity_reviews 타임라인을 함께 확인하십시오.

이전 제출 내역(?include=resubmissions)

재제출은 사용자를 선택한 단계로 되돌려 보내며, 그 단계들이 이전에 반환한 결과를 유지합니다. ?include=resubmissions를 사용하면 재제출 요청마다 하나씩, 가장 오래된 순서로 정렬된 resubmissions 배열이 추가됩니다. 각 항목에는 해당 요청으로 대체된 결과가 포함되므로, 사용자가 이전에 제출한 내용을 언제든지 확인할 수 있습니다. 사용자(KYC) 세션과 기업(KYB) 세션 모두에서 동작하며, ?include=events,resubmissions처럼 이벤트와 함께 사용할 수 있습니다. 이 파라미터를 생략하면 응답은 변경되지 않습니다. 현재 결과(id_verifications 등 최상위 수준의 필드)는 항상 가장 최근 제출을 나타냅니다. 다시 보내지지 않은 단계는 그 자리에 결과가 하나만 유지됩니다.
세션을 삭제하면 모든 제출의 결과도 함께 삭제됩니다.

신분증 인증 방법

id_verifications[]의 각 항목은 신분증 인증 방법 세 가지 중 어떤 방법으로 결과가 생성되었는지 나타냅니다. 따라서 채워진 필드를 보고 추측하지 않아도 문서 판독, 등록부 조회, 지갑 로그인을 구분할 수 있습니다. 문서 세션은 document와 documentary를 보고하고 나머지는 null로 둡니다. 따라서 기존 연동은 변경할 필요가 없습니다. 필드별 타입은 데이터 모델에서 확인하십시오.

생체 인식 동의

사용자 인증 결정에는 biometric_consent 객체가 포함됩니다. 이 객체는 세션에 명시적 생체 인식 동의가 필요했는지, 동의를 요구한 trigger, 응답의 status, 그리고 그 근거를 나타냅니다. 다음 두 값은 동의가 수집되지 않았음을 나타냅니다. 동의 단계가 언제 나타나는지와 각 값의 의미는 생체 인식 동의에서 확인하십시오. 모든 필드는 데이터 모델에 있습니다.

은행 인증

워크플로에 은행 인증 단계가 있으면 결정 객체에 bank_verifications[]가 포함됩니다. 두 세션 유형 모두 해당하며, 단계당 항목 하나가 생성됩니다. 단계에서 결과가 나오기 전까지는 null입니다. 은행 로그인과 계좌 조회를 구분하려면 ownership.method가 아니라 method를 확인하십시오. ownership.method는 점수를 산출한 이름 비교 방식을 뜻합니다. 모든 필드는 이 endpoint 응답의 BankVerificationResult 스키마에 정의되어 있습니다.

전자 서명

워크플로에 전자 서명 단계가 있으면 결정 객체에 signatures[]가 포함됩니다. 두 세션 유형 모두 해당합니다. 서명자마다 항목이 하나씩 생성되며, 사용자 인증에서는 서명자가 한 명이고, 기업 확인에서는 서명하는 주요 인물마다 항목이 하나씩 생깁니다. 이 단계가 없는 워크플로에서는 이 키 자체가 반환되지 않습니다. API 키를 사용해 해당 경로에서 파일을 다운로드하십시오. 모든 필드는 전자 서명 보고서에서 확인할 수 있습니다.

오류

관련 문서

인증

x-api-key
string
header
필수

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 를 참고하십시오.

경로 매개변수

sessionId
string<uuid>
필수

결정을 조회하려는 인증 세션의 UUID입니다. 이는 POST /v3/session/에서 반환된 session_id입니다. 사용자 인증(KYC) 및 기업 확인(KYB) 세션 모두 동일한 경로를 사용하며, 서버는 두 세션 유형에 대해 ID를 확인합니다.

유효한 UUID여야 합니다. 라우트는 올바른 형식의 UUID만 일치시키므로, 잘못된 형식의 값은 애플리케이션 코드가 실행되기 전에 URL 라우터에 의해 거부되어 아래에 표시된 JSON {"detail": ...} 응답 형식 대신 404 HTML 페이지를 반환합니다. 클라이언트 측에서 UUID 형식을 검증하여 입력 오류와 실제 세션 누락에 따른 404를 구분할 수 있도록 하십시오.

예시:

"11111111-2222-3333-4444-555555555555"

쿼리 매개변수

include
enum<string>

추가 payload 섹션의 쉼표로 구분된 목록입니다. 지원되는 값: events, resubmissions, 또는 둘 다(events,resubmissions). include=events가 전달되면 응답에 세션 이벤트 타임라인(세션 조회 페이지에 설명된 WORKFLOW_BRANCH_EVALUATED / WORKFLOW_STATUS_NODE_REACHED 라우팅 이벤트를 포함하는 events), 전체 활동 로그(activity_reviews), 차단 목록 플래그(blocklisted), 세션당 cost_breakdown, 워크플로 메타데이터(세션 상태를 설정한 마지막으로 기록된 워크플로 상태 노드이자 기록된 것이 없으면 null인 workflow_terminal_node_id, workflow_type, workflow_version, workflow_version_id - 수동 승인, 거부 또는 재제출에 의해 지워지지 않으며 이후의 워크플로 상태 노드로 대체되는 이력 정보), 세션 메타데이터(독립형 API 세션에만 설정되는 문자열 또는 null인 api_service, API, HOSTED 또는 MIGRATED인 session_type, 불리언 값인 has_device_nfc_support)가 추가로 포함됩니다. 기본 형태와 비교하여 두 가지 필드가 변경됩니다. 최상위 session_kind 구분자가 생략되며(events 형태는 사용자 세션에만 존재함), features 배열이 단순 문자열에서 {feature, node_id} 객체로 전환됩니다(이때 이메일 기능은 EMAIL_VERIFICATION 대신 EMAIL로 보고됨). 이 확장된 형태는 주로 Didit Console에서 사용되며, 대부분의 API 연동에서는 이 파라미터를 생략해야 합니다. KYB 제한 사항: include=events는 사용자(KYC) 세션에만 적용됩니다. 기업 세션(session_kind = "business")은 항상 표준 기업 결정 형태를 반환합니다. 기업 세션에는 events, activity_reviews, blocklisted, cost_breakdown 및 추가 workflow_*/세션 메타데이터가 절대 반환되지 않으며, features 배열은 단순 문자열 배열로 유지됩니다. include=resubmissions를 사용하면(사용자 및 기업 세션 모두) 응답에 resubmissions도 포함됩니다. 재제출 요청당 하나의 항목이 가장 오래된 순서대로 포함되며, 각각 number, created_at, previous_status, nodes, reasons, requested_by, results(요청 전 재제출된 단계가 반환한 내용으로, 현재 결과와 동일한 키 및 형태로 제공됨)를 가집니다. 각 cost_breakdown 항목에는 usage_type, price, details, created_at이 포함됩니다. 다시 실행되는 재제출 단계는 새 항목으로 청구됩니다.

사용 가능한 옵션:
events,
resubmissions,
events,resubmissions
예시:

"events"

응답

전체 결정 보고서입니다. session_kind는 두 가지 형태를 구분합니다. user 세션은 아래에 표시된 KYC 기능 배열을 포함하고, business 세션은 공유 배열과 함께 registry_checks, document_verifications, key_people_checks를 대신 포함합니다. 기능 배열은 워크플로에서 해당 기능을 실행할 때까지 null이며, 미디어 URL은 유효 기간이 짧은 presigned 링크입니다.

session_id
string<uuid>

세션의 고유 식별자입니다.

session_kind
enum<string>

해당 세션이 사용자 인증(KYC)인지 기업 확인(KYB) 세션인지 나타내는 구분자입니다. user인 경우 KYC 기능 배열(id_verifications, nfc_verifications, liveness_checks, face_matches, poa_verifications, document_ai_documents, database_validations, ...)이 적용되고 기업 배열은 제외됩니다. business인 경우 payload에는 대신 registry_checks, document_verifications, key_people_checks와 공유 배열(aml_screenings, phone_verifications, email_verifications, ip_analyses, questionnaire_responses)이 포함됩니다. include=events가 전달된 경우 생략됩니다 — 이벤트 형태는 사용자 세션에만 존재하므로 해당 변형에서는 구분자가 제외됩니다.

사용 가능한 옵션:
user,
business
shared_from_session
string<uuid> | null

POST /v3/session/import-shared/로 복제된 세션의 경우: 소스 애플리케이션의 원본 세션 session_id입니다. 다른 모든 세션의 경우 null입니다. include=events가 전달되면 생략됩니다.

shared_from_session_number
integer | null

이 세션을 조직의 다른 애플리케이션에서 가져온 경우 소스 세션의 session_number입니다. 그렇지 않으면 null입니다.

session_number
integer | null

세션 번호입니다.

session_url
string<uri> | null

세션의 URL입니다.

status
enum<string>

세션의 전체 라이프사이클 상태 — 취합된 워크플로 결과입니다. 최종 값은 Approved, Declined, In Review, Expired, Kyc Expired, Abandoned이며, Not Started, In Progress, Awaiting User, Resubmitted는 세션이 아직 워크플로를 진행 중임을 나타냅니다.

사용 가능한 옵션:
Not Started,
In Progress,
Awaiting User,
In Review,
Approved,
Declined,
Resubmitted,
Expired,
Kyc Expired,
Abandoned
status_override
object | null

검토자가 status를 직접 설정했을 때 표시됩니다. 상태가 자동으로 지정된 경우 null입니다. 수동 승인과 자동 승인을 구분하는 데 사용합니다.

decision_trace
object

상태에 도달한 방식: 설정한 주체 및 해당 상태를 유발한 경고입니다.

linked_records
object | null

세션에 연결된 다른 레코드의 요약입니다. 표시할 내용이 없거나 연령 확인 기준을 선언하는 워크플로의 경우 null입니다.

workflow_id
string<uuid> | null

이 세션을 생성한 워크플로 그룹의 안정적인 식별자입니다. 워크플로는 버전이 관리되며, 이 값은 특정 버전이 아닌 워크플로 자체를 식별합니다.

features
string[]

이 세션에 구성된 인증 기능 목록이며, 표시 이름으로 제공됩니다: ID_VERIFICATION, NFC, LIVENESS, FACE_MATCH, POA, PHONE, EMAIL_VERIFICATION, AML, IP_ANALYSIS, DATABASE_VALIDATION, QUESTIONNAIRE, AGE_ESTIMATION, FACE_SEARCH, GEOLOCATION(위치 확인) (기업 확인(KYB) 세션은 KYB 기능 세트를 사용합니다: KYB_REGISTRY, KYB_DOCUMENTS, KYB_KEY_PEOPLE, AML, PHONE, EMAIL_VERIFICATION, IP_ANALYSIS, QUESTIONNAIRE). include=events를 사용하면 각 항목이 일반 문자열 대신 {feature, node_id} 객체가 되며, 이메일 기능의 이름이 변경됩니다. 여기에서 사용된 EMAIL_VERIFICATION 대신 이벤트 모드에서는 EMAIL로 표시됩니다.

세션의 기능입니다.

vendor_data
string | null

세션의 벤더 데이터입니다.

metadata
object | null

세션의 메타데이터입니다.

expected_details
object | null

세션 생성 시 제공된 예상 세부정보 — 추출된 데이터와의 교차 검증(KYC)에 사용되거나 법인 등기부 검색 사전 입력(KYB)에 사용됩니다. 제공된 키를 그대로 다시 반환하며, 아무것도 제공되지 않은 경우 null입니다. KYC 세션에는 개인 필드가 포함되며, 기업 확인(KYB) 세션에는 company_name, registry_country, registration_number가 포함됩니다.

contact_details
object | null

세션 생성 시 제공된 연락처 세부 정보입니다(알림 이메일, 미리 채워진 전화번호/이메일 인증, 통신 언어에 사용됨). 이메일과 전화번호가 모두 제공되지 않은 경우 null입니다.

callback
string<uri> | null

세션의 콜백 URL입니다.

id_verifications
object[] | null

워크플로 그래프의 신분증 문서 단계에서 생성된 신분증 인증(OCR) 보고서 배열입니다. 항상 JSON 배열입니다. 워크플로에서 둘 이상의 신분증 확인(예: 기본 확인에 추가적인 스텝업 확인)을 실행할 수 있는 경우 id_verifications[0]을 읽고 반복 처리하십시오. 하나 이상의 신분증 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 기능 수준 status, 추출된 문서 필드, 이미지 URL, 품질 점수, MRZ, 주소 파싱, 세션 간 일치 항목, warnings[]를 포함한 전체 보고서입니다.

nfc_skip_reason
enum<string> | null

NFC 칩 인증이 실행되지 않은 이유로, 워크플로에 NFC 단계가 포함되어 있을 때마다 채워집니다. NFC가 대기 중이거나 칩을 실제로 읽은 경우에는 null입니다. 값: USER_SKIPPED - 사용자가 NFC 지원 기기에서 건너뛰기를 선택함(allow_nfc_skip에 의해 허용됨), DOCUMENT_WITHOUT_CHIP - 문서에 읽기 가능한 NFC 칩이 없음(ICAO 9303 전자 문서가 아님), CHIP_CERTIFICATE_UNAVAILABLE - 문서 발급 기간을 포함하는 발급 국가의 서명 인증서(CSCA)를 사용할 수 없어 칩 서명을 검증할 수 없음, DEVICE_WITHOUT_NFC - 기기에서 NFC 리더가 보고되지 않음, INTEGRATION_WITHOUT_NFC_ACCESS - 휴대폰의 NFC 리더에 접근할 수 없는 네이티브 SDK 없이(예: 웹 브라우저에서) 인증이 실행됨, MRZ_KEY_UNAVAILABLE - 문서의 MRZ에서 칩 접근 키를 도출할 수 없음, JPKI_UNAVAILABLE - 문서가 일본 마이넘버 카드이고 칩을 JPKI를 통해 읽는데, 해당 인증에서 JPKI를 사용할 수 없음(활성화되지 않았거나 앱의 네이티브 SDK가 마이넘버 카드를 읽을 수 없음).

사용 가능한 옵션:
USER_SKIPPED,
DOCUMENT_WITHOUT_CHIP,
CHIP_CERTIFICATE_UNAVAILABLE,
DEVICE_WITHOUT_NFC,
INTEGRATION_WITHOUT_NFC_ACCESS,
MRZ_KEY_UNAVAILABLE,
JPKI_UNAVAILABLE
nfc_verifications
object[] | null

워크플로 그래프의 NFC 단계에서 생성된 NFC / 전자여권 보고서 배열입니다. 단일 nfc 객체가 아닌 항상 JSON 배열입니다 — 워크플로에서 NFC를 두 번 이상 실행할 수 있는 경우 nfc_verifications[0]을 읽고 반복 처리하십시오. 하나 이상의 NFC 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 기능 수준 status, chip_protocol, chip_data, authenticity(SOD + DG 무결성), certificate_summary, warnings[]를 포함한 전체 보고서입니다. 일본 마이넘버카드는 ICAO 9303 대신 JPKI를 통해 읽힙니다. 해당 항목은 chip_protocol: "jpki"를 가지며 증거를 jpki 아래에 포함하고 ICAO 필드는 null로 유지합니다. NFC 단계를 제시할 수 있기 전에 건너뛴 경우(칩이 없는 문서, 인증서 누락, 보고된 NFC 기능 없음, 읽을 수 없는 MRZ 키, 마이넘버카드에 JPKI를 사용할 수 없음) 이 필드는 null로 유지되며 nfc_skip_reason에 이유가 설명됩니다. 단계 자체에서 건너뛴 경우(사용자가 건너뛰기를 탭했거나 스캔 시점에 리더기를 사용할 수 없는 것으로 나타남)에는 is_nfc_skipped: true인 보고서가 생성됩니다.

liveness_checks
object[] | null

워크플로 그래프의 라이브니스 단계에서 생성된 라이브니스 보고서 배열입니다. 단일 liveness 객체가 아닌 항상 JSON 배열입니다. 하나 이상의 라이브니스 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 기능 수준 status, method, score, reference_image, video_url, 선택 사항인 age_estimation, 세션 간 matches[], warnings[]를 포함한 전체 보고서입니다.

face_matches
object[] | null

워크플로 그래프의 얼굴 대조 단계에서 생성된 얼굴 대조 보고서 배열입니다. 단일 face_match 객체가 아닌 항상 JSON 배열입니다. 하나 이상의 얼굴 대조 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 기능 수준 status, 유사도 score, source_image, target_image, warnings[]를 포함한 전체 보고서입니다.

phone_verifications
object[] | null

전화번호 인증 보고서 배열 — 단일 phone 객체가 아닌 항상 JSON 배열입니다. 하나 이상의 전화번호 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 기능 수준 status, 전화번호 및 국가 메타데이터, lifecycle[], matches[], warnings[]를 포함한 전체 보고서입니다.

email_verifications
object[] | null

이메일 인증 보고서 배열 — 단일 email 객체가 아닌 항상 JSON 배열입니다. 하나 이상의 이메일 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 기능 수준 status, 이메일 주소, 유출 데이터, lifecycle[], matches[], warnings[]를 포함한 전체 보고서입니다.

poa_verifications
object[] | null

주소 증명(POA) 보고서 배열 — 단일 poa 객체가 아닌 항상 JSON 배열입니다. 하나 이상의 POA 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 기능 수준 status, 문서 파일 URL, 발급자, 날짜, 파싱된 주소, warnings[]를 포함한 전체 보고서입니다.

document_ai_documents
object[] | null

워크플로 노드별로 그룹화된 Document AI 보고서 — 항상 JSON 배열이며 단일 객체가 아닙니다. 최소 하나의 Document AI 단계에서 데이터가 생성될 때까지 null입니다. session_kind = user일 때만 표시됩니다. 각 항목은 집계된 status, node_id, 문서별 결과(구성된 필드 키를 키로 하는 추출된 데이터)의 items[] 배열, 그리고 warnings를 포함하는 노드 그룹입니다.

questionnaire_responses
object[] | null

설문지 응답 보고서 배열 — 단일 questionnaire 객체가 아닌 항상 JSON 배열입니다. 하나 이상의 설문지 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 설문지 메타데이터, 양식 요소가 포함된 섹션, 사용자의 답변을 포함한 전체 보고서입니다.

bank_verifications
object[] | null

사용자 인증 및 기업 확인(KYB)에 대한 은행 인증 단계별 한 항목씩의 은행 인증 결과입니다. 단계에서 결과가 생성될 때까지 null입니다. 각 항목의 method는 계좌가 어떻게 인증되었는지를 나타냅니다: open_banking(은행 로그인) 또는 account_lookup(계좌 조회), 또는 statement나 microdeposits 대체 수단, 그리고 시도가 평가되기 전에 사용자가 은행 없이 계속 진행한 경우(continued_without_bank) none입니다. 은행 인증 방법을 참조하십시오.

signatures
object[]

사용자 인증 및 기업 확인(KYB)에 대한 서명자 및 서명 단계별 전자 서명 결과 항목입니다. 워크플로에 전자 서명 단계가 있는 경우에만 표시되며, 서명자가 해당 단계에 도달할 때까지는 빈 배열입니다. 전자 서명 보고서를 참조하세요.

aml_screenings
object[] | null

AML 스크리닝 보고서 배열 — 단일 aml 객체가 아닌 항상 JSON 배열입니다. 하나 이상의 AML 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 기능 수준 status, total_hits, entity_type, hits[], score, screened_data, is_ongoing_monitoring_enabled 및 warnings[]를 포함한 전체 보고서입니다.

ip_analyses
object[] | null

기기 및 IP 분석 보고서 배열 — 단일 ip_analysis 객체가 아닌 항상 JSON 배열입니다. 하나 이상의 IP 분석 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 기능 수준 status, IP 및 지리적 위치 데이터, 기기 핑거프린트, warnings[]를 포함한 전체 보고서입니다. 중복된 (node_id, ip_address, device_fingerprint) 항목은 서버 측에서 중복 제거됩니다.

geolocation_checks
object[] | null

위치 검증 단계마다 하나씩 생성되며, 각 단계에서 수락된 시도를 나타내는 위치 검증 결과 배열입니다. 위치 검증 단계에서 데이터가 생성될 때까지 null입니다. 동일한 단계의 이전 시도는 geolocation_attempts에 포함됩니다.

geolocation_attempts
object[] | null

이 세션의 모든 위치 인증 단계 시도 내역(오래된 순)입니다. 재제출로 대체된 시도는 제외됩니다. 응답 속성을 통해 geolocation_checks를 보류하는 워크플로는 이 목록도 보류합니다.

database_validations
object[] | null

데이터베이스 검증 보고서 배열 — 단일 database_validation 객체가 아닌 항상 JSON 배열입니다. 하나 이상의 DB 검증 단계에서 데이터가 생성될 때까지 null입니다. 각 항목은 node_id, 기능 수준의 status, screened_data, 서비스별 validations[](각각 레지스트리 source_data 포함), warnings[]를 포함하는 전체 보고서입니다. screened_data 및 source_data 필드는 국가별로 다릅니다:

ARG (아르헨티나): screened_data: {document_number, selfie, gender, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, date_of_death, tax_id, tax_id_type, face_match_score, sit_1_since, banks, last_position, highest_position, rejected_checks}. RENAPER 생체 얼굴 대조 검증을 사용합니다. 신분증(예: 운전면허증)에 성별이 명시되어 있지 않은 경우 얼굴 분석 또는 이름에서 자동으로 추론됩니다.

BOL (볼리비아): screened_data: {document_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender}

BRA (브라질): screened_data: {tax_number, first_name, last_name, date_of_birth}. 일치하는 CPF 조회가 성공한 경우 source_data에는 항상 {identification_number, first_name, last_name, date_of_birth, lgpd_minor, minor_under_18, minor_under_16}이 포함됩니다. 성인 조회가 성공하면 해당 플래그는 false로 설정됩니다. Receita Federal Consulta CPF 서비스는 LGPD로 인해 보류된 데이터와 함께 HTTP 422(18세 미만 미성년자) 또는 451(16세 미만 미성년자)을 반환할 수 있습니다. 이러한 경우 source_data는 미성년자 플래그를 적절하게 true로 설정하고, 업스트림 HTTP 상태를 포함하며, 필드 수준 검증은 no_match가 됩니다. 전체 코드 목록은 데이터베이스 검증 결과 코드 참조 문서의 브라질 섹션을 확인하세요.

CHL (칠레): screened_data: {personal_number, first_name, last_name, date_of_birth}. source_data: {identification_number, first_name, last_name, date_of_birth, gender}

COL (콜롬비아): screened_data: {document_number, document_type, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, document_type}

CRI (코스타리카): screened_data: {personal_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}

DOM (도미니카 공화국): screened_data: {personal_number}. source_data: {identification_number} (유효/무효만 반환)

ECU (에콰도르): screened_data: {personal_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, street, formatted_address, gender, nationality, education, marital_status, spouse, mother_name, father_name, profession}

ESP (스페인): screened_data: {personal_number, document_type, expiration_date, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, document_type, expiration_date}

GTM (과테말라): screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}

HND (온두라스): screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}

MEX (멕시코): screened_data: {personal_number (CURP), first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender, nationality, curp_status, state_of_birth, doc_probatorio, registration_year, registration_state, registration_municipality, num_acta, crip, issuing_state_code, foreign_registry_number, folio_carta, folio_certificado}. RENAPO 주민등록 레지스트리를 사용합니다. 멕시코의 경우 추가적인 개별 검증으로 별도의 INE 유효성 검사 서비스도 이용할 수 있습니다.

PAN (파나마): screened_data: {personal_number, selfie}. source_data: {identification_number}. SIB 생체 인식 검증을 사용합니다

PER (페루): screened_data: {personal_number (DNI), first_name, last_name}. source_data: {identification_number, first_name, last_name, paternal_name, maternal_name, verification_number, verification_letter}

PRY (파라과이): screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}

SLV (엘살바도르): screened_data: {document_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}

URY (우루과이): screened_data: {personal_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}

VEN (베네수엘라): screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, gender, date_of_birth, document_type}

database_validation_not_performed_reason
object | null

설정된 데이터베이스 검증에서 결과가 생성되지 않은 이유로, {code, message}와 컨텍스트 필드로 표시됩니다. 해당 단계가 포함된 워크플로에서 database_validations가 null일 때만 표시되므로, "등기소가 일치함을 확인함"과 "아무것도 실행되지 않음"을 구분할 수 있습니다. 그 외의 경우에는 null입니다.

reviews
object[]
assignee
object | null

세션이 할당된 콘솔 검토자 또는 담당자가 없는 경우 null입니다.

waiting_since
string<date-time> | null

세션이 검토 대기를 시작한 시점입니다. 세션이 In Review 상태이고 애플리케이션에서 검토 기한을 설정한 경우가 아니면 null입니다.

sla_due_at
string<date-time> | null

검토가 완료되어야 하는 시점입니다. 세션이 In Review 상태이고 애플리케이션에서 검토 기한을 설정한 경우가 아니면 null입니다.

created_at
string<date-time>

세션이 생성된 타임스탬프(ISO 8601, UTC)입니다.

expires_at
string<date-time> | null

이 세션이 만료되도록 예약된 타임스탬프입니다. 생성 시 만료가 구성되었거나(Approved 상태가 되어 KYC 만료 계산이 트리거된 경우) 사용자 인증(KYC) 세션에 설정됩니다. 만료가 구성되지 않은 세션 및 만료를 사용하지 않는 종류(예: expires_at을 수신하지 않은 기업 확인(KYB) 세션)의 경우 null입니다.

registry_checks
object[] | null

법인 등기부 확인입니다. session_kind = business인 경우에만 존재합니다. 각 항목은 전체 법인 등기부 payload를 포함합니다.

key_people_checks
object[] | null

종합 주요 인물 확인입니다. session_kind = business인 경우에만 표시됩니다. 각 항목은 2개 버킷 형태(registry, submitted, ubo_kyc_summary)를 사용합니다.

document_verifications
object[] | null

워크플로 노드별로 그룹화된 문서 검증 확인 항목입니다. session_kind = business인 경우에만 표시됩니다.

environment
enum<string>

세션이 프로덕션 애플리케이션(live)에서 생성되었는지 또는 샌드박스 애플리케이션(sandbox)에서 생성되었는지 여부입니다. 샌드박스 세션은 무료이며 완전히 시뮬레이션되고 크레딧이 청구되지 않습니다.

사용 가능한 옵션:
live,
sandbox
sandbox_scenario
string | null

세션 생성 시 사용된 샌드박스 시나리오입니다. 라이브 세션 및 시나리오 없이 생성된 샌드박스 세션의 경우 null입니다.

resubmissions
object[]

사용자 및 기업 세션에 대해 include=resubmissions가 포함된 경우에만 반환됩니다. 재제출 요청당 하나의 항목이 오래된 순서대로 반환됩니다. 각 항목에는 요청 전 재제출된 단계가 반환한 결과가 포함되어 있으므로 이전 제출 내용을 계속 읽을 수 있습니다. 세션을 삭제하면 모든 제출 내용이 삭제됩니다.

세션에서 얼굴 캡처 전 명시적인 생체 인식 동의가 필요했는지 여부, 그 이유 및 응답 증거입니다. 사용자 인증(KYC) 세션 전용이며, 세션 webhook의 decision에도 동일한 객체가 포함됩니다. 얼굴 캡처가 없는 워크플로 등 세션이 평가된 적이 없는 경우 null입니다. 기록된 값이 없는 필드는 null입니다. 4.10.0 미만의 네이티브 SDK 또는 버전을 보고하지 않는 SDK는 동의 단계를 표시할 수 없습니다. 이 경우 얼굴 캡처는 이전과 동일하게 실행되며, 동의가 필요했던 세션은 status: "pending"과 함께 reason: "BIOMETRIC_CONSENT_UNSUPPORTED_SDK"를 보고합니다. 생체 인식 동의를 참조하세요.

investigator
object | null

항목의 최신 조사관 검토 내역이며, 검토가 진행된 적이 없는 경우 null입니다. V3 세션 및 기업 세션 결정에 포함되어 전달됩니다(따라서 status.updated webhook에서도 전달됨).

biometric_retention
object

이 세션의 라이브 생체 데이터가 삭제되는 시점입니다.

fraud_check
object | null

Fraud Check API 호출 결과입니다. 다른 모든 세션의 경우 null입니다.

full_session_video
string<uri> | null

전체 세션 녹화본의 만료되는 URL입니다. 조직에서 전체 세션 동영상을 녹화하는 경우에만 반환됩니다.

full_session_video_recorded_at
string<date-time> | null

전체 세션 녹화가 생성된 시점입니다. 조직에서 전체 세션 동영상을 녹화하는 경우에만 반환됩니다.

마지막 수정일 2026년 11월 7일