KYC Sharing

API Description

Share Exchange Link User KYC Info API.

Note: For KZ Entity Brokers (Partial Sharing mode, enabled for brokers whose bizEntityKey is configured as a partial-sharing broker on the Binance side), each data section is optional and can be submitted independently. For Standard Brokers, basicInfo and identityInfo are both mandatory. For KZ Entity brokers, at least one of basicInfo / identityInfo / tncInfo / questionnaireInfo must be non-null per request.

HTTP Request

POST /bapi/ekyc/v2/public/ekyc/customer/share-kyc-data

Request Header

Name	Type	Mandatory	Description
X-SHA2-Signature	STRING	YES	Request Signature

Request Parameters

Name	Type	Mandatory	Description
bizEntityKey	STRING	YES	business entity key, each access entity has its own bizEntityKey
requestNo	STRING	YES	every request unique number, max length is 120
kycInfo	STRING	YES	KycInfo

KycInfo

Name	Type	Mandatory	Description
userInfo	UserInfo	YES	user account linking info
basicInfo	BasicInfo	Conditional	required for standard brokers; optional for KZ Entity brokers
identityInfo	IdentityInfo	Conditional	required for standard brokers; optional for KZ Entity brokers
tncInfo	TncInfo	NO	KZ Entity brokers only. T&C acceptance info
questionnaireInfo	QuestionnaireInfo	NO	KZ Entity brokers only. Questionnaire answers

UserInfo

Name	Type	Mandatory	Description
bizEntityKey	STRING	YES	business entity key, each access entity has its own bizEntityKey
entityCustomerId	STRING	YES	customer id，that is, the user id of the access entity site, max length is 128
brokerMainAccountId	STRING	YES	broker main account id
brokerSubAccountId	STRING	YES	broker sub account id
notifyUrl	STRING	YES	notify url when kyc status changed
extra	STRING	NO	extra info in JSON format

BasicInfo

Name	Type	Mandatory	Description
firstName	STRING	YES
middleName	STRING	NO
lastName	STRING	YES
residentialCountry	STRING	YES	country of residence: 2-alpha code in UPPER CASE
dob	STRING	YES	yyyy-MM-dd
country	STRING	YES	nationality, 2-alpha code in UPPER CASE
userSubmitIp	STRING	YES
address	STRING	YES	max is 400
city	STRING	YES	max is 100
postalCode	STRING	NO	max is 50

IdentityInfo

Name	Type	Mandatory	Description
documentType	STRING	YES	document type, for example: ID_CARD, PASSPORT, DRIVING_LICENSE,RESIDENCE_PERMIT
selectCountry	STRING	Yes	user selected country when do Id verification 2-alpha code in UPPER CASE
frontFileUrl	STRING	YES	id front image download url
backFileUrl	STRING	NO	id back image download url
faceFileUrl	STRING	YES	face image download url
firstName	STRING	YES	please ensure this matches the “firstName” under Basic Info table above, if not it will be rejected.
middleName	STRING	NO
lastName	STRING	YES	please ensure this matches the “lastName” under Basic Info table above, if not it will be rejected.
dob	STRING	YES	date of birth: yyyy-MM-dd
idType	STRING	YES	id doc type. for example: ID_CARD, PASSPORT, DRIVING_LICENSE,RESIDENCE_PERMIT
idSubType	STRING	NO	id doc sub type
idCountry	STRING	YES	2-alpha code in UPPER CASE
nationalityCountry	STRING	YES	2-alpha code in UPPER CASE
idNumber	STRING	YES	id Number
idExpiry	STRING	NO	yyyy-MM-dd
userSubmitIp	STRING	YES
idUsState	STRING	NO
personalNumber	STRING	NO
gender	STRING	NO
issuingAuthority	STRING	NO
issuingDate	STRING	NO	yyyy-MM-dd
issuingPlace	STRING	NO
registrationNumber	STRING	NO
city	STRING	NO
stateCode	STRING	NO
postalCode	STRING	NO
address	STRING	NO

TncInfo

T&C (Terms & Conditions) acceptance info submitted by KZ Entity brokers. Applicable only when bizEntityKey is configured as a partial sharing broker. This section is optional — omit it if no TNC data needs to be submitted in this request.

Name	Type	Mandatory	Description
userSubmitIp	STRING	YES	IP address of the user at the time of TNC submission
tncVersion	STRING	YES	Version of the T&C document the user consented to. Format: a.b (e.g., "1.0"). Must match regex ^\d+\.\d+$
consent	BOOLEAN	YES	Whether the user explicitly consented to the T&C. Must not be null
signTime	STRING	YES	Timestamp of the user's TNC consent action. ISO-8601 format (e.g., "2024-01-01T12:00:00Z")

