> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qash.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC status

> Get the KYC verification status for the authenticated user.

<Note>
  Requires `X-Api-Key` and `X-Api-Secret` headers. Pass `userId` as a query parameter — no JWT required. See [Authentication](/api-reference/users/introduction#authentication) for details.
</Note>

Returns the current KYC verification status for the given user. Use this endpoint to check whether a user has completed identity verification before proceeding to [login](/api-reference/users/send-otp) and financial operations.

## Request

```http theme={null}
GET /api/v1/user/kyc/status?userId=a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

### Query parameters

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `userId`  | string | Yes      | Qash user ID |

## Response

**200 OK** — always, even if the user has never started KYC. Check `data.kyc.hasKyc` and `data.kyc.status`.

```json theme={null}
{
  "success": true,
  "data": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userStatus": "active",
    "userType": "individual",
    "kyc": {
      "hasKyc": true,
      "hasActiveKyc": false,
      "isApproved": true,
      "isExpired": false,
      "status": "approved",
      "inquiryId": "inq_abc123xyz",
      "verificationLevel": "identity",
      "riskLevel": "low",
      "riskScore": 12,
      "submittedAt": "2026-06-10T14:00:00.000Z",
      "approvedAt": "2026-06-10T14:30:00.000Z",
      "expiresAt": null,
      "nextReviewDate": null,
      "canStartNewKyc": false
    },
    "permissions": {
      "canStartKyc": false,
      "canCreateAccounts": true,
      "requiresKyc": true,
      "maxTransactionAmount": 10000,
      "dailyTransactionLimit": 50000
    }
  }
}
```

| Field                     | Type           | Description                                                             |
| ------------------------- | -------------- | ----------------------------------------------------------------------- |
| `data.userStatus`         | string         | `"pending"`, `"kyc_required"`, `"active"`, `"suspended"`, or `"banned"` |
| `data.kyc.hasKyc`         | boolean        | `false` if the user has never started KYC                               |
| `data.kyc.isApproved`     | boolean        | `true` once identity verification has been approved                     |
| `data.kyc.status`         | string \| null | See status values below — `null` if `hasKyc` is `false`                 |
| `data.kyc.inquiryId`      | string \| null | Persona inquiry ID — use for support queries                            |
| `data.kyc.canStartNewKyc` | boolean        | Whether [Start KYC](/api-reference/users/start-kyc) can be called again |
| `data.permissions`        | object         | Derived operating limits based on KYC/user status                       |

### Status values (`data.kyc.status`)

| Status         | Description                                                                      | Approved? |
| -------------- | -------------------------------------------------------------------------------- | --------- |
| `created`      | Verification session created, not yet started                                    | No        |
| `pending`      | Awaiting submission                                                              | No        |
| `in_progress`  | Submitted, under automated review                                                | No        |
| `completed`    | Automated checks finished, pending decision                                      | No        |
| `needs_review` | Escalated for manual review                                                      | No        |
| `approved`     | Identity verified                                                                | Yes       |
| `declined`     | Rejected by reviewer                                                             | No        |
| `rejected`     | Rejected automatically                                                           | No        |
| `expired`      | Approval window elapsed — call [Start KYC](/api-reference/users/start-kyc) again | No        |
| `failed`       | Verification failed                                                              | No        |

## Errors

| HTTP status | Error                                            | Cause                                   |
| ----------- | ------------------------------------------------ | --------------------------------------- |
| `400`       | `Missing userId in request body or query params` | `userId` query param missing            |
| `401`       | `Invalid partner credentials`                    | Wrong `X-Api-Key` or `X-Api-Secret`     |
| `403`       | `User does not belong to this partner`           | `userId` belongs to a different partner |