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

# List users

> List all end-users registered under your partner API key, with filters and pagination.

<Note>
  Requires `X-Api-Key` and `X-Api-Secret` headers. See [Authentication](/api-reference/users/introduction#authentication) for details.
</Note>

Only returns users created by your API key — you never see users from other partners.

To iterate all pages, increment `offset` by `limit` until `hasMore` is `false`:

```
offset=0,  limit=20 → hasMore: true  → continue
offset=20, limit=20 → hasMore: true  → continue
offset=40, limit=20 → hasMore: false → done
```


## OpenAPI

````yaml api-reference/openapi.json GET /api/v1/partner/users
openapi: 3.1.0
info:
  title: QASH API
  description: >-
    QASH endpoints for exchange rates, cards, and partner-facing financial
    workflows.
  version: 1.0.0
servers:
  - url: https://api.qash.ai
    description: Partner API (Production)
  - url: https://staging.qash.ai
    description: Staging
  - url: https://app.qash.ai
    description: Production
security: []
tags:
  - name: Exchange rates
    description: Public endpoints for supported assets and TRM-based quotes.
  - name: Cards
    description: >-
      Authenticated partner endpoints for card state, controls, limits, and
      balances.
  - name: Users
    description: Admin endpoints for user provisioning and account management.
paths:
  /api/v1/partner/users:
    get:
      tags:
        - Users
      summary: List users
      description: >-
        Returns all end-users registered under your partner API key. Supports
        filtering by status and offset-based pagination.
      operationId: partnerListUsers
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by user status.
          schema:
            type: string
            enum:
              - pending
              - active
              - suspended
              - banned
              - kyc_required
        - name: limit
          in: query
          required: false
          description: 'Number of records per page. Default: `20`. Max: `200`.'
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - name: offset
          in: query
          required: false
          description: 'Number of records to skip. Default: `0`.'
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Users returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerListUsersResponse'
              examples:
                default:
                  summary: Single active user
                  value:
                    success: true
                    data:
                      users:
                        - id: 550e8400-e29b-41d4-a716-446655440000
                          email: user@example.com
                          status: active
                          countryCode: CO
                          createdAt: '2026-05-27T10:00:00.000Z'
                      pagination:
                        total: 1
                        limit: 100
                        offset: 0
                        hasMore: false
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                default:
                  value:
                    success: false
                    error: Number must be greater than or equal to 1
        '401':
          description: Invalid partner credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                default:
                  value:
                    success: false
                    error: Invalid partner credentials
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                default:
                  value:
                    success: false
                    error: Failed to retrieve users
      security:
        - partnerApiKey: []
          partnerApiSecret: []
components:
  schemas:
    PartnerListUsersResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            users:
              type: array
              items:
                $ref: '#/components/schemas/PartnerUserListItem'
            pagination:
              $ref: '#/components/schemas/PartnerPagination'
          required:
            - users
            - pagination
      required:
        - success
        - data
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Human-readable error message.
          example: Email is required
      required:
        - success
        - error
    PartnerUserListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        status:
          $ref: '#/components/schemas/UserStatus'
        countryCode:
          type: string
          example: CO
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - email
        - status
        - countryCode
        - createdAt
    PartnerPagination:
      type: object
      properties:
        total:
          type: integer
          description: Number of users in this page.
        limit:
          type: integer
          description: Applied limit.
        offset:
          type: integer
          description: Applied offset.
        hasMore:
          type: boolean
          description: '`true` if more results exist beyond the current offset.'
      required:
        - total
        - limit
        - offset
        - hasMore
    UserStatus:
      type: string
      enum:
        - pending
        - active
        - suspended
        - banned
      description: Current lifecycle status of the user.
  securitySchemes:
    partnerApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Partner API key. Generated from Qash Dashboard → Settings → API Keys.
    partnerApiSecret:
      type: apiKey
      in: header
      name: X-Api-Secret
      description: Partner API secret. Shown once at creation — store it securely.

````