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

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

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

    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

    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

    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

    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.