Search timecards

POST

/v2/labor/timecards/search

Returns a paginated list of Timecard records for a business.

The list to be returned can be filtered by:

Location IDs
Team member IDs
Timecard status (OPEN or CLOSED)
Timecard start
Timecard end
Workday details

The list can be sorted by:

START_AT
END_AT
CREATED_AT
UPDATED_AT

Permissions:TIMECARDS_READ

Guide

Time Tracking with the Labor API

Try in API Explorer

Link to section

Request body

Example code

Link to section

query

Query filters.

Link to section

limit

integer(32-bit)

The number of resources in a page (200 by default).

Min

Max

200

Link to section

cursor

string

An opaque cursor for fetching the next page.

Link to section

Response fields

Link to section

timecards

Timecards.

Link to section

cursor

string

An opaque cursor for fetching the next page.

Link to section

errors

Any errors that occurred during the request.

Link to section

Examples

All versions ->

POST /v2/labor/timecards/search

curl https://connect.squareup.com/v2/labor/timecards/search \
  -X POST \
  -H 'Square-Version: 2025-10-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "workday": {
          "date_range": {
            "start_date": "2019-01-20",
            "end_date": "2019-02-03"
          },
          "match_timecards_by": "START_AT",
          "default_timezone": "America/Los_Angeles"
        }
      }
    },
    "limit": 100
  }'

Response JSON

{
  "timecards": [
    {
      "id": "X714F3HA6D1PT",
      "team_member_id": "ormj0jJJZ5OZIzxrZYJI",
      "location_id": "PAA1RJZZKXBFG",
      "timezone": "America/New_York",
      "start_at": "2019-01-21T03:11:00-05:00",
      "end_at": "2019-01-21T13:11:00-05:00",
      "wage": {
        "title": "Barista",
        "hourly_rate": {
          "amount": 1100,
          "currency": "USD"
        },
        "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M",
        "tip_eligible": true
      },
      "breaks": [
        {
          "id": "SJW7X6AKEJQ65",
          "start_at": "2019-01-21T06:11:00-05:00",
          "end_at": "2019-01-21T06:11:00-05:00",
          "break_type_id": "REGS1EQR1TPZ5",
          "name": "Tea Break",
          "expected_duration": "PT10M",
          "is_paid": true
        }
      ],
      "declared_cash_tip_money": {
        "amount": 500,
        "currency": "USD"
      },
      "status": "CLOSED",
      "version": 6,
      "created_at": "2019-01-24T01:12:03Z",
      "updated_at": "2019-02-07T22:21:08Z"
    },
    {
      "id": "GDHYBZYWK0P2V",
      "team_member_id": "33fJchumvVdJwxV0H6L9",
      "location_id": "PAA1RJZZKXBFG",
      "timezone": "America/New_York",
      "start_at": "2019-01-22T12:02:00-05:00",
      "end_at": "2019-01-22T13:02:00-05:00",
      "wage": {
        "title": "Cook",
        "hourly_rate": {
          "amount": 1600,
          "currency": "USD"
        },
        "job_id": "gcbz15vKGnMKmaWJJ152kjim",
        "tip_eligible": true
      },
      "breaks": [
        {
          "id": "BKS6VR7WR748A",
          "start_at": "2019-01-22T14:30:00-05:00",
          "end_at": "2019-01-22T14:40:00-05:00",
          "break_type_id": "WQX00VR99F53J",
          "name": "Tea Break",
          "expected_duration": "PT10M",
          "is_paid": true
        },
        {
          "id": "BQFEZSHFZSC51",
          "start_at": "2019-01-22T12:30:00-05:00",
          "end_at": "2019-01-22T12:44:00-05:00",
          "break_type_id": "P6Q468ZFRN1AC",
          "name": "Coffee Break",
          "expected_duration": "PT15M",
          "is_paid": false
        }
      ],
      "declared_cash_tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "status": "CLOSED",
      "version": 16,
      "created_at": "2019-01-23T23:32:45Z",
      "updated_at": "2019-01-24T00:56:25Z"
    }
  ]
}