# Data Overview

Coupler.io's 7shifts integration pulls data from the 7shifts API using OAuth. You select one entity per data flow — from your organizational structure (Companies, Locations, Departments, Roles) to employee and wage records (Users, Wages, Assignments) to operational data (Shifts, Time punches) to pre-aggregated labor reports (Worked hours and wages).

## What data is available?

The integration covers four natural groups of data:

* **Organizational structure** — your company hierarchy, locations, departments, and job roles
* **Employee management** — employee profiles, pay rates, and assignments across locations and departments
* **Time & scheduling** — published shift schedules and actual clock-in/clock-out records
* **Labor reports** — pre-aggregated worked hours and wages summaries per employee, role, and day

## When to use it

Use the 7shifts integration when you need to:

* Analyze actual hours worked vs. scheduled hours for labor cost control
* Build payroll-ready time punch exports broken down by employee, role, and location
* Track staffing coverage across departments and shifts over time
* Maintain a live roster of employees and their role assignments for operations reporting

## Available entities

### Organizational structure

#### Companies

The top-level record for your 7shifts account. Most accounts have one company, but multi-brand or franchise groups may have more.

| Field      | Description                         |
| ---------- | ----------------------------------- |
| `id`       | Unique company identifier           |
| `name`     | Company name                        |
| `industry` | Industry type (e.g., Restaurant)    |
| `timezone` | Company default timezone            |
| `created`  | Date the company record was created |

#### Locations

Your physical restaurant or store locations. Each location sits under a company and has its own departments and roles.

| Field         | Description                |
| ------------- | -------------------------- |
| `id`          | Unique location identifier |
| `company_id`  | Parent company ID          |
| `name`        | Location name              |
| `address`     | Street address             |
| `city`        | City                       |
| `state`       | State or province          |
| `country`     | Country                    |
| `postal_code` | Postal or ZIP code         |
| `timezone`    | Location timezone          |
| `status`      | Active or inactive         |

#### Departments

Operational departments within a location, such as Kitchen, Front of House, or Bar.

| Field         | Description                     |
| ------------- | ------------------------------- |
| `id`          | Unique department identifier    |
| `location_id` | Parent location ID              |
| `name`        | Department name                 |
| `position`    | Sort order within the location  |
| `created`     | Date the department was created |

#### Roles

Job titles or positions that employees can be assigned to, such as Server, Cook, or Bartender.

| Field           | Description                     |
| --------------- | ------------------------------- |
| `id`            | Unique role identifier          |
| `location_id`   | Location the role belongs to    |
| `department_id` | Department the role belongs to  |
| `name`          | Role name                       |
| `color`         | Color used in the schedule view |
| `sort`          | Display order                   |
| `created`       | Date the role was created       |

### Employee management

#### Users

All employees and managers in your 7shifts account, including their personal details and account status.

| Field           | Description                        |
| --------------- | ---------------------------------- |
| `id`            | Unique user identifier             |
| `company_id`    | Parent company ID                  |
| `first_name`    | Employee first name                |
| `last_name`     | Employee last name                 |
| `email`         | Employee email address             |
| `mobile_number` | Mobile phone number                |
| `employee_id`   | External employee or payroll ID    |
| `type`          | Account type (employee or manager) |
| `status`        | Active or inactive                 |
| `hired_at`      | Hire date                          |
| `created`       | Date the user record was created   |

#### Wages

Pay rates for each employee, broken down by role and location. One employee may have multiple wage records if they work different roles at different rates.

| Field         | Description                      |
| ------------- | -------------------------------- |
| `id`          | Unique wage record identifier    |
| `user_id`     | Employee ID                      |
| `location_id` | Location the wage applies to     |
| `role_id`     | Role the wage applies to         |
| `wage`        | Pay rate amount                  |
| `wage_type`   | Wage type (hourly or salary)     |
| `created`     | Date the wage record was created |

#### Assignments

General assignment records linking an employee to a location, department, or role.

| Field           | Description                     |
| --------------- | ------------------------------- |
| `id`            | Unique assignment identifier    |
| `user_id`       | Employee ID                     |
| `location_id`   | Location ID                     |
| `department_id` | Department ID                   |
| `role_id`       | Role ID                         |
| `created`       | Date the assignment was created |

#### Location assignments

Records that authorize each employee to work at a specific location.

| Field             | Description                             |
| ----------------- | --------------------------------------- |
| `id`              | Unique record identifier                |
| `user_id`         | Employee ID                             |
| `location_id`     | Location the employee is authorized for |
| `primary_role_id` | Default role at this location           |
| `created`         | Date the assignment was created         |

#### Department assignments

Records that link employees to the departments they work in.

| Field           | Description                            |
| --------------- | -------------------------------------- |
| `id`            | Unique record identifier               |
| `user_id`       | Employee ID                            |
| `department_id` | Department the employee is assigned to |
| `location_id`   | Location context                       |
| `created`       | Date the assignment was created        |

#### Role assignments

Records that link employees to the specific roles they are qualified to perform.

| Field         | Description                                 |
| ------------- | ------------------------------------------- |
| `id`          | Unique record identifier                    |
| `user_id`     | Employee ID                                 |
| `role_id`     | Role the employee can perform               |
| `location_id` | Location context                            |
| `primary`     | Whether this is the employee's primary role |
| `created`     | Date the assignment was created             |

### Time & scheduling

#### Time punches

