API Documentation

General

Endpoints

Appendix

Schedules

Schedule Object

Property Type Description Writable
id string Unique identifier for this schedule. No
name string Schedule name. Required when creating a schedule. Must be unique across all of your own schedules. The maximum length is 200 characters. Yes
working_days array[string] Working days for this schedule. Must be at least one of: monday, tuesday, wednesday, thursday, friday, saturday, sunday. Default is monday to friday. Yes
working_day_start string Start time of a working day based on a 24 hour clock. Default is 0:00. Yes
working_day_end string End time of a working day based on a 24 hour clock. Use 0:00 for the end of day. Default is 0:00. Yes
week_numbering_system string Week numbering system used for this schedule. Must be one of: iso8601, american, arabic, mixed (explanation). Default is iso8601. Yes
link string Web link associated with this schedule. 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 schedule web link. The maximum length is 100 characters. Yes
note string A multi-line note for this schedule. The maximum length is 500 characters. Yes
resource_link string General web link for resources. The URL scheme must be HTTP or HTTPS. The maximum length is 250 characters. The maximum length is 250 characters. For dynamic variables, see here. Yes
resource_link_title string Title for the resource web link. The maximum length is 100 characters. Yes
booking_link string General web link for bookings. The URL scheme must be HTTP or HTTPS. The maximum length is 250 characters. For dynamic variables, see here. Yes
booking_link_title string Title for the booking web link. The maximum length is 100 characters. Yes
resource_custom_1_name string Name of the first custom field for resources. The maximum length is 100 characters. Yes
resource_custom_2_name string Name of the second custom field for resources. The maximum length is 100 characters. Yes
booking_custom_1_name string Name of the first custom field for bookings. The maximum length is 100 characters. Yes
booking_custom_2_name string Name of the second custom field for bookings. The maximum length is 100 characters. Yes
owner object Owner of this schedule. No
owner.email string Email of the owner of this schedule. No
owner.firstname string First name of the owner of this schedule. No
owner.lastname string Last name of the owner of this schedule. No
collaborator_id integer Your collaborator identifier. This property is only avalaible if you are not the owner of this schedule. No
user_role string The user role defines what you are allowed to do on this schedule. Possible values: owner, editor and viewer. No
resources_limit integer Maximum number of resources for this schedule. No
bookings_limit integer Maximum number of bookings for this schedule. No
holidays_limit integer Maximum number of holidays for this schedule. No
collaborators_limit integer Maximum number of collaborators for this schedule. No
data_updated_at string The date and time when this schedule (including data like bookings) was last updated, in UTC and ISO 8601 format. No
updated_at string The date and time when this schedule object was last updated, in UTC and ISO 8601 format. No
created_at string The date and time when this schedule was created, in UTC and ISO 8601 format. No

Get Schedules

GET /schedules

Returns all schedules that you can access, i.e. the schedules you created and the schedules that you collaborate with.

Parameters

Name Description
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.
owner When set to 1, only your own schedules are returned. Default is 0.

Example

The following request returns the id, name, owner and your role of all schedules that you can access:

curl https://api.oberplan.com/v1/schedules?fields=id,name,owner,user_role \
-X GET \
-u user@oberplan.com:mypassword

Sample Response:

{
   "data": [
      {
         "id": "m92nfq5b167oguzs",
         "name": "Team Schedule",
         "owner": {
            "email": "team@example.com",
            "firstname": "Marc",
            "lastname": "Johnson"
         },
         "user_role": "editor"
      },
      {
         "id": "9gjzfb6smcit7m7j",
         "name": "Employee Absence Schedule",
         "owner": {
            "email": "user@oberplan.com",
            "firstname": "John",
            "lastname": "Smith"
         },
         "user_role": "owner"
      },
      {
         "id": "akg5mf6beccwf9ce",
         "name": "Room Reservation Schedule",
         "owner": {
            "email": "user@oberplan.com",
            "firstname": "John",
            "lastname": "Smith"
         },
         "user_role": "owner"
      },
      {
         "id": "qb5b4fz928rndnou",
         "name": "Production Schedule",
         "owner": {
            "email": "user@oberplan.com",
            "firstname": "John",
            "lastname": "Smith"
         },
         "user_role": "owner"
      }
   ],
   "pagination": {
      "limit": 20,
      "links": {
         "first": "https://api.oberplan.com/v1/schedules?fields=id%2Cname%2Cowner%2Cuser_role&offset=0&limit=20",
         "last": "https://api.oberplan.com/v1/schedules?fields=id%2Cname%2Cowner%2Cuser_role&offset=0&limit=20"
      },
      "offset": 0,
      "page_count": 4,
      "total_count": 4
   },
   "success": true
}

