API reference

Holiday

16 requests. Each shows the permission a key needs, what to send and what comes back.

On this page

Absence types (Holiday, Sickness, Unpaid leave, Other, and the company's own)

GET/v1/absence-types

Permission: absence.self
Module: holiday
Answers: 200

Response array of object

iduuidrequired
keystringrequiredcan be null
namestringrequired
paidbooleanrequired
usesAllowancebooleanrequired
archivedbooleanrequired

curl "https://app.workscope.co.uk/v1/absence-types" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "key": "example-slug",
    "name": "Harbourside Dental",
    "paid": false,
    "usesAllowance": false,
    "archived": false
  }
]

Add an absence type

POST/v1/absence-types

Permission: organization.update
Module: holiday
Answers: 201

Request body JSON

namestringrequired
1–200 characters
paidbooleanrequired
usesAllowancebooleanrequired

Response object

iduuidrequired
keystringrequiredcan be null
namestringrequired
paidbooleanrequired
usesAllowancebooleanrequired
archivedbooleanrequired

curl -X POST "https://app.workscope.co.uk/v1/absence-types" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "paid": false,
    "usesAllowance": false
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "key": "example-slug",
  "name": "Harbourside Dental",
  "paid": false,
  "usesAllowance": false,
  "archived": false
}

Change or archive an absence type

PATCH/v1/absence-types/{id}

Permission: organization.update
Module: holiday
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

namestringoptional
1–200 characters
paidbooleanoptional
usesAllowancebooleanoptional
archivedbooleanoptional

Response object

iduuidrequired
keystringrequiredcan be null
namestringrequired
paidbooleanrequired
usesAllowancebooleanrequired
archivedbooleanrequired

curl -X PATCH "https://app.workscope.co.uk/v1/absence-types/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "paid": false,
    "usesAllowance": false,
    "archived": false
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "key": "example-slug",
  "name": "Harbourside Dental",
  "paid": false,
  "usesAllowance": false,
  "archived": false
}

Absences between two dates (who's off), with filters

GET/v1/absences

Permission: absence.view
Module: holiday
Answers: 200

Parameters

Name	In	Kind
`from`	query	daterequired
`to`	query	daterequired
`status`	query	enum	One of `requested`, `approved`, `declined`, `cancelled`, `pending`
`teamMemberId`	query	uuid
`typeId`	query	uuid
`teamId`	query	uuid
`teamIds`	query	array of uuid

Response array of object

iduuidrequired
teamMemberIduuidrequired
teamMemberNamestringrequired
typeobjectrequired
- iduuidrequired
- namestringrequired
- paidbooleanrequired
- usesAllowancebooleanrequired
statusenumrequired
One of "requested", "approved", "declined", "cancelled"
startDatedaterequired
YYYY-MM-DD
endDatedaterequired
YYYY-MM-DD
partenumrequired
One of "full", "am", "pm", "hours"
minutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
secondsintegerrequired
-9007199254740991 to 9007199254740991
amountLabelstringrequired
notestringrequiredcan be null
declineReasonstringrequiredcan be null
cancelRequestedbooleanrequired
requestedByNamestringrequiredcan be null
decidedByNamestringrequiredcan be null
decidedAtstringrequiredcan be null
createdAtstringrequired

curl "https://app.workscope.co.uk/v1/absences?from=2026-11-06&to=2026-11-06" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "teamMemberId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "teamMemberName": "Sam Hart",
    "type": {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "name": "Harbourside Dental",
      "paid": false,
      "usesAllowance": false
    },
    "status": "requested",
    "startDate": "2026-11-06",
    "endDate": "2026-11-06",
    "part": "full",
    "minutes": 120,
    "seconds": 7200,
    "amountLabel": "text",
    "note": "Side gate code is on the key safe.",
    "declineReason": "text",
    "cancelRequested": false,
    "requestedByName": "Harbourside Dental",
    "decidedByName": "Harbourside Dental",
    "decidedAt": "2026-11-06T09:30:00.000Z",
    "createdAt": "2026-11-06T09:30:00.000Z"
  }
]

Add an absence for one or more people (approved, or as a request), deciding what happens to their bookings

POST/v1/absences

Permission: absence.manage
Module: holiday
Answers: 201

Request body JSON

