Help CentreSign in

The REST API for developers: endpoints, scopes and rate limits

Read-only endpoints for your own records: contractors, sites, the gate, safety, expiries and the Insights feed, with an OpenAPI description at /api/v1/openapi.json.

2 min readLast updated

Applies to: Integrations · Administrator, Visitors and anyone with a link

On this page

The REST API (the iComply API on the developer page; it used to be called the Builder API) is read-only access to your own business's records for your own systems. It works for every kind of business with Integrations on. The reference is at /developers/api, built from the OpenAPI 3.1 description at /api/v1/openapi.json.

Before you start

  • An admin creates a key with the scopes you need. See Create and revoke API keys.
  • It's not for browsers: there are no cookies and no cross-site access.

How to make a request

  1. Step 1: Use the base address https://app.icomplyaustralia.com.au/api/v1, or your business's own address. A key used on another business's address is refused.
  2. Step 2: Send the header Authorization: Bearer followed by a space and the key exactly as shown.
  3. Step 3: Page through lists with ?limit= (1 to 200, default 50) and ?cursor= from the previous page's nextCursor (empty on the last page).
  4. Step 4: Send back the ETag as If-None-Match to get 304 when nothing changed.

The endpoints

  • /subcontractors (read:subcontractors): each of your contractors, their status, requirements met and next expiry, and each site they're on. No contact names, emails or phones.
  • /sites (read:sites): id, name, client, address, state, status and dates.
  • /sites/<id>/on-site (read:gate): who's signed in now. No phone numbers.
  • /gate-events (read:gate): sign-ins, overrides and refusals; the last 7 days by default, 93 days at most.
  • /incidents/summary (read:safety): counts only, by kind, severity, status and site. No descriptions and no people.
  • /corrective-actions (read:safety): title, site, source, priority, due date and status. Owners aren't named.
  • /expiries (read:compliance): approved documents and tickets expiring in the next 1 to 365 days (30 by default).
  • /insights/<table> (read:insights): the Insights feed. See The Power BI feed.

Errors and limits

  • 120 requests a minute per key. Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining; past the limit you get 429 with Retry-After.
  • 30 failed key checks from one connection in 10 minutes, then 429 for that connection.
  • 401: no key, a wrong key, or one that's expired or revoked. 403: the key lacks the scope, or the business is suspended. 404: not found, including another business's ids. 400: a bad query.
  • Fields are only ever added; existing ones keep their meaning.
Every request, including refusals, is recorded in Who looked at what with the key's name, the path, the status and how many records.
Open the API documentation
Was this helpful?

Related articles