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

# Get KYC Status

> Get KYC verification status

# Get KYC Status

Returns the current KYC verification status for a user.

## Request

```bash theme={null}
curl https://api.stablepay.global/v2/users/usr_abc123/kyc/status \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "level": "basic",
    "status": "verified",
    "digilocker": {
      "verified": true,
      "status": "completed",
      "completedAt": "2025-06-15T10:00:00Z"
    },
    "aadhaar": {
      "verified": true,
      "maskedNumber": "XXXXXXXX1234",
      "nameOnAadhaar": "RAHUL KUMAR",
      "verifiedAt": "2025-06-15T10:00:00Z"
    },
    "pan": {
      "verified": true,
      "maskedNumber": "XXXXX1234X",
      "nameOnPan": "RAHUL KUMAR",
      "nameMatchScore": 95,
      "verifiedAt": "2025-06-15T10:05:00Z"
    },
    "passport": {
      "verified": false
    },
    "attestation": {
      "verified": true,
      "docType": "driving_license",
      "country": "USA",
      "issuingCountry": "USA",
      "legalName": "John Doe",
      "verifiedAt": "2025-06-15T10:00:00Z"
    },
    "face": {
      "verified": false
    },
    "upi": {
      "verified": false
    },
    "bank": {
      "verified": true,
      "maskedAccountNumber": "XXXXXX7890",
      "bankName": "HDFC Bank",
      "ifsc": "HDFC0001234",
      "verifiedAt": "2025-06-15T10:10:00Z"
    }
  }
}
```

Any method the user has not completed is returned as `{ "verified": false }` with no other fields.

<Warning>
  Fields with no value are **omitted**, not returned as `null`. In particular, before DigiLocker completes, the `digilocker` block is just `{ "status": "pending" }` — with **no `verified` key at all**. Treat a missing `verified` as `false`.
</Warning>

<Note>
  The declaration is **not** part of this response — it's submitted via [Submit Declaration](/api-reference/kyc/submit-declaration).
</Note>

<Warning>
  Submitting the declaration does **not** immediately recompute the aggregate `status` — it can remain `in_progress` even once every requirement is met. Call `POST /kyc/refresh` (below) after the final step to settle the status.
</Warning>

## Status Values

| Status        | Description                                   |
| ------------- | --------------------------------------------- |
| `pending`     | No verifications started                      |
| `in_progress` | Some steps complete, not all requirements met |
| `verified`    | All requirements met — user can transact      |
| `rejected`    | KYC rejected                                  |

`level` is `none`, `basic`, or `enhanced`. It becomes `basic` when `status` is `verified`.

## Refresh KYC Status

```
POST /v2/users/{userId}/kyc/refresh
```

Recomputes the aggregate status from the underlying verifications. Use this if a status looks stale after a verification completed.

```json theme={null}
{
  "success": true,
  "data": {
    "previous": { "level": "none", "status": "in_progress" },
    "current": { "level": "basic", "status": "verified" }
  }
}
```