Organization admin requests:

Request Purpose
POST /users Create a user
GET /users Retrieve a list of users and their details
GET /users/<user_id> Retrieve a user’s details
PUT /users/<user_id> Update a user’s details
PATCH /users/<user_id> Selectively edit a user’s details
DELETE /users/<user_id> Delete a user
PUT /users/<user_id>/disable Disable/re-enable a user
POST /integrations Create an integration
GET /integrations Retrieve a list of integrations and their details
GET /integrations/<integration_id> Retrieve an integration’s details
PUT /integrations/<integration_id> Update an integration’s details
PATCH /integrations/<integration_id> Selectively edit an integration’s details
DELETE /integrations/<integration_id> Delete an integration
POST /conferences Create a conference for a user in the organization
GET /conferences List conferences
PUT  /conferences/<conf_id> Update a conference
DELETE /conferences/<conf_id> Cancel a conference
GET /conferences/<conf_id> Retrieve conference details
PUT /conferences/<conf_id>/occurrences/<occur_id> Modify a single occurrence of an existing repeating conference
DELETE /conferences/<conf_id>/occurrences/<occur_id> Cancel a single occurrence of a repeating conference
GET /conferences/<conf_id>/occurrences/<occur_id> Retrieve details of a single occurrence of a repeating conference

Managing users

Create a user

New in Cloud 4.6, API minor version 7.

To create a user, make an HTTPS POST request to:

/users

This creates a user in the organization.

The body of this request is the request object user. Refer to user request object.

On success this generates a 201 Created response with a Location header field containing the URI of the newly created user resource. The response body is the response object user. Refer to user response object.

Retrieve a list of users and their details

New in Cloud 4.6, API minor version 7.

To retrieve a list of users and their details, make an HTTPS GET request to:

/users

There is no request body. However, there are optional query parameters that you can use in the request to page the response:

  • count: The number of user records that you want returned. If not specified, all the records will be returned.
  • startIndex: When you make the request, the Cloud will skip the user records prior to the number that you specify for startIndex. Use startIndex to get the next set of user records. If not specified, startIndex defaults to 1.

For example, HTTPS GET /users?count=20&startIndex=41 will skip the first 40 users and return the next 20.

On success, this request generates a 200 OK response with a body having the following structure:

{ 
  "itemsPerPage": <integer>,
  "startIndex": <integer>,
  "totalResults": <integer>,
  "users": [
	<user response object>,
	<user response object>,
	...] 
} 	

Field

Description

itemsPerPage

The number of items, which will either be equal to totalResults or if you made the request with count specified, it will be equal to the number you specified.

startIndex

This will be the same as the requested startIndex. If not specified, it will be 1.

totalResults

The total number of user records for the organization.
users A list of user response objects. Refer to user response object.

Retrieve a user’s details

New in Cloud 4.6, API minor version 7.

To retrieve a user’s details, make an HTTPS GET request to:

/users/<user_id>

where <user_id> is the unique identifier user details returned when the user was created.

There is no request body.

On success, this generates a 200 OK response with a body which is the response object user. Refer to user response object.

Update a user’s details

New in Cloud 4.6, API minor version 7.

To edit a user, make an HTTPS PUT request to:

/users/<user_id>

where <user_id> is the unique identifier returned when the user was created.

This request is used to update an existing user. Values that are not provided by the request will be populated with the default settings for those values.

The body of this request is the request object user. Refer to user request object.

On success, this generates a 200 OK response with a body which is the response object user. Refer to user response object.

Selectively edit a user’s details

New in Cloud 4.6, API minor version 7.

To selectively edit a user, make an HTTPS PATCH request to:

/users/<user_id>

where <user_id> is the unique identifier returned when the user was created.

Use this request to update an existing user where only particular settings need to be edited. Where values are not provided the existing settings will persist.

The body of this request is the request object user. Refer to user request object. All fields are optional.

On success, this generates a 200 OK response with a body which is the response object user. Refer to user response object.

Delete a user

New in Cloud 4.6, API minor version 7.

To delete a user, make an HTTPS DELETE request to:

/users/<user_id>

where <user_id> is the unique identifier returned when the user was created.

There is no request body. However, there is an optional query parameter (new in Cloud 5.1, API minor version 12) that you can use in the request to specify whether or not the deleted user will also be removed as a participant from all conferences in the same organization. By default, the user will be removed from conferences:

  • keep_conf_participants=true: do not remove the user from conferences

On success, this generates a 204 No Content response.

