> ## Documentation Index > Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt > Use this file to discover all available pages before exploring further. # Query KYC > How-to task page: use the KYC ticket ID (or the idempotency key you supplied when applying) to retrieve the latest status and outcome of a KYC verification. Organized as task steps plus a minimal request/response and a who-does-what note; the status machine table and the rejection reasons follow the source, the common response envelope is explained as in the source, and the page ends with a next-steps CTA. ## 📄 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](./kyc-info). 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](../../getting-started/first-steps). * You have already submitted a KYC application. If not, complete [Apply for KYC](./apply-kyc) first. ### Steps 1. 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). 2. Build the request headers as described in [Authentication](../../integration-resources/authentication) and call the query endpoint (you → DCS). 3. 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](./h5-kyc-guidance); * `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: Content-Type: application/json X-DAPI-API-KEY: X-DAPI-TIMESTAMP: X-DAPI-NONCE: 12345 X-DAPI-SIGN: ``` > 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](../../integration-resources/authentication). #### Response example ```json theme={null} { "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`: ```json theme={null} { "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](./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](./kyc-renewal)) / `H5-MIGRATION` ([KYC information migration](./kyc-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](./h5-kyc-guidance) | | `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](../cards/card-issuing) | | `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](../webhooks/events-and-schema). For the full classification of the codes (bucket / retryable / what the user should do / whether a resubmission is possible) see [KYC reject codes](./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](./kyc-reject-codes). ## Next steps Once the KYC status is `PASSED` you can [apply for a virtual card / issue a card](../cards/card-issuing) for the user; if the status is `NEED_VERIFY`, first use the [H5 KYC guide page](./h5-kyc-guidance) to walk the user through verification.