User-level requests
Last updated October 19, 2021 Cloud API
User privilege-level requests:
Request | Purpose |
---|---|
POST /myconferences | Create a conference |
GET /myconferences | List conferences |
PUT /myconferences/<conf_id> | Update a conference |
DELETE /myconferences/<conf_id> | Cancel a conference |
GET /myconferences/<conf_id> | Retrieve conference details |
PUT /myconferences/<conf_id>/occurrences/<occur_id> | Modify a single occurrence of an existing repeating conference |
DELETE /myconferences/<conf_id>/occurrences/<occur_id> | Cancel a single occurrence of a repeating conference |
GET /myconferences/<conf_id>/occurrences/<occur_id> | Retrieve details of a single occurrence of a repeating conference |
GET /myprofile | Retrieve details of a user’s profile |
PUT /myprofile | Update a user’s profile |
PATCH /myprofile | Selectively edit a user’s profile |
DELETE /myprofile | Delete a user’s profile |
POST /invite | Send a guest invite |
GET /features | Request a feature list |
GET /version | Request the version |
Conferences that have been created through the StarLeaf Portal cannot be managed through the API. Any attempt to do so will yield a 403 Forbidden response.
Managing conferences
Create a conference
To create a new conference, make an HTTPS POST request to:
/myconferences
The structure of the request is as follows:
{
"settings": <conf_settings object: required>,
"send_update_emails": <boolean: optional, default: true>,
}
Field |
Description |
---|---|
settings | Settings for the conference — refer to conf_settings request object . |
send_update_emails | If send_emails (above) is true, and the request is making a change to the conference that may be of interest to the participants, then the user has the option to send update emails to the participants. If send_update_emails is false, update emails will not be sent. |
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.
If the client has authenticated as an integration, the conference owner will be the integration rather than a real user.
List conferences
Use this request to:
- list the conferences owned by a user (if the client is authenticated as a real user)
- list the conferences created by the integration (if the client is authenticated as an integration)
To list conferences, make an HTTPS GET request to:
/myconferences
Used to obtain a list of unique identifiers (<conf_id>) owned by the user or integration. There is no request body. However, there is an optional query parameter 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 the unique identifiers for all conferences owned by the user. |
Update a conference
To update a conference, make an HTTPS PUT request to:
/myconferences/<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>,
"send_update_emails": <boolean: optional, default: true>,
}
Field |
Description |
---|---|
settings |
Settings for the conference — refer to conf_settings request object . |
send_update_emails | If send_emails (above) is true, and the request is making a change to the conference that may be of interest to the participants, then the user has the option to send update emails to the participants. If send_update_emails is false, update emails will not be sent. |
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
To cancel a conference, make an HTTPS DELETE request to:
/myconferences/<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
To find details about a specific conference, make an HTTPS GET request to:
/myconferences/<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>,
"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. |
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
To modify a single occurrence of an existing repeating conference, make an HTTPS PUT request to:
/v1/myconferences/<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
To cancel a single occurrence of an repeating conference, make an HTTPS DELETE request to:
/myconferences/<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
To retrieve details of a single occurrence of a repeating conference, make an HTTPS GET request to:
/myconferences/<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.
Managing a user’s profile
Retrieve details of a user’s profile
Use this request to list the details of a user’s profile.
To retrieve a user’s profile, make an HTTPS GET request to:
/myprofile
On success, this generates a 200 OK response with a body having the following structure:
{
'email': <string>,
'user_id': <string>,
'org_id': <string>,
'org_account_type': <string>,
'admin_status': <string>,
'calendar_delegate': <boolean>,
'firstname': <string>,
'lastname': <string>,
'timezone': <string or null>,
'locale': <string or null>,
'phone_home': <string or null>,
'phone_work': <string or null>,
'phone_mobile': <string or null>,
'conf_layout': <string or null>,
'externally_managed': <boolean>,
'integration_name': <string or null>,
'defaults': {
'locale': <string>,
'timezone': <string>,
'conf_layout': <string>,
},
}
The descriptions of these arguments are the same as in the user response object, except for the following:
Field |
Description |
---|---|
conf_layout |
The layout used for QuickMeet conferences and the default layout for scheduled conferences. If null, then the default layout set for the org is used. The valid values for the string are as per the layout argument in the conf_settings request object. |
externally_managed | Indicates whether or not this user is managed by an external integration. If it is, any attempt to modify firstname, lastname, phone_work or phone_mobile will return a 403 FORBIDDEN response. |
integration_name | The name of the external integration, if any, that is managing this user. |
defaults | The locale, timezone and conf_layout values in the defaults object provide the default values for the org. These are the values that will be used if the corresponding values for the user are set to null. |
Update a user’s profile
New in Cloud 5.4, API minor version 15.
To edit a user’s profile, make an HTTPS PUT request to:
/myprofile
The structure of the request is as follows:
{
'firstname': <string: required>,
'lastname': <string: required>,
'timezone': <string: optional, default: null>,
'locale': <string: optional, default: null>,
'phone_home': <string: optional, default: null>,
'phone_work': <string: optional, default: null>,
'phone_mobile': <string: optional, default: null>,
'conf_layout': <string: optional, default: null>
}
On success, this returns 204 NO CONTENT.
The descriptions of these arguments are the same as in the user request object, except for the following:
Field |
Description |
---|---|
conf_layout |
The layout used for QuickMeet conferences and the default layout for scheduled conferences. If null, then the default layout set for the org is used. The valid values for the string are as per the layout argument in the conf_settings request object. |
If this user is managed by an external integration, any attempt to modify firstname, lastname, phone_work or phone_mobile will return a 403 FORBIDDEN response.
Selectively edit a user’s profile
New in Cloud 5.4, API minor version 15.
Use this request to update a user’s profile where only particular settings need to be edited. Where values are not provided the existing settings will persist.
To selectively edit a user’s profile, make an HTTPS PATCH request to:
/myprofile
The structure of the request is as follows:
{
'firstname': <string: required>,
'lastname': <string: required>,
'timezone': <string: optional, default: null>,
'locale': <string: optional, default: null>,
'phone_home': <string: optional, default: null>,
'phone_work': <string: optional, default: null>,
'phone_mobile': <string: optional, default: null>,
'conf_layout': <string: optional, default: null>
}
On success, this returns 204 NO CONTENT.
The descriptions of these args are the same as in the user request object, except for the following:
Field |
Description |
---|---|
conf_layout |
The layout used for QuickMeet conferences and the default layout for scheduled conferences. If null, then the default layout set for the org is used. The valid values for the string are as per the layout argument in the conf_settings request object. |
If this user is managed by an external integration, any attempt to modify firstname, lastname, phone_work or phone_mobile will return a 403 FORBIDDEN response.
Delete a user’s profile
To delete a user’s profile, make an HTTPS DELETE request to:
/myprofile
Sending guest invites
This request is only available for clients that use the challenge and response authentication method.
To send a guest invite to someone so that they can sign up to StarLeaf and download a software video client, make an HTTPS POST request to:
/invite
The structure of the request is as follows:
{
"invitee": <string: required>
}
Field |
Description |
---|---|
invitee |
The email address of the person you would like to invite. |
On success, this generates a 200 OK response with a body having the following structure:
{
"status": invitee is callable
}
or
{
"status": invite sent if possible
}
Response status |
Description |
---|---|
invitee is callable |
If this guest is logged in to StarLeaf, this guest is callable. |
invite sent if possible |
If the email address was valid, the guest has received an invite. |
Requesting a feature list
This request will obtain a list of API features available on the server and enabled for the user’s or integration’s organization. Remember, that if the user has reseller privileges in the StarLeaf platform, this request will return features for the reseller organization.
To obtain a list of API features available on the server and enabled for the organization, make an HTTPS GET request to:
/features
There is no request body.
On success, this generates a 200 OK response with a body having the following structure:
{
"features": [
<string: optional>,
<string: optional>,
...]
}
Field |
Description |
---|---|
features |
The list of API features available on the server and enabled for the client. Some of the available features are defined in the table below (note that this is not a complete list). |
Feature |
Description |
---|---|
conferencing |
Ability to schedule conferences. |
conf_layouts |
Ability to select the layout of a scheduled conference. |
conf_recording |
Ability to record a conference. |
lync |
Ability to dial into a conference using Microsoft Skype-for-Business. |
guest_invites | Ability to send guest invites. |
webrtc | Ability for this organization to use Click-to-Call (browser-based calling). |
Requesting the version
To obtain the software version running on the server, make an HTTPS GET request to:
/version
There is no request body.
On success, this generates a 200 OK response with a body having the following structure:
{
"software_version": <string>,
"api_minor_version": <integer>
}
Field |
Description |
---|---|
software_version |
Cloud software version running on the server. |
api_minor_version |
API minor version running on the server. |