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

# Retrieve a User's KYC Verification Status and Docs

> Fetch a user's KYC record: verification status, submitted ID number, and time-limited signed document URLs. Pass me as userId for your own record.

Retrieve the KYC record for a specific user. Pass `me` as the `userId` path parameter to fetch your own record without knowing your user ID. The response includes time-limited signed URLs for each uploaded document — do not store these URLs permanently; re-fetch the record to get fresh ones.

<Note>
  Document URLs (`idFrontUrl`, `idBackUrl`, `passportPhotoUrl`) expire after **15 minutes**. Regenerate them by calling this endpoint again.
</Note>

## Endpoint

```
GET https://api.nyotaimara.com/v1/kyc/:userId
```

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token issued after sign-in. Format: `Bearer <token>`.
</ParamField>

## Path parameters

<ParamField path="userId" type="string" required>
  The ID of the user whose KYC record to retrieve. Pass `me` to fetch your own record.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the record was found.
</ResponseField>

<ResponseField name="data" type="object">
  The KYC record.

  <Expandable title="properties">
    <ResponseField name="userId" type="string">
      The user's unique identifier.
    </ResponseField>

    <ResponseField name="userInfo" type="object">
      Basic profile information.

      <Expandable title="properties">
        <ResponseField name="email" type="string">
          The user's email address.
        </ResponseField>

        <ResponseField name="name" type="string">
          The user's full name.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="idNumber" type="string">
      The government-issued ID number submitted during KYC.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current verification status. One of: `none`, `pending`, `verified`, `rejected`.
    </ResponseField>

    <ResponseField name="documents" type="object">
      Pre-signed URLs for uploaded documents. Each URL expires after 15 minutes.

      <Expandable title="properties">
        <ResponseField name="idFrontUrl" type="string">
          Pre-signed URL for the front of the identity document.
        </ResponseField>

        <ResponseField name="idBackUrl" type="string">
          Pre-signed URL for the back of the identity document.
        </ResponseField>

        <ResponseField name="passportPhotoUrl" type="string">
          Pre-signed URL for the passport-style photo.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="verifiedAt" type="string | null">
      ISO 8601 timestamp when the record was verified, or `null` if not yet verified.
    </ResponseField>

    <ResponseField name="rejectionReason" type="string | null">
      Reviewer's rejection note, or `null` if not rejected.
    </ResponseField>

    <ResponseField name="submittedAt" type="string">
      ISO 8601 timestamp when the documents were first submitted.
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "success": true,
  "data": {
    "userId": "usr_01j9z...",
    "userInfo": {
      "email": "aisha@example.com",
      "name": "Aisha Kamau"
    },
    "idNumber": "12345678",
    "status": "pending",
    "documents": {
      "idFrontUrl": "https://storage.example.com/id-front?X-Amz-Expires=900&...",
      "idBackUrl": "https://storage.example.com/id-back?X-Amz-Expires=900&...",
      "passportPhotoUrl": "https://storage.example.com/passport?X-Amz-Expires=900&..."
    },
    "verifiedAt": null,
    "rejectionReason": null,
    "submittedAt": "2025-04-20T08:30:00.000Z"
  }
}
```

## Errors

| Status | Error message                           | Cause                                            |
| ------ | --------------------------------------- | ------------------------------------------------ |
| `404`  | `"KYC record not found for this user."` | No KYC submission exists for the given `userId`. |
| `500`  | `"Failed to retrieve KYC data"`         | Server-side database or storage error.           |

## Example

```bash theme={null}
# Fetch your own KYC record
curl https://api.nyotaimara.com/v1/kyc/me \
  -H "Authorization: Bearer <token>"

# Fetch another user's KYC record (requires admin permissions)
curl https://api.nyotaimara.com/v1/kyc/usr_01j9z... \
  -H "Authorization: Bearer <token>"
```