Add or Update Booking

POST [PlatformAddress]/api/1.0/venue?action=addOrUpdateBooking

Adds or updates the details of a venue booking. NOTE: The venue must have access to

normal bookings

in order to call this api action.

{
  "success": true,
  "id": 1234,
  "warnings": ["packageErrors", "packageSessionErrors"]
}

{
  "errorCode": 400,
  "message": "The request contains invalid data",
  "specificCode": 24297,
  "additionalMessages": [
    "dateEventEnd: End date has to be greater than the start date."
  ]
}

{
  "errorCode": 429
  "message": "Race condition error",
  "specificCode": 24299,
  "additionalMessages": []
}

{
  "errorCode": 500,
  "message": "An error has occurred",
  "specificCode": 24296,
  "additionalMessages": []
}

Booking

Property	Type	Required	Description
id	integer	optional	The unique id of the booking to update. A new booking will be created if this parameter is not present.
venueId	integer	required	The unique id of the venue to which the booking belongs.
leadId	integer	optional	The unique id of the opportunity to which the new booking will be assigned. Has no effect when updating a booking (i.e. an existing booking cannot be assigned to another opportunity).
bookingType	Booking Type	optional	The type of booking. Required when adding a new booking. Has no effect when updating a booking (i.e the type of an existing booking cannot be changed).
currentStatus	Booking Status	optional	The current status of the booking. Required when adding a new booking. Has no effect when updating a booking (i.e. the status of an existing booking cannot be changed). For example, to add a quote, the value should be 1.
code	string	optional	The unique reference code of the booking. Excluding this parameter from the request when adding a booking will cause the system to generate the code. The venue can be configured to prevent the code of an existing booking from being changed.
name	string	optional	The booking name. Required when adding a new booking.
companyId	integer	optional	The unique id of the company to assign to the booking. See assigning a company/contact to the booking.
company	object	optional	The data array of company. See addOrUpdateCompany API in contact namespace for parameters.
contactId	integer	optional	The unique id of the contact to assign to the booking See assigning a company/contact to the booking.
contact	object	optional	The data array of contact. See addOrUpdateContact API in contact namespace for parameters.
industryId	integer	optional	The unique id of the industry to which the contact belongs when a contact is assigned to the booking.
purchaseOrderNumber	string	optional	The purchase order number of the booking.
eventTypeId	integer	optional	The unique id of the booking event type. Required when adding a booking.
bookedById	integer	optional	The unique id of the account user who is the coordinator of the booking. Required when adding a new booking.
canBeMoved	boolean	optional	Whether or not the dates of the booking are flexible, and the booking itself can be moved to other dates.
dateEventStart	date	optional	The event start date of the booking. Required when adding a booking that includes event details. Has no effect if the venue doesn't have function space.
dateEventEnd	date	optional	The event end date of the booking. Required when adding a booking that includes event details. Has no effect if the venue doesn't have function space. When adding a booking with an event template, the end date cannot be more than 7 days after dateEventStart.
totalAttendees	integer	optional	The booking number of attendees. Required when adding a new booking. Has no effect when updating a booking (i.e. the number of attendees on a booking cannot be changed). When adding a booking with an event template, this number is assigned to the event template added to the booking.
packageId	integer	optional	The unique id of the event template that will be added to all event days (i.e. dateEventStart to dateEventEnd) of the new booking. Has no effect when updating a booking (i.e. this cannot be used to change the event templates on a booking). See adding an event template to a new booking.
packagePrice	float	optional	The price of the event template added to the new booking. Has no effect when updating a booking. Excluding this parameter from the request will cause the system to use the price assigned to the event template by the venue. The value is rounded to 3 decimal places.
isAccommIncluded	boolean	optional	Whether or not the booking includes accommodation. Has no effect if the venue doesn't have accommodation. Always true for accommodation only bookings.
dateAccomStart	date	optional	The earliest arrival date of the accommodation blocks on the booking. Required when adding a booking that includes accommodation. Has no effect if the venue doesn't have accommodation.
dateAccomEnd	date	optional	The latest departure date of the accommodation blocks on the booking. Required when adding a booking that includes accommodation. Has no effect if the venue doesn't have accommodation.
accommCutOffDate	date	optional	The cut off date for changes to the accommodation blocks on the booking. Only applies when the booking includes accommodation.
accommCancellationDate	date	optional	The date before which the accommodation blocks on the booking can be cancelled. Only applies when the booking includes accommodation.
accommChargingMethod	Charging Method	optional	The method used to charge for the accommodation blocks on the booking. Only applies when the booking includes accommodation.
accommGuaranteeRequired	boolean	optional	Whether or not a guarantee is required for the accommodation blocks on the booking. Only applies when the booking includes accommodation.
accommExternalBlockId	string	optional	The block id from an external pms (property management system). Only applies when the booking includes accommodation.
accommReservationMethod	Reservation Method	optional	The method by which attendees will reserve rooms from the accommodation blocks on the booking. Only applies when the booking includes accommodation.
accommReservationCancellationDate	date	optional	The date after which reservations from the accommodation blocks cannot be cancelled. Only applies when the booking includes accommodation.
accommArrivalMethod	Arrival Method	optional	The method by which the group attendees will arrive at the venue. Only applies when the booking includes accommodation.
isConfidential	boolean	optional	Whether or not the booking is confidential. Only applies when the venue's account has access to confidential meetings.
otaFolioRef	string	optional	The Folio ID from the external postings extension installed by the venue.
bookingRoleUserId1	string	optional	The unique id of the account user assigned to the booking role label 1
bookingRoleUserId2	string	optional	The unique id of the account user assigned to the booking role label 2
bookingRoleUserId3	string	optional	The unique id of the account user assigned to the booking role label 3
bookingRoleUserId4	string	optional	The unique id of the account user assigned to the booking role label 4
bookingRoleUserId5	string	optional	The unique id of the account user assigned to the booking role label 5
customFields	array of Custom Field	optional	The custom field values of the booking. A custom field value might be required depending on how it has been configured in the venue's account.
discountCode	string	optional	The discount code applied to the booking
externalUrls	array of ExternalUrl Field	optional	This is an array of External URL field objects of the booking (a maximum of 3 objects allowed). When set to null, it will remove all externalUrls from the booking.

