These docs are for v2.2022.0501. Click to read the latest docs for v2.2023.0501.

Read Employee Data

This section focuses on:

  • Structure of GET requests to the /users endpoint:
    • Get familiar with the request you need to make to read a list of user data.
  • Narrowing the request scope:
    • Understand how you can read user data by location, by department, etc. and how to page through responses.
  • Understanding the /users response:
    • Extract relevant information on users from the response.
  • Finding user assignments:
    • Learn how to find what locations, departments & roles (LDRs) a user is assigned to in 7shifts.

GET Structure for /users

User data in 7shifts can be read through the /users endpoint, either one user at a time or by getting user data in a list. Please bear in mind that this will return all user types, including admins, managers & assistant managers.

An example GET request to the /users endpoint to list some user data looks as follows:

Request URL

curl --request GET --url 'https://api.7shifts.com/v2/company/1234/users?limit=50'

With the additional limit URL query parameter, this request will return the alphabetically-first 50 active users. The default limit is 100 users with a maximum of 500

Filtering the Request Scope

Filtering by Location, Department and/or Role

It is also recommended that you retrieve users only for a specific location, department or role at a time to make it easier for you to process the response. This can be done with the help of following URL query parameters:

NOTE: location_id, department_id and role_id filtering is currently only available on the V1 /users endpoint. They will be available in the v2 endpoint soon.

ParameterTypeDescription
location_idintegerID of the location that the users you are looking for are assigned to.
department_idintegerID of the department that the users you are looking for are assigned to.
role_idintegerID of the role that the users you are looking for are assigned to.
modified_sincedatetimeReturn users that have been modified since the specified date. In ISO8601 Format

Filtering by Active/Inactive Status

Depending on the scope of your integration, you may want to read user data not just for active 7shifts users, but for inactive users as well. You can do so by using the following boolean URL query parameter:

NOTE: active filtering is currently only available on the V1 /users endpoint. They will be available in the v2 endpoint soon.

ParameterTypeDescription
activebooleanSetting this to true will return only active users.
Setting this to false will return only inactive users.

Default is null, returning both active and inactive users.

All the above query parameters can also be used in combination. Here’s an example request on how to list the data for all active & inactive users assigned to location ID 98765, department ID 24680 and role ID 13579:

curl --request GET --url 'https://api.7shifts.com/v1/users?limit=50&location_id=98765&department_id=24680&role_id=13579'

Paginating through responses

In the response only contains the first 50 users that match the filter criteria you specified in the URL query parameters. The response payload will include a current, prev or next cursor value which can be passed in via URL parameter to retrieve the next or previous set of results

These parameters are described below:

ParameterTypeDescription
limitintegerMaximum number of objects you want in the response (min = 1, max = 50).
cursorstringThe current, prev or next cursor used to retrieve a paginated result.

For example,

