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

 

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

1st 

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

|

| |

30th 

29 Bit index in integer “days_of_month_mask”.
31st  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 the user or video address of the room system, as registered in the StarLeaf Cloud.

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.

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>,
   "breeze": <breeze object: optional>,
   "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.
breeze

Setting for the breeze software client — refer to breeze request object. The default is Breeze is enabled for a user.

breeze request object

{
   "enabled":<boolean: required>,
    }
Field Description
enabled Boolean specifying if Breeze will be enabled or not.

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.