Integrations

Three 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 two of the three ways in cost no development at all.

Connect the system you already run

Under Connections, pick your provider, sign in there and authorise a read. We pull the placements that changed, the people on them and the companies they are with. Nothing is written back.

Which providers appear depends on the provider rather than on us, and the screen says so plainly before you click rather than after. The position today:

An authorised connection carries no posting secret. Two live ways into the same book, one of them sitting unused, is not a convenience.

A scheduled drop

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.

This is the route that covers the whole market, which is why it was built first. Every recruitment system can post a file on a schedule, including all the ones above that publish no API at all.

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. A provider connection lands in the same place: a connector renders what it read into the same shapes, so there is no automated path with its own looser rules.

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.

So we watch for it rather than leaving a date on a screen for somebody to notice. If a live connection goes quiet for materially longer than its own usual gap, everyone who can sign in gets one email saying so. Its own gap, not a schedule you have to declare: nightly, weekly and payroll-day feeds each have a rhythm, and the rule is drawn from the connection's own history. Once per silence, never once a day, because a daily reminder about the same dead feed is how people learn to filter the sender. A connection nobody has wired up yet is treated as unfinished rather than broken, and one you switched off is left alone.

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.

One thing a provider connection cannot tell you: whether a placement runs through an umbrella, a personal service company or your own payroll. No CRM in this market records it, because it is a compliance question rather than a sales one. It arrives as PAYE and you correct it, and the system will not guess, because guessing there decides the answer that the rest of the chain hangs off.

A key

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 gives every endpoint with its request and response body.

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.