How to log unavailable time with the API

Aim: Create unavailable time on your schedule with the Calendar event API endpoint. This guide will provide the steps required for logging a full day of unavailable time as well as a part day (in hours) of unavailable time.

API endpoint:

Required fields:

"attending-user-ids" - The user id for the user which you would like to log the time against

"start" - The start date and time for the event (only date is required for full day events)

"end" - The end date and time for the event (only date is required for full day events)

"type" - Though not required, this is important if you want to add an event type. List of event types shown below with the respective id that is required for the type object.

Meeting Types and id's for unavailable time:

The meeting you require must be logged with its id in the request body.

-2 : Paid Time off

-3 : Sick Leave

-4 : Meeting

-5 : Other

-6 : Training

-7 : Public Holiday

All day events:

When setting unavailable time with the full day flag enabled you can set the start and end dates for the same day for a single day.

Change the end date for another date if you would like to log unavailable time across multiple days.

You can find the code sample below and more on our public GitHub repo for sample requests.

Log unavailable time for a part day(s) > multiple users

POST
https://"+siteName+".teamwork.com/calendarevents.json
const myHeaders = new Headers();
const userName = "email address or API KEY here";
const password = "password";
const siteName = "yourSiteName"
const userId = "userIdHere"
const userIds = "userIdsHere" // Multiple user id's can be added here to set unavailabel time for each user in bulk ie: "12345,67575"
const userId2 = "userId2Here" // If you are creating the same unavailable time for multiple users, use this id for the 2nd user and create more variables if you have more than two users
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Basic " + btoa(userName + ":" + password));

/*Event type id's:
-2 : Paid Time Off
-3 : Sick Leave
-4 : Meeting
-5 : Other
-6 : Training
-7 : Public Holiday*/ 

const raw = JSON.stringify({
    "event": {
        "title": "Unavailable",
        "attending-user-ids": userIds,
        "description": "Training in 2hr blocks for 5 days - 10hr total",
        "start": "2024-07-08T09:00",
        "end": "2024-07-12T17:00",
        "ranges": [
            {
                "start": "2024-07-08T09:00",
                "end": "2024-07-12T17:00",
                "attending-user-ids": userIds,
                "unavailableTimes": [
                    {
                        "userId": userId,
                        "durationMinutes": 600
                    },
                    {
                        "userId": userId2,
                        "durationMinutes": 600
                    }
                ]
            }
        ],
        "type": {
            "color": "00ffff",
            "unavailable": "1",
            "id": "-6",
            "name": "Training",
            "translatedName": "Training"
        },
        "all-day": false,
        "utc": true,
        "attendees-can-edit": true,
        "privacy": {
            "type": "all"
        }
    }
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://" + siteName + ".teamwork.com/calendarevents.json", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Part day events based on hours per day:

When setting unavailable time with the full day flag enabled you can set the start and end dates for the same day for a single day.

Change the end date for another date if you would like to log unavailable time across multiple days.

Events can be created for a group of users which is shown in the code sample to the right.

You can find the code sample below and more on our public GitHub repo for sample requests.

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.

Log unavailable time for a full day(s)

POST
https://"+siteName+".teamwork.com/calendarevents.json
const myHeaders = new Headers();
const userName = "email address or API KEY here";
const password = "password";
const siteName = "yourSiteName"
const userId = "userIdHere"
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Basic "+btoa(userName+":"+password));

/*Event type id's:
-2 : Paid Time off
-3 : Sick Leave
-4 : Meeting
-5 : Other
-6 : Training
-7 : Public Holiday*/

const raw = JSON.stringify({
  "event": {
    "title": "Unavailable",
    "attending-user-ids": userId,
    "description": "Via API for ticket (unavailability - all day)",
    "start": "2024-04-15",//yyyy-mm-dd
    "end": "2024-04-15",//yyyy-mm-dd (Set date higher than start date to set unavailable time across multiple days)
    "ranges": [
      {
        "start": "2024-06-27",
        "end": "2024-06-27",
        "attending-user-ids": userId,
    "type": {
      "color": "ff0000",
      "unavailable": true,
      "id": -2,
      "name": "Paid Time Off"
    },
    "all-day": true,
    "utc": true,
    "attendees-can-edit": true,
    "privacy": {
      "type": "all"
    }
  }
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://"+siteName+".teamwork.com/calendarevents.json", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));