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>

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

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
}

or

{ 
   "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.