Property

Type

Required

Description

integer

optional

The unique id of the booking to update. A new booking will be created if this parameter is not present.

venueId

integer

required

The unique id of the venue to which the booking belongs.

leadId

integer

optional

The unique id of the opportunity to which the new booking will be assigned. Has no effect when updating a booking (i.e. an existing booking cannot be assigned to another opportunity).

bookingType

Booking Type

optional

The type of booking. Required when adding a new booking. Has no effect when updating a booking (i.e the type of an existing booking cannot be changed).

currentStatus

Booking Status

optional

The current status of the booking. Required when adding a new booking. Has no effect when updating a booking (i.e. the status of an existing booking cannot be changed). For example, to add a quote, the value should be 1.

code

string

optional

The unique reference code of the booking. Excluding this parameter from the request when adding a booking will cause the system to generate the code. The venue can be configured to prevent the code of an existing booking from being changed.

name

string

optional

The booking name. Required when adding a new booking.

companyId

integer

optional

The unique id of the company to assign to the booking. See assigning a company/contact to the booking.

company

object

optional

The data array of company. See addOrUpdateCompany API in contact namespace for parameters.

contactId

integer

optional

The unique id of the contact to assign to the booking See assigning a company/contact to the booking.

contact

object

optional

The data array of contact. See addOrUpdateContact API in contact namespace for parameters.

industryId

integer

optional

The unique id of the industry to which the contact belongs when a contact is assigned to the booking.

purchaseOrderNumber

string

optional

The purchase order number of the booking.

eventTypeId

integer

optional

The unique id of the booking event type. Required when adding a booking.

bookedById

integer

optional

