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

GET https://api.7shifts.com/v1/users?limit=50

With the additional limit URL query parameter, this request will return the alphabetically-first 50 active users. To avoid excessive resource consumption, please ensure that limit doesn’t exceed 50.

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:

Parameter

Type

Description

location_id

Integer

ID of the location that the users you are looking for are assigned to.

department_id

Integer

ID of the department that the users you are looking for are assigned to.

role_id

Integer

ID of the role that the users you are looking for are assigned to.

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:

Parameter

Type

Description

active

Boolean

Setting this to 0 will return only inactive users.
Setting this to 1 will return only active users.
Setting this to 0,1 will return active & 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:

GET https://api.7shifts.com/v1/users?limit=50&location_id=98765&department_id=24680&role_id=13579&active=0,1

Page through responses

Finally, in the response, you may notice that you only see the 50 users that match the filter criteria you specified in the URL query parameters. This is because our API supports “pagination” by using the offset & limit URL query parameters together to get the remaining results.
These parameters are described below:

Parameter

Type

Description

limit

Integer

Maximum number of objects you want in the response (min = 1, max = 50).

offset

Integer

Number of objects you want to offset the result by (default = 0).

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 assigned to location 98765 (results #1-#50):

GET https://api.7shifts.com/v1/users?limit=50&offset=0&location_id=98765

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

GET https://api.7shifts.com/v1/users?limit=50&offset=50&location_id=98765

Finally, the following request will return the last 37 users (results #101-137):

GET https://api.7shifts.com/v1/users?limit=50&offset=100&location_id=98765

When the number of returned user objects in the response is less than the limit, that’s how you can determine for certain that the end of the results list 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

{
    "status": "success",
    "total": 3,
    "offset": 0,
    "limit": 50,
    "data": [
        {
            "user": {
                "id": 2351418,
                "firstname": "Bertram",
                "lastname": "Gilfoyle",
                "user_type_id": 1,
                "email": "[email protected]",
                "mobile_phone": "(555) 555-5555",
                "home_phone": "(777) 777-7777",
                "payroll_id": 83745270,
                "employee_id": 2329,
                "active": false,
                ...
            }
        },
        {
            "user": {
                "id": 2645543,
                "firstname": "Dinesh",
                "lastname": "Chugtai",
                "user_type_id": 1,
                "email": "[email protected]",
                "payroll_id": 98643832,
                "employee_id": 5057,
                "active": false,
                ...
            }
        },
        {
            "user": {
                "id": 2789647,
                ...
            }
        },
    ]
}

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:

Parameter

Type

Description

id

Integer

ID that is essentially the index ID of the user in 7shifts.

firstname

String

First name of the user.

lastname

String

Last name of the user.

user_type_id

Integer

Value specifies type of the user in 7shifts:
1 – Employee, 2 – Administrator, 3 – Manager, 4 – Assistant Manager

email

String

Email address of the user

mobile_phone

Integer

Mobile phone number of the user.

home_phone

Integer

Home phone number of the user.

payroll_id

Integer

Payroll ID of the user, specified as “Employee ID” field in the 7shifts UI.

employee_id

Integer

Punch ID of the user, not to be confused with the above field.

active

Boolean

Specifies whether the user is currently active in 7shifts or not.

A few things to note:

  • Please do not read the hourly_wage or wage_type fields on the user object. These fields will not always display the current wage values, and it is strongly recommended that you implement the requests specified in the next sections for getting current wage data.
  • payroll_id & employee_id fields can be confusing, given that they have different names in the UI.
  • To clarify, employee_id is represented in the UI as ‘Punch ID’, and this is the ID that users use for time clocking through the 7punches app.
  • payroll_id is represented in the UI as ‘Employee ID’, and this is the Payroll ID for their payroll provider, which is often used for payroll integrations.

Find User Assignment

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.

Since the mapping will have already been completed by this point, the 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 (replace 12345 with the user’s ID):

Request

GET https://api.7shifts.com/v1/roles?user_id=12345

Response

{
    "status": "success",
    "total": 2,
    "offset": 0,
    "limit": 250,
    "data": [
        {
            "role": {
                "id": 13579,
                "location_id": 24680,
                "department_id": 36953,
                "name": "Bartender",
                ...
            },
            "station": []
        },
        {
            "role": {
                "id": 13591,
                "location_id": 24682,
                "department_id": 36917,
                "name": "Host",
                ...
            },
            "station": []
        }
    ]
}

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

Parameter

Type

Description

id

Integer

ID of the role that the user is assigned to.

name

String

Name of the role that the user is assigned to.

location_id

Integer

ID of the location that the role belongs to.

department_id

Integer

ID of the department that the role belongs to.

Every role object will have information on which location (location_id) & department (department_id) it belongs to. 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.


Did this page help you?