Breadcrumbs

Export GPS breadcrumb trails for employee shifts on a specific date. Breadcrumbs capture location movement while an employee is clocked in — useful for field-service compliance, route verification, and enterprise audit workflows.

The API uses an async three-step flow: request a report, poll until it is ready, then download a JSON file.

Endpoints

Step	Method	Endpoint	Description
1	POST	/time-clock/breadcrumbs/v1/report	Start report generation for a date
2	GET	/time-clock/breadcrumbs/v1/report/{fileId}	Poll task status
3	GET	/time-clock/breadcrumbs/v1/report/{fileId}/download	Download the JSON report

Overview

Single-day export: pass one date (YYYY-MM-DD). The report includes shift breadcrumbs for that calendar day across all time clocks in the company (company timezone).
Async generation: step 1 returns a fileId (UUID). A background worker builds the file and uploads it to storage.
Poll then download: call step 2 until status is completed, then call step 3 to stream the JSON.
Shift-scoped data: breadcrumbs are grouped per shift (timeActivityId) and user. Only shifts with breadcrumb data appear in the file.
Prerequisite: breadcrumbs must be enabled on at least one time clock in the company (Time Clock settings).

📘
What are breadcrumbs?
While an employee is clocked into a shift, Connecteam can record periodic GPS events — motion readings, geofence enter/exit events, and providerChange events (network/GPS state changes). These are stored on the shift and exported in the report.

👍
Authenticated download
Always download through step 3 with your API key or OAuth token. The API validates that the fileId belongs to your company before streaming the file.

Authentication

API Key (X-API-KEY header), or
OAuth 2.0 with scope time_clock.read

Plan requirement: Time Clock API (timeClockApi, Operations API category).

Step 1 — Generate Report

POST /time-clock/breadcrumbs/v1/report

Request Body

Field	Type	Required	Description
date	string (YYYY-MM-DD)	Yes	Calendar date to export. Must not be in the future.

Example Request

curl --request POST \
  --url https://api.connecteam.com/time-clock/breadcrumbs/v1/report \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "date": "2025-03-15"
  }'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "fileId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Save data.fileId — you need it for steps 2 and 3.

Step 2 — Poll Status

GET /time-clock/breadcrumbs/v1/report/{fileId}

Path Parameters

Parameter	Type	Required	Description
fileId	string (UUID)	Yes	The `fileId` returned from step 1

Task Status Values

Status	Meaning
`in_queue`	Task created; waiting for the worker
`in_progress`	Report is being generated
`completed`	File is ready — proceed to step 3
`error`	Generation failed — see `errorMsg`

Example Request

curl --request GET \
  --url https://api.connecteam.com/time-clock/breadcrumbs/v1/report/550e8400-e29b-41d4-a716-446655440000 \
  --header 'X-API-KEY: YOUR_API_KEY'

Response (in progress)

{
  "requestId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "data": {
    "status": "in_progress",
    "errorMsg": null
  }
}

Response (completed)

{
  "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "data": {
    "status": "completed",
    "errorMsg": null
  }
}

Poll every few seconds until status is completed or error.

Step 3 — Download Report

GET /time-clock/breadcrumbs/v1/report/{fileId}/download

Streams the JSON file (Content-Type: application/json) with a Content-Disposition: attachment header. Only available when status is completed.

Example Request

curl --request GET \
  --url https://api.connecteam.com/time-clock/breadcrumbs/v1/report/550e8400-e29b-41d4-a716-446655440000/download \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --output breadcrumbs_2025-03-15.json

Report File Structure

The downloaded JSON has this top-level shape:

{
  "breadcrumbsByActivities": [
    {
      "timeClockId": 12345,
      "timeActivityId": "shift-abc123",
      "userId": 9170357,
      "breadcrumbs": [
        {
          "timestamp": 1710504000,
          "receivedTimestamp": 1710504002,
          "type": "motion",
          "gps": {
            "altitude": 50.0,
            "latitude": 40.7128,
            "longitude": -74.0060,
            "speed": 2.5,
            "accuracy": 10.0,
            "altitudeAccuracy": 5.0,
            "latitudeAccuracy": null,
            "longitudeAccuracy": null
          }
        },
        {
          "timestamp": 1710507600,
          "receivedTimestamp": 1710507601,
          "type": "geoFence",
          "action": "ENTER",
          "geoFenceId": "gf-site-001",
          "gps": {
            "altitude": 48.0,
            "latitude": 40.7130,
            "longitude": -74.0058,
            "speed": 0.0,
            "accuracy": 8.0
          }
        }
      ]
    }
  ]
}