Disable/re-enable a user

New in Cloud 5.2, API minor version 12.

Disabling a user allows you to effectively ‘deactivate’ the user without having to delete that user. To disable or re-enable a user, make an HTTPS PUT request to:

/users/<user_id>/disable

where <user_id> is the unique identifier returned when the user was created.

The structure of the request is as follows:

{
   "enabled": <boolean: required>,
   "keep_conf_participants": <boolean: optional, default: false>
}

Field

Description

enabled Set to true to enable the user. Set to false to disable the user.
keep_conf_participants When a user is being disabled, this field determines whether or not the user will be removed as a participant from all conferences in the same organization. Defaults to false (user will be removed from conferences). This field is ignored when the user is being enabled.

On success, this generates a 200 OK response with a body which is the response object user refer to user response object.

To see whether a user is enabled or not, retrieve a user’s details and look at the user response object.

Managing integrations

Create an integration

New in Cloud 4.6, API minor version 7.

An integration can be used to access the API, for example, to create conferences in an organization.

To create an integration in an organization, make an HTTPS POST request to:

/integrations

This creates an integration.

The body of this request is the request object create_integration. Refer to create_integration request object.

On success, this generates a 201 Created response with a body which is the response object integration. Refer to integration response object.

Retrieve a list of integrations and their details

New in Cloud 4.6, API minor version 7.

To retrieve a list of integrations and their details, make an HTTPS GET request to:

/integrations

There is no request body.

On success, this request generates a 200 OK response with a body having the following structure:

[
  <integration response object>,
  <integration response object>,
...]  	

This is a list of integration response objects. Refer to integration response object.

Retrieve an integration’s details

New in Cloud 4.6, API minor version 7.

To retrieve details of an integration, make an HTTP GET request to:

/integrations/<integration_id>

There is no request body.

On success, this generates a 200 OK response with a body which is the response object integration. Refer to integration response object.

Update an integration’s details

New in Cloud 4.6, API minor version 7.

To update an integration, make an HTTPS PUT request to:

/integrations/<integration_id>

where <integration_id> is the unique identifier for the integration returned when the integration was created. Used to update an existing integration. Values that are not provided by the request will be populated with the default settings for those values.

The body of this request is the request object update_integration. Refer to update_integration request object.

On success, this generates a 200 OK response with a body which is the response object integration. Refer to integration response object.

Selectively edit an integration’s details

New in Cloud 4.6, API minor version 7.

To selectively edit an integration, make an HTTPS PATCH request to:

/integrations/<integration_id>

where <integration_id> is the unique identifier for the integration returned when the integration was created.

Use this request to update an existing integration where only particular settings need to be edited. Where values are not provided the existing settings will persist.

The body of this request is the request object update_integration. Refer to update_integration request object. All fields are optional.

On success, this generates a 200 OK response with a body which is the response object integration. Refer to integration response object.

Delete an integration

New in Cloud 4.6, API minor version 7.

To delete an integration, make an HTTPS DELETE request to:

/integrations/<integration_id>

where <integration_id> is the unique identifier returned when the integration was created.

There is no request body.

On success, this generates a 204 No Content response.

Managing conferences

Create a conference for a user in the organization

New in Cloud 5.1, API minor version 11.

To create a new conference for a user in the organization, make an HTTPS POST request to:

/conferences

The structure of the request is as follows:

{ 
  "settings": <conf_settings object: required>, 
  "owner_id": <string: required>				
} 	

Field

Description

settings Settings for the conference — refer to conf_settings request object .
owner_id The user_id of the user that will be the conference owner.

On success, this generates a 201 Created response with a Location header field containing the URI of the newly created conference resource. The response also includes a body having the following structure:

{ 
  "conf_id": <string>, 
  "dial_info": <conf_dial_info object> 
} 	

Field

Description

conf_id

The unique identifier for the newly created conference.

dial_info

The information required to dial into the conference — refer to conf_dial_info response object.

If the request would result in the maximum number of conferences per user or per organization being exceeded, the server generates a 507 Maximum Resource Count Exceeded response.

List conferences

New in Cloud 5.1, API minor version 11.

Use this request to list all conferences in this organization.

To list conferences, make an HTTPS GET request to:

/conferences

Used to obtain a list of unique conference identifiers (<conf_id>) in this organization. There is no request body. However, there is an optional query parameters that you can use in the request to limit the response to externally managed conferences:

  • thisappmanaged=true: only the conferences having externally_managed set to true are returned

