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

# Create cardholder

> Register a person who can hold cards under a business customer.

`phoneCountryCode` and `phoneNumber` travel together — sending one without the other is a `400 ERRCRD_1005`. A `91` country code requires 10 digits starting 6–9.



## OpenAPI

````yaml api-reference/endl-cards-api.json POST /api/v0/customer/{businessId}/card-users
openapi: 3.1.0
info:
  title: Endl Cards API
  version: '0'
  description: >-
    Issue single-use virtual cards to cardholders under a business customer.


    Three endpoints under `/api/v0/customer`. The key must carry the **`cards`**
    permission, and the business customer must be enabled for cards.


    **Card details are returned once, encrypted to your own RSA public key** —
    see [Card details encryption](/api-reference/cards/encryption).
servers:
  - url: https://api-sandbox.endl.io
    description: Sandbox
security:
  - apiKey: []
paths:
  /api/v0/customer/{businessId}/card-users:
    post:
      tags:
        - Cards
      summary: Create cardholder
      description: >-
        Register a person who can hold cards under a business customer.


        `phoneCountryCode` and `phoneNumber` travel together — sending one
        without the other is a `400 ERRCRD_1005`. A `91` country code requires
        10 digits starting 6–9.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/BusinessId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - firstName
                - lastName
                - email
              properties:
                firstName:
                  type: string
                  description: Non-blank.
                lastName:
                  type: string
                  description: Non-blank.
                email:
                  type: string
                  description: >-
                    Valid email. Must not already be an Endl account or another
                    business's cardholder.
                phoneCountryCode:
                  type: string
                  description: Digits — `"1"`. Required with `phoneNumber`.
                phoneNumber:
                  type: string
                  description: >-
                    Digits, unique across cardholders. Required with
                    `phoneCountryCode`.
            example:
              firstName: Ada
              lastName: Lovelace
              email: ada@example.com
              phoneCountryCode: '1'
              phoneNumber: '5555550100'
      responses:
        '201':
          description: The cardholder. Returned directly — no envelope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardholderId:
                    type: string
                    description: '`cus_…`. Use it to issue cards.'
                  businessId:
                    type: string
                    description: The business.
                  firstName:
                    type: string
                    description: As stored.
                  lastName:
                    type: string
                    description: As stored.
                  email:
                    type: string
                    description: As stored.
                  status:
                    type: string
                    enum:
                      - active
                      - pending
                      - rejected
                      - canceled
                    description: Cardholder state.
              example:
                cardholderId: cus_6OzDYZWl5Aim37RwvZfZ
                businessId: cus_HUCgMg1iqWb379FMNvaJ
                firstName: Ada
                lastName: Lovelace
                email: ada@example.com
                status: active
        '400':
          description: >-
            `ERRCRD_1000` not a business customer · `ERRCRD_1001` business not
            enabled for cards · `ERRCRD_1005` missing or invalid field, phone
            sent half, invalid JSON · `ERRCRD_1010` cannot create — already
            added, email already registered or in use, phone already used,
            invalid phone.
          content:
            application/json:
              example:
                code: 400
                message: Cardholder could not be created
                status: ERROR
                data: null
                errors:
                  - code: ERRCRD_1010
                    message: Cardholder could not be created
                    field: null
        '401':
          description: Missing or invalid `Api-Key`.
          content:
            application/json:
              example:
                code: 401
                message: Partner API key required
                status: ERROR
                data: null
                errors:
                  - code: ERRCORE_1004
                    message: Partner API key required
                    field: null
        '403':
          description: Business belongs to another partner, or the key lacks `cards`.
          content:
            application/json:
              example:
                code: 403
                message: Access denied / missing cards permission
                status: ERROR
                data: null
                errors:
                  - code: ERRCORE_1005
                    message: Access denied / missing cards permission
                    field: null
        '404':
          description: Unknown `businessId` — reported on field `userId`.
          content:
            application/json:
              example:
                code: 404
                message: Reference not found
                status: ERROR
                data: null
                errors:
                  - code: ERRREF_1001
                    message: Reference not found
                    field: userId
components:
  parameters:
    ApiVersion:
      name: Api-Version
      in: header
      required: true
      description: >-
        The API version this request targets. `2026-09.1`. See
        [Versioning](/api-reference/versioning).
      schema:
        type: string
        pattern: ^\d{4}-\d{2}\.\d+$
        default: 2026-09.1
      example: 2026-09.1
    BusinessId:
      name: businessId
      in: path
      required: true
      schema:
        type: string
      description: Your **business** customer, `cus_…`, enabled for cards.
      example: cus_HUCgMg1iqWb379FMNvaJ
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Api-Key
      description: Partner API key. Must carry the `cards` permission.

````