Skip to content

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_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • archivedboolean

Returns

  • itemsobject[]required
    16 fields
    • idstringrequired
    • namestringrequired
    • kind"location" | "team"required
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • timezonestringrequired
    • countrystring | nullrequired
    • membersintegerrequired

      People on the rota today.

    • extra_membersobject[]required

      Borrowed staff (editors only; empty for others).

      2 fields
      • idstringrequired
      • namestringrequired
    • editors_mode"default" | "custom"required

      default: the team's leads up the tree (team rotas), HR only (location rotas).

    • editorsobject[]required

      Who besides owners, admins and HR plans and publishes it.

      2 fields
      • idstringrequired
      • namestringrequired
    • opening_hoursstring | nullrequired
    • archivedbooleanrequired
    • access"edit" | "read"required

      edit: you plan it (drafts, publish, requests); read: you see what is published.

    • created_atstringrequired
    • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/rotas.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'
Response
{
  "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_get on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • rota_idstringrequired

    1–100 characters.

Returns

17 fields
  • idstringrequired
  • namestringrequired
  • kind"location" | "team"required
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • timezonestringrequired
  • countrystring | nullrequired
  • membersintegerrequired

    People on the rota today.

  • extra_membersobject[]required

    Borrowed staff (editors only; empty for others).

    2 fields
    • idstringrequired
    • namestringrequired
  • editors_mode"default" | "custom"required

    default: the team's leads up the tree (team rotas), HR only (location rotas).

  • editorsobject[]required

    Who besides owners, admins and HR plans and publishes it.

    2 fields
    • idstringrequired
    • namestringrequired
  • opening_hoursstring | nullrequired
  • archivedbooleanrequired
  • access"edit" | "read"required

    edit: you plan it (drafts, publish, requests); read: you see what is published.

  • created_atstringrequired
  • updated_atstringrequired
  • peopleobject[]required

    Everyone on the rota today (editors only; empty for others).

    2 fields
    • idstringrequired
    • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/rotas.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rota_id":"r1"}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • location_idstring

    1–100 characters.

  • unit_idstring

    1–100 characters.

  • namestring

    1–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 | null

    The 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
  • idstringrequired
  • namestringrequired
  • kind"location" | "team"required
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • timezonestringrequired
  • countrystring | nullrequired
  • membersintegerrequired

    People on the rota today.

  • extra_membersobject[]required

    Borrowed staff (editors only; empty for others).

    2 fields
    • idstringrequired
    • namestringrequired
  • editors_mode"default" | "custom"required

    default: the team's leads up the tree (team rotas), HR only (location rotas).

  • editorsobject[]required

    Who besides owners, admins and HR plans and publishes it.

    2 fields
    • idstringrequired
    • namestringrequired
  • opening_hoursstring | nullrequired
  • archivedbooleanrequired
  • access"edit" | "read"required

    edit: you plan it (drafts, publish, requests); read: you see what is published.

  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • rota_idstringrequired

    1–100 characters.

  • namestring

    1–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 | null

    The 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
  • idstringrequired
  • namestringrequired
  • kind"location" | "team"required
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • timezonestringrequired
  • countrystring | nullrequired
  • membersintegerrequired

    People on the rota today.

  • extra_membersobject[]required

    Borrowed staff (editors only; empty for others).

    2 fields
    • idstringrequired
    • namestringrequired
  • editors_mode"default" | "custom"required

    default: the team's leads up the tree (team rotas), HR only (location rotas).

  • editorsobject[]required

    Who besides owners, admins and HR plans and publishes it.

    2 fields
    • idstringrequired
    • namestringrequired
  • opening_hoursstring | nullrequired
  • archivedbooleanrequired
  • access"edit" | "read"required

    edit: you plan it (drafts, publish, requests); read: you see what is published.

  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • rota_idstringrequired

    1–100 characters.

  • archivedboolean

    Default true.

Returns

16 fields
  • idstringrequired
  • namestringrequired
  • kind"location" | "team"required
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • timezonestringrequired
  • countrystring | nullrequired
  • membersintegerrequired

    People on the rota today.

  • extra_membersobject[]required

    Borrowed staff (editors only; empty for others).

    2 fields
    • idstringrequired
    • namestringrequired
  • editors_mode"default" | "custom"required

    default: the team's leads up the tree (team rotas), HR only (location rotas).

  • editorsobject[]required

    Who besides owners, admins and HR plans and publishes it.

    2 fields
    • idstringrequired
    • namestringrequired
  • opening_hoursstring | nullrequired
  • archivedbooleanrequired
  • access"edit" | "read"required

    edit: you plan it (drafts, publish, requests); read: you see what is published.

  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_set on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • rota_idstringrequired

    1–100 characters.

  • mode"default" | "custom"

    Default "custom".

  • person_idsstring[]

    1–100 characters. Up to 20 items.

Returns

16 fields
  • idstringrequired
  • namestringrequired
  • kind"location" | "team"required
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • timezonestringrequired
  • countrystring | nullrequired
  • membersintegerrequired

    People on the rota today.

  • extra_membersobject[]required

    Borrowed staff (editors only; empty for others).

    2 fields
    • idstringrequired
    • namestringrequired
  • editors_mode"default" | "custom"required

    default: the team's leads up the tree (team rotas), HR only (location rotas).

  • editorsobject[]required

    Who besides owners, admins and HR plans and publishes it.

    2 fields
    • idstringrequired
    • namestringrequired
  • opening_hoursstring | nullrequired
  • archivedbooleanrequired
  • access"edit" | "read"required

    edit: you plan it (drafts, publish, requests); read: you see what is published.

  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"]}'
Response
{
  "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_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • archivedboolean

Returns

  • itemsobject[]required
    5 fields
    • idstringrequired
    • namestringrequired
    • colorstring (enum)required

      One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • archivedbooleanrequired
    • peopleintegerrequired

      People tagged for it.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/positions.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • namestringrequired

    1–80 characters.

  • colorstring (enum)

    One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo. Default "teal".

Returns

  • idstringrequired
  • namestringrequired
  • colorstring (enum)required

    One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • archivedbooleanrequired
  • peopleintegerrequired

    People tagged for it.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • position_idstringrequired

    1–100 characters.

  • namestring

    1–80 characters.

  • colorstring (enum)

    One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • archivedboolean

Returns

  • idstringrequired
  • namestringrequired
  • colorstring (enum)required

    One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • archivedbooleanrequired
  • peopleintegerrequired

    People tagged for it.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_assign on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • person_idstringrequired

    1–100 characters.

  • position_idsstring[]required

    1–100 characters. Up to 100 items.

Returns

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • position_idsstring[]required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"]}'
Response
{
  "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_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • archivedboolean

Returns

  • itemsobject[]required
    8 fields
    • idstringrequired
    • namestringrequired
    • startstringrequired
    • endstringrequired
    • break_minutesintegerrequired
    • colorstring (enum)required

      One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • position_idstring | nullrequired
    • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/templates.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • namestringrequired

    1–80 characters.

  • startstringrequired

    Pattern ^([01]\d|2[0-3]):[0-5]\d$.

  • endstringrequired

    At or before start: ends the next day.

    Pattern ^([01]\d|2[0-3]):[0-5]\d$.

  • break_minutesinteger

    From 0 to 240. Default 0.

  • colorstring (enum)

    One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo. Default "teal".

  • position_idstring | null

    1–100 characters.

Returns

8 fields
  • idstringrequired
  • namestringrequired
  • startstringrequired
  • endstringrequired
  • break_minutesintegerrequired
  • colorstring (enum)required

    One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • position_idstring | nullrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_idstringrequired

    1–100 characters.

  • namestring

    1–80 characters.

  • startstring

    Pattern ^([01]\d|2[0-3]):[0-5]\d$.

  • endstring

    Pattern ^([01]\d|2[0-3]):[0-5]\d$.

  • break_minutesinteger

    From 0 to 240.

  • colorstring (enum)

    One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • position_idstring | null

    1–100 characters.

  • archivedboolean

Returns

8 fields
  • idstringrequired
  • namestringrequired
  • startstringrequired
  • endstringrequired
  • break_minutesintegerrequired
  • colorstring (enum)required

    One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • position_idstring | nullrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • rota_idstring

    1–100 characters.

Returns

  • itemsobject[]required
    5 fields
    • idstringrequired
    • namestringrequired
    • rota_idstring | nullrequired
    • shiftsobject[]required
      6 fields
      • weekdayintegerrequired
      • startstringrequired
      • endstringrequired
      • break_minutesintegerrequired
      • position_idstring | nullrequired
      • personobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
    • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_create on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • namestringrequired

    1–80 characters.

  • keep_peopleboolean

    Default true.

Returns

  • idstringrequired
  • namestringrequired
  • rota_idstring | nullrequired
  • shiftsobject[]required
    6 fields
    • weekdayintegerrequired
    • startstringrequired
    • endstringrequired
    • break_minutesintegerrequired
    • position_idstring | nullrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_delete on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_week_idstringrequired

    1–100 characters.

Returns

  • idstringrequired
  • deletedtruerequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_get on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • rota_idstringrequired

    1–100 characters.

  • weekstring

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

Returns

13 fields
  • rotaobjectrequired
    16 fields
    • idstringrequired
    • namestringrequired
    • kind"location" | "team"required
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • timezonestringrequired
    • countrystring | nullrequired
    • membersintegerrequired

      People on the rota today.

    • extra_membersobject[]required

      Borrowed staff (editors only; empty for others).

      2 fields
      • idstringrequired
      • namestringrequired
    • editors_mode"default" | "custom"required

      default: the team's leads up the tree (team rotas), HR only (location rotas).

    • editorsobject[]required

      Who besides owners, admins and HR plans and publishes it.

      2 fields
      • idstringrequired
      • namestringrequired
    • opening_hoursstring | nullrequired
    • archivedbooleanrequired
    • access"edit" | "read"required

      edit: you plan it (drafts, publish, requests); read: you see what is published.

    • created_atstringrequired
    • updated_atstringrequired
  • weekstringrequired
  • startstringrequired
  • daysobject[]required
    2 fields
    • datestringrequired
    • weekdayintegerrequired
  • access"edit" | "read"required
  • statusobjectrequired
    4 fields
    • versionintegerrequired

      0: never published.

    • published_atstring | nullrequired
    • published_byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • changesintegerrequired

      Draft changes not published yet (editors; 0 for others).

  • peopleobject[]required
    6 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • planned_minutesintegerrequired
    • contract_minutesinteger | nullrequired

      What the work schedule expects this week (editors only).

    • position_idsstring[]required

      Positions they can work (editors only).

    • daysobject[]required

      Editors only (empty for others).

      3 fields
      • datestringrequired
      • away"full" | "am" | "pm" | "hours"required

        Approved time off ("Away"; never its type).

      • holidaystring | nullrequired
    • availabilityobject[]required

      When they said they can't work (editors only; notes stay private).

      4 fields
      • weekdayinteger | nullrequired
      • datestring | nullrequired
      • fromstring | nullrequired
      • tostring | nullrequired
  • shiftsobject[]required

    Editors: the draft; others: what is published.

    10 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired

      Local time; at or before start: the shift ends the next day.

    • break_minutesintegerrequired
    • minutesintegerrequired

      Planned work: the shift minus its break.

    • personobject | nullrequired

      null: an open shift.

      2 fields
      • idstringrequired
      • namestringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • notestring | nullrequired

      Editors and the shift's person; null for others.

    • template_idstring | nullrequired
  • findingsobject[]required

    Law checks on the draft (editors only).

    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • changesobject[]required

    What publishing would change (editors only).

    7 fields
    • shift_idstringrequired
    • datestringrequired
    • kind"added" | "removed" | "changed"required
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • beforeobject | nullrequired
      3 fields
      • startstringrequired
      • endstringrequired
      • personobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
    • afterobject | nullrequired
      3 fields
      • startstringrequired
      • endstringrequired
      • personobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
    • inside_noticebooleanrequired

      The shift (before or after) starts inside the notice window: publishing records a reason.

  • publish_bystring | nullrequired

    The day to publish by so the week goes out with the notice (week start minus notice days; editors only).

  • notice_daysinteger | nullrequired
  • notice_source"law" | "company"required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_check on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • rota_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

Returns

  • findingsobject[]required
    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • blocksintegerrequired
  • reasonsintegerrequired
  • warningsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_fill on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • mode"schedules" | "copy" | "template"required
  • from_weekstring

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • from_rota_idstring

    1–100 characters.

  • template_week_idstring

    1–100 characters.

  • replaceboolean

    Default false.

Returns

  • addedintegerrequired
  • skipped_leaveintegerrequired
  • skipped_holidayintegerrequired
  • skipped_otherintegerrequired
  • weekobjectrequired
    13 fields
    • rotaobjectrequired
      16 fields
      • idstringrequired
      • namestringrequired
      • kind"location" | "team"required
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • timezonestringrequired
      • countrystring | nullrequired
      • membersintegerrequired

        People on the rota today.

      • extra_membersobject[]required

        Borrowed staff (editors only; empty for others).

        2 fields
        • idstringrequired
        • namestringrequired
      • editors_mode"default" | "custom"required

        default: the team's leads up the tree (team rotas), HR only (location rotas).

      • editorsobject[]required

        Who besides owners, admins and HR plans and publishes it.

        2 fields
        • idstringrequired
        • namestringrequired
      • opening_hoursstring | nullrequired
      • archivedbooleanrequired
      • access"edit" | "read"required

        edit: you plan it (drafts, publish, requests); read: you see what is published.

      • created_atstringrequired
      • updated_atstringrequired
    • weekstringrequired
    • startstringrequired
    • daysobject[]required
      2 fields
      • datestringrequired
      • weekdayintegerrequired
    • access"edit" | "read"required
    • statusobjectrequired
      4 fields
      • versionintegerrequired

        0: never published.

      • published_atstring | nullrequired
      • published_byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • changesintegerrequired

        Draft changes not published yet (editors; 0 for others).

    • peopleobject[]required
      6 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • planned_minutesintegerrequired
      • contract_minutesinteger | nullrequired

        What the work schedule expects this week (editors only).

      • position_idsstring[]required

        Positions they can work (editors only).

      • daysobject[]required

        Editors only (empty for others).

        3 fields
        • datestringrequired
        • away"full" | "am" | "pm" | "hours"required

          Approved time off ("Away"; never its type).

        • holidaystring | nullrequired
      • availabilityobject[]required

        When they said they can't work (editors only; notes stay private).

        4 fields
        • weekdayinteger | nullrequired
        • datestring | nullrequired
        • fromstring | nullrequired
        • tostring | nullrequired
    • shiftsobject[]required

      Editors: the draft; others: what is published.

      10 fields
      • idstringrequired
      • datestringrequired
      • startstringrequired
      • endstringrequired

        Local time; at or before start: the shift ends the next day.

      • break_minutesintegerrequired
      • minutesintegerrequired

        Planned work: the shift minus its break.

      • personobject | nullrequired

        null: an open shift.

        2 fields
        • idstringrequired
        • namestringrequired
      • positionobject | nullrequired
        3 fields
        • idstringrequired
        • namestringrequired
        • colorstring (enum)required

          One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

      • notestring | nullrequired

        Editors and the shift's person; null for others.

      • template_idstring | nullrequired
    • findingsobject[]required

      Law checks on the draft (editors only).

      8 fields
      • codestring (enum)required

        One 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"required

        info; 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 | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • shift_idsstring[]required
      • datestringrequired
      • messagestringrequired

        The rule, the numbers and the article, in English.

      • lawstring | nullrequired
      • valuesobjectrequired
        2 fields
        • actualnumber | nullrequired
        • limitnumber | nullrequired
    • changesobject[]required

      What publishing would change (editors only).

      7 fields
      • shift_idstringrequired
      • datestringrequired
      • kind"added" | "removed" | "changed"required
      • personobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • beforeobject | nullrequired
        3 fields
        • startstringrequired
        • endstringrequired
        • personobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
      • afterobject | nullrequired
        3 fields
        • startstringrequired
        • endstringrequired
        • personobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
      • inside_noticebooleanrequired

        The shift (before or after) starts inside the notice window: publishing records a reason.

    • publish_bystring | nullrequired

      The day to publish by so the week goes out with the notice (week start minus notice days; editors only).

    • notice_daysinteger | nullrequired
    • notice_source"law" | "company"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_create on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • datestringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • template_idstring

    1–100 characters.

  • startstring

    Pattern ^([01]\d|2[0-3]):[0-5]\d$.

  • endstring

    At or before start: ends the next day.

    Pattern ^([01]\d|2[0-3]):[0-5]\d$.

  • break_minutesinteger

    From 0 to 240.

  • person_idstring | null

    null: an open shift.

    1–100 characters.

  • position_idstring | null

    1–100 characters.

  • notestring | null

    Job tier: who covers what, never health or personal reasons.

    Up to 200 characters.

Returns

  • shiftobject | nullrequired
    10 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired

      Local time; at or before start: the shift ends the next day.

    • break_minutesintegerrequired
    • minutesintegerrequired

      Planned work: the shift minus its break.

    • personobject | nullrequired

      null: an open shift.

      2 fields
      • idstringrequired
      • namestringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • notestring | nullrequired

      Editors and the shift's person; null for others.

    • template_idstring | nullrequired
  • findingsobject[]required

    What the checks say about the people of this shift this week (blocks are refused).

    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • changesintegerrequired

    Draft changes not published yet.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_update on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • shift_idstringrequired

    1–100 characters.

  • startstring

    Pattern ^([01]\d|2[0-3]):[0-5]\d$.

  • endstring

    At or before start: ends the next day.

    Pattern ^([01]\d|2[0-3]):[0-5]\d$.

  • break_minutesinteger

    From 0 to 240.

  • person_idstring | null

    null: an open shift.

    1–100 characters.

  • position_idstring | null

    1–100 characters.

  • notestring | null

    Job tier: who covers what, never health or personal reasons.

    Up to 200 characters.

Returns

  • shiftobject | nullrequired
    10 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired

      Local time; at or before start: the shift ends the next day.

    • break_minutesintegerrequired
    • minutesintegerrequired

      Planned work: the shift minus its break.

    • personobject | nullrequired

      null: an open shift.

      2 fields
      • idstringrequired
      • namestringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • notestring | nullrequired

      Editors and the shift's person; null for others.

    • template_idstring | nullrequired
  • findingsobject[]required

    What the checks say about the people of this shift this week (blocks are refused).

    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • changesintegerrequired

    Draft changes not published yet.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_move on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • shift_idstringrequired

    1–100 characters.

  • datestring

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • person_idstring | null

    1–100 characters.

  • copyboolean

    Default false.

Returns

  • shiftobject | nullrequired
    10 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired

      Local time; at or before start: the shift ends the next day.

    • break_minutesintegerrequired
    • minutesintegerrequired

      Planned work: the shift minus its break.

    • personobject | nullrequired

      null: an open shift.

      2 fields
      • idstringrequired
      • namestringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • notestring | nullrequired

      Editors and the shift's person; null for others.

    • template_idstring | nullrequired
  • findingsobject[]required

    What the checks say about the people of this shift this week (blocks are refused).

    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • changesintegerrequired

    Draft changes not published yet.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_delete on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • shift_idstringrequired

    1–100 characters.

Returns

  • shiftobject | nullrequired
    10 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired

      Local time; at or before start: the shift ends the next day.

    • break_minutesintegerrequired
    • minutesintegerrequired

      Planned work: the shift minus its break.

    • personobject | nullrequired

      null: an open shift.

      2 fields
      • idstringrequired
      • namestringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • notestring | nullrequired

      Editors and the shift's person; null for others.

    • template_idstring | nullrequired
  • findingsobject[]required

    What the checks say about the people of this shift this week (blocks are refused).

    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • changesintegerrequired

    Draft changes not published yet.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_suggest on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • rota_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • shift_idstringrequired

    1–100 characters.

Returns

  • shiftobjectrequired
    10 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired

      Local time; at or before start: the shift ends the next day.

    • break_minutesintegerrequired
    • minutesintegerrequired

      Planned work: the shift minus its break.

    • personobject | nullrequired

      null: an open shift.

      2 fields
      • idstringrequired
      • namestringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • notestring | nullrequired

      Editors and the shift's person; null for others.

    • template_idstring | nullrequired
  • candidatesobject[]required

    Up to 10 items.

    6 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • planned_minutesintegerrequired
    • contract_minutesinteger | nullrequired
    • below_minutesinteger | nullrequired
    • whystringrequired
    • notesstring[]required

      Information findings (a holiday, night work).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_publish on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • weeksinteger

    From 1 to 4. Default 1.

  • acknowledge_warningsboolean

    Default false.

  • reasonobject
    2 fields
    • kind"agreed" | "asked" | "force_majeure" | "short_change" | "other"required

      agreed (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.

    • notestring

      Private: required for other; the people concerned and HR see it.

      1–500 characters.

Returns

  • weeksobject[]required
    7 fields
    • weekstringrequired
    • publishedbooleanrequired
    • versionintegerrequired
    • changesintegerrequired
    • toldintegerrequired

      People told (in the app, and by email where allowed).

    • findingsobject[]required
      8 fields
      • codestring (enum)required

        One 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"required

        info; 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 | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • shift_idsstring[]required
      • datestringrequired
      • messagestringrequired

        The rule, the numbers and the article, in English.

      • lawstring | nullrequired
      • valuesobjectrequired
        2 fields
        • actualnumber | nullrequired
        • limitnumber | nullrequired
    • inside_noticeintegerrequired

      Changes inside the notice window.

  • blockedbooleanrequired

    Something always blocks: nothing was published (the findings at level block say what).

  • needs_ackbooleanrequired

    Warnings need acknowledge_warnings true.

  • needs_reasonbooleanrequired

    Rest findings or changes inside the notice need a reason.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
  }
}'
Response
{
  "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_history on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • rota_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

Returns

  • versionsobject[]required
    8 fields
    • versionintegerrequired
    • source"publish" | "request" | "leave" | "leaver"required
    • atstringrequired
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • changesobject[]required
      7 fields
      • shift_idstringrequired
      • datestringrequired
      • kind"added" | "removed" | "changed"required
      • personobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • beforeobject | nullrequired
        3 fields
        • startstringrequired
        • endstringrequired
        • personobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
      • afterobject | nullrequired
        3 fields
        • startstringrequired
        • endstringrequired
        • personobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
      • inside_noticebooleanrequired

        The shift (before or after) starts inside the notice window: publishing records a reason.

    • shiftsintegerrequired
    • reasonobject | nullrequired
      2 fields
      • kind"agreed" | "asked" | "force_majeure" | "short_change" | "other"required
      • notestring | nullrequired
    • acknowledgedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • scope"mine" | "to_decide" | "all"

    Default "mine".

  • status"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"

Returns

  • itemsobject[]required
    17 fields
    • idstringrequired
    • kind"swap" | "give_away" | "claim"required
    • status"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"required
    • rotaobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • weekstringrequired
    • shiftobject | nullrequired

      The shift asked about (null when it no longer exists).

      5 fields
      • idstringrequired
      • datestringrequired
      • startstringrequired
      • endstringrequired
      • positionobject | nullrequired
        3 fields
        • idstringrequired
        • namestringrequired
        • colorstring (enum)required

          One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • fromobjectrequired

      Who asks: claim, the person who wants the open shift; swap and give away, whose shift it is.

      2 fields
      • idstringrequired
      • namestringrequired
    • toobject | nullrequired

      swap: the colleague asked; give away: who took it.

      2 fields
      • idstringrequired
      • namestringrequired
    • other_shiftobject | nullrequired

      swap: the colleague's shift offered in exchange.

      5 fields
      • idstringrequired
      • datestringrequired
      • startstringrequired
      • endstringrequired
      • positionobject | nullrequired
        3 fields
        • idstringrequired
        • namestringrequired
        • colorstring (enum)required

          One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • messagestring | nullrequired

      Private: the two people and HR in the app; null for others and machines.

    • findingsobject[]required

      The checks for both people as it would be approved (editors, on requests waiting for them).

      8 fields
      • codestring (enum)required

        One 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"required

        info; 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 | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • shift_idsstring[]required
      • datestringrequired
      • messagestringrequired

        The rule, the numbers and the article, in English.

      • lawstring | nullrequired
      • valuesobjectrequired
        2 fields
        • actualnumber | nullrequired
        • limitnumber | nullrequired
    • can_acceptbooleanrequired
    • can_cancelbooleanrequired
    • can_decidebooleanrequired
    • starts_atstringrequired
    • created_atstringrequired
    • decided_atstring | nullrequired
  • waiting_for_meintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_create on My Workplace, HR Assistant
Preview
?dry_run=true runs 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"required
  • rota_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • shift_idstringrequired

    1–100 characters.

  • with_person_idstring

    1–100 characters.

  • with_rota_idstring

    1–100 characters.

  • with_weekstring

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • with_shift_idstring

    1–100 characters.

  • messagestring

    1–500 characters.

Returns

17 fields
  • idstringrequired
  • kind"swap" | "give_away" | "claim"required
  • status"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"required
  • rotaobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • weekstringrequired
  • shiftobject | nullrequired

    The shift asked about (null when it no longer exists).

    5 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • fromobjectrequired

    Who asks: claim, the person who wants the open shift; swap and give away, whose shift it is.

    2 fields
    • idstringrequired
    • namestringrequired
  • toobject | nullrequired

    swap: the colleague asked; give away: who took it.

    2 fields
    • idstringrequired
    • namestringrequired
  • other_shiftobject | nullrequired

    swap: the colleague's shift offered in exchange.

    5 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • messagestring | nullrequired

    Private: the two people and HR in the app; null for others and machines.

  • findingsobject[]required

    The checks for both people as it would be approved (editors, on requests waiting for them).

    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • can_acceptbooleanrequired
  • can_cancelbooleanrequired
  • can_decidebooleanrequired
  • starts_atstringrequired
  • created_atstringrequired
  • decided_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_accept on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

Returns

17 fields
  • idstringrequired
  • kind"swap" | "give_away" | "claim"required
  • status"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"required
  • rotaobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • weekstringrequired
  • shiftobject | nullrequired

    The shift asked about (null when it no longer exists).

    5 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • fromobjectrequired

    Who asks: claim, the person who wants the open shift; swap and give away, whose shift it is.

    2 fields
    • idstringrequired
    • namestringrequired
  • toobject | nullrequired

    swap: the colleague asked; give away: who took it.

    2 fields
    • idstringrequired
    • namestringrequired
  • other_shiftobject | nullrequired

    swap: the colleague's shift offered in exchange.

    5 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • messagestring | nullrequired

    Private: the two people and HR in the app; null for others and machines.

  • findingsobject[]required

    The checks for both people as it would be approved (editors, on requests waiting for them).

    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • can_acceptbooleanrequired
  • can_cancelbooleanrequired
  • can_decidebooleanrequired
  • starts_atstringrequired
  • created_atstringrequired
  • decided_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_cancel on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • request_idstringrequired

    1–100 characters.

Returns

17 fields
  • idstringrequired
  • kind"swap" | "give_away" | "claim"required
  • status"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"required
  • rotaobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • weekstringrequired
  • shiftobject | nullrequired

    The shift asked about (null when it no longer exists).

    5 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • fromobjectrequired

    Who asks: claim, the person who wants the open shift; swap and give away, whose shift it is.

    2 fields
    • idstringrequired
    • namestringrequired
  • toobject | nullrequired

    swap: the colleague asked; give away: who took it.

    2 fields
    • idstringrequired
    • namestringrequired
  • other_shiftobject | nullrequired

    swap: the colleague's shift offered in exchange.

    5 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • messagestring | nullrequired

    Private: the two people and HR in the app; null for others and machines.

  • findingsobject[]required

    The checks for both people as it would be approved (editors, on requests waiting for them).

    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • can_acceptbooleanrequired
  • can_cancelbooleanrequired
  • can_decidebooleanrequired
  • starts_atstringrequired
  • created_atstringrequired
  • decided_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_approve on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • whystring | null

    Optional: 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
  • idstringrequired
  • kind"swap" | "give_away" | "claim"required
  • status"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"required
  • rotaobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • weekstringrequired
  • shiftobject | nullrequired

    The shift asked about (null when it no longer exists).

    5 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • fromobjectrequired

    Who asks: claim, the person who wants the open shift; swap and give away, whose shift it is.

    2 fields
    • idstringrequired
    • namestringrequired
  • toobject | nullrequired

    swap: the colleague asked; give away: who took it.

    2 fields
    • idstringrequired
    • namestringrequired
  • other_shiftobject | nullrequired

    swap: the colleague's shift offered in exchange.

    5 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • messagestring | nullrequired

    Private: the two people and HR in the app; null for others and machines.

  • findingsobject[]required

    The checks for both people as it would be approved (editors, on requests waiting for them).

    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • can_acceptbooleanrequired
  • can_cancelbooleanrequired
  • can_decidebooleanrequired
  • starts_atstringrequired
  • created_atstringrequired
  • decided_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_decline on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • request_idstringrequired

    1–100 characters.

  • whystring | null

    Optional: 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
  • idstringrequired
  • kind"swap" | "give_away" | "claim"required
  • status"offered" | "pending" | "approved" | "declined" | "cancelled" | "expired"required
  • rotaobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • weekstringrequired
  • shiftobject | nullrequired

    The shift asked about (null when it no longer exists).

    5 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • fromobjectrequired

    Who asks: claim, the person who wants the open shift; swap and give away, whose shift it is.

    2 fields
    • idstringrequired
    • namestringrequired
  • toobject | nullrequired

    swap: the colleague asked; give away: who took it.

    2 fields
    • idstringrequired
    • namestringrequired
  • other_shiftobject | nullrequired

    swap: the colleague's shift offered in exchange.

    5 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

  • messagestring | nullrequired

    Private: the two people and HR in the app; null for others and machines.

  • findingsobject[]required

    The checks for both people as it would be approved (editors, on requests waiting for them).

    8 fields
    • codestring (enum)required

      One 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"required

      info; 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 | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shift_idsstring[]required
    • datestringrequired
    • messagestringrequired

      The rule, the numbers and the article, in English.

    • lawstring | nullrequired
    • valuesobjectrequired
      2 fields
      • actualnumber | nullrequired
      • limitnumber | nullrequired
  • can_acceptbooleanrequired
  • can_cancelbooleanrequired
  • can_decidebooleanrequired
  • starts_atstringrequired
  • created_atstringrequired
  • decided_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • rest_hard_blockbooleanrequired

    Rest findings block publishing instead of needing a recorded reason.

  • auto_approve_claimsbooleanrequired

    Claims of open shifts that pass every check are approved at once.

  • notice_daysintegerrequired

    Days' 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[]required

    The PT mapa de horário's fields, for each location in Portugal (Código do Trabalho art. 215).

    2 fields
    • locationobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • countrystringrequired
    • fieldsobjectrequired
      10 fields
      • employer_namestring | nullrequired

        Up to 200 characters.

      • activitystring | nullrequired

        Up to 200 characters.

      • caestring | nullrequired

        Up to 200 characters.

      • seat_addressstring | nullrequired

        Up to 200 characters.

      • workplace_addressstring | nullrequired

        Up to 200 characters.

      • closing_daystring | nullrequired

        Up to 200 characters.

      • mandatory_rest_daystring | nullrequired

        Up to 200 characters.

      • complementary_rest_daystring | nullrequired

        Up to 200 characters.

      • irctstring | nullrequired

        Up to 200 characters.

      • adaptabilitystring | nullrequired

        Up to 200 characters.

  • savedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • rest_hard_blockboolean
  • auto_approve_claimsboolean
  • notice_daysinteger

    From 1 to 60.

  • mapaobject

Returns

  • rest_hard_blockbooleanrequired

    Rest findings block publishing instead of needing a recorded reason.

  • auto_approve_claimsbooleanrequired

    Claims of open shifts that pass every check are approved at once.

  • notice_daysintegerrequired

    Days' 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[]required

    The PT mapa de horário's fields, for each location in Portugal (Código do Trabalho art. 215).

    2 fields
    • locationobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • countrystringrequired
    • fieldsobjectrequired
      10 fields
      • employer_namestring | nullrequired

        Up to 200 characters.

      • activitystring | nullrequired

        Up to 200 characters.

      • caestring | nullrequired

        Up to 200 characters.

      • seat_addressstring | nullrequired

        Up to 200 characters.

      • workplace_addressstring | nullrequired

        Up to 200 characters.

      • closing_daystring | nullrequired

        Up to 200 characters.

      • mandatory_rest_daystring | nullrequired

        Up to 200 characters.

      • complementary_rest_daystring | nullrequired

        Up to 200 characters.

      • irctstring | nullrequired

        Up to 200 characters.

      • adaptabilitystring | nullrequired

        Up to 200 characters.

  • savedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
    }
  }
}'
Response
{
  "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_print on My Workplace, HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–100 characters.

  • weekstringrequired

    Pattern ^(\d{4})-W(0[1-9]|[1-4]\d|5[0-3])$.

  • weeksinteger

    From 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

  • fileobjectrequired
    6 fields
    • namestringrequired
    • content_typestringrequired
    • encoding"utf8" | "base64"required
    • contentstringrequired
    • bytesintegerrequired
    • sha256stringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_home on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • publish_byobject[]required

    Weeks not published yet, with the day to publish by (week start minus the notice).

    4 fields
    • rotaobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • weekstringrequired
    • bystringrequired
    • overduebooleanrequired
  • open_shiftsintegerrequired

    Open shifts in the next 14 days (published or in a draft), incl. those opened by approved leave.

  • requestsintegerrequired

    Swaps, give-aways and claims waiting for you.

  • over_48integerrequired

    People 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
curl https://api.bizisy.com/v1/shifts/home \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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.

Developer docs