Real-Time Clocking

Clock in and clock out users in real-time. Unlike creating time activities with specific timestamps, these endpoints record the current server time as the punch timestamp.

Endpoints

Method	Endpoint	Description
POST	/time-clock/v1/time-clocks/{timeClockId}/clock-in	Clock in a user
POST	/time-clock/v1/time-clocks/{timeClockId}/clock-out	Clock out a user

Clock In

Record the start of a work period. The timestamp is automatically set to the current time.

Path Parameters

Parameter	Type	Required	Description
timeClockId	integer	Yes	Time clock ID

Request Body

Field	Type	Required	Description
userId	integer	Yes	User's ID (must be assigned to the time clock)
jobId	string	Conditional	Job or sub-job ID (required if job enforcement is enabled)
timezone	string	No	Tz format (e.g., America/New_York). Defaults to time clock setting
schedulerShiftId	string	No	Link to a scheduled shift
locationData	object	No	GPS coordinates and address

⚠️
User Assignment Required
The user must be assigned to the specified time clock before they can clock in. Use the Users API to manage assignments.

Example: Basic Clock In

curl --request POST \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/clock-in \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357
  }'

Example: Clock In with Job

curl --request POST \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/clock-in \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "jobId": "job-123",
    "timezone": "America/New_York"
  }'

Example: Clock In with Location

curl --request POST \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/clock-in \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "jobId": "job-123",
    "timezone": "America/New_York",
    "locationData": {
      "address": "123 Main St, New York, NY 10001",
      "latitude": 40.7128,
      "longitude": -74.0060
    }
  }'

Example: Clock In with Scheduler Shift

curl --request POST \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/clock-in \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "schedulerShiftId": "sched-shift-789",
    "timezone": "America/New_York"
  }'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "shift": {
      "id": "shift-abc123",
      "userId": 9170357,
      "start": {
        "timestamp": 1704110400,
        "timezone": "America/New_York",
        "locationData": {
          "address": "123 Main St, New York, NY 10001",
          "latitude": 40.7128,
          "longitude": -74.0060
        },
        "source": {
          "type": "api"
        }
      },
      "jobId": "job-123",
      "schedulerShiftId": null,
      "createdAt": 1704110400,
      "modifiedAt": 1704110400
    }
  }
}

Clock Out

Record the end of a work period. Associates with the user's currently open shift.

Path Parameters

Parameter	Type	Required	Description
timeClockId	integer	Yes	Time clock ID

Request Body

Field	Type	Required	Description
userId	integer	Yes	User's ID
timezone	string	No	Tz format. Defaults to time clock setting
locationData	object	No	GPS coordinates and address

📝
Open Shift Required
The user must have an open shift (clocked in but not out) in this time clock. The clock-out will be associated with the most recent open shift.

Example: Basic Clock Out

curl --request POST \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/clock-out \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357
  }'

Example: Clock Out with Location

curl --request POST \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/clock-out \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "timezone": "America/New_York",
    "locationData": {
      "address": "456 Oak Ave, New York, NY 10002",
      "latitude": 40.7145,
      "longitude": -74.0055
    }
  }'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "shift": {
      "id": "shift-abc123",
      "userId": 9170357,
      "start": {
        "timestamp": 1704110400,
        "timezone": "America/New_York",
        "source": {
          "type": "api"
        }
      },
      "end": {
        "timestamp": 1704139200,
        "timezone": "America/New_York",
        "locationData": {
          "address": "456 Oak Ave, New York, NY 10002",
          "latitude": 40.7145,
          "longitude": -74.0055
        },
        "source": {
          "type": "api"
        }
      },
      "jobId": "job-123",
      "createdAt": 1704110400,
      "modifiedAt": 1704139200
    }
  }
}

Integration Example

Complete clock-in/clock-out workflow:

class TimeClockIntegration {
  constructor(apiKey, timeClockId) {
    this.apiKey = apiKey;
    this.timeClockId = timeClockId;
    this.baseUrl = 'https://api.connecteam.com/time-clock/v1/time-clocks';
  }

  async clockIn(userId, jobId, location) {
    const response = await fetch(
      `${this.baseUrl}/${this.timeClockId}/clock-in`,
      {
        method: 'POST',
        headers: {
          'X-API-KEY': this.apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          userId,
          jobId,
          timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
          locationData: location
        })
      }
    );
    return response.json();
  }

  async clockOut(userId, location) {
    const response = await fetch(
      `${this.baseUrl}/${this.timeClockId}/clock-out`,
      {
        method: 'POST',
        headers: {
          'X-API-KEY': this.apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          userId,
          timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
          locationData: location
        })
      }
    );
    return response.json();
  }
}

// Usage
const timeClock = new TimeClockIntegration('YOUR_API_KEY', 12345);

// Clock in
await timeClock.clockIn(9170357, 'job-123', {
  address: '123 Main St, New York, NY',
  latitude: 40.7128,
  longitude: -74.0060
});

// ... work period ...

// Clock out
await timeClock.clockOut(9170357, {
  address: '123 Main St, New York, NY',
  latitude: 40.7128,
  longitude: -74.0060
});

Error Responses

400 Bad Request

User not assigned:

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

Already clocked in (for clock-in):

{
  "detail": "User already has an open shift"
}

No open shift (for clock-out):

{
  "detail": "User does not have an open shift"
}

Job required:

{
  "detail": "Job ID is required based on time clock settings"
}

API Reference