If the request finds a total of 137 users matching the criteria, you can make the following request to get a list of the first 50 users (results #1-#50):

curl --request GET --url 'https://api.7shifts.com/v2/company/1234/users?limit=50'

The response payload contains a meta object that includes the cursor information.

{
    "data": [
        {...
        }
    ],
    "meta": {
        "cursor": {
            "current": "eyJpZCI6Ijg1Njg1NjYwIiwibmV4dCI6dHJ1ZX0=",
            "prev": "eyJpZCI6Ijg1NzgxNzY4IiwibmV4dCI6ZmFsc2V9",
            "next": "eyJpZCI6Ijg2MDIzMDM2IiwibmV4dCI6dHJ1ZX0=",
            "count": 50
        }
    },
    "object": "users"
}

The following request will return the next 50 users (results #51-#100):

curl --request GET -url 'https://api.7shifts.com/v2/company/1234//users?cursor=eyJpZCI6Ijg2MDIzMDM2IiwibmV4dCI6dHJ1ZX0='

To get the final set of users, extract the next cursor from the response payload.

When the number of returned user objects in the response is less than the limit, or the next cursor is null, it means that the end of the results has been reached.

Understanding the /users response

Now that you know how to make a basic request to read user data and how to use certain filters with it, let’s explore the response. We’ll use this example response to understand what fields are important:

Example Response

{
    "data": [
        {
            "user": {
                "id": 2351418,
                "first_name": "Bertram",
                "last_name": "Gilfoyle",
                "type": "employee",
                "email": "[email protected]",
                "mobile_phone": "(555) 555-5555",
                "home_phone": "(777) 777-7777",
                "payroll_id": 83745270,
                "punch_id": 2329,
                "active": true,
                ...
            }
        },
        {
            "user": {
                "id": 2645543,
                "first_name": "Dinesh",
                "lastn_ame": "Chugtai",
                "type": "employee",
                "email": "[email protected]",
                "payroll_id": 98643832,
                "employee_id": 5057,
                "active": false,
                ...
            }
        },
        {
            "user": {
                "id": 2789647,
                ...
            }
        },
    ],
        "meta": {
        "cursor": {
            "current": "",
            "prev": null,
            "next": null,
            "count": 11
        }
    },
    "object": "users"
}

Within the response, every object in the data array represents one user.

You’ll mostly be working with only a few fields in each user object in the response. Here are some details on them:

ParameterTypeDescription
idintegerID that is essentially the index ID of the user in 7shifts.
first_namestringFirst name of the user.
last_namestringLast name of the user.
typestringValue specifies type of the user in 7shifts:
employee
administrator
manager
assistant_manager
emailstringEmail address of the user
mobile_phoneintegerMobile phone number of the user.
home_phoneintegerHome phone number of the user.
employee_idintegerSpecified as “Employee ID” field in the 7shifts UI.
punch_idintegerPunch ID of the user, not to be confused with the above field.
activebooleanSpecifies whether the user is currently active in 7shifts or not.

Find User Assignments

In order to establish an understanding on which roles, departments & locations (LDR) a user needs to be assigned to on your side, you will need to read the user’s relevant LDR assignments from 7shifts.

You should have full understanding of Mapping and implemented a tracking table in your system. Your integration should know which LDRs in 7shifts corresponds to which LDRs in your system. All that is left to figure out which LDRs the user is assigned to in 7shifts so that you can mirror the assignments in your system.

The best way to find assignment info is to get the roles that a user is assigned to, and then using that to infer what department & location the user is assigned to. Here’s an example request to get a user’s assigned roles:

Request

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

Response

{
    "data": {
        "locations": [
            {
                "id": 212291,
                "name": "Location 1"
            },
            {
                "id": 210363,
                "name": "Location 2"
            }
        ],
        "departments": [
            {
                "id": 297069,
                "company_id": 1234,
                "location_id": 212291,
                "name": "Kitchen 1"
            },
            {
                "id": 300319,
                "company_id": 1234,
                "location_id": 210363,
                "name": "Kitchen 2"
            }
        ],
        "roles": [
            {
                "id": 1013849,
                "company_id": 1234,
                "location_id": 212291,
                "department_id": 297069,
                "name": "Cook",
                "is_primary": false,
                "skill_level": 2,
                "sort": 0
            },
            {
                "id": 1013850,
                "company_id": 1234,
                "location_id": 210363,
                "department_id": 300319,
                "name": "Cook",
                "is_primary": false,
                "skill_level": 2,
                "sort": 0
            }
        ]
    },
    "object": "assignments"
}

You’ll primarily need to look at the following fields in the response:

ParameterTypeDescription
locations.idintegerID of the location that the user is assigned to.
locations.namestringName of the location
departments.idintegerID of the department that the user is assigned to
departments.location_idintegerID of the location this department belongs to
departments.namestringName of the department
role.idintegerID of the role the user is assigned to
role.department_idintegerID of the department this role belongs to
role.location_idintegerID of the location this role belongs to
role.namestringName of the role that the user is assigned to.

Every assignments object will have information on the full mapping of roles, departments and roles for the user. Using the ID of every role returned, along with the respective department & location IDs, you should be able to determine the LDR assignments for a user.

Please note that you might come across some rare cases where a role has a null department_id. This would be a case of a 7shifts location simply not having any departments, and only having roles directly associated to the location.