← Developer Home

API Reference

Complete reference for the Commish REST API v1.

Authentication

All API requests require a valid API key sent in the Authorization header:

Authorization: Bearer cm_live_your_api_key_here

Key format: cm_live_ + 64 hex characters

Scopes: read (view data), write (create/update), admin (approve/reject, manage webhooks)

Rate limit: 100 requests per minute per key

Pagination

List endpoints return paginated results. Use page and per_page parameters.

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 100
  }
}

Error Codes

Errors return a consistent JSON structure:

{
  "error": {
    "code": "not_found",
    "message": "Deal not found"
  }
}
CodeHTTP StatusDescription
unauthorized401Missing or invalid API key
forbidden403Insufficient permissions or inactive account
not_found404Resource not found
validation_error400Invalid request parameters
invalid_operation400Operation not allowed on resource in current state
rate_limited429Too many requests (100/min limit)
internal_error500Unexpected server error

Deals

Manage sales deals and their commission calculations.

Comp Plans

Manage compensation plans and their configurations.

Users

Manage sales reps and team members.

Commissions

Aggregated commission data across your organization.

SPIFFs

Manage SPIFFs (Sales Performance Incentive Fund) and leaderboards.

Custom Deal Fields

Manage custom fields that can be added to deals for your organization.

Webhooks

Manage webhook subscriptions to receive real-time event notifications.

Webhook Events

EventDescription
deal.createdA new deal is created
deal.approvedA deal is approved
deal.rejectedA deal is rejected
deal.updatedA deal is updated
commission.calculatedCommissions are recalculated
comp_plan.createdA new comp plan is created
comp_plan.updatedA comp plan is updated
comp_plan.assignedA comp plan is assigned to a user
spiff.createdA new SPIFF is created
spiff.updatedA SPIFF is updated
spiff.completedA SPIFF contest ends
user.createdA new user is added
user.updatedA user profile is updated