Time Activities

Time activities are the work records in a time clock, including shifts, manual breaks, and time offs. This page covers querying, creating, and updating time activities.

Endpoints

Method	Endpoint	Description
GET	/time-clock/v1/time-clocks/{timeClockId}/time-activities	Get time activities
POST	/time-clock/v1/time-clocks/{timeClockId}/time-activities	Create time activities
PUT	/time-clock/v1/time-clocks/{timeClockId}/time-activities	Update time activities

Activity Types

Type	Description
`shift`	Regular work periods
`manual_break`	Scheduled break periods
`time_off`	Approved PTO entries

Get Time Activities

Retrieve time activities within a date range.

Path Parameters

Parameter	Type	Required	Description
timeClockId	integer	Yes	Time clock ID

Query Parameters

Parameter	Type	Required	Description
startDate	string	Yes	Start date (YYYY-MM-DD)
endDate	string	Yes	End date (YYYY-MM-DD)
userIds	array	No	Filter by user IDs
jobIds	array	No	Filter by job IDs
manualBreakIds	array	No	Filter by manual break type IDs
policyTypeIds	array	No	Filter by time-off policy type IDs
activityTypes	array	No	Filter by type: `shift`, `manual_break`, `time_off`

⚠️
Date Range Limit
The date range cannot exceed 92 days (approximately 3 months).

Example Request

curl --request GET \
  --url 'https://api.connecteam.com/time-clock/v1/time-clocks/12345/time-activities?startDate=2024-01-01&endDate=2024-01-31&activityTypes=shift' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Structure

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "timeActivitiesByUsers": [
      {
        "userId": 9170357,
        "shifts": [
          {
            "id": "shift-abc123",
            "start": {
              "timestamp": 1704110400,
              "timezone": "America/New_York",
              "locationData": {
                "address": "123 Main St, New York, NY",
                "latitude": 40.7128,
                "longitude": -74.0060
              },
              "source": {
                "type": "mobile"
              }
            },
            "end": {
              "timestamp": 1704139200,
              "timezone": "America/New_York",
              "source": {
                "type": "mobile"
              }
            },
            "jobId": "job-123",
            "subJobId": "subjob-456",
            "schedulerShiftId": "sched-789",
            "employeeNote": "Completed delivery route",
            "managerNote": "",
            "createdAt": 1704110400,
            "modifiedAt": 1704139200,
            "isAutoClockOut": false,
            "shiftAttachments": []
          }
        ],
        "manualBreaks": [],
        "timeOffs": []
      }
    ]
  }
}

Shift Response Fields

Field	Type	Description
id	string	Unique shift identifier
start	object	Start time point with timestamp, timezone, location, source
end	object	End time point (null if shift is ongoing)
jobId	string	Associated job ID
subJobId	string	Associated sub-job ID
schedulerShiftId	string	Linked scheduler shift ID
employeeNote	string	Note from employee
managerNote	string	Note from manager
createdAt	integer	Creation timestamp
modifiedAt	integer	Last modification timestamp
isAutoClockOut	boolean	Whether auto clock-out occurred
shiftAttachments	array	Attached data (forms, files, etc.)

Create Time Activities

Create new shifts and manual breaks for users.

📝
Locked Days
You cannot create time activities on days that are locked or approved. Check timesheet status before creating entries.

Request Body

{
  "timeActivities": [
    {
      "userId": 9170357,
      "shifts": [
        {
          "start": {
            "timestamp": 1704110400,
            "timezone": "America/New_York"
          },
          "end": {
            "timestamp": 1704139200,
            "timezone": "America/New_York"
          },
          "jobId": "job-123",
          "employeeNote": "Imported from external system",
          "managerNote": "Verified"
        }
      ],
      "manualbreaks": []
    }
  ]
}

Shift Create Fields

Field	Type	Required	Description
start	object	Yes	Start time with timestamp and timezone
end	object	No	End time (omit for open shift)
jobId	string	Conditional	Required if job tracking is enforced
subJobId	string	Conditional	Required if job has sub-jobs
employeeNote	string	No	Employee note
managerNote	string	No	Manager note

Manual Break Create Fields

Field	Type	Required	Description
id	string	Yes	Manual break type ID (from settings)
start	object	Yes	Start time
end	object	No	End time
employeeNote	string	No	Employee note
managerNote	string	No	Manager note

Example: Create Shift

curl --request POST \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/time-activities \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "timeActivities": [
      {
        "userId": 9170357,
        "shifts": [
          {
            "start": {
              "timestamp": 1704110400,
              "timezone": "America/New_York"
            },
            "end": {
              "timestamp": 1704139200,
              "timezone": "America/New_York"
            },
            "jobId": "job-123"
          }
        ],
        "manualbreaks": []
      }
    ]
  }'

Example: Bulk Import

async function importTimeActivities(timeClockId, activities) {
  const BATCH_SIZE = 100;
  
  for (let i = 0; i < activities.length; i += BATCH_SIZE) {
    const batch = activities.slice(i, i + BATCH_SIZE);
    
    await fetch(
      `https://api.connecteam.com/time-clock/v1/time-clocks/${timeClockId}/time-activities`,
      {
        method: 'POST',
        headers: {
          'X-API-KEY': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ timeActivities: batch })
      }
    );
  }
}

Update Time Activities

Modify existing shifts and manual breaks.

Request Body

{
  "timeActivities": [
    {
      "userId": 9170357,
      "shifts": [
        {
          "id": "shift-abc123",
          "start": {
            "timestamp": 1704111000,
            "timezone": "America/New_York"
          },
          "end": {
            "timestamp": 1704140000,
            "timezone": "America/New_York"
          },
          "managerNote": "Adjusted per employee request"
        }
      ],
      "manualbreaks": []
    }
  ]
}

Shift Update Fields

Field	Type	Required	Description
id	string	Yes	Existing shift ID
start	object	No	New start time
end	object	No	New end time
jobId	string	No	Change associated job
subJobId	string	No	Change associated sub-job
employeeNote	string	No	Update employee note
managerNote	string	No	Update manager note

Example: Adjust Shift Times

curl --request PUT \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/time-activities \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "timeActivities": [
      {
        "userId": 9170357,
        "shifts": [
          {
            "id": "shift-abc123",
            "end": {
              "timestamp": 1704142800,
              "timezone": "America/New_York"
            },
            "managerNote": "Extended shift for project completion"
          }
        ],
        "manualbreaks": []
      }
    ]
  }'

Error Responses

400 Bad Request

User not assigned to time clock:

{
  "detail": ["User 9170357 is not assigned to time clock 12345"]
}

Locked days:

{
  "detail": ["User: 9170357 has locked days: ['2024-01-15', '2024-01-16']"]
}

Invalid job:

{
  "detail": ["jobs: ['job-invalid'] not in the required time clock"]
}

Manual breaks disabled:

{
  "detail": "manual breaks are disabled for the given time clock"
}

API Reference