Create Cardholder

POST

cards

cardholder

curl -X POST https://api.usenaive.ai/v1/cards/cardholder \
  -H "Authorization: Bearer nv_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "billingLine1": "123 Main St",
    "billingCity": "San Francisco",
    "billingState": "CA",
    "billingPostalCode": "94105",
    "dobDay": 15,
    "dobMonth": 3,
    "dobYear": 1990,
    "email": "john@acme.com",
    "phone": "+14155551234"
  }'

{
  "cardholder": {
    "id": "ich_1abc123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@acme.com",
    "phone": "+14155551234",
    "billingLine1": "123 Main St",
    "billingCity": "San Francisco",
    "billingState": "CA",
    "billingPostalCode": "94105",
    "billingCountry": "US",
    "type": "individual",
    "status": "active",
    "created_at": "2026-01-20T08:30:00Z"
  }
}

Creates a new cardholder profile for your company. A cardholder is required only for managed virtual cards (provider: "managed_virtual", Stripe Issuing). The default prepaid gift cards (prepaid_gift) do not need one.

Request Body

Parameter	Type	Required	Description
`firstName`	string	Yes	Cardholder’s first name
`lastName`	string	Yes	Cardholder’s last name
`billingLine1`	string	Yes	Billing address line 1
`billingCity`	string	Yes	Billing city
`billingState`	string	Yes	Billing state (2-letter code)
`billingPostalCode`	string	Yes	Billing postal/ZIP code
`dobDay`	number	Yes	Day of birth (1-31)
`dobMonth`	number	Yes	Month of birth (1-12)
`dobYear`	number	Yes	Year of birth (4 digits)
`email`	string	No	Cardholder’s email address
`phone`	string	No	Cardholder’s phone number
`billingCountry`	string	No	Billing country (2-letter ISO code, defaults to `US`)
`type`	string	No	Cardholder type: `individual` or `company` (defaults to `individual`)

curl -X POST https://api.usenaive.ai/v1/cards/cardholder \
  -H "Authorization: Bearer nv_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "billingLine1": "123 Main St",
    "billingCity": "San Francisco",
    "billingState": "CA",
    "billingPostalCode": "94105",
    "dobDay": 15,
    "dobMonth": 3,
    "dobYear": 1990,
    "email": "john@acme.com",
    "phone": "+14155551234"
  }'

{
  "cardholder": {
    "id": "ich_1abc123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@acme.com",
    "phone": "+14155551234",
    "billingLine1": "123 Main St",
    "billingCity": "San Francisco",
    "billingState": "CA",
    "billingPostalCode": "94105",
    "billingCountry": "US",
    "type": "individual",
    "status": "active",
    "created_at": "2026-01-20T08:30:00Z"
  }
}

CLI

naive cards create-cardholder

The CLI will prompt for required fields interactively.

MCP

Tool: naive_cards_create_cardholder

{
  "firstName": "John",
  "lastName": "Doe",
  "billingLine1": "123 Main St",
  "billingCity": "San Francisco",
  "billingState": "CA",
  "billingPostalCode": "94105",
  "dobDay": 15,
  "dobMonth": 3,
  "dobYear": 1990
}

May require approval. If the user’s Account Kit gates cards, an agent (API-key) call (cards.cardholder.create) returns 202 { "status": "pending_approval", "approval_id" }. A human approves it via Approvals. See Approvals.

curl -X POST https://api.usenaive.ai/v1/cards/cardholder \
  -H "Authorization: Bearer nv_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "billingLine1": "123 Main St",
    "billingCity": "San Francisco",
    "billingState": "CA",
    "billingPostalCode": "94105",
    "dobDay": 15,
    "dobMonth": 3,
    "dobYear": 1990,
    "email": "john@acme.com",
    "phone": "+14155551234"
  }'

{
  "cardholder": {
    "id": "ich_1abc123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@acme.com",
    "phone": "+14155551234",
    "billingLine1": "123 Main St",
    "billingCity": "San Francisco",
    "billingState": "CA",
    "billingPostalCode": "94105",
    "billingCountry": "US",
    "type": "individual",
    "status": "active",
    "created_at": "2026-01-20T08:30:00Z"
  }
}

​Request Body

​CLI

​MCP

Request Body

CLI

MCP