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

# List cardholders

> Lists cardholders available to the authenticated partner.

Use `account_id` after an interrupted onboarding flow to find the
cardholder associated with an account.



## OpenAPI

````yaml https://core.sandbox.gnosispay.in/partner-api/openapi.json get /v1/cardholders
openapi: 3.1.0
info:
  title: Gnosis Pay Partner API
  version: 1.0.0
  description: >-
    Server-to-server API for onboarding users, creating accounts and cards,
    moving

    funds, and managing the card lifecycle. Call this API only from a trusted

    backend. Every request requires a partner access token, and every resource
    is

    scoped to the authenticated partner.
servers:
  - url: https://core.prod.gnosispay.com/partner-api
    description: Production
    variables: {}
  - url: https://core.sandbox.gnosispay.in/core
    description: Sandbox
    variables: {}
security:
  - BearerAuth: []
tags:
  - name: Accounts
  - name: Cards
  - name: Card transactions
  - name: KYC
  - name: Deposits
  - name: Withdrawals
  - name: PCI
  - name: 3DS
  - name: Webhooks
paths:
  /v1/cardholders:
    get:
      tags:
        - Cards
      summary: List cardholders
      description: |-
        Lists cardholders available to the authenticated partner.

        Use `account_id` after an interrupted onboarding flow to find the
        cardholder associated with an account.
      operationId: cardholders.list.v1
      parameters:
        - name: account_id
          in: query
          required: false
          description: Filter by account.
          schema:
            $ref: '#/components/schemas/uuid'
          explode: false
        - name: created_at_start
          in: query
          required: false
          description: Filter cardholders created on or after this date.
          schema:
            type: string
            format: date-time
          explode: false
        - name: created_at_end
          in: query
          required: false
          description: Filter cardholders created on or before this date.
          schema:
            type: string
            format: date-time
          explode: false
        - name: page_size
          in: query
          required: false
          description: The number of cardholders on each page (1-100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
          explode: false
        - name: page_cursor
          in: query
          required: false
          description: >-
            The cursor of the page to return. Its value comes from
            `pagination.next_page_cursor` in the previous response.
          schema:
            type: string
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Cardholder'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
                description: Paginated response containing data and pagination metadata
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    uuid:
      type: string
      format: uuid
    Cardholder:
      type: object
      required:
        - id
        - account_id
        - document_number
        - kyc_profile_id
        - phone
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: Unique identifier for the cardholder.
        account_id:
          $ref: '#/components/schemas/uuid'
          description: The account this cardholder belongs to.
        document_number:
          type: string
          description: Identity document number from the KYC profile.
        kyc_profile_id:
          $ref: '#/components/schemas/uuid'
          description: The KYC profile associated with this cardholder.
        phone:
          $ref: '#/components/schemas/CardholderPhone'
          description: Contact phone number for the cardholder.
    PaginationInfo:
      type: object
      required:
        - next_page_cursor
        - has_next
      properties:
        next_page_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: Base64-encoded cursor for the next page, null if no more items
        has_next:
          type: boolean
          description: True if there are more items available
      description: Pagination metadata for cursor-based pagination
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: HTTP status code.
        message:
          type: string
          description: Generic human-readable text for the status code. Do not parse it.
        reason:
          type: string
          description: >-
            Stable machine-readable code identifying the specific cause, present
            only

            for errors that expose one (e.g. `CREATE_CARD_LIMIT_EXCEEDED`).
            Branch on

            this rather than on `message`.
    CardholderPhone:
      type: object
      required:
        - number
        - country_code
      properties:
        number:
          type: string
          minLength: 4
          maxLength: 15
          pattern: ^[0-9]+$
          description: Phone number without country code.
        country_code:
          type: string
          minLength: 1
          maxLength: 4
          pattern: ^[0-9]+$
          description: Country calling code (e.g., "1" for US, "44" for UK).
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.