Events

Create an event

Creates an event with the app's rules: venue availability (block mode refuses a closure or hours outside opening, 409), locked venue refused, rooms of the venue only, contact and company found or created, a booking platform name given as company_name becomes the event source instead of a client company, calendars synchronised. The response is the stored event; warnings lists what could not be done (space_ids_not_booked). Role permission: events.manage.

post/events

Request

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

Headers

Idempotency-Keystring

Optional client-generated key (1 to 255 characters, e.g. a UUID v4) that makes the request idempotent for 24 hours: a retry with the same key replays the recorded response (marked Idempotency-Replayed: true) instead of executing the operation again. Same key with another body: 422 idempotency_key_reuse; while the first request runs: 409 idempotency_conflict. See the Idempotency section.

Request body

titlestring required
start_datestring date-time required

Start (ISO 8601; a YYYY-MM-DD day is accepted).

end_datestring date-time

End, after the start. Defaults to start_date.

venue_idstring uuid

The venue to book (internally location_id); a venue, not a space (pass spaces in space_ids). Defaults to the workspace's only active venue; with several, it is required (400 venue_required).

status'option' | 'confirmed' | 'lost' | 'cancelled'

option = pending / tentative, confirmed = booked, lost = did not convert, cancelled = cancelled after booking.

typestring

Event type, e.g. dinner.

paxinteger
budgetnumber
company_idstring uuid

An existing company of the workspace.

company_namestring

Company found by name or created. A booking platform name (Aleou, Kactus…) is not a client: it becomes the event source.

contact_person_idstring uuid

An existing contact of the workspace, instead of the contact_* fields.

contact_first_namestring
contact_last_namestring
contact_emailstring email

Contact found by email or created.

contact_phonestring
assigned_to_account_idstring uuid

A member of the workspace (400 invalid_assignee otherwise). Defaults to the token owner.

timezonestring

IANA time zone. Defaults to the venue's.

space_idsstring[]

Spaces (rooms) of the venue the event books; omitted or empty = the whole venue. Ignored for a venue only rented whole (booked_whole_only).

sourcestring

Origin of the request, e.g. platform:Kactus.

flexibleboolean
selected_datesstring[]

Non-contiguous days (YYYY-MM-DD). With 2 or more distinct days, start_date / end_date are the time envelope and these days are the event's days.

Example request

{
  "status": "confirmed",
  "timezone": "Europe/Paris",
  "day_hours": [
    {
      "date": "2026-11-12",
      "start": "09:00",
      "end": "18:00"
    },
    {
      "date": "2026-11-13",
      "start": "19:00",
      "end": "02:00"
    }
  ]
}

Response

The created event.

idstring uuid
account_idstring uuid
event_numberinteger nullable
internal_referencestring nullable
titlestring
descriptionstring nullable
typestring nullable
categorystring nullable
status'option' | 'confirmed' | 'lost' | 'cancelled'

option = pending / tentative, confirmed = booked, lost = did not convert, cancelled = cancelled after booking.

status_changed_atstring date-time nullable
stage_idstring uuid nullable
stage_changed_atstring date-time nullable
paxinteger nullable
start_datestring date-time
end_datestring date-time nullable
selected_datesstring[] nullable
timezonestring nullable
is_virtualboolean nullable
flexibleboolean nullable
languagestring nullable
venue_idstring uuid nullable

The venue (internally location_id).

locationstring nullable

Free-text place (legacy), not the venue.

addressstring nullable
citystring nullable
postal_codestring nullable
countrystring nullable
sourcestring nullable
source_lead_idstring uuid nullable

Primary request (lead) of the event.

budgetnumber nullable
expected_revenuenumber nullable
currencystring nullable
confirmed_amountnumber nullable
confirmed_amount_excl_taxnumber nullable
cancellation_fee_excl_taxnumber nullable
confirmed_atstring date-time nullable
loss_reasonstring nullable
loss_reason_detailstring nullable
cancellation_reasonstring nullable
cancellation_reason_detailstring nullable
tagsstring[] nullable
notesstring nullable
company_idstring uuid nullable
contact_person_idstring uuid nullable
assigned_to_account_idstring uuid nullable
created_bystring uuid nullable
billing_company_idstring uuid nullable

Third-party company the quotes are billed to (instead of the client).

quote_to_platformboolean nullable

The quotes are billed to the booking platform of source.

event_group_idstring uuid nullable
external_linkstring nullable
setup_typestring nullable
setup_notesstring nullable
catering_notesstring nullable
dietary_notesstring nullable

Diets and allergies (« Contraintes alimentaires »), for the whole event.

technical_notesstring nullable
service_notesstring nullable
beo_contextstring nullable
beo_remarksstring nullable
scheduleobject[] nullable

BEO program lines (see BeoUpdate.schedule).

beo_public_urlstring uri nullable

Shareable, no-login URL of the public BEO page.

archived_atstring date-time nullable
archived_bystring uuid nullable
created_atstring date-time nullable
updated_atstring date-time nullable
warningsstring[]

Only present when something could not be done: space_ids_not_booked, day_hours_not_saved (the event is created with the same hours every day).

Example response

{
  "status": "confirmed",
  "day_hours": [
    {
      "date": "2026-11-12",
      "start": "09:00",
      "end": "18:00"
    },
    {
      "date": "2026-11-13",
      "start": "19:00",
      "end": "02:00"
    }
  ],
  "beo_public_url": "https://joinways.app/beo/8f3c2a1e-…",
  "warnings": [
    "space_ids_not_booked"
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.