typeIduuidrequired
startDatedaterequired
YYYY-MM-DD
endDatedaterequired
YYYY-MM-DD
partenumoptional
One of "full", "am", "pm", "hours" · Default "full"
minutesintegeroptional
1 to 527040
notestringoptionalcan be null
Up to 2000 characters
teamMemberIdsarray of uuidrequired
1–200 items
statusenumoptional
One of "approved", "requested" · Default "approved"
clashesarray of objectoptional
Up to 2000 items · Default []
- bookingIduuidrequired
- actionenumrequired
  One of "leave", "open", "reassign"
- teamMemberIduuidoptional

Response array of object

iduuidrequired
teamMemberIduuidrequired
teamMemberNamestringrequired
typeobjectrequired
- iduuidrequired
- namestringrequired
- paidbooleanrequired
- usesAllowancebooleanrequired
statusenumrequired
One of "requested", "approved", "declined", "cancelled"
startDatedaterequired
YYYY-MM-DD
endDatedaterequired
YYYY-MM-DD
partenumrequired
One of "full", "am", "pm", "hours"
minutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
secondsintegerrequired
-9007199254740991 to 9007199254740991
amountLabelstringrequired
notestringrequiredcan be null
declineReasonstringrequiredcan be null
cancelRequestedbooleanrequired
requestedByNamestringrequiredcan be null
decidedByNamestringrequiredcan be null
decidedAtstringrequiredcan be null
createdAtstringrequired

curl -X POST "https://app.workscope.co.uk/v1/absences" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "startDate": "2026-11-06",
    "endDate": "2026-11-06",
    "part": "full",
    "minutes": 120,
    "note": "Side gate code is on the key safe.",
    "teamMemberIds": [
      "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
    ],
    "status": "approved",
    "clashes": [
      {
        "bookingId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
        "action": "leave",
        "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41"
      }
    ]
  }'

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "teamMemberId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "teamMemberName": "Sam Hart",
    "type": {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "name": "Harbourside Dental",
      "paid": false,
      "usesAllowance": false
    },
    "status": "requested",
    "startDate": "2026-11-06",
    "endDate": "2026-11-06",
    "part": "full",
    "minutes": 120,
    "seconds": 7200,
    "amountLabel": "text",
    "note": "Side gate code is on the key safe.",
    "declineReason": "text",
    "cancelRequested": false,
    "requestedByName": "Harbourside Dental",
    "decidedByName": "Harbourside Dental",
    "decidedAt": "2026-11-06T09:30:00.000Z",
    "createdAt": "2026-11-06T09:30:00.000Z"
  }
]

One absence

GET/v1/absences/{id}

Permission: absence.view
Module: holiday
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

iduuidrequired
teamMemberIduuidrequired
teamMemberNamestringrequired
typeobjectrequired
- iduuidrequired
- namestringrequired
- paidbooleanrequired
- usesAllowancebooleanrequired
statusenumrequired
One of "requested", "approved", "declined", "cancelled"
startDatedaterequired
YYYY-MM-DD
endDatedaterequired
YYYY-MM-DD
partenumrequired
One of "full", "am", "pm", "hours"
minutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
secondsintegerrequired
-9007199254740991 to 9007199254740991
amountLabelstringrequired
notestringrequiredcan be null
declineReasonstringrequiredcan be null
cancelRequestedbooleanrequired
requestedByNamestringrequiredcan be null
decidedByNamestringrequiredcan be null
decidedAtstringrequiredcan be null
createdAtstringrequired

curl "https://app.workscope.co.uk/v1/absences/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "teamMemberId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "teamMemberName": "Sam Hart",
  "type": {
    "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
    "name": "Harbourside Dental",
    "paid": false,
    "usesAllowance": false
  },
  "status": "requested",
  "startDate": "2026-11-06",
  "endDate": "2026-11-06",
  "part": "full",
  "minutes": 120,
  "seconds": 7200,
  "amountLabel": "text",
  "note": "Side gate code is on the key safe.",
  "declineReason": "text",
  "cancelRequested": false,
  "requestedByName": "Harbourside Dental",
  "decidedByName": "Harbourside Dental",
  "decidedAt": "2026-11-06T09:30:00.000Z",
  "createdAt": "2026-11-06T09:30:00.000Z"
}

Change an absence (an approved one is taken back and put in again)

PATCH/v1/absences/{id}

