Clientish Webhooks & API Reference

Introduction

The API returns JSON. A key can read what you checked for it, and keys you allow can also add and update leads, clients, orders and tickets and prepare draft invoices; see Create and update. Nothing can ever be deleted through it.

A request needs an API key, made on the Webhooks & API → API keys tab of your dashboard. Each key reads only what you checked for it, only from your own workspace, and every call it makes is listed on that tab.

Successful responses come back under data:

{ "data": { "clients": [ … ], "pagination": { … } } }

If you want to hear about things as they happen instead of asking again and again, see Webhooks.

Authentication

Send the key as a Bearer token:

curl 'https://clientish.io/api/v1/clients?per_page=5' \
  -H 'Authorization: Bearer YOUR-API-KEY'

A tool that can’t set an Authorization header may send X-Api-Key: YOUR-API-KEY instead.

A key that is missing, mistyped, revoked or expired gets 401. A key may also be limited to fixed addresses and given an expiration date.

Permissions

Permissions are chosen per key when it’s created: read per area and, for leads, clients, orders, tickets and invoices, permission to create and update them. Asking for something a key can’t do gets 403.

GET /search works with any permission, and searches only the record types the key may read.

Create & update for an area includes reading it.

Pagination & filters

Lists come back newest first, 25 rows at a time. Ask for more with per_page (up to 100) and move with page. Every list carries a pagination object; keep asking while has_more is true.

{ "pagination": { "page": 2, "per_page": 100, "total": 1204, "last_page": 13, "has_more": true } }

• Filters are query parameters, listed on each endpoint. A parameter the endpoint doesn’t recognize is ignored.
• Dates are YYYY-MM-DD, and from and to both include the day given.
• Status filters take the label you see in Clientish, in any case: paid and Paid are the same.
• Times are ISO 8601 with their offset, for example 2026-09-12T10:21:04+06:00. Money is a plain number in the currency the response names.

Rate limits

Each key has its own limit per minute, set when it is made: 120 unless you change it, anywhere from 1 to 1,000. Every successful response says where you stand.

Repeated tries with a wrong key from one address are refused with 429 for a minute.

Errors

Errors use the HTTP status and a body you can show or log:

{ "error": { "status": 403, "message": "This API key does not have permission for this data." } }

Webhooks

Add an endpoint on the Webhooks tab and your workspace POSTs an event to it the moment something happens. Webhooks need no API key; each endpoint has its own signing secret.

Events

What is sent

data is the record in the same shape the matching Get endpoint returns, as it stands when the event is first sent. test is true for test events.

{
  "id": "evt_k2m9q4w7x1c8v5b3n6z0",
  "type": "order.status_changed",
  "created_at": "2026-09-18T10:21:04+06:00",
  "test": false,
  "data": { "order": { "id": 5120, "order_no": "ORD-5120", "status": "Working" } },
  "changes": { "status": { "from": "Pending", "to": "Working" } }
}

Headers

Check the signature

Compute it over the raw body, before parsing:

// Node.js (Express)
const crypto = require('crypto');

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto
    .createHmac('sha256', SIGNING_SECRET)
    .update(req.headers['clientish-timestamp'] + '.' + req.body)
    .digest('hex');
  if (expected !== req.headers['clientish-signature']) return res.sendStatus(401);
  res.sendStatus(200);
});

Answering and retries

• Answer any 2xx within 10 seconds. Anything else (another code, a redirect, a timeout) counts as failed.
• A failed delivery is retried 5 more times: after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours.
• After 20 failed attempts in a row the endpoint is switched off and the owner is notified. Resume it from the Webhooks tab once it is fixed.
• Events are sent within about a minute, and not in strict order. Use created_at and the record itself when order matters.
• Endpoints must be HTTPS on a public address. Deliveries are kept for 30 days.

Create and update

A key can also add and change records where you allow it: on the key, check Create & update for Leads, Clients, Orders, Tickets or Invoices. Every change runs through the same rules as when your team makes it, including notifications, history and plan limits, and nothing can ever be deleted.

Request

Send the fields as JSON with Content-Type: application/json. POST creates or adds; PATCH changes only the fields you send.

Response

201 when something was created, 200 otherwise. id and type name the record, summary says what was done, and change_id is its entry under What it changed on the key. When nothing needed changing, such as an order already at that status, only done and summary come back.

Idempotency-Key

Tools like Zapier retry a request when a response is slow. Send a unique Idempotency-Key header, up to 100 characters, with each POST. For 24 hours the same Idempotency-Key on the same API key gets the first response back, with Idempotent-Replayed: true, instead of creating the record twice.

Limits and undo

• Up to 500 changes a day per key, on top of its requests per minute.
• Invoices are always drafts: your team approves them before the client sees anything. Nothing is ever marked paid.
• Every change is listed on the key under What it changed. A change of status, stage or details can be undone there for 7 days.

Errors

Instant triggers

Zapier and Make can subscribe to your webhook events with the key: POST /hooks starts one, DELETE /hooks/{id} stops it.