Build on the Soon REST API.
Connect your own systems to the schedule. Create and publish shifts, manage staffing and assignments, work with leave requests, and read your team’s people and boards. JSON over HTTPS, with API keys scoped to what each integration needs.
On every plan, nothing extra. The Developers tab is switched on team by team: if your team doesn't have it yet, ask us.
# Set SOON_API_KEY securely in your server environment.
curl --fail-with-body "https://api.soon.works/v1/ping" \
-H "Authorization: Bearer $SOON_API_KEY"- Base URL
https://api.soon.works/v1- Format
- JSON over HTTPS, OpenAPI 3.1
- Authentication
- An API key as a bearer token
- Plans
- Every plan
- Version
- v1, in the path
- Pagination
- A cursor, up to 200 a page
- Reference
- api.soon.works/v1/docs
- Spec
- openapi.json
Checked against the live v1 spec on 2 November 2026.
27 operations, in 6 groups.
System
Check that a key works and which permissions it holds.
- GET
/pingPing authenticated API
Boards
Your team's scheduling boards.
- GET
/boardsList boards - GET
/boards/{boardId}Get board by id
Shifts
Create, read, change, publish and delete shifts and their staffing rows. Bulk editing is available where enabled for your team; check each shift’s result.
- GET
/shiftsList shifts - POST
/shiftsCreate shift - GET
/shifts/{shiftId}Get shift by id - PATCH
/shifts/{shiftId}Update shift - DELETE
/shifts/{shiftId}Delete shift - GET
/shifts/{shiftId}/staffingList staffing for shift - POST
/shifts/{shiftId}/staffingCreate staffing for shift - GET
/shifts/{shiftId}/staffing/{staffingId}Get shift staffing by id - PATCH
/shifts/{shiftId}/staffing/{staffingId}Update shift staffing - DELETE
/shifts/{shiftId}/staffing/{staffingId}Delete shift staffing - GET
/shifts/bulk/jobs/{jobId}Get a bulk edit job - POST
/shifts/bulkBulk edit shifts - POST
/shifts/{shiftId}/publishPublish shift
Assignments
Who is on which staffing row of a shift, and in what state.
- GET
/assignmentsList assignments - POST
/assignmentsCreate assignment - GET
/assignments/{assignmentId}Get assignment by id - PATCH
/assignments/{assignmentId}Update assignment status
Users
Your team's people, to read: by board or by email.
- GET
/usersList users - GET
/users/{userId}Get user by id
Leaves
Create pending leave requests, read leave and overlapping shifts, and update leave status with write permission.
- GET
/leavesList leaves - POST
/leavesCreate leave - GET
/leaves/{leaveId}Get leave by id - PATCH
/leaves/{leaveId}Update leave status - GET
/leaves/{leaveId}/overlapping-shiftsList shifts a leave overlaps
Current boundaries
- No outbound webhooks in the public v1 API. Integrations can poll supported list endpoints with date filters and pagination.
- People are read-only in v1. Add people in Soon or use directory sync (SCIM) on Enterprise.
- Leave creation starts a pending request. Approval requires an explicit choice to keep or cancel overlapping shifts.
Build your own workflows, with documented endpoints.
- 01
Authenticate with the Soon API
Check that your key works and inspect its granted permissions before building a workflow.
Uses
GET /ping - 02
Create and publish a shift with the Soon API
Read a board, create a shift and its staffing, assign people, then publish when the schedule is ready.
Uses
GET /boardsPOST /shiftsPOST /shifts/{shiftId}/staffingPOST /assignmentsPOST /shifts/{shiftId}/publishPATCH /shifts/{shiftId}GET /shifts - 03
Import shifts from your own system
Parse CSV or ERP data in your integration and create shifts. Use bulk jobs for supported edits where enabled, and check each result.
Uses
POST /shiftsGET /shifts/{shiftId}PATCH /shifts/{shiftId}POST /shifts/bulk - 04
Read assignments for payroll and calendar sync
Page through shifts and assignments for a date window to prepare your own calendar or payroll export.
Uses
GET /shiftsGET /assignments - 05
Handle rate limits and retries
Read the response headers, respect Retry-After when throttled, and check write results before retrying.
Uses
GET /ping - 06
Work with leave requests
Create a pending request, inspect overlapping shifts, and update leave status with the required write permission.
Uses
POST /leavesGET /leaves/{leaveId}/overlapping-shiftsPATCH /leaves/{leaveId}
Keep the key private. Keep access specific.
- Call the API from your server or trusted automation. Store keys in a secret manager or server environment, never in browser code, public repositories or logs.
- Use a separate key for each integration. Grant only the resource permissions it needs, start with read-only access when possible, and set an expiry.
- Revoke unused or exposed keys. The example above checks access without creating or changing schedule data.
API, connector or something already built?
| You want to | Use |
|---|---|
| Move shifts between Soon and your own system, on your own schedule | The REST API (this page) |
| Ask about the schedule from Claude or ChatGPT | Soon's MCP server: your own sign-in, no API key |
| Bring people in from your identity provider | Directory sync (SCIM), on Enterprise |
| Connect an HR or payroll system | Build with the REST API for people, schedules and leave, export hours as CSV, or discuss a custom integration on Enterprise. |
| Show shifts in people's own calendars | Google Calendar and Outlook, built in (one way, from Soon) |
Team owners create keys under Account › Developers: the API keys help article
Questions about the API.
Yes. Soon’s API v1 is a JSON REST API at https://api.soon.works/v1, documented at https://api.soon.works/v1/docs with an OpenAPI 3.1 specification. Read boards and people; manage shifts, staffing, assignments and leave with the required permissions.
Every plan; there's no separate API tier. The Developers tab is switched on team by team: if your team doesn't have it yet, ask us.
With an API key sent as a bearer token. The team owner creates keys under Account › Developers and chooses each key's permissions and expiry.
Default limits are 600 reads a minute per key and 1200 per team, and 120 writes a minute per key and 300 per team. Read the rate-limit response headers and follow Retry-After on a 429 response.
No outbound webhooks are documented in the current public v1 API. Use supported date filters and cursor pagination to poll for the data your integration needs.
You can create a pending leave request and update its status with leaves:write permission. Before approving leave, check overlapping shifts and explicitly choose whether to keep or cancel them. People remain read-only in v1.
Yes. The OpenAPI 3.1 document is public at https://api.soon.works/v1/openapi.json.