User-level requests

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
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>, 
}

Field	Description
settings	Settings for the conference — refer to conf_settings request object .

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> 
}

Field	Description
settings	Settings for the conference — refer to conf_settings request object .

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>

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>

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

New in Cloud 5.4, API minor version 15.

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>,
'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.

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 the StarLeaf Cloud service 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
}

{ 
   "status": invite sent if possible
}

Response status	Description
invitee is callable	If this guest is logged in to Breeze, 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 Cloud 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.

Integrating Cloud API

Managing conferences

Create a conference

List conferences

Update a conference

Cancel a conference

Retrieve conference details

Modify a single occurrence of an existing repeating conference

Cancel a single occurrence of a repeating conference

Retrieve details of a single occurrence of a repeating conference

Managing a user’s profile

Retrieve details of a user’s profile

Update a user’s profile

Selectively edit a user’s profile

Sending guest invites

Requesting a feature list

Requesting the version