Skip to main content

​
Base URL

All Partner API requests use the following base URL: 
https://api.contro.me/v1

​
Authentication

Include your API key in the x-contro-api-key header: 
x-contro-api-key: sk_live_...
EnvironmentKey prefixBase URL
Sandboxsk_test_*https://api.contro.me/v1
Productionsk_live_*https://api.contro.me/v1
Never expose your API keys in client-side code or public repositories.

​
Request format

  • All request bodies must be JSON with Content-Type: application/json
  • Path parameters are denoted by {id} in endpoint paths
  • Query parameters are used for filtering and pagination

​
Response format

Successful responses return the requested resource or a success indicator: 
{
  "id": "ch_abc123",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "status": "active"
}
List endpoints return paginated results: 
{
  "data": [...],
  "hasMore": true,
  "nextCursor": "cursor_abc123"
}

​
Pagination

List endpoints support cursor-based pagination with two query parameters:
ParameterTypeDefaultDescription
cursorstring—Cursor from a previous response’s nextCursor
limitinteger20Items per page (1–100)
To paginate through results, pass the nextCursor value from the previous response as the cursor parameter. When hasMore is false, you have reached the end.

​
Rate limiting

The Partner API allows 1,000 requests per minute per API key. When exceeded:
  • Response status: 429 Too Many Requests
  • The Retry-After header indicates seconds to wait before retrying

​
Errors

All errors return a consistent format: 
{
  "success": false,
  "error": "Human-readable error message"
}
StatusMeaning
400Bad request — invalid parameters
401Unauthorized — missing or invalid API key
404Not found — resource does not exist
429Rate limited — too many requests
500Internal server error
See the errors guide for troubleshooting details.

​
Resources

Authentication

API key setup and security best practices

Quickstart

Issue your first card in 5 steps

Webhooks

Real-time event notifications

Errors

Error codes and troubleshooting