Skip to main content
POST
/
partner
/
cardholders
Create cardholder
curl --request POST \
  --url https://api.contro.me/v1/partner/cardholders \
  --header 'Content-Type: application/json' \
  --header 'x-contro-api-key: <api-key>' \
  --data '
{
  "externalUserId": "user_42",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "phoneNumber": "+14155552671",
  "metadata": {
    "plan": "premium",
    "tier": "gold"
  }
}
'
{
  "id": "ch_abc123",
  "externalUserId": "user_42",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "phoneNumber": "+14155552671",
  "kycStatus": "approved",
  "status": "active",
  "createdAt": "2026-03-20T14:30:00Z",
  "metadata": {
    "plan": "premium"
  }
}

Authorizations

​
x-contro-api-key
string
header
required

Partner API key (sk_live_* for production, sk_test_* for sandbox)

Body

application/json
​
externalUserId
string
required

Your unique identifier for this user. Min 1 character

Minimum string length: 1
Example:

"user_42"

​
firstName
string
required

Cardholder's first name. Min 1 character

Minimum string length: 1
Example:

"Jane"

​
lastName
string
required

Cardholder's last name. Min 1 character

Minimum string length: 1
Example:

"Doe"

​
email
string<email>
required

Valid email address

Example:

"jane@example.com"

​
phoneNumber
string

E.164 formatted phone number

Example:

"+14155552671"

​
metadata
object

Arbitrary key-value pairs for your use

Example:
{ "plan": "premium", "tier": "gold" }

Response

Cardholder created

​
id
string
required

Contro cardholder ID

Example:

"ch_abc123"

​
externalUserId
string
required

Your unique identifier for this user

Example:

"user_42"

​
firstName
string
required

Cardholder's first name

Example:

"Jane"

​
lastName
string
required

Cardholder's last name

Example:

"Doe"

​
email
string
required

Email address

Example:

"jane@example.com"

​
phoneNumber
string | null
required

E.164 formatted phone number, or null if not provided

Example:

"+14155552671"

​
kycStatus
string
required

KYC verification status. One of: pending, approved, rejected

Example:

"approved"

​
status
string
required

Cardholder account status. One of: active, suspended, closed

Example:

"active"

​
createdAt
string
required

ISO 8601 creation timestamp

Example:

"2026-03-20T14:30:00Z"

​
metadata
any

Custom key-value metadata, or null if not set

Example:
{ "plan": "premium" }