Schedules API Guide

Introduction

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

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

Resources

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

Get Access

Contact your Fourth Implementation Consultant. They will provide:

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

CONTACT US

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 shiftsRequest.fromDate and shiftsRequest.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?shiftsRequest.fromDate=20180101&shiftsRequest.toDate=20180107

The parameters shiftsRequest.daysInPast and shiftsRequest.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?shiftsRequest.daysInPast=0&shiftsRequest.daysInFuture=6

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

GET <ROOT>/shifts?shiftsRequest.daysInPast=-3&shiftsRequest.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": "",
        "fourthAccountId": "acme_123456",
        "workDate": "2018-03-28",
        "startDateTime": "2018-03-28T12:00:00Z",
        "endDateTime": "2018-03-28T22:30:00Z",
        "breakMinutes": 30,
        "roleName": "Manager",
        "locationName": "Acme 8942",
        "departmentName": "1. Front of House"
    },
    {
        "externalId": "183719",
        "personnelNumber": "STU12435",
        "locationTnAId": "",
        "fourthAccountId": "acme_123456",
        "workDate": "2018-03-29",
        "startDateTime": "2018-03-29T12:00:00Z",
        "endDateTime": "2018-03-29T22:30:00Z",
        "breakMinutes": 30,
        "roleName": "Server",
        "locationName": "Acme 8942_1",
        "departmentName": "1. Front of House"
    },
    {
        "externalId": "183727",
        "personnelNumber": "MOY54321",
        "locationTnAId": "",
        "fourthAccountId": "acme_123456",
        "workDate": "2018-03-30",
        "startDateTime": "2018-03-30T12:00:00Z",
        "endDateTime": "2018-03-30T22:30:00Z",
        "breakMinutes": 30,
        "roleName": "Bartender",
        "locationName": "Acme 8942_2",
        "departmentName": "1. Front of House"
    },
    {
        "externalId": "183690",
        "personnelNumber": "JEN54312",
        "locationTnAId": "",
        "fourthAccountId": "acme_123456",
        "workDate": "2018-03-27",
        "startDateTime": "2018-03-27T12:00:00Z",
        "endDateTime": "2018-03-27T22:30:00Z",
        "breakMinutes": 30,
        "roleName": "Server",
        "locationName": "Acme 8942_1",
        "departmentName": "1. Front of House"
    }
]

Unsuccessful requests 

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