The unique id of the account user who is the coordinator of the booking. Required when adding a new booking.

canBeMoved

boolean

optional

Whether or not the dates of the booking are flexible, and the booking itself can be moved to other dates.

dateEventStart

date

optional

The event start date of the booking. Required when adding a booking that includes event details. Has no effect if the venue doesn't have function space.

dateEventEnd

date

optional

The event end date of the booking. Required when adding a booking that includes event details. Has no effect if the venue doesn't have function space. When adding a booking with an event template, the end date cannot be more than 7 days after dateEventStart.

totalAttendees

integer

optional

The booking number of attendees. Required when adding a new booking. Has no effect when updating a booking (i.e. the number of attendees on a booking cannot be changed). When adding a booking with an event template, this number is assigned to the event template added to the booking.

packageId

integer

optional

The unique id of the event template that will be added to all event days (i.e. dateEventStart to dateEventEnd) of the new booking. Has no effect when updating a booking (i.e. this cannot be used to change the event templates on a booking). See adding an event template to a new booking.

packagePrice

float

optional

The price of the event template added to the new booking. Has no effect when updating a booking. Excluding this parameter from the request will cause the system to use the price assigned to the event template by the venue. The value is rounded to 3 decimal places.

isAccommIncluded

boolean

optional

Whether or not the booking includes accommodation. Has no effect if the venue doesn't have accommodation. Always true for accommodation only bookings.

dateAccomStart

date

optional

The earliest arrival date of the accommodation blocks on the booking. Required when adding a booking that includes accommodation. Has no effect if the venue doesn't have accommodation.

dateAccomEnd

date

optional

The latest departure date of the accommodation blocks on the booking. Required when adding a booking that includes accommodation. Has no effect if the venue doesn't have accommodation.

accommCutOffDate

date

optional

The cut off date for changes to the accommodation blocks on the booking. Only applies when the booking includes accommodation.

accommCancellationDate

date

optional

The date before which the accommodation blocks on the booking can be cancelled. Only applies when the booking includes accommodation.

accommChargingMethod

Charging Method

optional

The method used to charge for the accommodation blocks on the booking. Only applies when the booking includes accommodation.

accommGuaranteeRequired

boolean

optional

Whether or not a guarantee is required for the accommodation blocks on the booking. Only applies when the booking includes accommodation.

accommExternalBlockId

string

optional

The block id from an external pms (property management system). Only applies when the booking includes accommodation.

accommReservationMethod

Reservation Method

optional

The method by which attendees will reserve rooms from the accommodation blocks on the booking. Only applies when the booking includes accommodation.

accommReservationCancellationDate

date

optional

The date after which reservations from the accommodation blocks cannot be cancelled. Only applies when the booking includes accommodation.

accommArrivalMethod

Arrival Method

optional

The method by which the group attendees will arrive at the venue. Only applies when the booking includes accommodation.

isConfidential

boolean

optional

Whether or not the booking is confidential. Only applies when the venue's account has access to confidential meetings.

otaFolioRef

string

optional

The Folio ID from the external postings extension installed by the venue.

bookingRoleUserId1

string

optional

The unique id of the account user assigned to the booking role label 1

bookingRoleUserId2

string

optional

The unique id of the account user assigned to the booking role label 2

bookingRoleUserId3

string

optional

The unique id of the account user assigned to the booking role label 3

bookingRoleUserId4

string

optional

The unique id of the account user assigned to the booking role label 4

bookingRoleUserId5

string

optional

The unique id of the account user assigned to the booking role label 5

customFields

array of Custom Field

optional

The custom field values of the booking. A custom field value might be required depending on how it has been configured in the venue's account.

discountCode

string

optional

The discount code applied to the booking

externalUrls

array of ExternalUrl Field

optional

This is an array of External URL field objects of the booking (a maximum of 3 objects allowed). When set to null, it will remove all externalUrls from the booking.

Booking Type

The following booking types are supported when adding a new booking.

