-1.Overview

-1.1.Introduction

This developer portal will walk you through the steps required for accessing your data via the Findmyshift API.

-1.2.Authentication techniques

Authentication can be achieved in one of two ways.

  1. By passing an API key with each request, or;
  2. 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.

-1.3.HTTP methods

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.

-1.4.Rate limiting

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.

-2.Getting started

-2.1.Register an account

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

-2.2.Set up your applications

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).

-2.3.Add some test data

If you've registered an account you can add in a pre-populated test team for testing purposes.

-3.Authentication

-3.1.Using an API key

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

-3.2.Using OAuth 2.0

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 URIhttps://www.findmyshift.com/oauth2-login
Token URIhttps://www.findmyshift.com/oauth2-token
Refresh Token URIhttps://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:
POSThttps://www.findmyshift.com/oauth2-token?client_id=YOUR-CLIENT-ID&client_secret=YOUR-CLIENT-SECRET&code=ACCESS-CODE&grant_type=authorization_code

-4.API reference

-4.1.Facilities: List

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.
URIhttps://www.findmyshift.com/api/1.4/facilities/list
Argument Type Required Default Description
teamId text The team.
curl https://www.findmyshift.com/api/1.4/facilities/list -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

-4.2.Facilities: Get

Get a single facility.
Properties will be returned as NULL when the authenticated user does not have permission to view them.
URIhttps://www.findmyshift.com/api/1.4/facilities/get
Argument Type Required Default Description
teamId text The team.
facilityId text The facility.
curl https://www.findmyshift.com/api/1.4/facilities/get -d apiKey=APIKEY -d teamId=TEAMID -d facilityId=FACILITYID
Log in to try it

-4.3.Staff: List

Get a list of staff members 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.
URIhttps://www.findmyshift.com/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.com/api/1.4/staff/list -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

-4.4.Staff: Get

Gets a single staff member.
Properties will be returned as NULL when the authenticated user does not have permission to view them.
URIhttps://www.findmyshift.com/api/1.4/staff/get
Argument Type Required Default Description
teamId text The team.
staffId text The employee.
curl https://www.findmyshift.com/api/1.4/staff/get -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID
Log in to try it

-4.5.Staff: Update

Updates an existing staff member, or adds a new staff member if required.
URIhttps://www.findmyshift.com/api/1.4/staff/update
Argument Type Required Default Description
teamId text The team.
staffId text The employee to update. If missing, an employee will be selected by matching on the first name and last name, or by matching on the email address. If no employee is found, a new employee 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 employee to add and edit all employees.
manager yes/no Allow the employee to manage the shifts of all employees.
timeOffManager yes/no Allow the employee to view, edit and approve the time off of all employees.
timesheetManager yes/no Allow the employee to view, edit and approve the timesheets of all employees.
reportViewer yes/no Allow the employee to access sensitive reports regarding staff pay and their hours.
selfScheduler yes/no Allow the employee to edit their own shifts.
displayOnRoster yes/no Display the employee on the team.
style text Colour and font styles (CSS).
notes text Administrator only notes to display on the employee's profile.
curl https://www.findmyshift.com/api/1.4/staff/update -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

-4.6.Teams: List

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.
URIhttps://www.findmyshift.com/api/1.4/teams/list

This method accepts no parameters.

curl https://www.findmyshift.com/api/1.4/teams/list -d apiKey=APIKEY
Log in to try it

-4.7.Teams: Get

Get a single team.
Properties will be returned as NULL when the authenticated user does not have permission to view them.
URIhttps://www.findmyshift.com/api/1.4/teams/get
Argument Type Required Default Description
teamId text The team.
curl https://www.findmyshift.com/api/1.4/teams/get -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

-4.8.Teams: Last modified

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 members, facilities, settings, etc.).
URIhttps://www.findmyshift.com/api/1.4/teams/last-modified
Argument Type Required Default Description
teamId text The team being queried.
curl https://www.findmyshift.com/api/1.4/teams/last-modified -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

-4.9.Time clock: Clock in

Clock in an staff member.
URIhttps://www.findmyshift.com/api/1.4/time-clock/clock-in
Argument Type Required Default Description
teamId text The team.
staffId text The employee.
photo text A photo of the clock in event encoded as a base64 string.
latitude number The latitude of the employee being clocked in.
longitude number The longitude of the employee being clocked in.
self yes/no no When "yes", the employee will appear to have clocked themself in, otherwise it will appear they were clocked in by the authenticated user.
curl https://www.findmyshift.com/api/1.4/time-clock/clock-in -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID
Log in to try it

-4.10.Time clock: Clock out

