The recruitment week
Recruso is a week-driven system. Bookings, plans, timesheets, payroll and invoices are all reasoned about a week at a time, and every one of them belongs to exactly one week-ending date.
If you take one thing from this page: when handling a date from this API, the useful question is not “what day is this?” but “which week-ending date does this belong to?”
The week is the agency’s, not the calendar’s
Section titled “The week is the agency’s, not the calendar’s”There is no fixed definition of a week in Recruso. Each agency configures its own, and two agencies on the platform can disagree about which week a Tuesday belongs to.
Two fields on the agency record define it:
- The day the working week starts — Monday and Sunday are both common.
- The week-ending date of the agency’s first trading week — the anchor every subsequent week is counted from.
Together those two give an unambiguous grid of weeks. Read them from the agency rather than assuming: a client that hardcodes Monday–Sunday will silently mis-file every record for an agency that runs Sunday–Saturday, and the error will not show up until someone reconciles a payroll run.
Why alignment matters more than it looks
Section titled “Why alignment matters more than it looks”A week-ending date is not a display convenience. It is the key that groups work into the unit the financial side of the product acts on.
A worker’s bookings at a site within one week become a plan. Completing that plan snapshots the hours and rates that were agreed and produces both the payroll figures that pay the worker and the invoice figures that bill the client. Those values are legally authoritative once written and are never recalculated.
The practical consequence for an integration is that a record assigned to the wrong week is not a cosmetic error. It lands in the wrong pay run and the wrong invoice, and correcting it is a business process rather than an update.
Dates are UK local time
Section titled “Dates are UK local time”Week alignment is computed in UK local time — Europe/London, so GMT in winter and BST in summer. Business timestamps from this API are returned in UK local time and are not UTC.
Converting a UK-local timestamp as though it were UTC shifts it by an hour during British Summer Time, which is enough to move a late-evening or early-morning record across a week boundary. Do the week arithmetic in UK local time, then convert for display if you need to.
Authentication tokens are the exception: their lifetimes are UTC.
The other year boundaries
Section titled “The other year boundaries”The week is not the only cycle an agency configures, and none of them are safe to assume:
- The financial year start, and the tax year end.
- The holiday year start — which can also be set to run from each worker’s own start date instead of a single agency-wide date.
- Averaging windows, such as the number of trailing weeks used to calculate a worker’s average pay.
There is no platform-wide default behind any of these. Each is a value on the agency record, set during onboarding, and each is readable through the API.
Common misconceptions
Section titled “Common misconceptions”“A week runs Monday to Sunday.” Only if that agency configured it that way. Derive the grid from the agency’s own two fields.
“I can work out the week from the date alone.” Not without the anchor. The same calendar date belongs to different weeks for two agencies with different week-start days.
“Week-ending dates are just for reporting.” They are the grouping key for payroll and invoicing. Getting one wrong has financial consequences, not presentational ones.
What is published today
Section titled “What is published today”The agency configuration described here is readable through the API now. The entities that hang off the week — bookings, plans, timesheets, payroll and invoicing — are not yet part of the published surface. They are described in the domain model so the shape of the system makes sense, and will appear in the reference when they ship.
Agencies — the record these settings live on.