Documentation menu

Events reference

Event management (org-scoped).

GET/events

List events in the caller's organization

Parameters

NameInTypeRequiredDescription
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.
pagequeryintegeroptionalPage number to retrieve (1-based); integer, minimum 1, defaults to 1.
limitqueryintegeroptionalPage size (number of records per page); integer, minimum 1, maximum 100, defaults to 25.

Responses

  • 200Paginated events.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
POST/events

Create an event (manager+)

Parameters

NameInTypeRequiredDescription
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Request body EventCreate (required, application/json)

Responses

  • 201Created event.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 402Plan quota reached for this resource (code `QUOTA_EXCEEDED`).
  • 403Authenticated but not allowed (role or cross-org).
  • 429Rate limit exceeded.
GET/events/{id}

Get an event by id (must belong to the caller's org)

Parameters

NameInTypeRequiredDescription
idpathstringrequiredObjectId of the target event in the path. Used only by /events/{id}.
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Responses

  • 200The event.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
PATCH/events/{id}

Update an event (manager+)

Parameters

NameInTypeRequiredDescription
idpathstringrequiredObjectId of the target event in the path. Used only by /events/{id}.
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Request body EventUpdate (required, application/json)

Responses

  • 200Updated event.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
  • 429Rate limit exceeded.
DELETE/events/{id}

Soft-delete an event (manager+)

Parameters

NameInTypeRequiredDescription
idpathstringrequiredObjectId of the target event in the path. Used only by /events/{id}.
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Responses

  • 204Deleted.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
  • 429Rate limit exceeded.

Event schema

FieldTypeRequiredDescription
_idstringoptionalServer-generated MongoDB ObjectId uniquely identifying the event (read-only).
titlestringoptionalEvent name shown in the create/edit form; required, trimmed, non-empty string.
codestringoptionalServer-generated UUID identifying the event (read-only).
startstring (date-time)optionalEvent start date; required date (the form labels it "Event Start Date" and requires it to be at least one day in the future).
endstring (date-time)optionalEvent end date; required date that must be on or after the start date.
statusPRE_EVENT | POST_EVENT | COMPLETED | OPENoptionalEvent lifecycle status — one of PRE_EVENT ("Pre-event"), POST_EVENT ("Post-event"), COMPLETED ("Completed") or OPEN ("Open"); server-controlled and set by lifecycle/cron, not by the client.
formatstringoptionalEvent format — one of IN_PERSON ("In Person"), VIRTUAL ("Virtual") or HYBRID ("Hybrid"); required.
clientIdstringoptionalObjectId reference to the owning organization; set server-side from the authenticated caller and never accepted from the client.
clientNamestringoptionalDenormalized name of the owning client/organization, displayed as the read-only "Client Name" field.
categorystringoptionalOptional event category, selected from the organization's categories and stored as the category ObjectId.
currencystringoptionalOptional currency for the event budget, selected from the currency list.
projectJobNumberstringoptionalOptional project/job reference identifying the event; accepted and stored as a nullable string (no uniqueness enforced by the v2 API). The create/edit form surfaces it with the tooltip "This is an optional number that uniquely identifies your event".
departmentIdstringoptionalOptional ObjectId reference to the department/SBU the event belongs to.
userGroupIdstringoptionalOptional ObjectId reference to the user group the event is assigned to.
budgetstringoptionalOptional event budget amount (non-negative number).
countrystringoptionalOptional country where the event takes place, selected from the country list.
citystringoptionalOptional city, region or state where the event takes place.
summarystringoptionalOptional free-text note giving a brief summary of the event's activities.
venueNamestringoptionalOptional name of the event's main venue.
venueTypestringoptionalOptional venue type — typically Indoor, Outdoor or Both.
venueFormatstringoptionalOptional venue format for the event.
industryTypestringoptionalOptional industry/sector type of the event, inherited from the organization (the form shows it as a disabled, non-editable field).
emissionnumberoptionalComputed total event emissions in kgCO2e (read-only, server-calculated).
estimatedInPersonAttendiesnumberoptionalOptional estimated number of in-person attendees (non-negative; shown for in-person/hybrid events).
estimatedVirtualAttendiesnumberoptionalOptional estimated number of virtual attendees (non-negative; shown for virtual/hybrid events).
estimatedCrewMembersnumberoptionalOptional estimated number of staff/crew members for the event (non-negative).
fieldsToCalculatearray of stringoptionalOptional list of carbon-source parameters to include in emission calculations — e.g. ACCOMODATION_PARAMETER ("Accommodation"), FOODANDBEVVERAGES_PARAMETER ("Food and Beverages"), PRINTEDMATERIAL_PARAMETER ("Printed Materials"), VENUE_PARAMETER ("Venue (Energy)"), PRODUCTION_PARAMETER ("Production and Build Items"), TRAVEL_PARAMETER ("Travel"), WASTE_PARAMETER ("Waste Management"), VIRTUAL_PARAMETER ("Virtual") and TRANSPORTATION_PARAMETER ("Freight and Shipping"); defaults to all parameters.
createdAtstring (date-time)optionalServer-generated timestamp recording when the event was created (read-only).
updatedAtstring (date-time)optionalServer-generated timestamp recording when the event was last updated (read-only).

EventCreate schema

FieldTypeRequiredDescription
titlestringrequiredEvent name shown in the create/edit form; required, trimmed, non-empty string.
startstring (date-time)requiredEvent start date; required date (the form labels it "Event Start Date" and requires it to be at least one day in the future).
endstring (date-time)requiredEvent end date; required date that must be on or after the start date.
formatstringrequiredEvent format — one of IN_PERSON ("In Person"), VIRTUAL ("Virtual") or HYBRID ("Hybrid"); required.
categorystringoptionalOptional event category, selected from the organization's categories and stored as the category ObjectId.
currencystringoptionalOptional currency for the event budget, selected from the currency list.
projectJobNumberstringoptionalOptional project/job reference identifying the event; accepted and stored as a nullable string (no uniqueness enforced by the v2 API). The create/edit form surfaces it with the tooltip "This is an optional number that uniquely identifies your event".
departmentIdstringoptionalOptional ObjectId reference to the department/SBU the event belongs to.
userGroupIdstringoptionalOptional ObjectId reference to the user group the event is assigned to.
budgetstringoptionalOptional event budget amount (non-negative number).
countrystringoptionalOptional country where the event takes place, selected from the country list.
citystringoptionalOptional city, region or state where the event takes place.
summarystringoptionalOptional free-text note giving a brief summary of the event's activities.
venueNamestringoptionalOptional name of the event's main venue.
venueTypestringoptionalOptional venue type — typically Indoor, Outdoor or Both.
venueFormatstringoptionalOptional venue format for the event.
industryTypestringoptionalOptional industry/sector type of the event, inherited from the organization (the form shows it as a disabled, non-editable field).
estimatedInPersonAttendiesnumberoptionalOptional estimated number of in-person attendees (non-negative; shown for in-person/hybrid events).
estimatedVirtualAttendiesnumberoptionalOptional estimated number of virtual attendees (non-negative; shown for virtual/hybrid events).
estimatedCrewMembersnumberoptionalOptional estimated number of staff/crew members for the event (non-negative).
fieldsToCalculatearray of stringoptionalOptional list of carbon-source parameters to include in emission calculations — e.g. ACCOMODATION_PARAMETER ("Accommodation"), FOODANDBEVVERAGES_PARAMETER ("Food and Beverages"), PRINTEDMATERIAL_PARAMETER ("Printed Materials"), VENUE_PARAMETER ("Venue (Energy)"), PRODUCTION_PARAMETER ("Production and Build Items"), TRAVEL_PARAMETER ("Travel"), WASTE_PARAMETER ("Waste Management"), VIRTUAL_PARAMETER ("Virtual") and TRANSPORTATION_PARAMETER ("Freight and Shipping"); defaults to all parameters.