API and SDK quickstart

The ClickFix REST API lets your systems create conversations, add notes, update contacts and subscribe to events. The API reference lists every endpoint and schema with ready-made request samples per language; it only contains public, stable endpoints. OpenAPI file: public-api.yaml.

1. Create an API key#

1. Open Organization → API & automations.
2. On the API keys tab, click New API key.
3. Enter a name, select only the Scopes your integration needs and optionally set Requests per minute and an Expires date.
4. Click Create key and copy the key right away. It starts with cf_sk_ and is shown only once; ClickFix stores only a hash.

A key is limited to the current permissions of the member who created it. If that member loses a permission or leaves the organization, the key is restricted accordingly. Revoke invalidates a key immediately.

Use API keys on your server only. Never put them in browser or mobile app code.

Scopes#

2. Your first request#

Base URL:

https://api.getclickfix.com/v1/public-api

Send the key in the Authorization header of every request:

curl https://api.getclickfix.com/v1/public-api/contacts?limit=20 \
  -H "Authorization: Bearer cf_sk_..."

Response envelope#

Every response uses the same envelope:

{
  "success": true,
  "data": {},
  "meta": { "request_id": "..." }
}

On error:

{
  "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [] },
  "meta": { "request_id": "..." }
}

Branch on error.code; message text can change. Include meta.request_id when you contact support.

Pagination#

List endpoints accept limit (default 20, max 100) and offset. The contact list also supports q for search.

{
  "success": true,
  "data": { "items": [], "total": 0, "limit": 20, "offset": 0 }
}

To follow changes continuously, use trigger polling or webhooks instead of paging.

Writes and Idempotency-Key#

Every request other than GET must carry an Idempotency-Key header. Generate a unique value per logical action and send the same value with the same body when you retry. ClickFix stores the completed response and returns it again for a repeated request with the same key. Reusing a key with a different body returns 409 IDEMPOTENCY_CONFLICT.

Example: create a conversation#

curl -X POST https://api.getclickfix.com/v1/public-api/conversations \
  -H "Authorization: Bearer cf_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42-support" \
  -d '{
    "contact_uuid": "CONTACT_UUID",
    "inbox_uuid": "CHANNEL_UUID",
    "subject": "Delivery question"
  }'

inbox_uuid is the ID of one of your active channels. The contact and the channel must belong to the key's organization. The conversation is assigned to the member who created the key.

Example: add an internal note#

curl -X POST https://api.getclickfix.com/v1/public-api/conversations/CONVERSATION_UUID/messages \
  -H "Authorization: Bearer cf_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c0e3a-note-1" \
  -d '{ "content": "Order shipped.", "private": true, "client_id": "6f1c0e3a-0d0b-4a4e-9a51-3c8b7d2f1e90" }'

Endpoints#

Body fields and response schemas are in the API reference.

Rate limits and sizes#

• Each key has a per-minute request limit (default 120, configurable from 1 to 6000).
• Over the limit you get 429 RATE_LIMITED with a Retry-After header; wait that long before retrying.
• Request bodies can be up to 128 KB.
• Don't retry validation and auth errors (400, 401, 403); fix the request first.

SDKs#

Server SDKs for Go and Node.js and a headless React widget client are available as source on GitHub. They are not yet published as packages. Configure them with https://api.getclickfix.com as the base URL (without /v1).

The SDKs handle authentication, bounded retries, pagination and webhook signature verification. For example, in Node.js:

import { createClient } from "@clickfix/node";

const client = createClient({
  baseURL: "https://api.getclickfix.com",
  apiKey: process.env.CLICKFIX_API_KEY!,
});

await client.request(
  "/v1/public-api/conversations",
  "post",
  {
    contact_uuid: contactUUID,
    inbox_uuid: inboxUUID,
    subject: "Delivery question",
  },
  { idempotencyKey: "order-42-support" },
);

Next steps#

• Webhooks and signature verification
• Zapier, Make and n8n
• Build your own app