Availability and Out of Office

Each team member has an availability state: on_shift, off_hours (outside their work hours), absent (out of office) or inactive (no longer an active member). The state decides whether a contact owner or assignee receives new conversations: absent members never get automatic assignments, and an out-of-office period can name a substitute.

Contacts show the state of their owner in owner.availability_state.

The team member list (GET /api/v1/users, scope team:read) carries the same summary per member: availability_state, absent_until, substitute, has_work_hours (true when the member has work hours set, so on_shift with has_work_hours: false means "no work hours") and next_shift_start (UTC start of the next work-hours window; null when on shift, without work hours, or unknown).

Endpoints

Method	Path	Scope
GET / PUT	/api/v1/users/me/availability	none (the token's own user)
GET / POST	/api/v1/users/me/absences	none (the token's own user)
PATCH / DELETE	/api/v1/users/me/absences/{absence_id}	none (the token's own user)
POST	/api/v1/users/me/absences/end-now	none (the token's own user)
same paths	/api/v1/users/{user_id}/availability, /absences, ...	team:read to read, team:update to change another member (only an Owner can change another Owner)

The /users/me endpoints act as the user the token belongs to. A token that changes the auto-reply fields (auto_reply_*) on PUT /users/me/availability also needs messages:create, because auto-replies are sent to customers in that user's name.

Work hours (PUT /users/me/availability)

Send only the fields you change.

Field	Description
timezone	IANA zone such as Europe/Berlin; null uses the workspace time zone
work_schedule_enabled	false (default): always on shift
work_schedule.time_ranges	[{ "days": [0,1,2,3,4], "start": "09:00", "end": "17:00" }], days 0 (Monday) to 6 (Sunday), local time, end before start means overnight
default_substitute	Substitute suggested for new absences
auto_reply_absence_enabled / auto_reply_off_hours_enabled	Turn the out-of-office / outside-work-hours auto-reply on or off
auto_reply_absence_text / auto_reply_off_hours_text	Reply text (max 2000 characters). Variables: {{agent.name}}, {{agent.first_name}}, {{agent.substitute_name}}, {{agent.return_date}}, {{agent.next_shift}} and the standard contact variables ({{contact.first_name}}, {{contact.last_name}}, {{contact.name}}, {{contact.email}}, {{contact.phone}}, {{contact.birthday}}, {{contact.custom.<key>}}). A variable without a value renders empty
auto_reply_absence_translations / auto_reply_off_hours_translations	{ "<language>": "<text>" }, sent when the contact's language matches; same variables
auto_reply_excluded_channel_types	Channel types that never get an auto-reply, for example ["email"]

The response adds effective_timezone and status (availability_state, absent_until, next_shift_start, absence, substitute).

Out of office

curl -X POST "https://api.sendseven.com/api/v1/users/me/absences" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{"ends_at": "2026-11-03T08:00:00Z", "substitute_mode": "user", "substitute_user_id": "usr_7f3a9c", "note": "Vacation"}'

Field	Description
starts_at	ISO 8601, default now
ends_at	ISO 8601, or null for "until switched off"
substitute_mode	none, user, round_robin_inbox, round_robin_tag, least_busy_inbox, least_busy_tag
substitute_user_id / substitute_inbox_id / substitute_tag_id	The ID the mode needs; a substitute user must be active
note	Internal reason (max 255 characters), never shown to customers. On /users/{user_id}/... reads it is only returned to callers with team:update; the member sees their own

While absent with a substitute, new conversations of the member's contacts, and their assigned conversations that receive a new customer message, move to the substitute. POST /users/me/absences/end-now ends every running absence and returns {"success": true, "ended": 1}. Overlapping absences are rejected.