> ## 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 a user's KYC information

> How-to task page: query the KYC summary per user (GET /open-api/kyc/v1/detail). Focuses on how it differs from querying a KYC ticket (both are called "querying KYC" and are easily confused), and routes kycRenewalRequired=true to the renewal page.

## 📄 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](./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

```json theme={null}
{
  "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](../../integration-resources/authentication) 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](../webhooks/events-and-schema#kyc) 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](./kyc-renewal). Once it passes, DCS pushes `kycRenewalRequired=false` and the restriction is lifted.

## Prerequisites

* You hold the Enterprise ApiKey / SecretKey — see [First steps](../../getting-started/first-steps).
* You have created the user and hold their `customerId` — see [Create a user](../users/create-customer).

## Next steps

* The user needs to renew → [Updating KYC information](./kyc-renewal)
* Check the progress of one verification → [Query KYC](./query-kyc)
* Reuse KYC the user already completed under the DeCard-Managed model → [KYC information migration](./kyc-migration)