API documentation

Overview

The ShiftPlanner REST API allows you to display your shifts on your own website or integrate them into your application. You can query shifts with the same filters available on the All shifts.

The API returns JSON and uses token-based authentication. Each request must include your API token in the request header. Tokens are only available with Premium accounts and can be can be found here.

All active groups are returned, including private groups. Make sure your API token is only shared with trusted parties.

Authentication

Every request must include an Authorization header with a Bearer token:

Authorization: Bearer <your-api-token>

Requests without a valid token receive a 401 Unauthorized response:

{"error": "Invalid or expired API token"}

To request an API token, contact ShiftPlanner support.

Shifts endpoint

GET /:account/api/v1/shifts

Returns a paginated list of shifts for your account. Without filters, the next 12 months of shifts are returned.

Filter parameters

All filter parameters are optional and can be combined freely.

Parameter

Type

Description

group_ids[]

array of integers

Filter by one or more group IDs.

months[]

array of integers

Filter by month number (1 = January … 12 = December).

years[]

array of integers

Filter by year, e.g. 2026.

weeks[]

array of integers

Filter by ISO week number (1–53).

days[]

array of integers

Filter by day of week (1 = Sunday, 2 = Monday … 7 = Saturday).

location_ids[]

array of integers

Filter by one or more location IDs.

day

date (YYYY-MM-DD)

Return shifts for a single specific date.

Pagination parameters

Parameter

Default

Description

page

1

Page number to retrieve.

per_page

500

Results per page. Maximum is 500.

Response format

The response is JSON with a shifts array and a meta object for pagination.

{
  "shifts": [
    {
      "id": 123,
      "date": "2026-05-01",
      "start_time": "09:00",
      "end_time": "17:00",
      "end_date": "2026-05-01",
      "group": {
        "id": 5,
        "name": "Morning crew"
      },
      "location": {
        "name": "Main hall",
        "address": "Kerkstraat 1, Amsterdam"
      },
      "person": {
        "name": "Jane Doe"
      },
      "remarks": "Bring your badge",
      "starred": false,
      "cancelled": false,
      "noshow": false
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 500,
    "total_pages": 1
  }
}

Field reference

Field

Description

id

Unique shift identifier.

date

Start date of the shift (YYYY-MM-DD).

start_time / end_time

Start and end time (HH:MM, 24-hour).

end_date

End date of the shift. Same as date for single-day shifts.

group

The group this shift belongs to (id + name).

location

Location name and address. null if no location is set.

person

Name of the assigned person. null if the shift is open.

remarks

Optional remarks for this shift.

starred

true if the shift is starred/highlighted.

cancelled

true if the shift has been cancelled.

noshow

true if the assigned person did not show up.

Examples

All upcoming shifts (default)

curl -H "Authorization: Bearer <token>" \
  "https://shiftplanner.org/youraccount/api/v1/shifts"

Shifts for a specific month and year

curl -H "Authorization: Bearer <token>" \
  "https://shiftplanner.org/youraccount/api/v1/shifts?months[]=5&years[]=2026"

Shifts for a specific group

curl -H "Authorization: Bearer <token>" \
  "https://shiftplanner.org/youraccount/api/v1/shifts?group_ids[]=5"

Shifts on a single date

curl -H "Authorization: Bearer <token>" \
  "https://shiftplanner.org/youraccount/api/v1/shifts?day=2026-05-01"

Paging through results

curl -H "Authorization: Bearer <token>" \
  "https://shiftplanner.org/youraccount/api/v1/shifts?years[]=2026&page=2&per_page=50"

JavaScript (fetch)

fetch('/youraccount/api/v1/shifts?months[]=5&years[]=2026', {
  headers: { 'Authorization': 'Bearer <token>' }
})
.then(r => r.json())
.then(data => console.log(data.shifts));

Error responses

HTTP status

Meaning

200 OK

Request successful.

401 Unauthorized

Missing, invalid or expired API token.

404 Not Found

Account not found.

Create a roster

User guide

Admin guide

Other