Integrations

Two ways in, and only one of them needs a developer

A key assumes somebody will write code against it. That is a fair assumption for an agency with a developer and a wrong one for most, so there is a second way in that costs no development at all.

A connection

Create one in the desk under Connections and you get an address and a secret. Point the export your current system already produces at that address, on whatever schedule suits, with the secret as a bearer token or an X-Connection-Secret header. That is the whole setup on their side: no partner programme, no marketplace approval, no code.

What arrives runs through the same importer a person uses, so it reads your own column headings, reports every rename it made, and refuses exactly what a manual import would refuse.

Every run is recorded, including the ones that brought nothing, and each carries what the importer said about it. The failure that matters with an automated source is never loud: it is a connection that quietly stopped, leaving an agency believing its compliance position is current when it is three weeks stale.

Connections read into us and never write back into your system. Writing into somebody's CRM is a different product with a different failure mode, and an agency will forgive a stale read long before it forgives a corrupted book.

A key

Keys, and what they can touch

An agency generates its own keys. A key belongs to exactly one agency and there is no way to ask for another agency's data with a valid one.

Grants are per area and per level rather than one global read and write, because a key is the keys to somebody's back office. The areas are placements, timesheets, billing, compliance and jobs. Write implies read for the same area only and never leaks across areas, so an integration that pushes placements cannot read your billing ledger.

The secret is shown once. Only its hash is stored, so it cannot be recovered or shown again; if it leaks, revoke it and issue another. Revocation takes effect on the next request rather than eventually, because the reason somebody revokes a key is usually that it has just leaked.

What no key can do

The usual first integration

1. Create a key scoped placements:write timesheets:write compliance:read.
2. Post each new assignment as a placement. Umbrella engagements must name their umbrella.
3. Push approved hours as weeks, or let the client sign them off through their portal.
4. Read the compliance position back into your own dashboard: which placements lack a KID, which umbrellas carry live placements on a stale file, which workers need rechecking before 1 October.

The API reference lists every published endpoint by area.

Your own address

Agencies can be given their own address, either a subdomain of ours or a domain you already own, so links your clients and workers receive come from somewhere they recognise. An address selects branding and never permission: the hostname is written by whoever makes the request, so authorisation always comes from the session, the portal token or the key.

Or we do it

BookKept is built and operated by COM Computing, so the integration can be a fixed piece of work done by the people who wrote the thing it plugs into, up to and including rebuilding the agency's website on the same system. How that works.