Skip to content
Recruso API

Record a day of a worker's availability

POST
/v1/workers/{workerId}/availability
curl --request POST \
  --url https://api2.recruso.co.uk/v1/workers/1/availability \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "date": "2026-11-03", "startTime": "07:00:00", "finishTime": "19:00:00", "availabilityStatusId": 3 }'

Records a day a worker in your own agency is, or is not, available: a date, one of your agency’s availability statuses and, optionally, a start and a finish time. Either time may be sent alone, and a finish earlier than the start passes midnight.

The date must be no more than 20 days before today and no more than a year after it, in the UK. A worker holds one entry a date, or two when your agency allows more than one status a day; a date already full returns 400. A status that affects a worker’s AWR parity cannot be recorded through this API, and one that is not your agency’s returns 400.

doNotAccrue is set from your agency’s holiday accrual setting for the worker’s type, for limited-company and PSC workers only, and kept as it was even if the setting changes later. If your agency’s settings hold two entries for that type, the request returns 400 until they are corrected in Recruso CRM.

A worker in another agency, under a branch the Recruso user behind your API app cannot reach, or deleted under data-protection law returns 404 rather than 403, so their existence is never disclosed.

Access. Requires a client-credentials access token. Tokens issued through the interactive user login are rejected.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
workerId
required
integer format: int32

The workerId path parameter

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

A day to record for a worker. The worker comes from the route. doNotAccrue cannot be sent: it is your agency’s setting for the worker’s type when the entry is created.

object
date

The day the entry is for, in the UK. Required. No more than 20 days before today and no more than a year after it.

string format: date
nullable
Example
2026-11-03
startTime

When the worker becomes available or unavailable that day, as a time of day, kept to the nearest minute. Optional, and independent of finishTime.

string format: time
nullable
Example
07:00:00
finishTime

When it ends, as a time of day, kept to the nearest minute. Optional. A finish earlier than the start means the entry passes midnight.

string format: time
nullable
Example
19:00:00
availabilityStatusId

One of your agency’s availability statuses. Required. A status that affects a worker’s AWR parity cannot be used here.

integer format: int16
nullable
Example
3

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json

The entry as recorded.

object
availabilityId

The entry’s identifier.

integer format: int32
workerId

The worker the entry belongs to.

integer format: int32
date

The day the entry is for, in the UK.

string format: date
startTime

When the worker becomes available or unavailable that day, as a time of day; null when not set.

string format: time
nullable
finishTime

When it ends, as a time of day; null when not set. Earlier than startTime means the entry passes midnight.

string format: time
nullable
availabilityStatusId

The status, as an id from your agency’s availability statuses.

integer format: int16
doNotAccrue

Read only. Whether the day stops holiday accrual for the worker: your agency’s setting for the worker’s type when the entry was created, kept as it was then. Null means the entry carries no accrual instruction, which is always so for workers other than limited-company and PSC types.

boolean
nullable
createdOn

When the entry was created, in UK local time; null for entries that predate the column.

string format: date-time
nullable
modifiedOn

When the entry was last changed, in UK local time; null when it never has been.

string format: date-time
nullable
Example
{
  "availabilityId": 51207,
  "workerId": 4821,
  "date": "2026-11-03",
  "startTime": "07:00:00",
  "finishTime": "19:00:00",
  "availabilityStatusId": 3,
  "doNotAccrue": false,
  "createdOn": "2026-10-20T09:14:52",
  "modifiedOn": "2026-10-21T16:02:10"
}

400

Section titled “400”

Bad Request

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

401

Section titled “401”

Unauthorized

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

403

Section titled “403”

Forbidden

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

404

Section titled “404”

Not Found

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}