Time Off Requests

Create and manage time-off requests for users. Requests can be created as approved or pending, and updated to change dates, times, or status.

Endpoints

Method	Endpoint	Description
POST	/time-off/v1/requests	Create a time-off request
PUT	/time-off/v1/requests/{requestId}	Update a time-off request

Create Time Off Request

Create a new time-off request for a user.

Request Body

Field	Type	Required	Description
userId	integer	Yes	The user's ID
policyTypeId	string	Yes	The policy type ID
isAllDay	boolean	Yes	Whether the request is for full days
startDate	string	Yes	Start date (YYYY-MM-DD)
endDate	string	Yes	End date (YYYY-MM-DD)
startTime	string	Conditional	Start time (HH:MM:SS) - required if isAllDay=false
endTime	string	Conditional	End time (HH:MM:SS) - required if isAllDay=false
timezone	string	Yes	Timezone in Tz format (e.g., America/New_York)
status	string	Yes	`approved`, `pending`, or `denied`
timeClockId	integer	No	Time clock ID to show in timesheet
employeeNote	string	No	Note from the employee
managerNote	string	No	Note from the manager
isAdjustForDayLightSaving	boolean	No	Adjust for DST edge cases (default: false)

⚠️
Partial Day Rules
When isAllDay is false:

startTime and endTime are required

startDate and endDate must be the same date

Example: Full Day Request

curl --request POST \
  --url https://api.connecteam.com/time-off/v1/requests \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "policyTypeId": "pt-vacation-001",
    "isAllDay": true,
    "startDate": "2024-03-15",
    "endDate": "2024-03-20",
    "timezone": "America/New_York",
    "status": "approved",
    "employeeNote": "Family vacation"
  }'

Example: Partial Day Request

curl --request POST \
  --url https://api.connecteam.com/time-off/v1/requests \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "policyTypeId": "pt-vacation-001",
    "isAllDay": false,
    "startDate": "2024-03-15",
    "endDate": "2024-03-15",
    "startTime": "09:00:00",
    "endTime": "13:00:00",
    "timezone": "America/New_York",
    "status": "pending",
    "employeeNote": "Doctor appointment"
  }'

Example: With Time Clock Integration

curl --request POST \
  --url https://api.connecteam.com/time-off/v1/requests \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "policyTypeId": "pt-sick-001",
    "isAllDay": true,
    "startDate": "2024-03-18",
    "endDate": "2024-03-18",
    "timezone": "America/New_York",
    "status": "approved",
    "timeClockId": 12345,
    "managerNote": "Approved via API integration"
  }'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "id": "req-abc123def456",
    "timeClockId": 12345,
    "policyTypeId": "pt-vacation-001",
    "userId": 9170357,
    "isAllDay": true,
    "startDate": "2024-03-15",
    "endDate": "2024-03-20",
    "startTime": "00:00:00",
    "endTime": "23:59:59",
    "timezone": "America/New_York",
    "status": "approved",
    "employeeNote": "Family vacation",
    "managerNote": ""
  }
}

Update Time Off Request

Modify an existing time-off request. Only include fields you want to change.

Path Parameters

Parameter	Type	Required	Description
requestId	string	Yes	The request's unique ID

Request Body

All fields are optional - include only what you want to update:

Field	Type	Description
isAllDay	boolean	Change to full day or partial day
startDate	string	New start date (YYYY-MM-DD)
endDate	string	New end date (YYYY-MM-DD)
startTime	string	New start time (HH:MM:SS)
endTime	string	New end time (HH:MM:SS)
timezone	string	New timezone
status	string	Change status: `approved`, `pending`, or `denied`
timeClockId	integer	Update time clock association
managerNote	string	Add or update manager note
isAdjustForDayLightSaving	boolean	DST adjustment flag

📝
Partial Updates
Only include fields you want to change. Omitted fields retain their current values. The employeeNote field cannot be updated via API.

Example: Approve a Pending Request

curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/requests/req-abc123def456 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "status": "approved",
    "managerNote": "Approved by HR system"
  }'

Example: Deny a Request

curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/requests/req-abc123def456 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "status": "denied",
    "managerNote": "Insufficient coverage for requested dates"
  }'

Example: Change Dates

curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/requests/req-abc123def456 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "startDate": "2024-03-18",
    "endDate": "2024-03-22",
    "timezone": "America/New_York"
  }'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "id": "req-abc123def456",
    "timeClockId": null,
    "userId": 9170357,
    "isAllDay": true,
    "startDate": "2024-03-18",
    "endDate": "2024-03-22",
    "startTime": "00:00:00",
    "endTime": "23:59:59",
    "timezone": "America/New_York",
    "status": "approved",
    "managerNote": "Dates adjusted per employee request"
  }
}

Error Responses

404 Not Found

{
  "detail": "Time off request not found"
}

422 Validation Error

Missing required fields:

{
  "detail": [
    {
      "loc": ["body", "startTime"],
      "msg": "startTime is required when isAllDay is false",
      "type": "value_error"
    }
  ]
}

Invalid date format:

{
  "detail": [
    {
      "loc": ["body", "startDate"],
      "msg": "Invalid date format. Use YYYY-MM-DD",
      "type": "value_error"
    }
  ]
}

Best Practices

Syncing from HR Systems

When importing approved time off from external HR systems:

async function syncApprovedTimeOff(requests) {
  for (const req of requests) {
    await fetch('https://api.connecteam.com/time-off/v1/requests', {
      method: 'POST',
      headers: {
        'X-API-KEY': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userId: req.userId,
        policyTypeId: req.policyTypeId,
        isAllDay: true,
        startDate: req.startDate,
        endDate: req.endDate,
        timezone: req.timezone,
        status: 'approved',
        managerNote: `Imported from ${req.sourceSystem}`
      })
    });
  }
}

API Reference