This developer portal will walk you through the steps required for accessing your data via the Findmyshift API.
Authentication can be achieved in one of two ways.
- By passing an API key with each request, or;
- By passing a OAuth 2.0 token.
While both methods are secure, using an API key is typically only suited for developing apps to access your own account's data. That being said, you could ask a user to provide their API key to your app before you begin making API requests, but that user experience is not as seamless as one provided by OAuth 2.0 authentication.
With OAuth 2.0, you'll redirect the user to our OAuth 2.0 login page, we'll verify their identity and send them back to your site with a token (much like an API key) which you can then use to authenticate any API requests on their behalf.
Findmyshift's API accepts either GET or POST requests for all methods. You don't need to choose one or the other, you can mix and match as you like. When using GET requests you'll naturally need to encode all of your parameters in the query string. When using POST requests you can send your parameters as form values, or you can post a JSON object with each of the parameters as properties.
We do enforce rate limiting, so be prepared to handle response codes of 429 appropriately. If requests continue to abuse the limits imposed we may temporarily disable the application/API key being used. Please be aware that some requests take longer than others, so you should always wait for requests to finish before starting another. Our API will only allow one concurrent request at a time per application/API key.
The first thing you'll need to do if you're interested in accessing our API is to register an account. Registering an account is completely free and only takes a second. If you've already got an account with Findmyshift, all you need to do is log in.
Register Log in
If you're using OAuth 2.0, you'll need to tell us a bit about your application so we can allocate your Client ID and Client Secret (both of which are required to authenticate with OAuth 2.0).
If you've registered an account you can add in a pre-populated test team for testing purposes.
There's a few different ways you can provide an API key in a request, so you'll just need to pick the method that makes most sense to you:
- Pass the API key as a query string parameter.
- Pass the API key as a form parameter.
- Pass the API key as an HTTP header.
Regardless of the method you choose to pass the API key, it should be passed in the format: apiKey=YOUR API KEY
If you're using OAuth 2.0 as your authentication method, you're going to need to that Client ID and Client Secret you set up earlier. If you haven't done it already, you'll need to set up an account and define your application. Once you've done that we'll give you a Client ID and Client Secret you'll need for authenticating users via OAuth 2.0.
Assuming you've got your Client ID and Client Secret stored safely, let's take a look at the URI's you'll need to plug in to your application:
Authorisation URI | https://www.findmyshift.com/oauth2-login |
Token URI | https://www.findmyshift.com/oauth2-token |
Refresh Token URI | https://www.findmyshift.com/oauth2-token |
So how does it all work? In short, a user comes along to your site and clicks "Do something with Findmyshift". First off, you'll check to see whether you've already got an access token for the user. If you do, you'll need to check if it's expired as you may need to get a new one by running it by our Refresh Token URI listed above. If it hasn't expired, you're good to go. If you don't have a token then you'll need to redirect the user to our Authorisation URI (with a few important parameters), so we can authenticate them, authenticate you, and redirect them back to you with a code. Once they come back with the code, you'll post it to us (server-side) and we'll exchange it for an access token.
Here's a quick example of how to exchange an authorisation code for an access token:
POST | https://www.findmyshift.com/oauth2-token?client_id=YOUR-CLIENT-ID&client_secret=YOUR-CLIENT-SECRET&code=ACCESS-CODE&grant_type=authorization_code |
Get a list of facilities for a team.
Properties will be returned as NULL when the authenticated user does not have permission to view them.
URI | https://www.findmyshift.es/api/1.4/facilities/list |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
curl https://www.findmyshift.es/api/1.4/facilities/list -d apiKey=APIKEY -d teamId=TEAMID |
Log in to try it Get a single facility.
Properties will be returned as NULL when the authenticated user does not have permission to view them.
URI | https://www.findmyshift.es/api/1.4/facilities/get |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
facilityId | text | | | The facility. |
curl https://www.findmyshift.es/api/1.4/facilities/get -d apiKey=APIKEY -d teamId=TEAMID -d facilityId=FACILITYID |
Log in to try it Get a list of staff visible to the authenticated user for a particular team.
Properties will be returned as NULL when the authenticated user does not have permission to view them.
URI | https://www.findmyshift.es/api/1.4/staff/list |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. If missing all teams will be queried. |
curl https://www.findmyshift.es/api/1.4/staff/list -d apiKey=APIKEY -d teamId=TEAMID |
Log in to try it Gets a single staff member.
Properties will be returned as NULL when the authenticated user does not have permission to view them.
URI | https://www.findmyshift.es/api/1.4/staff/get |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
staffId | text | | | The staff member. |
curl https://www.findmyshift.es/api/1.4/staff/get -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID |
Log in to try it Updates an existing staff member, or adds a new staff member if required.
URI | https://www.findmyshift.es/api/1.4/staff/update |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
staffId | text | | | The staff member to update. If missing, a staff member will be selected by matching on the first name and last name, or by matching on the email address. If no staff member is found, a new staff member will be added. |
firstName | text | | | |
lastName | text | | | |
dateStarted | date/time | | | |
dateFinished | date/time | | | |
dateOfBirth | date/time | | | |
gender | text | | | |
emailAddress | text | | | |
mobileNumber | text | | | |
alternatePhone | text | | | |
jobTitle | text | | | |
department | text | | | |
payrollId | text | | | |
administrator | yes/no | | | Allow the staff member to add and edit all staff. |
manager | yes/no | | | Allow the staff member to manage the shifts of all staff. |
timeOffManager | yes/no | | | Allow the staff member to view, edit and approve the time off of all staff. |
timesheetManager | yes/no | | | Allow the staff member to view, edit and approve the timesheets of all staff. |
reportViewer | yes/no | | | Allow the staff member to access sensitive reports regarding staff pay and their hours. |
selfScheduler | yes/no | | | Allow the staff member to edit their own shifts. |
displayOnRoster | yes/no | | | Display the staff member on the team. |
style | text | | | Colour and font styles (CSS). |
notes | text | | | Administrator only notes to display on the staff member's profile. |
curl https://www.findmyshift.es/api/1.4/staff/update -d apiKey=APIKEY -d teamId=TEAMID |
Log in to try it Get a list of teams linked to the authenticated user.
Properties will be returned as NULL when the authenticated user does not have permission to view them.
URI | https://www.findmyshift.es/api/1.4/teams/list |
This method accepts no parameters.
curl https://www.findmyshift.es/api/1.4/teams/list -d apiKey=APIKEY |
Log in to try it Get a single team.
Properties will be returned as NULL when the authenticated user does not have permission to view them.
URI | https://www.findmyshift.es/api/1.4/teams/get |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
curl https://www.findmyshift.es/api/1.4/teams/get -d apiKey=APIKEY -d teamId=TEAMID |
Log in to try it Get a team's last modification date/time (UTC). The last modification date/time is affected by any change made to the team (shifts, staff, facilities, settings, etc.).
URI | https://www.findmyshift.es/api/1.4/teams/last-modified |
Argument | Type | Required | Default | Description |
teamId | text | | | The team being queried. |
curl https://www.findmyshift.es/api/1.4/teams/last-modified -d apiKey=APIKEY -d teamId=TEAMID |
Log in to try it Clock in a staff member.
URI | https://www.findmyshift.es/api/1.4/time-clock/clock-in |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
staffId | text | | | The staff member. |
photo | text | | | A photo of the clock in event encoded as a base64 string. |
latitude | number | | | The latitude of the staff member being clocked in. |
longitude | number | | | The longitude of the staff member being clocked in. |
self | yes/no | | no | When "yes", the staff member will appear to have clocked themself in, otherwise it will appear they were clocked in by the authenticated user. |
curl https://www.findmyshift.es/api/1.4/time-clock/clock-in -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID |
Log in to try it Clock out a staff member.
URI | https://www.findmyshift.es/api/1.4/time-clock/clock-out |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
staffId | text | | | The staff member being clocked out. |
photo | text | | | A photo of the clock out event encoded as a base64 string. |
latitude | number | | | The latitude of the staff member being clocked out. |
longitude | number | | | The longitude of the staff member being clocked out. |
self | yes/no | | no | When "yes", the staff member will appear to have clocked themself out, otherwise it will appear they were clocked out by the authenticated user. |
curl https://www.findmyshift.es/api/1.4/time-clock/clock-out -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID |
Log in to try it Clock out all staff who are currently clocked in.
URI | https://www.findmyshift.es/api/1.4/time-clock/clock-out-all |
Argument | Type | Required | Default | Description |
teamId | text | | | The team which the staff belong to. |
curl https://www.findmyshift.es/api/1.4/time-clock/clock-out-all -d apiKey=APIKEY -d teamId=TEAMID |
Log in to try it Import a time clock entry for a staff member.
URI | https://www.findmyshift.es/api/1.4/time-clock/import |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
staffId | text | | | The staff member. |
clockIn | date/time | | | The date/time that the staff member clocked in. |
clockOut | date/time | | | The date/time that the staff member clocked out. |
clockInLatitude | number | | | The latitude where the staff member clocked in. |
clockOutLatitude | number | | | The latitude where the staff member clocked out. |
clockInLongitude | number | | | The longitude where the staff member clocked in. |
clockOutLongitude | number | | | The longitude where the staff member clocked out. |
self | yes/no | | no | |
curl https://www.findmyshift.es/api/1.4/time-clock/import -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID -d clockIn=CLOCKIN -d clockOut=CLOCKOUT |
Log in to try it Get the current time clock status of a one or more staff members.
URI | https://www.findmyshift.es/api/1.4/time-clock/status |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
staffId | text | | | The staff member. If missing all staff members will be queried. |
curl https://www.findmyshift.es/api/1.4/time-clock/status -d apiKey=APIKEY -d teamId=TEAMID |
Log in to try it Get a list of time off records visible to the authenticated user.
URI | https://www.findmyshift.es/api/1.4/time-off/list |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
staffId | text | | | The staff member. If missing all staff members will be queried. |
from | date/time | | | The first date to query. |
to | date/time | | | The last date to query. |
curl https://www.findmyshift.es/api/1.4/time-off/list -d apiKey=APIKEY -d teamId=TEAMID |
Log in to try it Get a single time off record.
URI | https://www.findmyshift.es/api/1.4/time-off/get |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
timeOffId | text | | | The time off. |
curl https://www.findmyshift.es/api/1.4/time-off/get -d apiKey=APIKEY -d teamId=TEAMID -d timeOffId=TIMEOFFID |
Log in to try it Approve a time off record.
URI | https://www.findmyshift.es/api/1.4/time-off/approve |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
timeOffId | text | | | The time off. |
curl https://www.findmyshift.es/api/1.4/time-off/approve -d apiKey=APIKEY -d teamId=TEAMID -d timeOffId=TIMEOFFID |
Log in to try it Delete a time off record.
URI | https://www.findmyshift.es/api/1.4/time-off/delete |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
timeOffId | text | | | The time off. |
curl https://www.findmyshift.es/api/1.4/time-off/delete -d apiKey=APIKEY -d teamId=TEAMID -d timeOffId=TIMEOFFID |
Log in to try it Unapprove a time off record.
URI | https://www.findmyshift.es/api/1.4/time-off/unapprove |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. |
timeOffId | text | | | The time off. |
curl https://www.findmyshift.es/api/1.4/time-off/unapprove -d apiKey=APIKEY -d teamId=TEAMID -d timeOffId=TIMEOFFID |
Log in to try it URI | https://www.findmyshift.es/api/1.4/reports/budget |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. If missing all teams will be queried. |
from | date/time | | | The first date to query. |
to | date/time | | | The last date to query. |
publishedShifts | yes/no | | yes | Only include shifts that have been published. |
timesheetData | yes/no | | no | Query timesheet data instead of scheduled data. |
timeOff | text | | yes | |
publicHolidays | yes/no | | yes | |
groupingInterval | text | | day | |
groupByTeam | yes/no | | yes | |
filters | text | | | |
curl https://www.findmyshift.es/api/1.4/reports/budget -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO |
Log in to try it URI | https://www.findmyshift.es/api/1.4/reports/hours |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. If missing all teams will be queried. |
from | date/time | | | The first date to query. |
to | date/time | | | The last date to query. |
publishedShifts | yes/no | | yes | Only include shifts that have been published. |
timesheetData | yes/no | | no | Query timesheet data instead of scheduled data. |
daysToInclude | text | | 0123456 | The days of the week to query. Eg. "12345" for weekdays, "06" for weekends. |
timeOff | text | | yes | |
publicHolidays | yes/no | | yes | |
filters | text | | | |
curl https://www.findmyshift.es/api/1.4/reports/hours -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO |
Log in to try it URI | https://www.findmyshift.es/api/1.4/reports/schedule-vs-timesheets |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. If missing all teams will be queried. |
from | date/time | | | The first date to query. |
to | date/time | | | The last date to query. |
publishedShifts | yes/no | | yes | Only include shifts that have been published. |
groupingInterval | text | | day | |
filters | text | | | |
curl https://www.findmyshift.es/api/1.4/reports/schedule-vs-timesheets -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO |
Log in to try it URI | https://www.findmyshift.es/api/1.4/reports/sent-messages |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. If missing all teams will be queried. |
from | date/time | | | The first date to query. |
to | date/time | | | The last date to query. |
filters | text | | | |
curl https://www.findmyshift.es/api/1.4/reports/sent-messages -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO |
Log in to try it URI | https://www.findmyshift.es/api/1.4/reports/shifts |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. If missing all teams will be queried. |
from | date/time | | | The first date to query. |
to | date/time | | | The last date to query. |
publishedShifts | yes/no | | yes | Only include shifts that have been published. |
timesheetData | yes/no | | no | Query timesheet data instead of scheduled data. |
daysToInclude | text | | 0123456 | The days of the week to query. Eg. "12345" for weekdays, "06" for weekends. |
comments | yes/no | | yes | |
times | yes/no | | yes | |
facilities | yes/no | | yes | |
groupingInterval | text | | day | |
groupByStaff | yes/no | | yes | |
filters | text | | | |
curl https://www.findmyshift.es/api/1.4/reports/shifts -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO |
Log in to try it URI | https://www.findmyshift.es/api/1.4/reports/time-clock |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. If missing all teams will be queried. |
from | date/time | | | The first date to query. |
to | date/time | | | The last date to query. |
distanceUnit | text | | Kilometres | Kilometers or miles. |
filters | text | | | |
curl https://www.findmyshift.es/api/1.4/reports/time-clock -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO |
Log in to try it URI | https://www.findmyshift.es/api/1.4/reports/time-off |
Argument | Type | Required | Default | Description |
teamId | text | | | The team. If missing all teams will be queried. |
from | date/time | | | The first date to query. |
to | date/time | | | The last date to query. |
daysToInclude | text | | 0123456 | The days of the week to query. Eg. "12345" for weekdays, "06" for weekends. |
publicHolidays | yes/no | | yes | |
groupByMonth | yes/no | | no | |
filters | text | | | |
curl https://www.findmyshift.es/api/1.4/reports/time-off -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO |
Log in to try it