1. Documentation
  2. Workforce Management
  3. Schedules API
  4. Guide

Schedules API Guide

Getting Started
What's New
Integration Options
Authenticating with OAuth
System Status
Identity and Access Management
Single Sign-On & SAML
Outbound Federation
Federated Authentication
Troubleshooting & FAQs
Glossary
Platform
Workforce Management
Fourth Inventory for Hotels
Fourth Inventory for Restaurants

Introduction

With the Schedules API you can retrieve the most recently published schedules in Fourth.

The returned schedule shows assigned shifts only that are published to My Schedule. Open shifts are not included in the data.

Quick Facts

API type HTTP REST with JSON
Authentication Basic Authentication
Availability All customers using Workforce Management solutions
Testing Test environment is available; however, you can test this API against live
More information

See the Reference

Get Access

To get started with this API, you will need:

  • A Schedules API account to access this API
  • The root URL for requests

Your mutual Fourth customer must request credentials on your behalf. Please ensure they do this as soon as possible. The Fourth Professional Services team member managing the integration can provide the above information and help you with any integration questions you may have.

Updates

You can find any updates on the Release Notes page for the Schedules API.

Resources

There is the one resource, shifts, which accepts GET requests.  

Timezones and shifts

The Schedules API provides shift data in UTC time. Each shift belongs to the day on which it ends; therefore if you need the shifts for a Friday night, you will need to request both Friday and Saturday's data.

Specifying a date range

You must specify a date range for your results using a pair of URL query parameters. There are two options for this.

The parameters fromDate and toDate let you get the schedule by date. The dates are inclusive. For example, to get the schedule for the first week of January 2019:

GET <ROOT>/shifts?fromDate=20180101&toDate=20180107

The parameters daysInPast and daysInFuture let you get the schedule based on the current day. The dates are inclusive. You can set the value to a positive or negative number, or to zero. For example, to get the schedule for one week including today: 

GET <ROOT>/shifts?daysInPast=0&daysInFuture=6

To get the schedule for one week starting three days in the future (-3 days in the past): 

GET <ROOT>/shifts?daysInPast=-3&daysInFuture=9

Response

Successful requests

For successful requests, Fourth responds with an HTTP 200 OK status. The response body contains the schedule broken down into individual shifts as an array. For example:

[
    {
        "externalId": "183698",
        "personnelNumber": "MOF12345",
        "locationTnAId": "8001",
        "fourthAccountId": "0058E000001hYirQAE",
        "workDate": "2019-12-29",
        "startDateTime": "2019-12-29T09:30:00:0000",
        "endDateTime": "2019-12-29T17:30:00:0000",
        "breakMinutes": 30,
        "roleName": "Manager",
        "locationName": "Acme Burgers Covent Garden",
        "departmentName": "1. Front of House"
    },
    {
        "externalId": "183719",
        "personnelNumber": "STU12435",
        "locationTnAId": "8001",
        "fourthAccountId": "0058E000002MlVnQAK",
        "workDate": "2019-12-29",
        "startDateTime": "2019-12-29T09:30:00:0000",
        "endDateTime": "2019-12-29T14:30:00:0000",
        "breakMinutes": 30,
        "roleName": "Server",
        "locationName": "Acme Burgers Covent Garden",
        "departmentName": "1. Front of House"
    },
    {
        "externalId": "183727",
        "personnelNumber": "MOY54321",
        "locationTnAId": "8001",
        "fourthAccountId": "0058E000001jqgiQAA",
        "workDate": "2019-12-29",
        "startDateTime": "2019-12-29T11:30:00:0000",
        "endDateTime": "2019-12-29T20:00:00:0000",
        "breakMinutes": 30,
        "roleName": "Bartender",
        "locationName": "Acme Burgers Covent Garden",
        "departmentName": "1. Front of House"
    },
    {
        "externalId": "183690",
        "personnelNumber": "JEN54312",
        "locationTnAId": "8001",
        "fourthAccountId": "0058E000005M8oCQAS",
        "workDate": "2019-12-29T00:00:0000",
        "startDateTime": "2019-12-29T16:00:00:0000",
        "endDateTime": "2019-12-29T23:30:00:0000",
        "breakMinutes": 30,
        "roleName": "Server",
        "locationName": "Acme Burgers Covent Garden",
        "departmentName": "1. Front of House"
    }
]

Unsuccessful requests 

Unsuccessful requests receive a standard HTTP 400-599 response, with a more detailed error in the body. 

Error code Error message Description
1001 The provided parameters are not valid. Either both fromDate and toDate or both daysInPast and daysInFuture must be provided

Your query parameters are not valid. This could be because:

  • You have not included a pair of parameters. Your options are to use fromDate and toDate together, or daysInPast and daysInFuture together.
  • The query parameters are in some way misspelled.

Troubleshooting

Questions

How does the API handle shifts that pass midnight? For example, when a shift starts at 02/01/2020 07:00pm and ends at 03/01/2020 02:00am, how do we pull data for that shift?

The 02:00 shift will show up under the next day, i.e you need to query the day of 03/01/2020 in order to see that shift. The Schedules API doesn’t deal with business days, the shift is part of the day that it ends on and in this case it is the 3rd.

My request was accepted but the response didn't include any shifts — what's wrong?

This API gets shifts that are published in My Schedules. If you stop publishing shifts to My Schedules then the API will not return any data.