API Documentation

General

Endpoints

Appendix

Collaborators

Note: All operations described on this page can only be performed by the owner of the schedule identified by the specified schedule identifier. There is one exception: If you are a collaborator you can delete your own collaborator object. This will terminate your collaboration.

Collaborator Object

Property Type Description Writable
id integer Unique identifier for this collaborator. No
schedule_id string Schedule identifier. No
email string Email address of this collaborator. Required when creating a collaborator. No
user_role string This value defines the access rights for this collaborator. Possible values are editor and viewer. Default is viewer. Yes
invite boolean true if an invitation email should be sent to this collaborator; false otherwise. Default is false. This property is only available when creating a collaborator. No
user object More information about this collaborator. This property is only available if the collaborator is a registered Oberplan user. No
user.email string Email of this collaborator. No
user.firstname string First name of this collaborator. No
user.lastname string Last name of this collaborator. No
updated_at string The date and time when this collaborator was last updated, in UTC and ISO 8601 format. No
created_at string The date and time when this collaborator was created, in UTC and ISO 8601 format. No

Get Collaborators

GET /schedules/scheduleId/collaborators

Returns all collaborators of a schedule.

Parameters

Name Description
scheduleId Schedule 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 collaborator identifiers. Only the associated collaborators will be returned.

Example

The following request returns for all collaborators the id, email, user role and, if the collaborator is a registered Oberplan user, the name:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/collaborators?fields=email,user,user_role \
-X GET \
-u user@oberplan.com:mypassword

Sample Response:

{
   "data": [
      {
         "email": "Sarah.Beck@example.com",
         "id": 522,
         "user_role": "viewer"
      },
      {
         "email": "Mike.Miller@example.com",
         "id": 523,
         "user_role": "editor"
      },
      {
         "email": "marcus.beck@oberplan.com",
         "id": 524,
         "user": {
            "email": "marcus.beck@oberplan.com",
            "firstname": "Marcus",
            "lastname": "Beck"
         },
         "user_role": "editor"
      }
   ],
   "pagination": {
      "limit": 20,
      "links": {
         "first": "https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/collaborators?fields=email%2Cuser%2Cuser_role&offset=0&limit=20",
         "last": "https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/collaborators?fields=email%2Cuser%2Cuser_role&offset=0&limit=20"
      },
      "offset": 0,
      "page_count": 3,
      "total_count": 3
   },
   "success": true
}

Get a Collaborator

GET /schedules/scheduleId/collaborators/collaboratorId

Returns a specific collaborator.

Parameters

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

Example

The following request returns a specpfic collaborator:

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

Sample Response:

{
   "data": {
      "created_at": "2018-09-05T16:33:52Z",
      "email": "marcus.beck@oberplan.com",
      "id": 524,
      "schedule_id": "akg5mf6beccwf9ce",
      "updated_at": "2018-09-05T16:33:52Z",
      "user": {
         "email": "marcus.beck@oberplan.com",
         "firstname": "Marcus",
         "lastname": "Beck"
      },
      "user_role": "editor"
   },
   "success": true
}

Create a Collaborator

POST /schedules/scheduleId/collaborators

Creates a new collaborator.

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

Parameters

Name Description
scheduleId Schedule identifier.

Example

The following request creates a new collaborator:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/collaborators \
-X POST \
-u user@oberplan.com:mypassword \
-d \
'
{
   "email": "william.hunt@example.com",
   "user_role": "editor"
}
'

Sample Response:

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

Update Collaborators

PUT /schedules/scheduleId/collaborators

Updates all collaborators of a schedule.

You can only change the user role. This means that the request body must contain only the new user role.

Parameters

Name Description
scheduleId Schedule identifier.
Optional Query Parameters
ids Comma delimited list of collaborator identifiers. Only the associated collaborators will be updated.

Example

The following request sets the user role for all collaborators:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/collaborators \
-X PUT \
-u user@oberplan.com:mypassword \
-d \
'
{
   "user_role": "viewer"
}
'

Response:

{
   "success": true
}

Update a Collaborator

PUT /schedules/scheduleId/collaborators/collaboratorId

Updates a specific collaborator.

You can only change the user role.

The request body may contain all object properties or only the user role.

Parameters

Name Description
scheduleId Schedule identifier.
collaboratorId Collaborator identifier.

Example

The following request changes the user role for a specific collaborator:

curl https://api.oberplan.com/v1/schedules/akg5mf6beccwf9ce/collaborators/533 \
-X PUT \
-u user@oberplan.com:mypassword \
-d \
'
{
   "user_role": "editor"
}
'

Response:

{
   "success": true
}

Delete Collaborators

DELETE /schedules/scheduleId/collaborators

Deletes all collaborators of a schedule.

You must use either the all (set to 1) or the ids query parameter to delete collaborators.

Parameters

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

Example

The following request deletes all collaborators:

curl https://api.oberplan.com/v1/schedules/oydpudpjnirmlbg1/collaborators?all=1 \
-X DELETE \
-u user@oberplan.com:mypassword

Response:

{
   "success": true
}

Delete a Collaborator

DELETE /schedules/scheduleId/collaborators/collaboratorId

Deletes a specific collaborator.

Note: If you are a collaborator, you can delete your own collaborator object to terminate your collaboration. You can get your collaborator identifier from the schedule object.

Parameters

Name Description
scheduleId Schedule identifier.
collaboratorId Collaborator identifier.

Example

The following request deletes a specific collaborator:

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

Response:

{
   "success": true
}