Clock out an staff member.
URIhttps://www.findmyshift.com/api/1.4/time-clock/clock-out
Argument Type Required Default Description
teamId text The team.
staffId text The employee being clocked out.
photo text A photo of the clock out event encoded as a base64 string.
latitude number The latitude of the employee being clocked out.
longitude number The longitude of the employee being clocked out.
self yes/no no When "yes", the employee will appear to have clocked themself out, otherwise it will appear they were clocked out by the authenticated user.
curl https://www.findmyshift.com/api/1.4/time-clock/clock-out -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID
Log in to try it

-4.11.Time clock: Clock out all

Clock out all staff members who are currently clocked in.
URIhttps://www.findmyshift.com/api/1.4/time-clock/clock-out-all
Argument Type Required Default Description
teamId text The team which the employees belong to.
curl https://www.findmyshift.com/api/1.4/time-clock/clock-out-all -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

-4.12.Time clock: Import

Import a time clock entry for a staff member.
URIhttps://www.findmyshift.com/api/1.4/time-clock/import
Argument Type Required Default Description
teamId text The team.
staffId text The employee.
clockIn date/time The date/time that the employee clocked in.
clockOut date/time The date/time that the employee clocked out.
clockInLatitude number The latitude where the employee clocked in.
clockOutLatitude number The latitude where the employee clocked out.
clockInLongitude number The longitude where the employee clocked in.
clockOutLongitude number The longitude where the employee clocked out.
self yes/no no
curl https://www.findmyshift.com/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

-4.13.Time clock: Status

Get the current time clock status of a one or more staff members.
URIhttps://www.findmyshift.com/api/1.4/time-clock/status
Argument Type Required Default Description
teamId text The team.
staffId text The employee. If missing all employees will be queried.
curl https://www.findmyshift.com/api/1.4/time-clock/status -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

-4.14.Time off: List

Get a list of time off records visible to the authenticated user.
URIhttps://www.findmyshift.com/api/1.4/time-off/list
Argument Type Required Default Description
teamId text The team.
staffId text The employee. If missing all employees will be queried.
from date/time The first date to query.
to date/time The last date to query.
curl https://www.findmyshift.com/api/1.4/time-off/list -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

-4.15.Time off: Get

Get a single time off record.
URIhttps://www.findmyshift.com/api/1.4/time-off/get
Argument Type Required Default Description
teamId text The team.
timeOffId text The time off.
curl https://www.findmyshift.com/api/1.4/time-off/get -d apiKey=APIKEY -d teamId=TEAMID -d timeOffId=TIMEOFFID
Log in to try it

-4.16.Time off: Approve

Approve a time off record.
URIhttps://www.findmyshift.com/api/1.4/time-off/approve
Argument Type Required Default Description
teamId text The team.
timeOffId text The time off.
curl https://www.findmyshift.com/api/1.4/time-off/approve -d apiKey=APIKEY -d teamId=TEAMID -d timeOffId=TIMEOFFID
Log in to try it

-4.17.Time off: Delete

Delete a time off record.
URIhttps://www.findmyshift.com/api/1.4/time-off/delete
Argument Type Required Default Description
teamId text The team.
timeOffId text The time off.
curl https://www.findmyshift.com/api/1.4/time-off/delete -d apiKey=APIKEY -d teamId=TEAMID -d timeOffId=TIMEOFFID
Log in to try it

-4.18.Time off: Unapprove

Unapprove a time off record.
URIhttps://www.findmyshift.com/api/1.4/time-off/unapprove
Argument Type Required Default Description
teamId text The team.
timeOffId text The time off.
curl https://www.findmyshift.com/api/1.4/time-off/unapprove -d apiKey=APIKEY -d teamId=TEAMID -d timeOffId=TIMEOFFID
Log in to try it

-4.19.Reports: Budget

URIhttps://www.findmyshift.com/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.com/api/1.4/reports/budget -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO
Log in to try it

-4.20.Reports: Hours

URIhttps://www.findmyshift.com/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.com/api/1.4/reports/hours -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO
Log in to try it

-4.21.Reports: Schedule vs. timesheets

URIhttps://www.findmyshift.com/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.com/api/1.4/reports/schedule-vs-timesheets -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO
Log in to try it

-4.22.Reports: Sent messages

URIhttps://www.findmyshift.com/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.com/api/1.4/reports/sent-messages -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO
Log in to try it

-4.23.Reports: Shifts

URIhttps://www.findmyshift.com/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.com/api/1.4/reports/shifts -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO
Log in to try it

-4.24.Reports: Time clock

URIhttps://www.findmyshift.com/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.com/api/1.4/reports/time-clock -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO
Log in to try it

-4.25.Reports: Time off

URIhttps://www.findmyshift.com/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.com/api/1.4/reports/time-off -d apiKey=APIKEY -d teamId=TEAMID -d from=FROM -d to=TO
Log in to try it