Mapping

Mapping is how your integration learns which record in your system corresponds to which record in 7shifts. Store a 7shifts ID against each of your own locations, departments, roles, and users, then use those IDs on every request you send.

You need four mappings, in this order: location, department, role, user. Each one depends on the one before it.

7shifts account structure

A company contains locations. A location contains departments. A department contains roles. A user is assigned to one or more roles, across one or more locations and departments.

graph TD
    C[Company] --> L1[Location]
    C --> L2[Location]
    L1 --> D1[Department]
    L1 --> D2[Department]
    L1 --> R3[Role<br/>department_id = 0]
    D1 --> R1[Role]
    D2 --> R2[Role]
    R1 --> U[User]
    R2 --> U
    R3 --> U

Two structural cases will break an integration that assumes a strict tree:

• A role can belong directly to a location with no department. These roles return department_id of 0. Send 0 for department_id when you create records against them.
• A user can be assigned to a department without holding a role in it.

Use user for the API object and employee for the person. The API returns users.

Authentication

Every example below uses an access token. See Authentication for how to create one and for the OAuth client alternative.

Replace {ACCESS_TOKEN} with your token and {COMPANY_ID} with your company's numeric ID. It is recommended to send the x-api-version header on every request as tokens carry a default version.

Map locations

Build a UI that lets a user pair each location in your system with a 7shifts location, then store the 7shifts location ID against your own record.

Fetch the list of locations to populate a dropdown:

curl --request GET \
  --url 'https://api.7shifts.com/v2/company/{COMPANY_ID}/locations' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'x-api-version: 2026-01-01'

A dropdown of location names is better than a free-text ID field. Users know their restaurant by name, not by ID, and typed IDs produce silent mismappings that surface weeks later as sales or punches posted to the wrong location.

Map departments

Store both the department ID and the ID of the location it belongs to. Make the location explicit in the mapping UI, since department names repeat across locations.

curl --request GET \
  --url 'https://api.7shifts.com/v2/company/{COMPANY_ID}/departments' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'x-api-version: 2026-01-01'

If your system has no concept of departments, skip this UI. Instead, store the department_id returned with each role alongside that role's ID.

Map roles

Store the role ID, the department ID, and the location ID. Show the user which location and department the roles belong to.

curl --request GET \
  --url 'https://api.7shifts.com/v2/company/{COMPANY_ID}/roles' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'x-api-version: 2026-01-01'

A department_id of 0 means the role hangs off the location directly. Carry the 0 through to any records you create for that role.

Map users

Store the user ID plus the locations, departments, and roles the user is assigned to. User mapping is not scoped to a single location, because one user can work across several.

curl --request GET \
  --url 'https://api.7shifts.com/v2/company/{COMPANY_ID}/users' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'x-api-version: 2026-01-01'

{
  "data": [
    {
      "id": 1111,
      "active": true
    },
    {
      "id": 1112,
      "active": false
    }
  ],
  "meta": {
    "cursor": {
      "current": "",
      "prev": null,
      "next": null,
      "count": 11
    }
  },
  "object": "users"
}

Map on the id field. The response also contains punch_id and employee_id; neither is the mapping key.

By default this endpoint returns active users only. Use the active=false parameter to retrieve inactive ones. An inactive user cannot be mapped until a manager reactivates the employee in 7shifts.

Then fetch each user's role assignments:

curl --request GET \
  --url 'https://api.7shifts.com/v2/company/{COMPANY_ID}/users/USER_ID/role_assignments' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'x-api-version: 2026-01-01'

Mapping order

graph LR
    A[Map locations] --> B[Map departments]
    B --> C[Map roles]
    C --> D[Map users]
    B -.-> E[No departments<br/>in your system?<br/>Store department_id<br/>from each role]
    E -.-> C

Error responses

Handle 404 on a previously mapped ID as a stale mapping rather than a fatal error. Locations, roles, and users get removed in 7shifts without your system being told.