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 Room Reservation
  • Booking Room Reservation
  • Reserved Room
  • Reserved Room Day Rates
  • Reserved Room Additional Guests
  • Guest
  • Guest Contact Details
  • Additional Guest Type
  • Occupancy Type
  • Notes on adding a room reservation
  • Notes on updating a room reservation
  • Updating additional guests on a reserved room
  • Notes on guest details in the request
  1. Venue
  2. Booking Accommodation Data

Add or Update Booking Room Reservation

Add or Update Booking Room Reservation

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

Adds or updates the details of a specific room reservation on a specific venue booking. The booking must satisfy the following:* Accommodation is included, and the booking has accommodation groups.* The status must be "not confirmed", "confirmed", "checked in" or "checked out"

{
  "success": true,
  "id": 123,
  "reference": "45",
  "mainGuest": {
    "id": 101,
    "guestContactId": 43213
  },
  "rooms": [
    {
      "id": 4001,
      "guest": {
        "id": 101,
        "guestContactId": 43213
      },
      "additionalGuests": []
    },
    {
      "id": 4002,
      "guest": {
        "id": 102,
        "guestContactId": 44321
      },
      "additionalGuests": [
        {
          "guestId": 103,
          "guestContactId": 43277,
          "guestType": 2
        }
      ]
    }
  ]
}
{
  "errorCode": 400,
  "message": "The request contains invalid data",
  "specificCode": 24257,
  "additionalMessages": [
      "firstName: Value is required and can't be empty"
  ],
}

Booking Room Reservation

Property
Type
Required
Description

id

integer

optional

The unique id of the room reservation to update - a new room reservation will be created if this parameter is not present

venueId

integer

required

The unique id of the venue to which the booking belongs

bookingId

integer

required

The unique id of the booking to which the room reservation belongs

canBeEdited

boolean

optional

Whether or not updates to the booking room reservation are allowed

mainGuest

required on add, optional on update

Details of the main guest of the room reservation

rooms

required on add, optional on update

Details of the individually reserved rooms on the reservation

removeRooms

array of integers

optional

The unique id of the individual rooms to remove from an existing reservation

Reserved Room

Property
Type
Required
Description

id

integer

optional

The unique id of the individual reserved room on the reservation to update. Omit this to create a new room on the reservation

guest

required on add, optional on update

Details of the guest on the individual reservation room

groupId

integer

required on add, optional on update

arrivalDate

date

required on add, optional on update

The arrival date of the reserved room

departureDate

date

required on add, optional on update

The departure date of the reserved room

excludedTaxIds

array of integers

optional

The unique ids of the taxes that are excluded from the daily rates

numAdultGuests

integer

required on add, optional on update

The number of adults on the reserved room. The value cannot exceed 10

numChildGuests

integer

required on add, optional on update

The number of children on the reserved room. The value cannot exceed 10

dayRates

required on add, optional on update

The daily rates of the reserved room

additionalGuests

optional

The additional guests of the reserved room

overrideBlockCapacity

boolean

optional

Whether or not the reservations can exceed the block capacity

externalReference

text

optional

External system identifier for this reserved room. eg. PMS ID. Allowed max length is 254 Characters.

occType

integer

optional

Reserved Room Day Rates

Property
Type
Required
Description

dayDate

date

required

The date of the reserved room to which the rate applies

cost

number

required

The rate amount for the reserved room on dayDate. The amount either includes or excludes tax depending on how the venue is configured

Reserved Room Additional Guests

Property
Type
Required
Description

guestId

integer

required when guest is not set

The identifier of guest being updated on the reserved room

guest

required when guestId is not set

The additional guest details for the reserved room

arrivalDate

date

optional

The arrival date of the additional guest

departureDate

date

optional

The departure date of the additional guest

guestType

enum

optional (required for new guests)

Guest

Property
Type
Required
Description

id

integer

optional

The unique id of the venue guest to update

guestContact

required on add, optional on update

The contact details of the guest

primaryPhone

string

optional

The primary phone number of the guest

address

optional

The address of the guest

Guest Contact Details

Property
Type
Required
Description

firstName

string

required

The first name of the contact

lastName

string

required

The last name of the contact

email

string

required

The email address of the contact

phone

string

optional

The mobile phone number of the contact

Additional Guest Type

One of the following values

#
Description

1

Sharer

2

Accompanying

Occupancy Type

One of the following values

#
Description

1

Single

2

Double

3

Triple

4

Quad

Notes on adding a room reservation

Notes on updating a room reservation

