Request objects

The request objects are:

conf_settings request object

conf_repetition request object

conf_participant request object

occur_settings request object

location request object

user request object

directory_entries request object

create_integration request object

update_integration request object

Request objects for managing conferences

conf_settings request object

{ 
  "title": <string: required>, 
  "description": <string: optional, default: "">, 
  "timezone": <string: required>, 
  "permanent": <boolean: required>, 
  "start": <string: optional, default: null>,  # null if permanent 
  "end": <string: optional, default: null>,    # null if permanent 
  "repetition": <conf_repetition object: optional, default: null> 
				# null for conferences that do not repeat 
  "participants": <[
		<conf_participant object: optional>, 
		<conf_participant object: optional>, 
 		...], default: []>, 
  "layout": <string: optional, default: "speaker_with_strip">, 
  "require_owner": <boolean: optional, default: false>, 
  "recording": <boolean: optional, default: false>, 
  "dummy": <boolean: optional, default: false>,
  "hide_dir_entry": <boolean: optional, default: false>, 
  "send_emails": <boolean: optional, default: false>,
  "externally_managed": <boolean: optional, default: true>
}

Field	Description
title	The title of the conference. Must be between 2 and 256 characters in length.
description	A description of the conference, maximum length 2048 characters.
timezone	The name of the conference time zone, as per the IANA Time Zone Database. This must match one of the StarLeaf supported time zone names – see Timezone for more details.
permanent	True if the conference is permanent, else false.
start	The start date and time of the conference in ISO 8601 format (without time zone). Must be null if the conference is permanent.
end	The end date and time of the conference in ISO 8601 format (without time zone). Must be null if the conference is permanent.
repetition	The conf_repetition object must be not null if and only if the conference is recurring.
participants	An optional array of conf_participant objects, each of which identifies a user or room system that is present in the StarLeaf Cloud. The default value is an empty array.
layout	The layout to be used for the conference. Valid values are “speaker_with_strip”, “equal_panes”, “speaker_only”, and “large_speaker”. The default value is “speaker_with_strip”. “speaker_only” is new in Cloud 4.6, API minor version 9. The layouts are described in more detail below.
require_owner	If true, participants joining the conference are kept on hold until the conference owner joins. Otherwise, participants cease to be on hold after at least two have joined. The default value is false.
recording	If true, the conference is recorded.
dummy	If true, the conference is silently deleted after 30 days. Use this feature if the client must create a placeholder conference (in order to be allocated a dial in number, for example) before the details can be finalized.
hide_dir_entry	If false, permanent conferences will appear as directory listings. This is useful where permanent conferences are used as ‘virtual meeting rooms’ and where people might want to access them through the directory. If true, permanent conferences will not appear in the directory.
send_emails	If true, conference invitation emails are sent by the Cloud to the attendees.
externally_managed	If true, the conference cannot be edited on the Portal (and has been created by, for example, an Outlook Add-in).

layout
	Speaker with strip: In this layout, the current speaker is given prominence with the largest pane. Other participants are displayed in a strip below the current speaker. A maximum of five participants appear in the strip. Counters display the numbers of additional audio and video participants in the conference
	Eaual panes: In this layout, every participant is given equal prominence in equal-sized panes. The number of panes is determined by the number of participants in the conference. Up to 25 participants are shown. Counters display the numbers of additional audio and video participants in the conference
	Speaker only: In this layout, only the current speaker is seen in a large pane. Counters display the numbers of additional audio and video participants in the conference
	Large speaker: In this layout, the current speaker is given prominence in the largest pane. The size of that pane is determined by the number of other people in the conference. Every participant remains visible at all times up to a maximum of 10 participants. Counters display the numbers of additional audio and video participants in the conference

conf_repetition request object

{ 
  "frequency": <string: required>,
  "interval": <integer: required>, 
  "count": <integer: optional, default: null>, 
  "until": <string: optional, default: null>, 
  "days_of_week_mask": <integer: optional, default: null>, 
  "days_of_month_mask": <integer: optional, default: null>, 
  "months_of_year_mask": <integer: optional, default: null>, 
  "month_day_what": <integer: optional, default: null>,   
  "month_day_which": <string: optional, default: null> 
}