Clock-in and clock-out records for each employee. This is the primary entity for payroll and hours-worked analysis.

| Field           | Description                                      |
| --------------- | ------------------------------------------------ |
| `id`            | Unique time punch identifier                     |
| `user_id`       | Employee who clocked in                          |
| `location_id`   | Location where the punch was recorded            |
| `department_id` | Department the punch is attributed to            |
| `role_id`       | Role the employee worked during this punch       |
| `clocked_in`    | Clock-in timestamp                               |
| `clocked_out`   | Clock-out timestamp                              |
| `hours`         | Total hours worked (decimal)                     |
| `breaks`        | Total break time (minutes)                       |
| `status`        | Punch status (e.g., active, deleted)             |
| `approved`      | Whether the punch has been approved by a manager |

#### Shifts

Scheduled work shifts for each employee, representing planned coverage rather than actual attendance.

| Field           | Description                                         |
| --------------- | --------------------------------------------------- |
| `id`            | Unique shift identifier                             |
| `user_id`       | Employee assigned to the shift (null if open shift) |
| `location_id`   | Location for the shift                              |
| `department_id` | Department for the shift                            |
| `role_id`       | Role required for the shift                         |
| `start`         | Scheduled start timestamp                           |
| `end`           | Scheduled end timestamp                             |
| `notes`         | Manager notes on the shift                          |
| `status`        | Shift status (draft, published, deleted)            |
| `published`     | Whether the shift has been published to employees   |
| `created`       | Date the shift record was created                   |

{% hint style="info" %}
Open shifts (not yet assigned to an employee) appear in the Shifts entity with `user_id` as null. If you're calculating scheduled hours, filter to only shifts where `user_id` is not null — or keep open shifts if you want to analyze staffing gaps.
{% endhint %}

### Labor reports

#### Worked hours and wages

A pre-aggregated summary of worked hours, wages, and tips per employee per day. This entity saves you from having to join and aggregate Time punches with Wages yourself — 7shifts calculates the totals and Coupler.io exports the result directly.

| Field            | Description                            |
| ---------------- | -------------------------------------- |
| `date`           | Reporting date                         |
| `user_id`        | Employee ID                            |
| `location_id`    | Location where hours were worked       |
| `department_id`  | Department the hours are attributed to |
| `role_id`        | Role the employee worked               |
| `hours`          | Total hours worked                     |
| `wages`          | Total wages for the period             |
| `tips`           | Tips recorded (if applicable)          |
| `overtime_hours` | Overtime hours for the period          |

{% hint style="success" %}
Use the **Worked hours and wages** entity when you want daily labor cost totals without building complex joins. It's ideal for dashboards that display total labor spend per location, department, or employee — without needing to combine multiple entities in your destination.
{% endhint %}

## Common data combinations

| Goal                         | Configuration                                                                                                  |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Quick labor cost report      | **Worked hours and wages** — pre-aggregated daily totals per employee and role, no joins required              |
| Payroll hours report         | Time punches + Users (join on `user_id`) — shows hours per employee per pay period                             |
| Detailed labor cost analysis | Time punches + Wages (join on `user_id` and `role_id`) — multiply `hours` × `wage` for punch-level granularity |
| Scheduled vs. actual hours   | Shifts + Time punches (join on `user_id`, match by date) — compare scheduled and worked hours                  |
| Employee roster              | Users + Location assignments + Role assignments — full picture of who works where                              |
| Department coverage          | Shifts filtered by `department_id` — analyze shift count and hours by department over time                     |

## Use cases by role

#### Operations manager

Pull Shifts and Time punches daily to compare scheduled vs. actual hours for each location. Use Wages data to calculate labor cost per shift and identify where costs are running over budget. Set up a daily refresh to keep your labor dashboard current for the morning standup.

#### Payroll administrator

Export Time punches at the end of each pay period using the date picker to define the exact range. Join with Users to get employee names and IDs, and with Wages to calculate gross pay by role. Combine multiple location data flows in one destination sheet using Coupler.io's data join feature.

#### General manager / multi-unit operator

Use Locations and Departments to build a clean org structure reference table, then join it to Time punches and Shifts for location-level reporting. Track department-level hours and labor percentages across all your locations in a single dashboard.

#### HR / workforce analyst

Pull Users, Location assignments, and Role assignments to maintain an up-to-date employee roster with role qualifications. Use hire dates and status fields to track headcount changes over time and analyze turnover rates.

## Platform-specific notes

* **One entity per data flow** — Each Coupler.io data flow exports one 7shifts entity. To combine entities (e.g., Time punches + Users), create separate data flows and use Coupler.io's data join feature to merge them by a shared key like `user_id`.
* **Start date is required** — All data flows require a Start date. Data before this date will not be included. Use the date picker to set the exact start of your reporting window.
* **Early access** — The 7shifts integration is currently in early access. If you don't see it in your Coupler.io account, contact support to have it enabled.
* **Assignment entities** — Assignments, Location assignments, Department assignments, and Role assignments all describe the same concept (which employees work where and in what role) from different angles. For most reporting needs, Role assignments or Location assignments provide the clearest picture.
* **Open shifts** — Shifts without an assigned employee (`user_id` is null) represent open shifts posted for employees to claim. Include or exclude them depending on your analysis.
* **Worked hours and wages** — This report entity provides pre-computed daily labor totals. Use it for high-level dashboards. For punch-level detail (individual clock-ins, break deductions, approval status), use Time punches instead.