Updating an existing room reservation overlays the existing data. Optional request data that is excluded will not change existing data (with the exception of additionalGuests - see below). This does not guarantee that the request data will validate if other data is changed. For example, if the departure date of a reserved room is extended, rates for the new dates will be required.

The following is an example of an update request that updates an existing room (id 400) and adds a new room:

"rooms": [
  {
    "id": 400,
    "arrivalDate": "2019-01-01",
    "departureDate": "2019-02-03",
    "dayRates": [
      {
        "dayDate": "2019-01-01",
        "cost": 100
      },
      {
        "dayDate": "2019-01-02",
        "cost": 101
      }
    ]
  },
  {
    "guest": {
      "id": 301
    },
    "groupId": 1,
    "arrivalDate": "2019-01-01",
    "departureDate": "2019-02-03",
    "numAdultGuests": 1,
    "numChildGuests": 0,
    "dayRates": [
      {
        "dayDate": "2019-01-01",
        "cost": 100
      },
      {
        "dayDate": "2019-01-02",
        "cost": 101
      }
    ]
]

Existing rooms can be removed from a reservation by passing their unique identifier in the removeRooms of the request. Rooms are removed before other rooms in the request are added/updated.

Updating additional guests on a reserved room

The additionalGuests request param can be used to set the additional guest details of a reserved room. If this value is present in the request, it will become the new list of additional guests on the room. Therefore if you do not want to remove an additional guest, it must be present (at least the guestId value) in the array.

If the value is not present in the request, the existing list of additional guests will remain. The details of the additional guests will still be validated against the updated reservation details. For example, if the arrivalDate of the reserved rooms is updated, the new value will be validated against the existing additional guests. If the arrivalDate of an existing additional guest is invalid, the request will be rejected.

Notes on guest details in the request

Guests are uniquely identified based on the following (in order): 1) The unique id value of the guest. 2) The combination of the guest's email, firstName, and lastName (case insensitive).

{
  "id": 101,
  "primaryPhone": "123456789"
}

{
  "guestContact": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@somewhere.com",
  },
  "primaryPhone": "0419111222"
}

The first object will update the guest with the unique id 101. The request will fail if the guest does not exist. Only the primaryPhone of the guest will be updated.

The second object will either create a new guest or update an existing one. If a guest already exists with the firstName "John", lastName "Doe", and email "john.doe@somewhere.com" then that guest will be updated (only the primaryPhone of the guest will be updated). Otherwise a new guest will be created.

If the same guest details appear multiple times in the request, only the details of the first guest are applied. For example, consider the following request data (some details are omitted for simplicity):

{
  "venueId": 13,
  "bookingId": 1413,
  "mainGuest": {
    "guestContact": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "John.Doe@somewhere.com",
      "phone": "12345678",
    },
    "primaryPhone": "12345678"
  },
  "rooms": [
    {
      "guest": {
        "guestContact": {
          "firstName": "John",
          "lastName": "Doe",
          "email": "John.Doe@somewhere.com",
          "phone": "87654321",
        },
        "primaryPhone": "87654321"
      },
      "groupId": 54,
      "arrivalDate": "2019-01-01",
      "departureDate": "2019-01-04"
    },
    {
      "guest": {
        "guestContact": {
          "firstName": "Jane",
          "lastName": "Doe",
          "email": "Jane.Doe@somewhere.com",
          "phone": "123123123",
        },
        "primaryPhone": "123123123"
      },
      "groupId": 55,
      "arrivalDate": "2019-01-01",
      "departureDate": "2019-01-04"
    }
  ]
}

There are 2 unique guests in the above request data: John Doe, and Jane Doe. John Doe appears in the request twice (first as mainGuest and second as the guest on the first room). The details of the first appearance will be used when updating John Doe, therefore the primaryPhone value will be "12345678", not "87654321".

PreviousGet Booking Room Reservation ListNextUpdate Room Reservation Guest Contact

Last updated 8 months ago

array of

The unique id of the from which the room is reserved

array of

array of

The occupancy type of the reserverd room. See

The sharing type of additional guest. See

This action only supports adding a "not confirmed" room reservation. To add a "confirmed" room reservation, you will need to call the action after a successfull add.

This action only supports adding a room reservation to a booking that has . The on the reservation must be assigned to a group.

Consider the following objects:

guest
Address
Guest
Reserved Rooms
Guest
Day Rates
Additional Guests
Occupancy Type
Guest
Additional Guest Type
Contact
rooms
confirmBookingRoomReservation
accommodation groups
accommodation group