Field	Description
frequency	The base units used for repetition frequency: permitted values are “daily”, “weekly”,”monthly”,”yearly”.
interval	The number of frequency base units between successive repetition occurrences (valid range is 1 to 999).
count	The number of repetition occurrences to schedule (valid range is 1 to 999). At least one of “count” and “until” must be null. If “count” and “until” are both null, the conference repeats forever.
until	The date in ISO 8601 format after which the repetition stops. At least one of “count” and “until” must be null. If “count” and “until” are both null, the conference repeats forever.
days_of_week_mask	May be not null only if the frequency is weekly. The presence of this field allows a custom repetition pattern to be defined. Each day of the week on which the conference is to occur is defined by setting the corresponding bit in this integer. The mapping between days and bits is given below.
days_of_month_mask	May be not null only if the frequency is monthly. If “days_of_month_mask” is not null then both “month_day_what” and “month_day_which” must be null. A not null value for this field allows a custom repetition pattern to be defined. Each day of the month on which the conference is to occur is defined by setting the corresponding bit in this integer. The mapping between days and bits is given below.
months_of_year_mask	May be not null only if the frequency is yearly. A not null value for this field allows a custom repetition pattern to be defined. Each month of the year on which the conference is to occur is defined by setting the corresponding bit in this integer. The mapping between months and bits is given below.
month_day_what	May be not null only if the frequency is monthly or yearly. If “month_day_what” is not null then “month_day_which” must also be not null and “days_of_month_mask” must be null. A not null value for this field together with “month_day_which” allows more complex repetition patterns to be defined, of the form ‘repeat every <month_day_which> <month_day_what>’. The permitted values for the “month_day_what” integer, together with their meanings, are given below.
month_day_which	May be not null only if the frequency is monthly or yearly. If “month_day_which” is not null then “month_day_what” must also be not null and “days_of_month_mask” must be null. A not null value for this field together with “month_day_what” allows more complex repetition patterns to be defined, of the form ‘repeat every <month_day_which> <month_day_what>’. The permitted values for “month_day_which” are “first”, “second”, “third”, “fourth”, “last”.

Enumeration to use for fields “month_day_what” and “days_of_week_mask”:

Day	Enumeration	Description
Monday	0	Value in integer “month_day_what”, bit index in integer “days_of_week_mask”.
Tuesday	1	Value in integer “month_day_what”, bit index in integer “days_of_week_mask”.
Wednesday	2	Value in integer “month_day_what”, bit index in integer “days_of_week_mask”.
Thursday	3	Value in integer “month_day_what”, bit index in integer “days_of_week_mask”.
Friday	4	Value in integer “month_day_what”, bit index in integer “days_of_week_mask”.
Saturday	5	Value in integer “month_day_what”, bit index in integer “days_of_week_mask”.
Sunday	6	Value in integer “month_day_what”, bit index in integer “days_of_week_mask”.
Weekday	7	Value in integer “month_day_what”.
Weekend	8	Value in integer “month_day_what”.
Day	9	Value in integer “month_day_what”.

Enumeration to use for field “days_of_month_mask”:

Day	Enumeration	Description
1^st	0	Bit index in integer “days_of_month_mask”.
2nd	1	Bit index in integer “days_of_month_mask”.
3rd	2	Bit index in integer “days_of_month_mask”.
4th	3	Bit index in integer “days_of_month_mask”.
\|	\|	\|
30^th	29	Bit index in integer “days_of_month_mask”.
31^st	30	Bit index in integer “days_of_month_mask”.

Enumeration to use for field ” months_of_year_mask”:

Month	Enumeration	Description
January	0	Bit index in integer “months_of_year_mask”.
February	1	Bit index in integer “months_of_year_mask”.
March	2	Bit index in integer “months_of_year_mask”.
April	3	Bit index in integer “months_of_year_mask”.
\|	\|	\|
November	10	Bit index in integer “months_of_year_mask”.
December	11	Bit index in integer “months_of_year_mask”.

conf_participant request object

{ 
  "email": <string: required>
}

Field	Description
email	The email address of a user or video address of the room system as registered to the StarLeaf Cloud or any other email address

occur_settings request object

{ 
  "title": <string: optional, default: null>, 
  "description": <string: optional, default: null>, 
  "timezone": <string: optional, default: null>, 
  "start": <string: optional, default: null>, 
  "end": <string: optional, default: null>, 
  "participants": <[<conf_participant object: optional>,  	 	        
                  <conf_participant object: optional>, 
                  ...], default: null>, 
  "layout": <string: optional, default: null>, 
  "require_owner": <boolean: optional, default: null>, 
  "recording": <boolean: optional, default: null> 
}

Field	Description
title	The title of the occurrence. Must be between 2 and 256 characters in length.
description	A description of the occurrence, maximum length 2048 characters.
timezone	The name of the occurrence time zone, as per the IANA Time Zone Database. This must match one of the StarLeaf supported time zone names – see the Time Zone section for more details.
start	The start date and time of the occurrence in ISO 8601 format (without time zone). If this value is not null, then a valid value for end must also be provided.
end	The end date and time of the occurrence in ISO 8601 format (without time zone). If this value is not null, then a valid value for start must also be provided.
participants	An array of conf_participant objects, each of which identifies a user or room system that is present in the StarLeaf Cloud or any other email address.
layout	The layout to be used for the conference. Valid values are “speaker_with_strip”, “equal_panes” , “large_speaker”, and “null”. The default value is “null”.
require_owner	If true, participants joining the conference are kept on hold until the conference owner joins. Otherwise, participants cease to be on hold after at least two have joined.
recording	If true, the conference is recorded.

