Skip to main content
This guide walks you through the core Partner API flow: creating a cardholder, completing KYC, and issuing a card.

​
Prerequisites

  • A Contro partner account with sandbox API keys (sk_test_*)
  • A tool for making HTTP requests (cURL, Postman, or your language’s HTTP client)
1

Authenticate

Set your API key. All examples below use the sandbox key.
export CONTRO_API_KEY="sk_test_your_key_here"
2

Create a cardholder

Register an end user as a 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_123",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com"
  }'
Required fields: externalUserId, firstName, lastName, emailOptional fields: phoneNumber, metadata
3

Initiate KYC

Submit the cardholder for identity verification. Cards cannot be issued until KYC is approved.
curl -X POST https://api.contro.me/v1/partner/cardholders/ch_abc123/kyc \
  -H "x-contro-api-key: $CONTRO_API_KEY"
Poll the KYC status or listen for the webhook event:
curl https://api.contro.me/v1/partner/cardholders/ch_abc123/kyc \
  -H "x-contro-api-key: $CONTRO_API_KEY"
4

Issue a card

Once KYC is approved, choose a card program and issue a card.First, list available programs:
curl https://api.contro.me/v1/partner/card-programs \
  -H "x-contro-api-key: $CONTRO_API_KEY"
Then issue a card:
curl -X POST https://api.contro.me/v1/partner/cards \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholderId": "ch_abc123",
    "programId": "prog_xyz"
  }'
5

Query transactions

View transaction activity for the card.
curl https://api.contro.me/v1/partner/cards/card_def456/transactions \
  -H "x-contro-api-key: $CONTRO_API_KEY"

​
Next steps

Cardholders

Learn about cardholder management and KYC

Cards

Card lifecycle, limits, and actions

Webhooks

Set up real-time event notifications

API reference

Explore all endpoints in the playground