Skip to main content

Documentation Index

Fetch the complete documentation index at: https://partner-docs.contro.dev/llms.txt

Use this file to discover all available pages before exploring further.

Cardholders are the end users who receive and use cards. Each cardholder belongs to a single partner and must pass KYC before cards can be issued.

​
KYC methods

Contro supports two ways to submit KYC when creating a cardholder. Choose the method that best fits your integration:
MethodkycSourceBest for
KYC via web link"web" (default)Partners who prefer a hosted KYC flow without handling sensitive data
KYC via Sumsub share token"sumsub"Partners already using Sumsub who want to reuse verified KYC

​
Create a cardholder

Creating a cardholder and submitting KYC happen in a single request. The example below uses the web link method (kycSource: "web"), where KYC is completed via a hosted session. See the individual KYC method pages for other approaches. First, create a KYC session via POST /partner/kyc-sessions and wait for the user to complete it, then create the cardholder: 
curl -X POST https://api.contro.me/v1/partner/cardholders \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_42",
    "kycSource": "web",
    "kycSessionId": "ks_abc123",
    "email": "jane@example.com",
    "phoneNumber": "+14155552671"
  }'

​
Required fields

FieldTypeDescription
externalUserIdstringYour unique identifier for this user. Min 1 character. Example: "user_42"
emailstringValid email address. Example: "jane@example.com"
phoneNumberstringE.164 formatted phone number. Example: "+14155552671"

​
Optional fields

FieldTypeDescription
kycSourcestringKYC method. One of "web" (default), "sumsub". See KYC methods

​
Initiate KYC for a card program

After creating the cardholder, initiate KYC verification for a specific card program. Cards cannot be issued until KYC is approved for that program. 
curl -X POST https://api.contro.me/v1/partner/cardholders/{id}/kyc \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardProgramId": "cp_xyz789"
  }'
Response: 
{
  "status": "pending",
  "cardholderId": "ch_abc123",
  "cardProgramId": "cp_xyz789"
}

​
KYC status

​
Check KYC status

The cardProgramId query parameter is required. 
curl "https://api.contro.me/v1/partner/cardholders/{id}/kyc?cardProgramId=cp_xyz789" \
  -H "x-contro-api-key: $CONTRO_API_KEY"
Response: 
{
  "kycStatus": "approved",
  "cardProgramId": "cp_xyz789"
}

​
KYC status lifecycle

StatusDescription
pendingVerification in progress
approvedVerification passed — cards can be issued
rejectedVerification failed — review and retry
In sandbox mode, KYC is auto-approved for testing. In production, verification is performed by the KYC provider.

​
Update a cardholder

Update mutable fields on an existing cardholder: 
curl -X PATCH https://api.contro.me/v1/partner/cardholders/{id} \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@newdomain.com",
    "phoneNumber": "+14155559999"
  }'
Updatable fields: email, phoneNumber.

​
List cardholders

Retrieve cardholders with optional filtering: 
curl "https://api.contro.me/v1/partner/cardholders?limit=20&status=active&kycStatus=approved" \
  -H "x-contro-api-key: $CONTRO_API_KEY"

​
Query parameters

ParameterTypeDescription
pageintegerPage number (default 1).
limitintegerItems per page (1–100, default 20). Example: 50
statusstringFilter by cardholder status. One of active, suspended, closed.
kycStatusstringFilter by KYC status. One of pending, approved, rejected.
externalUserIdstringFilter by your externalUserId.
fromstringISO 8601 start timestamp (inclusive) on createdAt.
tostringISO 8601 end timestamp (inclusive) on createdAt.

​
Get a cardholder

Retrieve a single cardholder by ID: 
curl https://api.contro.me/v1/partner/cardholders/{id} \
  -H "x-contro-api-key: $CONTRO_API_KEY"

​
Response fields

FieldTypeDescription
idstringContro cardholder ID. Example: "ch_abc123"
externalUserIdstringYour user identifier. Example: "user_42"
firstNamestringFirst name. Example: "Jane"
lastNamestringLast name. Example: "Doe"
emailstringEmail address. Example: "jane@example.com"
phoneNumberstring | nullE.164 phone number, or null if not provided. Example: "+14155552671"
kycSourcestringKYC submission method. One of sumsub, web
kycStatusstringKYC verification status. One of pending, approved, rejected
statusstringCardholder account status. One of active, suspended, closed
createdAtstringISO 8601 creation timestamp. Example: "2026-03-20T14:30:00Z"