1. Home
  2. Docs
  3. Employee Sync
  4. Read Employee Data
  5. Narrowing the Request Scope

Narrowing 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:

ParameterTypeExplanation
location_idNumericID of the location that the users you are looking for are assigned to
department_idNumericID of the department that the users you are looking for are assigned to
role_idNumericID 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:

ParameterTypeExplanation
activeBooleanSetting 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:

ParameterTypeExplanation
limitNumericMaximum number of objects you want in the response (min = 1, max = 50)
offsetNumericNumber 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.