Overview

This step-by-step guide will walk you through creating a complete labor integration with 7shifts through our REST API.

📘

MAPPING NOTE

This section requires an understanding of how to map locations, departments, and roles.

Upon completion of this guide, you will have created an integration that can interact with the 7shifts platform as follows:

• Establish entity mapping between your system & 7shifts
• Create time punch data in 7shifts
• Update previously-sent time punch data

What’s in it for the client?

• Ability to see actual labor data in real time in 7shifts
• Enable 7shifts’ Engage platform, allowing employee happiness & engagement scoring
• See scheduled labor vs. worked labor variance
• Report on actual sales vs. actual labor data
• Receive break alerts if an employee hasn’t taken a break.
• See who is clocked in at any given point of time
• Communicate with the employees currently clocked in (coming soon)
• Generate late clock-in summary reports
• Add tips information into 7shifts

Requirements

• An OAuth client and company grant for a test/sandbox 7shifts account
• cURL or Postman to make test requests

Restrictions

• You may only make 10 requests per second per access token across all API endpoints
• You must create time punch data in 7shifts in near-real time for clients to be able to use the labor integration to its full extent

Functionality Overview

The labor integration involves creating a time punch in 7shifts as soon as an employee clocks in on your system. From that point on, any subsequent actions until the employee clocks out of their shift will result in updating the existing time punch in 7shifts.

The usual clock in/out flow for an employee would look as follows:

1. Clock in >> 2. Go on a break >> 3. Return from break >> 4. Clock out

Steps 2 & 3 could be repeated consequently for multiple breaks. Here’s a diagram detailing this:

You will be interacting with the following 7shifts API endpoints for building this integration:

• POST Time Punch
• GET Locations
• GET Departments
• GET Roles
• GET Users

📘

Audit report

7shifts offers a Punch Audit report that provides insight into who created, updated or deleted punches in 7shifts on The Works subscription plan & above.

With partner-led integrations, the authentication you use acts as a proxy for the oldest-existing administrator user in a 7shifts account. Hence, all actions described in this guide that are performed via the API will show as if they are being performed by the oldest-existing administrator user in the account.

If this is not ideal, we can set up an additional new admin user for the affected administrator profile, and rename the old one. This will make it clearer that the action is being performed by your integration, and not by the admin.

Please reach out to [email protected] if you need help with this, and request that the affected user’s admin profile be renamed to ‘API Integration’, and that a new admin profile be set up for the admin user.