API Reference

Authentication

All API requests require authentication via an API key. Create API keys in your Clearmargin dashboard settings.

Include your API key in the request using either method:

Authorization: Bearer sk_live_your_api_key_here

x-api-key: sk_live_your_api_key_here

Base URL

https://app.clearmargin.app/api

All endpoint paths below are relative to this base URL.

Rate Limits

API requests are rate-limited to ensure platform stability:

When rate-limited, the API returns HTTP 429 with a Retry-After header indicating when you can retry.

Endpoints

Clearmargin exposes a RESTful API following standard CRUD patterns. Each resource supports list, get, create, update, and delete operations.

Query Parameters

List endpoints support filtering, sorting, and pagination via query parameters.

Filter syntax

The where parameter uses Payload query syntax. Pass conditions as nested query parameters:

# Filter clients by status
GET /api/clients?where[status][equals]=active

# Filter invoices by amount greater than 1000
GET /api/invoices?where[total][greater_than]=1000

# Filter time entries by date range
GET /api/time-entries?where[date][greater_than_equal]=2026-01-01&where[date][less_than]=2026-02-01

# Combine filters with AND (default)
GET /api/projects?where[status][equals]=active&where[client][equals]=client_id_here

Available operators

Examples

curl -H "Authorization: Bearer sk_live_your_key" \
  "https://app.clearmargin.app/api/clients?limit=10&sort=-createdAt"

curl -X POST \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "email": "billing@acme.com"}' \
  "https://app.clearmargin.app/api/clients"

curl -H "Authorization: Bearer sk_live_your_key" \
  "https://app.clearmargin.app/api/invoices?where[status][not_equals]=paid&sort=dueDate"

curl -X POST \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "project_id_here",
    "hours": 2.5,
    "date": "2026-03-14",
    "description": "API integration work",
    "billable": true
  }' \
  "https://app.clearmargin.app/api/time-entries"

{
  "docs": [
    {
      "id": "abc123",
      "name": "Acme Corp",
      "email": "billing@acme.com",
      "status": "active",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-03-01T14:20:00.000Z"
    }
  ],
  "totalDocs": 42,
  "limit": 10,
  "totalPages": 5,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}

Webhooks

Webhooks send real-time HTTP POST notifications to your server when events occur in Clearmargin. Configure webhooks in your organization settings.

Webhook payload format

{
  "event": "invoice_paid",
  "timestamp": "2026-03-14T15:30:00.000Z",
  "data": {
    "documentType": "invoice",
    "documentId": "inv_abc123",
    "documentNumber": "INV-0042",
    "amount": 2500.00,
    "client": {
      "id": "client_xyz",
      "name": "Acme Corp"
    },
    "contact": {
      "id": "contact_123",
      "name": "Jane Smith",
      "email": "jane@acme.com"
    }
  }
}

HMAC signature verification

When you configure a signing secret on your webhook, Clearmargin includes two headers for verification:

The signature is computed over {timestamp}.{body}. Verify it like this:

const crypto = require('crypto');

function verifyWebhookSignature(body, timestamp, signature, secret) {
  // Reject old timestamps (> 5 minutes) to prevent replay attacks
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error('Timestamp too old');
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');

  const received = signature.replace('sha256=', '');

  if (!crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(received, 'hex')
  )) {
    throw new Error('Invalid signature');
  }
}

Webhook Event Catalog

All available webhook events you can subscribe to. Each event includes the standard payload format shown above with event-specific metadata.

Proposal Events

Invoice & Payment Events

Receipt Events

Example: invoice_paid event

{
  "event": "invoice_paid",
  "timestamp": "2026-03-14T15:30:00.000Z",
  "data": {
    "documentType": "invoice",
    "documentId": "inv_abc123",
    "documentNumber": "INV-0042",
    "amount": 2500.00,
    "client": {
      "id": "client_xyz",
      "name": "Acme Corp"
    },
    "contact": {
      "id": "contact_123",
      "name": "Jane Smith",
      "email": "jane@acme.com"
    },
    "paymentMethod": "card",
    "last4": "4242",
    "brand": "visa"
  }
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Error responses include a JSON body with an errors array describing what went wrong.