Rosterfy API

The Rosterfy REST API lets you read and write the same records the console works with — people, events, shifts, forms, training, role offers and the rest — so you can keep another system in step with Rosterfy without anyone re-keying anything.

Every account is reached on its own hostname, the one you sign in on:

https://<your-account>.rosterfy.com/api/v2

Accounts on a regional deployment use the domain they sign in on instead of rosterfy.com. Whichever it is, the /api/v2 prefix and everything after it is the same.

Every endpoint except the token exchange itself expects an OAuth 2 bearer token:

Authorization: Bearer <access_token>

You get one by posting your client credentials and a user's sign-in details to POST /api/v2/oauth/token — the first operation in the reference. The token carries exactly that user's access, so use a dedicated integration user rather than a person's own login: the integration keeps working when people come and go, and its activity stays distinguishable in the audit trail.

Access tokens last 30 days. The refresh token issued alongside lives longer and can be exchanged for a new access token by calling the same endpoint again with grant_type=refresh_token. Refresh before the access token lapses rather than after — once it has expired there is nothing left to refresh.

Treat the access token the way you would treat the password you exchanged for it. Anything holding it has that user's access for as long as it lives.

The guides describe conventions that hold across every endpoint, and they will save you working them out one endpoint at a time:

• Errors and status codes — including why the API answers 404 where you might expect 403.
• Filtering, sorting and pagination — the query parameters every listing endpoint shares.
• Request options — the _options envelope that changes how a write is carried out.
• Rate limits — the two windows that apply, and what happens when you exceed one.
• Webhooks — how to be told about a change instead of polling for it.

• Paths are singular and kebab-case: /api/v2/user, not /api/v2/users.
• Query parameters and JSON keys are lower_snake_case.
• Related records are never included unless you ask for them with with.
• Listing endpoints share one set of parameters — page, sort, filter, with, extras — documented per endpoint and explained in full in the guides.