coss.comdocs

Create out of office entries

POST
/v1/scheduling/out_of_office

Marks one host, a list of hosts or everyone matching some attributes as away, for part of a day or for whole dates. They aren't offered during it. Existing bookings stay as they are: list them with the entry's conflicts.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Header Parameters

Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Request Body

application/json
  1. body
host?string

One host, by id or uid.

hosts?array<string>

Several hosts, by id or uid. Each gets an entry of their own.

Itemsitems <= 500
host_filter?

Every active host matching these attributes right now. A host added later isn't covered.

start?string

An ISO 8601 instant with an offset.

end?string

An ISO 8601 instant with an offset.

start_date?string

The first whole day away. Use instead of start and end.

Match^\d{4}-\d{2}-\d{2}$
end_date?string

The last whole day away, which is included.

Match^\d{4}-\d{2}-\d{2}$
time_zone?string

What the dates mean in. Default: the host's zone when this is made.

Length1 <= length <= 64
delegates?array<string>

Who can be booked in this host's place during it, by id or uid, in the order to try them. They still have to fit how a booking's routed.

Itemsitems <= 10
reason?string

One of unspecified, vacation, travel, sick, public_holiday, parental_leave, training and other, or a key from the settings' out_of_office_reasons. Only people who manage this host see it: never bookers, webhooks or calendars.

Match^[a-z][a-z0-9_]{0,63}$
notes?string

For people who manage this host. Encrypted, and never shown to a booker.

Lengthlength <= 2000
public_message?string

Shown to bookers while this host is away. Can't contain a link.

Lengthlength <= 300
show_on_calendar?boolean

Put a private "Out of office" event on the host's calendar. Default: true.

existing_bookings?string

What happens to bookings already in the way. leave (the default) only reports them. reassign moves them, and any nobody can take stay where they are.

Value in"leave""reassign"
reassign?

With existing_bookings: reassign: who they go to. Default: the fairest who's free.

external_id?string

Your own id for this entry, unique in the environment. Needs one host.

Length1 <= length <= 255

Response Body

An entry per host.

application/json
  1. response
object*"list"
Value in"list"
data*array<>
has_more*boolean
import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = 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.",});
{  "object": "list",  "data": [    {      "object": "scheduling.out_of_office",      "id": "ooo_01kd2m9a0b1c2d3e4f5g6h7j8m",      "host": "host_01kd2m9a0b1c2d3e4f5g6h7j8m",      "start": "2027-08-02T04:00:00.000Z",      "end": "2027-08-14T04:00:00.000Z",      "all_day": {        "start_date": "2027-08-02",        "end_date": "2027-08-13",        "time_zone": "America/New_York"      },      "reason": "vacation",      "notes": null,      "public_message": "Back on the 16th.",      "show_on_calendar": true,      "delegates": [        "host_01kd2m9a0b1c2d3e4f5g6h7j8n"      ],      "existing_bookings": "leave",      "external_id": null,      "group": null,      "source": "api",      "created_at": "2027-01-01T10:00:00.000Z",      "updated_at": "2027-01-01T10:00:00.000Z"    }  ],  "has_more": false}