Value	Description
1	A detailed booking that can include both event templates, and accommodation. Available only when the venue has function space.
4	A booking that only has accommodation. Available only when the venue has accommodation.

Value

Description

A detailed booking that can include both event templates, and accommodation. Available only when the venue has function space.

A booking that only has accommodation. Available only when the venue has accommodation.

Booking Status

The following booking status options are supported when adding a new booking.

Value	Description
1	Prospective
2	Tentative
3	Confirmed
5	Ordering
9	Prospective Hold

Accommodation Charging Methods

The following lists the accommodation charging method options.

Value	Description
0	None
1	Individual Pays Own
2	Bill to Master
3	Combined
4	Complimentary

Accommodation Reservation Methods

The following lists the accommodation reservation method options.

Value	Description
1	Rooming List
2	Individual Call-In
3	Booking Engine
4	Housing Form

Accommodation Arrival Methods

The following lists the accommodation arrival method options.

Value	Description
1	Together
2	Individually

Value

Description

Together

Individually

Custom Field

A booking custom field is an object with the following details.

Property	Type	Required	Description
fieldId	integer	required	The unique id of the booking custom field
fieldValue	mixed	required	The value of the booking custom field. Depends on the type of custom field value.

Property

Type

Required

Description

fieldId

integer

required

The unique id of the booking custom field

fieldValue

mixed

required

The value of the booking custom field. Depends on the type of custom field value.

External URL Field

An External URL field is an object with the following details.

Property	Type	Required	Description
ref	string	required	The unique reference key of the external URL
url	string	optional	The url link (https) scheme eg. https://example.com When the value is null, the external url record will be removed based on the provided reference key.
label	string	optional	The label of the URL to display.

Property

Type

Required

Description

ref

string

required

The unique reference key of the external URL

url

string

optional

The url link (https) scheme eg. https://example.com When the value is null, the external url record will be removed based on the provided reference key.

label

string

optional

The label of the URL to display.

Special Considerations

Assigning a company/contact to the booking

The contact type of a booking is either a company or a contact. When companyId or company is present in the request then the contact type of the booking is set to company, and the contactId or contact must be a contact that belongs to that company. Otherwise the contact type of the booking is set to contact and contactId can be any valid contact in the venue's account.

If contact and company are present in request then it will link given contact to company.

A quote (i.e. booking status is prospective) that is assigned to an opportunity is forced to have the same companyId and contactId of the opportunity. Trying to change these values to something else will have no effect when updating the quote.

Adding an event template to a new booking

Setting packageId in the request when adding a new booking will attempt to add that event template to all event days of the booking after the booking is created. There is no guarantee that the event template will be successfully added to all days of the booking. When the event template cannot be added to the booking, one or more warnings will be returned in the response.

There are also the following additional restrictions:

An event template can only be added when the venue has function spaces.
An event template can only be added to a detailed booking.
The maximum number of event days when adding an event template is 7.
packagePrice will be rounded to 3 decimal places if present in the request.

Updating a booking

Updating a booking (i.e. by setting id in the request) is an overlay action. This means the request can include only the details of the booking to be changed. This does not necessarily mean the operation will succeed. For example, the request might include the dateEventEnd value, and not the dateEventStart value. This scenario will fail if the value of dateEventEnd is earlier than the current dateEventStart value of the booking.

Response Warnings

Value	Description
packageErrors	The way the venue has configured the event template prevents it from being added to one or more event days of the booking.
packageSessionErrors	One or more sessions of the event template could not be added to the booking. This is usually caused by conflicting reservations on function space.

Value

Description

packageErrors

The way the venue has configured the event template prevents it from being added to one or more event days of the booking.

packageSessionErrors

One or more sessions of the event template could not be added to the booking. This is usually caused by conflicting reservations on function space.

Unsupported Features

The following features are currently not supported by this api action:

Recurring bookings
Simple booking types
Discount settings
Commission settings
Multi language content

PreviousGet Booking Release Schedule NextChange Booking Status

Last updated 2 months ago