On success, this generates a 200 OK response with a body having the following structure:

{
    "conf_ids": [
	<string: optional>,
	<string: optional>,
	...] 
}

Field

Description

conf_ids

A list of unique identifiers for conferences in the organization.

Update a conference

New in Cloud 5.1, API minor version 11.

To update a conference, make an HTTPS PUT request to:

/conferences/<conf_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created.

Used to update an existing conference. This request can also be used to create a new conference with a <conf_id> specified by the client, in which case <conf_id> must not end in ‘@starleaf.com’.

The structure of the request is as follows:

{ 
   "settings": <conf_settings object: required>, 
   "owner_id": <string: required>				
   } 	

Field

Description

settings

Settings for the conference — refer to conf_settings request object .

owner_id The user_id of the user that is the conference owner. You cannot change the owner of the conference and attempting to do so will result in a 400 Bad Request error

On success, updating an existing conference generates a 204 No Content response. Creating a new conference (with <conf_id> specified by the client) generates a 201 Created response with a Location header field containing the URI of the newly created conference resource and a body having the following structure:

{ 
  "dial_info": <conf_dial_info object> 
}	

Field

Description

dial_info

The information required to dial into the conference — refer to conf_dial_info response object.

Cancel a conference

New in Cloud 5.1, API minor version 11.

To cancel a conference, make an HTTPS DELETE request to:

/conferences/<conf_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created. There is no request body.

On success, this generates a 204 No Content response.

Retrieve conference details

New in Cloud 5.1, API minor version 11.

To find details about a specific conference, make an HTTPS GET request to:

/conferences/<conf_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created. There is no request body.

On success, this generates a 200 OK response with a body having the following structure:

{ 
  "settings": <conf_settings object>,
  "dial_info": <conf_dial_info object>,
  "owner_id": <string>,
  "occur_mod": [
	<string: optional>,
	<string: optional>,
	...] 
} 	

Field

Description

settings

Settings for the conference — refer to conf_settings response object .

dial_info

The information required to dial into the conference — refer to conf_dial_info response object.

owner_id The user_id of the owner of the conference.

occur_mod

For a repeating conference, this is a list of occurrence identifiers [<occur_id>, …] that have been modified relative to the parent conference, if any. For non-repeating conferences, this is an empty list. Each <occur_id> is the UTC start date and time of the occurrence as specified by the original parent repetition pattern, given in ISO 8601 format (including the ‘Z’ suffix to indicate UTC).

Modify a single occurrence of an existing repeating conference

New in Cloud 5.1, API minor version 11.

To modify a single occurrence of an existing repeating conference, make an HTTPS PUT request to:

/conferences/<conf_id>/occurrences/<occur_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created and <occur_id> is the occurrence identifier, which is the UTC start date and time of the occurrence as specified by the original parent repetition pattern, given in ISO 8601 format (including the ‘Z’ suffix to indicate UTC).

The structure of the request is as follows:

{ 
  "settings": <occur_settings object: required> 
}

Field

Description

settings

Settings for the occurrence — refer to occur_settings request object .

On success, this generates a 204 No Content response.

Cancel a single occurrence of a repeating conference

New in Cloud 5.1, API minor version 11.

To cancel a single occurrence of a repeating conference, make an HTTPS DELETE request to:

/conferences/<conf_id>/occurrences/<occur_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created and <occur_id> is the occurrence identifier, which is the UTC start date and time of the occurrence as specified by the original parent repetition pattern, given in ISO 8601 format (including the ‘Z’ suffix to indicate UTC). There is no request body.

On success, this generates a 204 No Content response.

Retrieve details of a single occurrence of a repeating conference

New in Cloud 5.1, API minor version 11.

To retrieve details of a single occurrence of a repeating conference, make an HTTPS GET request to:

/conferences/<conf_id>/occurrences/<occur_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created and <occur_id> is the occurrence identifier, which is the UTC start date and time of the occurrence as specified by the original parent repetition pattern, given in ISO 8601 format (including the ‘Z’ suffix to indicate UTC). There is no request body.

On success, this generates a 200 OK response with a body having the following structure:

{ 
  "settings": <occur_settings object>,
  "canceled": <boolean>
}

Field

Description

settings

Settings for the occurrence — refer to occur_settings response object.

canceled Boolean specifying whether or not this occurrence is canceled. This key is new in Cloud 5.3, API minor version 14.

Note that the dialing information for the occurrence is not returned by this request as it is identical to that of the parent conference.