Labor API: Code Cookbook

Get Completed Shifts

Backend
Labor API
cURL (Command Line)

Before you start
Permalink Get a link to this section

  • You will need an access token. If you are using OAuth, you will need TIMECARDS_WRITE permission to update a Shift and TIMECARDS_READ permission to retrieve Shifts.

  • You need to have created a Shift object using the Labor API. You can follow The Build With Labor API Guide to create your first Shift object.

Step 1: Get all closed shifts for the workweek
Permalink Get a link to this section

Requests to the SearchShifts endpoint include search filters and sorting instructions. The following request asks for all complete shifts during a 1 week pay period for the given location with the following characteristics:

  • The targeted pay period is October 1, 2018 through October 8, 2018.

  • The result is sorted on the shift creation timestamp in ascending order.

  • The results are limited to 20 shifts per response (page size).

Did you know?

Default timezone is set in the filter and used in the query when a timezone is not set in the Square Dashboard for the targeted location.


Calls to the SearchShifts endpoint must use POST:

curl https://connect.squareupsandbox.com/v2/labor/shifts/search  \
  -H 'Content-Type: application/json'                     \
  -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'   \
  -d '{
    "query": {
      "filter": {
        "location_id": ["YOUR_LOCATION_ID"],
        "workday": {
          "date_range": {
            "start_date": "2018-10-01",
            "end_date": "2018-10-08"
          },
          "default_timezone": "America/Los Angeles",
          "match_shifts_by": "START_AT"
        },
        "status": "CLOSED"
      },
      "sort": {
        "field": "CREATED_AT",
        "order": "ASC"
      }
    },
    "limit": 20
}'

Step 2: Get additional results
Permalink Get a link to this section

If more results are available, the response includes a cursor object that can be used in subsequent calls to fetch the additional results. To use the cursor key from the previous response, add it to your request body and call the endpoint again:

curl https://connect.squareupsandbox.com/v2/labor/shifts/search  \
  -H 'Content-Type: application/json'                     \
  -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'   \
  -d '{
    "query": {
      "filter": {
        "location_id": ["YOUR_LOCATION_ID"],
        "workday": {
          "date_range": {
            "start_date": "2018-10-01",
            "end_date": "2018-10-08"
          },
          "default_timezone": "America/Los Angeles",
          "match_shifts_by": "START_AT"
        },
        "status": "CLOSED"
      },
      "sort": {
        "field": "CREATED_AT",
        "order": "ASC"
      }
    },
    "limit": 20,
    "cursor": "CURSOR_FROM_PREVIOUS_RESPONSE"
}'