> For the complete documentation index, see [llms.txt](https://docs.musepay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.musepay.io/reference/api-reference/kyc-api/query.md).

# Query KYC Status

{% hint style="warning" %}
Every request must include the [common parameters](/reference/api-reference/common-parameters.md). The example below shows business fields only.
{% endhint %}

<mark style="color:green;">`POST`</mark> `/v1/kyc/query`

Reads the user's most recent verification application and the level they have already obtained. No fee. Call [Create Applicant](/reference/api-reference/kyc-api/create-applicant.md) first if the user does not exist yet.

## Request Body

| Name        | Type   | Required | Description                                                                                       |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| request\_id | String | Yes      | Identifier for this query. Use a new value each time; it does not need to match the link request. |
| user\_xid   | String | Yes      | User identifier under your merchant account.                                                      |

## Request Example

```json
{
  "request_id": "kyc-query-202610150001",
  "user_xid": "customer-0001"
}
```

## Response Body

The following fields are returned in `data`. Levels and statuses are strings, not JSON numbers.

| Name                     | Type            | Description                                                                                                               |
| ------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| request\_id              | String          | Identifier for this query.                                                                                                |
| user\_xid                | String          | Merchant-side user identifier.                                                                                            |
| user\_id                 | String          | MusePay user ID.                                                                                                          |
| level\_name              | String          | Level of the most recent application (`L1`, `L2`, `L1_AML`, `L2_AML`); `null` if never applied.                           |
| kyc\_status              | String          | Status of the most recent application; see the table below.                                                               |
| kyc\_level               | String          | Highest level obtained through this product: `0` none, `1` level 1, `2` level 2.                                          |
| application\_request\_id | String          | The link `request_id` behind the most recent application; `null` if never applied. Matches `data.requestId` in callbacks. |
| moderation\_comment      | String          | Review comment, present when `kyc_status` is `REJECTED`.                                                                  |
| reject\_labels           | Array of String | Rejection labels, present when `kyc_status` is `REJECTED`.                                                                |
| review\_reject\_type     | String          | `FINAL` for a final rejection, present when `kyc_status` is `REJECTED`.                                                   |

### `kyc_status`

| Value         | Means                                                                          | Fee       |
| ------------- | ------------------------------------------------------------------------------ | --------- |
| `NOT_STARTED` | No application has been made.                                                  | None.     |
| `PROCESSING`  | Waiting for the user to submit, under review, or waiting for more information. | Reserved. |
| `APPROVED`    | Latest application approved.                                                   | Settled.  |
| `REJECTED`    | Latest application finally rejected.                                           | Settled.  |
| `EXPIRED`     | The fee order closed after roughly 24 hours; the review may still be running.  | Released. |

```json
{
  "code": "200",
  "message": "success",
  "data": {
    "request_id": "kyc-query-202610150001",
    "user_xid": "customer-0001",
    "user_id": "1000001",
    "level_name": "L1",
    "kyc_status": "APPROVED",
    "kyc_level": "1",
    "application_request_id": "kyc-link-202610150001"
  }
}
```

## Reading the response

* `level_name` and `kyc_status` describe the **most recent** application; `kyc_level` describes what the user **already holds**. A user at level 1 with an `L2_AML` application running returns `level_name=L2_AML`, `kyc_status=PROCESSING`, `kyc_level=1`.
* `kyc_level` rises only on approval. Applying, being rejected, or expiring leaves it unchanged, and it is independent of levels in other MusePay products such as card issuing.
* This endpoint returns the latest application per user. To reconcile a specific one, match `data.requestId` from the [KYC webhook](/integration/webhook/kyc.md) against `application_request_id`. For fee order details, call [Query Order](/reference/api-reference/acquiring-api/query-order.md) (`POST /v1/order/query`) with the `fee_order_no` from the link response.