Read and change the schedule from your own tools: a JSON REST API protected by a key, and signed webhooks that tell you what changes. Any HTTP client will do.
Base URL
https://api.swissplanif.ch/api/v1
Authentication
Key in the Authorization header
Format
JSON, UTF-8, UTC dates
Rate
100 requests per 60 s
Checked against the code and production on November 13, 2026.
Quick start
1
Create a key
In Settings → API keys, create a key with only the permissions your integration needs. It is shown once: put it in your secret manager straight away.
2
Keep it out of the code
Your program reads the key from an environment variable, here SWISSPLANIF_TOKEN. Never write it in a repository, in a URL, or in a web page or mobile app.
3
Make a first call
List your locations with a key that carries locations:read. It is a read: it changes nothing.
Every request carries the Authorization: Bearer header followed by your key. There is no cookie and no key in the URL.
A key starts with stk_live_, followed by 64 random characters (48 bytes). We keep only its SHA-256 digest: nobody, us included, can show it to you again. If you lose it, create another one.
A key opens the data of the whole organisation, within its permissions. Creating one therefore takes an account that is allowed to manage API keys and whose access covers the whole organisation.
A revoked or expired key is refused from the very next call, with a 401. Choose its lifetime when you create it: 30, 90 (the default) or 365 days, or no expiry.
Permissions
A key carries one or more permissions. A call that needs another one is refused with a 403. Reading and writing are separate: a dashboard key never needs to write.
Base URL: https://api.swissplanif.ch/api/v1. The version is in the path: a breaking change will come under a new prefix, never as a change in place.
HTTPS only. Always write https://: a key sent in clear text must be treated as lost.
Requests and responses are JSON (UTF-8). Send Content-Type: application/json whenever there is a body.
Dates are ISO 8601 instants in UTC, ending in Z, for example 2026-11-16T07:00:00Z. An offset such as +01:00 is refused.
Identifiers are UUIDs.
An unknown field in a body is ignored, not refused.
A request body weighs 5 MB at most.
Pagination
Only the list of shifts is paginated. limit sets the page size, from 1 to 200, 50 by default. As long as the response contains a nextCursor, send it back as cursor to read the next page; null means you have read everything.
Pages are sorted by identifier. The order is stable from one page to the next, but it is not chronological: sort on start yourself if you need to.
The lists of employees, locations and positions return everything in a single response.
Objects
The four objects the API returns. A field marked “or null” can be empty.
Shift
iduuid
Identifier of the shift.
startdatetime
Start.
enddatetime
End.
breakMinutesinteger
Break, in minutes.
statusenum
State of the shift.DRAFTPUBLISHEDCOMPLETEDCANCELLED
positionIduuid
Position.
positionNamestring
Name of the position.
locationIduuid
Location.
locationNamestring
Name of the location.
employeeIduuid · or null
Person assigned; empty when the shift is assigned to nobody.
employeeFullNamestring · or null
First and last name of that person.personal data
notestring · or null
Free-text note.personal data
createdAtdatetime
Creation.
updatedAtdatetime
Last change.
Employee
iduuid
Identifier of the employee.
firstNamestring
First name.personal data
lastNamestring
Last name.personal data
emailstring · or null
E-mail address, when there is one.personal data
contractTypeenum
Type of contract.PERMANENTFIXED_TERMTEMPINTERNFREELANCE
weeklyHoursnumber
Weekly hours of the contract.
locationIdsuuid[]
Locations the person is attached to.
positionIdsuuid[]
Positions the person can hold.
Location
iduuid
Identifier of the location.
namestring
Name.
addressstring · or null
Address, when there is one.
timezonestring
IANA time zone, for example Europe/Zurich.
Position
iduuid
Identifier of the position.
namestring
Name.
colorstring
Display colour, in hexadecimal.
requiredSkillsstring[]
Skills required to hold the position.
Endpoints
Every path starts from the base URL. On top of the errors specific to each call, all of them can answer 401, 403 and 429.
GET/shiftsPermissionshifts:read
List shifts
Returns the organisation’s shifts, page by page.
from and to filter on the start time: from is included, to is excluded.
Every state is returned, cancelled shifts included: filter on status if you do not want them.
Query parameters
fromdatetime
Start of the window, included.
todatetime
End of the window, excluded.
locationIduuid
Keep only this location.
employeeIduuid
Keep only this person.
positionIduuid
Keep only this position.
limitinteger
Number of shifts per page.from 1 to 200default: 50
cursoruuid
Value of nextCursor received with the previous page.
Response
200 An object with data, an array of Shift objects, and nextCursor.
Invalid request: missing or malformed field, identifier that is not a UUID, end before start.Possible messagesValidation failedValidation failed (uuid is expected)end must be strictly after start
401Unauthorized
Key missing, unknown, revoked or expired.Possible messagesMissing Bearer tokenEmpty bearer tokenInvalid API tokenToken revokedToken expired
402Payment Required
Subscription inactive: trial ended, payment not completed or subscription lapsed. Writes are refused, reads still work; everything resumes once it is reactivated.Possible messagesVotre période d’essai est terminée. Activez un abonnement pour continuer à modifier vos données.Votre paiement n’a pas été finalisé. Terminez la souscription pour reprendre les modifications.Votre abonnement est arrivé à échéance. Réactivez-le pour continuer à modifier vos données.
403Forbidden
The key lacks the required permission. The message names the missing permission.Possible messagesMissing scope: shifts:write
404Not Found
Resource not found in your organisation. A resource from another organisation gives exactly the same answer.Possible messagesShift not foundemployee not foundposition not foundlocation not found
429Too Many Requests
Too many requests. Wait the number of seconds given by Retry-After.Possible messagesThrottlerException: Too Many Requests
A 400 comes in three shapes
Request body refused: message is Validation failed and issues lists every offending field.
List parameter refused: the body is an object whose keys are the names of the offending parameters.
400
{
"limit": [
"Too big: expected number to be <=200"
]
}
Other cases: the standard body.
400
{
"message": "end must be strictly after start",
"error": "Bad Request",
"statusCode": 400
}
A body over 5 MB is refused with a 413. A 5xx means a failure on our side: retry a read after an increasing delay; before replaying a creation, check that it did not go through.
Rate limits
100 requests per 60-second window. The counter is kept separately for each endpoint, and tied to the caller: its IP address, or its key.
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, the number of seconds before the counter resets. Beyond the limit, the response is a 429 with Retry-After.
A global ceiling per address also protects the service as a whole. It answers the same way.
429
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Webhooks
A webhook sends you a signed POST request every time an event you subscribed to happens. You set them up in Settings → Webhooks.
The address must use https://, be public, carry no credentials in the URL, and be 500 characters at most. An address that leads to a private network is refused, when you save it and again at every delivery.
The signing secret starts with whs_ and is shown once, at creation. We keep it encrypted (AES-256-GCM).
As for keys, it takes an account that is allowed to manage webhooks and whose access covers the whole organisation.
sha256= followed by the HMAC-SHA-256 digest of the raw body, in hexadecimal, computed with your secret.
X-SwissPlanif-Event
Name of the event, identical to the event field.
X-SwissPlanif-Delivery-Id
Unique id of this delivery (a UUID). Keep it to recognise a delivery you have already handled.
eventstring
Name of the event.
tenantIduuid
Identifier of your organisation.
occurredAtdatetime
Instant the request was sent, in UTC.
dataobject
Content specific to the event, described below.
Verify the signature
Read the raw body, byte for byte, before any JSON decoding.
Compute its HMAC-SHA-256 with your secret and compare it to the header with a constant-time comparison.
Refuse the request if the signature does not match, or if occurredAt is more than a few minutes old: that is your protection against the replay of an intercepted request.
Answer 2xx straight away, then process the event in the background.
Node.js, no dependency
import { createHmac, timingSafeEqual } from 'node:crypto';
const MAX_AGE_MS = 5 * 60 * 1000;
// rawBody: the request body exactly as received (string or Buffer).
export function verifyWebhook(rawBody, signatureHeader, secret) {
const expected = Buffer.from(
`sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`,
);
const received = Buffer.from(String(signatureHeader ?? ''));
if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
return null;
}
const event = JSON.parse(rawBody.toString());
const age = Math.abs(Date.now() - Date.parse(event.occurredAt));
return age <= MAX_AGE_MS ? event : null;
}
// const event = verifyWebhook(
// rawBody,
// request.headers['x-swissplanif-signature'],
// process.env.SWISSPLANIF_WEBHOOK_SECRET,
// );
// if (!event) return response.writeHead(401).end();
Delivery
One attempt per event, with no automatic retry. A response outside 2xx, a redirect, or a delay of more than 8 seconds count as a failure.
After 10 consecutive failures, the endpoint is paused. You resume it from Settings, where its delivery history stays available.
An event can therefore be lost: to know the exact state, read the API again.
Events
The content of data for each event. Identifiers refer to objects of your organisation; dates are in UTC.
shift.publishedShift published
One event per shift of the published schedule.
shiftIduuid
Shift concerned.
scheduleIduuid
Schedule the shift belongs to.
publicationIduuid
Publication that froze this shift.
employeeIduuid · or null
Person concerned.
locationIduuid
Location.
startdatetime
Start.
enddatetime
End.
weekStartdatetime
Start of the published week.
publishedAtdatetime
Instant of the publication.
shift.cancelledShift cancelled
Sent when a shift moves to the cancelled state. A deletion sends nothing.
shiftIduuid
Shift concerned.
scheduleIduuid · or null
Schedule the shift belongs to.
employeeIduuid · or null
Person concerned.
locationIduuid
Location.
startdatetime
Start.
enddatetime
End.
absence.requestedAbsence requested
absenceIduuid
Absence concerned.
employeeIduuid
Person concerned.
startdatetime
Start.
enddatetime
End.
absence.approvedAbsence approved
Approving an absence no longer cancels any shift: cancelledShifts is always 0.
absenceIduuid
Absence concerned.
cancelledShiftsinteger
Always 0.
keptShiftsinteger
Number of the person’s shifts that overlap the absence and stay in place.
absence.rejectedAbsence rejected
Sent for a refusal, and also when an absence that was already approved is withdrawn, entirely or for a single day: revoked is then true.
absenceIduuid
Absence concerned.
reasonstring
Reason typed by the manager, when there is one.depending on the casefree text
revokedboolean
true when an absence that was already approved is withdrawn.depending on the case
deletedboolean
true when the withdrawn absence was deleted.depending on the case
partialboolean
true when a single day was removed from the absence.depending on the case
restoredShiftsinteger
Number of shifts put back in place.depending on the case
removedStartdatetime
Start of the removed period.depending on the case
removedEnddatetime
End of the removed period.depending on the case
tailAbsenceIduuid · or null
Absence created for the days after the removed day, when there are any.depending on the case
swap.requestedSwap requested
swapIduuid
Swap request.
shiftIduuid
Shift concerned.
requestedByIduuid
Employee asking for the swap.
targetEmployeeIduuid · or null
Employee targeted, when the request targets one.
swap.approvedSwap approved
swapIduuid
Swap request.
swap.rejectedSwap rejected
swapIduuid
Swap request.
reasonstring
Reason typed by the manager, when there is one.depending on the casefree text
open_shift.appliedOpen-shift application
claimIduuid
Application.
shiftIduuid
Shift concerned.
employeeIduuid
Person concerned.
open_shift.assignedOpen shift assigned
claimIduuid
Application.
shiftIduuid
Shift concerned.
employeeIduuid
Person concerned.
shift_offer.sentShift offer sent
offerIduuid
Offer.
shiftIduuid
Shift concerned.
recipientsinteger
Number of people the offer was sent to.
shift_offer.claimedShift offer claimed
offerIduuid
Offer.
shiftIduuid
Shift concerned.
employeeIduuid
Person concerned.
mission.activatedMission activated
missionIduuid
Mission.
mission.completedMission completed
missionIduuid
Mission.
mission.cancelledMission cancelled
missionIduuid
Mission.
employee.skill.expiringSkill expiring
Sent once a day for every skill that expires within 30 days.
employeeSkillIduuid
The employee’s skill that is about to expire.
employeeIduuid
Person concerned.
skillIduuid
Skill.
expiresAtdatetime
Expiry date.
observedAtdatetime
Instant of the check.
noticeDaysinteger
Notice, in days.
Security
An API key opens the data of your whole organisation. These rules fit on one page: apply all of them.
On your side
01One key per integration, as few permissions as possible
A dashboard only needs to read. One key per tool lets you revoke one without cutting the others.
02The key lives in a secret manager
Never in a repository, a ticket, an e-mail or a screenshot, nor in the code of a web page or a mobile app.
03Call the API from a server
A key loaded in a browser can be read by anyone who opens the page. The API does not allow any other website to call it from a browser anyway.
04Replace your keys regularly
Create the new key, switch your integration, check, then revoke the old one. Settings shows the last call of each key.
05At the slightest doubt, revoke
Revocation takes effect at the next call. A key that leaked must be treated as read.
06Do not log the key
Mask the Authorization header in your logs, your debugging tools and your error reports.
07Verify every webhook
Signature over the raw body, constant-time comparison, old requests rejected. Before that check, trust neither the source address nor the content.
08Treat personal data as such
Names, e-mail addresses and notes fall under the Swiss FADP and the GDPR. Copy only what you need, and delete it when you no longer use it.
09Validate what you receive
A note or a reason is text typed by a person. Treat every value you receive as data, never as code or a command to run.
On our side
Only the SHA-256 digest of a key is kept; the key appears once, when it is created.
Permissions are checked on every call, and every request runs within the organisation of the key, isolated by PostgreSQL Row-Level Security.
A resource from another organisation answers like a resource that does not exist.
The creation and revocation of a key, and every write made through the API, are recorded in the audit log with the identifier of the key.
A webhook secret is encrypted at rest (AES-256-GCM).
Before every delivery, the address of a webhook is resolved and checked: HTTPS only, private networks refused, certificate verified, no redirect followed.
In production, the API serves neither an interactive console nor an OpenAPI description.
Every endpoint has a rate limit, and every response carries the HSTS and CSP security headers.
Found a vulnerability? Write to contact@swissplanif.ch. The real state of our security, gaps included, is on the Security page.
What the API does not do yet
What is missing today, so that you know before you build on it.
Reads are not logged
The audit log keeps the writes made through the API, not the read calls.
No idempotency key
Replaying a creation creates a second shift. After an outage, read before you create again.
No business check on writes
The API checks neither the overlaps nor the working-time rules the app flags.
Webhooks without retry
A failed delivery is not retried. The failure stays visible in the delivery history, in Settings.
No rotation of a webhook secret
To change the secret, delete the endpoint and create it again.
No test environment
There are only production keys. Start with a read-only key.
Unpaginated lists
Employees, locations and positions are returned in one go.