메인 콘텐츠로 건너뛰기
POST
curl
이 endpoint를 가장 먼저 호출해 일치하는 법인 등기부 후보를 찾으세요. 검색만으로는 저장된 Manual Check가 만들어지지 않습니다. 유료 기업 데이터 소스를 사용하는 독립형 검색이 성공하면 후보 수와 관계없이 요청당 $0.50이 청구됩니다. 결과가 없거나, 검색이 실패하거나, 다른 소스에서만 결과가 제공된 경우에는 청구되지 않습니다. 이후 프로필을 가져오는 요청은 별도로 과금됩니다. 유료 소스를 사용할 수 있는 검색의 경우, Didit는 레지스트리에 연결하기 전에 해당 검색 가격을 확인하고 예약합니다. 잔액이 부족하면 403과 code: "insufficient_credits"가 반환됩니다. 계약 과금은 합의된 검색 요율을 따르며, 설정되지 않은 계약 요율은 검색 전에 거부됩니다. 샌드박스 검색은 무료입니다. 성공한 검색을 반복할 때마다 새로운 과금 대상 요청이 되며, 콜백 전송은 검색 요금을 추가로 부과하지 않습니다. webhook_url을 보내면 Didit는 제공업체가 검색을 처리하는 동안 즉시 응답하고, 후보가 준비되면 콜백 URL로 후보를 전송할 수 있습니다. 이 콜백은 설계상 서명되지 않으므로, 이 검색 알림을 위해 webhook 시크릿을 설정할 필요가 없습니다. 검색 콜백 페이로드 예시를 참고하세요. 올바른 kyb_response_id를 선택한 후에는 POST /v3/kyb/select/(Lite), POST /v3/kyb/shareholders/ 또는 POST /v3/kyb/ubo/를 호출해 필요한 등급으로 과금 대상 레지스트리 프로필을 가져오세요.
각 후보의 fetch_status는 검색 시점에 pending이며, 해당 후보를 선택하기 전까지 pending 상태를 유지합니다. 검색은 후보 목록만 제공하고, 전체 프로필은 선택할 때 가져옵니다. 해결될 때까지 검색을 폴링하지 마세요.kyb_response_id는 하나의 검색 요청에만 범위가 지정된 불투명하고 일시적인 핸들입니다. 받은 그대로 다시 전달하고, 내용을 해석하거나 그것으로부터 아무것도 유도하지 마세요. 같은 검색을 반복하면 새로운 id가 반환된다는 점을 예상해야 합니다. 검색 후 가능한 한 빨리 후보를 선택하고, 회사 자체를 식별하는 안정적인 식별자가 필요하면 registration_number를 사용하세요.

검색 등급

tier는 검색이 실행될 레지스트리 등급의 제공업체 체인을 선택합니다. 값은 basic(기본값, Lite 체인), shareholders 또는 ubo입니다. 후보 목록은 해당 등급의 체인에서 가져오며, 이 체인이 Lite 검색이 조회하는 소스와 항상 같지는 않습니다. 따라서 Lite 검색 결과가 비어 있어도 레지스트리에 해당 회사가 없다는 뜻은 아닙니다. 필요한 등급으로 다시 검색하세요. 지정하신 등급을 국가에서 제공하지 않는 경우, 검색은 그 등급까지 제공되는 가장 높은 등급에서 실행됩니다. 레지스트리 데이터가 전혀 없는 국가는 레지스트리 확인 대상으로 제공되지 않으며, 이 경우 수동 기업 정보 입력을 계속 진행하세요. 구매할 등급으로 검색한 다음, 그 후보를 판매하는 endpoint에서 가져오세요.

search_type

search_type은 contains만 허용하며, 이것이 기본값입니다. 검색의 기반이 되는 레지스트리 소스는 회사명이 포함되는지를 기준으로 일치시키므로, start_with와 fuzzy는 400("start_with" is not a valid choice)으로 거부되며 contains로 조용히 처리되지 않습니다. 정확한 회사 일치를 원하면 registration_number를 보내세요.

호스티드 검색과 독립형 검색

POST /v1/kyb/search/는 호스티드 인증 흐름이 실행하는 검색입니다. 인증 세션으로 인증되며, API 키에는 403으로 응답하고, tier를 받지 않습니다. 워크플로의 KYB 레지스트리 설정이 체인을 선택합니다. 독립형 API는 x-api-key와 함께 POST /v2/kyb/search/ 또는 POST /v3/kyb/search/를 호출합니다. tier 입력과 등급별 select endpoint는 독립형 연동이 같은 후보에 필요한 등급으로 접근하는 방법입니다.

레지스트리 중단 처리

