Query a user's KYC information - DCS Technical Documentation

📄 Guide

Besides checking the progress of one particular verification by ticket, you can also query the current KYC summary for a user: which country their proof of identity was issued in, and whether their KYC data has expired and needs renewing. This endpoint is how you make an eligibility decision before issuing a card, and how you discover in day-to-day operations that a user needs to renew.

How this differs from “Query KYC ticket”

Both endpoints are about “querying KYC” but they answer different questions, and they are easy to confuse:

	Query KYC ticket	Query a user’s KYC information (this page)
Endpoint	`GET /open-api/kyc-ticket/v1/detail`	`GET /open-api/kyc/v1/detail`
Input	`kycTicketId` or `kycTicketRef`	`customerId`
Question answered	How far has this verification got, and why was it rejected	The current KYC summary of this user, and whether the data has expired
Typical use	Polling for the result after submitting KYC	Eligibility checks before card issuance; spotting that a renewal is due

For ticket-level queries see Query KYC.

Endpoint

GET /open-api/kyc/v1/detail

Query parameters

Parameter	In	Type	Required	Description
`customerId`	query	string	Yes	User ID (returned when the user was created)

Request example

GET /open-api/kyc/v1/detail?customerId=1000000123

Response example

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "poiCountryCode": "SG",
    "kycRenewalRequired": false
  }
}

`data` fields

Field	Type	Description
`poiCountryCode`	string	Issuing country of the proof of identity (POI), 2-letter ISO, such as `CN` / `US` / `SG`
`kycRenewalRequired`	boolean	Whether this user’s KYC data needs renewing. `true` means the documents / KYC data have expired and the user must be guided through verification again

The common envelope is { code, message, messageDetail, data }; judge success by code == "SYS_SUCCESS". See the Authentication guide for the field semantics.

What to do when `kycRenewalRequired=true`

kycRenewalRequired set to true means the user’s documents / KYC data have expired and verification must be completed again. Until the renewal completes, some of the user’s operations (such as spending) may be restricted. There are two ways to learn about this, and they always agree:

Pull: call this endpoint and read kycRenewalRequired.
Push: DCS sends the user-level KYC webhook with kycRenewalRequired=true, and kycRenewalType tells you which factors need renewing (POI / SELFIE) so your front end can prompt for just that item.

For the full two-step flow that guides the user through the renewal, see Updating KYC information. Once it passes, DCS pushes kycRenewalRequired=false and the restriction is lifted.

Prerequisites

You hold the Enterprise ApiKey / SecretKey — see First steps.
You have created the user and hold their customerId — see Create a user.

Next steps

The user needs to renew → Updating KYC information
Check the progress of one verification → Query KYC
Reuse KYC the user already completed under the DeCard-Managed model → KYC information migration

​📄 Guide

​How this differs from “Query KYC ticket”

​Endpoint

​Query parameters

​Request example

​Response example

​data fields

​What to do when kycRenewalRequired=true

​Prerequisites

​Next steps