-
Notifications
You must be signed in to change notification settings - Fork 0
REST APIs
Sara edited this page Dec 11, 2025
·
37 revisions
HTTPS POST, mime-type application/json, with the request body being a JSON-serialized dictionary (key-value pairs).
All requests except Authenticate must include, besides the parameters listed under Request at each individual method, an auth_token parameter, as received in the response to the Authenticate method. Unless otherwise indicated, all request Input parameters are required.
The FQDN for API requests will be that of a company, typically the initial admin company created for the reseller during onboarding. E.g. the entire URL for an authenticate request would be https://reseller-admin.reseller.tld/enterprise_api/authenticate.
Response HTTP status code will indicate the overall status of the request:
- 2xx - the request succeeded
- 401 - authentication failed
- for Authenticate api: the supplied credentials are invalid
- for other methods:
-
Missing auth_tokenorInvalid token- theauth_tokenparameter is missing or invalid. -
Session expired- associated session has expired. please use Authenticate to get a new auth_token.
-
- 403 - attempting to act on objects beyond the scope of one’s role
- Reseller Admin beyond the current Reseller
- Company Admin beyond the current Company
- 404 - update, delete, and similar methods attempted where the indicated object does not exist
- 500 - internal server error
Response mime-type will be application/json, the body being a JSON-serialized dictionary including, besides the values listed under Response at each method, a ‘message’ with details of any errors.
- Host - may host conferences only.
- Company Admin - may host conferences, and via the web interface or this API, add/edit/delete hosts in his/her own Company
- Reseller Admin - may host conferences, and via the web interface or this API, add companies, manipulate subscriptions, and add/delete/hosts in any of the Reseller’s Companies
Each method below indicates which roles may use that method.
A reseller represents the organization selling conferencing as a white label of Iotum. A reseller can sell directly to Companies (customers) or can have sub resellers below them.
A Reseller has the following attributes:
- domain: abc-conferencing.com for example
ResellerAdmin
POST "/enterprise_api/domain/descendants"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98"
}
Response body (application/json):
{
"id": 3,
"domain": "website.com",
"display_name": "Video Meetings R Us",
"descendants: []
}
Response:
- id: The id of the child domain (sub-reseller)
- domain: The domain of the child domain
- display_name: The publicly displayed name of the child domain
- descendants: Child domains of the child domain (sub-sub-resellers)
Before calling other methods, API consumers must authenticate using an active "API Token".
- "API Tokens" can be managed in the "Developers" section of the Admin UI, accessible by reseller admins or company admins.
- You may have multiple active "API Tokens" at the same time. This allows the controlled access by different systems or personnels, as well as token rotation.
- The "API token" is linked to the account accessing the Admin UI. The account can coincide with a real host, but typically resellers will create a dedicated ‘host’ for API use.
NOTE: Using account credentials for authentication has been deprecated. Please migrate to "API Token".
Also see 12. OAuth for details on using OAuth with the API.
ResellerAdmin/CompanyAdmin
POST "/enterprise_api/authenticate"
Request body (application/json):
{
"api_token": "...api token..."
}
Response body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98"
}
Request:
- api_token: an active API Token from the Admin UI
Response:
-
auth_token: The token to be included with all subsequent requests, as described in the General section above. An
auth_tokenexpires 60 minutes after its last successful use in any of the methods below (i.e. it is ‘touched’ on each use). Please refer to section 1.2 for guidance.
A Company represents the customer. A company could be any organization that subscribes to a conferencing service. A company has any number of Host Accounts. Host accounts are the end users.
A company stores basic details about the customer, can have customizations available to all Hosts on that company and holds the billing details.
/enterprise_api/company/create
ResellerAdmin Only
POST "/enterprise_api/company/create"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"subdomain": "joe",
"name": "The Joe Company",
"customer_id": "Acme"
}
Response body (application/json):
{
"id": 5
}
Request:
| Field | Type | Description | Note |
|---|---|---|---|
| subdomain | string | Every company has a subdomain that is used in their meeting urls, i.e iotum.callbridge.com. | The subdomain must be unique within the scope of each reseller domain. |
| name | string | The name of the company as it should be displayed for billing purposes | |
| partner_id | number (Optional) | An ID for internal reporting that is not visible in the UI | |
| customer_id | number (Optional) | Any arbitrary string for your own purposes | |
| openid_provider | boolean (Optional) | Whether to use OpenID Connect for authentication | Contact your Rep for integration details. |
| primary_color | string (Optional) | CSS hex color notation. e.g. "#00ff00"
|
|
| accent_color | string (Optional) | CSS hex color notation. e.g. "#00ff00"
|
|
| currency | string (Optional) | Lower case ISO 4217. e.g. "usd"
|
|
| product_id | number (Optional) | The product to subscribe to, see products | default: the default product defined in the reseller domain. |
Response:
- id: id of the resulting new company
ResellerAdmin
Retrieve details for a particular company
POST "/enterprise_api/company/fetch"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5
}
Response body (application/json):
{
"subdomain": "joe",
"name": "The Joe Company",
"host_count": 3,
"hosts": [6, 7, 8],
"customer_id": "Acme"
}
Request:
- company_id: The id of the company you wish to fetch details of.
Response:
- subdomain: Every company has a subdomain that is used in their meeting urls, i.e iotum.callbridge.com. The subdomain must be unique within the scope of each reseller domain.
- name: The name of the company as it should be displayed for billing purposes
- host_count: Current number of hosts
- hosts: Array of host_id (q.v. in the Hosts section below), hosts in this company
- partner_id: An ID for internal reporting that is set via API during account creation
- customer_id: Optional. Any arbitrary string for your own purposes
ResellerAdmin Only
Change company subdomain, name, partner_id and/or customer_id
POST "/enterprise_api/company/update"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5,
"subdomain": "jane",
"name": "The Jane Company",
"customer_id": "Acme"
}
Response body (application/json):
{
"subdomain": "jane",
"name": "The Jane Company",
"host_count": 3,
"hosts": [6, 7, 8],
"customer_id": "Acme"
}
Request:
- company_id: The id of the company you wish to modify.
- subdomain: Every company has a subdomain that is used in their meeting urls, i.e iotum.callbridge.com. The subdomain must be unique within the scope of each reseller domain.
- name: The name of the company as it should be displayed for billing purposes
- partner_id: An ID for internal reporting that is set via API during account creation
- customer_id: Optional. Any arbitrary string for your own purposes
_ _
Response:
- subdomain: Every company has a subdomain that is used in their meeting urls, i.e iotum.callbridge.com. The subdomain must be unique within the scope of each reseller domain.
- name: The name of the company as it should be displayed for billing purposes
- host_count: Current number of hosts
- hosts: Array of host_id (q.v. in the Hosts section below), hosts in this company
- partner_id: An ID for internal reporting that is set via API during account creation
- customer_id: Optional. Any arbitrary string for your own purposes
ResellerAdmin
Retrieve details for all companies
POST "/enterprise_api/company/fetch_all"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98"
}
Response body (application/json):
[{
"subdomain": "joe",
"name": "The Joe Company",
"host_count": 3,
"hosts": [6, 7, 8],
"openid_provider": false
},
{
"subdomain": "jane",
"name": "The Jane Company",
"host_count": 4,
"hosts": [11, 12, 13],
"openid_provider": false
}]
Response: array of:
- subdomain: Every company has a subdomain that is used in their meeting urls, i.e iotum.callbridge.com. The subdomain must be unique within the scope of each reseller domain.
- name: The name of the company as it should be displayed for billing purposes
- host_count: Current number of hosts
- hosts: Array of host_id (q.v. in the Hosts section below), hosts in this company
-
openid_provider: If this company is an openid-connect authentication provider, we will send users through your auth instead of our own.
⚠️ Do not use any other value but false without contacting us.
ResellerAdmin
Deleting a company will remove all subscriptions (plans and add-ons) from the company, delete all hosts, and mark the company as deleted. Reseller admin companies page will show a ‘deleted at’ column .../admin/companies. This column can be filtered by date to show when a company was deleted.
POST “/enterprise_api/company/delete”
Request body (application/json):
{
“auth_token”: “dd6d5d51-9ea5-4c4c-82c8-677267aece98”
“company_id”: “12345”
}
A company can have one or more plans, and zero or more add-ons at a given time.
Having multiple plans enables companies to assign some hosts to one plan, and others to another plan. Each host individually can only be assigned to one plan at a time.
ResellerAdmin/CompanyAdmin
Fetch a list of all available products (plans and add-ons) for a reseller
POST "/enterprise_api/subscription/fetch_products"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98"
"include_description": true
}
Response body (application/json):
[
{
"slug": "small_plan",
"name": "Small Conference Plan",
"plan": true,
"description": "Description of the Small Conference Plan"
},
{
"slug": "large_plan",
"name": "Large Conference Plan",
"plan": true,
"description": "Description of the Large Conference Plan"
},
{
"slug": "recording",
"name": "Recording Add-On",
"plan": false,
"description": "Description of the Recording Add-On"
},
]
Response, array of:
- slug: an alphabetic unique identifier for the product
- name: a human-readable name of the product
- plan: boolean, whether the product is a plan [true] or an add-on [false]
- description: a human-readable description of the product
ResellerAdmin/CompanyAdmin
Create a subscription to a plan or add-on for a particular company.
POST "/enterprise_api/subscription/create"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5,
"slug": "small_plan",
"subscribe_all_hosts": false
}
Response body (application/json): "OK"
Request:
- company_id: The id of the company you wish to add this Subscription to.
- slug: alphabetic unique identifier for the product to add (see fetch_products above)
-
switch_plan (optional)
- If specified and set to the subscription ID of one of the company’s current plans, that plan will be canceled and used in to prorate the initial amount of the new plan (plan switching)
- If set to null, the current plan(s) of the company will not be canceled and instead the company will be subscribed to the provided plan in addition to their existing plan(s).
- When omitted (no key/value not present in the request body), the default behavior of switching the company’s current plan with the new plan will be applied.
- host_limit: A positive integer value that the new subscription’s host limit should be set to. When subscribing to a product that is using the per-host pricing method, the host_limit value provided will be multiplied by the per-host price of the product to determine and set the total amount of the monthly subscription charges.
- subscribe_all_hosts: Optional (default true). Whether to also add this subscription to all existing hosts. If false, the company, but no hosts, will be subscribed to the product. However, hosts can subsequently be subscribe via host/create or host/update (see below).
Response: "OK"
Partners can use the company_id and slug if follow up API calls to reference the specific subscription created for a company.
host_limit pricing details:
| Product Pricing Method: | Details: |
| Flat Rate ($ / month) | No host_limit parameter should be provided. The customer is charged the product.billing_amount each month.
There is no restriction on the number of hosts that can be assigned to the plan/add-on. |
| Per-Host Pricing ($ / host / month) | A host_limit parameter should be supplied, and will be multiplied by the product.billing_amount (per-host amount) to determine the total monthly charges for the subscription.
The host limit represents the maximum number of hosts that can be assigned to the plan/add-on, assigning additional hosts will automatically increment the host limit, and increase monthly charges. |
ResellerAdmin/CompanyAdmin
PUT "/enterprise_api/subscription/update"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5,
"slug": "small_plan",
"host_limit": 10
}
Response body (application/json): "OK"
Request:
- company_id: The id of the company you wish to add this Subscription to.
- slug: alphabetic unique identifier for the product. This is used to identify the associated subscription to be updated.
- host_limit: A positive integer value that the new subscription’s host limit should be set to. When subscribing to a product that is using the per-host pricing method, the host_limit value provided will be multiplied by the per-host price of the product to determine and set the total amount of the monthly subscription charges.
Response: "OK"
ResellerAdmin Only
Upon suspending a subscription a Host will no longer have access to features associated with the Plan or Add-on. If suspending a Subscription to a Plan the Hosts will no longer be able to host meetings.
A suspended Subscription can be reactivated at any time.
POST "/enterprise_api/subscription/suspend"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5,
"slug": "small_plan"
}
Response body (application/json): "OK"
Request:
- company_id: The id of the company you wish to suspend this Subscription for.
- slug: alphabetic unique identifier for the product to suspend (see fetch_products above)
Response: "OK"
ResellerAdmin Only
Reactivating a subscription will mean those Hosts have access to all the features associated with that subscription.
POST "/enterprise_api/subscription/reactivate"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5,
"slug": "small_plan"
}
Response body (application/json): "OK"
Request:
- company_id: The id of the company you wish to reactivate this Subscription for.
- slug: alphabetic unique identifier for the product to reactivate (see fetch_products above)
Response: "OK"
ResellerAdmin Only
Canceling a subscription is a permanent deactivation of that subscription. Hosts and Companies associated with that subscription can be subscribed to new subscriptions at any time but that particular subscription can not be reactivated once cancelled.
POST "/enterprise_api/subscription/cancel"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5,
"slug": "small_plan"
}
Response body (application/json): "OK"
Request:
- company_id: The id of the company you wish to cancel this Subscription for/from.
- slug: alphabetic unique identifier for the product to cancel (see fetch_products above)
Response: "OK"
ResellerAdmin Only
Suspends all active subscriptions on a company. Subscriptions in other statuses are untouched. Note that this operation is asynchronous; the response status code will be 202 Accepted.
POST "/enterprise_api/subscription/suspend_all"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5
}
Response body (application/json): "OK"
Request:
- company_id: The id of the company you wish to suspend this Subscription for.
- slug: alphabetic unique identifier for the product to suspend (see fetch_products above)
Response: "OK"
Reactivates all suspended subscriptions on a company. Subscriptions in other statuses are untouched. Note that this operation is asynchronous; the response status code will be 202 Accepted.
POST "/enterprise_api/subscription/reactivate_all"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5
}
Response body (application/json): "OK"
Request:
- company_id: The id of the company you wish to reactivate this Subscription for.
- slug: alphabetic unique identifier for the product to reactivate (see fetch_products above)
Response: "OK"
ResellerAdmin Only
POST "/enterprise_api/subscription/fetch"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5
}
Response body (application/json):
[
{
"id": 100,
"status": "Active",
"host_limit": 10,
"product": {
"slug": "small_plan",
"name": "Small Conference Plan",
"plan": true
},
},
{
"id": 101,
"status": "Active",
"host_limit": 15,
"product": {
"slug": "recording",
"name": "Recording Add-On",
"plan": false
}
}
]
Request:
- company_id: The id of the company you wish to fetch subscriptions for.
Response, array of:
- id: integer value uniquely identifying this subscription, globally.
- host_limit: integer indicating the assigned host limit (used for per-host priced subscriptions only)
-
product
- slug: an alphabetic unique identifier for the product
- name: a human-readable name of the product
- plan: boolean, whether the product is a plan [true] or an add-on [false]
- status: 'Active' or 'Suspended' (previously-canceled subscriptions not included)
A host is an account able to organize and host meetings and conference calls.
ResellerAdmin/CompanyAdmin
Create a new Host
POST "/enterprise_api/host/create"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 5,
"name": "John Host",
"email": "john@company.tld",
"password": "SoSecret5!",
"no_welcome_email": true,
"role": "HOST",
"subscription_ids": [102, 104],
"moderator_pin": 9876543,
"access_code": 1234567,
"native_streaming": true,
"auto_record": "none",
"auto_stream": "none",
"host_initiated_recording": true,
"waiting_room": true,
"stream_preview": { "duration": 60,
"interval": 300,
"image_preview": true },
"disable_emails": { "conference_invitations": true,
"conference_reminders": false,
"conference_summaries": false,
"transcription_summaries": false },
"time_format": { "time_24hr": false, "hm_separator": ":", "md_format": "M D", "md_y_comma": true },
"no_login": false,
"locale": "en-US",
"country_code": "US",
"time_zone: "US/Eastern"
}
Response body (application/json):
{
"host_id": 9,
"company_id": 5,
"name": "John Host",
"email": "john@company.tld",
"primary_dialin_number": {"phone_number": "14165551234",
"domestic_format": "(416) 555-1234",
"international_format": "+1 416-555-1234",
"country_code": "CA",
"location": "Toronto",
"id": null, "created_at": null, "updated_at": null,
"feature_id": null, "locale": null, "carrier": null,
"state": null, "billing_group": null, "display": null,
"organization_id": null, "grouped_billing_id": null,
"site_domain_id": null, "billing_code": null, "active": null,
"referral_number": null },
"meeting_url": "https://company.reseller.tld/conf/call/1234567",
"role": "HOST",
"openid_sub": "23081912eca",
"access_code": { "number": "1234567",
"id": null, "participant_id": null,
"lock_version": null, "updated_at": null,
"conference_call_id": null, "person_id": null,
"account_id": null, "recording_id": null,
"site_domain_id": null, "organization_id": null },
"moderator_pin": {"number": "9876543",
"id": null, "participant_id": null,
"lock_version": null, "updated_at": null,
"conference_call_id": null, "person_id": null,
"account_id": null, "recording_id": null,
"site_domain_id": null, "organization_id": null },
"password_creation_link": "https://...",
"login_token_public_key": "a1b2c3e4d5f6...",
"plan_slug": "small_plan",
"add_on_slugs": ["recording"],
"subscription_ids": [110, 111],
"sip_uri": "sip:1234567-0@sipgw.reseller.com",
"disable_emails": { "conference_invitations": true, "conference_reminders": false, "conference_summaries": false, "transcription_summaries": false },
"time_format": { "time_24hr": false, "hm_separator": ":", "md_format": "M D", "md_y_comma": true },
"locale": "en-US",
"country_code": "US",
"time_zone: "US/Eastern"
}
Request:
- company_id: The id of the company you wish to add the Host to. (Required when the API consumer is a Reseller Admin; ignored when a Company Admin: host will be created in Company Admin’s own company)
- name: The name of Host that will be displayed when joining meetings.
- email: The email address of the Host. This will be used for invitations and reminders as well as authentication.
- password: optional, to set on creation
- no_welcome_email: whether to not send the host a welcome email (optional, boolean, should probably be used with the above, and/or see password_creation_link in the Response)
- role: one of RESELLER_ADMIN, COMPANY_ADMIN, HOST - Only Reseller Admins can grant the Reseller Admin role; Reseller and Company Admins can grant the Company Admin or Host roles. Defaults to HOST if omitted.
- openid_sub: Optional. the OpenID subject identifier used for OAuth logins using your system rather than our login infrastructure. Do not use this feature without contacting us.
- moderator_pin: Optional. Providing this parameter will request a custom moderator pin for this account. If the number is already taken, the request will fail. If omitted, a number will be generated automatically.
- access_code: Optional. Providing this parameter will request a custom access code for this account. If the number is already taken, the request will fail. If omitted, a number will be generated automatically.
- native_streaming: Optional. Providing this parameter will enable live streaming for the host account on account creation. This bypasses the need to enable it through the account settings.
- auto_record: Optional. Indicates whether the conference should be recorded automatically and the format, allowable values are: none, audio, video. If omitted will default to none. Both record and stream must be the same value if recording and streaming together.
- auto_stream: Optional. Indicates whether the conference should be streamed automatically and the format, allowable values are: none, audio, video. If omitted will default to none. Both record and stream must be the same value if recording and streaming together.
- host_initiated_recording: Optional. Providing this parameter will change the trigger for automatically starting recording or streaming to also include the host joining the call.
- waiting_room: Optional. true or false, when set to true any participants joining the host’s conference will need to be let in by the organizer
- stream_preview: Optional. Allows recording a preview clip of provided duration every provided duration when recording or streaming. Also provides a preview image when requested. Preview clips and images are deleted after 24h.
-
subscription_ids: Optional. The list of subscription ids that define which products the host is subscribed to.
- Providing this property will set the host's subscriptions to the exact list provided. This means you can unsubscribe hosts from their subscriptions by omitting specific ids or by providing an empty array.
- If this property is omitted, the host's existing subscriptions will be left intact.
- IMPORTANT: The host limit for each subscription will automatically be incremented if required, so that the host limit remains greater than or equal to the number of hosts assigned to each subscription. Except in the case where hosts limit changes have been locked for the company, in which case an exception is raised.
- NOTE:
- Instead of passing subscription_ids, you can alternatively pass the following two optional arguments:
- plan_slug: the slug of the plan to assign the host to.
- add_on_slugs: an array of product slugs of add-ons to assign the host to.
- Instead of passing subscription_ids, you can alternatively pass the following two optional arguments:
- disable_emails: Optional. Specifies which emails are enabled or disabled for the host, options are conference_invitations, conference_reminders, conference_summaries, transcription_summaries and these are set to true to disable and false to enable.
-
public_username: Optional. Used to link user accounts on another platform (in addition to the
partner_id) -
time_format: Optional. Used to specify display of times and dates within the conferencing application. A sub-hash with the following keys:
- time_24hr: Whether times are displayed as 24-hour. Default false (display times as 12-hour with AM/PM)
- hm_separator: separator between hours and minutes in time of day. Default ':'. Typical values include ':', '.', ' [h] '. Literal letters must be escaped by enclosing them in square brackets as shown.
- md_format: Template for month and day in medium and long date formats. 'M' will be replaced with medium ('Aug') or long ('August') month, 'D' with 1- or 2-digit day. Default 'M D'. Typical values include 'M D', 'D M', 'D. M'.
- md_y_comma: Whether to display a comma between month-and-day and year in dates. Default true.
-
no_login: Optional. If
true, disables login via username (email)/password in the web UI (but login via SSO will still be allowed). This also impliesno_welcome_emailand ignores any password in the parameters. The principal advantage of this is that multiple hosts with the same email may be created if each isno_login: truesince it removes the authentication credential second purpose of the email. - locale: Optional. BCP-47 language preference, changes the user's voice prompts when dialing in and the browser/app UI language. Defaults to English if preferred language is not supported.
- country_code: Optional. Host's country code in two-letter ISO 3166 format.
- time_zone: Optional. Host's time zone in tz database (Region/City or Region/ZoneName) format
Response:
- host_id: The unique id of the host. This should be stored for all future APIs call on that host.
- company_id: The id of the company the host belongs to.
- name: The name of Host that will be displayed when joining meetings.
- email: The email address of the Host. This will be used for invitations and reminders as well as authentication.
- primary_dialin_number: The default dial-in number for the Hosts meeting invitations and reminders (primary_dialin_number is an object; .phone_number (raw e164), .domestic_format and .international_format represent the actual number to dial; choose the format that best suits your need; country_code and city are also included in case you wish to display to the end user; other properties can be safely ignored but are included here for the benefit of strict deserializers).
- meeting_url: The meeting url is the web location of the Host’s meeting room
- role: one of RESELLER_ADMIN, COMPANY_ADMIN, HOST
- access_code: to be used by non-moderator conference participants (access_code is an object; .number is the actual access code; other properties can be safely ignored but are included here for the benefit of strict deserializers)
- moderator_pin: to be used by moderator (moderator_pin is an object; .number is the actual moderator_pin; other properties can be safely ignored but are included here for the benefit of strict deserializers)
- password_creation_link: can be sent by resellers themselves to new hosts to allow setting password (most useful in conjunction with no_welcome_email: true in the request)
- login_token_public_key: this is what you will need to submit to us to use our SSO feature. See section 8.0 for details.
- plan_slug: slug (unique identifier, see subscription/fetch_products above) for the plan the host is subscribed to
- add_on_slugs: slug[s] for the add-on[s], if any, the host is subscribed to
- subscription_ids: An array of integers identifying the plan/add-on subscriptions that the host is currently assigned to.
- sip_uri: If the host is subscribed to the SIP Gateway feature, this sip URI can be used by SIP endpoints such as those from Cisco and Polycom to connect to the host’s meetings; null otherwise. Contact us to enable SIP Gateway.
- disable_emails: Shows the email settings for the host.
-
public_username: Optional. Used to link user accounts on another platform (in addition to the
partner_id) -
time_format: Optional. Used to specify display of times and dates within the conferencing application. A sub-hash with the following keys:
- time_24hr: Whether times are displayed as 24-hour. Default false (display times as 12-hour with AM/PM)
- hm_separator: separator between hours and minutes in time of day. Default ':'. Typical values include ':', '.', ' [h] '. Literal letters must be escaped by enclosing them in square brackets as shown.
- md_format: Template for month and day in medium and long date formats. 'M' will be replaced with medium ('Aug') or long ('August') month, 'D' with 1- or 2-digit day. Default 'M D'. Typical values include 'M D', 'D M', 'D. M'.
- md_y_comma: Whether to display a comma between month-and-day and year in dates. Default true.
- locale: User's stored BCY-47 language preference
- country_code: Host's country code in two-letter ISO 3166 format.
- time_zone: Host's time zone in tz database (Region/City or Region/ZoneName) format
/enterprise_api/host/fetch
ResellerAdmin/CompanyAdmin
Fetch the details of a particular host
POST "/enterprise_api/host/fetch"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 9
}
Response body (application/json):
{
"host_id": 9,
"company_id": 5,
"name": "John Host",
"email": "john@company.tld",
"primary_dialin_number": {"phone_number": "14165551234",
"domestic_format": "(416) 555-1234",
"international_format": "+1 416-555-1234",
"country_code": "CA",
"location": "Toronto",
"id": null, "created_at": null, "updated_at": null,
"feature_id": null, "locale": null, "carrier": null,
"state": null, "billing_group": null, "display": null,
"organization_id": null, "grouped_billing_id": null,
"site_domain_id": null, "billing_code": null, "active": null,
"referral_number": null },
"meeting_url": "https://company.reseller.tld/conf/call/1234567",
"role": "HOST",
"openid_sub": "23081912eca",
"access_code": { "number": "1234567",
"id": null, "participant_id": null,
"lock_version": null, "updated_at": null,
"conference_call_id": null, "person_id": null,
"account_id": null, "recording_id": null,
"site_domain_id": null, "organization_id": null },
"moderator_pin": {"number": "9876543",
"id": null, "participant_id": null,
"lock_version": null, "updated_at": null,
"conference_call_id": null, "person_id": null,
"account_id": null, "recording_id": null,
"site_domain_id": null, "organization_id": null },
"password_creation_link": "https://...",
"login_token_public_key": "a1b2c3e4d5f6...",
"plan_slug": "small_plan",
"add_on_slugs": ["recording"],
"subscription_ids": [110, 111],
"sip_uri": "sip:1234567-0@sipgw.reseller.com",
"disable_emails": { "conference_invitations": true, "conference_reminders": false, "conference_summaries": false, "transcription_summaries": false },
"time_format": { "time_24hr": false, "hm_separator": ":", "md_format": "M D", "md_y_comma": true },
"locale": "en-US",
"country_code": "US",
"time_zone: "US/Eastern"
}
Request:
- host_id: unique identifier of the host
Response:
- host_id: The unique id of the host. This should be stored for all future APIs call on that host.
- company_id: The id of the company the host belongs to.
- name: The name of Host that will be displayed when joining meetings.
- email: The email address of the Host. This will be used for invitations and reminders as well as authentication.
- primary_dialin_number: The default dial-in number for the Hosts meeting invitations and reminders (primary_dialin_number is an object; .phone_number (raw e164), .domestic_format and .international_format represent the actual number to dial; choose the format that best suits your need; country_code and city are also included in case you wish to display to the end user; other properties can be safely ignored but are included here for the benefit of strict deserializers).
- meeting_url: The meeting url is the web location of the Host’s meeting room
- role: one of RESELLER_ADMIN, COMPANY_ADMIN, HOST
- access_code: to be used by non-moderator conference participants (access_code is an object; .number is the actual access code; other properties can be safely ignored but are included here for the benefit of strict deserializers)
- moderator_pin: to be used by moderator (moderator_pin is an object; .number is the actual moderator_pin; other properties can be safely ignored but are included here for the benefit of strict deserializers)
- password_creation_link: can be sent by resellers themselves to new hosts to allow setting password (most useful in conjunction with no_welcome_email: true in the request)
- login_token_public_key: this is what you will need to submit to us to use our SSO feature. See section 8.0 for details.
- plan_slug: slug (unique identifier, see subscription/fetch_products above) for the plan the host is subscribed to
- add_on_slugs: slug[s] for the add-on[s], if any, the host is subscribed to
- subscription_ids: An array of integers identifying the plan/add-on subscriptions that the host is currently assigned to.
- sip_uri: If the host is subscribed to the SIP Gateway feature, this sip URI can be used by SIP endpoints such as those from Cisco and Polycom to connect to the host’s meetings; null otherwise. Contact us to enable SIP Gateway.
- openid_sub: The OpenID subject identifier used for OAuth logins using your system rather than our login infrastructure. Do not use this feature without contacting us.
- disable_emails: Shows the email settings for the host.
-
public_username: Optional. Used to link user accounts on another platform (in addition to the
partner_id) -
time_format: Optional. Used to specify display of times and dates within the conferencing application. A sub-hash with the following keys:
- time_24hr: Whether times are displayed as 24-hour. Default false (display times as 12-hour with AM/PM)
- hm_separator: separator between hours and minutes in time of day. Default ':'. Typical values include ':', '.', ' [h] '. Literal letters must be escaped by enclosing them in square brackets as shown.
- md_format: Template for month and day in medium and long date formats. 'M' will be replaced with medium ('Aug') or long ('August') month, 'D' with 1- or 2-digit day. Default 'M D'. Typical values include 'M D', 'D M', 'D. M'.
- md_y_comma: Whether to display a comma between month-and-day and year in dates. Default true.
- locale: User's stored BCY-47 language preference
- country_code: Host's country code in two-letter ISO 3166 format.
- time_zone: Host's time zone in tz database (Region/City or Region/ZoneName) format
/enterprise_api/host/update
ResellerAdmin/CompanyAdmin
Only host_id is required; all other input parameters optional. Omitted host properties will remain unchanged.
POST "/enterprise_api/host/update"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 9,
"name": "John ChangedName",
"email": "newemail@company.tld",
"role": "COMPANY_ADMIN",
"openid_sub": "23051912fbd",
"subscription_ids": [102, 104],
"moderator_pin": 9876543,
"access_code": 1234567,
"auto_record": "none",
"auto_stream": "none",
"host_initiated_recording": true,
"waiting_room": true,
"stream_preview": { "duration": 60,
"interval": 300,
"image_preview": true },
"image_url": "https://link.to/image.jpg",
"disable_emails": { "conference_invitations": true, "conference_reminders": false, "conference_summaries": false, "transcription_summaries": false },
"time_format": { "time_24hr": false, "hm_separator": ":", "md_format": "M D", "md_y_comma": true },
"locale": "en-US",
"country_code": "US",
"time_zone: "US/Eastern"
}
Response body (application/json):
{
"host_id": 9,
"company_id": 5,
"name": "John ChangedName",
"email": "newemail@company.tld",
"primary_dialin_number": {"phone_number": "14165551234",
"domestic_format": "(416) 555-1234",
"international_format": "+1 416-555-1234",
"country_code": "CA",
"location": "Toronto",
"id": null, "created_at": null, "updated_at": null,
"feature_id": null, "locale": null, "carrier": null,
"state": null, "billing_group": null, "display": null,
"organization_id": null, "grouped_billing_id": null,
"site_domain_id": null, "billing_code": null, "active": null,
"referral_number": null },
"meeting_url": "https://company.reseller.tld/conf/call/1234567",
"role": "COMPANY_ADMIN",
"openid_sub": "23051912fbd",
"access_code": { "number": "1234567",
"id": null, "participant_id": null,
"lock_version": null, "updated_at": null,
"conference_call_id": null, "person_id": null,
"account_id": null, "recording_id": null,
"site_domain_id": null, "organization_id": null },
"moderator_pin": {"number": "9876543",
"id": null, "participant_id": null,
"lock_version": null, "updated_at": null,
"conference_call_id": null, "person_id": null,
"account_id": null, "recording_id": null,
"site_domain_id": null, "organization_id": null },
"password_creation_link": "https://...",
"login_token_public_key": "a1b2c3e4d5f6...",
"plan_slug": "small_plan",
"add_on_slugs": ["recording"],
"subscription_ids": [110, 111],
"sip_uri": "sip:1234567-0@sipgw.reseller.com",
"disable_emails": { "conference_invitations": true, "conference_reminders": false, "conference_summaries": false, "transcription_summaries": false },
"time_format": { "time_24hr": false, "hm_separator": ":", "md_format": "M D", "md_y_comma": true },
"locale": "en-US",
"country_code": "US",
"time_zone: "US/Eastern"
}
Request:
- host_id: id of the host
- company_id: The id of the company the host belongs to.
- name: The name of Host that will be displayed when joining meetings.
- email: The email address of the Host. This will be used for invitations and reminders as well as authentication.
- role: one of RESELLER_ADMIN, COMPANY_ADMIN, HOST - Only Reseller Admins can grant the Reseller Admin role; Reseller and Company Admins can grant the Company Admin or Host roles.
- moderator_pin: optional. Providing this parameter will request a custom moderator pin for this account. If the number is already taken, the request will fail. If omitted, a number will be generated automatically.
- access_code: optional. Providing this parameter will request a custom access code for this account. If the number is already taken, the request will fail. If omitted, a number will be generated automatically.
- auto_record: Optional. Indicates whether the conference should be recorded automatically and the format, allowable values are: none, audio, video. If omitted will default to none. Both record and stream must be the same value if recording and streaming together.
- auto_stream: Optional. Indicates whether the conference should be streamed automatically and the format, allowable values are: none, audio, video. If omitted will default to none. Both record and stream must be the same value if recording and streaming together.
- host_initiated_recording: Optional. Providing this parameter will change the trigger for automatically starting recording or streaming to also include the host joining the call.
- waiting_room: Optional. true or false, when set to true any participants joining the host’s conference will need to be let in by the organizer
- stream_preview: Optional. Allows recording a preview clip of provided duration every provided duration when recording or streaming. Also provides a preview image when requested. Preview clips and images are deleted after 24h.
- image_url: optional. Providing this parameter with a valid image URL with open CORS policy will set the host’s profile picture to the image provided. Accepted formats are gif, png, jpg and jpeg.
- openid_sub: Optional. the OpenID subject identifier used for OAuth logins using your system rather than our login infrastructure. Do not use this feature without contacting us.
-
subscription_ids: Optional. The list of subscription ids that define which products the host is subscribed to.
- Providing this property will set the host's subscriptions to the exact list provided. This means you can unsubscribe hosts from their subscriptions by omitting certain ids or by providing an empty array.
- If this property is omitted, the host's existing subscriptions will be left intact.
- IMPORTANT: The host limit for each subscription will automatically be incremented if required, so that the host limit remains greater than or equal to the number of hosts assigned to each subscription. Except in the case where hosts limit changes have been locked for the company, in which case an exception is raised.
- NOTE:
- Instead of passing subscription_ids, you can alternatively pass the following two optional arguments:
- plan_slug: the slug of the plan to assign the host to.
- add_on_slugs: an array of product slugs of add-ons to assign the host to.
- Instead of passing subscription_ids, you can alternatively pass the following two optional arguments:
- disable_emails: Optional. Specifies which emails are enabled or disabled for the host, options are conference_invitations, conference_reminders, conference_summaries, transcription_summaries and these are set to true to disable and false to enable.
-
public_username: Optional. Used to link user accounts on another platform (in addition to the
partner_id) -
time_format: Optional. Used to specify display of times and dates within the conferencing application. A sub-hash with the following keys:
- time_24hr: Whether times are displayed as 24-hour. Default false (display times as 12-hour with AM/PM)
- hm_separator: separator between hours and minutes in time of day. Default ':'. Typical values include ':', '.', ' [h] '. Literal letters must be escaped by enclosing them in square brackets as shown.
- md_format: Template for month and day in medium and long date formats. 'M' will be replaced with medium ('Aug') or long ('August') month, 'D' with 1- or 2-digit day. Default 'M D'. Typical values include 'M D', 'D M', 'D. M'.
- md_y_comma: Whether to display a comma between month-and-day and year in dates. Default true.
- locale: Optional. BCP-47 language preference, changes the user's voice prompts when dialing in and the browser/app UI language. Defaults to English if preferred language is not supported.
- country_code: Optional. Host's country code in two-letter ISO 3166 format.
- time_zone: Optional. Host's time zone in tz database (Region/City or Region/ZoneName) format
Response:
- name: The name of Host that will be displayed when joining meetings.
- email: The email address of the Host. This will be used for invitations and reminders as well as authentication.
- primary_dialin_number: The default dial-in number for the Hosts meeting invitations and reminders (primary_dialin_number is an object; .phone_number (raw e164), .domestic_format and .international_format represent the actual number to dial; choose the format that best suits your need; country_code and city are also included in case you wish to display to the end user; other properties can be safely ignored but are included here for the benefit of strict deserializers).
- meeting_url: The meeting url is the web location of the Host’s meeting room
- role: one of RESELLER_ADMIN, COMPANY_ADMIN, HOST
- access_code: to be used by non-moderator conference participants (access_code is an object; .number is the actual access code; other properties can be safely ignored but are included here for the benefit of strict deserializers)
- moderator_pin: to be used by moderator (moderator_pin is an object; .number is the actual moderator_pin; other properties can be safely ignored but are included here for the benefit of strict deserializers)
- password_creation_link: can be sent by resellers themselves to new hosts to allow setting password (most useful in conjunction with no_welcome_email: true in the request)
- login_token_public_key: this is what you will need to submit to us to use our SSO feature. See section 8.0 for details.
- plan_slug: slug (unique identifier, see subscription/fetch_products above) for the plan the host is subscribed to
- add_on_slugs: slug[s] for the add-on[s], if any, the host is subscribed to
- subscription_ids: An array of integers identifying the plan/add-on subscriptions that the host is currently assigned to.
- sip_uri: If the host is subscribed to the SIP Gateway feature, this sip URI can be used by SIP endpoints such as those from Cisco and Polycom to connect to the host’s meetings; null otherwise. Contact us to enable SIP Gateway.
- openid_sub: The OpenID subject identifier used for OAuth logins using your system rather than our login infrastructure. Do not use this feature without contacting us.
- disable_emails: Shows the email settings for the host.
-
public_username: Optional. Used to link user accounts on another platform (in addition to the
partner_id) -
time_format: Optional. Used to specify display of times and dates within the conferencing application. A sub-hash with the following keys:
- time_24hr: Whether times are displayed as 24-hour. Default false (display times as 12-hour with AM/PM)
- hm_separator: separator between hours and minutes in time of day. Default ':'. Typical values include ':', '.', ' [h] '. Literal letters must be escaped by enclosing them in square brackets as shown.
- md_format: Template for month and day in medium and long date formats. 'M' will be replaced with medium ('Aug') or long ('August') month, 'D' with 1- or 2-digit day. Default 'M D'. Typical values include 'M D', 'D M', 'D. M'.
- md_y_comma: Whether to display a comma between month-and-day and year in dates. Default true.
- locale: User's stored BCY-47 language preference
- country_code: Host's country code in two-letter ISO 3166 format.
- time_zone: Host's time zone in tz database (Region/City or Region/ZoneName) format
ResellerAdmin/CompanyAdmin
POST "/enterprise_api/host/delete"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 8
}
Response code 202.
Request:
- host_id: unique identifier of the host
ResellerAdmin/CompanyAdmin
Re-send the the welcome email of the Host
POST "/enterprise_api/host/resend_invitation"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 8
}
Response message: OK
Request:
- host_id: unique identifier of the host
ResellerAdmin/CompanyAdmin
Send a Host a password reset email
POST "/enterprise_api/host/reset_password"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 8
}
Response message: OK
Request:
- host_id: unique identifier of the host
ResellerAdmin/CompanyAdmin
Details of the past conferences of the host.
POST "/enterprise_api/host/conferences"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 8,
"output": "summary",
"time_zone": "UTC",
"start_date": "2020-01-01",
"end_date": "2020-12-31"
}
Response body (application/json):
[
{
"conference_id": 256,
"start_time": "2020-09-29 11:10:00",
"end_time": "2020-09-29 11:20:00",
"total_participants": 5,
"total_participant_minutes": 20,
"meeting_summary_url": "https://test.domain.com/conf/summary/256"
}
]
Request:
- host_id: unique identifier of the host
- output: summary or detail, type of data to be returned. Optional defaults to summary if omitted.
- time_zone: Time zone for the start/end date and for the times in the response. Optional, defaults to UTC if omitted. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
- start_date: Filter by date. Optional.
- end_date: Filter by date: Optional.
Response:
Summary:
- conference_id: Unique conference ID
- start_time: Conference start date/time, if time_zone was specified in the request will be in the requested time_zone, if omitted will be in UTC. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
- end_time: Conference end date/time.
- total_participants: Total conference participants
- total_participant_minutes: Total minutes for all participants
- meeting_summary_url: URL to retrieve the meeting summary
Detail:
The detail output provides comprehensive data on the conference and the returned data will depend on the conference activity which includes:
- Conference_id: Unique conference ID
- Subject: Subject
- Agenda: Agenda
- Start_time: Date/time in the specified time_zone or defaults to UTC. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
- End_time: Date/time
- Day: Day of the conference
- Month: Month of the conference
- Year: Year of the conference
- Cancelled: true or false, true if the conference was cancelled.
- Participants: Number of participants
- Live_wall_posts: List of comments made during the conference
- Uploaded_documents: List of uploaded documents
- Recordings: List of recordings
-
Where there are more than ten (10) records:
page- A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use thenext_pagevalue returned in a previous response to request subsequent results.
ResellerAdmin/CompanyAdmin
Details of conference participants.
POST "/enterprise_api/host/cdrs"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 8,
"conference_id": 256,
"time_zone": "UTC",
"start_date": "2020-01-01",
"end_date": "2020-12-31"
}
Response body (application/json):
[
{
"id": 69226060,
"conference_id": 256,
"host_id": 8,
"host_name": "Host Name",
"host_email": "host@iotum.com",
"start_time": "2020-09-29 11:10:00",
"end_time": "2020-09-29 11:20:00",
"participant_id": 71974494,
"participant_name": "Participant Name 1",
"participant_email": "participant1@iotum.com",
"from": "+15551236789",
"to": "2342342",
"minutes": 880
},
{
"id": 69226061,
"conference_id": 256,
"host_id": 8,
"host_name": "Host Name",
"host_email": "host@iotum.com",
"start_time": "2020-09-29 11:10:00",
"end_time": "2020-09-29 11:20:00",
"participant_id": 71974494,
"participant_name": "Participant Name 2",
"participant_email": "participant2@iotum.com",
"from": "+15551236798",
"to": "2342342",
"minutes": 880
}
]
Request:
- host_id: unique identifier of the host
- conference_id: unique identifier of a conference, Optional
- time_zone: Time zone for the start/end date and for the times in the response. Optional, defaults to UTC if omitted. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
- start_date: Filter by date. Optional.
- end_date: Filter by date: Optional.
Response:
- Id: Unique CDR ID
- conference_id: Unique conference ID
- host_id: Unique host ID
- host_name: Host name
- host_email: Host email
- start_time: Participant's start date/time, if time_zone was specified in the request will be in the requested time_zone, if omitted will be in UTC. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
- end_time: Conference end date/time.
- participant_id: Unique participant ID
- participant_name: Participant name
- participant_email: Participant email
- from: Number participant originates from
- to: Number participant connected to
- minutes: Total minutes for the participant
Note: Only the first 100 records will be returned in the response.
List of calls which a given person is currently participating in.
POST "/enterprise_api/host/active_calls"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 8,
"time_zone": "UTC"
}
Response body (application/json):
[
{
"conference_id": 256,
"subject": "Call Subject",
"agenda": "Call Agenda",
"start_time": "2020-09-29 11:10:00"
}
]
Request:
- host_id: unique identifier of the host
Response:
- conference_id: Unique conference ID
- subject: Call’s subject
- agenda: Call’s agenda
- start_time: Call’s start date/time. If time_zone was specified in the request will be in the requested time_zone, if omitted will be in UTC. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
Get a summary of all the hosts in a company.
POST "/enterprise_api/host/fetch_all"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 8
}
Response body (application/json):
[
{
"host_id": 9,
"name": "John Host",
"email": "john@company.tld",
"meeting_url": "https://company.reseller.tld/conf/call/1234567",
"role": "COMPANY_ADMIN",
"access_code": "1234567"
"plan_slug": "small_plan",
"add_on_slugs": ["recording"]
}
{,
"host_id": 10,
"name": "Jane Host",
"email": "jane@company.tld",
"meeting_url": "https://company.reseller.tld/conf/call/1234568",
"role": "HOST",
"access_code": "1234568",
"plan_slug": "medium_plan",
"add_on_slugs": ["recording"]
}
]
Request:
- company_id: The id of the company whose hosts you wish to fetch. (Required when the API consumer is a Reseller Admin; ignored when a Company Admin: hosts will be fetched for Company Admin’s own company)
Response: array of
- host_id: unique identifier of the host
- name: The name of Host that will be displayed when joining meetings.
- email: The email address of the Host. This will be used for invitations and reminders as well as authentication.
- meeting_url: The meeting url is the web location of the Host’s meeting room
- role: one of RESELLER_ADMIN, COMPANY_ADMIN, HOST
- access_code: to be used by non-moderator conference participants, the access code itself as a string (not an object as with fetch)
- plan_slug: slug (unique identifier, see subscription/fetch_products above) for the plan the host is subscribed to
- add_on_slugs: slug[s] for the add-on[s], if any, the host is subscribed to
Contacts can be added to scheduled conferences.
/enterprise_api/contact/create
ResellerAdmin/CompanyAdmin
Create contacts for a Host or a Company. This function allows the creation of multiple contacts at the same time.
Creating contacts for a Host makes the contacts available in the scheduling user interface to that Host only.
Creating contacts for a Company makes the contacts available in the scheduling user interface to all Hosts in that company.
The examples in this section all show host_id in the requests; as described in the notes that follow each example request/response, company_id may be substituted to instead work with Company-level hosts (and can be omitted, if using Company Admin credentials, to work with one's own Company's Company-level contacts).
POST "/enterprise_api/contact/create"
Request body (application/json):
{
"auth_token": "8f946001-02b3-442b-9050-65b93c193f07",
"host_id": 31,
"contacts": [
{
"name": "John Smith",
"email": "john@smith.com",
"business_phone": "+12345678901",
"mobile_phone": "+12345678902",
"home_phone": "+12345678903",
"other_phone": "+12345678904",
"time_zone": "US/Eastern"
},
{
"name": "James Brown",
"email": "james@brown.com",
"business_phone": "+12345678905",
"mobile_phone": "+12345678906",
"home_phone": "+12345678907",
"other_phone": "+12345678908",
"time_zone": "US/Central"
}
]
}
Response body (application/json):
[
{
"contact_id": 35,
"name": "John Smith",
"email": "john@smith.com",
"business_phone": "+12345678901",
"mobile_phone": "+12345678902",
"home_phone": "+12345678903",
"other_phone": "+12345678904",
"time_zone": "US/Eastern",
"has_host": false
},
{
"contact_id": 37,
"name": "James Brown",
"email": "james@brown.com",
"business_phone": "+12345678905",
"mobile_phone": "+12345678906",
"home_phone": "+12345678907",
"other_phone": "+12345678908",
"time_zone": "US/Central",
"has_host": false
}
]
Request:
- host_id: The id of the host you wish to add the Contacts to. OR
- company_id: The id of the company you wish to add the Contacts to. (Required when the API consumer is a Reseller Admin; ignored when a Company Admin: contact will be created in Company Admin’s own company)
A list of contacts is supplied:
- name: The name of the Contact
- email: The email address of the Contact.
- business_phone: optional, business phone number
- mobile_phone: optional, mobile phone number
- home_phone: optional, home phone number
- other_phone: optional, other phone number
- time_zone: optional, IANA time zone name. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
Response:
A list of contacts is returned containing:
- contact_id: Unique id of the Contact.
- name: Name of the Contact.
- email: Email address of the contact
- business_phone: Business phone number
- mobile_phone: Mobile phone number
- home_phone: Home phone number
- other_phone: Other phone number
- time_zone: Time zone for the contact
- has_host: Indicates whether the contact is a host's contact details when true or a standalone contact when false.
/enterprise_api/contact/fetch
ResellerAdmin/CompanyAdmin
Fetch the details of a particular contact
POST "/enterprise_api/contact/fetch"
Request body (application/json):
{
"auth_token": "25af2fe2-010e-4868-8be8-802b100d34a7",
"host_id": 31,
"contact_id": 35
}
Response body (application/json):
{
"contact_id": 35,
"name": "John Smith",
"email": "john@smith.com",
"business_phone": "+12345678901",
"mobile_phone": "+12345678902",
"home_phone": "+12345678903",
"other_phone": "+12345678904",
"time_zone": "US/Eastern",
"has_host": false
}
Request:
- host_id: The id of the host whose Contact you want to fetch. OR
- company_id: The id of the company whose Contact you want to fetch. (Required when the API consumer is a Reseller Admin; ignored when a Company Admin: contact will be fetched from Company Admin’s own company)
- contact_id: Unique identifier of the contact
Response:
- contact_id: Unique id of the contact.
- name: Name of the contact.
- email: Email address of the contact.
- business_phone: Business phone number
- mobile_phone: Mobile phone number
- home_phone: Home phone number
- other_phone: Other phone number
- time_zone: Time zone for the contact. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
- has_host: Indicates whether the contact is a host's contact details when true or a standalone contact when false.
/enterprise_api/contact/fetch_all
ResellerAdmin/CompanyAdmin
Fetch all contact details of a particular host
POST "/enterprise_api/contact/fetch_all"
Request body (application/json):
{
"auth_token": "25af2fe2-010e-4868-8be8-802b100d34a7",
"host_id": 31
}
Response body (application/json):
[
{
"contact_id": 35,
"name": "John Smith",
"email": "john@smith.com",
"business_phone": "+12345678901",
"mobile_phone": "+12345678902",
"home_phone": "+12345678903",
"other_phone": "+12345678904",
"time_zone": "US/Eastern",
"has_host": false
},
{
"contact_id": 37,
"name": "James Brown",
"email": "james@brown.com",
"business_phone": "+12345678905",
"mobile_phone": "+12345678906",
"home_phone": "+12345678907",
"other_phone": "+12345678908",
"time_zone": "US/Central",
"has_host": false
}
]
Request:
- host_id: The id of the host whose Contacts you want to fetch. OR
- company_id: The id of the company whose Contacts you want to fetch. (Required when the API consumer is a Reseller Admin; ignored when a Company Admin: contacts will be fetched from Company Admin’s own company)
Response:
Returns an array of contacts:
- contact_id: Unique id of the contact
- name: Name of the contact
- email: Email address of the contact
- business_phone: Business phone number
- mobile_phone: Mobile phone number
- home_phone: Home phone number
- other_phone: Other phone number
- time_zone: Time zone for the contact. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
- has_host: Indicates whether the contact is a host's contact details when true or a standalone contact when false.
/enterprise_api/contact/update
ResellerAdmin/CompanyAdmin
Only contact_id is required; all other input parameters optional. Omitted contact properties will remain unchanged.
POST "/enterprise_api/contact/update"
Request body (application/json):
{
"auth_token": "25af2fe2-010e-4868-8be8-802b100d34a7",
"host_id": 31,
"contact_id": 35,
"name": "John Smith Updated",
"business_phone": "+12345678901",
"mobile_phone": "+12345678902",
"home_phone": "+12345678903",
"other_phone": "+12345678904",
"time_zone": "US/Eastern"
}
Response body (application/json):
{
"contact_id": 35,
"name": "John Smith Updated",
"email": "john@smith.com",
"business_phone": "+12345678901",
"mobile_phone": "+12345678902",
"home_phone": "+12345678903",
"other_phone": "+12345678904",
"time_zone": "US/Eastern"
}
Request:
- host_id: The id of the host whose Contact you want to update. OR
- company_id: The id of the company whose Contact you want to update. (Required when the API consumer is a Reseller Admin; ignored when a Company Admin: contact will be updated in Company Admin’s own company)
- contact_id: unique id of the contact
- name: Contact Name
- email: Contact Email
- time_zone: optional, IANA time zone name. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
Response:
- contact_id: unique id of the contact
- name: Contact Name
- email: Contact Email
- business_phone: Business phone number
- mobile_phone: Mobile phone number
- home_phone: Home phone number
- other_phone: Other phone number
- time_zone: IANA time zone name
/enterprise_api/contact/delete
ResellerAdmin/CompanyAdmin
POST "/enterprise_api/contact/delete"
Request body (application/json):
{
"auth_token": "25af2fe2-010e-4868-8be8-802b100d34a7",
"host_id": 31,
"contact_id": 37
}
Request:
- host_id: The id of the host whose Contact you want to delete. OR
- company_id: The id of the company whose Contact you want to delete. (Required when the API consumer is a Reseller Admin; ignored when a Company Admin: contact will be deleted from Company Admin’s own company)
- contact_id: unique id of the contact
Manage Drive and Drive files.
Status code 404 indicates the file is not found.
ResellerAdmin/CompanyAdmin
POST "/enterprise_api/drive/fetch_all"
Request body (application/json):
{
"auth_token": "25af2fe2-010e-4868-8be8-802b100d34a7",
"host_id": 31,
"page": <number> // optional, default: 1, page size: 20
}
Response body (application/json):
{
files: Array<{ id, created_at, filename, size }>,
total_pages: <number>,
current_page: <number>,
next_page: <number|null> // null: this is the last page
}
ResellerAdmin/CompanyAdmin
POST "/enterprise_api/drive/file/fetch"
Request body (application/json):
{
"auth_token": "25af2fe2-010e-4868-8be8-802b100d34a7",
"host_id": 31,
"id": 37
}
Response body (application/json):
{
id,
created_at,
filename,
size,
presentation_status, // 'processing'|'ready'|'failed'|'unsupported'
download_link,
mimetype,
page_count // number of pages in the file
}
ResellerAdmin/CompanyAdmin
Steps to add a new file:
- Request a pre-signed URL to upload
POST "/enterprise_api/drive/create"
Request body (application/json):
{
"auth_token": "25af2fe2-010e-4868-8be8-802b100d34a7",
"host_id": 31,
"filename": "presentation.mp4"
}
Response body (application/json):
{
id,
upload_url,
download_link
}
-
Transfer a local file to the “upload_url” (using PUT)
e.g.
curl -T <local file.ext> -L "<upload_url>" -
Notify the completion of upload
Status code 409 if the file has already been processed.
POST "/enterprise_api/drive/file/finish_upload"
Request body (application/json):
{
"auth_token": "25af2fe2-010e-4868-8be8-802b100d34a7",
"host_id": 31,
"id": 37
}
Response body (application/json):
{
id,
created_at,
filename,
size,
presentation_status, // not applicable
download_link,
mimetype,
page_count // not applicable
}
ResellerAdmin/CompanyAdmin
POST "/enterprise_api/drive/file/delete"
Request body (application/json):
{
"auth_token": "25af2fe2-010e-4868-8be8-802b100d34a7",
"host_id": 31,
"id": 37
}
Response code: 204
Manage Chat.
ResellerAdmin
Send a system message to DM or channel
POST "/enterprise_api/chat/create"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"company_id": 183,
"id": 123,
"message": "This is a message"
}
Response body (application/json):
{
"message": "OK"
}
Request:
- company_id: unique identifier of the company
- id: unique identifier of the DM chat room
- slug: Optional. unique slug of the channel chat room
- message: message to be sent to the specified DM or channel. The text will be displayed as a message from the name System.
Response:
- message: OK
The details below are for the initial release of the conference API functions. You get the calendar integration and advanced features but integrated into your own scheduling application. This will allow you to schedule meetings with advanced features like
- One-time access codes
- Moderator PINs
- Security PINs
- Recurring Meetings
- Default dial-in numbers (not yet implemented)
The access code is used by participants to access the meeting room. Think of it as a key to enter a locked door. Access codes are numeric strings between 3 - 9 digits.
The moderator token is to elevate one or more participants to have moderator role and functionality in the meeting without that participant being authenticated on the platform. Think of the moderator pin as a key to unlock Host functionality for a participant. Moderator tokens are randomly generated UUIDs.
When creating a conference either through 8.1 Schedule Conference or 8.2 Create Reservationless Conference an access code and moderator pin are returned for that conference.
Access Codes and Moderator Tokens can be split into two categories: Dedicated Access Codes and One Time Access Codes.
One Time Access Codes:
One Time access codes are randomly generated at the time the conference is created. Conference urls with one time access codes are valid from the time the conference is created until approximately 72 hours after the end time of the conference. Moderator Tokens are valid for use with this access code throughout the entire life cycle of the access code.
When the conference url is visited outside of the original conference time range a new conference instance will be created, however the access code and moderator token will be valid for all such instances.
Dedicated Access Codes:
Dedicated access codes belong to a Host and do not change. When a user visits the dedicated meeting url a reservation-less conference is created. When a conference is scheduled with a dedicated access code the conference is created for a specific time range. Either way the moderator token will be created for every conference created.
Recurring conferences will have the same moderator token for all conferences in the series.
ResellerAdmin/CompanyAdmin
Create a new scheduled conference
POST "/enterprise_api/conference/create"
Request body (application/json): {
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 1,
"subject": "Test Conference",
"agenda": "An agenda",
"start": "2020-09-19 13:00:00",
"time_zone": "America/Toronto",
"duration": 60,
"auto_record": "none",
"auto_stream": "none",
"auto_transcribe": false,
"one_time_access_code": true,
"secure_url": false,
"host_initiated_recording": true,
"security_pin": "123456",
"mute_mode": "conversation",
"participants": [
2,
3
],
"broadcast_stream_url": "https://domain/something.mp4"
}
Response body (application/json): {
"conference_id": 183,
"subject": "Test Conference",
"agenda": "An agenda",
"start": "2020-09-19 13:00:00",
"end_time": "2020-09-19 14:00:00",
"active": false,
"time_zone": "America/Toronto",
"duration": 60,
"auto_record": "none",
"auto_stream": "none",
"auto_transcribe": false,
"one_time_access_code": 987654321,
"security_pin": "123456",
"mute_mode": "conversation",
"room_url": "https://subdomain.domain.tld/conf/call/987654321",
"recordings": [],
"participants": [
1,
2,
3
],
"moderators": [
1
],
"is_streaming": false,
"moderator_token": "cnzrvyEeJp3H",
"participant_emails": [
{
"email": "bob@iotum.com",
"moderator": true
},
{
"email": "alice@iotum.com",
"moderator": false
}
],
"broadcast_stream_url": {
"source": url,
"state": null|'NEW'|'STARTED'|'STOPPED'|'FAILED'
}
}
Request:
-
host_id: unique identifier of the host
-
subject: Subject
-
agenda: Agenda
-
start: Start time, this works in conjunction with the time_zone to set the correct time.
-
time_zone: Time zone associated with the start time. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
-
duration: In minutes.
-
auto_record: Optional. Indicates whether the conference should be recorded automatically and the format, allowable values are: none, audio, video. If omitted will default to none. Both record and stream must be the same value if recording and streaming together.
-
auto_stream: Optional. Indicates whether the conference should be streamed automatically and the format, allowable values are: none, audio, video. If omitted will default to none. Both record and stream must be the same value if recording and streaming together.
-
auto_transcribe: Optional. Whether the recording should automatically be transcribed. Valid values are true or false. If omitted will default to false.
-
one_time_access_code: true or false, when set to true an access code will be returned in the response. Note that the generated access code can be used for additional conferences for up to 72 hours after the start of the original conference; additional conferences thus created will cause a one_time_access_code_reused webhook (see 11.23) to be sent. See 8.0.1 Access Code and Moderator PIN life cycle for more details.
-
secure_url: Optional. true or false, when set to true the room_url will contain an encrypted access code. Best when used with one_time_access_code.
-
host_initiated_recording: Optional. Providing this parameter will change the trigger for automatically starting recording or streaming to also include the host joining the call.
-
security_pin: Optional. Pin required to access the conference
-
mute_mode: Optional. Sets the initial participant mute settings. Options are:
- conversation - Default, all unmuted
- q&a - Participants muted, but can unmute. Only moderators will be able to use the Whiteboard or share their screen.
- presentation - Participants muted and can not unmute. Only moderators video will be visible to all and only moderators will be able to use the Whiteboard or share their screen.
If omitted will default to conversation.
-
participants: List of contact IDs to be included as participants.
- participant_emails: Alternatively participants can be listed via emails with moderators specified. If a participant’s emails is not on the host’s contact list, it will be added.
- participant_hosts: The host_id of other hosts in the same company can also be used with moderators specified.
-
broadcast_stream_url: Optional. The url to a MP4 video file that will automatically stream to the webinar and streaming pages at the exact start time of the conference. The URL must be publicly accessible during the scheduled time.
Response:
- conference_id: id of the conference
- subject: Subject
- agenda: Agenda
- start: Start time, this works in conjunction with the time_zone to indicate the correct time.
- end_time: The scheduled end time, according to the specified duration.
- active: Whether the call is active (is scheduled for the current time or has live participants)
- time_zone: Time zone associated with the start time. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
- duration: In minutes.
- auto_record: Indicates whether the conference will be recorded automatically and the format.
- auto_stream: Indicates whether the conference will be streamed automatically and the format.
- auto_transcribe: Whether the recording will be transcribed automatically.
- one_time_access_code: When the request has one_time_access_code set to true this field contains the conference access code. See 8.0.1 Access Code and Moderator PIN life cycle for more details.
- security_pin: Pin required to access the conference.
- mute_mode: The initial participant mute settings.Values as per the request.
- participants: List of participants in the conference, note the organizer is always included in the list. These are contact_id’s that can be used with contact/fetch and other contact methods.
- moderators: List of moderators in the conference. These are contact_id’s that can be used with contact/fetch and other contact methods.
- room_url: the URL for the meeting room. Can be navigated to in a browser to join the meeting.
- recordings: information about recordings made during the conference. For create, update, create/reservationless, will be an empty array [], as these return information about future conferences; however, see conference/fetch below for the substantive response for past conferences
- is_streaming: Boolean. Indicates if the conference is currently streaming
- moderator_token: If this token is provided in the call URL with the query param moderator_token=’token’, then the participant will join the call as a moderator. See 8.0.1 Access Code and Moderator PIN life cycle for more details.
- broadcast_stream: An object containing the source url and state of the broadcast stream. The source url being the url to the source video file being streamed and the state of that stream: null | 'NEW' | 'STARTED' | 'STOPPED' | 'FAILED'.
The above response is returned by the other API calls as well:
- update
- fetch
- fetch_all - Returns a list of these responses.
ResellerAdmin/CompanyAdmin
Creates an active reservationless conference call immediately. Mainly used for creating a reservationless call with a one time access code and/or a secure URL. Otherwise iotum can automatically create that reservationless call just by navigating to a host’s meeting URL.
POST "/enterprise_api/conference/create/reservationless"
Request body (application/json): {
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 183,
"one_time_access_code": true,
"secure_url": false
}
Response body (application/json): {
"conference_id": 183,
"subject": "Test Conference",
"agenda": "null",
"start": "2020-09-19 13:00:00",
"end_time": "2020-09-19 14:00:00",
"active": true,
"time_zone": "America/Toronto",
"duration": 60,
"auto_record": "none",
"auto_stream": "none",
"auto_transcribe": false,
"one_time_access_code": 987654321,
"security_pin": "123456",
"mute_mode": "conversation",
"room_url": "https://subdomain.domain.tld/conf/call/987654321",
"recordings": [],
"participants": [
1,
2,
3
],
"moderators": [
1
],
"is_streaming": false,
"moderator_token": "cnzrvyEeJp3H"
}
Request:
- host_id: unique identifier of the host
- one_time_access_code: true or false, when set to true an access code will be returned in the response. Note that the generated access code can be used for additional conferences for up to 72 hours after the start of the original conference; additional conferences thus created will cause a one_time_access_code_reused webhook (see 11.23) to be sent.
- secure_url: Optional. true or false, when set to true the room_url will contain an encrypted access code. Best when used with one_time_access_code.
Response:
- conference_id: id of the conference
- subject: Subject
- agenda: Agenda
- start: Start time, this works in conjunction with the time_zone to indicate the correct time.
- end_time: The scheduled end time, according to the specified duration.
- active: Whether the call is active (is scheduled for the current time or has live participants)
- time_zone: Time zone associated with the start time. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
- duration: In minutes.
- auto_record: Indicates whether the conference will be recorded automatically and the format.
- auto_stream: Indicates whether the conference will be streamed automatically and the format.
- auto_transcribe: Whether the recording will be transcribed automatically.
- one_time_access_code: When the request has one_time_access_code set to true this field contains the conference access code. See 8.0.1 Access Code and Moderator PIN life cycle for more details.
- mute_mode: The initial participant mute settings.
- participants: List of participants in the conference, note the organizer is always included in the list. These are contact_id’s that can be used with contact/fetch and other contact methods.
- moderators: List of moderators in the conference. These are contact_id’s that can be used with contact/fetch and other contact methods.
- room_url: the URL for the meeting room. Can be navigated to in a browser to join the meeting.
- recordings: information about recordings made during the conference. For create, update, create/reservationless, will be an empty array [], as these return information about future conferences; however, see conference/fetch below for the substantive response for past conferences
- is_streaming: Boolean. Indicates if the conference is currently streaming
- moderator_token: If this token is provided in the call URL with the query param moderator_token=’token’, then the participant will join the call as a moderator. See 8.0.1 Access Code and Moderator PIN life cycle for more details.
ResellerAdmin/CompanyAdmin
Update a scheduled conference
POST "/enterprise_api/conference/update"
Request body (application/json): {
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183,
"subject": "Test Conference",
"agenda": "An agenda",
"start": "2020-09-19 13:00:00",
"time_zone": "America/Toronto",
"duration": 60,
"auto_record": "none",
"auto_transcribe": false,
"one_time_access_code": false,
"mute_mode": "conversation",
"Participants": [
2,
3
]
}
Response body (application/json): {
"conference_id": 183,
"subject": "Test Conference",
"agenda": "An agenda",
"start": "2020-09-19 13:00:00",
"end_time": "2020-09-19 14:00:00",
"active": false,
"time_zone": "America/Toronto",
"duration": 60,
"auto_record": "none",
"auto_transcribe": false,
"one_time_access_code": 987654321,
"security_pin": "123456",
"mute_mode": "conversation",
"room_url": "https://subdomain.domain.tld/conf/call/987654321",
"recordings": [],
"participants": [
1,
2,
3
],
"moderators": [
1
],
"is_streaming": false,
"moderator_token": "cnzrvyEeJp3H"
}
Request:
-
conference_id: unique identifier of the conference
-
subject: Subject
-
agenda: Agenda
-
start: Start time, this works in conjunction with the time_zone to set the correct time.
-
end_time: The scheduled end time, according to the specified duration.
-
active: Whether the call is active (is scheduled for the current time or has live participants)
-
time_zone: Time zone associated with the start time. Values are those (e.g. US/Central, Europe/London, Asia/Tokyo, etc.) in the IANA Time Zone database (https://www.iana.org/time-zones)
-
duration: In minutes.
-
auto_record: Optional. Indicates whether the conference should be recorded automatically and the format, allowable values are: none, audio, video. If omitted will default to none.
-
auto_stream: Optional. Indicates whether the conference should be streamed automatically and the format, allowable values are: none, audio, video. If omitted will default to none. Both record and stream must be the same value if recording and streaming together.
-
auto_transcribe: Optional. Whether the recording should automatically be transcribed. Valid values are true or false. If omitted will default to false.
-
one_time_access_code: When the request has one_time_access_code set to true this field contains the conference access code.
-
security_pin: Optional. Pin required to access the conference.
-
mute_mode: Optional. Sets the initial participant mute settings. Options are:
- conversation - Default, all unmuted
- q&a - Participants muted, but can unmute. Only moderators will be able to use the Whiteboard or share their screen.
- presentation - Participants muted and can not unmute. Only moderators video will be visible to all and only moderators will be able to use the Whiteboard or share their screen.
If omitted will default to conversation.
-
participants: List of contact IDs to be included as participants.
-
participant_emails: Alternatively participants can be listed via emails with moderators specified. If a participant’s emails is not on the host’s contact list, it will be added:
POST "/enterprise_api/conference/update"
Request body (application/json): {
"participant_emails": [
{
"email": "bob@iotum.com",
"moderator": true
},
{
"email": "alice@iotum.com",
"moderator": false
}
]
}
Response:
Refer to the Schedule Conference response for field details.
ResellerAdmin/CompanyAdmin
Fetch a scheduled conference details
POST "/enterprise_api/conference/fetch"
Request body (application/json): {
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183
}
Response body (application/json): {
"conference_id": 183,
"subject": "Test Conference",
"agenda": "An agenda",
"start": "2020-09-19 13:00:00",
"end_time": "2020-09-19 14:00:00",
"active": false,
"time_zone": "America/Toronto",
"duration": 60,
"auto_record": "none",
"auto_stream": "none",
"auto_transcribe": false,
"one_time_access_code": 987654321,
"security_pin": "123456",
"mute_mode": "conversation",
"room_url": "https://subdomain.domain.tld/conf/call/987654321",
"recordings": [
{
"id": 12345,
"start_time": "2020-09-19 13:00:00",
"end_time": "2020-09-19 14:00:00",
"type": "video",
"publishing_state": "published",
"download_link": "https://subdomain.domain.tld/recording/inline/dc68df6c8a5.mp4",
"participants": [
1,
2,
3
],
"moderators": [
1
],
"is_streaming": false,
"moderator_token": "cnzrvyEeJp3H"
}
Request:
- conference_id: unique identifier of the conference
- output: [optional] if set to “detail”, the response will contain more detailed information about the conference and its associated data (see section on detailed output below).
Detailed Output:
When given a request parameter of “output” set to “detail”, the response will contain detailed data associated the conference including:
- participants: information about the participants (including those invited) of the conference, and there call descriptive record (CDR) data.
- chat_messages: a list of all public chat messages.
- uploaded_documents: a list of drive files uploaded over chat during the conference.
- Recordings: a list of all audio and video recordings, including the speech to text transcript.
Example of Detailed Conference Output:
{
"agenda": null,
"subject": "Wes's Meeting",
"start_time": "2022-06-03 16:30:00",
"end_time": "2022-06-03 16:43:00",
"day": "Friday",
"month": "June",
"year": "2022",
"conference_mode": "CONVERSATION_MODE",
"recurrence": null,
"one_time_access_code": false,
"additional_security_type": 1,
"cancelled": false,
"participants": [
{
"id": 128,
"person_id": 1,
"name": "Wes",
"email": "wesley@iotum.com",
"live_cdrs": [
{
"id": 35,
"ani": "+4361891128",
"dnis": "2342342",
"start_time": "2022-06-03T16:42:07.000Z",
"end_time": "2022-06-03T16:43:01.000Z",
"is_internet?": true,
"minute_usage": {
"minutes": 1,
"billing_group": "webrtc_billing",
"rate": null,
"cost": null,
"chargeable_minutes": null
}
}
]
}
],
"invited_count": 1,
"attended_count": 1,
"chat_messages": [
{
"id": 318,
"content": "message 1",
"participant_id": 128,
"created_at": "2022-06-03T12:42:10.976-04:00"
},
{
"id": 319,
"content": "message 2",
"participant_id": 128,
"created_at": "2022-06-03T12:42:12.360-04:00"
},
{
"id": 320,
"content": "",
"participant_id": 128,
"created_at": "2022-06-03T12:42:18.743-04:00"
}
],
"uploaded_documents": [
{
"id": 12,
"filename": "network.png",
"size": 319419,
"key": "d4d029a8-a3c3-4c96-b8c6-d8b7c9440d83",
"presentation_status": "ready",
"content_library": false,
"participant_id": 128,
"chat_message_id": 320,
"mimetype": "image/png",
"download_link": "https://wes.callbridge.com/drive_files/download/d4d029a8-a3c3-4c96-b8c6-d8b7c9440d83.png",
"image_preview_link": "https://wes.callbridge.com/drive_files/image_preview?key=d4d029a8-a3c3-4c96-b8c6-d8b7c9440d83",
"presentation_slides": [
{
"page_number": 1,
"width": 1763,
"height": 842,
"image_preview_link": "https://wes.callbridge.com/drive_files/image_preview?key=d4d029a8-a3c3-4c96-b8c6-d8b7c9440d83&page=1"
}
]
}
],
"recordings": [
{
"transcription_segments": [],
"transcription_tags": [],
"size": {}
},
{
"transcription_segments": [],
"transcription_tags": [],
"size": {
"mp4": 527562,
"mp3": 445797
}
}
],
"sentiment_available": false,
"sentiment_mean": null,
"sentiment_max": null,
"sentiment_min": null,
"has_video": false,
"has_audio": false,
"conference_id": 109,
"moderators": [
{
"person_id": 1,
"name": "Wes",
"email": "wesley@iotum.com"
}
],
"is_streaming": false,
"time_zone": "UTC",
"room_url": "https://wes.callbridge.com/conf/call/4361891",
"moderator_token": "xEQQUzqh_VZn",
"duration": 1,
"mute_mode": "conversation"
}Response:
Refer to the Schedule Conference response for details of other fields, except:
-
recordings: information about recordings made during the conference. An array of:
- id: unique identifier for the recording
- start_time
- end_time
- type: ‘audio’ or ‘video’
- publishing_state: ‘processing’ or ‘published’. ‘processing’ indicates that the recording is still undergoing final post-processing (the conference has likely just ended). Repeat the fetch in a few minutes.
- download_link: a link directly to the mp3 of an audio recording, or mp4 of a video recording (once the publishing state is ‘published’)
ResellerAdmin/CompanyAdmin
Fetch a list of all active scheduled conferences for a host. Please note that conferences scheduled more than 18 months in the future will not be returned.
POST "/enterprise_api/conference/fetch_all"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 1
}
Response body (application/json):
[
{
"conference_id": 183,
"subject": "Test Conference",
"agenda": "An agenda",
"start": "2020-09-19 13:00:00",
"end_time": "2020-09-19 14:00:00",
"active": false
"time_zone": "America/Toronto",
"duration": 60,
"auto_record": "none",
"auto_transcribe": false,
"one_time_access_code": 987654321,
"security_pin": "123456",
"mute_mode": "conversation",
"room_url":
"https://subdomain.domain.tld/conf/call/987654321",
"recordings": [],
"participants": [ 1, 2, 3 ],
"moderators": [ 1 ],
"is_streaming": false,
"moderator_token": "cnzrvyEeJp3H"
},
{
"conference_id": 184,
"subject": "Test Conference 2",
"agenda": "An agenda 2",
"start": "2020-09-19 14:00:00",
"end_time": "2020-09-19 15:00:00",
"active": false
"time_zone": "America/Toronto",
"duration": 60,
"auto_record": "none",
"auto_transcribe": false,
"one_time_access_code": 987654321,
"security_pin": "123456",
"mute_mode": "conversation",
"room_url":
"https://subdomain.domain.tld/conf/call/987654321",
"recordings": [],
"participants": [ 1, 2, 3 ],
"moderators": [ 1 ],
"is_streaming": false,
"moderator_token": "cnzrvyEeJp3H"
},
]
Request:
- output: if specified as "detail", the calls will be returned with additional details. See 6.7 Host Conferences
Response:
A list of scheduled conferences, refer to the Schedule Conference response for field details, and to the previous section, fetch, for details specifically about recordings.
Where there are more than ten (10) records: page - A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
ResellerAdmin/CompanyAdmin
Cancel a scheduled conference
POST "/enterprise_api/conference/cancel"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183
}
Response body (application/json):
{
"message": "OK"
}
Request:
- conference_id: unique identifier of the conference
Response:
- message: OK
ResellerAdmin/CompanyAdmin
Ends an active conference
POST "/enterprise_api/conference/end"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183
}
Response body (application/json):
{
"message": "OK"
}
Get Contact (see section 7) details for participants and moderators in a conference
POST "/enterprise_api/conference/fetch_participant_details"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183
}
Response body (application/json):
{
participants: [
{
"contact_id": 35,
"name": "John Smith",
"email": "john@smith.com",
"business_phone": "+12345678901",
"mobile_phone": "+12345678902",
"home_phone": "+12345678903",
"other_phone": "+12345678904",
"time_zone": "US/Eastern",
"has_host": false
}
],
moderators: [
{
"contact_id": 37,
"name": "James Brown",
"email": "james@brown.com",
"business_phone": "+12345678905",
"mobile_phone": "+12345678906",
"home_phone": "+12345678907",
"other_phone": "+12345678908",
"time_zone": "US/Central",
"has_host": true
}
]
}
Request:
- conference_id: unique identifier of the conference
Response:
- participants: array of contact structures (see 7.2 for details of fields) for participants in the conference
- moderators: array of contact structures (see 7.2 for details of fields) for moderators in the conference
Get the current number of participants viewing the livestream
POST "/enterprise_api/conference/fetch_livestream_viewer_count"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183
}
Response body (application/json):
{
"count": "4"
}
Request:
- conference_id: unique identifier of the conference
Response:
- count: number of livestream viewers currently viewing the livestream
Stop livestreaming on the specified conference
POST "/enterprise_api/conference/stop_streaming"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183
}
Response body (application/json):
{
"message": "OK"
}
Request:
- conference_id: unique identifier of the conference
Response:
- message: OK
Recurring conferences can be created by including a schedule parameter in the list of fields. The schedule field follows the iCalendar format for the RRULE field and allows flexibility in defining the schedule to be implemented.
The implementation supports a subset of the iCalendar RRULE options which are detailed below.
| Available Fields | Description |
|---|---|
| FREQ: | DAILY, WEEKLY or MONTHLY |
| INTERVAL: | Interval between days, weeks or months. |
| UNTIL: | End date for the recurring schedule, note this should just be date and will include the date in the schedule. |
| COUNT: | Number of occurrences |
| BYDAY: | For weekly this is MO, TU, WE, TH, FR, SA, SU, multiple days are supported. For Monthly this is the same set of days but prefixed by the week, so 2WE is the 2nd Wednesday. |
| BYMONTHDAY: | Only applicable to monthly and specifies the day of the month, note negative numbers can be used to indicate the reference is from the end of the month rather than the start. |
| Description | Example Rule |
|---|---|
| Daily every other day: | FREQ=DAILY;INTERVAL=2 |
| Daily until specific date: | FREQ=DAILY;UNTIL=20211231 |
| Weekly on Monday and Wednesday: | FREQ=WEEKLY;COUNT=10;BYDAY=MO,WE |
| Monthly, second Wednesday of the month, every other month: | FREQ=MONTHLY;COUNT=10;INTERVAL=2;BYDAY=2WE |
| Monthly, last Friday of the month,every month: | FREQ=MONTHLY;COUNT=10;INTERVAL=1;BYDAY=-1FR |
| Monthly, 10th day of the month: | FREQ=MONTHLY;COUNT=10;INTERVAL=1;BYMONTHDAY=10 |
| Monthly on the third-to-the-last day of the month, forever: | FREQ=MONTHLY;BYMONTHDAY=-3 |
Request and Response
POST "/enterprise_api/conference/create"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"host_id": 1,
"subject": "Test Conference",
"agenda": "An agenda",
"start": "2020-09-19 13:00:00",
"time_zone": "America/Toronto",
"duration": 60,
"auto_record": "none",
"auto_transcribe": false,
"one_time_access_code": true,
"security_pin": "123456",
"mute_mode": "conversation",
"participants": [ 2, 3 ],
"schedule": "FREQ=DAILY;INTERVAL=2"
}
Response body (application/json):
{
"conference_id": 183,
"subject": "Test Conference",
"agenda": "An agenda",
"start": "2020-09-19 13:00:00",
"end_time": "2020-09-19 14:00:00",
"active": false
"time_zone": "America/Toronto",
"duration": 60,
"auto_record": "none",
"auto_transcribe": false,
"one_time_access_code": 987654321,
"security_pin": "123456",
"mute_mode": "conversation",
"participants": [ 1, 2, 3 ],
"moderators": [ 1 ],
"is_master": true,
"master_id": 183,
"schedule": "FREQ=DAILY;INTERVAL=2"
}
Extra fields appear in the response:
- is_master: Indicates this is the master conference, conferences which are part of this schedule will have this set to false.
- master_id: ID for the master conference, for the master this will be the same as the conference_id
- schedule: The schedule that this conference is part of. Note the initial request may vary from the output as the system converts from the iCal RRULE to internal for processing and then when outputting the conference details it converts from internal to iCal so the content and formatting may differ.
Updating
Updating the master conference schedule will update all conferences in the series.
Deleting
Deleting conferences created by the schedule will only remove the specific instance unless the master conference is deleted which will remove all the occurrences.
Dial a phone number and add the callee to an active conference.
POST "/enterprise_api/conference/dial_number"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183,
"country_code": "CA",
"phone_number": "14165551212",
"name": "Jane",
"invitation_text": "John is bringing you into his meeting"
}
Response body (application/json):
{
"dialout_status": "new"
}
Request:
- conference_id: unique identifier of the conference
- country_code: ISO3166-2 country code of the phone number to dial
- phone_number: E164 (i.e. with country code) format of the phone number to dial, with or without leading +
- name: optional, participant name to be displayed in participant list and dialout status notifications. If omitted, defaults to phone_number.
- invitation_text: optional, text to be read to the callee when they answer. If omitted, defaults to ‘[host name] has invited you to a meeting with the subject [subject]’. This optional parameter supports use cases in which the dialout is made to the organizer on behalf of a non-organizer participant. In either case, this is followed by brief instructions about how to join (‘To join this meeting, please press one or just stay on the line. If you do not wish to join this meeting, please press two or just hang up.’).
Response:
- dialout_status: status of the dialout request. In initial implementation, always ‘new’.
Send a system message to an active conference call
POST "/enterprise_api/conference/message/create"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183,
"message": "This is a message"
}
Response body (application/json):
{
"message": "OK"
}
Request:
- conference_id: unique identifier of the conference
- message: message to be sent to the specified active conference call. The text will be displayed as a message from the name System.
Response:
- message: OK
Deletes all recordings for a past conference (and because they are related to the conference via recordings, all transcripts)
POST "/enterprise_api/conference/delete_recordings"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183,
}
Response body (application/json):
{
"message": "OK"
}
Request:
- conference_id: unique identifier of the conference
Response:
- message: OK
Deletes all transcriptions for a past conference
POST "/enterprise_api/conference/delete_transcriptions"
Request body (application/json):
{
"auth_token": "dd6d5d51-9ea5-4c4c-82c8-677267aece98",
"conference_id": 183,
}
Response body (application/json):
{
"message": "OK"
}
Request:
- conference_id: unique identifier of the conference
Response:
- message: OK
Below are error messages generated by the Schedule Conference API functions.
| Error | Description |
| Recording feature not enabled | The host does not have the recording feature assigned. |
| Video recording feature not enabled | The host does not have the video recording feature assigned. |
| Transcription feature not enabled | The host does not have the transcription feature assigned. |
| One time access code feature not available | The host does not have the one time access code feature assigned. |
| Must enable one_time_access_code to use security_pin | The security PIN has to be used in conjunction with the One Time Access Code. |
| Participants must be an array of contacts' | The participant field must be an array. |
| Participants has one or more contact that does not exist in the host's contact list. | The participants must be set as contacts for the host. |
Additionally there are errors generated when the schedule parameter is included:
| Error | Description |
| Can only include schedule details in the master conference | Recurring conferences can be updated but only the master conference can update the schedule. |
| Failed to parse the schedule rule. | This is a general error generated when trying to parse the schedule rule and will include additional details on the problem. |
| Schedule FREQ must be DAILY, WEEKLY or MONTHLY | The FREQ field only supports DAILY, WEEKLY or MONTHLY. |
| Schedule MONTHLY BYDAY only supports one item | For monthly rules the BYDAY field only supports a single day. |
| Schedule MONTHLY BYMONTHDAY only supports one item | Only a single day in the month is supported. |
| Schedule MONTHLY supports BYDAY or BYMONTHDAY, cannot use both | Only BYDAY or BYMONTHDAY can be used they cannot be used at the same time. |
| Schedule MONTHLY BYDAY must include number and day | For monthly the BYDAY field must include the week number and day. |
| Schedule MONTHLY must include BYDAY or BYMONTHDAY | For monthly one of BYDAY or BYMONTHDAY must be included. |
| Schedule WEEKLY must include BYDAY | For weekly BYDAY must be included. |