Managing customers

To use the requests for managing customers, the user that you use for authentication must be a reseller user in the StarLeaf Cloud.

Requests for managing customers:

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

The <org_uid> variable refers to the Organization reference number on the StarLeaf Portal.

Create an organization

To create a new organization, make an HTTPS POST request to:

/customers

The structure of the request is as follows:

{
    "org_name": <string: required>, 
    "subdomain": <string: required>,
    "email_domains": [
          <string: optional>,
          <string: optional>,     
           ...],
    "location": <location object: required>
}

Field

Description

org_name

The name of the organization.

subdomain

The subdomain of the new organization. This is used by the Cloud to create video addresses (URIs) for dialing into the organization (e.g. example.call.sl).

email_domains

A list of email domains to associate with the new organization. These are any corporate domains that this organization owns and uses for the sending and receiving of emails. For example, anybody receiving a guest invite whom appears (by their email address) to be part of this organization can be added as a user to this organization.

location Settings for the location. Refer to location request object.

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

{
     "org_uid": <string>
 }

where org_uid is the organization reference number, which is a unique identifier for this organization. You need this org_uid to create users in this organization.

Retrieve a list of organizations and their details

New in Cloud 4.6, API minor version 7.

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

/customers

There is no request body.

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

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

This is a list of org response objects. Refer to Response objects .

Retrieve the details of an organization

New in Cloud 4.6, API minor version 7.

To retrieve details of an organization, make an HTTPS GET request to:

/customers/<org_uid>

where <org_uid> is the unique identifier of the organization whose details you require.

There is no request body.

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

Delete an organization

New in Cloud 4.6, API minor version 9.

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

/customers/<org_uid>

where <org_uid> is the unique identifier of the organization that you want to delete.

There is no request body.

On success, this generates a 204 No Content response.

Create an integration in an organization

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:

/customers/<org_uid>/integrations

This creates an integration in the organization matched by org_uid.

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:

/customers/<org_uid>/integrations

where <org_uid> is the unique identifier of the organization whose integrations you are managing.

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:

/customers/<org_uid> /integrations/<integration_id>

where <integration_id> is the unique identifier for the integration returned when the integration was created and <org_uid> is the unique identifier of the organization whose integrations you are managing.

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:

/customers/<org_uid>/integrations/<integration_id>

where <integration_id> is the unique identifier for the integration returned when the integration was created and <org_uid> is the unique identifier of the organization whose integration you are managing. 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:

/customers/<org_uid>/integrations/<integration_id>

where <integration_id> is the unique identifier for the integration returned when the integration was created and <org_uid> is the unique identifier of the organization whose integration you are managing.

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:

/customers/<org_uid>/integrations/<integration_id>

where <integration_id> is the unique identifier returned when the integration was created and <org_uid> is the unique identifier of the organization whose integrations you are managing.

There is no request body.

On success, this generates a 204 No Content response.

Create a user

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

/customers/<org_uid>/users

This creates the user in the organization matched by org_uid.

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:

/customers/<org_uid>/users

where <org_uid> is the unique identifier of the organization for which you want users’ details.

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, (for an example organization with org_uid 99892630):
HTTPS GET customers/99892630/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 an individual user’s details, make an HTTPS GET request to:

    /customers/<org_uid>/users/<user_id>

    where <org_uid> is the unique identifier of the organization and <user_id> is the unique identifier for the user whose details you require.

    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:

    /customers/<org_uid>/users/<user_id>

    where <org_uid> is the unique identifier of the organization of the user and <user_id> is the unique identifier for the user that you want to edit.

    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:

    /customers/<org_uid>/users/<user_id>

    where <org_uid> is the unique identifier of the organization of the user and <user_id> is the unique identifier for the user that you want to edit.

    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:

    /customers/<org_uid>/users/<user_id>

    where <org_uid> is the unique identifier of the organization of the user and <user_id> is the unique identifier for the user that you want to delete.

    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

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

    /customers/<org_uid>/users/<user_id>/disable

    where <org_uid> is the unique identifier of the organization and <user_id> is the unique identifier for the user whose enabled state you want to change.

    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 conferences

    Create a conference for a user

    New in Cloud 5.1, API minor version 11.

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

    /customers/<org_uid>/conferences

    where <org_uid> is the organization reference number, which is a unique identifier for this organization

    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 conferences in this organization.

    To list conferences, make an HTTPS GET request to:

    /customers/<org_uid>/conferences

    where <org_uid> is the organization reference number, which is a unique identifier for this organization

    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 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 unique identifiers for conferences in an organization.

    Update a conference

    New in Cloud 5.1, API minor version 11.

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

    /customers/<org_uid>/conferences/<conf_id>

    where <conf_id> is the unique identifier for the conference returned when the conference was created and <org_uid> is the organization reference number, which is a unique identifier for this organization.

    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:

    /customers/<org_uid>/conferences/<conf_id>

    where <conf_id> is the unique identifier for the conference returned when the conference was created and <org_uid> is the organization reference number, which is a unique identifier for this organization. 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:

    /customers/<org_uid>/conferences/<conf_id>

    where <conf_id> is the unique identifier for the conference returned when the conference was created and <org_uid>is the organization reference number, which is a unique identifier for this organization. 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:

    /customers/<org_uid>/conferences/<conf_id>/occurrences/<occur_id>

    where <conf_id> is the unique identifier for the conference returned when the conference was created, <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), and <org_uid> is the organization reference number, which is a unique identifier for this organization .

    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:

    /customers/<org_uid>/conferences/<conf_id>/occurrences/<occur_id>

    where <conf_id> is the unique identifier for the conference returned when the conference was created, <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), and <org_uid> is the organization reference number, which is a unique identifier for this organization. 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:

    /customers/<org_uid>/conferences/<conf_id>/occurrences/<occur_id>

    where <conf_id> is the unique identifier for the conference returned when the conference was created, <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), and <org_uid> is the organization reference number, which is a unique identifier for this organization. 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.

    Request a feature list for an organization

    New in Cloud 5.1, API minor version 11.

    This request will obtain a list of API features available on the server and enabled for the specified organization.

    To obtain a list of API features available on the server and enabled for the organization, make an HTTPS GET request to:

    /customers/<org_uid>/features

    where <org_uid> is the organization reference number, which is a unique identifier for this organization.

    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).

    Request the version of an organization

    New in Cloud 5.1, API minor version 11.

    To obtain the Cloud software version for an organization, make an HTTPS GET request to:

    /customers/<org_uid>/version

    where <org_uid> is the organization reference number, which is a unique identifier for this organization.

    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.