Where a null value is supplied, the field is not modified from its previous value. If that field did not have a value previously assigned for this occurrence, then the occurrence of the conference uses the value from the parent conference.

Request objects for managing customers

location request object

{
    "country_dialing_code": <string: optional, default: null>,
    "country": <string: required>,
    "state": <string: optional, default: null>,
    "timezone": <string: optional>,
    "locale": <string: optional>,
    "default_dscp": <string: optional, default: null>
}

Field	Description
country_dialing_code	Where a country has multiple country dialing codes, a string specifying the code for this organization. This is required when there is a choice for a country.
country	Two letter country code for the country of the organization, as given by the CLDR Database . The Cloud uses this to determine which data center hosts this customer.
state	The state within the chosen country for the organization. This is required (and must not be null) if the country has multiple states from which to choose.
timezone	An optional timezone for the organization. This defaults to the default for the given country/ state. For details of supported timezones, refer to Timezones.
locale	An optional locale for the organization. This is for the purposes of localization and sets the language and units for the organization. This defaults to the default for the given country/ state. For a list of valid locale codes, refer to Locales.
default_dscp	Where an organization has requested that StarLeaf network traffic adheres to their network configuration for Quality of Service, this is the DSCP value used by StarLeaf media packets.

Request objects for managing users

user request object

{
   "firstname": <string: required>,
   "lastname": <string: required>,
   "email": <string: required>,
   "is_org_admin": <boolean: optional, default: false>,
   "send_emails": <boolean: optional, default: true>,
   "enable_vvm": <boolean: optional, default: true>,
   "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>
}

Field	Description
firstname	First name of the new user.
lastname	Last name of the new user.
email	Email address of the new user.
is_org_admin	Boolean to specify whether this user has admin privileges. The default value is false.
send_emails	Boolean to specify whether to send account-settings emails. Setting to false will suppress the sending of account-settings emails to this user by the Cloud (NOT recommended). The default value is true.
enable_vvm	Boolean to turn off/on video voicemail for this user. The default value is true.
timezone	If the user is in a different timezone to the default timezone for the organization, this is the name of the user’s time zone, as per the IANA Time Zone Database. This must match one of the StarLeaf supported timezone names—see Timezone for more details.
locale	This is for the purposes of localization and sets the language and units for the user. For a list of valid locale codes, refer to Locales.
phone_home	The user’s home telephone number.
phone_work	Another contact telephone number for the user.
phone_mobile	A mobile phone number for the user.

Request objects for managing directory entries

directory_entries request object

{
   "firstname": <string: required>,
   "lastname": <string: required>,
   "phone_home": <string: optional, default: null>,
   "phone_work": <string: optional, default: null>,
   "phone_mobile": <string: optional, default: null>
}

Field	Description
firstname	First name of the new directory entry.
lastname	Last name of the new directory entry.
phone_home	A home contact telephone number, extension number, IP address, or video address for the directory entry.
phone_work	A work contact telephone number, extension number, IP address, or video address for the directory entry.
phone_mobile	A mobile phone number for the directory entry.

Request objects for managing integrations

create_integration request object

{
   "type": <string: optional, default: "custom">,
   "label": <string: required>,
   "is_org_admin": <boolean: optional, default: false>				
}

Field	Description
type	The type of integration. Currently, the only supported type is “custom”.
label	A name by which you can recognize the integration. If you use your integration to create conferences, this is the owner of those conferences. The label must be unique within the organization and must be between 2 and 250 characters in length.
is_org_admin	Whether or not the integration will have administrator privileges to the organization. For example, if your client will create users, it will need to have administrator privileges. If your client will only create conferences, it does not need administrator privileges. If true, the client will have administrator privileges.

update_integration request object

{
   "label": <string: required>,
   "is_org_admin": <boolean: optional, default: false>,
   "regen_password": <boolean: optional, default: false>				
}

Field	Description
label	A name by which you can recognize the integration. If you use your integration to create conferences, this is the owner of those conferences. The label must be unique within the organization and must be between 2 and 250 characters in length.
is_org_admin	Whether or not the integration will have administrator privileges to the organization. For example, if your client will create users, it will need to have administrator privileges. If your client will only create conferences, it does not need administrator privileges. If true, the client will have administrator privileges.
regen_password	If regen_password is true, then the Cloud will generate a new access token for the integration. Warning: all clients using the previous token will stop working until configured with the new token.

Integrating Cloud API

Request objects for managing conferences

conf_settings request object

conf_repetition request object

conf_participant request object

occur_settings request object

Request objects for managing customers

location request object

Request objects for managing users

user request object

Request objects for managing directory entries

directory_entries request object

Request objects for managing integrations

create_integration request object

update_integration request object