Shiftbase MCP by usefulapi

The Shiftbase account this API key belongs to: company, country, time zone, working-day start/end, plan facts. GET /accounts.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List employees (users) with their teams and departments, contact details, employee number, start/end dates and plus-min hours balance. Use it to map user ids in schedules, timesheets and absences to names. Identity, bank and birth data are never returned. GET /users.

{
  "type": "object",
  "properties": {
    "active": {
      "description": "true = only active employees, false = only inactive. Default: both.",
      "type": "boolean"
    },
    "department_id": {
      "description": "Only employees of this department.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "include_hidden": {
      "description": "Also include hidden users.",
      "type": "boolean"
    },
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One employee by user id or email address, with teams and departments. GET /users/{identifier}.

{
  "type": "object",
  "properties": {
    "user_id": {
      "description": "Shiftbase user id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "email": {
      "description": "Or the employee's email address.",
      "type": "string",
      "maxLength": 254,
      "pattern": "^[^\\s@/?#]+@[^\\s@/?#]+\\.[^\\s@/?#]+$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List departments (sites/branches that own teams, shifts and schedules) with address and timesheet/clocking settings. GET /departments.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List teams (the rows of the schedule within a department), optionally for one department. GET /teams.

{
  "type": "object",
  "properties": {
    "department_id": {
      "description": "Only teams of this department.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List active locations (addresses that group departments). GET /locations.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List shift types (the templates a scheduled shift uses: name, short name, default start/end time and break), optionally for one department. Their ids are the shift_id for shiftbase_create_roster. GET /shifts.

{
  "type": "object",
  "properties": {
    "department_id": {
      "description": "Only shift types of this department.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "include_deleted": {
      "description": "Also include deleted shift types.",
      "type": "boolean"
    },
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the schedule (rosters = shifts assigned to employees) for a date range of at most 62 days: date, start/end time, break, employee, team, shift type, department, published state, hours and cost. Each item's occurrence_id identifies it for shiftbase_get_roster and shiftbase_update_roster. GET /rosters.

{
  "type": "object",
  "properties": {
    "min_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First date (yyyy-mm-dd)."
    },
    "max_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last date (yyyy-mm-dd), at most 62 days after min_date."
    },
    "user_id": {
      "description": "Only shifts of this employee.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "department_id": {
      "description": "Only shifts in this department.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "required": [
    "min_date",
    "max_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One scheduled shift by its occurrence_id, with the employee, shift type, team and who created/changed it. GET /rosters/{occurrenceId}.

{
  "type": "object",
  "properties": {
    "occurrence_id": {
      "type": "string",
      "maxLength": 40,
      "description": "The occurrence_id from shiftbase_list_rosters: \"<roster id>\" or, for a recurring shift, \"<roster id>:<yyyy-mm-dd>\"."
    }
  },
  "required": [
    "occurrence_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List open (unassigned) shifts that employees can pick up, for a date range of at most 62 days (default: today). Needs the Basic plan or higher. GET /open_shifts.

{
  "type": "object",
  "properties": {
    "min_date": {
      "description": "First date (yyyy-mm-dd). Give both dates or neither (= today).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "max_date": {
      "description": "Last date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "department_id": {
      "description": "Only open shifts in this department.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "user_id": {
      "description": "Only open shifts this employee can take.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Employee availability (available / unavailable, all day or from a time) for a date range of at most 62 days, from Shiftbase's availability report. Needs the Basic plan and the "View reports" permission. POST /reports/availability (export json; reads only).

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First date (yyyy-mm-dd)."
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last date (yyyy-mm-dd), at most 62 days after from."
    },
    "user_id": {
      "description": "Only this employee.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "department_ids": {
      "description": "Only these departments.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "statuses": {
      "description": "Only these availability types.",
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Available all day",
          "Available from",
          "Unavailable all day",
          "Unavailable from"
        ]
      }
    },
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "required": [
    "from",
    "to"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List timesheets (worked hours: clock in/out, breaks, total, status Approved/Declined/Pending, wage and surcharges) for a date range of at most 62 days. GET /timesheets.

{
  "type": "object",
  "properties": {
    "min_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First date (yyyy-mm-dd)."
    },
    "max_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last date (yyyy-mm-dd), at most 62 days after min_date."
    },
    "user_id": {
      "description": "Only this employee.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "department_id": {
      "description": "Only this department.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "description": "Only timesheets with this status.",
      "type": "string",
      "enum": [
        "Approved",
        "Declined",
        "Pending"
      ]
    },
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "required": [
    "min_date",
    "max_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One timesheet by id, with its clocked breaks. GET /timesheets/{timesheetId}.

{
  "type": "object",
  "properties": {
    "timesheet_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Shiftbase timesheet id."
    }
  },
  "required": [
    "timesheet_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Who is clocked in right now: employee, since when, their scheduled shift, team, department and location. GET /timesheets/clock.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List absences (leave, sick leave, other time off) overlapping a date range of at most 366 days: employee, absence type, start/end date, hours or days, status Approved/Declined/Pending and who reviewed it. Needs the Basic plan. GET /absentees.

{
  "type": "object",
  "properties": {
    "min_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First date (yyyy-mm-dd)."
    },
    "max_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last date (yyyy-mm-dd), at most 366 days after min_date."
    },
    "user_id": {
      "description": "Only this employee.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "description": "Only absences with this status (Pending = requests waiting for review).",
      "type": "string",
      "enum": [
        "Approved",
        "Declined",
        "Pending"
      ]
    },
    "absence_type_ids": {
      "description": "Only these absence types (ids from shiftbase_list_absence_types).",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "only_open_ended": {
      "description": "Only open-ended absences (no end date yet, e.g. long-term sick leave).",
      "type": "boolean"
    },
    "include": {
      "description": "Add related data: the per-day breakdown, the employee or the absence type.",
      "type": "string",
      "enum": [
        "AbsenteeDay",
        "User",
        "AbsenteeOption"
      ]
    },
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "required": [
    "min_date",
    "max_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One absence by id, with the per-day hours and who reviewed it. GET /absentees/{absenteeId}.

{
  "type": "object",
  "properties": {
    "absence_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Shiftbase absence (absentee) id."
    }
  },
  "required": [
    "absence_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List absence types (e.g. Holiday, Sick, Unpaid leave): name, unit (hours or days), whether it costs leave hours, colour. Their ids are the absence_type_id for absences. GET /absentee_options.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Results per page, 1-200 (default 50). The reply's total and next_offset show what is left.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "offset": {
      "description": "Index of the first result; pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

How many hours an absence would cost for an employee, per day and in total (from the schedule or the contract, per the absence policy), for a period of at most 366 days. Changes nothing. POST /absentees/expected.

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The employee."
    },
    "absence_type_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Absence type id (shiftbase_list_absence_types)."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day (yyyy-mm-dd)."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day (yyyy-mm-dd)."
    }
  },
  "required": [
    "user_id",
    "absence_type_id",
    "start_date",
    "end_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: put one employee on the schedule for one date (a single, non-recurring shift) in a team, with a shift type, start/end time and break. The employee is notified only when notify is true. POST /rosters.

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date of the shift (yyyy-mm-dd)."
    },
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The employee to schedule."
    },
    "department_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Department of the team."
    },
    "team_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Team (shiftbase_list_teams)."
    },
    "shift_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Shift type (shiftbase_list_shift_types)."
    },
    "start_time": {
      "type": "string",
      "description": "Start, 24-hour hh:mm (e.g. 09:00)."
    },
    "end_time": {
      "type": "string",
      "description": "End, 24-hour hh:mm (e.g. 17:30); earlier than start = ends the next day."
    },
    "break_minutes": {
      "description": "Unpaid break in minutes (default 0).",
      "type": "integer",
      "minimum": 0,
      "maximum": 1440
    },
    "paid_break_minutes": {
      "description": "Paid break in minutes (default 0).",
      "type": "integer",
      "minimum": 0,
      "maximum": 1440
    },
    "description": {
      "description": "Note shown on the shift.",
      "type": "string",
      "maxLength": 2000
    },
    "notify": {
      "description": "Notify the employee (default false).",
      "type": "boolean"
    }
  },
  "required": [
    "date",
    "user_id",
    "department_id",
    "team_id",
    "shift_id",
    "start_time",
    "end_time"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: change a scheduled shift: move it to another date, time, employee, team or shift type, or change its break or note. Reads the shift first and sends it back with your changes. For a recurring shift, scope says what changes: "occurrence" (this date only), "sequence" (this date and all later ones) or "original" (the whole series; also the right scope for a non-recurring shift). PUT /rosters/{occurrenceId}/{scope}.

{
  "type": "object",
  "properties": {
    "occurrence_id": {
      "type": "string",
      "maxLength": 40,
      "description": "occurrence_id from shiftbase_list_rosters."
    },
    "scope": {
      "type": "string",
      "enum": [
        "original",
        "occurrence",
        "sequence"
      ],
      "description": "\"original\" for a non-recurring shift; see the description for recurring ones."
    },
    "date": {
      "description": "New date (yyyy-mm-dd).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "user_id": {
      "description": "New employee.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "department_id": {
      "description": "New department (when moving to a team of another department).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "team_id": {
      "description": "New team.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "shift_id": {
      "description": "New shift type.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "start_time": {
      "description": "New start, hh:mm.",
      "type": "string"
    },
    "end_time": {
      "description": "New end, hh:mm.",
      "type": "string"
    },
    "break_minutes": {
      "description": "New unpaid break in minutes.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1440
    },
    "paid_break_minutes": {
      "description": "New paid break in minutes.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1440
    },
    "description": {
      "description": "New note.",
      "type": "string",
      "maxLength": 2000
    },
    "notify": {
      "description": "Notify the employee (default false).",
      "type": "boolean"
    }
  },
  "required": [
    "occurrence_id",
    "scope"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: add an absence (leave/time-off request) for an employee. By default it is a Pending request for a manager to review; status Approved books it directly (needs the approve-absence permission). The hours per day come from Shiftbase's own expected-hours calculation (the same as shiftbase_get_expected_absence_hours). Needs the Basic plan. POST /absentees.

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The employee."
    },
    "absence_type_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Absence type id (shiftbase_list_absence_types)."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day (yyyy-mm-dd)."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day (yyyy-mm-dd), at most 366 days after start_date."
    },
    "note": {
      "description": "Note from the requester.",
      "type": "string",
      "maxLength": 2000
    },
    "status": {
      "description": "Pending (default) = a request to review; Approved = book it directly.",
      "type": "string",
      "enum": [
        "Pending",
        "Approved"
      ]
    },
    "notify_employee": {
      "description": "Notify the employee (default false).",
      "type": "boolean"
    }
  },
  "required": [
    "user_id",
    "absence_type_id",
    "start_date",
    "end_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: approve or decline an absence request. Reads the absence first and sends it back unchanged except for the status (needs the approve-absence permission). PUT /absentees/{absenteeId}.

{
  "type": "object",
  "properties": {
    "absence_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Absence (absentee) id, e.g. from shiftbase_list_absences with status Pending."
    },
    "decision": {
      "type": "string",
      "enum": [
        "Approved",
        "Declined"
      ],
      "description": "Approved or Declined."
    },
    "notify_employee": {
      "description": "Notify the employee (default false).",
      "type": "boolean"
    }
  },
  "required": [
    "absence_id",
    "decision"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}