Out of office

While a host is away they aren't offered for new bookings. Bookings they already have stay as they are: coss.com never cancels or moves one on its own, and tells you which ones fall in the time instead.

Mark a host as away

Give whole dates, which end with end_date itself and mean those days in the host's time zone:

await coss.scheduling.outOfOffice.create({
  host: "doctor_482",
  start_date: "2027-08-02",
  end_date: "2027-08-13",
  reason: "vacation",
  public_message: "Back on the 16th.",
});

Or part of a day, as instants:

await coss.scheduling.outOfOffice.create({
  host: "doctor_482",
  start: "2027-08-02T13:00:00-04:00",
  end: "2027-08-02T15:00:00-04:00",
  reason: "training",
});

Entries can overlap. A host is away for all of them, and removing one leaves the others.

Mark many hosts at once

Use hosts for a list, or host_filter for everyone matching some attributes right now, such as an office closing for the day. Each host gets an entry of their own, sharing a group, so you can change or remove one person's without touching the others:

const { data } = await coss.scheduling.outOfOffice.create({
  host_filter: { office: "berlin" },
  start_date: "2027-10-03",
  end_date: "2027-10-03",
  reason: "public_holiday",
});

A filter is read once, when you ask. A host who matches later isn't covered.

Sync from an HR tool

put creates or replaces the entry with your own id, so a system of record can send what it knows as often as it likes, and there's one entry for it:

await coss.scheduling.outOfOffice.put("leave_4471", {
  host: "doctor_482",
  start_date: "2027-08-02",
  end_date: "2027-08-13",
  reason: "parental_leave",
});

See which bookings it affects

Conflicts are the host's live bookings that fall in an entry, including holds and requests waiting for approval:

const { data } = await coss.scheduling.outOfOffice.conflicts(entryId);

They carry ids, times and statuses, not the attendee's details. If you didn't mark them away from their own page, the host also gets an email saying how many there are.

To move them, reassign one, or many at once.

A hold that was already there can still be confirmed, and a request can still be approved, during an entry. Both show up as conflicts.

Name who covers

Delegates can be booked in a host's place while they're away, inside the same event type:

await coss.scheduling.outOfOffice.create({
  host: "doctor_482",
  start_date: "2027-08-02",
  end_date: "2027-08-13",
  delegates: ["doctor_518", "doctor_530"],
});

Bookers see slots as usual, and the first of them who's free gets the booking, in the order you named them. A pool still picks fairly, with a delegate ranked no better than the host they're covering, so someone with few bookings doesn't take all of them. This only applies to meetings that touch the time away, and only to hosts a booking could otherwise have: a required host still has to be there.

A delegate still has to fit how a booking's routed. They need to match a pool's host_filter and whatever narrowed the booking, and a host taken out of the event type by name stays out. It doesn't chain: a delegate who's also away just has no slots. A host choosing their own on their page can only name people they share an event type with.

When a host comes back, their count in each pool moves up to the lowest of their peers, once, so they don't take every booking until they've caught up.

Move what it's in the way of

Existing bookings only move if you say so:

await coss.scheduling.outOfOffice.create({
  host: "doctor_482",
  start_date: "2027-08-02",
  end_date: "2027-08-13",
  existing_bookings: "reassign",
  reassign: { preferred_hosts: ["doctor_518"] },
});

That starts a reassignment when there's anything to move, and again if the entry's times change later. reassign takes to_host, or preferred_hosts and otherwise; without it, each goes to one of its delegates if they're free, and otherwise the fairest who is. A booking nobody can take stays where it is. The host's email comes a little later and only counts what's left.

What people booking see

When the only host someone could book is away, the hosted pages say when they're back and show your public_message. A pool just offers its other hosts, and a required host being away takes the time with them.

public_message can't contain a link, and in a live environment it's screened like other text you set up.

Reasons

reason is one of unspecified, vacation, travel, sick, public_holiday, parental_leave, training and other, or a key of your own from the settings' out_of_office_reasons.

A reason can say someone's on medical leave, so only people who manage the host see it. It's never in webhooks, logs, calendars or anything shown to a person booking. Notes are encrypted, for the same reason. How long they're kept is on the data retention page.

Calendars

Each entry puts a private event called "Out of office" on the host's connected calendar, unless you pass show_on_calendar: false. It never says why.

Hosts' own time off

The hosted host page has a Time off tab, where a host can add and remove their own. A session only ever reaches the host it's for. See Embedding.

Webhooks

scheduling.out_of_office.created, .updated and .deleted, and .started and .ended when the time begins and ends. They carry ids and times. See Webhooks.