Request objects
Last updated February 4, 2021 Cloud API
The request objects are:
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>
"rtmp_enable": <boolean: optional, default: false>
"rtmp_uri": <string: optional, default: null>
"rtmp_token": <string: optional, default: null>
}
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). |
rtmp_enable | If true, meeting will attempt RTMP streaming (correct stream URL and key will be required) |
rtmp_uri | If rtmp_enable is true, this field is required. String will be filled into the Stream URL field |
rtmp_token | This field is optional, regardless of rtmp_enable. String will be filled into the Stream key field |
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 |
---|---|
|
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 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. |