Version 2.0.0

OnceHub API version 2 is here! Here are the changes you should be aware of.

This is a major new release that introduces the following:

1. changes to our existing booking object.

and

2. new objects to use when reading data from your account

• booking page object
• master page object
• event type object
• user object

The booking object

These are some of the breaking changes in the booking object that are also included as a payload in the events sent via webhooks.
Any webhook created with this api version will have the new booking data changes included.

Booking status

In version 1, the booking status can contain the following values

["Requested", "Scheduled", "Rescheduled", "Completed", "Canceled", "No-Show"]

These will now be changed to:

["requested", "scheduled", "rescheduled", "completed", "canceled", "no_show"]

This makes it more compatible with our overall api syntax.

External calendar type

In version 1, the booking object contains an external calendar type:

"external_calendar": { 
  "type": "Google", 
  "name": "[email protected]",
  "id": "[email protected]",
  "event_id": "8kvu74dda8kcv0gmmlm3folrhc"
}

The type field in version 1 could contain the following values:

["Google", "Exchange", "Office_365", "iCloud"]

We have changed the type field to snake case too, so the options will be:

["google", "exchange", "office_365", "icloud"]

Collapsed properties by default

In our first api version, objects that were embedded in the booking object were expanded by default
For example, the booking object contained an embedded master page object:
Before

{
   "object": "booking",
   // ...
   "master_page": {
     "id": "MP-ZID28U5946",
     "name": "Financial Services Inc.",
     "label": "financefirm",
     "link": "https://go.oncehub.com/financefirm"
   }
 }

To improve performance when returning a large list of bookings, we have changed the default behavior to return the embedded object in a “collapsed” format which means that we are only returning the id of that object:
After

{
 "object": "booking",
 // ...
 "master_page": "BP-ZID28U5946"
}

And if the user chooses to, they will be able to ask us to expand that object into a full object via the api query parameter.
The breaking change is that this will be collapsed by default in version 2 when retrieving bookings.

You can read more about it in our "expanding resources" section of the api reference.

Timezone description

Previously, booking objects contained a property named time_zone_description. An example of a value is

"time_zone_description": "(GMT-5) United States; Eastern time"

This string is non standard, and cannot easily be parsed by any library that deals with time / time zones and therefor not very useful. We have removed it in version 2.0.0 and plan to introduce an improved time zone string in the future.

Booking page and event types categories

Another field that is being removed from the booking page and event types objects is category. For example (previously):

"category": "Financial planning firm"

Owner field

In version 1 the booking owner field contains the name of the user.
Before

"owner": "Andrea Hartie"

In version 2 we have updated the value to the user id, since the user data can also be retrieved using the GET users endpoint. The same expanding functionality has been added to the owner field in the booking object.

After

"owner": "USR-FSD423423"

Virtual or physical location

In version 1 the booking object contained a field named virtual_or_physical_location for example:
Before

{
  "object": "booking",
  // ...
  "virtual_or_physical_location": "1600 Pennsylvania Avenue"
}

The virtual_or_physical_location value was either a location or a meeting link. That makes it more difficult to work with. Now there will be two separate fields for these values.
On a single booking only one of them will be populated.

The new format will look like this:
After

{
  "object": "booking",
  // ...
  "virtual_conferencing": {
    "join_url": "https://meet.google.com/2323523"
  }
  "location_description": "1600 Pennsylvania Avenue"
}

Cancel reschedule link

In order to be more consistent throughout with the syntax used, we have changed the ...link to ...url
Before

{
  "object": "booking",
  // ...
  "cancel_reschedule_link": "https://go.oncehub.com/financefirm?Params=IPLF"
}

After

{
  "object": "booking",
  // ...
  "cancel_reschedule_url": "https://go.oncehub.com/financefirm?Params=IPLF"
}

Canceled booking tracking id

This field has been renamed and the tracking id has been replaced with the cancelled booking's booking object id that can now be used to retrieve the booking in question.
Before

{
  "object": "booking",
  // ...
  "canceled_booking_tracking_id": "D36E0002"
}

After

{
  "object": "booking",
  // ...
  "rescheduled_booking_id": "BKNG-J4FR05BKEWEX"
}

Cancel reschedule information

The cancel reschedule information has been changed from being added as separate fields to being added as a list of values. This should make it easier for the developer to make use of these values.
Also, the format used to define who actioned the cancel/reschedule was changed from returning the name of either the customer or the user to returning an actioned_by field that can contain either "user" or "customer" and if it was initiated by a user it will return the id of the user in the user_id field.
Before

{
  "object": "booking",
  // ...
  "cancel_reschedule_reason": null,
  "name_of_user_who_canceled_rescheduled": null,
  "name_of_customer_who_canceled_rescheduled": null
}

After

{
  "object": "booking",
  // ...
  "cancel_reschedule_information": {
    "reason": "I was double booked",
    "actioned_by": "user",
    "user_id": "USR-FSD423423"
  }
}