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 GET 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 GET request to the 7shifts /shifts_scheduled endpoint.

The request can either specify the users_id or punch_id as a URL parameter. An example GET request to the /shifts_scheduled endpoint to check if employee with 'user_id' 1111 is scheduled:

Request URL

curl --request --url GET 'https://api.7shifts.com/v2/company/1234/shifts_scheduled/1111'

Alternatively a users punch_id can be used to check if an employee is scheduled.

Request URL

curl --ruquest --url GET 'https://api.7shifts.com/v2/company/1234/shifts_scheduled/punch_id:0123'

NOTE: one of user_id or punch_id is required in the request.

Here’s an explanation of each of the path parameters available on this endpoint:

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:

📘

NOTE

This endpoint will always return with 'scheduled: false` if you're making the request over 60 minutes after the shift has already started.

For example, if a shift started at 5:00 PM, and you made a request at 6:01 PM or beyond to check if the user is scheduled for a shift, the response won't show the scheduled shift. The check must be performed within 60 minutes of the shift starting for the response to show the actual scheduled shift.

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 as a URL parameter in every request.
• if the current time is greater than the start time of a shift, but the shift still hasn't ended, the shift will be returned in the response no matter what you set for the grace period.
• 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.