Permission: absence.manage
Module: holiday
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

typeIduuidoptional
startDatedateoptional
YYYY-MM-DD
endDatedateoptional
YYYY-MM-DD
partenumoptional
One of "full", "am", "pm", "hours" · Default "full"
minutesintegeroptional
1 to 527040
notestringoptionalcan be null
Up to 2000 characters
clashesarray of objectoptional
Up to 2000 items
- bookingIduuidrequired
- actionenumrequired
  One of "leave", "open", "reassign"
- teamMemberIduuidoptional

Response object

iduuidrequired
teamMemberIduuidrequired
teamMemberNamestringrequired
typeobjectrequired
- iduuidrequired
- namestringrequired
- paidbooleanrequired
- usesAllowancebooleanrequired
statusenumrequired
One of "requested", "approved", "declined", "cancelled"
startDatedaterequired
YYYY-MM-DD
endDatedaterequired
YYYY-MM-DD
partenumrequired
One of "full", "am", "pm", "hours"
minutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
secondsintegerrequired
-9007199254740991 to 9007199254740991
amountLabelstringrequired
notestringrequiredcan be null
declineReasonstringrequiredcan be null
cancelRequestedbooleanrequired
requestedByNamestringrequiredcan be null
decidedByNamestringrequiredcan be null
decidedAtstringrequiredcan be null
createdAtstringrequired

curl -X PATCH "https://app.workscope.co.uk/v1/absences/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "startDate": "2026-11-06",
    "endDate": "2026-11-06",
    "part": "full",
    "minutes": 120,
    "note": "Side gate code is on the key safe.",
    "clashes": [
      {
        "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "action": "leave",
        "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918"
      }
    ]
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "teamMemberId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "teamMemberName": "Sam Hart",
  "type": {
    "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
    "name": "Harbourside Dental",
    "paid": false,
    "usesAllowance": false
  },
  "status": "requested",
  "startDate": "2026-11-06",
  "endDate": "2026-11-06",
  "part": "full",
  "minutes": 120,
  "seconds": 7200,
  "amountLabel": "text",
  "note": "Side gate code is on the key safe.",
  "declineReason": "text",
  "cancelRequested": false,
  "requestedByName": "Harbourside Dental",
  "decidedByName": "Harbourside Dental",
  "decidedAt": "2026-11-06T09:30:00.000Z",
  "createdAt": "2026-11-06T09:30:00.000Z"
}

Approve a request (or a request to cancel), deciding what happens to their bookings

POST/v1/absences/{id}/approve

Permission: absence.manage
Module: holiday
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

clashesarray of objectoptional
Up to 2000 items · Default []
- bookingIduuidrequired
- actionenumrequired
  One of "leave", "open", "reassign"
- teamMemberIduuidoptional

Response object

iduuidrequired
teamMemberIduuidrequired
teamMemberNamestringrequired
typeobjectrequired
- iduuidrequired
- namestringrequired
- paidbooleanrequired
- usesAllowancebooleanrequired
statusenumrequired
One of "requested", "approved", "declined", "cancelled"
startDatedaterequired
YYYY-MM-DD
endDatedaterequired
YYYY-MM-DD
partenumrequired
One of "full", "am", "pm", "hours"
minutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
secondsintegerrequired
-9007199254740991 to 9007199254740991
amountLabelstringrequired
notestringrequiredcan be null
declineReasonstringrequiredcan be null
cancelRequestedbooleanrequired
requestedByNamestringrequiredcan be null
decidedByNamestringrequiredcan be null
decidedAtstringrequiredcan be null
createdAtstringrequired

curl -X POST "https://app.workscope.co.uk/v1/absences/ID/approve" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "clashes": [
      {
        "bookingId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
        "action": "leave",
        "teamMemberId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
      }
    ]
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "teamMemberId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "teamMemberName": "Sam Hart",
  "type": {
    "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
    "name": "Harbourside Dental",
    "paid": false,
    "usesAllowance": false
  },
  "status": "requested",
  "startDate": "2026-11-06",
  "endDate": "2026-11-06",
  "part": "full",
  "minutes": 120,
  "seconds": 7200,
  "amountLabel": "text",
  "note": "Side gate code is on the key safe.",
  "declineReason": "text",
  "cancelRequested": false,
  "requestedByName": "Harbourside Dental",
  "decidedByName": "Harbourside Dental",
  "decidedAt": "2026-11-06T09:30:00.000Z",
  "createdAt": "2026-11-06T09:30:00.000Z"
}

