API Documentation

General

Endpoints

Appendix

Bookings

Booking Object

Property Type Description Writable
id integer The identifier for this booking. The identifier is unique across all bookings of the schedule. No
schedule_id string Schedule identifier. No
resource_id integer Resource identifier. Required when creating a booking. Yes
title string Booking title. Can be empty. The maximum length is 100 characters. Yes
start string The booking start date and time in ISO 8601 format. If the time zone is omitted, the user's time zone is used. Required when creating a booking. Yes
end string The booking end date and time in ISO 8601 format. If the time zone is omitted, the user's time zone is used. Required when creating a booking. Yes
all_day_display boolean true if the booking period should be displayed without time of day, i.e. only the dates are displayed. This option only applies if the time of day (in the user's time zone) for both start and end is 0:00 (12:00 a.m.). Default is false. Yes
color_fg string Booking title color in HTML hex format #RRGGBB. Default is #000000 (black). Yes
color_bk string Booking bar background color in HTML hex format #RRGGBB. Default is #FFFFFF (white). Yes
text_bold boolean true if a bold font is used for the booking title; false otherwise. Default is false. Yes
link string Web link associated with this booking. The URL scheme must be HTTP or HTTPS. The maximum length is 250 characters. For dynamic variables, see here. Yes
link_title string Title for the booking web link. The maximum length is 100 characters. Yes
note string A multi-line note for this booking. The maximum length is 500 characters. Yes
custom_1 string Value of the first custom field. The maximum length is 200 characters. Yes
custom_2 string Value of the second custom field. The maximum length is 200 characters. Yes
start_utc string The booking start date and time, in UTC and ISO 8601 format. No
end_utc string The booking end date and time, in UTC and ISO 8601 format. No
updated_at string The date and time when this booking was last updated, in UTC and ISO 8601 format. No
created_at string The date and time when this booking was created, in UTC and ISO 8601 format. No

Get Bookings

GET /schedules/scheduleId/bookings

Returns all bookings of a schedule.

GET /schedules/scheduleId/resources/resourceId/bookings

Returns all bookings of a specific resource.

Parameters

Name Description
scheduleId Schedule identifier.
resourceId Resource identifier.
Optional Query Parameters
limit Number of objects to return. To return all objects, use 0. Default is 20.
offset The offset of the first record returned. Default is 0.
fields Comma delimited list of properties to be returned.
ids Comma delimited list of booking identifiers. Only the associated booking will be returned.
time_min When set, only bookings that start at this time or later will be returned. Must be in ISO 8601 format. If the time zone is omitted, the user's time zone is used.
time_max When set, only bookings that end before this time will be returned. Must be in ISO 8601 format. If the time zone is omitted, the user's time zone is used.

Example

The following request returns the id, title and resource identifier of all bookings of a schedule:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/bookings?fields=id,title,resource_id \
-X GET \
-u user@oberplan.com:mypassword

Sample Response (shortened for readability):

{
   "data": [
      {
         "id": 84171,
         "resource_id": 7339,
         "title": "Alexander Allen"
      },
      {
         "id": 84172,
         "resource_id": 7339,
         "title": "Ashley Harris"
      },
      {
         "id": 84173,
         "resource_id": 7329,
         "title": "Marc Johnson"
      },
      ...
      {
         "id": 84188,
         "resource_id": 7332,
         "title": "Christopher Martinez"
      },
      {
         "id": 84189,
         "resource_id": 7337,
         "title": "Lauren Young"
      },
      {
         "id": 84190,
         "resource_id": 7337,
         "title": "Daniel Thomas"
      }
   ],
   "pagination": {
      "limit": 20,
      "links": {
         "first": "https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/bookings?fields=id%2Ctitle%2Cresource_id&offset=0&limit=20",
         "last": "https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/bookings?fields=id%2Ctitle%2Cresource_id&offset=20&limit=20",
         "next": "https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/bookings?fields=id%2Ctitle%2Cresource_id&offset=20&limit=20"
      },
      "offset": 0,
      "page_count": 20,
      "total_count": 28
   },
   "success": true
}

Get a Booking

GET /schedules/scheduleId/bookings/bookingId

Returns a specific booking.

Parameters

Name Description
scheduleId Schedule identifier.
bookingId Booking identifier.
Optional Query Parameters
fields Comma delimited list of properties to be returned.

Example

The following request returns a specific booking:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/bookings/84172 \
-X GET \
-u user@oberplan.com:mypassword

Sample Response:

{
   "data": {
      "all_day_display": false,
      "color_bk": "#FFFF80",
      "color_fg": "#000000",
      "created_at": "2018-06-29T14:56:03Z",
      "custom_1": "",
      "custom_2": "",
      "end": "2018-10-02 09:00",
      "end_utc": "2018-10-02T13:00:00Z",
      "id": 84172,
      "link": "https://oberplan.com/events",
      "link_title": "Instructions for arrival",
      "note": "Closing date: one week before the event.",
      "resource_id": 7339,
      "schedule_id": "akg5mf6beccwf9ce",
      "start": "2018-10-02 03:00",
      "start_utc": "2018-10-02T07:00:00Z",
      "text_bold": false,
      "title": "Ashley Harris",
      "updated_at": "2018-08-24T16:55:40Z"
   },
   "success": true
}

Create a Booking

POST /schedules/scheduleId/bookings

Creates a new booking.

If successful, the server returns the identifier of the new booking.

Parameters

Name Description
scheduleId Schedule identifier.

Example

The following request creates a new booking based on times in your time zone:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/bookings \
-X POST \
-u user@oberplan.com:mypassword \
-d \
'
{
   "title": "Jessica Lewis",
   "resource_id": 7336,
   "start": "2018-10-01 13:00",
   "end": "2018-10-01 16:00",
   "color_bk": "#800000",
   "color_fg": "#FFFFFF"
}
'

Sample Response:

{
   "data": [
      {
         "id": 84246
      }
   ],
   "success": true
}

Update Bookings

PUT /schedules/scheduleId/bookings

Updates all bookings of a schedule.

PUT /schedules/scheduleId/resources/resourceId/bookings

Updates all bookings of a specific resource.

In both cases the request body must contain only those properties that you want to edit.

Parameters

Name Description
scheduleId Schedule identifier.
resourceId Resource identifier.
Optional Query Parameters
ids Comma delimited list of booking identifiers. Only the associated bookings will be updated.

Example

The following request moves all bookings of the resource with id 7342 to the resource with id 7357:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/resources/7342/bookings \
-X PUT \
-u user@oberplan.com:mypassword \
-d \
'
{
   "resource_id": 7357
}
'

Response:

{
   "success": true
}

Update a Booking

PUT /schedules/scheduleId/bookings/bookingId

Updates a specific booking.

The request body may contain all object properties or only those properties that you want to edit.

Parameters

Name Description
scheduleId Schedule identifier.
bookingId Booking identifier.

Example

The following request changes the title and the end time of a specific booking:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/bookings/84246 \
-X PUT \
-u user@oberplan.com:mypassword \
-d \
'
{
   "title": "Samantha Hall",
   "end": "2018-10-01 17:30"
}
'

Response:

{
   "success": true
}

Delete Bookings

DELETE /schedules/scheduleId/bookings

Deletes all bookings of a schedule.

DELETE /schedules/scheduleId/resources/resourceId/bookings

Deletes all bookings of a specific resource.

In both cases you must use either the all (set to 1) or the ids query parameter to delete bookings.

Parameters

Name Description
scheduleId Schedule identifier.
resourceId Resource identifier.
Query Parameters
all When set to 1, all bookings will be deleted. Default is 0.
ids Comma delimited list of booking identifiers. Only the associated bookings will be deleted.

Example

The following request deletes the bookings with id 84246 and 84248:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/bookings?ids=84246,84248 \
-X DELETE \
-u user@oberplan.com:mypassword

Response:

{
   "success": true
}

Delete a Booking

DELETE /schedules/scheduleId/bookings/bookingId

Deletes a specific booking.

Parameters

Name Description
scheduleId Schedule identifier.
bookingId Booking identifier.

Example

The following request deletes a specific booking:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/bookings/84249 \
-X DELETE \
-u user@oberplan.com:mypassword

Response:

{
   "success": true
}