TurnShift API Documentation - Automate Your Schedule Management

Overview

The TurnShift API lets you integrate shift scheduling into your existing workflows. Build custom integrations, automate repetitive tasks, or sync TurnShift with your internal tools.

What you can do with the API:

Manage shifts — Create, update, and delete shifts programmatically
Automate bookings — Assign team members to shifts based on your own logic
Sync teams — Keep your TurnShift teams in sync with your HR system
Build dashboards — Pull schedule data into your own reporting tools
Integrate with Slack/Discord — Create custom bots that interact with your schedules

All endpoints return JSON and use standard HTTP methods.Read = read-onlyWrite = modifies data

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer <your-api-token>

Roles and access

The token belongs to your organization, not to one person. Every request made with it has the same access as an admin: it can read and change every schedule, team and booking, including schedules that are not open. Treat it like an admin password and keep it in a secret store.

Only admins and managers can see the token in your organization settings. The member role limits what someone can do when they sign in to the dashboard, it does not limit the API token.

Admin can do everything a manager can, plus change roles.

Manager can create and edit schedules, assign anyone, and manage teams, Slack, billing and this token.

Member can book their own shifts. On an open schedule they can do everything except close it.

Quick Start

Test your API token by fetching your organization info.

curl -H "Authorization: Bearer <your-api-token>" \
  https://turnshift.app/api/v1/me

Expected response:

{
  "organization": {
    "id": 123,
    "name": "Your Organization",
    "slug": "your-org",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Common Examples

Here are curl examples for the most common API operations.

GETList all teamsRead

Fetch all teams in your organization.

curl -H "Authorization: Bearer <your-api-token>" \
  https://turnshift.app/api/v1/teams

POSTAdd a user to a teamWrite

Add a team member by email. Replace :teamId with the team ID.

curl -X POST \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"user": "john@example.com"}' \
  https://turnshift.app/api/v1/teams/1/members

GETList all shiftsRead

Fetch all shifts in your organization.

curl -H "Authorization: Bearer <your-api-token>" \
  https://turnshift.app/api/v1/shifts

POSTBook a user for a shiftWrite

Assign a user to a shift on a specific date. Add ?notify=true to send a Slack notification.

curl -X POST \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"user": "john@example.com"}' \
  https://turnshift.app/api/v1/shifts/1/bookings/2024-01-15

DELETERemove a bookingWrite

Remove a user from a shift on a specific date. Add ?notify=true to send a Slack notification.

curl -X DELETE \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"user": "john@example.com"}' \
  https://turnshift.app/api/v1/shifts/1/bookings/2024-01-15

Users Read Write

List users in your organization, see their team memberships and set their role.

GET/api/v1/users

List all users in your organization

Response:

{
  "users": [
    {
      "id": 1,
      "email": "john@example.com",
      "name": "John Doe",
      "timezone": "America/New_York",
      "role": "manager",
      "teams": [{ "id": 1, "name": "Support" }]
    }
  ]
}

PUT/api/v1/users/:userId/role

Set someone's role

:userId is a TurnShift user ID, a Slack user ID or an email address. Giving a role to a Slack person who never signed in creates their TurnShift user. The last admin cannot be demoted, promote someone else first.

Request:

{ "role": "manager" }

Response:

{
  "user": { "id": 1, "role": "manager" }
}

Example:

curl -X PUT \
  -H "Authorization: Bearer $TURNSHIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "manager"}' \
  "https://turnshift.app/api/v1/users/john@example.com/role"

Organization Read

Retrieve information about your organization.

GET/api/v1/me

Get organization information

Response:

{
  "organization": {
    "id": 123,
    "name": "Acme Inc",
    "slug": "acme-inc",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Shifts Read Write

Create, update, and delete shifts. Configure shift times, timezones, and notification settings.

GET/api/v1/shifts

List all shifts

POST/api/v1/shifts

Create a new shift

Request body:

{
  "name": "Morning Support",
  "startTime": "09:00",
  "endTime": "17:00",
  "timeZone": "Europe/Paris",
  "slackChannelId": 123
}

GET/api/v1/shifts/:shiftId

Get shift details

PUT/api/v1/shifts/:shiftId

Update a shift

DELETE/api/v1/shifts/:shiftId

Delete a shift

Bookings Read Write

Assign users to shifts on specific dates and retrieve booking schedules.

Specifying users: You can identify users by their numeric ID (e.g., 123) or email (e.g., john@example.com).

GET/api/v1/shifts/:shiftId/bookings?year=2024&month=1

Get bookings for a month

Response:

{
  "shift": { "id": 1, "name": "Support" },
  "year": 2024,
  "month": 1,
  "bookings": {
    "2024-01-15": [
      { "id": 1, "email": "john@example.com", "name": "John Doe" }
    ],
    "2024-01-16": []
  }
}

POST/api/v1/shifts/:shiftId/bookings/:date

Book a user for a shift on a specific date

Query parameters:

notify=true (optional) - Send a Slack notification to the user

Request body:

{
  "user": "john@example.com"  // or user ID: "123"
}

DELETE/api/v1/shifts/:shiftId/bookings/:date

Remove a booking

Query parameters:

notify=true (optional) - Send a Slack notification to the user

Request body:

{
  "user": "john@example.com"
}

Teams Read Write

Create, update, and delete teams. Teams group users together for shift assignments.

GET/api/v1/teams

List all teams

POST/api/v1/teams

Create a team

Request body:

{ "name": "Support Team" }

GET/api/v1/teams/:teamId

Get team details

PUT/api/v1/teams/:teamId

Update a team

DELETE/api/v1/teams/:teamId

Delete a team

Team Members Read Write

Add and remove users from teams.

Specifying users: You can identify users by their numeric ID (e.g., 123) or email (e.g., john@example.com).

GET/api/v1/teams/:teamId/members

List team members

POST/api/v1/teams/:teamId/members

Add a member to a team

Request body:

{ "user": "john@example.com" }

DELETE/api/v1/teams/:teamId/members

Remove a member from a team

Request body:

{ "user": "john@example.com" }

Error Responses

Errors return a JSON object with error and optional details:

{
  "error": "Unauthorized",
  "details": "Invalid API token"
}

Status	Meaning
400	Bad request / Validation error
401	Unauthorized (invalid or missing token)
403	Forbidden (organization blocked)
404	Resource not found
405	Method not allowed

TurnShift API v1