Cancel an absence (its holiday goes back)

POST/v1/absences/{id}/cancel

Permission: absence.manage
Module: holiday
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

iduuidrequired
teamMemberIduuidrequired
teamMemberNamestringrequired
typeobjectrequired
- iduuidrequired
- namestringrequired
- paidbooleanrequired
- usesAllowancebooleanrequired
statusenumrequired
One of "requested", "approved", "declined", "cancelled"
startDatedaterequired
YYYY-MM-DD
endDatedaterequired
YYYY-MM-DD
partenumrequired
One of "full", "am", "pm", "hours"
minutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
secondsintegerrequired
-9007199254740991 to 9007199254740991
amountLabelstringrequired
notestringrequiredcan be null
declineReasonstringrequiredcan be null
cancelRequestedbooleanrequired
requestedByNamestringrequiredcan be null
decidedByNamestringrequiredcan be null
decidedAtstringrequiredcan be null
createdAtstringrequired

curl -X POST "https://app.workscope.co.uk/v1/absences/ID/cancel" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "teamMemberId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "teamMemberName": "Sam Hart",
  "type": {
    "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
    "name": "Harbourside Dental",
    "paid": false,
    "usesAllowance": false
  },
  "status": "requested",
  "startDate": "2026-11-06",
  "endDate": "2026-11-06",
  "part": "full",
  "minutes": 120,
  "seconds": 7200,
  "amountLabel": "text",
  "note": "Side gate code is on the key safe.",
  "declineReason": "text",
  "cancelRequested": false,
  "requestedByName": "Harbourside Dental",
  "decidedByName": "Harbourside Dental",
  "decidedAt": "2026-11-06T09:30:00.000Z",
  "createdAt": "2026-11-06T09:30:00.000Z"
}

Decline a request, saying why (or refuse a request to cancel)

POST/v1/absences/{id}/decline

Permission: absence.manage
Module: holiday
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

reasonstringrequired
1–1000 characters

Response object

iduuidrequired
teamMemberIduuidrequired
teamMemberNamestringrequired
typeobjectrequired
- iduuidrequired
- namestringrequired
- paidbooleanrequired
- usesAllowancebooleanrequired
statusenumrequired
One of "requested", "approved", "declined", "cancelled"
startDatedaterequired
YYYY-MM-DD
endDatedaterequired
YYYY-MM-DD
partenumrequired
One of "full", "am", "pm", "hours"
minutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
secondsintegerrequired
-9007199254740991 to 9007199254740991
amountLabelstringrequired
notestringrequiredcan be null
declineReasonstringrequiredcan be null
cancelRequestedbooleanrequired
requestedByNamestringrequiredcan be null
decidedByNamestringrequiredcan be null
decidedAtstringrequiredcan be null
createdAtstringrequired

curl -X POST "https://app.workscope.co.uk/v1/absences/ID/decline" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "text"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "teamMemberId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "teamMemberName": "Sam Hart",
  "type": {
    "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
    "name": "Harbourside Dental",
    "paid": false,
    "usesAllowance": false
  },
  "status": "requested",
  "startDate": "2026-11-06",
  "endDate": "2026-11-06",
  "part": "full",
  "minutes": 120,
  "seconds": 7200,
  "amountLabel": "text",
  "note": "Side gate code is on the key safe.",
  "declineReason": "text",
  "cancelRequested": false,
  "requestedByName": "Harbourside Dental",
  "decidedByName": "Harbourside Dental",
  "decidedAt": "2026-11-06T09:30:00.000Z",
  "createdAt": "2026-11-06T09:30:00.000Z"
}

Before saving: what an absence takes for each person, their balance before and after, and their bookings on those days

POST/v1/absences/preview

Permission: absence.manage
Module: holiday
Answers: 200

Request body JSON

typeIduuidrequired
startDatedaterequired
YYYY-MM-DD
endDatedaterequired
YYYY-MM-DD
partenumoptional
One of "full", "am", "pm", "hours" · Default "full"
minutesintegeroptional
1 to 527040
notestringoptionalcan be null
Up to 2000 characters
teamMemberIdsarray of uuidrequired
1–200 items
excludeAbsenceIduuidoptional

