Connect every job, invoiceand certificate.
A stable, read-only REST contract for partner integrations, with scoped keys, per-key rate limits and signed event delivery.
Quick start
Your first request
Create a key in Admin → API Keys, grant the narrowest scopes your integration needs, then send it as a bearer token. Keys may also be restricted to one customer or an IP allow-list.
1. Create a key
The secret is shown once. Store it in a secret manager.
2. Add the header
Send Authorization: Bearer <api-key> on every request.
3. Read the headers
Use rate-limit headers to pace requests and retries.
curl "https://app.curcle.co.uk/api/public/v1/jobs?limit=20" \
--header "Authorization: Bearer <api-key>"REST reference
Seven versioned endpoints
All paths are under /api/public/v1. Collection responses use a data array; jobs, invoices and certificates include limit and offset pagination metadata.
/meIdentify the calling API keybearer token/jobsList visible jobsread:jobs/jobs/{id}Get a job and its appliancesread:jobs/invoicesList visible invoicesread:invoices/certificatesList visible certificatesread:certificates/customersList visible customersread:customers/healthzCheck API availabilitybearer tokenLeast privilege
Choose focused scopes
Resource scopes can be combined as a comma-separated list. Write scopes imply read access, while customer-bound keys cannot escape their customer restriction.
readRead access to every public resource.
read:jobsRead job summaries and job detail.
read:invoicesRead invoice records.
read:certificatesRead certificate links.
read:customersRead customer records.
writeReserved for future write endpoints; implies read access.
adminFull access to every public resource.
Rate limits
Predictable, per-key windows
Each API key has its own requests-per-minute allowance. Successful and rejected responses report the current allowance; a 429 also tells you when to retry.
X-RateLimit-LimitMaximum requests in the one-minute window.
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetUnix timestamp when the window resets.
Retry-AfterSeconds to wait after a 429 response.
Signed delivery
React to business events
Create an HTTPS subscription in Admin → Webhooks. Curcle sends the exact JSON body withX-HK-Signature: sha256=<HMAC>and retries failed deliveries with exponential backoff.
Job completed
Sent when a job is marked complete.
{
"event": "job.completed",
"data": {
"id": 123,
"certificateNumber": "HK-2026-00123",
"customerId": 42,
"siteId": 7,
"completedAt": "2026-06-15T10:30:00.000Z"
},
"timestamp": "2026-06-15T10:30:00.000Z"
}Verify the lowercase hex HMAC-SHA256 digest against the raw request body before parsing JSON. Delivery attempts use backoff intervals of 10 seconds, 30 seconds, 2 minutes, 10 minutes, 30 minutes and 2 hours.
Errors
Small, consistent envelopes
The API returns 401 for missing or invalid credentials, 403 for missing scopes or an IP allow-list denial, 404 for records outside the key's visibility, and 429 for rate limits.
{
"error": "Missing required scope: read:jobs"
}
Build around a record you can trust.
Review the API boundary, scopes and webhook behaviour with the Curcle team.