---
title: "Update an event"
method: PATCH
path: "/events/{id}"
tags: ["Events"]
---

# Update an event

`PATCH /events/{id}`

## Request

- Base URL: `https://joinways.app/api/v1`
- URL: `https://joinways.app/api/v1/events/{id}`
- 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`)

Updates the given fields with the app's rules: archived event refused, end after start (checked when dates are sent), locked venue refused, venue availability, time zone following a venue change, billed party pushed to the unsigned quotes, calendars synchronised, timeline entries. Omitted fields stay as they are. With `status`, the status change has the effects of `POST /events/{id}/status` (notification, reasons cleared, Slack, calendars, webhook); the other fields are written first, so a refused field never leaves a half-applied status. **Role permission:** `data.write`; changing `status` or `stage_id` also needs `events.manage`.

## Headers

- `Idempotency-Key` string

## Request body

- EventUpdate: Every field is optional; omitted fields stay as they are.
  - `title` string
  - `start_date` string, date-time
  - `end_date` string, date-time
  - `status` 'option' | 'confirmed' | 'lost' | 'cancelled': `option` = pending / tentative, `confirmed` = booked, `lost` = did not convert, `cancelled` = cancelled after booking.
  - `stage_id` string, uuid, nullable: Custom stage under the (new) status; `null` clears it. Needs `events.manage`.
  - `type` string
  - `pax` integer
  - `budget` number
  - `venue_id` string, uuid: A venue of the workspace. Changing it without `space_ids` drops the previous venue's spaces; the time zone follows unless given.
  - `space_ids` string[]: Replaces the booked spaces; `[]` = the whole venue. Ignored for a venue only rented whole (`booked_whole_only`).
  - `company_id` string, uuid
  - `contact_person_id` string, uuid
  - `assigned_to_account_id` string, uuid: A member of the workspace.
  - `timezone` string: IANA time zone.
  - `source` string
  - `flexible` boolean
  - `confirmed_amount_excl_tax` number
  - `quote_to_platform` boolean: Bill the quotes to the booking platform of `source`. Clears `billing_company_id`.
  - `billing_company_id` string, uuid, nullable: Bill the quotes to this company instead of the client; `null` = the client. Clears `quote_to_platform`.
  - `selected_dates` string[], nullable: `[]`, `null` or a single day reverts to a contiguous range.
  - `day_hours` DayHoursEntry[], nullable: One entry for every day of the event, each day exactly once (`400 invalid_day_hours` otherwise); `null` = the same hours every day. An end at or before the start finishes the next morning, at 06:00 at the latest; the last day may not end between 00:00 and 06:00 without starting the evening before. `null` keeps `start_date` / `end_date`: on consecutive days, an end at or before the start then reads as one continuous stay, nights included. When an update moves `start_date` / `end_date` without `day_hours`, the first day's start and the last day's end follow them and the other days keep their hours; if a day no longer fits, the event goes back to the same hours every day (`day_hours: null` in the response).
    - `date` string, date, required
    - `start` string, required
    - `end` string, required

## Response `200`

The updated event.

- Event: The stored event, as returned by `POST /events`, `PATCH /events/{id}` and the conversion of a lead. Every column of the event is returned except the internal search fields, the embedding and the public tokens; the main ones are listed. Amounts are `null` without `reports.view` or `quotes.manage`.
  - `id` string, uuid
  - `account_id` string, uuid
  - `event_number` integer, nullable
  - `internal_reference` string, nullable
  - `title` string
  - `description` string, nullable
  - `type` string, nullable
  - `category` string, nullable
  - `status` 'option' | 'confirmed' | 'lost' | 'cancelled': `option` = pending / tentative, `confirmed` = booked, `lost` = did not convert, `cancelled` = cancelled after booking.
  - `status_changed_at` string, date-time, nullable
  - `stage_id` string, uuid, nullable
  - `stage_changed_at` string, date-time, nullable
  - `pax` integer, nullable
  - `start_date` string, date-time
  - `end_date` string, date-time, nullable
  - `selected_dates` string[], nullable
  - `day_hours` DayHoursEntry[], nullable: Per-day hours of a multi-day event, by date: one entry per day when the days have different hours, `null` when every day has the same hours (the time of `start_date` to the time of `end_date`) or for a one-day event.
    - `date` string, date, required
    - `start` string, required
    - `end` string, required
  - `timezone` string, nullable
  - `is_virtual` boolean, nullable
  - `flexible` boolean, nullable
  - `language` string, nullable
  - `venue_id` string, uuid, nullable: The venue (internally `location_id`).
  - `location` string, nullable: Free-text place (legacy), not the venue.
  - `address` string, nullable
  - `city` string, nullable
  - `postal_code` string, nullable
  - `country` string, nullable
  - `source` string, nullable
  - `source_lead_id` string, uuid, nullable: Primary request (lead) of the event.
  - `budget` number, nullable
  - `expected_revenue` number, nullable
  - `currency` string, nullable
  - `confirmed_amount` number, nullable
  - `confirmed_amount_excl_tax` number, nullable
  - `cancellation_fee_excl_tax` number, nullable
  - `confirmed_at` string, date-time, nullable
  - `loss_reason` string, nullable
  - `loss_reason_detail` string, nullable
  - `cancellation_reason` string, nullable
  - `cancellation_reason_detail` string, nullable
  - `tags` string[], nullable
  - `notes` string, nullable
  - `company_id` string, uuid, nullable
  - `contact_person_id` string, uuid, nullable
  - `assigned_to_account_id` string, uuid, nullable
  - `created_by` string, uuid, nullable
  - `billing_company_id` string, uuid, nullable: Third-party company the quotes are billed to (instead of the client).
  - `quote_to_platform` boolean, nullable: The quotes are billed to the booking platform of `source`.
  - `event_group_id` string, uuid, nullable
  - `external_link` string, nullable
  - `setup_type` string, nullable
  - `setup_notes` string, nullable
  - `catering_notes` string, nullable
  - `dietary_notes` string, nullable: Diets and allergies (« Contraintes alimentaires »), for the whole event.
  - `technical_notes` string, nullable
  - `service_notes` string, nullable
  - `beo_context` string, nullable
  - `beo_remarks` string, nullable
  - `schedule` object[], nullable: BEO program lines (see `BeoUpdate.schedule`).
  - `beo_public_url` string, uri, nullable: Shareable, no-login URL of the public BEO page.
  - `archived_at` string, date-time, nullable
  - `archived_by` string, uuid, nullable
  - `created_at` string, date-time, nullable
  - `updated_at` string, date-time, nullable

## 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 venue (or a booked space) is in `block` availability mode and the event's days or hours fall on a closure or outside its opening hours. `error.code` is `conflict`; `error.details` carries `reason: venue_unavailable`, `violation` (`VENUE_CLOSED` or `OUTSIDE_HOURS`) and the `closures` / `outside_hours` hit (see GET /venues/{venueId}/conflicts). In `warn` mode the event is saved.
- `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)