1. Home
  2. Docs
  3. Payroll / Earned Wage Access
  4. Read Time Punch Data
  5. Narrowing the Request Scope

Narrowing the Request Scope

Filtering by Time

Since you will be reading time punch data from 7shifts in the context of a specific pay period, you will want to bind the request scope to a certain timeframe.
You can do this by limiting your request to only retrieve time punches that have a clock in start time that falls within the pay period you are looking for. This can be done with the help of the following URL query parameters:

ParameterTypeExplanation
clocked_in[gte]DatetimeStart of pay period time range (always in UTC, format: yyyy-MM-dd hh:mm:ss)
clocked_in[gte]DatetimeEnd of pay period time range (always in UTC, format: yyyy-MM-dd hh:mm:ss)

Filtering by Location, Department and/or User

It is also recommended that you retrieve time punches only for a specific location, department or user 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 you want to retrieve time punches for
department_idNumericID of the department you want to retrieve time punches for
user_idNumericID of the user you want to retrieve time punches for

All the above query parameters can also be used in combination. Here’s an example request on how to get all time punches for user ID 12345 that were created at location ID 98765 for department ID 24680, on & between Aug 16 2020 and Aug 31 2020 (UTC):

GET https://api.7shifts.com/v1/time_punches?user_id=12345&location_id=98765&department_id=24680&clocked_in[gte]=2020-08-16 00:00:00&clocked_in[lte]=2020-08-31 23:59:59

Retrieve in Location Timezone

While we recommend you retrieve time punches in UTC, if you wanted to retrieve the data in the location’s local timezone as specified in 7shifts, you can do so by using the following URL query parameter:

ParameterTypeExplanation
localizedBooleanSetting this to true will return punch times in the location’s timezone specified in 7shifts

Page through responses

Finally, in the response, you may notice that you only see the 20 time punches that match the filter criteria which were created the earliest. 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 (default = 20, min = 1, max = 20)
offsetNumericNumber of objects you want to offset the result by (default = 0)

For example,

If the request finds a total of 57 time punches matching the criteria, you can make the following request to get a list of the first 20 time punches created at the location (results #1-#20):

GET https://api.7shifts.com/v1/time_punches?location_id=98765&clocked_in[gte]=2020-08-16 00:00:00&clocked_in[lte]=2020-08-31 23:59:59&limit=20&offset=0

The following request will return the next 20 time punches (results #21-#40):

GET https://api.7shifts.com/v1/time_punches?location_id=98765&clocked_in[gte]=2020-08-16 00:00:00&clocked_in[lte]=2020-08-31 23:59:59&limit=20&offset=20

Finally, the following request will return the last 17 time punches (results #41-57):

GET https://api.7shifts.com/v1/time_punches?location_id=98765&clocked_in[gte]=2020-08-16 00:00:00&clocked_in[lte]=2020-08-31 23:59:59&limit=20&offset=40

When the number of returned time punch 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.