API reference
Shift rotas
Rotas per location or team: drafts filled from work schedules, another week or a template week; shifts placed, moved and checked against the working-time rules of PT, ES, DE and the EU Directive floor, each finding citing its article; suggestions for open shifts; history and prints (rota, mapa de horário, cuadrante). Publishing and approving requests are in the app (never API keys).
36 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List rotas#
POST/v1/shifts/rotas.listRead
The rotas you can see: owners, admins and HR all of them; a rota's editors theirs (access edit); viewers, the people on a rota and their managers the published ones (access read). Archived rotas only with archived true.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_rotas_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
archivedboolean
Returns
itemsobject[]required16 fields
idstringrequirednamestringrequiredkind"location" | "team"requiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
timezonestringrequiredcountrystring | nullrequiredmembersintegerrequiredPeople on the rota today.
extra_membersobject[]requiredBorrowed staff (editors only; empty for others).
2 fields
idstringrequirednamestringrequired
editors_mode"default" | "custom"requireddefault: the team's leads up the tree (team rotas), HR only (location rotas).
editorsobject[]requiredWho besides owners, admins and HR plans and publishes it.
2 fields
idstringrequirednamestringrequired
opening_hoursstring | nullrequiredarchivedbooleanrequiredaccess"edit" | "read"requirededit: you plan it (drafts, publish, requests); read: you see what is published.
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/rotas.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"archived":true}'const res = await fetch('https://api.bizisy.com/v1/shifts/rotas.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"archived": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/rotas.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "r1",
"name": "Kitchen",
"kind": "team",
"location": null,
"unit": {
"id": "u1",
"name": "Kitchen"
},
"timezone": "Europe/Lisbon",
"country": "PT",
"members": 3,
"extra_members": [],
"editors_mode": "default",
"editors": [
{
"id": "p2",
"name": "Bea Lima"
}
],
"opening_hours": "Mon–Sat 09:00–20:00",
"archived": false,
"access": "edit",
"created_at": "2026-11-10T10:00:00.000Z",
"updated_at": "2026-11-10T10:00:00.000Z"
},
{
"id": "r2",
"name": "Lisbon shop",
"kind": "location",
"location": {
"id": "l1",
"name": "Lisbon shop"
},
"unit": null,
"timezone": "Europe/Lisbon",
"country": "PT",
"members": 3,
"extra_members": [],
"editors_mode": "default",
"editors": [],
"opening_hours": "Mon–Sat 09:00–20:00",
"archived": false,
"access": "read",
"created_at": "2026-11-10T10:00:00.000Z",
"updated_at": "2026-11-10T10:00:00.000Z"
}
]
}
}Get a rota#
POST/v1/shifts/rotas.getRead
One rota: its location or team, time zone and country (whose rules apply), how many people are on it, its editors, and your access. The people on it: shifts_week_get.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_rotas_geton My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
rota_idstringrequired1–100 characters.
Returns
17 fields
idstringrequirednamestringrequiredkind"location" | "team"requiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
timezonestringrequiredcountrystring | nullrequiredmembersintegerrequiredPeople on the rota today.
extra_membersobject[]requiredBorrowed staff (editors only; empty for others).
2 fields
idstringrequirednamestringrequired
editors_mode"default" | "custom"requireddefault: the team's leads up the tree (team rotas), HR only (location rotas).
editorsobject[]requiredWho besides owners, admins and HR plans and publishes it.
2 fields
idstringrequirednamestringrequired
opening_hoursstring | nullrequiredarchivedbooleanrequiredaccess"edit" | "read"requirededit: you plan it (drafts, publish, requests); read: you see what is published.
created_atstringrequiredupdated_atstringrequiredpeopleobject[]requiredEveryone on the rota today (editors only; empty for others).
2 fields
idstringrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/rotas.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rota_id":"r1"}'const res = await fetch('https://api.bizisy.com/v1/shifts/rotas.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"rota_id": "r1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/rotas.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"rota_id": "r1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "r1",
"name": "Kitchen",
"kind": "team",
"location": null,
"unit": {
"id": "u1",
"name": "Kitchen"
},
"timezone": "Europe/Lisbon",
"country": "PT",
"members": 3,
"extra_members": [],
"editors_mode": "default",
"editors": [
{
"id": "p2",
"name": "Bea Lima"
}
],
"opening_hours": "Mon–Sat 09:00–20:00",
"archived": false,
"access": "edit",
"created_at": "2026-11-10T10:00:00.000Z",
"updated_at": "2026-11-10T10:00:00.000Z",
"people": [
{
"id": "p3",
"name": "Carl Reis"
},
{
"id": "p2",
"name": "Bea Lima"
}
]
}
}Create a rota#
POST/v1/shifts/rotas.createWrite
Creates a rota for one location (location_id: everyone working there) or one team (unit_id: the team and its sub-teams), named after it unless name is given. Team rotas are planned by the team's leads up the tree by default; location rotas by owners, admins and HR until HR adds editors (shifts_rotas_editors_set). At most 200 a company. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
shifts_rotas_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
location_idstring1–100 characters.
unit_idstring1–100 characters.
namestring1–80 characters.
extra_member_idsstring[]Borrowed staff, beyond the location's or team's people (the whole list).
1–100 characters. Up to 200 items.
opening_hoursstring | nullThe opening hours line for the printed rota and the PT mapa de horário, e.g. "Mon–Sat 09:00–20:00".
Up to 200 characters.
Returns
16 fields
idstringrequirednamestringrequiredkind"location" | "team"requiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
timezonestringrequiredcountrystring | nullrequiredmembersintegerrequiredPeople on the rota today.
extra_membersobject[]requiredBorrowed staff (editors only; empty for others).
2 fields
idstringrequirednamestringrequired
editors_mode"default" | "custom"requireddefault: the team's leads up the tree (team rotas), HR only (location rotas).
editorsobject[]requiredWho besides owners, admins and HR plans and publishes it.
2 fields
idstringrequirednamestringrequired
opening_hoursstring | nullrequiredarchivedbooleanrequiredaccess"edit" | "read"requirededit: you plan it (drafts, publish, requests); read: you see what is published.
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/rotas.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"location_id": "l1",
"name": "Lisbon shop",
"extra_member_ids": [
"p9"
],
"opening_hours": "Mon–Sat 09:00–20:00"
}'const res = await fetch('https://api.bizisy.com/v1/shifts/rotas.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"location_id": "l1",
"name": "Lisbon shop",
"extra_member_ids": [
"p9"
],
"opening_hours": "Mon–Sat 09:00–20:00"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/rotas.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"location_id": "l1",
"name": "Lisbon shop",
"extra_member_ids": [
"p9",
],
"opening_hours": "Mon–Sat 09:00–20:00",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "r1",
"name": "Lisbon shop",
"kind": "team",
"location": null,
"unit": {
"id": "u1",
"name": "Kitchen"
},
"timezone": "Europe/Lisbon",
"country": "PT",
"members": 3,
"extra_members": [],
"editors_mode": "default",
"editors": [
{
"id": "p2",
"name": "Bea Lima"
}
],
"opening_hours": "Mon–Sat 09:00–20:00",
"archived": false,
"access": "edit",
"created_at": "2026-11-10T10:00:00.000Z",
"updated_at": "2026-11-10T10:00:00.000Z"
}
}Change a rota#
POST/v1/shifts/rotas.updateWrite
Renames a rota, sets its borrowed staff (extra_member_ids, the whole list) or its opening hours line. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
shifts_rotas_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
rota_idstringrequired1–100 characters.
namestring1–80 characters.
extra_member_idsstring[]Borrowed staff, beyond the location's or team's people (the whole list).
1–100 characters. Up to 200 items.
opening_hoursstring | nullThe opening hours line for the printed rota and the PT mapa de horário, e.g. "Mon–Sat 09:00–20:00".
Up to 200 characters.
Returns
16 fields
idstringrequirednamestringrequiredkind"location" | "team"requiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
timezonestringrequiredcountrystring | nullrequiredmembersintegerrequiredPeople on the rota today.
extra_membersobject[]requiredBorrowed staff (editors only; empty for others).
2 fields
idstringrequirednamestringrequired
editors_mode"default" | "custom"requireddefault: the team's leads up the tree (team rotas), HR only (location rotas).
editorsobject[]requiredWho besides owners, admins and HR plans and publishes it.
2 fields
idstringrequirednamestringrequired
opening_hoursstring | nullrequiredarchivedbooleanrequiredaccess"edit" | "read"requirededit: you plan it (drafts, publish, requests); read: you see what is published.
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/rotas.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"rota_id":"r1","extra_member_ids":[],"opening_hours":null}'const res = await fetch('https://api.bizisy.com/v1/shifts/rotas.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"extra_member_ids": [],
"opening_hours": null
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/rotas.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"extra_member_ids": [],
"opening_hours": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "r1",
"name": "Kitchen",
"kind": "team",
"location": null,
"unit": {
"id": "u1",
"name": "Kitchen"
},
"timezone": "Europe/Lisbon",
"country": "PT",
"members": 3,
"extra_members": [],
"editors_mode": "default",
"editors": [
{
"id": "p2",
"name": "Bea Lima"
}
],
"opening_hours": null,
"archived": false,
"access": "edit",
"created_at": "2026-11-10T10:00:00.000Z",
"updated_at": "2026-11-10T10:00:00.000Z"
}
}Archive a rota#
POST/v1/shifts/rotas.archiveWrite
Archives a rota (archived false brings it back). Its published weeks and history are kept and stay readable; nothing new is planned on it, and its open requests are cancelled. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
shifts_rotas_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
rota_idstringrequired1–100 characters.
archivedbooleanDefault
true.
Returns
16 fields
idstringrequirednamestringrequiredkind"location" | "team"requiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
timezonestringrequiredcountrystring | nullrequiredmembersintegerrequiredPeople on the rota today.
extra_membersobject[]requiredBorrowed staff (editors only; empty for others).
2 fields
idstringrequirednamestringrequired
editors_mode"default" | "custom"requireddefault: the team's leads up the tree (team rotas), HR only (location rotas).
editorsobject[]requiredWho besides owners, admins and HR plans and publishes it.
2 fields
idstringrequirednamestringrequired
opening_hoursstring | nullrequiredarchivedbooleanrequiredaccess"edit" | "read"requirededit: you plan it (drafts, publish, requests); read: you see what is published.
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/rotas.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"rota_id":"r1","archived":false}'const res = await fetch('https://api.bizisy.com/v1/shifts/rotas.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"archived": false
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/rotas.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"archived": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "r1",
"name": "Kitchen",
"kind": "team",
"location": null,
"unit": {
"id": "u1",
"name": "Kitchen"
},
"timezone": "Europe/Lisbon",
"country": "PT",
"members": 3,
"extra_members": [],
"editors_mode": "default",
"editors": [
{
"id": "p2",
"name": "Bea Lima"
}
],
"opening_hours": "Mon–Sat 09:00–20:00",
"archived": false,
"access": "edit",
"created_at": "2026-11-10T10:00:00.000Z",
"updated_at": "2026-11-10T10:00:00.000Z"
}
}Choose a rota's editors#
POST/v1/shifts/rotas.editors.setWrite
Who plans and publishes a rota besides owners, admins and HR: person_ids (people of the company with a login, at most 20), or mode default (team rotas: the team's leads up the tree; location rotas: HR only). Editors see drafts, publish, approve swaps and claims and print the rota. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
shifts_rotas_editors_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
rota_idstringrequired1–100 characters.
mode"default" | "custom"Default
"custom".person_idsstring[]1–100 characters. Up to 20 items.
Returns
16 fields
idstringrequirednamestringrequiredkind"location" | "team"requiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
timezonestringrequiredcountrystring | nullrequiredmembersintegerrequiredPeople on the rota today.
extra_membersobject[]requiredBorrowed staff (editors only; empty for others).
2 fields
idstringrequirednamestringrequired
editors_mode"default" | "custom"requireddefault: the team's leads up the tree (team rotas), HR only (location rotas).
editorsobject[]requiredWho besides owners, admins and HR plans and publishes it.
2 fields
idstringrequirednamestringrequired
opening_hoursstring | nullrequiredarchivedbooleanrequiredaccess"edit" | "read"requirededit: you plan it (drafts, publish, requests); read: you see what is published.
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/rotas.editors.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"rota_id":"r1","person_ids":["p2"]}'const res = await fetch('https://api.bizisy.com/v1/shifts/rotas.editors.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"person_ids": [
"p2"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/rotas.editors.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"person_ids": [
"p2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "r1",
"name": "Kitchen",
"kind": "team",
"location": null,
"unit": {
"id": "u1",
"name": "Kitchen"
},
"timezone": "Europe/Lisbon",
"country": "PT",
"members": 3,
"extra_members": [],
"editors_mode": "custom",
"editors": [
{
"id": "p2",
"name": "Bea Lima"
}
],
"opening_hours": "Mon–Sat 09:00–20:00",
"archived": false,
"access": "edit",
"created_at": "2026-11-10T10:00:00.000Z",
"updated_at": "2026-11-10T10:00:00.000Z"
}
}List positions#
POST/v1/shifts/positions.listRead
The company's positions (Kitchen, Till, Nurse): what a shift is for and what a person can work. Everyone with access to shifts.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_positions_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
archivedboolean
Returns
itemsobject[]required5 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.archivedbooleanrequiredpeopleintegerrequiredPeople tagged for it.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/positions.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"archived":true}'const res = await fetch('https://api.bizisy.com/v1/shifts/positions.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"archived": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/positions.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "pos1",
"name": "Till",
"color": "amber",
"archived": false,
"people": 4
}
]
}
}Create a position#
POST/v1/shifts/positions.createWrite
Adds a position (name, color). At most 100. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
shifts_positions_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–80 characters.
colorstring (enum)One of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo. Default"teal".
Returns
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.archivedbooleanrequiredpeopleintegerrequiredPeople tagged for it.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/positions.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Kitchen","color":"rose"}'const res = await fetch('https://api.bizisy.com/v1/shifts/positions.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Kitchen",
"color": "rose"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/positions.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Kitchen",
"color": "rose",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "pos1",
"name": "Kitchen",
"color": "rose",
"archived": false,
"people": 0
}
}Change a position#
POST/v1/shifts/positions.updateWrite
Renames, recolours or archives a position (archived: shifts keep it; nobody new is tagged). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
shifts_positions_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
position_idstringrequired1–100 characters.
namestring1–80 characters.
colorstring (enum)One of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.archivedboolean
Returns
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.archivedbooleanrequiredpeopleintegerrequiredPeople tagged for it.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/positions.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"position_id":"pos1","name":"Till 1","color":"amber","archived":false}'const res = await fetch('https://api.bizisy.com/v1/shifts/positions.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"position_id": "pos1",
"name": "Till 1",
"color": "amber",
"archived": false
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/positions.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"position_id": "pos1",
"name": "Till 1",
"color": "amber",
"archived": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "pos1",
"name": "Till 1",
"color": "amber",
"archived": false,
"people": 4
}
}Set the positions a person can work#
POST/v1/shifts/positions.assignWrite
Sets the positions a person can work (position_ids, the whole list). A shift for a position the person isn't tagged with is a warning, never a block. Owners, admins and HR, and the editors of a rota the person is on.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_positions_assignon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idstringrequired1–100 characters.
position_idsstring[]required1–100 characters. Up to 100 items.
Returns
personobjectrequired2 fields
idstringrequirednamestringrequired
position_idsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/positions.assign \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p3","position_ids":["pos1"]}'const res = await fetch('https://api.bizisy.com/v1/shifts/positions.assign', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p3",
"position_ids": [
"pos1"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/positions.assign",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p3",
"position_ids": [
"pos1",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p3",
"name": "Carl Reis"
},
"position_ids": [
"pos1"
]
}
}List shift templates#
POST/v1/shifts/templates.listRead
The company's shift templates ("Morning 07:00–15:00, 30 min break"): pick one to place a shift in one tap.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_templates_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
archivedboolean
Returns
itemsobject[]required8 fields
idstringrequirednamestringrequiredstartstringrequiredendstringrequiredbreak_minutesintegerrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.position_idstring | nullrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/templates.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"archived":true}'const res = await fetch('https://api.bizisy.com/v1/shifts/templates.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"archived": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/templates.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "t1",
"name": "Morning",
"start": "07:00",
"end": "15:00",
"break_minutes": 30,
"color": "teal",
"position_id": null,
"archived": false
}
]
}
}Create a shift template#
POST/v1/shifts/templates.createWrite
Adds a shift template: name, start, end (HH:MM; at or before start ends the next day), break_minutes, color, position_id. At most 100. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
shifts_templates_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–80 characters.
startstringrequiredPattern
^([01]\d|2[0-3]):[0-5]\d$.endstringrequiredAt or before start: ends the next day.
Pattern
^([01]\d|2[0-3]):[0-5]\d$.break_minutesintegerFrom 0 to 240. Default
0.colorstring (enum)One of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo. Default"teal".position_idstring | null1–100 characters.
Returns
8 fields
idstringrequirednamestringrequiredstartstringrequiredendstringrequiredbreak_minutesintegerrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.position_idstring | nullrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/templates.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Night",
"start": "22:00",
"end": "06:00",
"break_minutes": 30,
"color": "indigo",
"position_id": null
}'const res = await fetch('https://api.bizisy.com/v1/shifts/templates.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Night",
"start": "22:00",
"end": "06:00",
"break_minutes": 30,
"color": "indigo",
"position_id": null
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/templates.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Night",
"start": "22:00",
"end": "06:00",
"break_minutes": 30,
"color": "indigo",
"position_id": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "t1",
"name": "Night",
"start": "22:00",
"end": "06:00",
"break_minutes": 30,
"color": "indigo",
"position_id": null,
"archived": false
}
}Change a shift template#
POST/v1/shifts/templates.updateWrite
Changes a shift template (shifts already placed keep their times) or archives it. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
shifts_templates_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequired1–100 characters.
namestring1–80 characters.
startstringPattern
^([01]\d|2[0-3]):[0-5]\d$.endstringPattern
^([01]\d|2[0-3]):[0-5]\d$.break_minutesintegerFrom 0 to 240.
colorstring (enum)One of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.position_idstring | null1–100 characters.
archivedboolean
Returns
8 fields
idstringrequirednamestringrequiredstartstringrequiredendstringrequiredbreak_minutesintegerrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.position_idstring | nullrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/templates.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_id":"t1","archived":true,"position_id":"pos1"}'const res = await fetch('https://api.bizisy.com/v1/shifts/templates.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "t1",
"archived": true,
"position_id": "pos1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/templates.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "t1",
"archived": True,
"position_id": "pos1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "t1",
"name": "Morning",
"start": "07:00",
"end": "15:00",
"break_minutes": 30,
"color": "teal",
"position_id": null,
"archived": true
}
}List template weeks#
POST/v1/shifts/template_weeks.listRead
Saved weeks to apply to a rota (shifts by weekday, with their person or open). Editors and HR (a rota's own, and the company's).
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_template_weeks_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
rota_idstring1–100 characters.
Returns
itemsobject[]required5 fields
idstringrequirednamestringrequiredrota_idstring | nullrequiredshiftsobject[]required6 fields
weekdayintegerrequiredstartstringrequiredendstringrequiredbreak_minutesintegerrequiredposition_idstring | nullrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
created_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/template_weeks.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rota_id":"r1"}'const res = await fetch('https://api.bizisy.com/v1/shifts/template_weeks.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"rota_id": "r1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/template_weeks.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"rota_id": "r1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "tw1",
"name": "Normal week",
"rota_id": "r1",
"shifts": [
{
"weekday": 1,
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"position_id": "pos1",
"person": {
"id": "p3",
"name": "Carl Reis"
}
},
{
"weekday": 2,
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"position_id": null,
"person": null
}
],
"created_at": "2026-11-10T10:00:00.000Z"
}
]
}
}Save a week as a template#
POST/v1/shifts/template_weeks.createWrite
Saves a rota week's draft as a template week (name; keep_people false makes every shift open). Apply it with shifts_week_fill mode template. At most 50. The rota's editors and HR.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_template_weeks_createon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
rota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.namestringrequired1–80 characters.
keep_peoplebooleanDefault
true.
Returns
idstringrequirednamestringrequiredrota_idstring | nullrequiredshiftsobject[]required6 fields
weekdayintegerrequiredstartstringrequiredendstringrequiredbreak_minutesintegerrequiredposition_idstring | nullrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
created_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/template_weeks.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rota_id": "r1",
"week": "2026-W47",
"name": "Open week",
"keep_people": false
}'const res = await fetch('https://api.bizisy.com/v1/shifts/template_weeks.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W47",
"name": "Open week",
"keep_people": false
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/template_weeks.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"week": "2026-W47",
"name": "Open week",
"keep_people": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tw1",
"name": "Open week",
"rota_id": "r1",
"shifts": [
{
"weekday": 1,
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"position_id": "pos1",
"person": {
"id": "p3",
"name": "Carl Reis"
}
},
{
"weekday": 2,
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"position_id": null,
"person": null
}
],
"created_at": "2026-11-10T10:00:00.000Z"
}
}Delete a template week#
POST/v1/shifts/template_weeks.deleteDestructive
Deletes a template week (weeks it filled keep their shifts). The rota's editors and HR.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_template_weeks_deleteon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_week_idstringrequired1–100 characters.
Returns
idstringrequireddeletedtruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/template_weeks.delete \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_week_id":"tw1"}'const res = await fetch('https://api.bizisy.com/v1/shifts/template_weeks.delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_week_id": "tw1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/template_weeks.delete",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_week_id": "tw1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tw1",
"deleted": true
}
}Read a rota week#
POST/v1/shifts/week.getRead
A rota week as the grid shows it: the days, the people (planned and contract hours; editors also see leave as "Away", holidays and when people said they can't work), the shifts (editors: the draft; others: what is published), the law findings and the changes not published yet (editors), and the day to publish by. week: ISO week (2026-W47); default this week.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_week_geton My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
rota_idstringrequired1–100 characters.
weekstringPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.
Returns
13 fields
rotaobjectrequired16 fields
idstringrequirednamestringrequiredkind"location" | "team"requiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
timezonestringrequiredcountrystring | nullrequiredmembersintegerrequiredPeople on the rota today.
extra_membersobject[]requiredBorrowed staff (editors only; empty for others).
2 fields
idstringrequirednamestringrequired
editors_mode"default" | "custom"requireddefault: the team's leads up the tree (team rotas), HR only (location rotas).
editorsobject[]requiredWho besides owners, admins and HR plans and publishes it.
2 fields
idstringrequirednamestringrequired
opening_hoursstring | nullrequiredarchivedbooleanrequiredaccess"edit" | "read"requirededit: you plan it (drafts, publish, requests); read: you see what is published.
created_atstringrequiredupdated_atstringrequired
weekstringrequiredstartstringrequireddaysobject[]required2 fields
datestringrequiredweekdayintegerrequired
access"edit" | "read"requiredstatusobjectrequired4 fields
versionintegerrequired0: never published.
published_atstring | nullrequiredpublished_byobject | nullrequired2 fields
idstringrequirednamestringrequired
changesintegerrequiredDraft changes not published yet (editors; 0 for others).
peopleobject[]required6 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
planned_minutesintegerrequiredcontract_minutesinteger | nullrequiredWhat the work schedule expects this week (editors only).
position_idsstring[]requiredPositions they can work (editors only).
daysobject[]requiredEditors only (empty for others).
3 fields
datestringrequiredaway"full" | "am" | "pm" | "hours"requiredApproved time off ("Away"; never its type).
holidaystring | nullrequired
availabilityobject[]requiredWhen they said they can't work (editors only; notes stay private).
4 fields
weekdayinteger | nullrequireddatestring | nullrequiredfromstring | nullrequiredtostring | nullrequired
shiftsobject[]requiredEditors: the draft; others: what is published.
10 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredLocal time; at or before start: the shift ends the next day.
break_minutesintegerrequiredminutesintegerrequiredPlanned work: the shift minus its break.
personobject | nullrequirednull: an open shift.
2 fields
idstringrequirednamestringrequired
positionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
notestring | nullrequiredEditors and the shift's person; null for others.
template_idstring | nullrequired
findingsobject[]requiredLaw checks on the draft (editors only).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
changesobject[]requiredWhat publishing would change (editors only).
7 fields
shift_idstringrequireddatestringrequiredkind"added" | "removed" | "changed"requiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
beforeobject | nullrequired3 fields
startstringrequiredendstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
afterobject | nullrequired3 fields
startstringrequiredendstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
inside_noticebooleanrequiredThe shift (before or after) starts inside the notice window: publishing records a reason.
publish_bystring | nullrequiredThe day to publish by so the week goes out with the notice (week start minus notice days; editors only).
notice_daysinteger | nullrequirednotice_source"law" | "company"required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/week.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rota_id":"r1","week":"2026-W47"}'const res = await fetch('https://api.bizisy.com/v1/shifts/week.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W47"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/week.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"rota_id": "r1",
"week": "2026-W47",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"rota": {
"id": "r1",
"name": "Kitchen",
"kind": "team",
"location": null,
"unit": {
"id": "u1",
"name": "Kitchen"
},
"timezone": "Europe/Lisbon",
"country": "PT",
"members": 3,
"extra_members": [],
"editors_mode": "default",
"editors": [
{
"id": "p2",
"name": "Bea Lima"
}
],
"opening_hours": "Mon–Sat 09:00–20:00",
"archived": false,
"access": "edit",
"created_at": "2026-11-10T10:00:00.000Z",
"updated_at": "2026-11-10T10:00:00.000Z"
},
"week": "2026-W47",
"start": "2026-11-16",
"days": [
{
"date": "2026-11-16",
"weekday": 1
},
{
"date": "2026-11-17",
"weekday": 2
},
{
"date": "2026-11-18",
"weekday": 3
},
{
"date": "2026-11-19",
"weekday": 4
},
{
"date": "2026-11-20",
"weekday": 5
},
{
"date": "2026-11-21",
"weekday": 6
},
{
"date": "2026-11-22",
"weekday": 7
}
],
"access": "edit",
"status": {
"version": 1,
"published_at": "2026-11-12T10:00:00.000Z",
"published_by": {
"id": "p2",
"name": "Bea Lima"
},
"changes": 1
},
"people": [
{
"person": {
"id": "p3",
"name": "Carl Reis"
},
"planned_minutes": 420,
"contract_minutes": 2100,
"position_ids": [
"pos1"
],
"days": [
{
"date": "2026-11-16",
"away": null,
"holiday": null
},
{
"date": "2026-11-19",
"away": "full",
"holiday": null
}
],
"availability": [
{
"weekday": 3,
"date": null,
"from": "16:00",
"to": null
}
]
}
],
"shifts": [
{
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"minutes": 420,
"person": {
"id": "p3",
"name": "Carl Reis"
},
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
},
"note": "Opens the kitchen",
"template_id": null
},
{
"id": "sh_2",
"date": "2026-11-18",
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"minutes": 420,
"person": null,
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
},
"note": null,
"template_id": null
}
],
"findings": [
{
"code": "rest",
"level": "reason",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"shift_ids": [
"sh_1",
"sh_3"
],
"date": "2026-11-17",
"message": "11 h rest between shifts: 8 h 30 between Mon 16 and Tue 17. Código do Trabalho art. 214",
"law": "Código do Trabalho art. 214",
"values": {
"actual": 510,
"limit": 660
}
}
],
"changes": [
{
"shift_id": "sh_1",
"date": "2026-11-16",
"kind": "changed",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"before": {
"start": "09:00",
"end": "17:00",
"person": {
"id": "p3",
"name": "Carl Reis"
}
},
"after": {
"start": "12:00",
"end": "20:00",
"person": {
"id": "p3",
"name": "Carl Reis"
}
},
"inside_notice": true
}
],
"publish_by": "2026-11-13",
"notice_days": 3,
"notice_source": "law"
}
}Check a rota week#
POST/v1/shifts/week.checkRead
Runs the law checks on a rota week's draft across all the people's rotas and the weeks around it: rest between shifts (PT/EU/DE 11 h, ES 12 h), weekly rest (EU 24 h + 11 h, PT a rest day, ES 1.5 days over 14), longest day (PT 8 h, ES 9 h, DE 10 h), the 48-hour week and its rolling average, breaks, PT changes of shift before the weekly rest, leave, holidays, availability, positions, contract hours and night work. Each finding names the rule and the article. Editors and HR.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_week_checkon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
rota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.
Returns
findingsobject[]required8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
blocksintegerrequiredreasonsintegerrequiredwarningsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/week.check \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rota_id":"r1","week":"2026-W47"}'const res = await fetch('https://api.bizisy.com/v1/shifts/week.check', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W47"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/week.check",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"rota_id": "r1",
"week": "2026-W47",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"findings": [
{
"code": "rest",
"level": "reason",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"shift_ids": [
"sh_1",
"sh_3"
],
"date": "2026-11-17",
"message": "11 h rest between shifts: 8 h 30 between Mon 16 and Tue 17. Código do Trabalho art. 214",
"law": "Código do Trabalho art. 214",
"values": {
"actual": 510,
"limit": 660
}
}
],
"blocks": 0,
"reasons": 1,
"warnings": 0
}
}Fill a rota week#
POST/v1/shifts/week.fillWrite
Fills a rota week's draft: mode schedules (each person's work schedule for those days becomes shifts; flexible days are skipped), copy (from_week of this rota or from_rota_id), or template (template_week_id). replace true clears the draft first; otherwise shifts are added. Approved full-day leave, holidays and anything that would always block are skipped and counted. Nothing is published: people see it once an editor publishes. Editors and HR; an API key or AI app may draft.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_week_fillon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
rota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.mode"schedules" | "copy" | "template"requiredfrom_weekstringPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.from_rota_idstring1–100 characters.
template_week_idstring1–100 characters.
replacebooleanDefault
false.
Returns
addedintegerrequiredskipped_leaveintegerrequiredskipped_holidayintegerrequiredskipped_otherintegerrequiredweekobjectrequired13 fields
rotaobjectrequired16 fields
idstringrequirednamestringrequiredkind"location" | "team"requiredlocationobject | nullrequired2 fields
idstringrequirednamestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
timezonestringrequiredcountrystring | nullrequiredmembersintegerrequiredPeople on the rota today.
extra_membersobject[]requiredBorrowed staff (editors only; empty for others).
2 fields
idstringrequirednamestringrequired
editors_mode"default" | "custom"requireddefault: the team's leads up the tree (team rotas), HR only (location rotas).
editorsobject[]requiredWho besides owners, admins and HR plans and publishes it.
2 fields
idstringrequirednamestringrequired
opening_hoursstring | nullrequiredarchivedbooleanrequiredaccess"edit" | "read"requirededit: you plan it (drafts, publish, requests); read: you see what is published.
created_atstringrequiredupdated_atstringrequired
weekstringrequiredstartstringrequireddaysobject[]required2 fields
datestringrequiredweekdayintegerrequired
access"edit" | "read"requiredstatusobjectrequired4 fields
versionintegerrequired0: never published.
published_atstring | nullrequiredpublished_byobject | nullrequired2 fields
idstringrequirednamestringrequired
changesintegerrequiredDraft changes not published yet (editors; 0 for others).
peopleobject[]required6 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
planned_minutesintegerrequiredcontract_minutesinteger | nullrequiredWhat the work schedule expects this week (editors only).
position_idsstring[]requiredPositions they can work (editors only).
daysobject[]requiredEditors only (empty for others).
3 fields
datestringrequiredaway"full" | "am" | "pm" | "hours"requiredApproved time off ("Away"; never its type).
holidaystring | nullrequired
availabilityobject[]requiredWhen they said they can't work (editors only; notes stay private).
4 fields
weekdayinteger | nullrequireddatestring | nullrequiredfromstring | nullrequiredtostring | nullrequired
shiftsobject[]requiredEditors: the draft; others: what is published.
10 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredLocal time; at or before start: the shift ends the next day.
break_minutesintegerrequiredminutesintegerrequiredPlanned work: the shift minus its break.
personobject | nullrequirednull: an open shift.
2 fields
idstringrequirednamestringrequired
positionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
notestring | nullrequiredEditors and the shift's person; null for others.
template_idstring | nullrequired
findingsobject[]requiredLaw checks on the draft (editors only).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
changesobject[]requiredWhat publishing would change (editors only).
7 fields
shift_idstringrequireddatestringrequiredkind"added" | "removed" | "changed"requiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
beforeobject | nullrequired3 fields
startstringrequiredendstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
afterobject | nullrequired3 fields
startstringrequiredendstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
inside_noticebooleanrequiredThe shift (before or after) starts inside the notice window: publishing records a reason.
publish_bystring | nullrequiredThe day to publish by so the week goes out with the notice (week start minus notice days; editors only).
notice_daysinteger | nullrequirednotice_source"law" | "company"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/week.fill \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rota_id": "r1",
"week": "2026-W48",
"mode": "copy",
"from_week": "2026-W47",
"from_rota_id": "r1",
"replace": true
}'const res = await fetch('https://api.bizisy.com/v1/shifts/week.fill', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W48",
"mode": "copy",
"from_week": "2026-W47",
"from_rota_id": "r1",
"replace": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/week.fill",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"week": "2026-W48",
"mode": "copy",
"from_week": "2026-W47",
"from_rota_id": "r1",
"replace": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"added": 9,
"skipped_leave": 1,
"skipped_holiday": 0,
"skipped_other": 0,
"week": {
"rota": {
"id": "r1",
"name": "Kitchen",
"kind": "team",
"location": null,
"unit": {
"id": "u1",
"name": "Kitchen"
},
"timezone": "Europe/Lisbon",
"country": "PT",
"members": 3,
"extra_members": [],
"editors_mode": "default",
"editors": [
{
"id": "p2",
"name": "Bea Lima"
}
],
"opening_hours": "Mon–Sat 09:00–20:00",
"archived": false,
"access": "edit",
"created_at": "2026-11-10T10:00:00.000Z",
"updated_at": "2026-11-10T10:00:00.000Z"
},
"week": "2026-W47",
"start": "2026-11-16",
"days": [
{
"date": "2026-11-16",
"weekday": 1
},
{
"date": "2026-11-17",
"weekday": 2
},
{
"date": "2026-11-18",
"weekday": 3
},
{
"date": "2026-11-19",
"weekday": 4
},
{
"date": "2026-11-20",
"weekday": 5
},
{
"date": "2026-11-21",
"weekday": 6
},
{
"date": "2026-11-22",
"weekday": 7
}
],
"access": "edit",
"status": {
"version": 1,
"published_at": "2026-11-12T10:00:00.000Z",
"published_by": {
"id": "p2",
"name": "Bea Lima"
},
"changes": 1
},
"people": [
{
"person": {
"id": "p3",
"name": "Carl Reis"
},
"planned_minutes": 420,
"contract_minutes": 2100,
"position_ids": [
"pos1"
],
"days": [
{
"date": "2026-11-16",
"away": null,
"holiday": null
},
{
"date": "2026-11-19",
"away": "full",
"holiday": null
}
],
"availability": [
{
"weekday": 3,
"date": null,
"from": "16:00",
"to": null
}
]
}
],
"shifts": [
{
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"minutes": 420,
"person": {
"id": "p3",
"name": "Carl Reis"
},
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
},
"note": "Opens the kitchen",
"template_id": null
},
{
"id": "sh_2",
"date": "2026-11-18",
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"minutes": 420,
"person": null,
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
},
"note": null,
"template_id": null
}
],
"findings": [
{
"code": "rest",
"level": "reason",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"shift_ids": [
"sh_1",
"sh_3"
],
"date": "2026-11-17",
"message": "11 h rest between shifts: 8 h 30 between Mon 16 and Tue 17. Código do Trabalho art. 214",
"law": "Código do Trabalho art. 214",
"values": {
"actual": 510,
"limit": 660
}
}
],
"changes": [
{
"shift_id": "sh_1",
"date": "2026-11-16",
"kind": "changed",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"before": {
"start": "09:00",
"end": "17:00",
"person": {
"id": "p3",
"name": "Carl Reis"
}
},
"after": {
"start": "12:00",
"end": "20:00",
"person": {
"id": "p3",
"name": "Carl Reis"
}
},
"inside_notice": true
}
],
"publish_by": "2026-11-13",
"notice_days": 3,
"notice_source": "law"
}
}
}Add a shift#
POST/v1/shifts/shifts.createWrite
Adds a shift to a rota's draft: date, start and end (or template_id), break_minutes, person_id (null: an open shift), position_id, note (who covers what; never health or personal reasons). Returns the checks for that person's week; what always blocks is refused. Nobody is told until an editor publishes. Editors and HR; an API key or AI app may draft.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_shifts_createon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
rota_idstringrequired1–100 characters.
datestringrequiredPattern
^\d{4}-\d{2}-\d{2}$.template_idstring1–100 characters.
startstringPattern
^([01]\d|2[0-3]):[0-5]\d$.endstringAt or before start: ends the next day.
Pattern
^([01]\d|2[0-3]):[0-5]\d$.break_minutesintegerFrom 0 to 240.
person_idstring | nullnull: an open shift.
1–100 characters.
position_idstring | null1–100 characters.
notestring | nullJob tier: who covers what, never health or personal reasons.
Up to 200 characters.
Returns
shiftobject | nullrequired10 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredLocal time; at or before start: the shift ends the next day.
break_minutesintegerrequiredminutesintegerrequiredPlanned work: the shift minus its break.
personobject | nullrequirednull: an open shift.
2 fields
idstringrequirednamestringrequired
positionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
notestring | nullrequiredEditors and the shift's person; null for others.
template_idstring | nullrequired
findingsobject[]requiredWhat the checks say about the people of this shift this week (blocks are refused).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
changesintegerrequiredDraft changes not published yet.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/shifts.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rota_id": "r1",
"date": "2026-11-18",
"template_id": "t1",
"person_id": null,
"break_minutes": 30,
"position_id": "pos1",
"note": "Covers the till"
}'const res = await fetch('https://api.bizisy.com/v1/shifts/shifts.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"date": "2026-11-18",
"template_id": "t1",
"person_id": null,
"break_minutes": 30,
"position_id": "pos1",
"note": "Covers the till"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/shifts.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"date": "2026-11-18",
"template_id": "t1",
"person_id": None,
"break_minutes": 30,
"position_id": "pos1",
"note": "Covers the till",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"shift": {
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"minutes": 420,
"person": {
"id": "p3",
"name": "Carl Reis"
},
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
},
"note": "Opens the kitchen",
"template_id": null
},
"findings": [
{
"code": "rest",
"level": "reason",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"shift_ids": [
"sh_1",
"sh_3"
],
"date": "2026-11-17",
"message": "11 h rest between shifts: 8 h 30 between Mon 16 and Tue 17. Código do Trabalho art. 214",
"law": "Código do Trabalho art. 214",
"values": {
"actual": 510,
"limit": 660
}
}
],
"changes": 3
}
}Change a shift#
POST/v1/shifts/shifts.updateWrite
Changes a draft shift's times, break, person (null: open), position or note. A published shift changes for people once the week is published again (inside the notice window that needs a reason). Editors and HR; an API key or AI app may draft.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_shifts_updateon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
rota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.shift_idstringrequired1–100 characters.
startstringPattern
^([01]\d|2[0-3]):[0-5]\d$.endstringAt or before start: ends the next day.
Pattern
^([01]\d|2[0-3]):[0-5]\d$.break_minutesintegerFrom 0 to 240.
person_idstring | nullnull: an open shift.
1–100 characters.
position_idstring | null1–100 characters.
notestring | nullJob tier: who covers what, never health or personal reasons.
Up to 200 characters.
Returns
shiftobject | nullrequired10 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredLocal time; at or before start: the shift ends the next day.
break_minutesintegerrequiredminutesintegerrequiredPlanned work: the shift minus its break.
personobject | nullrequirednull: an open shift.
2 fields
idstringrequirednamestringrequired
positionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
notestring | nullrequiredEditors and the shift's person; null for others.
template_idstring | nullrequired
findingsobject[]requiredWhat the checks say about the people of this shift this week (blocks are refused).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
changesintegerrequiredDraft changes not published yet.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/shifts.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1",
"person_id": null,
"position_id": null,
"note": null,
"break_minutes": 0
}'const res = await fetch('https://api.bizisy.com/v1/shifts/shifts.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1",
"person_id": null,
"position_id": null,
"note": null,
"break_minutes": 0
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/shifts.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1",
"person_id": None,
"position_id": None,
"note": None,
"break_minutes": 0,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"shift": {
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"minutes": 420,
"person": {
"id": "p3",
"name": "Carl Reis"
},
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
},
"note": "Opens the kitchen",
"template_id": null
},
"findings": [
{
"code": "rest",
"level": "reason",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"shift_ids": [
"sh_1",
"sh_3"
],
"date": "2026-11-17",
"message": "11 h rest between shifts: 8 h 30 between Mon 16 and Tue 17. Código do Trabalho art. 214",
"law": "Código do Trabalho art. 214",
"values": {
"actual": 510,
"limit": 660
}
}
],
"changes": 3
}
}Move or copy a shift#
POST/v1/shifts/shifts.moveWrite
Moves a draft shift to another day of the same week and/or another person (person_id null: open), or copies it there (copy true). To another week: add it there and remove it here. Editors and HR; an API key or AI app may draft.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_shifts_moveon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
rota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.shift_idstringrequired1–100 characters.
datestringPattern
^\d{4}-\d{2}-\d{2}$.person_idstring | null1–100 characters.
copybooleanDefault
false.
Returns
shiftobject | nullrequired10 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredLocal time; at or before start: the shift ends the next day.
break_minutesintegerrequiredminutesintegerrequiredPlanned work: the shift minus its break.
personobject | nullrequirednull: an open shift.
2 fields
idstringrequirednamestringrequired
positionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
notestring | nullrequiredEditors and the shift's person; null for others.
template_idstring | nullrequired
findingsobject[]requiredWhat the checks say about the people of this shift this week (blocks are refused).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
changesintegerrequiredDraft changes not published yet.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/shifts.move \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1",
"person_id": "p2",
"copy": true
}'const res = await fetch('https://api.bizisy.com/v1/shifts/shifts.move', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1",
"person_id": "p2",
"copy": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/shifts.move",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1",
"person_id": "p2",
"copy": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"shift": {
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"minutes": 420,
"person": {
"id": "p3",
"name": "Carl Reis"
},
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
},
"note": "Opens the kitchen",
"template_id": null
},
"findings": [
{
"code": "rest",
"level": "reason",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"shift_ids": [
"sh_1",
"sh_3"
],
"date": "2026-11-17",
"message": "11 h rest between shifts: 8 h 30 between Mon 16 and Tue 17. Código do Trabalho art. 214",
"law": "Código do Trabalho art. 214",
"values": {
"actual": 510,
"limit": 660
}
}
],
"changes": 3
}
}Remove a shift#
POST/v1/shifts/shifts.deleteDestructive
Removes a shift from the draft (a published one goes for people when the week is published again). Editors and HR; an API key or AI app may draft.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_shifts_deleteon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
rota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.shift_idstringrequired1–100 characters.
Returns
shiftobject | nullrequired10 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredLocal time; at or before start: the shift ends the next day.
break_minutesintegerrequiredminutesintegerrequiredPlanned work: the shift minus its break.
personobject | nullrequirednull: an open shift.
2 fields
idstringrequirednamestringrequired
positionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
notestring | nullrequiredEditors and the shift's person; null for others.
template_idstring | nullrequired
findingsobject[]requiredWhat the checks say about the people of this shift this week (blocks are refused).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
changesintegerrequiredDraft changes not published yet.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/shifts.delete \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"rota_id":"r1","week":"2026-W47","shift_id":"sh_1"}'const res = await fetch('https://api.bizisy.com/v1/shifts/shifts.delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/shifts.delete",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"shift": null,
"findings": [],
"changes": 2
}
}Suggest people for an open shift#
POST/v1/shifts/suggestRead
For an open draft shift: the rota's people who could take it, best first. Each is tagged for its position (if any), not on leave, not already working then, said nothing against it, passes every law check, and the furthest below their contract hours this week comes first, with why ("12 h below contract this week"). Deterministic; never assigns anyone (shifts_shifts_update does). Editors and HR.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_suggeston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
rota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.shift_idstringrequired1–100 characters.
Returns
shiftobjectrequired10 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredLocal time; at or before start: the shift ends the next day.
break_minutesintegerrequiredminutesintegerrequiredPlanned work: the shift minus its break.
personobject | nullrequirednull: an open shift.
2 fields
idstringrequirednamestringrequired
positionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
notestring | nullrequiredEditors and the shift's person; null for others.
template_idstring | nullrequired
candidatesobject[]requiredUp to 10 items.
6 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
planned_minutesintegerrequiredcontract_minutesinteger | nullrequiredbelow_minutesinteger | nullrequiredwhystringrequirednotesstring[]requiredInformation findings (a holiday, night work).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/suggest \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rota_id":"r1","week":"2026-W47","shift_id":"sh_2"}'const res = await fetch('https://api.bizisy.com/v1/shifts/suggest', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_2"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/suggest",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"shift": {
"id": "sh_2",
"date": "2026-11-18",
"start": "09:00",
"end": "17:00",
"break_minutes": 60,
"minutes": 420,
"person": null,
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
},
"note": null,
"template_id": null
},
"candidates": [
{
"person": {
"id": "p2",
"name": "Bea Lima"
},
"planned_minutes": 1260,
"contract_minutes": 2100,
"below_minutes": 840,
"why": "14 h below contract this week",
"notes": []
}
]
}
}Publish a rota week#
POST/v1/shifts/week.publishWrite
Publishes a rota's draft for a week, or up to 4 weeks from it (weeks). Runs the law checks first: anything at level block stops it; warnings need acknowledge_warnings true ("I've checked these", recorded); rest findings and changes to published shifts inside the notice window (PT 7 days, 3 in a microempresa; ES 5; elsewhere the company's own) need a reason (agreed, asked, force_majeure, short_change, other with a note), recorded in the history and shown to the people concerned. Then the people whose shifts changed are told (in the app, push, and one email). A dry run returns the findings and how many would be told, publishing nothing. In the app only: never through an API key or an AI app. The rota's editors and HR.
- Web app only
- Refused for API keys and connected apps. A person publishes a rota in the app: it tells people and has legal effect. A dry run is not offered either.
- MCP tool
shifts_week_publishon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
rota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.weeksintegerFrom 1 to 4. Default
1.acknowledge_warningsbooleanDefault
false.reasonobject2 fields
kind"agreed" | "asked" | "force_majeure" | "short_change" | "other"requiredagreed (agreed with the person), asked (the person asked), force_majeure, short_change (a change of a week or less recorded in the book, PT art. 217 n.º 3), other.
notestringPrivate: required for other; the people concerned and HR see it.
1–500 characters.
Returns
weeksobject[]required7 fields
weekstringrequiredpublishedbooleanrequiredversionintegerrequiredchangesintegerrequiredtoldintegerrequiredPeople told (in the app, and by email where allowed).
findingsobject[]required8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
inside_noticeintegerrequiredChanges inside the notice window.
blockedbooleanrequiredSomething always blocks: nothing was published (the findings at level block say what).
needs_ackbooleanrequiredWarnings need acknowledge_warnings true.
needs_reasonbooleanrequiredRest findings or changes inside the notice need a reason.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/week.publish \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rota_id": "r1",
"week": "2026-W47",
"weeks": 4,
"acknowledge_warnings": true,
"reason": {
"kind": "other",
"note": "Supplier delay"
}
}'const res = await fetch('https://api.bizisy.com/v1/shifts/week.publish', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W47",
"weeks": 4,
"acknowledge_warnings": true,
"reason": {
"kind": "other",
"note": "Supplier delay"
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/week.publish",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"week": "2026-W47",
"weeks": 4,
"acknowledge_warnings": True,
"reason": {
"kind": "other",
"note": "Supplier delay",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"weeks": [
{
"week": "2026-W47",
"published": true,
"version": 2,
"changes": 1,
"told": 1,
"findings": [
{
"code": "rest",
"level": "reason",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"shift_ids": [
"sh_1",
"sh_3"
],
"date": "2026-11-17",
"message": "11 h rest between shifts: 8 h 30 between Mon 16 and Tue 17. Código do Trabalho art. 214",
"law": "Código do Trabalho art. 214",
"values": {
"actual": 510,
"limit": 660
}
}
],
"inside_notice": 1
}
],
"blocked": false,
"needs_ack": false,
"needs_reason": false
}
}A rota week's history#
POST/v1/shifts/week.historyRead
Every published version of a rota week, newest first: when, who published or approved it, what changed (shift by shift), the reason recorded for changes inside the notice and for rest findings, and the warnings acknowledged. This is the record of who works each shift and of short changes (PT Código do Trabalho arts. 215 n.º 4, 217 n.º 3, 221 n.º 6). Kept for the country's time-record retention. The rota's editors and HR; a reason's note (other) only in the app.
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- Never the note of an "other" reason.
- MCP tool
shifts_week_historyon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
rota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.
Returns
versionsobject[]required8 fields
versionintegerrequiredsource"publish" | "request" | "leave" | "leaver"requiredatstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
changesobject[]required7 fields
shift_idstringrequireddatestringrequiredkind"added" | "removed" | "changed"requiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
beforeobject | nullrequired3 fields
startstringrequiredendstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
afterobject | nullrequired3 fields
startstringrequiredendstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
inside_noticebooleanrequiredThe shift (before or after) starts inside the notice window: publishing records a reason.
shiftsintegerrequiredreasonobject | nullrequired2 fields
kind"agreed" | "asked" | "force_majeure" | "short_change" | "other"requirednotestring | nullrequired
acknowledgedintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/week.history \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rota_id":"r1","week":"2026-W47"}'const res = await fetch('https://api.bizisy.com/v1/shifts/week.history', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W47"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/week.history",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"rota_id": "r1",
"week": "2026-W47",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"versions": [
{
"version": 2,
"source": "publish",
"at": "2026-11-14T10:00:00.000Z",
"by": {
"id": "p2",
"name": "Bea Lima"
},
"changes": [
{
"shift_id": "sh_1",
"date": "2026-11-16",
"kind": "changed",
"person": {
"id": "p3",
"name": "Carl Reis"
},
"before": {
"start": "09:00",
"end": "17:00",
"person": {
"id": "p3",
"name": "Carl Reis"
}
},
"after": {
"start": "12:00",
"end": "20:00",
"person": {
"id": "p3",
"name": "Carl Reis"
}
},
"inside_notice": true
}
],
"shifts": 9,
"reason": {
"kind": "agreed",
"note": null
},
"acknowledged": 1
}
]
}
}List shift requests#
POST/v1/shifts/requests.listRead
Shift swaps, give-aways and claims (their private messages only in the app: never over an API key or AI app). scope mine (default in Me): yours, offers made to you, and give-aways on your rotas you could take; to_decide: requests waiting for you as a rota editor (with the checks for both people); all: every request of the rotas you edit (HR: the company). status narrows (default: open ones, offered or pending).
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- Never the private messages.
- MCP tool
shifts_requests_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
scope"mine" | "to_decide" | "all"Default
"mine".status"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"
Returns
itemsobject[]required17 fields
idstringrequiredkind"swap" | "give_away" | "claim"requiredstatus"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"requiredrotaobjectrequired2 fields
idstringrequirednamestringrequired
weekstringrequiredshiftobject | nullrequiredThe shift asked about (null when it no longer exists).
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
fromobjectrequiredWho asks: claim, the person who wants the open shift; swap and give away, whose shift it is.
2 fields
idstringrequirednamestringrequired
toobject | nullrequiredswap: the colleague asked; give away: who took it.
2 fields
idstringrequirednamestringrequired
other_shiftobject | nullrequiredswap: the colleague's shift offered in exchange.
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
messagestring | nullrequiredPrivate: the two people and HR in the app; null for others and machines.
findingsobject[]requiredThe checks for both people as it would be approved (editors, on requests waiting for them).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
can_acceptbooleanrequiredcan_cancelbooleanrequiredcan_decidebooleanrequiredstarts_atstringrequiredcreated_atstringrequireddecided_atstring | nullrequired
waiting_for_meintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/requests.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scope":"all","status":"approved"}'const res = await fetch('https://api.bizisy.com/v1/shifts/requests.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"scope": "all",
"status": "approved"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/requests.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"scope": "all",
"status": "approved",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "rq1",
"kind": "swap",
"status": "pending",
"rota": {
"id": "r1",
"name": "Kitchen"
},
"week": "2026-W47",
"shift": {
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
}
},
"from": {
"id": "p3",
"name": "Carl Reis"
},
"to": {
"id": "p2",
"name": "Bea Lima"
},
"other_shift": {
"id": "sh_4",
"date": "2026-11-17",
"start": "09:00",
"end": "17:00",
"position": null
},
"message": null,
"findings": [],
"can_accept": false,
"can_cancel": false,
"can_decide": true,
"starts_at": "2026-11-16T09:00:00.000Z",
"created_at": "2026-11-12T10:00:00.000Z",
"decided_at": null
}
],
"waiting_for_me": 1
}
}Ask to swap, give away or claim a shift#
POST/v1/shifts/requests.createWrite
For your own published shifts: swap (with_shift_id, a colleague's shift on a rota you are on; they accept, then an editor approves), give_away (a colleague takes it, then an editor approves; with_person_id to offer it to one colleague), or claim an open published shift (an editor approves; the company may approve claims that pass every check at once). The law checks run first: a request that would break a rest rule or always blocks can't be made, and says why. At most 20 open requests a person. message: optional, private.
- Who can call it
- Manage key owner admin hr
Me key owner admin hr member - MCP tool
shifts_requests_createon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
kind"swap" | "give_away" | "claim"requiredrota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.shift_idstringrequired1–100 characters.
with_person_idstring1–100 characters.
with_rota_idstring1–100 characters.
with_weekstringPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.with_shift_idstring1–100 characters.
messagestring1–500 characters.
Returns
17 fields
idstringrequiredkind"swap" | "give_away" | "claim"requiredstatus"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"requiredrotaobjectrequired2 fields
idstringrequirednamestringrequired
weekstringrequiredshiftobject | nullrequiredThe shift asked about (null when it no longer exists).
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
fromobjectrequiredWho asks: claim, the person who wants the open shift; swap and give away, whose shift it is.
2 fields
idstringrequirednamestringrequired
toobject | nullrequiredswap: the colleague asked; give away: who took it.
2 fields
idstringrequirednamestringrequired
other_shiftobject | nullrequiredswap: the colleague's shift offered in exchange.
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
messagestring | nullrequiredPrivate: the two people and HR in the app; null for others and machines.
findingsobject[]requiredThe checks for both people as it would be approved (editors, on requests waiting for them).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
can_acceptbooleanrequiredcan_cancelbooleanrequiredcan_decidebooleanrequiredstarts_atstringrequiredcreated_atstringrequireddecided_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/requests.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"kind": "swap",
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1",
"with_shift_id": "sh_4",
"with_rota_id": "r1",
"with_week": "2026-W47",
"message": "Doctor on Monday"
}'const res = await fetch('https://api.bizisy.com/v1/shifts/requests.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"kind": "swap",
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1",
"with_shift_id": "sh_4",
"with_rota_id": "r1",
"with_week": "2026-W47",
"message": "Doctor on Monday"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/requests.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"kind": "swap",
"rota_id": "r1",
"week": "2026-W47",
"shift_id": "sh_1",
"with_shift_id": "sh_4",
"with_rota_id": "r1",
"with_week": "2026-W47",
"message": "Doctor on Monday",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "rq1",
"kind": "swap",
"status": "offered",
"rota": {
"id": "r1",
"name": "Kitchen"
},
"week": "2026-W47",
"shift": {
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
}
},
"from": {
"id": "p3",
"name": "Carl Reis"
},
"to": {
"id": "p2",
"name": "Bea Lima"
},
"other_shift": {
"id": "sh_4",
"date": "2026-11-17",
"start": "09:00",
"end": "17:00",
"position": null
},
"message": "Doctor on Monday",
"findings": [],
"can_accept": false,
"can_cancel": true,
"can_decide": false,
"starts_at": "2026-11-16T09:00:00.000Z",
"created_at": "2026-11-12T10:00:00.000Z",
"decided_at": null
}
}Accept a swap or a shift offered#
POST/v1/shifts/requests.acceptWrite
Accepts a swap asked of you, or takes a shift a colleague gives away. The law checks run for both people first; a request that would break a rest rule or always blocks can't be accepted, and says why. Then it waits for an editor's approval — unless your company's Ask HR rule approves it at once (logged with the rule).
- Who can call it
- Manage key owner admin hr
Me key owner admin hr member - MCP tool
shifts_requests_accepton My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
request_idstringrequired1–100 characters.
Returns
17 fields
idstringrequiredkind"swap" | "give_away" | "claim"requiredstatus"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"requiredrotaobjectrequired2 fields
idstringrequirednamestringrequired
weekstringrequiredshiftobject | nullrequiredThe shift asked about (null when it no longer exists).
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
fromobjectrequiredWho asks: claim, the person who wants the open shift; swap and give away, whose shift it is.
2 fields
idstringrequirednamestringrequired
toobject | nullrequiredswap: the colleague asked; give away: who took it.
2 fields
idstringrequirednamestringrequired
other_shiftobject | nullrequiredswap: the colleague's shift offered in exchange.
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
messagestring | nullrequiredPrivate: the two people and HR in the app; null for others and machines.
findingsobject[]requiredThe checks for both people as it would be approved (editors, on requests waiting for them).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
can_acceptbooleanrequiredcan_cancelbooleanrequiredcan_decidebooleanrequiredstarts_atstringrequiredcreated_atstringrequireddecided_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/requests.accept \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"request_id":"rq1"}'const res = await fetch('https://api.bizisy.com/v1/shifts/requests.accept', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"request_id": "rq1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/requests.accept",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"request_id": "rq1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "rq1",
"kind": "swap",
"status": "pending",
"rota": {
"id": "r1",
"name": "Kitchen"
},
"week": "2026-W47",
"shift": {
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
}
},
"from": {
"id": "p3",
"name": "Carl Reis"
},
"to": {
"id": "p2",
"name": "Bea Lima"
},
"other_shift": {
"id": "sh_4",
"date": "2026-11-17",
"start": "09:00",
"end": "17:00",
"position": null
},
"message": null,
"findings": [],
"can_accept": false,
"can_cancel": false,
"can_decide": true,
"starts_at": "2026-11-16T09:00:00.000Z",
"created_at": "2026-11-12T10:00:00.000Z",
"decided_at": null
}
}Cancel or decline a shift request#
POST/v1/shifts/requests.cancelWrite
Cancels your own open request, or declines a swap asked of you (it is then declined).
- Who can call it
- Manage key owner admin hr
Me key owner admin hr member - MCP tool
shifts_requests_cancelon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
request_idstringrequired1–100 characters.
Returns
17 fields
idstringrequiredkind"swap" | "give_away" | "claim"requiredstatus"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"requiredrotaobjectrequired2 fields
idstringrequirednamestringrequired
weekstringrequiredshiftobject | nullrequiredThe shift asked about (null when it no longer exists).
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
fromobjectrequiredWho asks: claim, the person who wants the open shift; swap and give away, whose shift it is.
2 fields
idstringrequirednamestringrequired
toobject | nullrequiredswap: the colleague asked; give away: who took it.
2 fields
idstringrequirednamestringrequired
other_shiftobject | nullrequiredswap: the colleague's shift offered in exchange.
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
messagestring | nullrequiredPrivate: the two people and HR in the app; null for others and machines.
findingsobject[]requiredThe checks for both people as it would be approved (editors, on requests waiting for them).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
can_acceptbooleanrequiredcan_cancelbooleanrequiredcan_decidebooleanrequiredstarts_atstringrequiredcreated_atstringrequireddecided_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/requests.cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"request_id":"rq1"}'const res = await fetch('https://api.bizisy.com/v1/shifts/requests.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"request_id": "rq1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/requests.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"request_id": "rq1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "rq1",
"kind": "swap",
"status": "cancelled",
"rota": {
"id": "r1",
"name": "Kitchen"
},
"week": "2026-W47",
"shift": {
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
}
},
"from": {
"id": "p3",
"name": "Carl Reis"
},
"to": {
"id": "p2",
"name": "Bea Lima"
},
"other_shift": {
"id": "sh_4",
"date": "2026-11-17",
"start": "09:00",
"end": "17:00",
"position": null
},
"message": null,
"findings": [],
"can_accept": false,
"can_cancel": false,
"can_decide": false,
"starts_at": "2026-11-16T09:00:00.000Z",
"created_at": "2026-11-12T10:00:00.000Z",
"decided_at": null
}
}Approve a shift request#
POST/v1/shifts/requests.approveWrite
Approves a swap, give-away or claim waiting for you as one of the rota's editors. The checks run again for both people; what would break a rest rule or always blocks is refused. The published week changes at once (no republish), both people are told, and the history shows it (inside the notice window with "the person asked"). In the app only; never by the people in the request.
- Web app only
- Refused for API keys and connected apps. An editor approves shift requests in the app.
- MCP tool
shifts_requests_approveon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
request_idstringrequired1–100 characters.
whystring | nullOptional: why, in one line about the case (never the person), kept as a decision record when your company records decisions (Ask HR). Refused if it mentions health, names or ratings.
Up to 300 characters.
why_source"person" | "ai"ai: the "Why?" is as Ask HR prefilled it.
Returns
17 fields
idstringrequiredkind"swap" | "give_away" | "claim"requiredstatus"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"requiredrotaobjectrequired2 fields
idstringrequirednamestringrequired
weekstringrequiredshiftobject | nullrequiredThe shift asked about (null when it no longer exists).
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
fromobjectrequiredWho asks: claim, the person who wants the open shift; swap and give away, whose shift it is.
2 fields
idstringrequirednamestringrequired
toobject | nullrequiredswap: the colleague asked; give away: who took it.
2 fields
idstringrequirednamestringrequired
other_shiftobject | nullrequiredswap: the colleague's shift offered in exchange.
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
messagestring | nullrequiredPrivate: the two people and HR in the app; null for others and machines.
findingsobject[]requiredThe checks for both people as it would be approved (editors, on requests waiting for them).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
can_acceptbooleanrequiredcan_cancelbooleanrequiredcan_decidebooleanrequiredstarts_atstringrequiredcreated_atstringrequireddecided_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/requests.approve \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"request_id": "rq1",
"why": "Same role, both agreed",
"why_source": "person"
}'const res = await fetch('https://api.bizisy.com/v1/shifts/requests.approve', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"request_id": "rq1",
"why": "Same role, both agreed",
"why_source": "person"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/requests.approve",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"request_id": "rq1",
"why": "Same role, both agreed",
"why_source": "person",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "rq1",
"kind": "swap",
"status": "approved",
"rota": {
"id": "r1",
"name": "Kitchen"
},
"week": "2026-W47",
"shift": {
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
}
},
"from": {
"id": "p3",
"name": "Carl Reis"
},
"to": {
"id": "p2",
"name": "Bea Lima"
},
"other_shift": {
"id": "sh_4",
"date": "2026-11-17",
"start": "09:00",
"end": "17:00",
"position": null
},
"message": null,
"findings": [],
"can_accept": false,
"can_cancel": false,
"can_decide": false,
"starts_at": "2026-11-16T09:00:00.000Z",
"created_at": "2026-11-12T10:00:00.000Z",
"decided_at": "2026-11-13T10:00:00.000Z"
}
}Decline a shift request#
POST/v1/shifts/requests.declineWrite
Declines a swap, give-away or claim waiting for you as one of the rota's editors; both people are told. In the app only.
- Web app only
- Refused for API keys and connected apps. An editor declines shift requests in the app.
- MCP tool
shifts_requests_declineon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
request_idstringrequired1–100 characters.
whystring | nullOptional: why, in one line about the case (never the person), kept as a decision record when your company records decisions (Ask HR). Refused if it mentions health, names or ratings.
Up to 300 characters.
why_source"person" | "ai"ai: the "Why?" is as Ask HR prefilled it.
Returns
17 fields
idstringrequiredkind"swap" | "give_away" | "claim"requiredstatus"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"requiredrotaobjectrequired2 fields
idstringrequirednamestringrequired
weekstringrequiredshiftobject | nullrequiredThe shift asked about (null when it no longer exists).
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
fromobjectrequiredWho asks: claim, the person who wants the open shift; swap and give away, whose shift it is.
2 fields
idstringrequirednamestringrequired
toobject | nullrequiredswap: the colleague asked; give away: who took it.
2 fields
idstringrequirednamestringrequired
other_shiftobject | nullrequiredswap: the colleague's shift offered in exchange.
5 fields
idstringrequireddatestringrequiredstartstringrequiredendstringrequiredpositionobject | nullrequired3 fields
idstringrequirednamestringrequiredcolorstring (enum)requiredOne of:
teal,rose,violet,slate,amber,blue,green,orange,pink,indigo.
messagestring | nullrequiredPrivate: the two people and HR in the app; null for others and machines.
findingsobject[]requiredThe checks for both people as it would be approved (editors, on requests waiting for them).
8 fields
codestring (enum)requiredOne of:
overlap,leave,not_employed,rest,weekly_rest,day_max,week_max,week_average,break,shift_change,leave_partial,leave_pending,availability,position,holiday,contract_hours,night,notice,company_rule.level"info" | "warning" | "reason" | "block"requiredinfo; warning (publishing asks for one "I've checked these" tick); reason (rest rules and changes inside the notice: publishing records a reason; a company setting can make rest rules blocks); block (never published).
personobject | nullrequired2 fields
idstringrequirednamestringrequired
shift_idsstring[]requireddatestringrequiredmessagestringrequiredThe rule, the numbers and the article, in English.
lawstring | nullrequiredvaluesobjectrequired2 fields
actualnumber | nullrequiredlimitnumber | nullrequired
can_acceptbooleanrequiredcan_cancelbooleanrequiredcan_decidebooleanrequiredstarts_atstringrequiredcreated_atstringrequireddecided_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/requests.decline \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"request_id":"rq1","why":"Not enough cover on Saturday"}'const res = await fetch('https://api.bizisy.com/v1/shifts/requests.decline', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"request_id": "rq1",
"why": "Not enough cover on Saturday"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/requests.decline",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"request_id": "rq1",
"why": "Not enough cover on Saturday",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "rq1",
"kind": "swap",
"status": "declined",
"rota": {
"id": "r1",
"name": "Kitchen"
},
"week": "2026-W47",
"shift": {
"id": "sh_1",
"date": "2026-11-16",
"start": "09:00",
"end": "17:00",
"position": {
"id": "pos1",
"name": "Till",
"color": "amber"
}
},
"from": {
"id": "p3",
"name": "Carl Reis"
},
"to": {
"id": "p2",
"name": "Bea Lima"
},
"other_shift": {
"id": "sh_4",
"date": "2026-11-17",
"start": "09:00",
"end": "17:00",
"position": null
},
"message": null,
"findings": [],
"can_accept": false,
"can_cancel": false,
"can_decide": false,
"starts_at": "2026-11-16T09:00:00.000Z",
"created_at": "2026-11-12T10:00:00.000Z",
"decided_at": "2026-11-13T10:00:00.000Z"
}
}Shift settings#
POST/v1/shifts/settings.getRead
Settings → Shifts: whether rest findings block or need a reason, the company's notice days where the law leaves it to the company, auto-approved claims, and the PT mapa de horário fields per Portuguese location. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
shifts_settings_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
rest_hard_blockbooleanrequiredRest findings block publishing instead of needing a recorded reason.
auto_approve_claimsbooleanrequiredClaims of open shifts that pass every check are approved at once.
notice_daysintegerrequiredDays' notice of a change where the law leaves it to the company (Directive 2019/1152 art. 10: "reasonable"); Portugal (7, or 3 in a microempresa) and Spain (5) follow their law.
mapaobject[]requiredThe PT mapa de horário's fields, for each location in Portugal (Código do Trabalho art. 215).
2 fields
locationobjectrequired3 fields
idstringrequirednamestringrequiredcountrystringrequired
fieldsobjectrequired10 fields
employer_namestring | nullrequiredUp to 200 characters.
activitystring | nullrequiredUp to 200 characters.
caestring | nullrequiredUp to 200 characters.
seat_addressstring | nullrequiredUp to 200 characters.
workplace_addressstring | nullrequiredUp to 200 characters.
closing_daystring | nullrequiredUp to 200 characters.
mandatory_rest_daystring | nullrequiredUp to 200 characters.
complementary_rest_daystring | nullrequiredUp to 200 characters.
irctstring | nullrequiredUp to 200 characters.
adaptabilitystring | nullrequiredUp to 200 characters.
savedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/shifts/settings.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/settings.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"rest_hard_block": false,
"auto_approve_claims": false,
"notice_days": 7,
"mapa": [
{
"location": {
"id": "l1",
"name": "Lisbon shop",
"country": "PT"
},
"fields": {
"employer_name": "Acme Lda",
"activity": "Restauração",
"cae": "56101",
"seat_address": "Rua A, Lisboa",
"workplace_address": "Rua B, Lisboa",
"closing_day": "Domingo",
"mandatory_rest_day": "Rotativo, ver escala",
"complementary_rest_day": null,
"irct": "CCT Restauração",
"adaptability": null
}
}
],
"saved": true
}
}Change shift settings#
POST/v1/shifts/settings.updateWrite
Changes Settings → Shifts: rest_hard_block, auto_approve_claims, notice_days (1–60, where the law leaves it to the company), mapa {location_id: fields} for Portuguese locations (only the fields sent change; null clears one). An API key or AI app can't make rest rules blocks or switch auto-approval (in the app). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Rest rules as blocks and auto-approved claims are changed in the app.
- MCP tool
shifts_settings_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
rest_hard_blockbooleanauto_approve_claimsbooleannotice_daysintegerFrom 1 to 60.
mapaobject
Returns
rest_hard_blockbooleanrequiredRest findings block publishing instead of needing a recorded reason.
auto_approve_claimsbooleanrequiredClaims of open shifts that pass every check are approved at once.
notice_daysintegerrequiredDays' notice of a change where the law leaves it to the company (Directive 2019/1152 art. 10: "reasonable"); Portugal (7, or 3 in a microempresa) and Spain (5) follow their law.
mapaobject[]requiredThe PT mapa de horário's fields, for each location in Portugal (Código do Trabalho art. 215).
2 fields
locationobjectrequired3 fields
idstringrequirednamestringrequiredcountrystringrequired
fieldsobjectrequired10 fields
employer_namestring | nullrequiredUp to 200 characters.
activitystring | nullrequiredUp to 200 characters.
caestring | nullrequiredUp to 200 characters.
seat_addressstring | nullrequiredUp to 200 characters.
workplace_addressstring | nullrequiredUp to 200 characters.
closing_daystring | nullrequiredUp to 200 characters.
mandatory_rest_daystring | nullrequiredUp to 200 characters.
complementary_rest_daystring | nullrequiredUp to 200 characters.
irctstring | nullrequiredUp to 200 characters.
adaptabilitystring | nullrequiredUp to 200 characters.
savedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/settings.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rest_hard_block": true,
"auto_approve_claims": true,
"mapa": {
"l1": {
"cae": "56101",
"closing_day": "Domingo",
"irct": null
}
}
}'const res = await fetch('https://api.bizisy.com/v1/shifts/settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rest_hard_block": true,
"auto_approve_claims": true,
"mapa": {
"l1": {
"cae": "56101",
"closing_day": "Domingo",
"irct": null
}
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rest_hard_block": True,
"auto_approve_claims": True,
"mapa": {
"l1": {
"cae": "56101",
"closing_day": "Domingo",
"irct": None,
},
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"rest_hard_block": true,
"auto_approve_claims": true,
"notice_days": 7,
"mapa": [
{
"location": {
"id": "l1",
"name": "Lisbon shop",
"country": "PT"
},
"fields": {
"employer_name": "Acme Lda",
"activity": "Restauração",
"cae": "56101",
"seat_address": "Rua A, Lisboa",
"workplace_address": "Rua B, Lisboa",
"closing_day": "Domingo",
"mandatory_rest_day": "Rotativo, ver escala",
"complementary_rest_day": null,
"irct": "CCT Restauração",
"adaptability": null
}
}
],
"saved": true
}
}Print or export a rota#
POST/v1/shifts/printWrite
A rota's published shifts for 1–5 weeks from week, as PDF (one page per week) or CSV, in lang. kind rota (every country); mapa: the Portuguese mapa de horário de trabalho (a location in Portugal: employer, activity, seat and workplace, opening hours, closing day, rest days, the collective agreement and adaptability regime, number of shifts and the rotation scale; Código do Trabalho arts. 215–216: post it where people can see it; fill the fields in Settings → Shifts); cuadrante (Spain: the rota titled "Cuadrante de turnos"); history (every version with its changes and reasons). The rota's editors and HR.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_printon My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
rota_idstringrequired1–100 characters.
weekstringrequiredPattern
^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.weeksintegerFrom 1 to 5. Default
1.kind"rota" | "mapa" | "cuadrante" | "history"Default
"rota".format"pdf" | "csv"Default
"pdf".lang"en" | "pt" | "es" | "de" | "fr" | "it"Language of the print (default en).
Returns
fileobjectrequired6 fields
namestringrequiredcontent_typestringrequiredencoding"utf8" | "base64"requiredcontentstringrequiredbytesintegerrequiredsha256stringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/print \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rota_id": "r1",
"week": "2026-W47",
"weeks": 5,
"kind": "mapa",
"format": "pdf",
"lang": "pt"
}'const res = await fetch('https://api.bizisy.com/v1/shifts/print', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rota_id": "r1",
"week": "2026-W47",
"weeks": 5,
"kind": "mapa",
"format": "pdf",
"lang": "pt"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/print",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rota_id": "r1",
"week": "2026-W47",
"weeks": 5,
"kind": "mapa",
"format": "pdf",
"lang": "pt",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file": {
"name": "rota-kitchen-2026-W47.pdf",
"content_type": "application/pdf",
"encoding": "base64",
"content": "JVBERi0=",
"bytes": 5,
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
}
}What needs you in shift rotas#
POST/v1/shifts/homeRead
For rota editors and HR: weeks to publish and by when (so changes go out with the notice the law asks), open shifts in the next 14 days, swaps and claims waiting for you, and people planned over 48 hours. Empty for everyone else.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
shifts_homeon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
publish_byobject[]requiredWeeks not published yet, with the day to publish by (week start minus the notice).
4 fields
rotaobjectrequired2 fields
idstringrequirednamestringrequired
weekstringrequiredbystringrequiredoverduebooleanrequired
open_shiftsintegerrequiredOpen shifts in the next 14 days (published or in a draft), incl. those opened by approved leave.
requestsintegerrequiredSwaps, give-aways and claims waiting for you.
over_48integerrequiredPeople planned over 48 hours in a week, this week or the next 3 (drafts).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/shifts/home \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/shifts/home', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/shifts/home",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"publish_by": [
{
"rota": {
"id": "r1",
"name": "Kitchen"
},
"week": "2026-W48",
"by": "2026-11-20",
"overdue": false
}
],
"open_shifts": 2,
"requests": 1,
"over_48": 0
}
}Something missing or wrong on this page? Write to hello@bizisy.com.