Response array of object

teamMemberIduuidrequired
namestringrequired
payBasisenumrequired
One of "hourly", "salaried"
secondsintegerrequired
-9007199254740991 to 9007199254740991
amountLabelstringrequired
needsMinutesbooleanrequired
suggestedMinutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
daysarray of objectrequired
- datedaterequired
  YYYY-MM-DD
- minutesintegerrequired
  -9007199254740991 to 9007199254740991
- fromenumrequired
  One of "booked", "average", "none"
averageDayMinutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
averageWeeksintegerrequired
-9007199254740991 to 9007199254740991
usesAllowancebooleanrequired
balanceBeforeSecondsintegerrequired
-9007199254740991 to 9007199254740991
balanceAfterSecondsintegerrequired
-9007199254740991 to 9007199254740991
balanceBeforeLabelstringrequired
balanceAfterLabelstringrequired
clashesarray of objectrequired
- bookingIduuidrequired
- datedaterequired
  YYYY-MM-DD
- namestringrequired
- clientNamestringrequired
- starttimerequiredcan be null
  HH:MM, 24-hour
- endtimerequiredcan be null
  HH:MM, 24-hour
- statusstringrequired

curl -X POST "https://app.workscope.co.uk/v1/absences/preview" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "startDate": "2026-11-06",
    "endDate": "2026-11-06",
    "part": "full",
    "minutes": 120,
    "note": "Side gate code is on the key safe.",
    "teamMemberIds": [
      "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
    ],
    "excludeAbsenceId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918"
  }'

Example response

[
  {
    "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "name": "Harbourside Dental",
    "payBasis": "hourly",
    "seconds": 7200,
    "amountLabel": "text",
    "needsMinutes": false,
    "suggestedMinutes": 120,
    "days": [
      {
        "date": "2026-11-06",
        "minutes": 120,
        "from": "booked"
      }
    ],
    "averageDayMinutes": 120,
    "averageWeeks": -9007199254740991,
    "usesAllowance": false,
    "balanceBeforeSeconds": 7200,
    "balanceAfterSeconds": 7200,
    "balanceBeforeLabel": "text",
    "balanceAfterLabel": "text",
    "clashes": [
      {
        "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "date": "2026-11-06",
        "name": "Harbourside Dental",
        "clientName": "Harbourside Dental",
        "start": "09:00",
        "end": "11:00",
        "status": "text"
      }
    ]
  }
]

Bank holidays between two dates in the company's region (and whether it works them)

GET/v1/bank-holidays

Permission: booking.viewAll or booking.viewOwn
Answers: 200

Parameters

Name	In	Kind
`from`	query	daterequired
`to`	query	daterequired

Response object

regionenumrequired
One of "england-and-wales", "scotland", "northern-ireland"
modeenumrequired
One of "work", "close_from_allowance", "close_on_top"
datesarray of objectrequired
- datedaterequired
  YYYY-MM-DD
- titlestringrequired

curl "https://app.workscope.co.uk/v1/bank-holidays?from=2026-11-06&to=2026-11-06" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "region": "england-and-wales",
  "mode": "work",
  "dates": [
    {
      "date": "2026-11-06",
      "title": "text"
    }
  ]
}

The company's holiday settings: accrual rate, holiday year, salaried allowance, bank holidays, carry-over

GET/v1/holiday/settings

Permission: absence.view
Module: holiday
Answers: 200

Response object

accrualRatePercentnumberrequired
holidayYearStartstringrequired
MM-DD
salariedAllowanceDaysnumberrequired
bankHolidayModeenumrequired
One of "work", "close_from_allowance", "close_on_top"
bankHolidayRegionenumrequired
One of "england-and-wales", "scotland", "northern-ireland"
carryOverMaxDaysnumberrequired
carryOverUseBystringrequiredcan be null
MM-DD
hourlyExpiryMonthsintegerrequiredcan be null
-9007199254740991 to 9007199254740991

curl "https://app.workscope.co.uk/v1/holiday/settings" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "accrualRatePercent": 1,
  "holidayYearStart": "04-01",
  "salariedAllowanceDays": 1,
  "bankHolidayMode": "work",
  "bankHolidayRegion": "england-and-wales",
  "carryOverMaxDays": 1,
  "carryOverUseBy": "04-01",
  "hourlyExpiryMonths": -9007199254740991
}

