Identifiers, audit and timestamps
Three small things that produce a disproportionate number of integration bugs: what an id is, what an audit field tells you, and what time zone a timestamp is in.
Identifiers
Section titled “Identifiers”Every resource carries a numeric id named after itself — a branch has a branch id, a cost centre a cost centre id — and that is the value every other call refers to it by.
Treat ids as opaque. They are assigned by Recruso, they are not derived from anything you can predict, and their numeric width varies by resource. Store what you receive; do not narrow a value because a particular id happens to be small today, and do not construct one.
You only ever see ids from your own agency. An id obtained under different credentials will not
resolve — it returns a 404 rather than an error saying it belongs elsewhere, because the API never
discloses another tenant’s data. See Multi-tenancy.
Some resources are nested, and the parent id is part of the identity. Where a path carries more
than one id, both must line up: a real child id under the wrong parent is a 404, not a redirect to
the right one.
Audit fields
Section titled “Audit fields”Most resources carry some combination of created-by, created-on, modified-by and modified-on.
- The modified pair is null until the record is actually changed. A record that has never been edited since creation reports no modifier and no modification time — that is the normal state, not missing data. Fall back to the created pair.
- Writes stamp the user behind your API app. Your integration’s changes are attributed to the Recruso user the API app acts as, not to a generic system account, so they are indistinguishable in the audit trail from that person working in the UI.
- You never set these fields. They are stamped server-side; a value you send is not what gets stored.
- A user id does not resolve to a name through this API. There is no user directory on the integrator surface, so treat the value as a stable key for the person and look them up in the Recruso UI when you need to display one.
Timestamps
Section titled “Timestamps”Business timestamps are UK local time — Europe/London, GMT in winter and BST in summer. They are not UTC, and they carry no offset that would tell you so.
This is the single most expensive assumption to get wrong. Parsing a UK-local value as UTC shifts it by an hour for roughly half the year, which is enough to move a late-evening record into the previous day and, at a week boundary, into the previous week. See The recruitment week for why that matters more than it sounds.
Parse these values as local times in Europe/London. If your storage is UTC, convert on the way in and back on the way out — do not treat the wire value as already converted.
Authentication token lifetimes are the exception: those are UTC.
Common misconceptions
Section titled “Common misconceptions”“modifiedBy is null, so the record is broken.” It means nobody has changed the record since it
was created. Use the created fields instead.
“The ids are sequential, so I can guess the next one.” Do not rely on it. Ids come from the server; a guessed id that happens to exist in another agency returns a 404 anyway.
“Timestamps are ISO 8601, therefore UTC.” The format is ISO 8601. The zone is UK local, and no offset is attached. Those are separate facts.
The recruitment week — why an hour’s drift can land a record in the wrong pay run.