Get a Schedule

GET /schedules/scheduleId

Returns a specific schedule.

Parameters

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

Example

The following request returns a specific schedule:

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

Sample Response:

{
   "data": {
      "booking_custom_1_name": "Contact phone number",
      "booking_custom_2_name": "",
      "booking_link": "",
      "booking_link_title": "",
      "bookings_limit": 10000,
      "collaborators_limit": 100,
      "created_at": "2018-06-29T13:55:57Z",
      "data_updated_at": "2018-09-27T15:24:34Z",
      "holidays_limit": 1000,
      "id": "akg5mf6beccwf9ce",
      "link": "https://example.com/room-schedule",
      "link_title": "Schedule Documentation",
      "name": "Room Reservation Schedule",
      "note": "",
      "owner": {
         "email": "user@oberplan.com",
         "firstname": "John",
         "lastname": "Smith"
      },
      "resource_custom_1_name": "Equipment",
      "resource_custom_2_name": "",
      "resource_link": "",
      "resource_link_title": "",
      "resources_limit": 500,
      "updated_at": "2018-09-27T15:24:34Z",
      "user_role": "owner",
      "week_numbering_system": "american",
      "working_day_end": "20:00",
      "working_day_start": "08:00",
      "working_days": [
         "monday",
         "tuesday",
         "wednesday",
         "thursday",
         "friday",
         "saturday"
      ]
   },
   "success": true
}

Create a Schedule

POST /schedules

Creates a new schedule.

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

Example

The following request creates a new schedule:

curl https://api.oberplan.com/v1/schedules \
-X POST \
-u user@oberplan.com:mypassword \
-d \
'
{
   "name": "Work Schedule",
   "note": "Department Manager: William Moore",
   "working_day_start": "06:00",
   "working_day_end": "20:00"
}
'

Sample Response:

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

Update a Schedule

PUT /schedules/scheduleId

Updates a specific schedule.

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

Parameters

Name Description
scheduleId Schedule identifier.

Example

The following request changes some properties of a specific schedule:

curl https://api.oberplan.com/v1/schedules/rgv05s5unv3m601i \
-X PUT \
-u user@oberplan.com:mypassword \
-d \
'
{
   "name": "Work Schedule 2020",
   "working_days": [
      "monday",
      "tuesday",
      "wednesday",
      "thursday",
      "friday"
   ]
}
'

Response:

{
   "success": true
}

Transfer Schedule Ownership

PUT /schedules/scheduleId

Transfers the ownership of a schedule to a collaborator.

The request body must contain a JSON object with the key transfer_to, whose value specifies the identifier of the collaborator who should be the new owner.

Parameters

Name Description
scheduleId Schedule identifier.

Notes:

  • You can only perform this operation if you are the owner of the schedule.
  • The new owner must be a registered Oberplan user.

Example

The following request transfers the ownership of a schedule to a specific collaborator:

curl https://api.oberplan.com/v1/schedules/rgv05s5unv3m601i \
-X PUT \
-u user@oberplan.com:mypassword \
-d \
'
{
   "transfer_to": 528
}
'

Response:

{
   "success": true
}

Delete a Schedule

DELETE /schedules/scheduleId

Deletes a specific schedule.

Parameters

Name Description
scheduleId Schedule identifier.

Example

The following request deletes a specific schedule:

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

Response:

{
   "success": true
}