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

# Create a cardholder

> Creates a cardholder for an account.

In the recommended onboarding flow, call this after the linked account is
active. The cardholder's verified identity is taken from the KYC profile
already associated with the account; the request supplies only the account
and contact phone number.

Returns 422 with reason `CARDHOLDER_CREATION_LIMIT_EXCEEDED` when creating the
cardholder would exceed the configured number of cardholders for the account.



## OpenAPI

````yaml https://core.sandbox.gnosispay.in/partner-api/openapi.json post /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:
    post:
      tags:
        - Cards
      summary: Create a cardholder
      description: >-
        Creates a cardholder for an account.


        In the recommended onboarding flow, call this after the linked account
        is

        active. The cardholder's verified identity is taken from the KYC profile

        already associated with the account; the request supplies only the
        account

        and contact phone number.


        Returns 422 with reason `CARDHOLDER_CREATION_LIMIT_EXCEEDED` when
        creating the

        cardholder would exceed the configured number of cardholders for the
        account.
      operationId: cardholders.create.v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCardholderParams'
        description: Account and contact phone number for the new cardholder.
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCardholderResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateCardholderParams:
      type: object
      required:
        - account_id
        - phone
      properties:
        account_id:
          $ref: '#/components/schemas/uuid'
          description: The account this cardholder belongs to.
        phone:
          $ref: '#/components/schemas/CardholderPhone'
          description: Contact phone number for the cardholder.
    CreateCardholderResponse:
      type: object
      required:
        - cardholder_id
      properties:
        cardholder_id:
          $ref: '#/components/schemas/uuid'
          description: The ID of the newly created cardholder.
    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`.
    uuid:
      type: string
      format: uuid
    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.