Check for Scheduled Shifts

Now that you have complete mapping, you will want to verify that the employee is scheduled to work when an they punch in.This section focuses on:

  • Structure of POST requests to the /shifts/scheduled endpoint
  • Setting the grace period
  • Putting it all together
  • Advanced schedule enforcement

Checking for a user’s scheduled shifts in 7shifts is handled through a POST request to the 7shifts /shifts/scheduled endpoint.

An example POST request to the /shifts/scheduled endpoint to create a sales receipt looks as follows:

Request URL

POST https://api.7shifts.com/v1/shifts/scheduled

Request body

{
    "punch_id": 123456,
    "grace_period": 30
}

Here’s an explanation of each of the fields required in the request body:

Parameter

Type

Description

punch_id

Integer

The 7shifts ID of the user clocking in (employee_id field from the users response object)

grace_period

Integer

Amount of time in minutes that the employee should be allowed to clock in before the shift is scheduled to start, i.e., number of minutes between now and end of the timeframe for finding shifts that are scheduled to start or have already started within the timeframe.

Example response

{
    "status": "success",
    "data": {
        "scheduled": true,
        "shift": {
            "id": 123456789
        },
        "role": {
            "id": 98765,
            "name": "Server"
        }
    },
    "message": ""
}

Below is an explanation of each of the fields in the response:

Parameter

Type

Description

scheduled

Boolean

The field you really need to look at — whether the user is scheduled in 7shifts or not.

shift.id

Integer

ID of the scheduled shift

role.id

Integer

ID of the role that the shift is scheduled for.

role.name

String

Name of the role that the shift is scheduled for.

Setting the grace period

The grace period is an interval defined in minutes that specifies the time window between now and the X defined number of minutes into the future within which 7shifts should look for scheduled shifts for the user.

Consider a shift that is scheduled to start at 4:00 PM and end at 5:00 PM, as an example. Setting different lengths of grace periods will have the following effects on clocking in at the shown example times (i.e., will return a shift to determine whether user should be allowed to clock in):

Since the grace_period field will need to be specified in the request body, you will need to create a setting in the UI which will allow the admin in your system to define this grace period. You can then use this saved setting value from your system for every request you make to the /shifts/scheduled endpoint.

A few things to note about the grace period:

  • This grace period only exists within the context of each individual request, so it must be specified in the body of every request.
  • If the current time of making the request is already past the starting time of the shift, but the shift still hasn’t ended, the shift will be returned in the response no matter what you set the grace period to.
  • The grace period cannot be defined any higher than 60 minutes.

Putting it all together

Now that the structure of the request and the concept of grace period has been covered, it’s time to put it all together.

These requests will need to be made to the 7shifts API at the of a user clocking in. This is what a simple flow would look like, for example, if an employee is clocking in exactly at the scheduled shift start time:

  • User clocks in on your system.
  • Your system makes a request to the /shifts/scheduled endpoint.
  • The response you receive contains a shift.
  • Employee’s clock-in action is completed on your system.

You may also want to build failure logic for times when your system isn’t able to reach the 7shifts API, as this schedule enforcement integration won’t be effective in that event.

For such cases, you may want to mark any clock-ins that happened with an incomplete schedule enforcement in some way within your system to denote the admin/manager that schedule enforcement did not take place for that clock-in.


Did this page help you?