> ## 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

> How-to task page: query a user's latest status by user ID (or by the idempotency key you used when creating them). Organized as task steps plus a minimum request/response and who does what, with the field table and the common response envelope filled in from the source, and a next-step call to action at the end.

## 📄 Guide

Whether you are an exchange, a wallet or a platform, you can look up a user's latest details at any time after creating them: the user ID, the current status and the creation and update timestamps. That lets you reconcile the user record in your own system and decide whether they can move on to card issuance.

The query is initiated by **the partner**, and **DCS** returns the user's current snapshot.

### Prerequisites

* You hold the Enterprise `ApiKey` / `SecretKey`. If you have not received them yet, see [First steps](../../getting-started/first-steps).
* You have already created the user. If not, complete [Create a user](./create-customer) first.

### Steps

1. Prepare the user identifier: either the `customerId` returned when the user was created, or the idempotency key `customerRef` you supplied at creation (you).
2. Build the request headers as described in [Authentication](../../integration-resources/authentication) and call the query endpoint (you → DCS).
3. Read the user's `status` and the timestamp fields from the response `data`, and reconcile them in your own system (you).

### Query user details

**`GET /open-api/customer/v1/detail`**

#### Query parameters

| Parameter     | In    | Type   | Required | Description                                                              |
| ------------- | ----- | ------ | -------- | ------------------------------------------------------------------------ |
| `customerId`  | query | string | No       | User ID (returned by DCS when the user was created)                      |
| `customerRef` | query | string | No       | Your idempotency key for the user (set by you when the user was created) |

<Note>
  at least one of `customerId` and `customerRef` must be supplied; with neither present the user cannot be located.
</Note>

#### Request example

```
GET /open-api/customer/v1/detail?customerId=100000000123
Host: <api-base>
Content-Type: application/json
X-DAPI-API-KEY: <your-api-key>
X-DAPI-TIMESTAMP: 1743044911331
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`), see [Authentication](../../integration-resources/authentication).

#### Response example

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "customerId": "100000000123",
    "status": "SUCCEED",
    "createTime": "2025-01-01T12:00:00+08:00",
    "modifyTime": "2025-01-02T09:30:00+08:00"
  }
}
```

#### `data` fields

| Field        | Type   | Description                                                                                                                                                        |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `customerId` | string | User ID                                                                                                                                                            |
| `status`     | string | User status, sample value `SUCCEED` (spelled as the source endpoint returns it; standardising on `SUCCESS`/`SUCCEEDED` is under consideration, see the note below) |
| `createTime` | string | Creation time in the format `yyyy-MM-dd'T'HH:mm:ss+08:00`                                                                                                          |
| `modifyTime` | string | Time of the last update in the format `yyyy-MM-dd'T'HH:mm:ss+08:00`                                                                                                |

> **About the `status` value**: the sample value `SUCCEED` means the user is ready and can move on to the next stage. Documentation of the full set of status values is planned; until then, match on the values you actually receive.

### Common response envelope

Every `/open-api/` endpoint returns the same envelope, with this endpoint's payload in `data`:

| Field           | Type           | Description                                                                                                                        |
| --------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `code`          | string         | System-level return code; `SYS_SUCCESS` on success                                                                                 |
| `message`       | string         | Return message (such as `success`)                                                                                                 |
| `messageDetail` | object \| null | Copy meant for display to the end user (`title`/`message`/`type`/`icon`/`action`/`linkTitle`/`linkUrl`); usually `null` on success |
| `data`          | object         | Business payload, see the field table above                                                                                        |

<Note>
  "success" on this endpoint is signalled by the system-level `code` (`SYS_SUCCESS`), while the business outcome is carried by `data.status`. Use `code` to decide whether the call itself succeeded and the fields inside `data` to decide the user's business status; `messageDetail` is returned only when there is something to show the end user, and is usually `null` on success.
</Note>

For how error codes are grouped, whether they are retryable and how to handle them, see [Error codes](../transactions/decline-codes).

## Next steps

Once you have confirmed that the user's status is healthy, you can [apply for KYC](../kyc/apply-kyc) for them, or go straight to [card issuance](../cards/card-issuing).