Guides
Start typing to search…

Getting Shifts

Retrieve shifts from a scheduler with flexible filtering and pagination options.

Endpoints

MethodEndpointDescription
GET/scheduler/v1/schedulers/{schedulerId}/shiftsGet multiple shifts
GET/scheduler/v1/schedulers/{schedulerId}/shifts/{shiftId}Get a single shift

Get Multiple Shifts

Retrieve shifts with optional filters.

Path Parameters

ParameterTypeRequiredDescription
schedulerIdintegerYesThe scheduler's unique ID

Query Parameters

ParameterTypeRequiredDefaultDescription
startTimeintegerYes-Start of date range (Unix timestamp in seconds)
endTimeintegerYes-End of date range (Unix timestamp in seconds)
isOpenShiftbooleanNo-Filter by open shift status
isPublishedbooleanNo-Filter by published status
isRequireAdminApprovalbooleanNo-Filter shifts requiring approval
jobIdarrayNo-Filter by job IDs
assignedUserIdsarrayNo-Filter by assigned user IDs
shiftIdarrayNo-Filter by specific shift IDs
titlestringNo-Filter by shift title (partial match)
sortstringNocreated_atSort by created_at or updated_at
orderstringNoascSort order: asc or desc
limitintegerNo10Results per page (1-500)
offsetintegerNo0Pagination offset
⚠️

Required Parameters

startTime and endTime are required. The API will return a 422 error if these are missing.

📝

Note on Time Range

Shifts are returned if they overlap with the specified time range. A shift starting before startTime but ending after it will be included.

Example: Basic Query

curl --request GET \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?startTime=1736899200&endTime=1737504000' \
  --header 'X-API-KEY: YOUR_API_KEY'

Example: Filter by Job and User

curl --request GET \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?startTime=1736899200&endTime=1737504000&jobId=job-123&assignedUserIds=9170357&assignedUserIds=9170358' \
  --header 'X-API-KEY: YOUR_API_KEY'

Example: Get Open Shifts Requiring Approval

curl --request GET \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?startTime=1736899200&endTime=1737504000&isOpenShift=true&isRequireAdminApproval=true&isPublished=true' \
  --header 'X-API-KEY: YOUR_API_KEY'

Example: Paginated Results

curl --request GET \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?startTime=1736899200&endTime=1737504000&limit=50&offset=100&sort=updated_at&order=desc' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "shifts": [
      {
        "id": "6784dacb3c07733b0a849f49",
        "title": "Morning Shift",
        "color": "#4B7AC5",
        "assignedUserIds": [9170357],
        "startTime": 1736924400,
        "endTime": 1736953200,
        "timezone": "America/New_York",
        "isOpenShift": false,
        "isPublished": true,
        "isRequireAdminApproval": null,
        "jobId": "d4ad7232-576f-2ff6-c57d-8240f1089b00",
        "locationData": {
          "isReferencedToJob": true,
          "gps": {
            "address": "123 Main Street, New York, NY",
            "latitude": 40.7579747,
            "longitude": -73.9855426
          }
        },
        "createdBy": 9170357,
        "creationTime": 1736760011,
        "updateTime": 1736760011,
        "openSpots": null,
        "notes": [
          {
            "type": "html",
            "html": "<p>Remember to check inventory</p>"
          }
        ],
        "statuses": [
          {
            "statusId": "status-001",
            "status": "accepted",
            "creatingUserId": 9170357,
            "creationTime": 1736760100,
            "assignedUserId": 9170357
          }
        ],
        "breaks": [
          {
            "id": "break-001",
            "name": "Lunch",
            "type": "unpaid",
            "startTime": 720,
            "duration": 30
          }
        ],
        "shiftDetails": {
          "shiftLayers": [
            {
              "id": "layer-dept-001",
              "title": "Department",
              "value": {
                "id": "value-sales-001",
                "displayName": "Sales"
              }
            }
          ],
          "shiftSource": null
        },
        "customFields": [
          {
            "id": "field_abc123",
            "title": "Project Code",
            "value": "PROJ-2024-001"
          },
          {
            "id": "field_def456",
            "title": "Cost Center",
            "value": "CC-Operations"
          }
        ]
      }
    ]
  },
  "paging": {
    "offset": 1
  }
}

Get Single Shift

Retrieve a specific shift by its ID.

Path Parameters

ParameterTypeRequiredDescription
schedulerIdintegerYesThe scheduler's unique ID
shiftIdstringYesThe shift's unique ID

Example