Activity Fields

Field	Type	Description
timeClockId	integer	Time clock the shift belongs to
timeActivityId	string	Shift ID (same as shift `id` in time-activities APIs)
userId	integer	Employee ID
breadcrumbs	array	Ordered GPS events for this shift

Breadcrumb Event Fields

Field	Type	Description
timestamp	integer	When the event was recorded on the device (Unix seconds)
receivedTimestamp	integer	When Connecteam received the event (Unix seconds)
type	string	`motion`, `geoFence`, or `providerChange`
gps	object	Latitude, longitude, altitude, speed (m/s), accuracy (meters), and optional accuracy components
action	string	(geoFence only) `ENTER` or `EXIT`
geoFenceId	string	(geoFence only) Geofence identifier
isNetworkEnabled	boolean	(providerChange only) Device network state
isLocationEnabled	boolean	(providerChange only) OS location services state
isGpsEnabled	boolean	(providerChange only) GPS hardware state

📝
Export notes

Activities with no breadcrumbs are omitted from the file.

Internal fields (age, lastLocationTrackingEvent) are stripped from the export.

Shifts are included when they have activity on the requested date (per company timezone day boundaries).

Integration Example

const BASE = 'https://api.connecteam.com/time-clock/breadcrumbs/v1';
const API_KEY = 'YOUR_API_KEY';
const headers = { 'X-API-KEY': API_KEY, 'Content-Type': 'application/json' };

async function downloadBreadcrumbsReport(date) {
  // Step 1 — start generation
  const createRes = await fetch(`${BASE}/report`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ date }),
  });
  if (!createRes.ok) throw new Error(await createRes.text());
  const { data: { fileId } } = await createRes.json();

  // Step 2 — poll until completed
  const pollHeaders = { 'X-API-KEY': API_KEY };
  let status = 'in_queue';
  let errorMsg = null;
  while (status === 'in_queue' || status === 'in_progress') {
    await new Promise((r) => setTimeout(r, 5000));
    const statusRes = await fetch(`${BASE}/report/${fileId}`, { headers: pollHeaders });
    if (!statusRes.ok) throw new Error(await statusRes.text());
    ({ status, errorMsg } = (await statusRes.json()).data);
  }
  if (status === 'error') throw new Error(errorMsg || 'Report generation failed');

  // Step 3 — download JSON
  const downloadRes = await fetch(`${BASE}/report/${fileId}/download`, { headers: pollHeaders });
  if (!downloadRes.ok) throw new Error(await downloadRes.text());
  return downloadRes.json();
}

// Export breadcrumbs for March 15, 2025
const report = await downloadBreadcrumbsReport('2025-03-15');
console.log(`Activities with breadcrumbs: ${report.breadcrumbsByActivities.length}`);

Error Codes

HTTP Status	When
`400`	Invalid `fileId` format (not a UUID); report not ready for download (`status` ≠ `completed`); breadcrumbs not enabled; future `date`; no time clocks in company
`401`	Missing or invalid authentication
`403`	`fileId` belongs to a different company
`404`	`fileId` not found; report file missing from storage
`422`	Request body validation failure

When status is error, errorMsg in the status response contains the failure reason.

Prerequisites & Limitations

📝
Important Considerations

Enable breadcrumbs in Time Clock settings before calling the API. If no time clock has breadcrumbs enabled, step 1 returns 400.

Task metadata is retained for approximately 2 hours (poll within this window).

Generated files in storage use a 1-day TTL tag — download soon after completion.

Company-wide scope: one request exports breadcrumbs from all time clocks for the date.

Date only: there is no multi-day range in a single request; call once per day.

Generate Report API Reference · Get Status API Reference · Download API Reference