-1.Overview

-1.1.Introduction

Welcome to the Findmyshift developer portal. Here we'll walk you through all of the steps required for accessing data from Findmyshift via our API. Working through a new API can be daunting, so we're going to ll try to make this as quick and painless as possible.

-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

Once you've registered your account you'll need to tell us a little about your application. Once we've got that we can allocate your Client ID (you'll need this to authenticate regardless of whether you use OAuth 2.0 or an API key) and Client Secret (only required for OAuth 2.0).

-2.3.Add some test data

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

-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

-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.co.uk/api/1.1/facilities/list
Argument Type Required Default Description
teamId text The team.
curl https://www.findmyshift.co.uk/api/1.1/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.co.uk/api/1.1/facilities/get
Argument Type Required Default Description
teamId text The team.
facilityId text The facility.
curl https://www.findmyshift.co.uk/api/1.1/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 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.co.uk/api/1.1/staff/list
Argument Type Required Default Description
teamId text The team.
curl https://www.findmyshift.co.uk/api/1.1/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.co.uk/api/1.1/staff/get
Argument Type Required Default Description
teamId text The team.
staffId text The staff member.
curl https://www.findmyshift.co.uk/api/1.1/staff/get -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID
Log in to try it

-4.5.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.co.uk/api/1.1/teams/list

This method accepts no parameters.

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

-4.6.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.co.uk/api/1.1/teams/get
Argument Type Required Default Description
teamId text The team.
curl https://www.findmyshift.co.uk/api/1.1/teams/get -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

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

-4.8.Time clock: Clock in

Clock in a staff member.
URIhttps://www.findmyshift.co.uk/api/1.1/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.co.uk/api/1.1/time-clock/clock-in -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID
Log in to try it

-4.9.Time clock: Clock out

Clock out a staff member.
URIhttps://www.findmyshift.co.uk/api/1.1/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.co.uk/api/1.1/time-clock/clock-out -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID
Log in to try it

-4.10.Time clock: Clock out all

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

-4.11.Time clock: Import

Import a time clock entry for a staff member.
URIhttps://www.findmyshift.co.uk/api/1.1/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.
curl https://www.findmyshift.co.uk/api/1.1/time-clock/import -d apiKey=APIKEY -d teamId=TEAMID -d staffId=STAFFID -d clockIn=CLOCKIN -d clockOut=CLOCKOUT
Log in to try it

-4.12.Time clock: Status

Get the current time clock status of a one or more staff members.
URIhttps://www.findmyshift.co.uk/api/1.1/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.co.uk/api/1.1/time-clock/status -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

-4.13.Time off: List

Get a list of time off records visible to the authenticated user.
URIhttps://www.findmyshift.co.uk/api/1.1/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.
curl https://www.findmyshift.co.uk/api/1.1/time-off/list -d apiKey=APIKEY -d teamId=TEAMID
Log in to try it

-4.14.Time off: Get

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

-4.15.Time off: Approve

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

-4.16.Time off: Delete

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

-4.17.Time off: Unapprove

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

-4.18.Reports: Budget

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

-4.19.Reports: Hours

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

-4.20.Reports: Sent messages

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

-4.21.Reports: Shifts

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

-4.22.Reports: Time off

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