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

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.

    On success, this generates a 204 No Content response.