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>

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

List users in your organization and view their team memberships.

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",
      "teams": [{ "id": 1, "name": "Support" }]
    }
  ]
}

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