Integrations•8 min read

API Access

Build custom integrations with the SimpleStaff REST API.

Coming Soon

API Access is currently in development and not yet available. This documentation provides a preview of what's coming. We'll notify you when this feature launches!

Overview

The SimpleStaff API allows you to programmatically access and manage your scheduling data. Build custom integrations, automate workflows, or sync data with your internal systems.

Enterprise Only: Full API access is available on Enterprise plans. Pro plans have limited read-only API access.

Getting Started

Generate API Key

Go to Settings → Integrations → API and click "Generate API Key".

Copy Your Key

Copy the API key immediately—it won't be shown again. Store it securely.

Set Permissions

Choose which resources the key can access (schedules, employees, time-off, etc.).

Security Warning: Never expose your API key in client-side code or public repositories. Treat it like a password.

Authentication

Include your API key in the Authorization header:

curl https://api.simplestaff.com/v1/schedules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Base URL

https://api.simplestaff.com/v1

All API endpoints are versioned. The current version is v1.

Available Endpoints

Published weeks

GET/published-weeks— List published weeks (markers, keyed by week-start YYYY-MM-DD)

GET/published-weeks/:weekStart— Get publish state for a week

POST/published-weeks/:weekStart/publish— Publish a week (snapshots live shifts into the published view)

POST/published-weeks/:weekStart/publish-changes— Release staged edits to staff (since last publish)

Shifts

GET/shifts— List shifts

POST/shifts— Create shift

PATCH/shifts/:id— Update shift

DELETE/shifts/:id— Delete shift

Employees

GET/employees— List employees

GET/employees/:id— Get employee

GET/employees/:id/shifts— Get employee shifts

Time-Off

GET/time-off— List requests

POST/time-off— Create request

PATCH/time-off/:id/approve— Approve request

Example: Get This Week's Shifts

Request:

curl "https://api.simplestaff.com/v1/shifts?start=2024-01-15&end=2024-01-21" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "shift_abc123",
      "date": "2024-01-15",
      "start_time": "09:00",
      "end_time": "17:00",
      "employee_id": "emp_xyz789",
      "employee_name": "John Smith",
      "position": "Server",
      "location": "Downtown"
    },
    ...
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 25
  }
}

Rate Limits

Plan	Requests/Hour	Requests/Day
Pro	100	1,000
Enterprise	1,000	50,000

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset

Error Handling

The API returns standard HTTP status codes and JSON error responses:

Code	Meaning
200	Success
400	Bad request (invalid parameters)
401	Unauthorized (invalid or missing API key)
403	Forbidden (insufficient permissions)
404	Resource not found
429	Rate limit exceeded
500	Server error

Webhooks SSO Setup Export Data Enterprise Plans

Need help with API integration?

Contact Support