Org admin-level requests
Cloud API
Last updated January 8, 2020Organization admin requests:
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 directory entries
Create a directory entry
To create a directory entry, make an HTTPS POST request to:
/directory_entries
This creates a directory entry in the organization.
The body of this request is the request object directory_entries . Refer to directory_entries request object.
On success this generates a 201 Created response with a Location header field containing the URI of the newly created directory entry resource. The response body is the response object directory_entries. Refer to directory_entries response object.
Retrieve a list of directory entries and their details
To retrieve a list of directory entries and their details, make an HTTPS GET request to:
/directory_entries
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 /directory_entries?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": [
<directory_entries response object>,
<directory_entries response object>,
...]
} If the count requested is > 1000, it will return a 400 Cannot request more than 1000 directory entries error. If a count isn’t specified and the response would otherwise be > 1000, it will return the same error.
If the start index is larger than the number of directory entries in the organization, it will return an empty list.
|
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 directory entry records for the organization. |
| directory entries | A list of directory_entries response objects. Refer to directory_entries response object. |
Retrieve a directory entry’s details
To retrieve a directory entry’s details, make an HTTPS GET request to:
/directory_entries/<uid>
where <uid> is the unique identifier user details returned when the directory entry 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 directory_entries response object.
Update a directory entry’s details
To edit a directory entry, make an HTTPS PUT request to:
/directory_entries/<uid>
where <uid> is the unique identifier returned when the directory entry was created.
This request is used to update an existing directory entry. 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 directory_entries. Refer to directory_entries request object.
On success, this generates a 200 OK response with a body which is the response object directory_entries. Refer to directory_entries response object.
Selectively edit a directory entry’s details
To selectively edit a directory entry, make an HTTPS PATCH request to:
/directory_entries/<uid>
where <uid> is the unique identifier returned when the directory entry was created.
Use this request to update an existing directory entry 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 directory_entries. Refer to directory_entries request object. All fields are optional.
On success, this generates a 200 OK response with a body which is the response object directory_entries. Refer to directory_entries response object.
Delete a directory entry
To delete a directory entry, make an HTTPS DELETE request to:
/directory_entries/<uid>
where <uid> is the unique identifier returned when the directory entry was created.
There is no request body.
On success, this generates a 204 No Content response.
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.