QuestionnaireInfo

Questionnaire answers submitted by KZ Entity brokers. The submitted answers are validated against the questionnaire template registered for the provided version. All questions defined for that version must be answered.

Name	Type	Mandatory	Description
version	STRING	YES	Questionnaire version identifier, e.g. "KZ_V6". Must correspond to a configured questionnaire version supported by the KYC SaaS service
answers	List<QuestionnaireAnswer>	YES	List of question-answer pairs. Must not be empty. All questions in the version must be answered

QuestionnaireAnswer

Name	Type	Mandatory	Description
title	STRING	YES	Question title key. Must match one of the configured question titles for the given questionnaire version
option	STRING	YES	Selected option key (single choice). Must be a valid option from the configured option list for the given questionnaire version

Request Body Example

{
  "bizEntityKey": "BROKERKEY",
  "kycInfo": {
    "userInfo": {
      "brokerMainAccountId": "1234567",
      "brokerSubAccountId": "12345678123456767",
      "bizEntityKey": "BROKERKEY",
      "entityCustomerId": "12345678123456767",
      "extra": "extraTestData",
      "notifyUrl": "https://webhook.site/"
    },
    "identityInfo": {
      "lastName": "testLastNameLItest01",
      "frontFileUrl": "https://image.cnbcfm.com/api/v1/image/104853635-GettyImages-870113330.jpg?v=1709055832&w=740&h=416&ffmt=webp&vtcrop=y",
      "gender": "M",
      "documentType": "ID_CARD",
      "idUsState": "testIdUsState",
      "issuingDate": "2010-09-19",
      "city": "testCity",
      "postalCode": "123456",
      "selectCountry": "SG",
      "idNumber": "testSaasBrokers0144288491",
      "userSubmitIp": "192.168.1.1",
      "issuingPlace": "AE",
      "backFileUrl": "https://cdn.shortpixel.ai/spai/q_lossless+w_1776+to_webp+ret_img/independent-photo.com/wp-content/uploads/2022/03/Karen-Pape-1800x1200.jpeg",
      "idSubType": "INTERNATIONAL_PASSPORT",
      "idType": "ID_CARD",
      "address": "testAddressData",
      "personalNumber": "personalNumber6462313972",
      "idCountry": "AE",
      "firstName": "testFirstName",
      "issuingAuthority": "firstName",
      "faceFileUrl": "https://cdn.shortpixel.ai/spai/q_lossless+w_1776+to_webp+ret_img/independent-photo.com/wp-content/uploads/2022/03/Karen-Pape-1800x1200.jpeg",
      "dob": "1999-09-19",
      "idExpiry": "2030-09-19",
      "registrationNumber": "registrationNumber4039460415",
      "middleName": "testMiddleNameboli",
      "stateCode": "QWER",
      "nationalityCountry": "AE"
    },
    "basicInfo": {
      "firstName": "AA",
      "lastName": "BB",
      "country": "AE",
      "residentialCountry": "AE",
      "dob": "1999-09-19",
      "middleName": "testMiddleName",
      "userSubmitIp": "192.168.1.1",
      "address": "aaa",
      "city": "bbb",
      "postalCode": "123456"

    }
  },
  "requestNo": "23454312345365012111113"
}

KZ Entity Broker — Partial Sharing with TncInfo & QuestionnaireInfo

{
  "bizEntityKey": "KZ_ENTITY_BROKER",
  "requestNo": "REQ_20240501_KZ_001",
  "kycInfo": {
    "userInfo": {
      "bizEntityKey": "KZ_ENTITY_BROKER",
      "entityCustomerId": "CUST_KZ_001",
      "brokerMainAccountId": "MAIN_ACC_001",
      "brokerSubAccountId": "SUB_ACC_001",
      "notifyUrl": "https://broker.example.com/kyc/notify"
    },
    "tncInfo": {
      "userSubmitIp": "192.168.1.1",
      "tncVersion": "1.0",
      "consent": true,
      "signTime": "2024-05-01T08:30:00Z"
    },
    "questionnaireInfo": {
      "version": "KZ_V6",
      "answers": [
        { "title": "KZ_V6_useFor", "option": "KZ_V6_useFor_investmentTrading" },
        { "title": "KZ_V6_sourceOfFunds", "option": "KZ_V6_sourceOfFunds_salary" }
      ]
    }
  }
}

Response Example

{
    "code": "000000",
    "message": null,
    "messageDetail": null,
    "data": null,
    "success": true
}