---
title: "Update event-level BEO fields"
method: PUT
path: "/events/{id}/beo"
tags: ["Events"]
---

# Update event-level BEO fields

`PUT /events/{id}/beo`

## Request

- Base URL: `https://joinways.app/api/v1`
- URL: `https://joinways.app/api/v1/events/{id}/beo`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://joinways.app/oauth/authorize`, token URL `https://joinways.app/api/oauth/token`, scopes: `mcp.write`)

Writes event-level BEO fields only (staff, contacts and per-day overrides have their own endpoints). Omit a key to leave it untouched; pass `null` to clear a nullable field; unknown keys are ignored. Each write bumps `beo_version` (a change after a sent release warns the team) and synchronises the calendars. **Role permission:** `data.write`.

## Headers

- `Idempotency-Key` string

## Request body

- BeoUpdate: Event-level BEO fields. Every field is optional; omit to leave untouched.
  - `schedule` BeoScheduleItem[]: Full program (replaces the existing one). `[]` clears it.
    - `id` string
    - `time` string, required
    - `endTime` string, nullable
    - `label` string, required
    - `notes` string, nullable
    - `category` 'welcome' | 'food' | 'session' | 'break' | 'technical' | 'entertainment' | 'other' | 'null', nullable
    - `day` string, nullable
    - `dayId` string, uuid, nullable: A day of this event; a stale id falls back to all days.
    - `setup` 'theatre' | 'classroom' | 'banquet' | 'cabaret' | 'cocktail' | 'u_shape' | 'boardroom' | 'u-shape' | 'theater' | 'custom' | 'null', nullable: Room layout of this moment, read on the room's seats for that layout. `u-shape` and `theater` are stored as `u_shape` and `theatre`; `custom` has no layout and is stored as null.
    - `setupNotes` string, nullable
    - `description` string, nullable
    - `quantity` number, nullable
    - `unitPrice` number, nullable
    - `quoteItemId` string, nullable
    - `slotId` string, uuid, nullable
    - `spaceId` string, uuid, nullable
    - `vendor` string, nullable
  - `setup_type` 'theatre' | 'classroom' | 'u-shape' | 'boardroom' | 'banquet' | 'cocktail' | 'custom' | 'null', nullable
  - `setup_notes` string, nullable
  - `catering_notes` string, nullable
  - `dietary_notes` string, nullable: Diets and allergies (« Contraintes alimentaires »), one line each with the number of guests, for the whole event.
  - `technical_notes` string, nullable
  - `service_notes` string, nullable
  - `beo_remarks` string, nullable: Free-text "Remarks" section below Technical & Service.
  - `beo_vendors` BeoVendor[]: Full vendor list (replaces the existing one). `[]` clears it.
    - `id` string, required
    - `name` string, required
    - `role` string, required
    - `contactName` string, nullable
    - `phone` string, nullable
    - `email` string, nullable
    - `notes` string, nullable
  - `beo_context` string, nullable: One-line context atop the BEO. `null` or empty = the automatic sentence.
  - `onsite_contact_person_id` string, uuid, nullable: Address-book person used as the on-site contact; a person of the workspace (`400` otherwise).

## Response `200`

Updated BEO fields.

- object
  - `success` boolean
  - `beo` object: The written fields (`schedule`, `setup_type`, the notes, `beo_remarks`, `beo_vendors`, `beo_context`, `onsite_contact_person_id`) and the new `beo_version`.

## Other responses

- `400`: Validation failed (`invalid_request`). For a body that fails the schema, `details` holds `formErrors` and `fieldErrors`.
- `401`: Missing, invalid, expired or revoked bearer token (`unauthorized`).
- `403`: `forbidden`: the token lacks the scope, its owner's role lacks the permission named by the operation, or the workspace has neither the Pro plan nor a trial (`details.reason` `plan_not_eligible`).
- `404`: Not found in this workspace, or the id of the path is not a UUID (`not_found`).
- `409`: The state of the record refuses the operation (`conflict`). `details.reason` is a stable code.
- `429`: Too many requests (`rate_limited`). `details.reason`: `per-ip`, `per-account-minute`, `per-account-day`, or `email_rate_limited` (email budget). Always carries `Retry-After`: wait that many seconds.

---

[API](https://skmtc.dev/joinways/apis/joinways-public-api.md) · [All operations](https://skmtc.dev/joinways/apis/joinways-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/joinways/apis/joinways-public-api/revisions/39e84309953e?raw)