iVvy Developer API
  • API Documentation
  • Getting Started
    • Obtaining Keys
    • Creating the request
      • Method/URI Header
      • Request Headers
        • Standard Headers
        • Custom Headers
      • Signing the request
      • Query Parameters
    • Test Ping
    • Interpreting the response
      • Collections
      • Pagination
      • Filtering
      • Exceptions
      • Response Headers
      • Dates
    • Batch
      • Run
      • Progress
      • Result
      • Restart
      • Repost
    • Use Cases
      • CRM Systems
      • Financial Accounting Systems
      • Point Of Sale
      • Property Management Systems
  • Contacts & Companies
    • Get Contact List
    • Get Contact
    • Get Contact Note List
    • Add or Update Contact
    • Get Contact Custom Field Definition
    • Get Company Custom Field Definition
    • Get Subscription Group List
    • Add Contacts To Subscription Group
    • Remove Contacts From Subscription Group
    • Get Company List
    • Get Company
    • Get Company Note List
    • Add or Update Company
    • Add or Update Lead
    • Add or Update Contact Note
    • Add or Update Company Note
  • Event
    • Add or Update Event
    • Get Event List
    • Get Event
    • Get Registration
    • Get Registration List
    • Get Attendee
    • Get Attendee List
    • Get Invited Contact List
    • Invite Contacts
    • Get Sponsorship List
    • Get Speaker List
    • Get Session List
    • Create Login Token
  • Venue
    • Venue Setup Data
      • Get Venue
      • Get Venue List
      • Get Venue Room List
      • Get Venue Room Option List
      • Get Venue Rate Plan List
      • Get Venue Rate Plan Rate List
      • Get Venue Rate Plan Room Rate List
      • Get Resource List
      • Get Resource Availability
      • Get Menu List
      • Get Beverage Package List
      • Get Function Space List
      • Get Space Blockout List
      • Get Function Space Category List
      • Get Function Space Availability
      • Get Function Space Hire Plan Rate List
      • Get Function Space Hire Plan Rate
      • Get Cost Center List
      • Get Session Type List
      • Get Revenue Template List
      • Get Tax List
      • Add or Update Function Space
      • Get Event Type List
      • Add or Update Function Space Category
      • Add or Update Guest Room
      • Get Booking Custom Field List
      • Get Space Hire Plans
      • Get Venue Package List
      • Get Venue Package
    • Booking Data
      • Convert Lead To Opportunity
      • Add or Update Opportunity
      • Get Booking
      • Get Booking List
      • Get Booking List For Account
      • Get Booking Notes
      • Get Booking Session List
      • Get Booking Session Menu List
      • Get Booking Changelog List
      • Get Booking Attendee (By Hash)
      • Get Booking Attendee List
      • Get Booking Release Schedule
      • Add or Update Booking
      • Change Booking Status
      • Add Items To Booking
      • Add Payment To Booking
      • Add Refund To Booking
      • Add or Update Booking Attendee
      • Add or Update Booking Note
      • Add or Update Booking Session
      • Add or Update Booking Session Beverage
      • Add or Update Booking Session Menu
      • Add or Update Booking Session Resource
      • Remove Booking Session
      • Remove Booking Session Beverage
      • Remove Booking Session Menu
      • Remove Booking Session Resource
      • Get Space Blockout List
      • Add or Update Blockout Space
      • Remove Blockout Space
      • Get Booking Tax List
      • Add or Update Opportunity Note
      • Upload Booking Document
    • Booking Accommodation Data
      • Get Booking Accommodation List
      • Add or Update Booking Accommodation
      • Remove Booking Accommodation
      • Get Booking Room Reservation List
      • Add or Update Booking Room Reservation
      • Update Room Reservation Guest Contact
      • Remove Booking Room Reservation
      • Confirm Booking Room Reservation
      • Cancel Booking Room Reservation
      • Change Status of Booking Room Reservation
      • Add or Update Room Counts
      • Add or Update Room Dynamic Rates
      • Remove Room Dynamic Rates
      • Add or Update Rate Plan Booking Rules
  • Partner
    • Get Venue List
    • Get Venue
  • Invoice
    • Get Invoice List
    • Get Invoice
    • Get Options
    • Add Payment
    • Get Credit Note List
    • Get Credit Note
  • Account
    • Add or Update Cost Center
    • Get Cost Center List
    • Get Email Log List
    • Add Error Report
    • Get Account User List
  • CRM
    • Get Lead List
    • Get Opportunity List
    • Get Opportunity Note List
    • Get Task List
    • Get Activity List
    • Get Lead Stage List
    • Get Lead Type List
    • Get Lead Quality List
    • Get Lead Source List
    • Get Lead Channel List
    • Get Lead Note List
    • Add or Update Activity Purpose
    • Add or Update Activity
    • Add or Update Task
    • Add or Update Lead Quality
    • Add or Update Lead Stage
    • Add or Update Lead Channel
    • Add or Update Lead Type
    • Add or Update Lead Source
    • Add or Update Lead Note
  • Notifications
    • Company Endpoint
    • Contact Endpoint
    • CRM Endpoint
    • Invoice Endpoint
    • Booking Endpoint
    • Event Endpoint
  • Development Reference
    • Calculating md5
    • HMAC-SHA1
    • JSON Encoding
    • Timestamp Format
    • Date Format
    • Time Format
    • Address Format
    • URLEncoding
    • Timezone List
  • Announcements
    • Room Reservation Contact Changes
    • Contact Customfield Changes
    • Booking Accommodation API Changes
Powered by GitBook
On this page
  • Add or Update Booking
  • Booking
  • Booking Type
  • Booking Status
  • Accommodation Charging Methods
  • Accommodation Reservation Methods
  • Accommodation Arrival Methods
  • Custom Field
  • External URL Field
  • Special Considerations
  • Assigning a company/contact to the booking
  • Adding an event template to a new booking
  • Updating a booking
  • Response Warnings
  • Unsupported Features
  1. Venue
  2. Booking Data

Add or Update Booking

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

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

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

company

object

optional

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

contactId

integer

optional

contact

object

optional

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

industryId

integer

optional

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

totalAttendees

integer

optional

packageId

integer

optional

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

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

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

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

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

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.

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

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.

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.

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

There are also the following additional restrictions:

  • An event template can only be added when the venue has function spaces.

  • 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.

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 ScheduleNextChange Booking Status

Last updated 7 months ago

The unique id of the company to assign to the booking. See .

The unique id of the contact to assign to the booking See .

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

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 , the end date cannot be more than 7 days after dateEventStart.

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 , this number is assigned to the event template added to the booking.

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 .

array of

array of Field

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 will be returned in the response.

An event template can only be added to a booking.

warnings
detailed
Booking Type
Booking Status
assigning a company/contact to the booking
assigning a company/contact to the booking
assigned to the booking
adding a booking with an event template
adding a booking with an event template
adding an event template to a new booking
Charging Method
Reservation Method
Arrival Method
Custom Field
ExternalUrl