Change the holiday settings

PATCH/v1/holiday/settings

Permission: organization.update
Module: holiday
Answers: 200

Request body JSON

accrualRatePercentnumberoptional
0 to 50
holidayYearStartstringoptional
MM-DD
salariedAllowanceDaysnumberoptional
0 to 366
bankHolidayModeenumoptional
One of "work", "close_from_allowance", "close_on_top"
bankHolidayRegionenumoptional
One of "england-and-wales", "scotland", "northern-ireland"
carryOverMaxDaysnumberoptional
0 to 366
carryOverUseBystringoptionalcan be null
MM-DD
hourlyExpiryMonthsintegeroptionalcan be null
1 to 120

Response object

accrualRatePercentnumberrequired
holidayYearStartstringrequired
MM-DD
salariedAllowanceDaysnumberrequired
bankHolidayModeenumrequired
One of "work", "close_from_allowance", "close_on_top"
bankHolidayRegionenumrequired
One of "england-and-wales", "scotland", "northern-ireland"
carryOverMaxDaysnumberrequired
carryOverUseBystringrequiredcan be null
MM-DD
hourlyExpiryMonthsintegerrequiredcan be null
-9007199254740991 to 9007199254740991

curl -X PATCH "https://app.workscope.co.uk/v1/holiday/settings" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "accrualRatePercent": 0,
    "holidayYearStart": "04-01",
    "salariedAllowanceDays": 0,
    "bankHolidayMode": "work",
    "bankHolidayRegion": "england-and-wales",
    "carryOverMaxDays": 0,
    "carryOverUseBy": "04-01",
    "hourlyExpiryMonths": 1
  }'

Example response

{
  "accrualRatePercent": 1,
  "holidayYearStart": "04-01",
  "salariedAllowanceDays": 1,
  "bankHolidayMode": "work",
  "bankHolidayRegion": "england-and-wales",
  "carryOverMaxDays": 1,
  "carryOverUseBy": "04-01",
  "hourlyExpiryMonths": -9007199254740991
}

A team member's holiday balance, this holiday year, and the ledger

GET/v1/team-members/{id}/holiday

Permission: absence.view
Module: holiday
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

teamMemberIduuidrequired
payBasisenumrequired
One of "hourly", "salaried"
minutesPerDayintegerrequired
-9007199254740991 to 9007199254740991
balanceSecondsintegerrequired
-9007199254740991 to 9007199254740991
balanceLabelstringrequired
aheadSecondsintegerrequired
-9007199254740991 to 9007199254740991
todaySecondsintegerrequired
-9007199254740991 to 9007199254740991
todayLabelstringrequired
pendingSecondsintegerrequired
-9007199254740991 to 9007199254740991
yearobjectrequired
- startdaterequired
  YYYY-MM-DD
- enddaterequired
  YYYY-MM-DD
thisYearobjectrequired
- earnedSecondsintegerrequired
  -9007199254740991 to 9007199254740991
- takenSecondsintegerrequired
  -9007199254740991 to 9007199254740991
- allowanceSecondsintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- carryInSecondsintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- bankHolidaySecondsintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- adjustmentSecondsintegerrequired
  -9007199254740991 to 9007199254740991
- expiredSecondsintegerrequired
  -9007199254740991 to 9007199254740991
ledgerarray of objectrequired
- iduuidrequiredcan be null
- datedaterequired
  YYYY-MM-DD
- kindenumrequired
  One of "accrual", "absence", "adjustment", "allowance", "carry_over", "bank_holiday", "expired"
- secondsintegerrequired
  -9007199254740991 to 9007199254740991
- labelstringrequired
- notestringrequiredcan be null
- byNamestringrequiredcan be null
- createdAtstringrequiredcan be null
byTypearray of objectrequired
- typeIduuidrequired
- namestringrequired
- usesAllowancebooleanrequired
- countintegerrequired
  -9007199254740991 to 9007199254740991
- secondsintegerrequired
  -9007199254740991 to 9007199254740991
- labelstringrequired

