FireCert Clock REST API
The REST API lists sites and assets, creates both, logs a visit, and downloads the asset CSV. Responses are JSON over HTTPS, except the CSV export. API access is on the Business plan. The pricing row for API and CSV export is the plan gate the routes enforce.
Authentication
Create a key in Settings. An account can hold up to 10 keys. The full key is shown once. The server stores only a SHA-256 hash. The key starts with fcc_. Send it as a bearer token:
curl -H "Authorization: Bearer fcc_..." https://www.firecertclock.com/api/v1/sites
A missing bearer token, a key that does not start with that prefix, or a hash the account does not recognise returns 401 with {"error":"unauthorized"}. The message is Send Authorization: Bearer <api key>. or Unknown or revoked API key. Revoke a key in Settings at any time. A key acts on the team owner of the account that created it. If that owner's plan does not allow the API, the route returns 402 with {"error":"plan_required","message":"API access starts on Business."}.
Rate limits
Each key may make 60 requests per minute. The window is 60 seconds from the first request in the bucket. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. X-RateLimit-Reset is the unix second when the bucket resets. Over the limit the route returns 429 with Retry-After and {"error":"rate_limited","message":"Limit is 60 requests per minute per key."}.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /api/v1/sites | List sites with asset counts and overdue totals. |
| POST | /api/v1/sites | Add a site. Returns 201, 400, 402, or 409. |
| GET | /api/v1/sites/{id} | One site and its assets, or 404. |
| DELETE | /api/v1/sites/{id} | Remove a site and its assets. Returns 204, or 404. |
| GET | /api/v1/assets | List assets. Optional ?status=overdue. |
| POST | /api/v1/assets | Add an asset. Returns 201, 400, 402, or 404. |
| POST | /api/v1/assets/{id}/visits | Log a visit and return the asset. Returns 200 or 404. |
| GET | /api/v1/export.csv | CSV attachment named assets.csv. |
GET /api/v1/sites
Returns {"data":[...]}. Each site object has id, name, address, client_email, asset_count, overdue_count and created_at. asset_count is the number of assets on that site. overdue_count is how many of those assets have next_due_on before today.
POST /api/v1/sites
Body fields are name (required, 1 to 120 characters), address (optional, up to 200 characters), client_email (optional email, or an empty string) and client_name (optional, up to 120 characters). A body that fails that shape returns 400 with {"error":"invalid_json","message":"Send {\"name\": \"Warehouse A\"}."}. A successful create returns 201 and {"data": site} with asset count and overdue count at zero. The route stores the jurisdiction as generic. It does not set a state or a council. Over the site cap the response is 402 with {"error":"plan_limit","message":"The current plan does not cover another site."}. A repeated name returns 409 with {"error":"duplicate","message":"That site name is already on the account."}.
GET and DELETE /api/v1/sites/{id}
GET returns the site object plus an assets array. Each asset has id, site_id, name, kind, location, preset_id, interval_days, last_service_on, next_due_on and created_at. A missing site returns 404 with {"error":"not_found"}. DELETE returns 204 with an empty body when the site belonged to the account, and the same 404 when it did not.
GET /api/v1/assets
Returns every asset on the account as {"data":[...]} using the asset fields above. ?status=overdue keeps only rows whose next_due_on is before today. Any other query value returns the full list. There is no pagination parameter on this route.
POST /api/v1/assets
Required fields are site_id, kind and last_service_on. kind is one of extinguisher, fire_alarm, sprinkler, emergency_light or custom. Optional fields are name (up to 120 characters), location (up to 120 characters), preset_id, interval_days (a positive integer up to 5000) and technician_id. A body that fails that shape returns 400 with {"error":"invalid_json","message":"Send site_id, kind and last_service_on."}. If preset_id is omitted or is not a known preset, the route uses the default preset for the kind. If interval_days is sent, preset_id is stored as custom-interval and the interval is the number you sent. Otherwise the interval is the preset's day count, or 365 when that preset has none. An empty name is stored as the label for the kind. A missing site returns 404 with {"error":"not_found"}. Another rejected create returns 400 with {"error":"invalid_json"}. Over the asset cap the response is 402 with {"error":"plan_limit","message":"The current plan does not cover another asset."}. Success is 201 and {"data": asset}.
POST /api/v1/assets/{id}/visits
Body field service_on is required and must be an ISO date YYYY-MM-DD. next_due_on is optional and, when present and a valid ISO date, is stored as the next due date. When it is omitted or not an ISO date, the next due date is calculated from service_on and the asset's interval_days. A bad body returns 400 with {"error":"invalid_json","message":"Send {\"service_on\":\"YYYY-MM-DD\"}."}. A missing asset returns 404 with {"error":"not_found"}. Success is 200 and {"data": asset} with the new last service and next due dates. The visit is stored as confirmed. The route does not accept a report file on this call.
GET /api/v1/export.csv
Returns 200 with content-type: text/csv; charset=utf-8 and content-disposition: attachment; filename="assets.csv". Each row carries the site name, the asset name, the kind, the location, the last service date, the next due date, the status, and the preset id. The same authentication, plan gate and rate limit apply as on the JSON routes.
Errors
JSON errors use {"error":"code","message":"..."}. The codes these routes return are unauthorized (401), plan_required (402), invalid_json (400), plan_limit (402), duplicate (409), not_found (404) and rate_limited (429). A message is included when the handler sets one.
A short script
Create the key in Settings, then GET https://www.firecertclock.com/api/v1/sites. POST a site with a name. Read data.id from the 201 body. POST an asset with that site_id, a kind, and last_service_on. POST a visit to /api/v1/assets/{id}/visits with service_on. GET /api/v1/assets?status=overdue when you only want rows already past the next due date. GET /api/v1/export.csv when a spreadsheet is the handoff. Stop on 401 and create a new key. Stop on 402 and use a Business account, or remove a site or asset when the code is plan_limit. On 429, wait for Retry-After and send that request again.
Signed webhooks
A reminder webhook is separate from the REST routes. When the account has a webhook URL and a signing secret, a due reminder POSTs JSON with content-type: application/json. The body is event set to inspection.reminder, an id built from the asset id, the days before due, and the next due date, sent_at, an asset object with id, name, next_due_on and url, plus subject and text. The headers are X-FireCertClock-Event: inspection.reminder and X-FireCertClock-Signature: t=<unix seconds>,v1=<hex>. v1 is HMAC-SHA256 of the unix timestamp, a dot, and the raw body, using the signing secret. The sender does not attach an expiry of its own. Compare t with your clock when you verify the signature.
Support and Terms. Calculator.