--- updatedAt: 2026-06-08T14:09:06.000Z --- Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further. # Time Off Requests Create, retrieve, and manage time-off requests for users. Requests can be created as approved or pending, updated to change dates, times, or status, and listed for a date range. > 📘 Reading requests > > For detailed guidance on querying time-off requests (filters, pagination, and examples), see [Get Time Off Requests](https://developer.connecteam.com/docs/time-off-get-time-off-requests). ## Endpoints | Method | Endpoint | Description | | :----- | :-------------------------------- | :------------------------ | | GET | /time-off/v1/requests | Get time-off requests | | 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 ```bash 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 ```bash 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 ```bash 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 ```json { "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 ```bash 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 ```bash 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 ```bash 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 ```json { "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 ```json { "detail": "Time off request not found" } ``` ### 422 Validation Error **Missing required fields:** ```json { "detail": [ { "loc": ["body", "startTime"], "msg": "startTime is required when isAllDay is false", "type": "value_error" } ] } ``` **Invalid date format:** ```json { "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: ```javascript 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](https://developer.connecteam.com/reference/)