curl "https://app.workscope.co.uk/v1/team-members/ID/holiday" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "payBasis": "hourly",
  "minutesPerDay": -9007199254740991,
  "balanceSeconds": 7200,
  "balanceLabel": "text",
  "aheadSeconds": 7200,
  "todaySeconds": 7200,
  "todayLabel": "text",
  "pendingSeconds": 7200,
  "year": {
    "start": "2026-11-06",
    "end": "2026-11-06"
  },
  "thisYear": {
    "earnedSeconds": 7200,
    "takenSeconds": 7200,
    "allowanceSeconds": 7200,
    "carryInSeconds": 7200,
    "bankHolidaySeconds": 7200,
    "adjustmentSeconds": 7200,
    "expiredSeconds": 7200
  },
  "ledger": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "kind": "accrual",
      "seconds": 7200,
      "label": "text",
      "note": "Side gate code is on the key safe.",
      "byName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "byType": [
    {
      "typeId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "name": "Harbourside Dental",
      "usesAllowance": false,
      "count": 3,
      "seconds": 7200,
      "label": "text"
    }
  ]
}

Add or take away holiday by hand, with a reason (a new ledger line)

POST/v1/team-members/{id}/holiday/adjustments

Permission: absence.manage
Module: holiday
Answers: 201

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

amountnumberrequired
unitenumrequired
One of "hours", "days"
datedateoptional
YYYY-MM-DD
reasonstringrequired
3–500 characters

Response object

teamMemberIduuidrequired
payBasisenumrequired
One of "hourly", "salaried"
minutesPerDayintegerrequired
-9007199254740991 to 9007199254740991
balanceSecondsintegerrequired
-9007199254740991 to 9007199254740991
balanceLabelstringrequired
aheadSecondsintegerrequired
-9007199254740991 to 9007199254740991
todaySecondsintegerrequired
-9007199254740991 to 9007199254740991
todayLabelstringrequired
pendingSecondsintegerrequired
-9007199254740991 to 9007199254740991
yearobjectrequired
- startdaterequired
  YYYY-MM-DD
- enddaterequired
  YYYY-MM-DD
thisYearobjectrequired
- earnedSecondsintegerrequired
  -9007199254740991 to 9007199254740991
- takenSecondsintegerrequired
  -9007199254740991 to 9007199254740991
- allowanceSecondsintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- carryInSecondsintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- bankHolidaySecondsintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- adjustmentSecondsintegerrequired
  -9007199254740991 to 9007199254740991
- expiredSecondsintegerrequired
  -9007199254740991 to 9007199254740991
ledgerarray of objectrequired
- iduuidrequiredcan be null
- datedaterequired
  YYYY-MM-DD
- kindenumrequired
  One of "accrual", "absence", "adjustment", "allowance", "carry_over", "bank_holiday", "expired"
- secondsintegerrequired
  -9007199254740991 to 9007199254740991
- labelstringrequired
- notestringrequiredcan be null
- byNamestringrequiredcan be null
- createdAtstringrequiredcan be null
byTypearray of objectrequired
- typeIduuidrequired
- namestringrequired
- usesAllowancebooleanrequired
- countintegerrequired
  -9007199254740991 to 9007199254740991
- secondsintegerrequired
  -9007199254740991 to 9007199254740991
- labelstringrequired

curl -X POST "https://app.workscope.co.uk/v1/team-members/ID/holiday/adjustments" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1,
    "unit": "hours",
    "date": "2026-11-06",
    "reason": "text"
  }'

Example response

{
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "payBasis": "hourly",
  "minutesPerDay": -9007199254740991,
  "balanceSeconds": 7200,
  "balanceLabel": "text",
  "aheadSeconds": 7200,
  "todaySeconds": 7200,
  "todayLabel": "text",
  "pendingSeconds": 7200,
  "year": {
    "start": "2026-11-06",
    "end": "2026-11-06"
  },
  "thisYear": {
    "earnedSeconds": 7200,
    "takenSeconds": 7200,
    "allowanceSeconds": 7200,
    "carryInSeconds": 7200,
    "bankHolidaySeconds": 7200,
    "adjustmentSeconds": 7200,
    "expiredSeconds": 7200
  },
  "ledger": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "kind": "accrual",
      "seconds": 7200,
      "label": "text",
      "note": "Side gate code is on the key safe.",
      "byName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "byType": [
    {
      "typeId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "name": "Harbourside Dental",
      "usesAllowance": false,
      "count": 3,
      "seconds": 7200,
      "label": "text"
    }
  ]
}