coss.comdocs

Create or replace an entry by your own id

PUT
/v1/scheduling/out_of_office/by_external_id/{external_id}

For syncing from a system of record such as an HR tool: send what it says, as often as you like, and there's one entry for it. Give every field you want to keep.

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path Parameters

external_id*string

Your own id for the entry.

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

The host, by id or uid.

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.

Response Body

The entry, replaced.

application/json
  1. response
object*"scheduling.out_of_office"
Value in"scheduling.out_of_office"
id*string
host*string
start*string
end*string
all_day*|

How it was given, when it was as whole dates.

reason*string
notes*string|null
public_message*string|null
show_on_calendar*boolean
delegates*array<string>

Who can be booked in their place.

existing_bookings*string
Value in"leave""reassign"
external_id*string|null
group*|

Shared by the entries one request made for several hosts.

source*string
Value in"api""host""manager""dashboard""holiday"
created_at*string
updated_at*string
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.put({  value: "hr_leave_4471",}, {  host: "doctor_482",  start_date: "2027-08-02",  end_date: "2027-08-13",  reason: "vacation",});
{  "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"}