curl --request GET \
  --url https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts/6784dacb3c07733b0a849f49 \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "id": "6784dacb3c07733b0a849f49",
    "title": "Morning Shift",
    "color": "#4B7AC5",
    "assignedUserIds": [9170357],
    "startTime": 1736924400,
    "endTime": 1736953200,
    "timezone": "America/New_York",
    "isOpenShift": false,
    "isPublished": true,
    "isRequireAdminApproval": null,
    "jobId": "d4ad7232-576f-2ff6-c57d-8240f1089b00",
    "locationData": {
      "isReferencedToJob": true,
      "gps": {
        "address": "123 Main Street, New York, NY",
        "latitude": 40.7579747,
        "longitude": -73.9855426
      }
    },
    "createdBy": 9170357,
    "creationTime": 1736760011,
    "updateTime": 1736760011,
    "openSpots": null,
    "notes": [],
    "statuses": [],
    "breaks": [],
    "shiftDetails": {
      "shiftLayers": [],
      "shiftSource": null
    },
    "customFields": [
      {
        "id": "field_abc123",
        "title": "Project Code",
        "value": "PROJ-2024-001"
      }
    ]
  }
}

Response Field Details

Shift Object

FieldTypeNullableDescription
idstringNoUnique shift identifier
titlestringNoShift display name
colorstringNoHex color code
assignedUserIdsarrayNoList of assigned user IDs (empty array if unassigned)
startTimeintegerNoStart time (Unix timestamp)
endTimeintegerNoEnd time (Unix timestamp)
timezonestringNoTimezone in Tz format
isOpenShiftbooleanNoWhether shift is open for claiming
isPublishedbooleanNoWhether shift is visible to users
isRequireAdminApprovalbooleanYesWhether claims require approval (null for non-open shifts)
jobIdstringYesAssociated job ID
locationDataobjectYesLocation information
createdByintegerYesUser ID of admin who created shift
creationTimeintegerYesCreation timestamp
updateTimeintegerYesLast update timestamp
openSpotsintegerYesNumber of open spots (null for non-open shifts)
notesarrayNoArray of note objects
statusesarrayNoArray of status objects
breaksarrayNoArray of break objects
shiftDetailsobjectNoShift layer values and source
customFieldsarrayNoCustom field values and metadata

Location Data Object

FieldTypeDescription
isReferencedToJobbooleanWhether location is inherited from job
gpsobjectGPS coordinates and address
gps.addressstringStreet address
gps.latitudenumberLatitude (-90 to 90)
gps.longitudenumberLongitude (-180 to 180)

Break Object

FieldTypeDescription
idstringUnique break identifier
namestringBreak display name
typestringpaid or unpaid
startTimeintegerMinutes from midnight (e.g., 720 = 12:00 PM)
durationintegerBreak duration in minutes
📝

Note on Break Times

Break startTime is expressed as minutes from midnight, not a Unix timestamp. For example, 720 means the break starts at 12:00 PM (noon).

Status Object

FieldTypeDescription
statusIdstringUnique status identifier
statusstringStatus type (see Shifts Overview)
notestringOptional status note
creatingUserIdintegerUser who created the status
modifyingUserIdintegerUser who last modified
creationTimeintegerCreation timestamp
updateTimeintegerLast update timestamp
gpsobjectGPS data if location was captured
assignedUserIdintegerUser the status applies to
attachmentsarrayAttached file URLs

Custom Field Object

FieldTypeDescription
idstringCustom field identifier
titlestringCustom field display name
valuestring/arrayField value(s)
📝

Note on Custom Fields

Custom fields are automatically included in shift responses when they have values. Use the Get Custom Fields endpoint to retrieve field definitions.

Pagination

When there are more results than the limit, use the offset from the response to fetch the next page.

async function getAllShifts(schedulerId, startTime, endTime) {
  const shifts = [];
  let offset = 0;
  const limit = 100;
  
  while (true) {
    const response = await fetch(
      `https://api.connecteam.com/scheduler/v1/schedulers/${schedulerId}/shifts?startTime=${startTime}&endTime=${endTime}&limit=${limit}&offset=${offset}`,
      { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
    );
    
    const result = await response.json();
    shifts.push(...result.data.shifts);
    
    if (result.data.shifts.length < limit) {
      break; // No more results
    }
    
    offset = result.paging.offset;
  }
  
  return shifts;
}

Error Responses

400 Bad Request

{
  "detail": [
    "job_id: job-invalid-123 does not exist",
    "assigned user ids doesn't exist: [99999999]"
  ]
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["query", "startTime"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
⚠️

Validation Note

The isRequireAdminApproval filter can only be used when isOpenShift=true. Using it with non-open shifts will return an error.

API Reference

Updated 7 days ago