레지스트리 제공업체를 일시적으로 사용할 수 없으면, endpoint는 안정적인 기계 판독용 코드와 함께 502를 반환합니다:
이 코드를 받으면 사용자가 수동 기업 정보 입력을 계속하도록 하거나, 나중에 다시 시도하도록 안내하세요. 검증 오류는 별도로 처리하세요. 잘못된 검색 입력은 400을 반환하며, 이 중단 코드를 사용하지 않습니다.

지원되지 않는 국가 및 검색 한도 처리

재시도를 중단하고 수동 기업 정보 입력을 계속하라는 안정적인 코드가 두 가지 더 있습니다: 호스티드 흐름에서는 레지스트리 단계마다 유료 기업 데이터 소스에 대해 3회까지 검색할 수 있습니다. 세 번째 검색 이후에는 신청자에게 수동 입력이 제공됩니다. 검색 결과 선택한 후보가 회사가 아니라 상표 등록인 경우, 400과 code: "kyb_registry_entry_not_a_company"가 반환됩니다. 이때는 검색 결과에서 회사를 선택하세요.

인증

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

본문

application/json
country_code
string
필수

검색할 법인 등기부가 있는 국가의 ISO 3166-1 alpha-2 코드입니다. 예를 들어 GB입니다. 법인 등기부가 주 또는 도 단위로 운영되는 경우 XX-YY 형식으로 ISO 3166-2 행정 구역 코드를 추가합니다. US-CA는 캘리포니아 등기부를 검색합니다. 미국 검색 시에는 항상 행정 구역이 필요하며 단순 US는 거부됩니다. 대소문자를 구분하지 않으며 대문자로 정규화됩니다.

Maximum string length: 10
예시:

"GB"

name
string

검색할 기업명입니다. name 또는 registration_number 중 하나는 필수입니다.

Maximum string length: 255
예시:

"Tesco"

registration_number
string

검색할 법인 등기부 등록번호입니다. name 또는 registration_number 중 하나가 필요합니다.

Maximum string length: 100
tier
enum<string>
기본값:basic

이 검색이 실행되는 제공업체 체인의 법인 등기부 등급입니다. basic(기본값)은 해당 국가의 Lite 체인을 검색합니다. shareholders 및 ubo는 해당 등급의 소유 구조 체인을 검색하며 다른 출처일 수 있으므로, Lite 검색 결과가 비어 있다고 해서 법인 등기부에 해당 기업이 없다는 것을 증명하지는 않습니다. 지정된 등급을 제공하지 않는 국가는 해당 등급 이하에서 제공하는 가장 높은 등급으로 검색됩니다. 검색한 등급을 판매하는 endpoint에서 후보를 검색하십시오: POST /v3/kyb/select/(Lite), POST /v3/kyb/shareholders/ 또는 POST /v3/kyb/ubo/.

사용 가능한 옵션:
basic,
shareholders,
ubo
예시:

"basic"

search_type
enum<string>
기본값:contains

등기부 검색에 적용되는 이름 일치 전략입니다. 허용되는 유일한 값은 contains입니다. 검색 대상인 등기부 소스 중 접두사 또는 퍼지 모드를 지원하는 소스가 없으므로 start_with 및 fuzzy는 400(not a valid choice) 오류로 거부됩니다.

사용 가능한 옵션:
contains
vendor_data
string

해당 조회에 대한 귀하의 식별자입니다. webhook 콜백에 포함되며 그대로 다시 반환됩니다.

metadata
object | null

자유 형식 JSON입니다. 그대로 반환되며 webhook 콜백에 포함됩니다.

webhook_url
string<uri>

검색을 비동기 모드로 전환합니다. API가 즉시 반환되며, 후보 목록이 준비되면 이 URL로 서명되지 않은 kyb.registry_search.resolved 콜백을 POST합니다.

Maximum string length: 500

응답

검색이 접수되었습니다. 동기 모드는 확인된 후보 목록을 반환하며, webhook 모드는 즉시 반환(주로 search_status: "pending")하고 kyb.registry_search.resolved 콜백을 통해 최종 목록을 전송합니다.

request_id
string<uuid>

webhook_url이 있는 경우: 영구 저장된 검색 요청 ID로, kyb.registry_search.resolved 콜백에서 request_id로 반환됩니다. webhook_url이 없는 경우: 일회성 상관관계 UUID입니다(검색이 저장되지 않음).

kyb_registry
object
vendor_data
string | null

전송한 vendor_data의 에코 값입니다.

metadata
object | null

전송한 metadata의 에코 값입니다.

created_at
string<date-time>
마지막 수정일 2026년 11월 7일