Query KYC - DCS Technical Documentation

📄 Guide

Whether you are an exchange, a wallet or a platform, you can check the progress of a KYC application at any time after submitting it — its current status, whether the user still needs to be guided through face verification, and the exact reason if it was rejected — so that you can track each user’s card eligibility in your own system in real time. As a licensed card issuer, DCS has KYC outcomes reviewed jointly by its compliance team and external vendors. You initiate the query; DCS returns the current snapshot of that KYC ticket.

This page queries the progress of one particular verification (a ticket). If you want the current KYC summary for a user — including whether their data has expired and needs redoing — that is a different endpoint: see Query a user’s KYC information. Both are called “querying KYC” and are easily confused.

Prerequisites

You hold the Enterprise ApiKey / SecretKey. If you have not received them yet, see First steps.
You have already submitted a KYC application. If not, complete Apply for KYC first.

Steps

Have the ticket identifier ready: either the kycTicketId returned when you applied for KYC, or the idempotency key kycTicketRef you supplied at that time (your side).
Build the request headers as described in Authentication and call the query endpoint (you → DCS).
Read the current status from data.status in the response and act on it as follows (your side):
- NEED_VERIFY: guide the user through face verification, see H5 KYC guide page;
- PASSED: you can move on to card issuance;
- REJECTED: read errorCode / errorMessage to determine the reason and, where appropriate, guide the user to resubmit.

Query KYC details

GET /open-api/kyc-ticket/v1/detail

Query parameters

Parameter	In	Type	Required	Description
`kycTicketId`	query	string	No	KYC ticket ID (returned by DCS when you applied for KYC)
`kycTicketRef`	query	string	No	KYC ticket idempotency field (chosen by you when applying)
`salt`	query	string	No	In API mode, a verification salt passed straight through to the risk center; you agree its value with the risk side, and DCS itself neither encrypts nor decrypts it. It can be ignored in H5 mode. Maximum length 64; if omitted, an empty string is passed through

Supply at least one of kycTicketId and kycTicketRef to locate the ticket; kycTicketId is preferred.

Request example

GET /open-api/kyc-ticket/v1/detail?kycTicketId=200000000456
Host: <api-base>
Content-Type: application/json
X-DAPI-API-KEY: <your-api-key>
X-DAPI-TIMESTAMP: <timestamp-ms>
X-DAPI-NONCE: 12345
X-DAPI-SIGN: <signature>

For how to build the full set of authentication headers (X-DAPI-API-KEY / X-DAPI-TIMESTAMP / X-DAPI-NONCE / X-DAPI-SIGN, together with Content-Type: application/json), see Authentication.

Response example

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "kycTicketId": "200000000456",
    "kycTicketRef": "your-kyc-ref-001",
    "customerId": "100000000123",
    "status": "PASSED",
    "createTime": "2025-01-01T12:00:00+08:00",
    "modifyTime": "2025-01-02T09:30:00+08:00",
    "digest": "****1234",
    "kycRenewalRequired": false,
    "kycApplyMode": "H5"
  }
}

When the ticket is rejected, data additionally carries errorCode / errorMessage:

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "kycTicketId": "200000000456",
    "status": "REJECTED",
    "errorCode": "INVALID_POA",
    "errorMessage": "Invalid proof of address"
  }
}

The errorCode above is illustrative; for the full set of values and their meanings see KYC reject codes.

`data` fields

Field	Type	Description
`kycTicketId`	string	KYC ticket ID
`kycTicketRef`	string	KYC ticket idempotency field
`customerId`	string	User ID
`status`	string	KYC ticket status; see the status machine table below for the values
`createTime`	string	Creation time, format `yyyy-MM-dd'T'HH:mm:ss+08:00`
`modifyTime`	string	Last update time, format `yyyy-MM-dd'T'HH:mm:ss+08:00`
`digest`	string	Encrypted (masked) document number
`kycRenewalRequired`	boolean	Whether a KYC renewal is required
`kycApplyMode`	string	Application mode: `API` (submitted via API) / `H5` (KYC applied for on the H5 page) / `H5-RENEWAL` (updating KYC information) / `H5-MIGRATION` (KYC information migration)
`errorCode`	string	Rejection reason code, returned only when the status is `REJECTED`
`errorMessage`	string	Rejection reason description, returned only when the status is `REJECTED`

KYC ticket status machine

Status	Meaning	Terminal	Your next step
`INIT`	KYC information submitted	No	Wait for the system to process it
`NEED_VERIFY`	Waiting for face verification	No	Guide the user through face verification, see H5 KYC guide page
`PENDING`	Under review	No	Wait for the review to finish
`PASSED`	Approved	Yes	You can proceed to the next step, such as issuing a card
`REJECTED`	Rejected	Yes	Read `errorCode` / `errorMessage` and, where appropriate, submit a new KYC application

About rejection reasons: when the status is REJECTED, the response data carries errorCode and errorMessage; the same information is also pushed through the KYC_TICKET webhook. For the full classification of the codes (bucket / retryable / what the user should do / whether a resubmission is possible) see KYC reject codes.

Common response envelope

Every /open-api/ endpoint returns the same envelope, with this endpoint’s business data in data:

Field	Type	Description
`code`	string	System-level return code; `SYS_SUCCESS` on success
`message`	string \| null	Usually `null` on success (some endpoints return a `success` string); rely on `code` to judge the outcome. Carries the corresponding error message on failure
`messageDetail`	object \| null	Information to display to the end user (`title`/`message`/`type`/`icon`/`action`/`linkTitle`/`linkUrl`); usually `null` on success
`data`	object	Business data, see the field table above

Please note: this endpoint carries two layers of meaning, so evaluate them separately. Use the system-level code to tell whether the request was accepted, and data.status to tell the KYC business outcome. code=SYS_SUCCESS only means “the request was accepted and a ticket snapshot was returned”; it does not mean KYC has passed (for example, code is still SYS_SUCCESS when status=REJECTED). On failure, messageDetail is what you show the end user.

For how the codes are classified, whether they are retryable and how to handle each of them, see KYC reject codes.

Next steps

Once the KYC status is PASSED you can apply for a virtual card / issue a card for the user; if the status is NEED_VERIFY, first use the H5 KYC guide page to walk the user through verification.

​📄 Guide

​Prerequisites

​Steps

​Query KYC details

​Query parameters

​Request example

​Response example

​data fields

​KYC ticket status machine

​Common response envelope

​Next steps