Skip to content
Recruso API

List a worker's availability

GET
/v1/workers/{workerId}/availability
curl --request GET \
  --url 'https://api2.recruso.co.uk/v1/workers/1/availability?from=2026-11-02&to=2026-11-15' \
  --header 'Authorization: <Authorization>'

Returns the days a worker in your own agency is, or is not, available between from and to, both inclusive. Each entry has a date, one of your agency’s availability statuses and, optionally, a start and a finish time. A day with no entry is a day the worker is available.

Both from and to are required, and the range may cover no more days than your agency shows at once in Recruso CRM, counting both ends: at most 30. A range that is missing, reversed or wider returns 400. The list is not paged.

Entries are ordered by date, then by start time, those with none first. A worker may hold two entries on one date when your agency allows it.

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

Query Parameters

Section titled “Query Parameters”
from
required

The first day, in the UK. Required.

string format: date
nullable
Example
2026-11-02

The first day, in the UK. Required.

to
required

The last day, in the UK. Required, not before from, and no more than your agency’s availability range after it, counting both ends: at most 30 days.

string format: date
nullable
Example
2026-11-15

The last day, in the UK. Required, not before from, and no more than your agency’s availability range after it, counting both ends: at most 30 days.

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

A worker’s availability over a range of days.

object
workerId

The worker the entries belong to.

integer format: int32
from

The first day listed, as requested.

string format: date
to

The last day listed, as requested.

string format: date
entries

The entries in the range, by date, then by start time with entries that have none first. A day with no entry has no element: the worker is available.

Array<object>

One day a worker is, or is not, available.

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
{
  "workerId": 4821,
  "from": "2026-11-02",
  "to": "2026-11-15",
  "entries": [
    {
      "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"
}