logo
Documentation Powered by ReDoc

Rainbow admin portal (1.236.21)

Download OpenAPI specification:Download

Rainbow API Support: support@openrainbow.com URL: https://developers.openrainbow.com/support

Rainbow administrator portal API guide

Preamble

Download Postman collection

Introduction

This guide describes list of API services that are provided by OT Rainbow management portal system. Services are used to manage OT Rainbow system entities

Protocol

REST interface is used for sending/receiving OT rainbow API messages. HTTP requests GET, DELETE, POST, UPDATE are used. Standard HTTP responses are used to provide requested information or error status. There is no session notion in OT Rainbow system, so requests could be issued according stateless model, without transport conservation between them. Additional data could be provided in message body. JSON is used as a main format for data encoding in message body part. Each request is started with the following pattern /{module}/{version}/ where {module} is a portal module name to address and {version} is a version of used API, par example, “v1.0”.

Security considerations

Each request should contain some credential information to authenticate itself. Standard HTTP authentication with basic/bearer modes is used. JSON Web Token mechanism is used to provide authentication information. JWT has a expire timeout that is controlled by OT Rainbow portal to prevent very long token usage. Also authentication with application token is used. The token must be provided in the request HTTP header, using a custom header: APIKey. At server side, token is verified, and if it doesn’t match, 403 Not Allowed response is sent. TLS is used as a transport protocol to support message exchanges between OT Rainbow portal and an application.

Authentication

Bearer

For accessing the API a valid JWT token or a valid OAuth has to be provided access token must be passed in all the queries in the 'Authorization' header.

  • JWT
    • A valid JWT token is generated by the API and returned as answer of a call to the route GET /api/rainbow/authentication/v1.0/login giving a valid user & password.
    • The following syntax must be used in the 'Authorization' header:
      Bearer xxxxxx.yyyyyyy.zzzzzz
  • OAuth access token
    • A valid OAuth access token is generated and returned as answer of the OAuth 2.0 workflow with authorization code grant. This is done by calling the route GET /api/rainbow/authentication/v1.0/oauth/authorize to get an authorization code and then POST /api/rainbow/authentication/v1.0/oauth/token to exchange it agains an access token and a refresh token.
    • The following syntax must be used in the 'Authorization' header:
      Bearer xxxxxx.yyyyyyy.zzzzzz
Security Scheme Type API Key
Header parameter name: Authorization

Bearer-x-rainbow-api-key

For accessing the API a valid API_KEY can be provided instead of Authorization Bearer JWT header

Security Scheme Type API Key
Header parameter name: x-rainbow-api-key

Avatar

Get user, company or bot avatar

This API can be used to retrieve users, companies or bots avatar.

Example: GET https://openrainbow.com/api/avatar/56c5c19f94141765119f896c?size=128

Clients can request avatars in a given size by specifying size query string parameter.

Avatar file can be resized from 1px to its original resolution, with a maximum of 512px:

  • If no size option is requested, avatar is returned by default with resolution of 80px.
  • Max requestable size is 512. If a higher resolution is requested, the default size is returned instead, i.e. 80px.
  • Original avatars' resolution can't be increased. If uploaded avatar size is 128 x 128 px, even is client request avatar with size 256, the original avatar file will be returned (128px).

Notes regarding bots avatar:

  • in the case of bots avatar, the entityId value to set in this URL corresponds to the field avatarId of the related bot resource.
  • bots avatar can be customized per company using API POST /api/rainbow/admin/v1.0/bots/:botId/companies/:companyId/avatar.
  • bot's avatarId value depends on the fact that the bot's avatar is customized or not for logged in user's company.
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
entityId
required
string

User, Company unique identifier or Bot avatarId.

query Parameters
update
required
string

Specify MD5(lastAvatarUpdateDate[DateTime format]) value from the user, company or bot for which the avatar is requested to ensure retrieving the latest avatar image (avatars are cached).

size
required
number [ 1 .. 512 ]
Default: 80

Specify avatar size in pixels (square size x size)

Responses

Companies Avatar

Delete company's avatar

This API can be used to delete avatar image for a given companyId.

Only a superadmin is allowed to handle avatars for 'Default' and 'Terminated' companies.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which list of administrators is requested

Responses

Response samples

Content type
application/json
{
  • "status": "Avatar successfully deleted for company 56c5c19f94141765119f896c",
  • "data": [ ]
}

Upload company's avatar

This API can be used to upload avatar image for a given companyId

Rules:

  • Avatar file has to be sent directly in http body (no JSon).
  • Only jpeg, jpg and png files are supported. Appropriate content-type has to be set (image/jpeg or image/png).
  • If company already has an avatar, the existing one is overwritten.
  • By default, avatar file size is limited to 4194304 bytes (4 MB) (this limit can be changed by integration team in admin portal config file).
  • When an avatar is uploaded, the field lastAvatarUpdateDate of the company is updated to the current date.

Only a superadmin is allowed to handle avatars for 'Default' and 'Terminated' companies.

To get the company's avatar, use the API GET /api/avatar/:entityId.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which list of administrators is requested

Request Body schema:
image/jpeg
image/jpeg
image/png
string <binary> (adminCompaniesPostAvatar)

File to be sent

Responses

Response samples

Content type
application/json
{
  • "status": "Avatar successfully set for company 56c5c19f94141765119f896c",
  • "data": [ ]
}

Companies

Delete a company

This API allows administrators to delete a company.

Users with superadmin role can delete any company (except default and terminated companies).

Users with bp_admin or bp_finance role can only delete companies of their End Customers (i.e. all the companies having bpId equal to their companyId).

Users with admin role can delete companies they can manage. That is to say:

  • an organization_admin can delete companies he manages (i.e. companies having organisationId equal to his organisationId)
  • a company_admin can only delete his company

A company can be deleted only if :

  • it's not the default company nor the terminated company
  • in case of BP company, it's not linked to EC / BP IR companies which are not themselves terminated
  • it's not linked to site(s)
  • it has no subscription(s)
  • it's not already seen as terminated (status equal terminated)
  • there are no more users in this company, including users in pending termination state (except for company_admin asking to delete his company if he is alone in it)

Note that following data linked to the company will be deleted too:

  • join company link(s)
  • join company invitation(s)
  • join company request(s)
  • avatar(s)
  • banner(s)
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "status": "Company 5901d451faae4928ef13bb78 successfully disabled",
  • "data": {
    }
}

Get a company data

Users with 'superadmin', 'support', 'customer_success_admin', 'sales_analytics' or 'business_admin' role can retrieve any company.
Users with admin role (and not having superadmin nor support role) can only retrieve their own company and companies they manage (case of organization_admin). They also have right to retrieve their BP company if they have one.
Users with bp_admin of bp_finance role (and not having superadmin nor support role) can only retrieve their own company and companies they manage (their EC companies). They also have right to retrieve their BP company if they have one. In the case of bp_admin or bp_finance of BP VAD companies, they can also retrieve EC companies being linked to their BP IR companies.

If user request his own company or a company he manages (superadmin, support, organisation admin), numberUsers field is returned with the number of Rainbow users being in this company.

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/companies/569d0ef3ef7816921f7e94fa

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less company details in response.

  • small: id, name
  • medium: id, name, status, adminEmail, companyContactId, isBP, bpType, country, website, slogan, description, size, economicActivityClassification, creationDate, lastAvatarUpdateDate, lastBannerUpdateDate, avatarShape, visibility
  • full for superadmin, support, business_admin, customer_success_admin, sales_analytics, bp_admin and bp_finance: All fields, including (dataLocation)
  • full for admin: All fields including BP field 'bpType' and dataLocation, but without fields (subscriptions, bsCompanyId, zuoraCompanyId, bpBusinessModel, bpApplicantNumber, bpCRDid, bpIsContractAccepted, bpContractAcceptationInfo, bpHasRightToSell, bpHasRightToConnect, bpHasRightForBYOT, preferredSipLoadBalancerId)
selectedThemeObj
boolean

Allows to return selectedTheme attribute as an object:

  • true returns selectedTheme as an object (e.g. { "light": "60104754c8fada2ad4be3e48", "dark": "5ea304e4359c0e6815fc8b57" }),
  • false return selectedTheme as a string.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a company

Users with superadmin role can update any company. Users with admin role (and not having superadmin role) can only update their own company.

Default and Terminated companies can't be renamed, and their name can't be use to rename another company

Sooner or later it will be unnecessary to manage each customization parameter individually. It will be necessary to create and/or apply customization templates.</br> <a href="admin/#api-customisation_template">See /admin/v1.0/customisations/templates</a>).

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
selectedThemeObj
boolean

Allows to return selectedTheme attribute as an object:

  • true returns selectedTheme as an object (e.g. { "light": "60104754c8fada2ad4be3e48", "dark": "5ea304e4359c0e6815fc8b57" }),
  • false return selectedTheme as a string.
Request Body schema: application/json
adminAllowedUpdateSubscriptionsOps
string
Enum: "all" "increase_only" "monthly"

In the case the company is linked to a Business Partner company and adminHasRightToUpdateSubscriptions is enabled, indicates the update operations for which the bp_finance allows the company_admin to perform on the subscriptions of his company.
Can only be set by superadmin or bp_finance of the related company.
Possible values:

  • `all: company_admin is allowed to perform all update operations on the subscriptions of his company
  • increase_only: company_admin is only allowed to increasemaxNumberUsers` on the subscriptions of his company (decrease is forbidden)
  • 'monthly': company_admin is only allowed to manage monthly subscription (increase and decrease)
adminCanSetCustomData
boolean

Whether or not administrators can set customData field for their own company.
adminCanSetCustomData can only be set:

  • by superadmin (all companies),
  • by bp_admin or bp_finance for the companies he manages,
  • by organization_admin for the companies he manages.
adminEmail
string [ 3 .. 255 ] characters /^[a-zA-Z0-9_\+-]+(\.[a-zA-Z0-9_\+-]+)*@[a-zA...

Company contact person email
adminEmail is case sentive.

adminHasRightToUpdateSubscriptions
boolean

In the case the company is linked to a Business Partner company, indicates if the bp_finance allows the company_admin to update the subscriptions of his company (if enable, allowed operations depend of the value of adminAllowedUpdateSubscriptionsOps).
Can only be set by superadmin or bp_finance of the related company.

adminHasTheRightToEnableDeskphoneFailover
boolean
Default: false

Superadmin allows admins of the company to select a given deskphone failover configuration for its cloudpbx devices.

adminServiceNotificationsLevel
string
Enum: "high" "medium" "low"

Level of service notification that admin should see

alertNotificationReception
string
Default: "disabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to receive alert notification.
Define if a user has the right to receive alert notification
alertNotificationReception can be:

  • enabled: Each user of the company can receive alert notification.
  • disabled: No user of the company can receive alert notification.
alertNotificationSending
string
Default: "disabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to send alert notification.
Define if a user has the right to send alert notification
alertNotificationSending can be:

  • enabled: Each user of the company can send alert notification.
  • disabled: No user of the company can send alert notification.
allowCloudPbxRecording
boolean
Default: false

deprecated ClouPbx recording capability now controlled by the 'voice_by_partner' BP business type. Allow company_admin recordings on cloud pbxs of companies for which this BP company is the BP, Only superadmin can update this parameter

allowDeviceFirmwareSelection
boolean
Default: false

Superadmin allows admins of the company to select a given firmware for its cloudpbx devices.

allowPhoneNumbersVisibility
boolean
Default: false

Indicates if Phone numbers should be visible or not when generating Voice CDR files. Applies only on BP companies.

allowTeamsToDesktopSso
boolean
Default: true

Superadmin allows if Teams add-in uses sso to login in desktop app for all company users

allowUsersSelectPublicTheme
boolean
Default: true

Allow users of this company to select a public theme.

allowUsersSelectTheme
boolean
Default: true

Allow users of this company to select a theme among the ones available (owned or visible by the company).

allowedProviderIds
Array of strings

A list of Provider Id that can be used company users to send sms. Only superddmin and bp_admin can set this field.

autoAcceptUserInvitations
boolean
Default: true

Allow to enable or disable the auto-acceptation of user invitations between users of this company (default true: enabled)

autoAddToUserNetwork
boolean
Default: false

Allow to enable or disable the auto addition to user's network between users of this company (default false: disabled)

avatarShape
string
Enum: "square" "circle"

Company's avatar customization

billingModel
string
Enum: "monthly" "prepaid_1y" "prepaid_3y" "prepaid_5y"

Billing model that can be subscribed for this company.

bpApplicantNumber
string [ 0 .. 255 ] characters

Reference of the Business Partner in ALE Finance tools (SAP)
Only applicable if isBP is true and bpType is DR or VAD.
Only settable by superadmin.

bpBusinessModel
string
Enum: "referral" "resell"

Indicates BP business model
Only applicable if isBP is true.
Only settable by superadmin.

bpBusinessType
Array of strings
Items Enum: "voice_by_partner" "voice_by_ale" "conference" "default"

Business type(s) that can be sold by a BP.

bpCRDid
string [ 0 .. 255 ] characters

Reference of the Business Partner in CDR
Only applicable if isBP is true and bpType is DR or VAD.
If bpCRDid is not defined, BP won't be able to sell (i.e. bpHasRightToSell can't be set to true)
Only settable by superadmin.

bpHasRightForBYOT
boolean

When True, the BP can create a SIP Hybrid Trunk for its managed companies (means that Bring Your Own Trunk feature is available for the BP). So when False, the "hybrid trunk" tab should be removed from the admin GUI
Only applicable if isBP is true.
Only settable by superadmin.

bpHasRightToConnect
boolean

When True [Default], the BP can connect CPE equipment of managed companies. So when False, the "equipment" tab should be removed from the admin GUI
Only applicable if isBP is true.
Only settable by superadmin.

bpHasRightToSell
boolean

Indicates if the Business has the right to sell
Only applicable if isBP is true and bpType is DR or VAD.
Only applicable if bpCRDid is defined.
Only settable by superadmin.

bpId
string

Link the company to the corresponding Business partner company.
bpId must correspond to a valid company having isBP equal to true.
Only directly settable by superadmin.
If the company is created by a bp_admin or a bp_finance, bpId is automatically set to BP company id.
For existing companies, bp_admin must use invitation mechanism to a company admin in order to request a link of this company company to his BP company.

bpIsContractAccepted
boolean
Default: false

Indicates if the Business has accepted the contract and can sell Rainbow offers
Should be set by bp_admin or bp_finance.
Only applicable if isBP is true.

bpType
string
Enum: "IR" "VAD" "DR"

Indicates BP Company type

  • IR: Indirect Reseller,
  • VAD: Value Added Distributor,
  • DR: Direct Reseller.
    Only applicable if isBP is true.
    Only settable by superadmin.
object

Set the business data of the company. Only settable by superadmin or business_admin.
Only settable by users with superadmin or business_admin role(s).

businessSpecific
string
Value: "UGAP"

Allow to specify if company has access to specific offers. Only settable by superadmin or business_admin.

catalogId
string

Id of the catalog of Rainbow offers to which the company is linked. The catalog corresponds to the list of offers the company can subscribe.

Only superadmin can change the catalogId of a company.
If the catalogId of a BP company is changed, the new catalogId of the BP is also set on the companies for which this BP company is the BP (when the company is a BP VAD, the catalog of the EC companies under the BP IR companies is also updated).

city
string [ 0 .. 255 ] characters

Company street

cloudPbxRecordingInboundOnly
boolean
Default: true

When CloudPbx recording is set, both inbound and outbound calls will be recorded for the selected users. If cloudPbxRecordingInboundOnly is set to true, only inbound calls will be recorded

cloudPbxVoicemailToEmail
string
Default: "none"
Enum: "none" "simple" "complete"

Cloudpbx email notification type when receiving a voicemail

companyCallNumber
string

If isCentrex = true, this is the company access number [multi-company call + company Area, ex: 8 210, 8 211]

companyContactId
string

User Id of a Rainbow user which is the contact for this company

contentPolicyLifeTime
boolean
Default: false

When different from -1 it activates content removal for all user of this companies with a content lifetime equals to contentPolicyLifeTime in minutes

country
string 3 characters
Default: "FRA"

Company country (ISO 3166-1 alpha3 format)

The list of allowed countries can be obtained using the API GET /api/rainbow/enduser/v1.0/countries

The country value which is provided at company creation is used to determine the location (data-center) where all the data related to this company will be stored. The data-center closest to the company's country is used.

⚠ Warning: the location of the company's data can't be changed after the company creation. The country value can be updated, but the data will remain in the data-center selected during the company creation.

Once the company is created, the location where the data are stored is indicated in the field dataLocation returned by the API GET /api/rainbow/admin/v1.0/companies/:companyId.

If no country is provided, the default value is "FRA", meaning that the company data are stored in French data-center.

csEmailList
Array of strings

A list of Customer Success email addresses (maximum length : 10)

csmEmailList
Array of strings

A list of Channel Sales Manager email addresses (maximum length : 10)

currency
string 3 characters
Enum: "USD" "EUR" "CNY"

Company currency, for payment of premium offers (ISO 4217 format)
For now, only USD, EUR and CNY are supported
Only settable by superadmin

customData
object

Company's custom data.
Object with free keys/values.
It is up to the client to manage the company's customData (new customData provided overwrite the existing one).

Restrictions on customData Object:

  • max 10 keys,
  • max key length: 64 characters,
  • max value length: 512 characters.


Company customData can only be created/updated by:
  • `superadmin` (all companies),
  • `bp_admin` or `bp_finance` for the companies he manages (except his company if its `adminCanSetCustomData` setting is not set to true),
  • `organization_admin` for the companies he manages,
  • `company_admin` for his own company if its `adminCanSetCustomData` setting is set to true (setting that can only be set by a superadmin, his bp_admin, bp_finance or organization_admin) or if he has the feature `ADMIN_CAN_SET_CUSTOM_DATA` (if the feature is enabled, it overwrites the value of the company setting).
ddiReadOnly
boolean

Indicates if admin of IR company is allowed to create or delete a DDI. Used only on IR companies.
This parameter can only be set by VAD bp_admin or superadmin.

defaultLicenseGroup
string

Group of license to assign to user when finalizing his account. Should be one of offers' groupName (e.g. Enterprise, Business ...)

defaultOptionsGroups
Array of strings

List of options to assign to user when finalizing his account. Should be one of offers' groupName (e.g. Alert ...)

delegatedCallPushDisable
boolean
Default: false

This setting allows to avoid disabling telephony events on manager when call delegation is enabled in manager_assistant supervision group belonging to this company.
This setting can only be set by a user with role superadmin.
This setting is optional: when it is not present, it is considered as having his default value (false): when a manager enables call delegation he will no longer receive telephony events on his mobile devices.

description
string [ 0 .. 2000 ] characters

A free string that describes the company (2000 char length)

disableCCareAdminAccess
boolean

When True, disables the access to the customer care logs for admins of this company.
Note that if disableCCareAdminAccessCustomers is enabled on its BP company or disableCCareAdminAccessResellers is enabled on its BP VAD company, this setting is forced to true.
disableCCareAdminAccess can only be set:

  • by superadmin (all companies),
  • by bp_admin or bp_finance for the companies he manages,
  • by organization_admin for the BP companies he manages.
  • by organization_admin for the companies he manages.
disableCCareAdminAccessCustomers
boolean

When True, disables the access to the customer care logs for admins of all the customers company.
This setting is only applicable for BP companies (isBP=true)

  • If the BP company is a DR or an IR, enabling this setting disables the access to the customer care logs for the admins of all its customers companies.
  • If the BP company is a VAD, enabling this setting disables the access to the customer care logs for all the admins of its customers companies.
    Note that the bp_admins/admins of all the BP IRs companies linked to this VAD still have access to the customer care logs (the setting disableCCareAdminAccessResellers on the BP VAD company allows to disable it).
    disableCCareAdminAccessCustomers can only be set:
    • by superadmin (all BP companies),
    • by bp_admin or bp_finance of a BP VAD company for the BP companies he manages,
    • by organization_admin for the BP companies he manages,
    • by company_admin for the BP company he manages.
disableCCareAdminAccessResellers
boolean

When True, disables the access to the customer care logs for admins of all the BP IRs companies linked to the BP VAD and their customers company.
This setting is only applicable for BP VAD companies (isBP=true and bpType=VAD)
Enabling this setting disables on the BP VAD company disables the access to the customer care logs for the bp_admins/admins of all the BP IRs linked to this VAD, and to all the admins of their customers.
Note that the admins of all the customer companies directly linked to this VAD still have access to the customer care logs (the setting disableCCareAdminAccessCustomers on the BP VAD company allows to disable it).
disableCCareAdminAccessResellers can only be set:

  • by superadmin (all BP VAD companies),
  • by bp_admin or bp_finance of a BP VAD company for the BP companies he manages,
  • by organization_admin for the BP VAD companies he manages,
  • by company_admin for the BP VAD company he manages.
displayIdrFiles
boolean

Indicates if IDR files should be displayed to BP on Web Admin (invoices view). Only settable by superadmin or business_admin.

documentGracePeriod
boolean
Default: false

When content removal is active for the organisation it represents the period in minutes where a document is still available event if it's content policy lifetime has expired

economicActivityClassification
string
Enum: "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "M" "N" "O" "P" "Q" "R" "S" "T" "U"
  • A: AGRICULTURE, FORESTRY AND FISHING
  • B: MINING AND QUARRYING
  • C: MANUFACTURING
  • D: ELECTRICITY, GAS, STEAM AND AIR CONDITIONING SUPPLY
  • E: WATER SUPPLY; SEWERAGE, WASTE MANAGEMENT AND REMEDIATION ACTIVITIES
  • F: CONSTRUCTION
  • G: WHOLESALE AND RETAIL TRADE; REPAIR OF MOTOR VEHICLES AND MOTORCYCLES
  • H: TRANSPORTATION AND STORAGE
  • I: ACCOMMODATION AND FOOD SERVICE ACTIVITIES
  • J: INFORMATION AND COMMUNICATION
  • K: FINANCIAL AND INSURANCE ACTIVITIES
  • L: REAL ESTATE ACTIVITIES
  • M: PROFESSIONAL, SCIENTIFIC AND TECHNICAL ACTIVITIES
  • N: ADMINISTRATIVE AND SUPPORT SERVICE ACTIVITIES
  • O: PUBLIC ADMINISTRATION AND DEFENCE; COMPULSORY SOCIAL SECURITY
  • P: EDUCATION
  • Q: HUMAN HEALTH AND SOCIAL WORK ACTIVITIES
  • R: ARTS, ENTERTAINMENT AND RECREATION
  • S: OTHER SERVICE ACTIVITIES
  • T: ACTIVITIES OF HOUSEHOLDS AS EMPLOYERS; UNDIFFERENTIATED GOODS- AND SERVICES-PRODUCING ACTIVITIES OF HOUSEHOLDS FOR OWN USE
  • U: ACTIVITIES OF EXTRATERRITORIAL ORGANISATIONS AND BODIES
Array of objects (putCompaniesEndOfConferenceBehavior)

Behavior settings after the end of conference.

externalReference
string [ 0 .. 64 ] characters

Free field that BP can use to link their Indirect Resellers / End Customers to their IS/IT tools
Only applicable by superadmin or by bp_admin or bp_finance on one of his Indirect Resellers / End Customers companies.
bp_admin or bp_finance of an IR company cannot update this field.

externalReference2
string [ 0 .. 64 ] characters

Free field that BP can use to link their Indirect Resellers / End Customers to their IS/IT tools
Only applicable by superadmin or by bp_admin or bp_finance on one of his Indirect Resellers / End Customers companies.

giphyEnabled
boolean

Whether or not giphy feature is enabled for users belonging to this company (possibility to use animated gifs in conversations)
This field is deprecated. Manage instead useGifCustomisation field!

hideContractInfo
boolean

Superadmin and Business_admin can update this field. If true, the 4 contractual documents for BP are hidden.

isBP
boolean

Indicates if the company is a Business partner company
Only settable by superadmin

isCentrex
boolean

Indicates if the company is one tenant of a multi-tenant call server (OXE - OTEC-S or third_party) (default: false)

kamEmailList
Array of strings

A list of Key Account Manager email addresses (maximum length : 10)
These fields can only be set by a business_admin or a superadmin

mobilePermanentConnectionMode
boolean
Default: false

deactivate push mode for mobile devices.
When we can't rely on Internet and Google FCM services to wake-up the app or notify the app, we can fall back to a direct XMPP connection.
For customers using Samsung devices with Google Play services, we must have an option on admin side to set this permanent connection mode, so that mobile apps can rely on this parameter. This option will be applied for the whole company.

name
required
string [ 1 .. 255 ] characters

Company name

offerType
string
Enum: "freemium" "premium"

Company offer type.
Companies with offerType=freemium are not able to subscribe to paid offers, they must be premium to do so.
Only superadmin can set offerType from premium to freemium.

postalCode
string [ 0 .. 64 ] characters

Company postal code

preferredSipLoadBalancerId
string

Indicates the identifier of the preferred SIP Load Balancer (Rainbow Hub context ; used for HybridTrunks of associated ECs)
Only applicable if isBP is true.
Only settable by superadmin.

salesforceAccountId
string [ 0 .. 64 ] characters

Customer's Salesforce reference.
Only settable by users with superadmin or business_admin role(s).

salesforceAccountName
string [ 0 .. 64 ] characters

Customer's Salesforce account name.
Only settable by users with superadmin or business_admin role(s).

salesforceAccountOwner
string [ 0 .. 64 ] characters

Customer's Salesforce account owner.
Only settable by users with superadmin or business_admin role(s).

seEmailList
Array of strings

A list of System Engineer email addresses (maximum length : 10)

selectedDeviceFirmware
string
Default: "released"
Enum: "released" "latest"

Cloudpbx default device firmware

  • released: Default value, device firmware will be the official released one.
  • latest: Device firmware can be a more up to date binary (e.g. early adopters)
    If allowed by superadmin, company admin can then select the kind of firmware for all the users, or only for some of them.
object

Set the selected theme(s) for users of the company.

object

Set the selected theme(s) for customers of this BP company.
This param only applies for BP companies.

sendPrepaidSubscriptionsNotification
boolean

Indicates if company_admin should receive email notification about prepaid subscriptions expiring soon. Used only on end customer companies

size
string
Default: "self-employed"
Enum: "self-employed" "1-10 employees" "11-50 employees" "51-200 employees" "201-500 employees" "501-1000 employees" "1001-5000 employees" "5001-10,000 employees" "10,001+ employees"

An overview of the number of employees

slogan
string [ 0 .. 255 ] characters

A free string corresponding to the slogan of the company

state
string
Enum: "null" "AA" "AE" "AP" "AK" "AL" "AR" "AZ" "CA" "CO" "CT" "DC" "DE" "FL" "GA" "GU" "HI" "IA" "ID" "IL" "IN" "KS" "KY" "LA" "MA" "MD" "ME" "MI" "MN" "MO" "MS" "MT" "NC" "ND" "NE" "NH" "NJ" "NM" "NV" "NY" "OH" "OK" "OR" "PA" "PR" "RI" "SC" "SD" "TN" "TX" "UT" "VA" "VI" "VT" "WA" "WI" "WV" "WY" "AB" "BC" "MB" "NB" "NL" "NS" "NT" "NU" "ON" "PE" "QC" "SK" "YT"

When country is 'USA' or 'CAN', a state must be defined. Else it is not managed.

The list of allowed states can be obtained using the API GET /api/rainbow/enduser/v1.0/countries for the associated countries.

  • List of allowed states for USA:
    • AA: "Armed Forces America",
    • AE: "Armed Forces",
    • AP: "Armed Forces Pacific",
    • AK: "Alaska",
    • AL: "Alabama",
    • AR: "Arkansas",
    • AZ: "Arizona",
    • CA: "California",
    • CO: "Colorado",
    • CT: "Connecticut",
    • DC: Washington DC",
    • DE: "Delaware",
    • FL: "Florida",
    • GA: "Georgia",
    • GU: "Guam",
    • HI: "Hawaii",
    • IA: "Iowa",
    • ID: "Idaho",
    • IL: "Illinois",
    • IN: "Indiana",
    • KS: "Kansas",
    • KY: "Kentucky",
    • LA: "Louisiana",
    • MA: "Massachusetts",
    • MD: "Maryland",
    • ME: "Maine",
    • MI: "Michigan",
    • MN: "Minnesota",
    • MO: "Missouri",
    • MS: "Mississippi",
    • MT: "Montana",
    • NC: "North Carolina",
    • ND: "North Dakota",
    • NE: "Nebraska",
    • NH: "New Hampshire",
    • NJ: "New Jersey",
    • NM: "New Mexico",
    • NV: "Nevada",
    • NY: "New York",
    • OH: "Ohio",
    • OK: "Oklahoma",
    • OR: "Oregon",
    • PA: "Pennsylvania",
    • PR: "Puerto Rico",
    • RI: "Rhode Island",
    • SC: "South Carolina",
    • SD: "South Dakota",
    • TN: "Tennessee",
    • TX: "Texas",
    • UT: "Utah",
    • VA: "Virginia",
    • VI: "Virgin Islands",
    • VT: "Vermont",
    • WA: "Washington",
    • WI: "Wisconsin",
    • WV: "West Virginia",
    • WY: "Wyoming"
  • List of allowed states for CAN:
    • AB: "Alberta",
    • BC: "British Columbia",
    • MB: "Manitoba",
    • NB: "New Brunswick",
    • NL: "Newfoundland and Labrador",
    • NS: "Nova Scotia",
    • NT: "Northwest Territories",
    • NU: "Nunavut",
    • ON: "Ontario",
    • PE: "Prince Edward Island",
    • QC: "Quebec",
    • SK: "Saskatchewan",
    • YT: "Yukon"
status
string
Enum: "initializing" "active" "alerting" "hold" "terminated"

Company status.
If company status is initializing, only superadmin can change the status value.

street
string [ 0 .. 255 ] characters

Company street

superadminComment
string [ 0 .. 256 ] characters

Free field that only superadmin can use.

supervisionGroupMaxNumber
number [ 0 .. 50 ]
Default: 5

Maximum number of supervision groups a supervisor can belong to

supervisionGroupMaxSize
number [ 0 .. 10000 ]
Default: 1500

Maximum number of users a company can supervise

supervisionGroupMaxUsers
number [ 0 .. 300 ]
Default: 30

Maximum number of users in a supervision group (supervisor included)

supportEmail
string [ 3 .. 255 ] characters /^[a-zA-Z0-9_\+-]+(\.[a-zA-Z0-9_\+-]+)*@[a-zA...

Company support email

  • supportEmail is case sensitive.
  • supportEmail should be provided if company to create is a VAD or a DR
supportUrlFAQ
string [ 0 .. 2000 ] characters

Company support url

teamsPresenceOnRainbowBusyPhone
string
Default: "Busy"
Enum: "DoNotDisturb" "Busy"

teams presence status configured when rainbow user has activated teams synchronisation and is busy

timezone
string

User timezone name
Allowed values: one of the timezone names defined in IANA tz database
Timezone name are composed as follow: Area/Location (ex: Europe/Paris, America/New_York,...)

useDialOutCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use dial out in phone meetings.
Define if a user is allowed to be called by the Rainbow conference bridge.
useDialOutCustomisation can be:

  • enabled: The user can be called by the Rainbow conference bridge.
  • disabled: The user can't be called by the Rainbow conference bridge.
userSelfRegisterAllowedDomains
Array of strings

Allow users with email domain matching one of the values of this array to join the company by self-register process (if userSelfRegisterEnabled is true)

userSelfRegisterEnabled
boolean
Default: true

Allow users with email domain matching 'userSelfRegisterAllowedDomains' to join the company by self-register process

visibility
string
Default: "private"
Enum: "public" "private" "organization" "closed" "isolated" "hotspot"

Company visibility (define if users being in this company can be searched by users being in other companies and if the user can search users being in other companies).

  • public: User can be searched by external users / can search external users. User can invite external users / can be invited by external users
  • private: User can't be searched by external users (even within his organisation) / can search external users. User can invite external users / can be invited by external users
  • organization: User can't be searched by external users / can search external users. User can invite external users / can be invited by external users
  • closed: User can't be searched by external users / can't search external users. User can invite external users / can be invited by external users
  • isolated: User can't be searched by external users / can't search external users. User can't invite external users / can't be invited by external users
  • hotspot: User can be searched by hotspot attached company's users (users from any company if the user belong to the default company) / can't search any users (even in their company) | user can't invite external users / can be invited by hotspot attached company's users (users from any company if the user belong to the default company)
    • currently hotspot visibility can only be set on the default company, and with superadmin role (development of hotspot visibility is partially done, only for default company in the context of RQRAINB-7456)

External users mean public user not being in user's company nor user's organisation nor a company visible by user's company.

Note related to organisation visibility:

  • Under the same organisation, a company can choose the visibility=organisation. That means users belonging to this company are visible for users of foreign companies inside the same organisation.
  • The visibility=organisation is same as visibility=private outside the organisation. That is to say users can't be searched outside the organisation's companies.
visibleBy
Array of strings

If visibility is private or organisation, list of company ids for which visibility is allowed

website
string [ 0 .. 2000 ] characters

Company website url

Responses

Request samples

Content type
application/json
{
  • "adminAllowedUpdateSubscriptionsOps": "all",
  • "adminCanSetCustomData": true,
  • "adminEmail": "string",
  • "adminHasRightToUpdateSubscriptions": true,
  • "adminHasTheRightToEnableDeskphoneFailover": false,
  • "adminServiceNotificationsLevel": "high",
  • "alertNotificationReception": "disabled",
  • "alertNotificationSending": "disabled",
  • "allowCloudPbxRecording": false,
  • "allowDeviceFirmwareSelection": false,
  • "allowPhoneNumbersVisibility": false,
  • "allowTeamsToDesktopSso": true,
  • "allowUsersSelectPublicTheme": true,
  • "allowUsersSelectTheme": true,
  • "allowedProviderIds": [
    ],
  • "autoAcceptUserInvitations": true,
  • "autoAddToUserNetwork": false,
  • "avatarShape": "square",
  • "billingModel": "monthly",
  • "bpApplicantNumber": "string",
  • "bpBusinessModel": "referral",
  • "bpBusinessType": [
    ],
  • "bpCRDid": "string",
  • "bpHasRightForBYOT": true,
  • "bpHasRightToConnect": true,
  • "bpHasRightToSell": true,
  • "bpId": "string",
  • "bpIsContractAccepted": false,
  • "bpType": "IR",
  • "businessData": {
    },
  • "businessSpecific": "UGAP",
  • "catalogId": "string",
  • "city": "string",
  • "cloudPbxRecordingInboundOnly": true,
  • "cloudPbxVoicemailToEmail": "none",
  • "companyCallNumber": "string",
  • "companyContactId": "string",
  • "contentPolicyLifeTime": false,
  • "country": "FRA",
  • "csEmailList": [
    ],
  • "csmEmailList": [
    ],
  • "currency": "USD",
  • "customData": { },
  • "ddiReadOnly": true,
  • "defaultLicenseGroup": "string",
  • "defaultOptionsGroups": [
    ],
  • "delegatedCallPushDisable": false,
  • "description": "string",
  • "disableCCareAdminAccess": true,
  • "disableCCareAdminAccessCustomers": true,
  • "disableCCareAdminAccessResellers": true,
  • "displayIdrFiles": true,
  • "documentGracePeriod": false,
  • "economicActivityClassification": "A",
  • "endOfConferenceBehavior": [
    ],
  • "externalReference": "string",
  • "externalReference2": "string",
  • "giphyEnabled": true,
  • "hideContractInfo": true,
  • "isBP": true,
  • "isCentrex": true,
  • "kamEmailList": [
    ],
  • "mobilePermanentConnectionMode": false,
  • "name": "string",
  • "offerType": "freemium",
  • "postalCode": "string",
  • "preferredSipLoadBalancerId": "string",
  • "salesforceAccountId": "string",
  • "salesforceAccountName": "string",
  • "salesforceAccountOwner": "string",
  • "seEmailList": [
    ],
  • "selectedDeviceFirmware": "released",
  • "selectedTheme": {
    },
  • "selectedThemeCustomers": {
    },
  • "sendPrepaidSubscriptionsNotification": true,
  • "size": "self-employed",
  • "slogan": "string",
  • "state": "null",
  • "status": "initializing",
  • "street": "string",
  • "superadminComment": "string",
  • "supervisionGroupMaxNumber": 5,
  • "supervisionGroupMaxSize": 1500,
  • "supervisionGroupMaxUsers": 30,
  • "supportEmail": "string",
  • "supportUrlFAQ": "string",
  • "teamsPresenceOnRainbowBusyPhone": "Busy",
  • "timezone": "string",
  • "useDialOutCustomisation": "enabled",
  • "userSelfRegisterAllowedDomains": [
    ],
  • "userSelfRegisterEnabled": true,
  • "visibility": "private",
  • "visibleBy": [
    ],
  • "website": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all companies

This API allows administrator to retrieve companies they can administrate.

Users with 'superadmin', 'support', 'customer_success_admin' or 'business_admin' role can retrieve all companies.

Users with admin role (and not having superadmin nor support role) can only retrieve their own company and companies they can manage, i.e.:

  • organisation admins can retrieve all companies being in their organisation,
  • bp admins or bp finance of BP DR or BP IR companies can retrieve their company and all of their EC companies (i.e. all companies for which their company is the BP),
  • bp admins or bp finance of BP VAD companies can retrieve their company, all of their BP IR and EC companies, and all the EC companies linked to their BP IR companies,
  • company admins and site admin can only retrieve their own company.
    Users with sales_analytics role (and not having superadmin nor support role) can only retrieve companies having their loginEmail in company's csEmailList, seEmailList, csmEmailList or kamEmailList fields.
    Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/companies?name=My com&format=small&limit=100&offset=0&sortField=name&sortOrder=-1
Authorizations:
BearerBearer-x-rainbow-api-key
query Parameters
format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less company details in response.

  • small: _id, name
  • medium: id, name, status, adminEmail, companyContactId, isBP, bpType, bpId, country, website, slogan, description, size, economicActivityClassification, creationDate, lastAvatarUpdateDate, lastBannerUpdateDate, avatarShape, visibility
  • full for superadmin, support, business_admin, customer_success_admin, sales_analytics, bp_admin and bp_finance: All fields
  • full for admin: All fields except BP fields (bpType, bpBusinessModel, bpApplicantNumber, bpCRDid, bpHasRightToSell, bpHasRightToConnect, bpHasRightForBYOT, preferredSipLoadBalancerId, bpIsContractAccepted, bpContractAcceptationInfo)
sortField
string
Default: "name"

Sort items list based on the given field

bpId
string

Allows to filter companies list on bpId field.
This filter allow to get all the End Customer companies associated to a given Business Partner company.

Only users with role superadmin, support, business_admin, customer_success_admin, sales_analytics, bp_admin or bp_finance can use this filter.
Users with role bp_admin or bp_finance can use this filter on their own company.

catalogId
string

Allows to filter companies list on catalogId field.
This filter allow to get all the companies linked to a given catalogId.

Only users with role superadmin, support, customer_success_admin, sales_analytics or business_admin can use this filter.

offerId
string

Allows to filter companies list on companies having subscribed to the provided offerId.

offerCanBeSold
boolean

Allows to filter companies list on companies having subscribed to offers with canBeSold=true.
This filter can only be used with the value true (false is not relevant, as all companies have a subscription to Essential which has canBeSold=false, so all companies would match offerCanBeSold=false).

externalReference
string

Allows to filter companies list on externalReference field.
The search is done on externalReference starting with the input characters, case sensitive (ex: ABC will match companies with externalReference ABC, ABCD, ABC12... ; but externalReference abc, AABC, 1ABC, ... will not match).

Only users with role superadmin, support, business_admin, customer_success_admin, sales_analytics, bp_admin or bp_finance can use this filter.

externalReference2
string

Allows to filter companies list on externalReference2 field.
The search is done on externalReference2 starting with the input characters, case sensitive (ex: ABC will match companies with externalReference2 ABC, ABCD, ABC12... ; but externalReference2 abc, AABC, 1ABC, ... will not match).

Only users with role superadmin, support, business_admin, customer_success_admin, sales_analytics, bp_admin or bp_finance can use this filter.

salesforceAccountId
string

Allows to filter companies list on salesforceAccountId field.
The search is done on the whole salesforceAccountId, case sensitive (no partial search).

Only users with role superadmin, support, business_admin, customer_success_admin, sales_analytics, bp_admin or bp_finance can use this filter.

selectedAppCustomisationTemplate
string

Allows to filter companies list on application customisation template applied for the company.
This filter allows to get a list of companies for which we have applied the same application customisation template.

Only users with role superadmin, support, bp_admin, admin can use this filter.

selectedThemeObj
boolean

Allows to return selectedTheme attribute as an object:

  • true returns selectedTheme as an object (e.g. { "light": "60104754c8fada2ad4be3e48", "dark": "5ea304e4359c0e6815fc8b57" }),
  • false return selectedTheme as a string.
offerGroupName
string

Allows to filter companies list on companies having subscribed to offers with provided groupName(s).
Only users with role superadmin, support, business_admin, customer_success_admin, sales_analytics, bp_admin or bp_finance can use this filter.
groupName can be retrieved from API GET /api/rainbow/subscription/v1.0/companies/:companyId/offers
The search is done on the whole groupName(s), case sensitive (no partial search).
Several groupName can be provided, seperated by a space.

bpBusinessType
string

Allows to filter companies list on bpBusinessType.
Only users with role superadmin, support, business_admin, customer_success_admin, sales_analytics, bp_admin or bp_finance can use this filter.
Several bpBusinessType can be provided, seperated by a space.

businessSpecific
string

Allows to filter companies list on businessSpecific.
Several businessSpecific can be provided, seperated by a space.

salesEmail
string

Allows to filter companies list on salesEmail
The given email address must be included either in csEmailList, seEmailList, csmEmailList or kamEmailList.

businessRegion
string

Allows to filter companies list on region of business location
Only users with role superadmin, support, business_admin can use this filter.
Several businessRegion can be provided, seperated by a pipe (|).

businessCluster
string

Allows to filter companies list on cluster of business location
Only users with role superadmin, support, business_admincan use this filter.
Several businessCluster can be provided, seperated by a pipe (|).

businessArea
string

Allows to filter companies list on area of business location
Only users with role superadmin, support, business_admin can use this filter.
Several businessArea can be provided, seperated by a pipe (|).

businessCountry
string

Allows to filter companies list on country of business location
Only users with role superadmin, support, business_admin can use this filter.
Several businessCountry can be provided, seperated by a pipe (|).

isEdge
boolean

Allows to return Edge companies. If not provided, Edge companies are not returned.

limit
number [ 0 .. 1000 ]
Default: 100

Allow to specify the number of items to retrieve.

offset
number
Default: 0

Allow to specify the position of first item to retrieve (first item if not specified). Warning: if offset > total, no results are returned.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting items list.

name
string

Allows to filter companies list on the given keyword(s) on field name.

The filtering is case insensitive and on partial name match: all companies containing the provided name value will be returned (whatever the position of the match).
Ex: if filtering is done on comp, companies with the following names are match the filter 'My company', 'Company', 'A comp 1', 'Comp of comps', ...

status
string
Enum: "initializing" "active" "alerting" "hold" "terminated"

Allows to filter companies list on the provided status(es)

visibility
string
Enum: "public" "private" "organization" "closed" "isolated"

Allows to filter companies list on the provided visibility(ies)

organisationId
string

Allows to filter companies list on the organisationIds provided in this option.

This filter can only be used if user has role(s) superadmin, support, bp_admin or admin

isBP
boolean

Allows to filter companies list on isBP field:

  • true returns only Business Partner companies,
  • false return only companies which are not Business Partner.

This filter can only be used if user has role(s) superadmin, business_admin,customer_success_admin, support, bp_admin or admin.

hasBP
boolean

Allows to filter companies list on companies being linked or not to a BP:

  • true returns only companies linked to a BP (BP IR companies are also returned),
  • false return only companies which are not linked to a BP.

This filter can only be used if user has role(s) superadmin, business_admin,customer_success_admin, support or bp_admin.

Users with role bp_admin can only use this filter with value false.

bpType
string

Allows to filter companies list on bpType field.

This filter allow to get all the Business Partner companies from a given bpType.

Only users with role superadmin, business_admin,customer_success_admin, support or bp_admin can use this filter.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": 2,
  • "limit": 100,
  • "offset": 0
}

Create a company

Only superadmin, BP admin, BP finance and organisation admin can create companies with this API.

Companies created by a bp_admin or a bp_finance (without organisation admin role) are automatically attached to his BP company (bpId set to BP company). They are created with the status initializing.
Companies created by a bp_admin or a bp_finance having also organisation admin role can be either be created in their organisation (default) or under a BP they manage in their organization (if they provide a bpId). to his BP company (bpId set to BP company). They are created with the status initializing.

  • If BP company has bpType equal to VAD, the field isBp can be set to true or false: In that case, the created company will be a BP with bpType Indirect Reseller:
    • If the field isBp is set to true, the company is created with isBP = true, bpType = 'IR', bpBusinessModel = 'resell' and bpHasRightToConnect = true (it will be a BP Indirect Reseller company linked to this BP VAD company, this BP IR company will be able to have his own EC companies attached to it)
    • If the field isBp is set to false (or not defined), the company is created with bpId = BP companyId (it will be an End Customer company directly attached to this BP VAD company)
    • The status of the company will be updated to active once the first invited bp_admin / bp_finance (invited using join company invitation with flag invitedToBeBpAdmin set to true) will join this company.
  • If BP company has bpType equal to DR or IR, the created company will be an End Customer company:
    • The company is created with bpId = BP companyId
    • The status of the company will be updated to active once the first invited company_admin (invited using join company invitation with flag invitedToBeCompanyAdmin set to true) will join this company.

Companies created by a Organisation admin are automatically attached to his organisation.

Users being in Default company can create their own company using API enduser/PostCompanies POST /api/rainbow/enduser/v1.0/companies

When a company is created, a subscription to the Default offer is assigned to this company. All users of this company will be assigned to this default subscription when they are created or when they arrive in the company.

Specific feature: Sharing a system between several companies
Configuring companies sharing a multi-tenant system is possible.
An OXE can be multi-company.
A multi-tenant system, so called CENTREX, allows sharing a call-server between several entities. For us an entity is a company with the flag isCentrex=true.
A Company can't change the CENTREX status, when some sites are already created for it.

Rainbow application customisation Activate/Deactivate some locks per company, per user
It's possible to forbid a feature for all users of a company. Even if a feature is offered by a Rainbow profile, companies may want to prohibit it for all its employees unless there is an exception.
Following keys are manageable via customisation templates to apply either to a company or a user.
See POST /api/rainbow/admin/v1.0/customisations/templates/apply

  • fileSharingCustomisation - Activate/Deactivate file sharing capability per company, per user

  • userTitleNameCustomisation - Activate/Deactivate the capability for a user to modify a part of his profile (title, firstName, lastName)

  • softphoneOnlyCustomisation - Activate/Deactivate the capability for an UCaas application not to offer all Rainbow services but to focus to telephony services

  • useRoomCustomisation - Activate/Deactivate the capability for a user to use bubbles.

  • phoneMeetingCustomisation - Activate/Deactivate the capability for a user to use phone meetings (PSTN conference).

  • useChannelCustomisation - Activate/Deactivate the capability for a user to use a channel.

  • useScreenSharingCustomisation - Activate/Deactivate the capability for a user to share a screen.

  • useWebRTCVideoCustomisation - Activate/Deactivate the capability for a user to switch to a Web RTC video conversation.

  • useWebRTCAudioCustomisation - Activate/Deactivate the capability for a user to switch to a Web RTC audio conversation.

  • instantMessagesCustomisation - Activate/Deactivate the capability for a user to use and receive instant messages.

  • userProfileCustomisation - Activate/Deactivate the capability for a user to modify globally his profile and not only (title, firstName, lastName).

  • fileStorageCustomisation - Activate/Deactivate the capability for a user to access to the Rainbow file storage.

  • overridePresenceCustomisation - Activate/Deactivate the capability for a user to change manually his presence status.

  • changeTelephonyCustomisation - Activate/Deactivate the ability for a user to modify telephony settings like forward activation...

  • changeSettingsCustomisation - Activate/Deactivate the ability for a user to change all client general settings.

  • recordingConversationCustomisation - Activate/Deactivate the capability for a user to record a conversation.

  • useGifCustomisation - Activate/Deactivate the ability for a user to Use GIFs in conversations.

  • fileCopyCustomisation - Activate/Deactivate the capability for a user to copy any file he receives in his personal cloud space.

  • fileTransferCustomisation - Activate/Deactivate the capability for a user to copy a file from a conversation then share it inside another conversation.

  • forbidFileOwnerChangeCustomisation - Activate/Deactivate the ability for a user to loose the ownership on one file.

  • eLearningCustomisation - Activate/Deactivate the ability for a user to participate on an Elearning training.

  • eLearningGamificationCustomisation - Activate/Deactivate the ability for a user to earn badges for Elearning progress.

  • meetingRecordingCustomisation - Activate/Deactivate the ability for a user to record a meeting.

  • useOtherPhoneMode - Activate/Deactivate the ability for a user to be on other phone mode.

  • useComputerMode - Activate/Deactivate the ability for a user to be on computer mode.

  • useSoftPhoneMode - Activate/Force/Deactivate the ability for a user to be on softphone mode.

  • useTeamsMode - Activate/Deactivate the ability for a user to be on Teams mode.

  • imPopupDuration - Defines the IM popup duration.

  • canAccessWhatsNew - Activate/Deactivate the ability for a user to access to what's new.

  • canAccessFaqCustomisation - Activate/Deactivate the ability for a user to access to FAQ.

  • canAccessHelpCenterCustomisation - Activate/Deactivate the ability for a user to access to help center.

  • canAccessStoreCustomisation - Activate/Deactivate the ability for a user to access to Rainbow store.

  • canDownloadAppCustomisation - Activate/Deactivate the ability for a user to download Rainbow application.

  • canUseTestConfigCustomisation - Activate/Deactivate the ability for a user to test the configuration.

  • canUseSendReportCustomisation - Activate/Deactivate the ability for a user to send report feature.

  • canUseTaskCustomisation - Activate/Deactivate the ability for a user to use task.

  • canCallParticipantPbxNumberCustomisation - Select the kind of number with what a user can call a participant.

  • canSetInvisiblePresenceCustomisation - Activate/Deactivate the ability for a user to set invisible presence.

  • receivedFileCustomisation: to restrict the receiving of files and protect from data coming from a foreign user of the company

  • Following keys stay manageable by this API

  • alertNotificationReception - Activate/Deactivate the capability for a user to receive alert notification.

  • alertNotificationSending - Activate/Deactivate the capability for a user to send alert notification.

  • useDialOutCustomisation - Activate/Deactivate the capability for a user to use dial out in phone meetings.

Each featureKey are added to companies and users data.
Each featureKey may get the value 'enabled', 'disabled' in the company data structure.
Each featureKey may get the value 'same_than_company' 'enabled', 'disabled' in the user data structure.

Authorizations:
BearerBearer-x-rainbow-api-key
query Parameters
selectedThemeObj
boolean

Allows to return selectedTheme attribute as an object:

  • true returns selectedTheme as an object (e.g. { "light": "60104754c8fada2ad4be3e48", "dark": "5ea304e4359c0e6815fc8b57" }),
  • false return selectedTheme as a string.
Request Body schema: application/json
adminAllowedUpdateSubscriptionsOps
string
Enum: "all" "increase_only" "monthly"

In the case the company is linked to a Business Partner company and adminHasRightToUpdateSubscriptions is enabled, indicates the update operations for which the bp_finance allows the company_admin to perform on the subscriptions of his company.
Can only be set by superadmin or bp_finance of the related company.
Possible values:

  • `all: company_admin is allowed to perform all update operations on the subscriptions of his company
  • increase_only: company_admin is only allowed to increasemaxNumberUsers` on the subscriptions of his company (decrease is forbidden)
  • 'monthly': company_admin is only allowed to manage monthly subscription (increase and decrease)
adminCanSetCustomData
boolean

Whether or not administrators can set customData field for their own company.
adminCanSetCustomData can only be set:

  • by superadmin (all companies),
  • by bp_admin or bp_finance for the companies he manages,
  • by organization_admin for the companies he manages.
adminEmail
string [ 3 .. 255 ] characters /^[a-zA-Z0-9_\+-]+(\.[a-zA-Z0-9_\+-]+)*@[a-zA...

Company contact person email
adminEmail is case sentive.

adminHasRightToUpdateSubscriptions
boolean

In the case the company is linked to a Business Partner company, indicates if the bp_finance allows the company_admin to update the subscriptions of his company (if enable, allowed operations depend of the value of adminAllowedUpdateSubscriptionsOps).
Can only be set by superadmin or bp_finance of the related company.

adminHasTheRightToEnableDeskphoneFailover
boolean
Default: false

Superadmin allows admins of the company to select a given deskphone failover configuration for its cloudpbx devices.

adminServiceNotificationsLevel
string
Enum: "high" "medium" "low"

Level of service notification that admin should see

alertNotificationReception
string
Default: "disabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to receive alert notification.
Define if a user has the right to receive alert notification
alertNotificationReception can be:

  • enabled: Each user of the company can receive alert notification.
  • disabled: No user of the company can receive alert notification.
alertNotificationSending
string
Default: "disabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to send alert notification.
Define if a user has the right to send alert notification
alertNotificationSending can be:

  • enabled: Each user of the company can send alert notification.
  • disabled: No user of the company can send alert notification.
allowDeviceFirmwareSelection
boolean
Default: false

Superadmin allows admins of the company to select a given firmware for its cloudpbx devices.

allowTeamsToDesktopSso
boolean
Default: true

Superadmin allows if Teams add-in uses sso to login in desktop app for all company users

allowUsersSelectPublicTheme
boolean
Default: true

Allow users of this company to select a public theme.

allowUsersSelectTheme
boolean
Default: true

Allow users of this company to select a theme among the ones available (owned or visible by the company).

allowedProviderIds
Array of strings

A list of Provider Id that can be used company users to send sms. Only superddmin and bp_admin can set this field.

autoAcceptUserInvitations
boolean
Default: true

Allow to enable or disable the auto-acceptation of user invitations between users of this company (default true: enabled)

autoAddToUserNetwork
boolean
Default: false

Allow to enable or disable the auto addition to user's network between users of this company (default false: disabled)

avatarShape
string
Enum: "square" "circle"

Company's avatar customization

billingModel
string
Enum: "monthly" "prepaid_1y" "prepaid_3y" "prepaid_5y"

Billing model that can be subscribed for this company.

bpApplicantNumber
string [ 0 .. 255 ] characters

Reference of the Business Partner in ALE Finance tools (SAP)
Only applicable if isBP is true and bpType is DR or VAD.
Only settable by superadmin.

bpBusinessModel
string
Enum: "referral" "resell"

Indicates BP business model
Only applicable if isBP is true.
Only settable by superadmin.

bpBusinessType
Array of strings
Items Enum: "voice_by_partner" "voice_by_ale" "conference" "default"

Business type(s) that can be sold by a BP.

bpCRDid
string [ 0 .. 255 ] characters

Reference of the Business Partner in CDR
Only applicable if isBP is true and bpType is DR or VAD.
If bpCRDid is not defined, BP won't be able to sell (i.e. bpHasRightToSell can't be set to true)
Only settable by superadmin.

bpHasRightForBYOT
boolean

When True, the BP can create a SIP Hybrid Trunk for its managed companies (means that Bring Your Own Trunk feature is available for the BP). So when False, the "hybrid trunk" tab should be removed from the admin GUI
Only applicable if isBP is true.
Only settable by superadmin.

bpHasRightToConnect
boolean

When True [Default], the BP can connect CPE equipment of managed companies. So when False, the "equipment" tab should be removed from the admin GUI
Only applicable if isBP is true.
Only settable by superadmin.

bpHasRightToSell
boolean

Indicates if the Business has the right to sell
Only applicable if isBP is true and bpType is DR or VAD.
Only applicable if bpCRDid is defined.
Only settable by superadmin.

bpId
string

Link the company to the corresponding Business partner company.
bpId must correspond to a valid company having isBP equal to true.
Only directly settable by superadmin.
If the company is created by a bp_admin or a bp_finance, bpId is automatically set to BP company id.
For existing companies, bp_admin must use invitation mechanism to a company admin in order to request a link of this company company to his BP company.

bpIsContractAccepted
boolean
Default: false

Indicates if the Business has accepted the contract and can sell Rainbow offers
Should be set by bp_admin or bp_finance.
Only applicable if isBP is true.

bpType
string
Enum: "IR" "VAD" "DR"

Indicates BP Company type

  • IR: Indirect Reseller,
  • VAD: Value Added Distributor,
  • DR: Direct Reseller.
    Only applicable if isBP is true.
    Only settable by superadmin.
object

Set the business data of the company. Only settable by superadmin or business_admin.
Only settable by users with superadmin or business_admin role(s).

businessSpecific
string
Value: "UGAP"

Allow to specify if company has access to specific offers. Only settable by superadmin or business_admin.

catalogId
string

Id of the catalog of Rainbow offers to which the company is linked. The catalog corresponds to the list of offers the company can subscribe.
When a new company is created, if no catalogId is specified the company is automatically linked to the default catalog.
When a bp_admin> or bp_finance> creates a company, catalogId of this new company is automatically set to BP company's catalogId.
When an organization_admin> creates a company, catalogId of this new company is automatically set to organization_admin's company's catalogId.

Only superadmin can set a different catalogId to a company.

city
string [ 0 .. 255 ] characters

Company street

cloudPbxVoicemailToEmail
string
Default: "none"
Enum: "none" "simple" "complete"

Cloudpbx email notification type when receiving a voicemail

companyCallNumber
string

If isCentrex = true, this is the company access number [multi-company call + company Area, ex: 8 210, 8 211]

companyContactId
string

User Id of a Rainbow user which is the contact for this company

contentPolicyLifeTime
boolean
Default: false

When different from -1 it activates content removal for all user of this companies with a content lifetime equals to contentPolicyLifeTime in minutes

country
string 3 characters
Default: "FRA"

Company country (ISO 3166-1 alpha3 format)

The list of allowed countries can be obtained using the API GET /api/rainbow/enduser/v1.0/countries

The country value which is provided at company creation is used to determine the location (data-center) where all the data related to this company will be stored. The data-center closest to the company's country is used.

⚠ Warning: the location of the company's data can't be changed after the company creation. The country value can be updated, but the data will remain in the data-center selected during the company creation.

Once the company is created, the location where the data are stored is indicated in the field dataLocation returned by the API GET /api/rainbow/admin/v1.0/companies/:companyId.

If no country is provided, the default value is "FRA", meaning that the company data are stored in French data-center.

csEmailList
Array of strings

A list of Customer Success e-mail addresses (maximum length : 10)

csmEmailList
Array of strings

A list of Channel Sales Manager e-mail addresses (maximum length : 10)

currency
string 3 characters
Enum: "USD" "EUR" "CNY"

Company currency, for payment of premium offers (ISO 4217 format)
For now, only USD, EUR and CNY are supported
Only settable by superadmin

customData
object

Company's custom data.
Object with free keys/values.
It is up to the client to manage the company's customData (new customData provided overwrite the existing one).

Restrictions on customData Object:

  • max 10 keys,
  • max key length: 64 characters,
  • max value length: 512 characters.


Company customData can only be created/updated by:
  • `superadmin` (all companies),
  • `bp_admin` or `bp_finance` for the companies he manages (except his company if its `adminCanSetCustomData` setting is not set to true),
  • `organization_admin` for the companies he manages,
  • `company_admin` for his own company if its `adminCanSetCustomData` setting is set to true (setting that can only be set by a superadmin, his bp_admin, bp_finance or organization_admin) or if he has the feature `ADMIN_CAN_SET_CUSTOM_DATA` (if the feature is enabled, it overwrites the value of the company setting).
ddiReadOnly
boolean

Indicates if admin of IR company is allowed to create or delete a DDI. Used only on IR companies.
This parameter can only be set by VAD bp_admin or superadmin.

defaultLicenseGroup
string

Group of license to assign to user when finalizing his account. Should be one of offers' groupName (e.g. Enterprise, Business ...)

defaultOptionsGroups
Array of strings

List of options to assign to user when finalizing his account. Should be one of offers' groupName (e.g. Alert ...)

delegatedCallPushDisable
boolean
Default: false

This setting allows to avoid disabling telephony events on manager when call delegation is enabled in manager_assistant supervision group belonging to this company.
This setting can only be set by a user with role superadmin.
This setting is optional: when it is not present, it is considered as having his default value (false): when a manager enables call delegation he will no longer receive telephony events on his mobile devices.

description
string [ 0 .. 2000 ] characters

A free string that describes the company (2000 char length)

disableCCareAdminAccess
boolean

When True, disables the access to the customer care logs for admins of this company.
Note that if disableCCareAdminAccessCustomers is enabled on its BP company or disableCCareAdminAccessResellers is enabled on its BP VAD company, this setting is forced to true.
disableCCareAdminAccess can only be set:

  • by superadmin (all companies),
  • by bp_admin or bp_finance for the companies he manages,
  • by organization_admin for the BP companies he manages.
  • by organization_admin for the companies he manages.
disableCCareAdminAccessCustomers
boolean

When True, disables the access to the customer care logs for admins of all the customers company.
This setting is only applicable for BP companies (isBP=true)

  • If the BP company is a DR or an IR, enabling this setting disables the access to the customer care logs for the admins of all its customers companies.
  • If the BP company is a VAD, enabling this setting disables the access to the customer care logs for all the admins of its customers companies.
    Note that the bp_admins/admins of all the BP IRs companies linked to this VAD still have access to the customer care logs (the setting disableCCareAdminAccessResellers on the BP VAD company allows to disable it).
    disableCCareAdminAccessCustomers can only be set:
    • by superadmin (all BP companies),
    • by bp_admin or bp_finance of a BP VAD company for the BP companies he manages,
    • by organization_admin for the BP companies he manages,
    • by company_admin for the BP company he manages.
disableCCareAdminAccessResellers
boolean

When True, disables the access to the customer care logs for admins of all the BP IRs companies linked to the BP VAD and their customers company.
This setting is only applicable for BP VAD companies (isBP=true and bpType=VAD)
Enabling this setting disables on the BP VAD company disables the access to the customer care logs for the bp_admins/admins of all the BP IRs linked to this VAD, and to all the admins of their customers.
Note that the admins of all the customer companies directly linked to this VAD still have access to the customer care logs (the setting disableCCareAdminAccessCustomers on the BP VAD company allows to disable it).
disableCCareAdminAccessResellers can only be set:

  • by superadmin (all BP VAD companies),
  • by bp_admin or bp_finance of a BP VAD company for the BP companies he manages,
  • by organization_admin for the BP VAD companies he manages,
  • by company_admin for the BP VAD company he manages.
documentGracePeriod
boolean
Default: false

When content removal is active for the organisation it represents the period in minutes where a document is still available event if it's content policy lifetime has expired

economicActivityClassification
string
Enum: "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "M" "N" "O" "P" "Q" "R" "S" "T" "U"
  • A: AGRICULTURE, FORESTRY AND FISHING
  • B: MINING AND QUARRYING
  • C: MANUFACTURING
  • D: ELECTRICITY, GAS, STEAM AND AIR CONDITIONING SUPPLY
  • E: WATER SUPPLY; SEWERAGE, WASTE MANAGEMENT AND REMEDIATION ACTIVITIES
  • F: CONSTRUCTION
  • G: WHOLESALE AND RETAIL TRADE; REPAIR OF MOTOR VEHICLES AND MOTORCYCLES
  • H: TRANSPORTATION AND STORAGE
  • I: ACCOMMODATION AND FOOD SERVICE ACTIVITIES
  • J: INFORMATION AND COMMUNICATION
  • K: FINANCIAL AND INSURANCE ACTIVITIES
  • L: REAL ESTATE ACTIVITIES
  • M: PROFESSIONAL, SCIENTIFIC AND TECHNICAL ACTIVITIES
  • N: ADMINISTRATIVE AND SUPPORT SERVICE ACTIVITIES
  • O: PUBLIC ADMINISTRATION AND DEFENCE; COMPULSORY SOCIAL SECURITY
  • P: EDUCATION
  • Q: HUMAN HEALTH AND SOCIAL WORK ACTIVITIES
  • R: ARTS, ENTERTAINMENT AND RECREATION
  • S: OTHER SERVICE ACTIVITIES
  • T: ACTIVITIES OF HOUSEHOLDS AS EMPLOYERS; UNDIFFERENTIATED GOODS- AND SERVICES-PRODUCING ACTIVITIES OF HOUSEHOLDS FOR OWN USE
  • U: ACTIVITIES OF EXTRATERRITORIAL ORGANISATIONS AND BODIES
Array of objects (postCompaniesEndOfConferenceBehavior)

Behavior settings after the end of conference.

externalReference
string [ 0 .. 64 ] characters

Free field that BP can use to link their Indirect Resellers / End Customers to their IS/IT tools
Only applicable by superadmin or by bp_admin or bp_finance on one of his Indirect Resellers / End Customers companies.
bp_admin or bp_finance of an IR company cannot update this field.

externalReference2
string [ 0 .. 64 ] characters

Free field that BP can use to link their Indirect Resellers / End Customers to their IS/IT tools
Only applicable by superadmin or by bp_admin or bp_finance on one of his Indirect Resellers / End Customers companies.

giphyEnabled
boolean

Whether or not giphy feature is enabled for users belonging to this company (possibility to use animated gifs in conversations)
This field is deprecated. Manage instead useGifCustomisation field!

hideContractInfo
boolean

Superadmin and Business_admin can update this field. If true, the 4 contractual documents for BP are hidden.

isBP
boolean

Indicates if the company is a Business partner company
Only settable by superadmin

isCentrex
boolean

Indicates if the company is one tenant of a multi-tenant call server (OXE - OTEC-S or third_party) (default: false)

isEdge
boolean

Indicates if company is an Edge company.

kamEmailList
Array of strings

A list of Key Account Manager e-mail addresses (maximum length : 10)
These fields can only be set by a superadmin

mobilePermanentConnectionMode
boolean
Default: false

deactivate push mode for mobile devices.
When we can't rely on Internet and Google FCM services to wake-up the app or notify the app, we can fall back to a direct XMPP connection.
For customers using Samsung devices with Google Play services, we must have an option on admin side to set this permanent connection mode, so that mobile apps can rely on this parameter. This option will be applied for the whole company.

name
required
string [ 1 .. 255 ] characters

Company name

offerType
string
Default: "freemium"
Enum: "freemium" "premium"

Company offer type.
Companies with offerType=freemium are not able to subscribe to paid offers, they must be premium to do so.
Companies created with privateDC="HDS" are automatically created with offerType=premium (as a paid subscription to HDS Company offer is automatically done during the company creation.

postalCode
string [ 0 .. 64 ] characters

Company postal code

preferredSipLoadBalancerId
string

Indicates the identifier of the preferred SIP Load Balancer (Rainbow Hub context ; used for HybridTrunks of associated ECs)
Only applicable if isBP is true.
Only settable by superadmin.

privateDC
string

Tag allowing to specify if the company and related data will be created on a given private data center
Supported values are the keys being in privateDCs section of zones.json file.
HDS (HealthCare) privateDC is charged. When creating a company with "privateDC": "HDS", a subscription to the "HDS Company" offer is automatically done. This require that the created company is linked to a BP company which has bpHasRightToSell equal to true and a valid bpApplicantNumber.
Only settable by superadmin, bp_admin or bp_finance.

salesforceAccountId
string [ 0 .. 64 ] characters

Customer's Salesforce reference.
Only settable by users with superadmin or business_admin role(s).

salesforceAccountName
string [ 0 .. 64 ] characters

Customer's Salesforce account name.
Only settable by users with superadmin or business_admin role(s).

salesforceAccountOwner
string [ 0 .. 64 ] characters

Customer's Salesforce account owner.
Only settable by users with superadmin or business_admin role(s).

seEmailList
Array of strings

A list of System Engineer e-mail addresses (maximum length : 10)

selectedDeviceFirmware
string
Default: "released"
Enum: "released" "latest"

Cloudpbx default device firmware

  • released: Default value, device firmware will be the official released one.
  • latest: Device firmware can be a more up to date binary (e.g. early adopters)
    If allowed by superadmin, company admin can then select the kind of firmware for all the users, or only for some of them.
object

Set the selected theme(s) for users of the company.

object

Set the selected theme(s) for customers of this BP company.
This param only applies for BP companies.

sendPrepaidSubscriptionsNotification
boolean

Indicates if company_admin should receive email notification about prepaid subscriptions expiring soon. Used only on end customer companies

size
string
Default: "self-employed"
Enum: "self-employed" "1-10 employees" "11-50 employees" "51-200 employees" "201-500 employees" "501-1000 employees" "1001-5000 employees" "5001-10,000 employees" "10,001+ employees"

An overview of the number of employees

slogan
string [ 0 .. 255 ] characters

A free string corresponding to the slogan of the company

state
string
Enum: "null" "AA" "AE" "AP" "AK" "AL" "AR" "AZ" "CA" "CO" "CT" "DC" "DE" "FL" "GA" "GU" "HI" "IA" "ID" "IL" "IN" "KS" "KY" "LA" "MA" "MD" "ME" "MI" "MN" "MO" "MS" "MT" "NC" "ND" "NE" "NH" "NJ" "NM" "NV" "NY" "OH" "OK" "OR" "PA" "PR" "RI" "SC" "SD" "TN" "TX" "UT" "VA" "VI" "VT" "WA" "WI" "WV" "WY" "AB" "BC" "MB" "NB" "NL" "NS" "NT" "NU" "ON" "PE" "QC" "SK" "YT"

When country is 'USA' or 'CAN', a state must be defined. Else it is not managed.

The list of allowed states can be obtained using the API GET /api/rainbow/enduser/v1.0/countries for the associated countries.

  • List of allowed states for USA:
    • AA: "Armed Forces America",
    • AE: "Armed Forces",
    • AP: "Armed Forces Pacific",
    • AK: "Alaska",
    • AL: "Alabama",
    • AR: "Arkansas",
    • AZ: "Arizona",
    • CA: "California",
    • CO: "Colorado",
    • CT: "Connecticut",
    • DC: Washington DC",
    • DE: "Delaware",
    • FL: "Florida",
    • GA: "Georgia",
    • GU: "Guam",
    • HI: "Hawaii",
    • IA: "Iowa",
    • ID: "Idaho",
    • IL: "Illinois",
    • IN: "Indiana",
    • KS: "Kansas",
    • KY: "Kentucky",
    • LA: "Louisiana",
    • MA: "Massachusetts",
    • MD: "Maryland",
    • ME: "Maine",
    • MI: "Michigan",
    • MN: "Minnesota",
    • MO: "Missouri",
    • MS: "Mississippi",
    • MT: "Montana",
    • NC: "North Carolina",
    • ND: "North Dakota",
    • NE: "Nebraska",
    • NH: "New Hampshire",
    • NJ: "New Jersey",
    • NM: "New Mexico",
    • NV: "Nevada",
    • NY: "New York",
    • OH: "Ohio",
    • OK: "Oklahoma",
    • OR: "Oregon",
    • PA: "Pennsylvania",
    • PR: "Puerto Rico",
    • RI: "Rhode Island",
    • SC: "South Carolina",
    • SD: "South Dakota",
    • TN: "Tennessee",
    • TX: "Texas",
    • UT: "Utah",
    • VA: "Virginia",
    • VI: "Virgin Islands",
    • VT: "Vermont",
    • WA: "Washington",
    • WI: "Wisconsin",
    • WV: "West Virginia",
    • WY: "Wyoming"
  • List of allowed states for CAN:
    • AB: "Alberta",
    • BC: "British Columbia",
    • MB: "Manitoba",
    • NB: "New Brunswick",
    • NL: "Newfoundland and Labrador",
    • NS: "Nova Scotia",
    • NT: "Northwest Territories",
    • NU: "Nunavut",
    • ON: "Ontario",
    • PE: "Prince Edward Island",
    • QC: "Quebec",
    • SK: "Saskatchewan",
    • YT: "Yukon"
status
string
Enum: "initializing" "active" "alerting" "hold" "terminated"

Company status.
Companies created by a bp_admin or a bp_finance are created with the status initializing (if status is provided, it is ignored).
Otherwise, if status is not provided, default value is active.

street
string [ 0 .. 255 ] characters

Company street

superadminComment
string [ 0 .. 256 ] characters

Free field that only superadmin can use.

supportEmail
string [ 3 .. 255 ] characters /^[a-zA-Z0-9_\+-]+(\.[a-zA-Z0-9_\+-]+)*@[a-zA...

Company support email

  • supportEmail is case sensitive.
  • supportEmail should be provided if company to create is a VAD or a DR
supportUrlFAQ
string [ 0 .. 2000 ] characters

Company support url

teamsPresenceOnRainbowBusyPhone
string
Enum: "DoNotDisturb" "Busy"

teams presence status to configure when rainbow user has activated teams synchronisation and is busy

useDialOutCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use dial out in phone meetings.
Define if a user is allowed to be called by the Rainbow conference bridge.
useDialOutCustomisation can be:

  • enabled: The user can be called by the Rainbow conference bridge.
  • disabled: The user can't be called by the Rainbow conference bridge.
userSelfRegisterAllowedDomains
Array of strings

Allow users with email domain matching one of the values of this array to join the company by self-register process (if userSelfRegisterEnabled is true)

userSelfRegisterEnabled
boolean
Default: true

Allow users with email domain matching 'userSelfRegisterAllowedDomains' to join the company by self-register process

visibility
string
Default: "private"
Enum: "public" "private" "organization" "closed" "isolated" "hotspot"

Company visibility (define if users being in this company can be searched by users being in other companies and if the user can search users being in other companies).

  • public: User can be searched by external users / can search external users. User can invite external users / can be invited by external users
  • private: User can't be searched by external users (even within his organisation) / can search external users. User can invite external users / can be invited by external users
  • organization: User can't be searched by external users / can search external users. User can invite external users / can be invited by external users
  • closed: User can't be searched by external users / can't search external users. User can invite external users / can be invited by external users
  • isolated: User can't be searched by external users / can't search external users. User can't invite external users / can't be invited by external users
  • hotspot: User can be searched by hotspot attached company's users (users from any company if the user belong to the default company) / can't search any users (even in their company) | user can't invite external users / can be invited by hotspot attached company's users (users from any company if the user belong to the default company)
    • currently hotspot visibility can only be set on the default company, and with superadmin role (development of hotspot visibility is partially done, only for default company in the context of RQRAINB-7456)

External users mean public user not being in user's company nor user's organisation nor a company visible by user's company.

Note related to organisation visibility:

  • Under the same organisation, a company can choose the visibility=organisation. That means users belonging to this company are visible for users of foreign companies inside the same organisation.
  • The visibility=organisation is same as visibility=private outside the organisation. That is to say users can't be searched outside the organisation's companies.
visibleBy
Array of strings

If visibility is private or organisation, list of company ids for which visibility is allowed

website
string [ 0 .. 2000 ] characters

Company website url

Responses

Request samples

Content type
application/json
{
  • "adminAllowedUpdateSubscriptionsOps": "all",
  • "adminCanSetCustomData": true,
  • "adminEmail": "string",
  • "adminHasRightToUpdateSubscriptions": true,
  • "adminHasTheRightToEnableDeskphoneFailover": false,
  • "adminServiceNotificationsLevel": "high",
  • "alertNotificationReception": "disabled",
  • "alertNotificationSending": "disabled",
  • "allowDeviceFirmwareSelection": false,
  • "allowTeamsToDesktopSso": true,
  • "allowUsersSelectPublicTheme": true,
  • "allowUsersSelectTheme": true,
  • "allowedProviderIds": [
    ],
  • "autoAcceptUserInvitations": true,
  • "autoAddToUserNetwork": false,
  • "avatarShape": "square",
  • "billingModel": "monthly",
  • "bpApplicantNumber": "string",
  • "bpBusinessModel": "referral",
  • "bpBusinessType": [
    ],
  • "bpCRDid": "string",
  • "bpHasRightForBYOT": true,
  • "bpHasRightToConnect": true,
  • "bpHasRightToSell": true,
  • "bpId": "string",
  • "bpIsContractAccepted": false,
  • "bpType": "IR",
  • "businessData": {
    },
  • "businessSpecific": "UGAP",
  • "catalogId": "string",
  • "city": "string",
  • "cloudPbxVoicemailToEmail": "none",
  • "companyCallNumber": "string",
  • "companyContactId": "string",
  • "contentPolicyLifeTime": false,
  • "country": "FRA",
  • "csEmailList": [
    ],
  • "csmEmailList": [
    ],
  • "currency": "USD",
  • "customData": { },
  • "ddiReadOnly": true,
  • "defaultLicenseGroup": "string",
  • "defaultOptionsGroups": [
    ],
  • "delegatedCallPushDisable": false,
  • "description": "string",
  • "disableCCareAdminAccess": true,
  • "disableCCareAdminAccessCustomers": true,
  • "disableCCareAdminAccessResellers": true,
  • "documentGracePeriod": false,
  • "economicActivityClassification": "A",
  • "endOfConferenceBehavior": [
    ],
  • "externalReference": "string",
  • "externalReference2": "string",
  • "giphyEnabled": true,
  • "hideContractInfo": true,
  • "isBP": true,
  • "isCentrex": true,
  • "isEdge": true,
  • "kamEmailList": [
    ],
  • "mobilePermanentConnectionMode": false,
  • "name": "string",
  • "offerType": "freemium",
  • "postalCode": "string",
  • "preferredSipLoadBalancerId": "string",
  • "privateDC": "string",
  • "salesforceAccountId": "string",
  • "salesforceAccountName": "string",
  • "salesforceAccountOwner": "string",
  • "seEmailList": [
    ],
  • "selectedDeviceFirmware": "released",
  • "selectedTheme": {
    },
  • "selectedThemeCustomers": {
    },
  • "sendPrepaidSubscriptionsNotification": true,
  • "size": "self-employed",
  • "slogan": "string",
  • "state": "null",
  • "status": "initializing",
  • "street": "string",
  • "superadminComment": "string",
  • "supportEmail": "string",
  • "supportUrlFAQ": "string",
  • "teamsPresenceOnRainbowBusyPhone": "DoNotDisturb",
  • "useDialOutCustomisation": "enabled",
  • "userSelfRegisterAllowedDomains": [
    ],
  • "userSelfRegisterEnabled": true,
  • "visibility": "private",
  • "visibleBy": [
    ],
  • "website": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get company administrators

This API allows administrators to list users being administrator of a company.

Users with superadmin, support role can list administrators from any company.

Users with bp_admin or bp_finance role can only list administrators for companies being End Customers of their BP company (i.e. all the companies having bpId equal to their companyId).

Users with admin role can only list administrators belonging to companies they can manage. That is to say:

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which list of administrators is requested

query Parameters
format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less user details in response.

  • small: id, loginEmail, firstName, lastName, displayName, companyId, companyName, isTerminated
  • medium: id, loginEmail, firstName, lastName, displayName, jid_im, jid_tel, companyId, companyName, lastUpdateDate, lastAvatarUpdateDate, isTerminated, terminatedStatus, guestMode
  • full: all user fields
limit
number
Default: 100

Allow to specify the number of users to retrieve.

offset
number

Allow to specify the position of first user to retrieve (first user if not specified). Warning: if offset > total, no results are returned.

sortField
string
Default: "displayName"

Sort user list based on the given field.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting user list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": 2,
  • "limit": 100,
  • "offset": 0
}

Get company service description file

This API allows administrators to get service description pdf file uploaded by superadmin

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which service description file is requested

Responses

Response samples

Content type
application/json
{
  • "errorCode": 400,
  • "errorMsg": "Bad Request",
  • "errorDetails": [
    ],
  • "errorDetailsCode": 400000
}

Get company App Customisation Deprecated

See (Company gets a given theme)

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which list of custom elements is requested.

Responses

Response samples

Content type
application/json
{
  • "errorCode": 401,
  • "errorMsg": "Unauthorized",
  • "errorDetails": {
    },
  • "errorDetailsCode": 401523
}

Set company App Customisation Deprecated

See (Company updates a given theme)

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which update of customisation elements is requested.

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get company App feature Customisation

This API allows administrators to list the features customisation elements for the company.

Retrieves the application features customisation elements (e.g. conversation pane, menu pane, services) for the given company.
The list of supported features elements is the following (naming convention given from the desktop):

  • featureConversationPane: Left pane containing conversations.
  • callContact: Button call a contact from conversations pane.
  • searchContact: Search bar in the conversations pane.
  • featureTopPane: Top pane containing the menu.
  • featureServices: Services available for the users.
  • meeting: Allow to create a meeting.
  • uploadFile: Allow user to upload a file.
  • shareFile: Allow user to share file with other user .
  • callHistory: Allow user to have a call history.
  • createBubble: Allow user to create bubble.
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which list of custom feature elements is requested.

Responses

Response samples

Content type
application/json
{
  • "errorCode": 401,
  • "errorMsg": "Unauthorized",
  • "errorDetails": {
    },
  • "errorDetailsCode": 401523
}

Set company App feature Customisation

This API allows administrators to set or update the feature customisation elements for the company.

These elements (e.g. conversation pane, menu pane, services) will then be available to the end user to customise their rainbow application.
See supported element names in above GET request.

The whole object will replace the existing one, if found.
The customisation object has some limitations:

  • Element name can't exceed 50 characters.
  • Element value can't exceed 50 characters.

Example:
  • PUT https://openrainbow.com/api/rainbow/admin/v1.0/companies/5749aa51245015fe0d36e968/app-feature-customisation
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which update of customisation elements is requested.

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get default company data

This API allows to get the default Rainbow company.
Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/companies/default

Authorizations:
BearerBearer-x-rainbow-api-key
query Parameters
format
string
Default: "full"
Enum: "small" "medium" "full"

Allows to retrieve more or less company details in response.

  • small: _id, name
  • medium: id, name, status, adminEmail, companyContactId, isBP, bpType, country, website, slogan, description, size, economicActivityClassification, creationDate, lastAvatarUpdateDate, lastBannerUpdateDate, avatarShape, visibility
  • full for superadmin and support: All fields
  • full for admin: All fields except BP fields (bpType, bpBusinessModel, bpApplicantNumber, bpCRDid, bpHasRightToSell, bpHasRightToConnect, bpHasRightForBYOT, preferredSipLoadBalancerId, bpIsContractAccepted, bpContractAcceptationInfo)
selectedThemeObj
boolean

Allows to return selectedTheme attribute as an object:

  • true returns selectedTheme as an object (e.g. { "light": "60104754c8fada2ad4be3e48", "dark": "5ea304e4359c0e6815fc8b57" }),
  • false return selectedTheme as a string.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a user properties

This API allows administrators to update properties for all company users (that could be categorized by using specific tag) among :

  • isActive
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which service description file is requested

query Parameters
tags
string[]

Tags to categorize a subset of company users for which modification should applied

Request Body schema: application/json
isActive
required
boolean

isActive property of a user to modify

Responses

Request samples

Content type
application/json
{
  • "isActive": true
}

Response samples

Content type
application/json
{
  • "total": 15,
  • "updated": 10
}

Companies Avatar

Delete company's avatar

This API can be used to delete avatar image for a given companyId.

Only a superadmin is allowed to handle avatars for 'Default' and 'Terminated' companies.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which list of administrators is requested

Responses

Response samples

Content type
application/json
{
  • "status": "Avatar successfully deleted for company 56c5c19f94141765119f896c",
  • "data": [ ]
}

Upload company's avatar

This API can be used to upload avatar image for a given companyId

Rules:

  • Avatar file has to be sent directly in http body (no JSon).
  • Only jpeg, jpg and png files are supported. Appropriate content-type has to be set (image/jpeg or image/png).
  • If company already has an avatar, the existing one is overwritten.
  • By default, avatar file size is limited to 4194304 bytes (4 MB) (this limit can be changed by integration team in admin portal config file).
  • When an avatar is uploaded, the field lastAvatarUpdateDate of the company is updated to the current date.

Only a superadmin is allowed to handle avatars for 'Default' and 'Terminated' companies.

To get the company's avatar, use the API GET /api/avatar/:entityId.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which list of administrators is requested

Request Body schema:
image/jpeg
image/jpeg
image/png
string <binary> (adminCompaniesPostAvatar)

File to be sent

Responses

Response samples

Content type
application/json
{
  • "status": "Avatar successfully set for company 56c5c19f94141765119f896c",
  • "data": [ ]
}

Companies Banner

Delete company's banner

This API can be used to delete avatar image for a given companyId.

Only a superadmin is allowed to handle avatars for 'Default' and 'Terminated' companies.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which list of administrators is requested

Responses

Response samples

Content type
application/json
{
  • "status": "Banner successfully deleted for company 56c5c19f94141765119f896c",
  • "data": [ ]
}

Upload company's banner

This API can be used to upload banner image for a given companyId

Rules:

  • Banner file has to be sent directly in http body (no JSon).
  • Only jpeg, jpg and png files are supported. Appropriate content-type has to be set (image/jpeg or image/png).
  • If company already has a banner, the existing one is overwritten.
  • By default, banner file size is limited to 10485760 bytes (10 MB) (this limit can be changed by integration team in admin portal config file).
  • When a banner is uploaded, the field lastBannerUpdateDate of the company is updated to the current date.
Only a superadmin is allowed to handle banner for 'Default' and 'Terminated' companies.
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which list of administrators is requested

Request Body schema:
image/jpeg
image/jpeg
image/png
string <binary> (adminCompaniesPostBanner)

File to be sent

Responses

Response samples

Content type
application/json
{
  • "status": "Banner successfully set for company 56c5c19f94141765119f896c",
  • "data": [ ]
}

Get company's banner

This API can be used to retrieve company's banner in addition to the logo retrieved via /api/avatar/{companyId}.
Example: GET https://openrainbow.com/api/banner/56c5c19f94141765119f896c?size=128

Clients can request banners in a given size by specifying size query string parameter.
Banner file can be resized from 1px to its original resolution:

  • If no size option is requested, banner is returned by default with resolution of 80px.
  • Max requestable size is 2048. If a higher resolution is requested, the default size is returned instead, i.e. 80px.
  • Original banner resolution can't be increased. If uploaded banner size is 128 x 128 px, even is client request banner with size 256, the original avatar file will be returned (128px).
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company for which list of administrators is requested

query Parameters
size
required
number [ 1 .. 512 ]
Default: 80

Specify avatar size in pixels (square size x size)

Responses

Companies Backgrounds

Get company's background

This API can be used to retrieve company's background (logo).
Example: GET https://openrainbow.com/api/backgrounds/625eace8edc658748e53c2d2?size=128

Client can request backgrounds in a given size by specifying size query string parameter.
Background file can be resized from 1px to its original resolution, with a maximum of 2048px:

  • If no size option is requested, background is returned by default with resolution of 80px.
  • Max requestable size is 2048. If a higher resolution is requested, the default size is returned instead, i.e. 80px.
  • Original backgrounds resolution can't be increased. If uploaded background size is 128 x 128 px, even is client request background with size 256, the original background file will be returned (128px).
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
backgroundId
required
string

Background unique identifier(like 625eace8edc658748e53c2ef)

query Parameters
size
required
number [ 1 .. 512 ]
Default: 80

Specify background size in pixels (square size x size)

Responses

Companies Calendars

Delete a calendar

This API allows to delete a Calendar.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
calendarId
required
string

Unique identifier of the Calendar to delete

companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "status": "Calendar 56c5c19f94141765119f896c successfully deleted",
  • "data": [ ]
}

Get a calendar

This API allows to get a calendar for a given company


Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/companies/5cd545b3a07de465fb123456/calendars/5cd545b3a07de465fb185969

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
calendarId
required
string

Unique identifier of the calendar to update

companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a calendar

This API allows to modify settings of a Calendar.
Modification can be done on the following settings of a calendar:

  • Calendar name
  • Calendar office hours:
    • The "openhours" array has 7 elements, one for each day of the week; each element is an array that has one more sub-elements (also arrays) indicating a continuous period (start time, end time).
    This sub-elements should contain two strings with each having the format "HH:MM". If the sub-elements contains only one string with "0" it will be converted to "00:00", "23:59" (24h period).
    The first day represents Sunday.
    The timezone used is the one defined for the company on the PABX.
    The exception indicates an specific period in time that will occur only once. Hence the indication of the year, month and the day of the month (mday) along side the periods of when it will be open.
  • Empty array for open hours or exceptions will remove every hours
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
calendarId
required
string

Unique identifier of the calendar to update

companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
name
string

Calendar name

object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "officehours": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all calendars

This API allows to get all the calendars for a given company


Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/companies/5cd545b3a07de465fb123456/calendars?limit=100&offset=0&sortField=name&sortOrder=-1

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
sortField
string
Default: "name"

Sort items list based on the given field

name
string

Filter calendars whose name contain the given filter

limit
number [ 0 .. 1000 ]
Default: 100

Allow to specify the number of items to retrieve.

offset
number
Default: 0

Allow to specify the position of first item to retrieve (first item if not specified). Warning: if offset > total, no results are returned.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting items list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 2
}

Create a company calendar

This API allows to create a new Calendar.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
name
required
string

Calendar name

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a calendar mode

This API allows to modify mode of a Calendar.
Modification will be forwarded to welcome services linked to it if the company have a Cloud PBX:
You can force to open when you're closed (at the time of the action) till the next open periods
Examples:
On Tuesdays the office hours are from 09:00(AM) to 12:30(PM) and from 14:00(PM) to 17:00(PM)
It's 11 o'clock and you have to go, you force the opening --> error you're already open
you force the closing --> will be closed from 11:00(AM) to 12:30(PM)

It's 12:31(PM), you force the closing --> error you're already closed
you force the opening --> will be open from 12:31(PM) to 14:00(PM)

It's 17:01(PM), you force the closing --> error you're already closed
you force the opening --> will be open from 17:01(PM) to the first Wenesday's open period
If mode is open and endDate is null --> always open, no open period found.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
calendarId
required
string

Unique identifier of the calendar to update

companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
mode
required
string
Enum: "open" "closed" "default"

Force open if closed, or closed if open or default to go back to pre configured office hours

Responses

Response samples

Content type
application/json
application/json
text/xml
{
  • "data": [
    ]
}

Companies Custom Data

Manage custom data Deprecated

This API is still working, but customData management can now be done directly at company creation (using API POST /api/rainbow/admin/v1.0/companies or with a company update (using API PUT /api/rainbow/admin/v1.0/companies/:companyId.

customData can only be updated:

  • by superadmin (all companies),
  • by bp_admin or bp_finance for the companies he manages (except his company if its adminCanSetCustomData setting is not set to true),
  • by organization_admin for the companies he manages,
  • by company_admin for his own company if its adminCanSetCustomData setting is set to true (setting that can only be set by a superadmin, his bp_admin, bp_finance or organization_admin) or if he has the feature ADMIN_CAN_SET_CUSTOM_DATA (if the feature is enabled, it overwrites the value of the company setting).
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
customData
required
object

Company's custom data.
Object with free keys/values.
It is up to the client to manage the company's customData (new customData provided overwrite the existing one).

Restrictions on customData Object:

  • max 10 keys,
  • max key length: 64 characters,
  • max value length: 512 characters.


Company customData can only be created/updated by:
  • `superadmin` (all companies),
  • `bp_admin` or `bp_finance` for the companies he manages (except his company if its `adminCanSetCustomData` setting is not set to true),
  • `organization_admin` for the companies he manages,
  • `company_admin` for his own company if its `adminCanSetCustomData` setting is set to true (setting that can only be set by a superadmin, his bp_admin, bp_finance or organization_admin).

Responses

Request samples

Content type
application/json
{
  • "customData": { }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Companies Cloudpbx Groups

Get all cloud PBX groups

This API allows to get all the groups of a Cloud PBX for a given company


Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/companies/5cd545b3a07de465fb123456/groups?limit=100&offset=0&sortField=name&sortOrder=-1

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
sortField
string
Default: "name"

Sort items list based on the given field

name
string

Filter groups whose name contain the given filter

shortNumber
string

Filter groups whose short phone number contain the given filter

externalNumber
string

Filter groups whose external number contain the given filter

memberId
string

Filter groups containing the given member

type
string

Filter groups according to its type (Can be one of the following values: call_queue, hunting_group, manager_assistant or a comma seperated list of these values)

siteId
string

Allows to filter users list on the siteIds provided in this option.

limit
number [ 0 .. 1000 ]
Default: 100

Allow to specify the number of items to retrieve.

offset
number
Default: 0

Allow to specify the position of first item to retrieve (first item if not specified). Warning: if offset > total, no results are returned.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting items list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 3
}

Get a cloud PBX group

This API allows to get data of a Cloud PBX group

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
groupId
required
string

Unique identifier of the Cloud PBX group to retrieve

companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Companies Event Providers

Companies Sites

Get all sites linked with this company

This API allows administrator to retrieve sites linked to a given company

superadmin and support get sites linked to all companies existing in Rainbow.
bp_admin or bp_finance only get sites linked to End Customer companies for which their bp_admin's company is the BP company.
organization_admin only get sites linked to companies under their organization.
company_admin only get sites linked to their company.
site_admin is not allowed to use this API.

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/companies/5749aa51245015fe0d36e968/sites?format=full

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less site details in response.
- small: _id, name
- medium: _id, name, status, companyId
- full: all site fields

limit
number
Default: 100

Allow to specify the number of companies to retrieve.

offset
number

Allow to specify the position of first site to retrieve (first site if not specified). Warning: if offset > total, no results are returned.

sortField
string
Default: "name"

Sort site list based on the given field.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting site list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": 2,
  • "limit": 100,
  • "offset": 0
}

Customisation Template

Apply a templates to a company or a user

This API allows an administrator to apply an application customisation template to a company or a user

Why is an application template?

  • An application template is a set of key feature controlled by permission.
  • A template can be applied to a company, to a user.
  • A template to a user can be applied by an administrator action or by bulk using mass provisioning mechanism.
  • Custom templates may be created

Who can apply a template?

  • superadmin, bp_admin and company_admin can apply templates available for any company (public or private template)

Restrictions about template types.

  • Each template has a type:

    • default_company
    • default_user
    • private_default_company
    • other

  • It may have only one template of default_company and default_user type.

  • A default_company or default_user template is always public.

  • default_company is created by Rainbow team under name Full.

  • default_user is a template used to reset user with default values. It is created by Rainbow team under name Same as company. It is public too.

  • An 'other' template is public or private. If private, it belongs to a company.

  • A private_default_company is private and belongs to a standalone company. It may have only one private_default_company per company.

To apply a template, a template name plus a companyId or a userId must be set. When both companyId or userId are set, an error occurs (400000).

You can find on which companies the template has been applied by using the API GET /api/rainbow/admin/v1.0/companies/?selectedAppCustomisationTemplate=:templateId.
The company field selectedAppCustomisationTemplate is the last template applied for this company.

Authorizations:
BearerBearer-x-rainbow-api-key
Request Body schema: application/json
companyId
required
string

Company unique identifier

name
required
string [ 1 .. 64 ] characters

Template name.

userId
required
string

User unique identifier { "name" : "File storage deactivation", "companyId": "5749ab92245015fe0d36e96a" }

Responses

Request samples

Content type
application/json
{
  • "companyId": "string",
  • "name": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "status": "Template 'File storage deactivation' successfully applied to company 5749ab92245015fe0d36e96a",
  • "data": {
    }
}

Create a template

This API allows an administrator to create an application customisation template for the given company.

  • The name of the template must be unique among all of its belonging to the company.

  • The template is always private. So it has automatically private visibility.

  • It can includes following items. When some of them are missing, the default value enabled is used. So the body can include only items to set with the state disabled.

    • instantMessagesCustomisation: to activate or deactivate the capability for a user to use and receive instant messages.
    • useGifCustomisation: to activate or deactivate the ability for a user to Use GIFs in conversations.
    • fileSharingCustomisation: to activate or deactivate file sharing capability per company, per user
    • fileStorageCustomisation: to activate or deactivate the capability for a user to access to the Rainbow file storage.
    • phoneMeetingCustomisation: to activate or deactivate the capability for a user to use phone meetings (PSTN conference).
    • useDialOutCustomisation: to activate or deactivate the capability for a user to use dial out in phone meetings.
    • useChannelCustomisation: to activate or deactivate the capability for a user to use a channel.
    • useRoomCustomisation: to activate or deactivate the capability for a user to use bubbles.
    • useScreenSharingCustomisation: to activate or deactivate the capability for a user to share his screen.
    • useWebRTCAudioCustomisation: to activate or deactivate the capability for a user to switch to a Web RTC audio conversation.
    • useWebRTCOnlyIfMobileLoggedCustomisation to activate or deactivate the capability for a user to receive web RTC call if mobile app is signed in.
    • useWebRTCVideoCustomisation: to activate or deactivate the capability for a user to switch to a Web RTC video conversation.
    • recordingConversationCustomisation: to activate or deactivate the capability for a user to record a conversation.
    • overridePresenceCustomisation: to activate or deactivate the capability for a user to change manually his presence status.
    • userProfileCustomisation: to activate or deactivate the capability for a user to modify globally his profile and not only (title, firstName, lastName).
    • userTitleNameCustomisation: to activate or deactivate the capability for a user to modify a part of his profile (title, firstName, lastName)
    • changeTelephonyCustomisation: to activate or deactivate the ability for a user to modify telephony settings like forward activation....
    • changeSettingsCustomisation: to activate or deactivate the ability for a user to change all client general settings.
    • fileCopyCustomisation: to activate or deactivate the ability for a user to copy any file he receives in his personal cloud space.
    • fileTransferCustomisation: to activate or deactivate the ability for a user to copy a file from a conversation then share it inside another conversation.
    • forbidFileOwnerChangeCustomisation: to activate or deactivate the ability for a user to loose the ownership on one file.
    • readReceiptsCustomisation: to activate or deactivate the ability for a user to allow a sender to check if a chat message is read.
    • useSpeakingTimeStatistics: to activate or deactivate the ability for a user to see speaking time statistics.
    • eLearningCustomisation: to activate or deactivate the ability for a user to participate on an Elearning training.
    • eLearningGamificationCustomisation: to activate or deactivate the ability for a user to earn badges for Elearning progress.
    • meetingRecordingCustomisation: to activate or deactivate the ability for a user to record a meeting.
    • useOtherPhoneMode: to activate or deactivate the ability for a user to be on other phone mode.
    • useComputerMode: to activate or deactivate the ability for a user to be on computer mode.
    • useSoftPhoneMode: to activate, force or deactivate the ability for a user to be on computer mode.
    • useTeamsMode: to activate or deactivate the ability for a user to be on computer mode.
    • canAccessWhatsNew: to activate or deactivate the ability for a user to access to what's new.
    • canAccessFaqCustomisation: to activate or deactivate the ability for a user to access to FAQ.
    • canAccessHelpCenterCustomisation: to activate or deactivate the ability for a user to access to help center.
    • canAccessStoreCustomisation: to activate or deactivate the ability for a user to access to Rainbow store.
    • canDownloadAppCustomisation: to activate or deactivate the ability for a user to download Rainbow application.
    • canUseTestConfigCustomisation: to activate or deactivate the ability for a user to test the configuration.
    • canUseSendReportCustomisation: to activate or deactivate the ability for a user to send report feature.
    • canUseTaskCustomisation: to activate or deactivate the ability for a user to use task.
    • canSetInvisiblePresenceCustomisation: to activate or deactivate the ability for a user to set invisible presence.
    • canCallParticipantPbxNumberCustomisation: to select the kind of call participant PBX number. This item admits the values internal and national too.
    • canSetInvisiblePresenceCustomisation: to disable the capability for users to set their presence to "Invisible"
    • receivedFileCustomisation: to restrict the receiving of files and protect from data coming from a foreign user of the company

  • Some template values can be defined as null. When they're applied , the value inherits from its company value :

    • imPopupDuration: to define the IM popup duration.

  • This API infers the logical value of all items from non-exhaustive information of the administrator and create a consistent custom template, according with latest constraints of Rainbow platform.

  • Some inconsistencies may lead to an error (403628)

    • fileSharingCustomisation can't be enabled when fileStorageCustomisation is disabled
    • fileCopyCustomisation can't be enabled when fileStorageCustomisation is disabled
    • fileTransferCustomisation can't be enabled when fileCopyCustomisation is disabled, as we have to make a copy of the file before sharing it.
    • useWebRTCVideoCustomisation can't be enabled when useWebRTCAudioCustomisation is disabled
    • instantMessagesCustomisation can't be enabled when fileStorageCustomisation is disabled
    • instantMessagesCustomisation can't be enabled when fileSharingCustomisation is disabled
Authorizations:
BearerBearer-x-rainbow-api-key
Request Body schema: application/json
canAccessFaqCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to access to FAQ.
Defines if a user can access to FAQ.
canAccessFaqCustomisation can be:

  • enabled: The user can access to FAQ.
  • disabled: The user can't access to FAQ.
canAccessHelpCenterCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to access to help center.
Defines if a user can access to help center.
canAccessHelpCenterCustomisation can be:

  • enabled: The user can access to help center.
  • disabled: The user can't access to help center.
canAccessStoreCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to access to Rainbow store.
Defines if a user can access to Rainbow store.
canAccessStoreCustomisation can be:

  • enabled: The user can access to Rainbow store.
  • disabled: The user can't access to Rainbow store.
canAccessWhatsNew
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to access to what's new.
Defines if a user can access to what's new.
canAccessWhatsNew can be:

  • enabled: The user can access to what's new.
  • disabled: The user can't access to what's new.
canCallParticipantPbxNumberCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled" "internal" "national"

Select the kind of call participant number.
Defines the kind of call participant number.
canCallParticipantPbxNumberCustomisation can be:

  • enabled: The user can call a participant via all PBX number
  • disabled: The user can't call a participant via any PBX number.
  • internal: The user can call a participant via an internal PBX number.
  • national: The user can call a participant via a national PBX number.
canDownloadAppCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to download Rainbow application.
Defines if a user can download Rainbow application.
canDownloadAppCustomisation can be:

  • enabled: The user can download Rainbow application.
  • disabled: The user can't download Rainbow application.
canSetInvisiblePresenceCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to set invisible presence
Defines if a user can download Rainbow application.
canSetInvisiblePresenceCustomisation can be:

  • enabled: The user can set invisible presence.
  • disabled: The user can't set invisible presence.
canUseSendReportCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use send report feature.
Defines if a user can use send report feature.
canUseSendReportCustomisation can be:

  • enabled: The user can use send report feature.
  • disabled: The user can't send report feature.
canUseTaskCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use task.
Defines if a user can use task.
canUseTaskCustomisation can be:

  • enabled: The user can use task.
  • disabled: The user can't use task.
canUseTestConfigCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to test the configuration.
Defines if a user can test the configuration.
canUseTestConfigCustomisation can be:

  • enabled: The user can test the configuration.
  • disabled: The user can't test the conguration.
changeSettingsCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to change all client general settings.
Define if one or all users of a company has the right to change his client general settings.
changeSettingsCustomisation can be:

  • enabled: The user can change all client general settings.
  • disabled: The user can't change any client general setting.
changeTelephonyCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to modify telephony settings.
Define if one or all users of a company has the right to modify telephony settings like forward activation ....
changeTelephonyCustomisation can be:

  • enabled: The user can modify telephony settings.
  • disabled: The user can't modify telephony settings.
eLearningCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to participate on an Elearning training.
Defines if a user can participate on an eLearning training.
eLearningCustomisation can be:

  • enabled: The user can participate on an eLearning training.
  • disabled: The user can't participate on an eLearning training.
eLearningGamificationCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to earn badges for Elearning progress.
Defines if a user can participate on an eLearning training.
eLearningCustomisation can be:

  • enabled: The user can participate on an eLearning training.
  • disabled: The user can't participate on an eLearning training.
fileCopyCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to copy files
Define if one or all users of a company is allowed to copy any file he receives in his personal cloud space.
fileCopyCustomisation can be:

  • enabled: The user can make a copy of a file to his personal cloud space.
  • disabled: The user can't make a copy of a file to his personal cloud space.
fileSharingCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate file sharing capability per company
Define if one or all users of a company can use the file sharing service then, allowed to download and share file.
fileSharingCustomisation can be:

  • enabled: Each user of the company can use the file sharing service, except when his own capability is set to 'disabled'.
  • disabled: Each user of the company can't use the file sharing service, except when his own capability is set to 'enabled'.
fileStorageCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to access to Rainbow file storage.
Define if one or all users of a company has the right to upload/download/copy or share documents.
fileStorageCustomisation can be:

  • enabled: Each user of the company can manage and share files.
  • disabled: No user of the company can manage and share files.
fileTransferCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to transfer files.
Define if one or all users of a company has the right to copy a file from a conversation then share it inside another conversation.
fileTransferCustomisation can be:

  • enabled: The user can transfer a file doesn't belong to him.
  • disabled: The user can't transfer a file doesn't belong to him.
forbidFileOwnerChangeCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to loose the ownership on one file.
Define if one or all users can drop the ownership of a file to another Rainbow user of the same company
forbidFileOwnerChangeCustomisation can be:

  • enabled: The user can't give the ownership of his file.
  • disabled: The user can give the ownership of his file.
imPopupDuration
number
Default: null

Defines the IM popup duration.

instantMessagesCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use instant messages.
Define if one or all users of a company has the right to use IM, then to start a chat (P2P ou group chat) or receive chat messages and chat notifications.
instantMessagesCustomisation can be:

  • enabled: Each user of the company can use instant messages.
  • disabled: No user of the company can use instant messages.
meetingRecordingCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to record a meeting.
Defines if a user can record a meeting.
meetingRecordingCustomisation can be:

  • enabled: The user can record a meeting.
  • disabled: The user can't record a meeting.
name
required
string [ 1 .. 64 ] characters

Template name.

overridePresenceCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to change manually his presence.
Define if one or all users of a company has the right to change his presence manually or only use automatic states.
overridePresenceCustomisation can be:

  • enabled: Each user of the company can change his presence.
  • disabled: No user of the company can change his presence.
ownedByCompany
required
string

Identifier of the company owning the template.

phoneMeetingCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use phone meetings (PSTN conference).
Define if one or all users of a company has the right to join phone meetings.
phoneMeetingCustomisation can be:

  • enabled: Each user of the company can join phone meetings.
  • disabled: No user of the company can join phone meetings.
readReceiptsCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to allow a sender to check if a chat message is read.
Defines whether a peer user in a conversation allows the sender of a chat message to see if this IM is acknowledged by the peer.
readReceiptsCustomisation can be:

  • enabled: The user allow the sender to check if an IM is read.
  • disabled: The user doesn't allow the sender to check if an IM is read.
receivedFileCustomisation
string
Default: "enabled"
Enum: "enabled" "internalOnly" "disabled"

Restrict data received.
Restrict the receiving of files to protect from data coming from a foreign user of the company.
receivedFileCustomisation can be:

  • enabled: The user can receive files without restrictions
  • internalOnly: User can receive files only within internal company communications
  • disable: The user can’t receive files under any circumstances. Best for users or roles where no file exchange is necessary or allowed. This ensures maximum protection against unauthorized or potentially harmful file transfers.
recordingConversationCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to record a conversation.
Define if one or all users of a company has the right to record a conversation (for P2P and multi-party calls).
recordingConversationCustomisation can be:

  • enabled: The user can record a peer to peer or a multi-party call.
  • disabled: The user can't record a peer to peer or a multi-party call.
useChannelCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use a channel.
Define if one or all users of a company has the right to create channels or be a member of channels.
useChannelCustomisation can be:

  • enabled: Each user of the company can use some channels.
  • disabled: No user of the company can use some channel.
useComputerMode
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to be on computer mode.
Defines if a user can be on computer mode.
useComputerMode can be:

  • enabled: The user can be on computer mode.
  • disabled: The user can't be on computer mode.
useDialOutCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use dial out in phone meetings.
Define if one or all users of a company is allowed to be called by the Rainbow conference bridge.
useDialOutCustomisation can be:

  • enabled: The user can be called by the Rainbow conference bridge.
  • disabled: The user can't be called by the Rainbow conference bridge.
useGifCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to Use GIFs in conversations.
Define if one or all users of a company has the is allowed to send animated GIFs in conversations
useGifCustomisation can be:

  • enabled: The user can send animated GIFs in conversations.
  • disabled: The user can't send animated GIFs in conversations.
useOtherPhoneMode
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to be on other phone mode.
Defines if a user can be on other phone mode.
useOtherPhoneMode can be:

  • enabled: The user can be on other phone mode.
  • disabled: The user can't be on other phone mode.
useRoomCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use bubbles.
Define if one or all users of a company can create bubbles or participate in bubbles (chat and web conference).
useRoomCustomisation can be:

  • enabled: Each user of the company can use bubbles.
  • disabled: No user of the company can use bubbles.
useScreenSharingCustomisation
string
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to share a screen.
Define if a user has the right to share his screen.
useScreenSharingCustomisation can be:

  • enabled: Each user of the company can share his screen.
  • disabled: No user of the company can share his screen.
useSoftPhoneMode
string
Default: "enabled"
Enum: "enabled" "disabled" "forced"

Activate/Force/Deactivate the capability for a user to be on softphone mode.
Defines if a user can be on softphone mode.
useSoftPhoneMode can be:

  • enabled: The user can be on softphone mode.
  • forced: The user can use the softphone mode only on Web application.
  • disabled: The user can't be on softphone mode.
useSpeakingTimeStatistics
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to see speaking time statistics.
Defines whether a user has the right to see for a given meeting the speaking time for each attendee of this meeting.
useSpeakingTimeStatistics can be:

  • enabled: The user can use meeting speaking time statistics.
  • disabled: The user can't can use meeting speaking time statistics.
useTeamsMode
string
Default: "disabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to be on Teams mode.
Defines if a user can be on Teams mode.
useTeamsMode can be:

  • enabled: The user can be on Teams mode.
  • disabled: The user can't be on Teams mode.
useWebRTCAudioCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to switch to a Web RTC audio conversation.
Define if one or all users of a company has the right to be joined via audio (WebRTC) and to use Rainbow audio (WebRTC) (start a P2P audio call, start a web conference call).
useWebRTCAudioCustomisation can be:

  • enabled: Each user of the company can switch to a Web RTC audio conversation.
  • disabled: No user of the company can switch to a Web RTC audio conversation.
useWebRTCOnlyIfMobileLoggedCustomisation
string
Default: "disabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to receive web RTC call if mobile app is signed in.
Define if one or all users of a company has the right to be joined via audio (WebRTC) if they have a mobile application signed in.
useWebRTCOnlyIfMobileLoggedCustomisation can be:

  • enabled: Each user of the company can receive a web RTC call if mobile app is signed in.
  • disabled: No user of the company can receive a web RTC call if mobile app is signed in.
useWebRTCVideoCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to switch to a Web RTC video conversation.
Define if one or all users of a company has the right to be joined via video and to use video (start a P2P video call, add video in a P2P call, add video in a web conference call).
useWebRTCVideoCustomisation can be:

  • enabled: Each user of the company can switch to a Web RTC video conversation.
  • disabled: No user of the company can switch to a Web RTC video conversation.
userProfileCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to modify his profile.
Define if one or all users of a company has the right to modify the globality of his profile and not only (title, firstName, lastName).
userProfileCustomisation can be:

  • enabled: Each user of the company can modify his profile.
  • disabled: No user of the company can modify his profile.
userTitleNameCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to modify his profile (title, firstName, lastName) per company
Define if one or all users of a company is allowed to change some profile data.
userTitleNameCustomisation can be:

  • enabled: Each user of the company can change some profile data, except when his own capability is set to 'disabled'.
  • disabled: Each user of the company can't change some profile data, except when his own capability is set to 'enabled'.
visibleBy
Array of strings

When visibility is private, list of companyIds that can access the template (other than the 'ownedByCompany' one).

Responses

Request samples

Content type
application/json
{
  • "canAccessFaqCustomisation": "enabled",
  • "canAccessHelpCenterCustomisation": "enabled",
  • "canAccessStoreCustomisation": "enabled",
  • "canAccessWhatsNew": "enabled",
  • "canCallParticipantPbxNumberCustomisation": "enabled",
  • "canDownloadAppCustomisation": "enabled",
  • "canSetInvisiblePresenceCustomisation": "enabled",
  • "canUseSendReportCustomisation": "enabled",
  • "canUseTaskCustomisation": "enabled",
  • "canUseTestConfigCustomisation": "enabled",
  • "changeSettingsCustomisation": "enabled",
  • "changeTelephonyCustomisation": "enabled",
  • "eLearningCustomisation": "enabled",
  • "eLearningGamificationCustomisation": "enabled",
  • "fileCopyCustomisation": "enabled",
  • "fileSharingCustomisation": "enabled",
  • "fileStorageCustomisation": "enabled",
  • "fileTransferCustomisation": "enabled",
  • "forbidFileOwnerChangeCustomisation": "enabled",
  • "imPopupDuration": null,
  • "instantMessagesCustomisation": "enabled",
  • "meetingRecordingCustomisation": "enabled",
  • "name": "string",
  • "overridePresenceCustomisation": "enabled",
  • "ownedByCompany": "string",
  • "phoneMeetingCustomisation": "enabled",
  • "readReceiptsCustomisation": "enabled",
  • "receivedFileCustomisation": "enabled",
  • "recordingConversationCustomisation": "enabled",
  • "useChannelCustomisation": "enabled",
  • "useComputerMode": "enabled",
  • "useDialOutCustomisation": "enabled",
  • "useGifCustomisation": "enabled",
  • "useOtherPhoneMode": "enabled",
  • "useRoomCustomisation": "enabled",
  • "useScreenSharingCustomisation": "enabled",
  • "useSoftPhoneMode": "enabled",
  • "useSpeakingTimeStatistics": "enabled",
  • "useTeamsMode": "disabled",
  • "useWebRTCAudioCustomisation": "enabled",
  • "useWebRTCOnlyIfMobileLoggedCustomisation": "disabled",
  • "useWebRTCVideoCustomisation": "enabled",
  • "userProfileCustomisation": "enabled",
  • "userTitleNameCustomisation": "enabled",
  • "visibleBy": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all available customisation templates

This API allows administrator to retrieve application customisation templates supported by a given company.

superadmin and support can get templates available for any company (the requested company has to be specified in companyId query parameter). bp_admin and company_admin get templates for its own company (no need to specify companyId parameter).

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/customisations/templates?companyId=5749aa51245015fe0d36e968

Authorizations:
BearerBearer-x-rainbow-api-key
query Parameters
companyId
string

Select a company other than the one the user belongs to (must be an admin of the company)

format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less templates details in response.
- small: id, name, visibility
- medium: id, name, visibility, visibleBy, type, createdBy, creationDate, ownedByCompany
- full: all fields

limit
number
Default: 100

Allow to specify the number of templates to retrieve.

offset
number

Allow to specify the position of first templates to retrieve (first template if not specified). Warning: if offset > total, no results are returned.

sortField
string
Default: "name"

Sort templates list based on the given field.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting templates list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 6
}

Delete a template

This API allows an administrator to delete an application customisation template.

Users with superadmin role can delete any private template.

Users with bp_admin or admin role can only delete template they owned.

The template to delete may have been applied to one or several companies. So, before the template deletion, we have to go back to the application of this template. A default template is applied instead (Full).
This is done automatically and it could be necessary to advice the administrator before deleting the template.

You can find on which companies the template has been applied by using the API GET /api/rainbow/admin/v1.0/companies/?selectedAppCustomisationTemplate=:templateId
The company field selectedAppCustomisationTemplate is the last template applied for this company.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
templateId
required
string

Application customisation templates unique identifier (e.g. 5e53a3ab98fb963c5068f176)

Responses

Response samples

Content type
application/json
{
  • "status": "Template 5d3704dc78ef1b101f69a01f successfully deleted",
  • "data": {
    }
}

Get requested template

This API allows administrator to retrieve the requested application customisation template

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/customisations/templates/5d3704dc78ef1b101f69a01f

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
templateId
required
string

Application customisation templates unique identifier (e.g. 5e53a3ab98fb963c5068f176)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a template

This API allows an administrator to update an application customisation template.

A public template can't be updated using this API. Update is only allowed via a database migration.

Only changing values should be passed in the body.

  • instantMessagesCustomisation: to activate or deactivate the capability for a user to use and receive instant messages.

  • useGifCustomisation: to activate or deactivate the ability for a user to Use GIFs in conversations.

  • fileSharingCustomisation: to activate or deactivate file sharing capability per company, per user

  • fileStorageCustomisation: to activate or deactivate the capability for a user to access to the Rainbow file storage.

  • phoneMeetingCustomisation: to activate or deactivate the capability for a user to use phone meetings (PSTN conference).

  • useDialOutCustomisation: to activate or deactivate the capability for a user to use dial out in phone meetings.

  • useChannelCustomisation: to activate or deactivate the capability for a user to use a channel.

  • useRoomCustomisation: to activate or deactivate the capability for a user to use bubbles.

  • useScreenSharingCustomisation: to activate or deactivate the capability for a user to share his screen.

  • useWebRTCAudioCustomisation: to activate or deactivate the capability for a user to switch to a Web RTC audio conversation.

  • useWebRTCOnlyIfMobileLoggedCustomisation to activate or deactivate the capability for a user to receive web RTC call if mobile app is signed in.

  • useWebRTCVideoCustomisation: to activate or deactivate the capability for a user to switch to a Web RTC video conversation.

  • recordingConversationCustomisation: to activate or deactivate the capability for a user to record a conversation.

  • overridePresenceCustomisation: to activate or deactivate the capability for a user to change manually his presence status.

  • userProfileCustomisation: to activate or deactivate the capability for a user to modify globally his profile and not only (title, firstName, lastName).

  • userTitleNameCustomisation: to activate or deactivate the capability for a user to modify a part of his profile (title, firstName, lastName)

  • changeTelephonyCustomisation: to activate or deactivate the ability for a user to modify telephony settings like forward activation.

  • changeSettingsCustomisation: to activate or deactivate the ability for a user to change all client general settings.

  • fileCopyCustomisation: to activate or deactivate the ability for a user to copy any file he receives in his personal cloud space.

  • fileTransferCustomisation: to activate or deactivate the ability for a user to copy a file from a conversation then share it inside another conversation.

  • forbidFileOwnerChangeCustomisation: to activate or deactivate the ability for a user to loose the ownership on one file.

  • readReceiptsCustomisation: to activate or deactivate the ability for a user to allow if a chat message is read..

  • useSpeakingTimeStatistics: to activate or deactivate the ability for a user to see speaking time statistics.

  • eLearningCustomisation: to activate or deactivate the ability for a user to participate on an Elearning training.

  • eLearningGamificationCustomisation: to activate or deactivate the ability for a user to earn badges for Elearning progress.

  • meetingRecordingCustomisation: to activate or deactivate the ability for a user to record a meeting.

  • useOtherPhoneMode: to activate or deactivate the ability for a user to be on other phone mode.

  • useComputerMode: to activate or deactivate the ability for a user to be on computer mode.

  • useSoftPhoneMode: to activate, force or deactivate the ability for a user to be on softphone mode.

  • useTeamsMode: to activate or deactivate the ability for a user to be on Teams mode.

  • imPopupDuration: to define the IM popup duration.

  • canAccessWhatsNew: to activate or deactivate the ability for a user to access to what's new.

  • canAccessFaqCustomisation: to activate or deactivate the ability for a user to access to FAQ.

  • canAccessHelpCenterCustomisation: to activate or deactivate the ability for a user to access to help center.

  • canAccessStoreCustomisation: to activate or deactivate the ability for a user to access to Rainbow store.

  • canDownloadAppCustomisation: to activate or deactivate the ability for a user to download Rainbow application.

  • canUseTestConfigCustomisation: to activate or deactivate the ability for a user to test the configuration.

  • canUseSendReportCustomisation: to activate or deactivate the ability for a user to use send report feature.

  • canUseTaskCustomisation: to activate or deactivate the ability for a user to use task.

  • canSetInvisiblePresenceCustomisation: to activate or deactivate the ability for a user to set invisible presence.

  • canCallParticipantPbxNumberCustomisation: to select the kind of call participant PBX number.

  • canSetInvisiblePresenceCustomisation: to disable the capability for users to set their presence to "Invisible"

  • receivedFileCustomisation: to restrict the receiving of files and protect from data coming from a foreign user of the company

  • Some inconsistencies may lead to an error (403628)

    • fileSharingCustomisation can't be enabled when fileStorageCustomisation is disabled
    • fileCopyCustomisation can't be enabled when fileStorageCustomisation is disabled
    • fileTransferCustomisation can't be enabled when fileCopyCustomisation is disabled, as we have to make a copy of the file before sharing it.
    • useWebRTCVideoCustomisation can't be enabled when useWebRTCAudioCustomisation is disabled
    • instantMessagesCustomisation can't be enabled when fileStorageCustomisation is disabled
    • instantMessagesCustomisation can't be enabled when fileSharingCustomisation is disabled

  • visibleBy array: when provided, it will be fully replaced by the newly provided array.

  • when modified, a custom profile is propagated to all users using this profile

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
templateId
required
string

Application customisation templates unique identifier (e.g. 5e53a3ab98fb963c5068f176)

Request Body schema: application/json
canAccessFaqCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to access to FAQ.
Defines if a user can access to FAQ.
canAccessFaqCustomisation can be:

  • enabled: The user can access to FAQ.
  • disabled: The user can't access to FAQ.
canAccessHelpCenterCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to access to help center.
Defines if a user can access to help center.
canAccessHelpCenterCustomisation can be:

  • enabled: The user can access to help center.
  • disabled: The user can't access to help center.
canAccessStoreCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to access to Rainbow store.
Defines if a user can access to Rainbow store.
canAccessStoreCustomisation can be:

  • enabled: The user can access to Rainbow store.
  • disabled: The user can't access to Rainbow store.
canAccessWhatsNew
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to access to what's new.
Defines if a user can access to what's new.
canAccessWhatsNew can be:

  • enabled: The user can access to what's new.
  • disabled: The user can't access to what's new.
canCallParticipantPbxNumberCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled" "internal" "national"

Select the kind of call participant number.
Defines the kind of call participant number.
canCallParticipantPbxNumberCustomisation can be:

  • enabled: The user can call a participant via all PBX number
  • disabled: The user can't call a participant via any PBX number.
  • internal: The user can call a participant via an internal PBX number.
  • national: The user can call a participant via a national PBX number.
canDownloadAppCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to download Rainbow application.
Defines if a user can download Rainbow application.
canDownloadAppCustomisation can be:

  • enabled: The user can download Rainbow application.
  • disabled: The user can't download Rainbow application.
canSetInvisiblePresenceCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to set invisible presence
Defines if a user can download Rainbow application.
canSetInvisiblePresenceCustomisation can be:

  • enabled: The user can set invisible presence.
  • disabled: The user can't set invisible presence.
canUseSendReportCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use send report feature.
Defines if a user can use send report feature.
canUseSendReportCustomisation can be:

  • enabled: The user can use send report feature.
  • disabled: The user can't send report feature.
canUseTaskCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use task.
Defines if a user can use task.
canUseTaskCustomisation can be:

  • enabled: The user can use task.
  • disabled: The user can't use task.
canUseTestConfigCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to test the configuration.
Defines if a user can test the configuration.
canUseTestConfigCustomisation can be:

  • enabled: The user can test the configuration.
  • disabled: The user can't test the conguration.
changeSettingsCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to change all client general settings.
Define if one or all users of a company has the right to change his client general settings.
changeSettingsCustomisation can be:

  • enabled: The user can change all client general settings.
  • disabled: The user can't change any client general setting.
changeTelephonyCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to modify telephony settings.
Define if one or all users of a company has the right to modify telephony settings like forward activation ....
changeTelephonyCustomisation can be:

  • enabled: The user can modify telephony settings.
  • disabled: The user can't modify telephony settings.
eLearningCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to participate on an Elearning training.
Defines if a user can participate on an eLearning training.
eLearningCustomisation can be:

  • enabled: The user can participate on an eLearning training.
  • disabled: The user can't participate on an eLearning training.
eLearningGamificationCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to earn badges for Elearning progress.
Defines if a user can participate on an eLearning training.
eLearningCustomisation can be:

  • enabled: The user can participate on an eLearning training.
  • disabled: The user can't participate on an eLearning training.
fileCopyCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to copy files
Define if one or all users of a company is allowed to copy any file he receives in his personal cloud space.
fileCopyCustomisation can be:

  • enabled: The user can make a copy of a file to his personal cloud space.
  • disabled: The user can't make a copy of a file to his personal cloud space.
fileSharingCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate file sharing capability per company
Define if one or all users of a company can use the file sharing service then, allowed to download and share file.
fileSharingCustomisation can be:

  • enabled: Each user of the company can use the file sharing service, except when his own capability is set to 'disabled'.
  • disabled: Each user of the company can't use the file sharing service, except when his own capability is set to 'enabled'.
fileStorageCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to access to Rainbow file storage.
Define if one or all users of a company has the right to upload/download/copy or share documents.
fileStorageCustomisation can be:

  • enabled: Each user of the company can manage and share files.
  • disabled: No user of the company can manage and share files.
fileTransferCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to transfer files.
Define if one or all users of a company has the right to copy a file from a conversation then share it inside another conversation.
fileTransferCustomisation can be:

  • enabled: The user can transfer a file doesn't belong to him.
  • disabled: The user can't transfer a file doesn't belong to him.
forbidFileOwnerChangeCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to loose the ownership on one file.
Define if one or all users can drop the ownership of a file to another Rainbow user of the same company
forbidFileOwnerChangeCustomisation can be:

  • enabled: The user can't give the ownership of his file.
  • disabled: The user can give the ownership of his file.
imPopupDuration
number
Default: null

Defines the IM popup duration.

instantMessagesCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use instant messages.
Define if one or all users of a company has the right to use IM, then to start a chat (P2P ou group chat) or receive chat messages and chat notifications.
instantMessagesCustomisation can be:

  • enabled: Each user of the company can use instant messages.
  • disabled: No user of the company can use instant messages.
meetingRecordingCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to record a meeting.
Defines if a user can record a meeting.
meetingRecordingCustomisation can be:

  • enabled: The user can record a meeting.
  • disabled: The user can't record a meeting.
name
string [ 1 .. 64 ] characters

Template name.

overridePresenceCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to change manually his presence.
Define if one or all users of a company has the right to change his presence manually or only use automatic states.
overridePresenceCustomisation can be:

  • enabled: Each user of the company can change his presence.
  • disabled: No user of the company can change his presence.
phoneMeetingCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use phone meetings (PSTN conference).
Define if one or all users of a company has the right to join phone meetings.
phoneMeetingCustomisation can be:

  • enabled: Each user of the company can join phone meetings.
  • disabled: No user of the company can join phone meetings.
readReceiptsCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to allow a sender to check if a chat message is read.
Defines whether a peer user in a conversation allows the sender of a chat message to see if this IM is acknowledged by the peer.
readReceiptsCustomisation can be:

  • enabled: The user allow the sender to check if an IM is read.
  • disabled: The user doesn't allow the sender to check if an IM is read.
receivedFileCustomisation
string
Default: "enabled"
Enum: "enabled" "internalOnly" "disabled"

Restrict data received.
Restrict the receiving of files to protect from data coming from a foreign user of the company.
receivedFileCustomisation can be:

  • enabled: The user can receive files without restrictions
  • internalOnly: User can receive files only within internal company communications
  • disable: The user can’t receive files under any circumstances. Best for users or roles where no file exchange is necessary or allowed. This ensures maximum protection against unauthorized or potentially harmful file transfers.
recordingConversationCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to record a conversation.
Define if one or all users of a company has the right to record a conversation (for P2P and multi-party calls).
recordingConversationCustomisation can be:

  • enabled: The user can record a peer to peer or a multi-party call.
  • disabled: The user can't record a peer to peer or a multi-party call.
useChannelCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use a channel.
Define if one or all users of a company has the right to create channels or be a member of channels.
useChannelCustomisation can be:

  • enabled: Each user of the company can use some channels.
  • disabled: No user of the company can use some channel.
useComputerMode
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to be on computer mode.
Defines if a user can be on computer mode.
useComputerMode can be:

  • enabled: The user can be on computer mode.
  • disabled: The user can't be on computer mode.
useDialOutCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use dial out in phone meetings.
Define if one or all users of a company is allowed to be called by the Rainbow conference bridge.
useDialOutCustomisation can be:

  • enabled: The user can be called by the Rainbow conference bridge.
  • disabled: The user can't be called by the Rainbow conference bridge.
useGifCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to Use GIFs in conversations.
Define if one or all users of a company has the is allowed to send animated GIFs in conversations
useGifCustomisation can be:

  • enabled: The user can send animated GIFs in conversations.
  • disabled: The user can't send animated GIFs in conversations.
useOtherPhoneMode
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to be on other phone mode.
Defines if a user can be on other phone mode.
useOtherPhoneMode can be:

  • enabled: The user can be on other phone mode.
  • disabled: The user can't be on other phone mode.
useRoomCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to use bubbles.
Define if one or all users of a company can create bubbles or participate in bubbles (chat and web conference).
useRoomCustomisation can be:

  • enabled: Each user of the company can use bubbles.
  • disabled: No user of the company can use bubbles.
useScreenSharingCustomisation
string
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to share a screen.
Define if a user has the right to share his screen.
useScreenSharingCustomisation can be:

  • enabled: Each user of the company can share his screen.
  • disabled: No user of the company can share his screen.
useSoftPhoneMode
string
Default: "enabled"
Enum: "enabled" "disabled" "forced"

Activate/Force/Deactivate the capability for a user to be on softphone mode.
Defines if a user can be on softphone mode.
useSoftPhoneMode can be:

  • enabled: The user can be on softphone mode.
  • forced: The user can use the softphone mode only on Web application.
  • disabled: The user can't be on softphone mode.
useSpeakingTimeStatistics
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the ability for a user to see speaking time statistics.
Defines whether a user has the right to see for a given meeting the speaking time for each attendee of this meeting.
useSpeakingTimeStatistics can be:

  • enabled: The user can use meeting speaking time statistics.
  • disabled: The user can't can use meeting speaking time statistics.
useTeamsMode
string
Default: "disabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to be on Teams mode.
Defines if a user can be on Teams mode.
useTeamsMode can be:

  • enabled: The user can be on Teams mode.
  • disabled: The user can't be on Teams mode.
useWebRTCAudioCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to switch to a Web RTC audio conversation.
Define if one or all users of a company has the right to be joined via audio (WebRTC) and to use Rainbow audio (WebRTC) (start a P2P audio call, start a web conference call).
useWebRTCAudioCustomisation can be:

  • enabled: Each user of the company can switch to a Web RTC audio conversation.
  • disabled: No user of the company can switch to a Web RTC audio conversation.
useWebRTCOnlyIfMobileLoggedCustomisation
string
Default: "disabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to receive web RTC call if mobile app is signed in.
Define if one or all users of a company has the right to be joined via audio (WebRTC) if they have a mobile application signed in.
useWebRTCOnlyIfMobileLoggedCustomisation can be:

  • enabled: Each user of the company can receive a web RTC call if mobile app is signed in.
  • disabled: No user of the company can receive a web RTC call if mobile app is signed in.
useWebRTCVideoCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to switch to a Web RTC video conversation.
Define if one or all users of a company has the right to be joined via video and to use video (start a P2P video call, add video in a P2P call, add video in a web conference call).
useWebRTCVideoCustomisation can be:

  • enabled: Each user of the company can switch to a Web RTC video conversation.
  • disabled: No user of the company can switch to a Web RTC video conversation.
userProfileCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to modify his profile.
Define if one or all users of a company has the right to modify the globality of his profile and not only (title, firstName, lastName).
userProfileCustomisation can be:

  • enabled: Each user of the company can modify his profile.
  • disabled: No user of the company can modify his profile.
userTitleNameCustomisation
string
Default: "enabled"
Enum: "enabled" "disabled"

Activate/Deactivate the capability for a user to modify his profile (title, firstName, lastName) per company
Define if one or all users of a company is allowed to change some profile data.
userTitleNameCustomisation can be:

  • enabled: Each user of the company can change some profile data, except when his own capability is set to 'disabled'.
  • disabled: Each user of the company can't change some profile data, except when his own capability is set to 'enabled'.
visibleBy
Array of strings

When visibility is private, list of companyIds that can access the template (other than the 'ownedByCompany' one).

Responses

Request samples

Content type
application/json
{
  • "canAccessFaqCustomisation": "enabled",
  • "canAccessHelpCenterCustomisation": "enabled",
  • "canAccessStoreCustomisation": "enabled",
  • "canAccessWhatsNew": "enabled",
  • "canCallParticipantPbxNumberCustomisation": "enabled",
  • "canDownloadAppCustomisation": "enabled",
  • "canSetInvisiblePresenceCustomisation": "enabled",
  • "canUseSendReportCustomisation": "enabled",
  • "canUseTaskCustomisation": "enabled",
  • "canUseTestConfigCustomisation": "enabled",
  • "changeSettingsCustomisation": "enabled",
  • "changeTelephonyCustomisation": "enabled",
  • "eLearningCustomisation": "enabled",
  • "eLearningGamificationCustomisation": "enabled",
  • "fileCopyCustomisation": "enabled",
  • "fileSharingCustomisation": "enabled",
  • "fileStorageCustomisation": "enabled",
  • "fileTransferCustomisation": "enabled",
  • "forbidFileOwnerChangeCustomisation": "enabled",
  • "imPopupDuration": null,
  • "instantMessagesCustomisation": "enabled",
  • "meetingRecordingCustomisation": "enabled",
  • "name": "string",
  • "overridePresenceCustomisation": "enabled",
  • "phoneMeetingCustomisation": "enabled",
  • "readReceiptsCustomisation": "enabled",
  • "receivedFileCustomisation": "enabled",
  • "recordingConversationCustomisation": "enabled",
  • "useChannelCustomisation": "enabled",
  • "useComputerMode": "enabled",
  • "useDialOutCustomisation": "enabled",
  • "useGifCustomisation": "enabled",
  • "useOtherPhoneMode": "enabled",
  • "useRoomCustomisation": "enabled",
  • "useScreenSharingCustomisation": "enabled",
  • "useSoftPhoneMode": "enabled",
  • "useSpeakingTimeStatistics": "enabled",
  • "useTeamsMode": "disabled",
  • "useWebRTCAudioCustomisation": "enabled",
  • "useWebRTCOnlyIfMobileLoggedCustomisation": "disabled",
  • "useWebRTCVideoCustomisation": "enabled",
  • "userProfileCustomisation": "enabled",
  • "userTitleNameCustomisation": "enabled",
  • "visibleBy": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": 401,
  • "errorMsg": "Unauthorized",
  • "errorDetails": {
    },
  • "errorDetailsCode": 401523
}

Delete a join company link

This API can be used by company admin users to delete a join company link by id

Join company links allow company administrators to generate an id that can be used by users to create their account in this company (using API POST /api/rainbow/enduser/v1.0/users/self-register).

Join company links can't be deleted if they have been used by users to register in the related company (in that case they can only be disabled, by updating isEnabled value to false).

Example: DELETE https://openrainbow.com/api/rainbow/admin/v1.0/companies/5703d0d49ccf39843c7ef897/join-companies/links/086e997557924910bc838f93aee7b25d

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

joinCompanyLinkId
required
string

Join company link unique identifier (like 086e997557924910bc838f93aee7b25d)

Responses

Response samples

Content type
application/json
{
  • "status": "JoinCompanyLink 086e997557924910bc838f93aee7b25d successfully deleted",
  • "data": {
    }
}

Get a join company link

This API can be used by company admin users to get a join company link by id

Join company links allow company administrators to generate an id that can be used by users to create their account in this company (using API POST /api/rainbow/enduser/v1.0/users/self-register).

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/companies/5703d0d49ccf39843c7ef897/join-companies/links/086e997557924910bc838f93aee7b25d

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

joinCompanyLinkId
required
string

Join company link unique identifier (like 086e997557924910bc838f93aee7b25d)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Organisations

Get all organisations

Users with 'superadmin', 'support', 'business_admin' or 'admin' role can retrieve all organisations. Users with admin role (and not having superadmin, business_admin nor support role) can only retrieve organisations he has to manage.
Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/organisations?format=small&limit=100&offset=0&sortField=name&sortOrder=-1

Authorizations:
BearerBearer-x-rainbow-api-key
query Parameters
format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less organisation details in response.
- small: _id, name
- medium: _id, name
- full: all organisation fields

limit
number
Default: 100

Allow to specify the number of companies to retrieve.

offset
number

Allow to specify the position of first company to retrieve (first company if not specified). Warning: if offset > total, no results are returned.

sortField
string
Default: "name"

Sort organisation list based on the given field.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting company list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 1
}

Get an organisation data

Users with 'superadmin', 'business_admin', 'support' or 'admin' role can retrieve any company.
Users with admin role (and not having superadmin, business_admin nor support role) can only retrieve organisations he has to manage..
Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/organisations/57486e5d807a594145e510d6

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
organisationId
required
string

Organisation unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an organisation

Update organisation data

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
organisationId
required
string

Organisation unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
autoAcceptUserInvitations
boolean
Default: false

Allow to enable or disable the auto-acceptation of user invitations between users belonging to companies of this organisation (default false: disabled)

autoAddToUserNetwork
number
Default: null

Allow to enable or disable the auto addition to user's network between users of this organisation (default false: disabled)

contentPolicyLifeTime
boolean
Default: false

When different from -1 it activates content removal for all user of this organisation with a content lifetime equals to contentPolicyLifeTime in minutes

documentGracePeriod
boolean
Default: false

When content removal is active for the organisation it represents the period in minutes where a document is still available event if it's content policy lifetime has expired

name
required
string [ 1 .. 255 ] characters

Organisation name

visibility
string
Default: "private"
Enum: "public" "private"

Organisation visibility (define if users being in this organisation can be searched by users being in other organisations)

Responses

Request samples

Content type
application/json
{
  • "autoAcceptUserInvitations": false,
  • "autoAddToUserNetwork": null,
  • "contentPolicyLifeTime": false,
  • "documentGracePeriod": false,
  • "name": "string",
  • "visibility": "private"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Organisations Companies

Unlink the company to an organization

Unlink the company to an organization

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
companyId
required
string

Company unique identifier (like 5749ab92245015fe0d36e96a)

organisationId
required
string

Organisation unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "status": "Company 5749ab92245015fe0d36e96a successfully deleted from the organisation",
  • "data": [ ]
}

Get all companies linked with this organization

For the 'Enterprise (E1)' offer, the premium offer, the Multi-Layer organization is defined.
It describes a hierarchy including ORGANIZATIONS/COMPANIES/SITES/SYSTEMS.
This api gets all companies linked with an organization.
Example: POST https://openrainbow.com/api/rainbow/admin/v1.0/organisations/57486e5d807a594145e510d6/companies

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
organisationId
required
string

Organisation unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
sortField
string
Default: "name"

Sort items list based on the given field

bpId
string

Allows to filter companies list on bpId field.
This filter allow to get all the End Customer companies associated to a given Business Partner company.

Only users with role superadmin, support, business_admin, bp_admin or bp_finance can use this filter.
Users with role bp_admin or bp_finance can use this filter on their own company.

catalogId
string

Allows to filter companies list on catalogId field.
This filter allow to get all the companies linked to a given catalogId.

Only users with role superadmin, support or business_admin can use this filter.

offerId
string

Allows to filter companies list on companies having subscribed to the provided offerId.

offerCanBeSold
boolean

Allows to filter companies list on companies having subscribed to offers with canBeSold=true.
This filter can only be used with the value true (false is not relevant, as all companies have a subscription to Essential which has canBeSold=false, so all companies would match offerCanBeSold=false).

externalReference
string

Allows to filter companies list on externalReference field.
The search is done on externalReference starting with the input characters, case sensitive (ex: ABC will match companies with externalReference ABC, ABCD, ABC12... ; but externalReference abc, AABC, 1ABC, ... will not match).

Only users with role superadmin, support, business_admin, bp_admin or bp_finance can use this filter.

externalReference2
string

Allows to filter companies list on externalReference2 field.
The search is done on externalReference2 starting with the input characters, case sensitive (ex: ABC will match companies with externalReference2 ABC, ABCD, ABC12... ; but externalReference2 abc, AABC, 1ABC, ... will not match).

Only users with role superadmin, support, business_admin, bp_admin or bp_finance can use this filter.

salesforceAccountId
string

Allows to filter companies list on salesforceAccountId field.
The search is done on the whole salesforceAccountId, case sensitive (no partial search).

Only users with role superadmin, support, business_admin, bp_admin or bp_finance can use this filter.

selectedAppCustomisationTemplate
string

Allows to filter companies list on application customisation template applied for the company.
This filter allows to get a list of companies for which we have applied the same application customisation template.

Only users with role superadmin, support, bp_admin, admin can use this filter.

selectedThemeObj
boolean

Allows to return selectedTheme attribute as an object:

  • true returns selectedTheme as an object (e.g. { "light": "60104754c8fada2ad4be3e48", "dark": "5ea304e4359c0e6815fc8b57" }),
  • false return selectedTheme as a string.
offerGroupName
string

Allows to filter companies list on companies having subscribed to offers with provided groupName(s).
Only users with role superadmin, support, business_admin, bp_admin or bp_finance can use this filter.
groupName can be retrieved from API GET /api/rainbow/subscription/v1.0/companies/:companyId/offers
The search is done on the whole groupName(s), case sensitive (no partial search).
Several groupName can be provided, seperated by a space.

bpBusinessType
string

Allows to filter companies list on bpBusinessType.
Only users with role superadmin, support, business_admin, bp_admin or bp_finance can use this filter.
Several bpBusinessType can be provided, seperated by a space.

businessSpecific
string

Allows to filter companies list on businessSpecific.
Several businessSpecific can be provided, seperated by a space.

salesEmail
string

Allows to filter companies list on salesEmail
The given email address must be included either in csEmailList, seEmailList, csmEmailList or kamEmailList.

businessRegion
string

Allows to filter companies list on region of business location
Only users with role superadmin, support, business_admin can use this filter.
Several businessRegion can be provided, seperated by a space.

businessCluster
string

Allows to filter companies list on cluster of business location
Only users with role superadmin, support, business_admincan use this filter.
Several businessCluster can be provided, seperated by a space.

businessArea
string

Allows to filter companies list on area of business location
Only users with role superadmin, support, business_admin can use this filter.
Several businessArea can be provided, seperated by a space.

format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less company details in response.
- small: _id, name
- medium: _id, name, status
- full: all company fields

name
string

Allows to filter companies list on the given keyword(s) on field name.

The filtering is case insensitive and on partial name match: all companies containing the provided name value will be returned (whatever the position of the match).
Ex: if filtering is done on comp, companies with the following names are match the filter 'My company', 'Company', 'A comp 1', 'Comp of comps', ...

status
string
Enum: "initializing" "active" "alerting" "hold" "terminated"

Allows to filter companies list on the provided status(es)

visibility
string
Enum: "public" "private" "organization" "closed" "isolated"

Allows to filter companies list on the provided visibility(ies)

organisationId
string

Allows to filter companies list on the organisationIds provided in this option.

This filter can only be used if user has role(s) superadmin, support, bp_admin or admin

isBP
boolean

Allows to filter companies list on isBP field:

  • true returns only Business Partner companies,
  • false return only companies which are not Business Partner.

This filter can only be used if user has role(s) superadmin, business_admin,customer_success_admin, support, bp_admin or admin.

hasBP
boolean

Allows to filter companies list on companies being linked or not to a BP:

  • true returns only companies linked to a BP (BP IR companies are also returned),
  • false return only companies which are not linked to a BP.

This filter can only be used if user has role(s) superadmin, business_admin,customer_success_admin, support or bp_admin.

Users with role bp_admin can only use this filter with value false.

bpType
string

Allows to filter companies list on bpType field.

This filter allow to get all the Business Partner companies from a given bpType.

Only users with role superadmin, business_admin,customer_success_admin, support or bp_admin can use this filter.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 3
}

Link a company to an organization

For the 'Enterprise (E1)' offer, the premium offer, the Multi-Layer organization is defined.
It describes a hierarchy including ORGANIZATIONS/COMPANIES/SITES/SYSTEMS.
This api links a company with the given organization. Company's users are automatically attached to this organisation.
A company must belong to only one organisation or kept single.
When an organization is deleted, the company is automatically unlinked.
Example: POST https://openrainbow.com/api/rainbow/admin/v1.0/organisations/57515338c5d7b862456d60a0/companies (body "companyId":"5749ab92245015fe0d36e96a")

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
organisationId
required
string

Organisation unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
companyId
required
string

Company unique identifier

Responses

Request samples

Content type
application/json
{
  • "companyId": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Sites

Delete a site

This API allows administrator to delete a site for a company they administrate.

superadmin can delete sites for all companies existing in Rainbow.
bp_admin can only delete sites for companies linked to End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only delete sites for companies linked to companies under their organisation.
company_admin can only delete sites for their own company.


Note : Delete will be forbidden if site is still linked to system(s)

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
siteId
required
string

Site unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "status": "Site 569d0ef3ef7816921f7e94fa successfully deleted",
  • "data": [ ]
}

Get a site data

This API allows administrator to retrieve a given site.

superadmin and support can get all sites existing in Rainbow.
bp_admin can only get visible sites linked to End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only get visible sites linked to companies under their organisation.
company_admin can only get visible sites linked to their company.
site_admin can only get the visible site they administrate.

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/sites/569d0ef3ef7816921f7e94fa

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
siteId
required
string

Site unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a site

This API allows administrator to update a given site.

superadmin can update all sites existing in Rainbow.
bp_admin can only update sites linked to End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only update sites linked to companies under their organisation.
company_admin can only update sites linked to their company.
site_admin can only update the site they administrate.

In a Multi-Layer organization defining a hierarchy ORGANIZATIONS/COMPANIES/SITES/SYSTEMS, only bp admin or admin of the site's organization is allowed to move the site (change companyId field of the site).


Note : Site companyId update will be forbidden if site is still linked to CloudPBX system(s)

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
siteId
required
string

Site unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
companyId
required
string

Id of the company from which the site is linked.

isVisibleByBP
boolean

Site is visible by BP admin and admins, only for superadmin

name
string [ 1 .. 255 ] characters

Site name

status
string [ 3 .. 255 ] characters
Enum: "active" "alerting" "hold" "terminated"

Site status

Responses

Request samples

Content type
application/json
{
  • "companyId": "string",
  • "isVisibleByBP": true,
  • "name": "string",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all sites

This API allows administrator to retrieve sites they can administrate.

superadmin and support get all sites existing in Rainbow.
bp_admin only get sites linked to End Customer companies for which their bp_admin's company is the BP company.
organization_admin only get sites linked to companies under their organisation.
company_admin only get sites linked to their company.
site_admin only get the site they administrate.

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/sites?format=small&limit=100&offset=0&sortField=name&sortOrder=-1

Authorizations:
BearerBearer-x-rainbow-api-key
query Parameters
nbUsers
boolean
Default: false

Allow to retrieve number of users for each site.

nbSystems
boolean
Default: false

Allow to retrieve number of systems linked for each site.

format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less site details in response.
- small: _id, name
- medium: _id, name, status, companyId
- full: all site fields

limit
number
Default: 100

Allow to specify the number of companies to retrieve.

offset
number

Allow to specify the position of first site to retrieve (first site if not specified). Warning: if offset > total, no results are returned.

sortField
string
Default: "name"

Sort site list based on the given field.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting site list.

name
string

Allows to filter sites list on field name.

The filtering is case insensitive and on partial name match: all sites containing the provided name value will be returned (whatever the position of the match).
Ex: if filtering is done on sit, sites with the following names are match the filter 'My site', 'Site', 'A site 1', 'Site of company', 'Sit1', 'Sit2', ...

companyId
string

Allows to filter sites list on the companyIds provided in this option.

isVisibleByBP
boolean

Allows to filter sites list visible by admins, only for superadmin or support.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": 2,
  • "limit": 100,
  • "offset": 0
}

Create a site

This API allows administrator to create a site for a company they administrate.

superadmin can create sites for all companies existing in Rainbow.
bp_admin can only create sites for companies linked to End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only create sites for companies linked to companies under their organisation.
company_admin can only create sites for their own company.

Specific feature: Sharing a system between several companies
Since 1.47.0 release, configuring companies sharing a multi-tenant system is possible.
An OXE can be multi-company.
A multi-tenant system, so called CENTREX, allows sharing a call-server between several entities. For us an entity is a company with the flag isCentrex=true.
A company in this environment can only have a single site. It has automatically the flag isCentrex = true
This flag is readonly.

Authorizations:
BearerBearer-x-rainbow-api-key
Request Body schema: application/json
companyId
required
string

Id of the company from which the site is linked.

name
required
string [ 1 .. 255 ] characters

Site name

status
required
string
Enum: "active" "alerting" "hold" "terminated"

Site status

Responses

Request samples

Content type
application/json
{
  • "companyId": "string",
  • "name": "string",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Sites Systems

Unlink a system to a site

This API allows administrator to delete a link between a system and a site

superadmin and support can unlink any systems from any sites existing in Rainbow.
bp_admin can only unlink systems being linked to sites of End Customer companies for which their bp_admin's company is the BP company from sites of End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only unlink systems being linked to sites of companies under their organisation from sites of companies under their organisation.
company_admin can only unlink systems being linked to sites of their company from sites of their company.
Access is denied for site_admin.
A system could be shared by several sites.
Last site can be detached from a system only if it is multi-company or multi-tenant (isShared=true or isCentrex=true)

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
siteId
required
string

Site unique identifier

systemId
required
string

System unique identifier

Responses

Response samples

Content type
application/json
{
  • "status": "Site 5749ab92245015fe0d36e96a successfully removed",
  • "data": [ ]
}

Get all systems linked with this site

This API allows administrator to retrieve systems linked to a given site

superadmin and support can get systems linked to all companies existing in Rainbow.
bp_admin can only get systems linked to sites of End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only get systems linked to sites of companies under their organisation.
company_admin can only get systems linked to sites of their company.
site_admin can only get the systems linked to the site they administrate.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
siteId
required
string

Site unique identifier

query Parameters
format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less system details in response.
- small: id pbxId version
- medium: id name pbxId serialNumber version status
- full: all system fields

limit
number
Default: 100

Allow to specify the number of systems to retrieve.

offset
number

Allow to specify the position of first system to retrieve (first site if not specified). Warning: if offset > total, no results are returned.

sortField
string
Default: "pbxId"

Sort system list based on the given field.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting pbx list.

name
string

Allows to filter systems list on field name.

The filtering is case insensitive and on partial name match: all systems containing the provided name value will be returned (whatever the position of the match).
Ex: if filtering is done on oxe1, systems with the following names are match the filter 'OXE1', 'Oxe1', 'My oxe1', 'oxe12', 'My OXE12', ...

type
string
Enum: "oxo" "oxe" "third_party" "cloud_pbx" "undefined"

Allows to filter systems list on the provided type(s)

status
string
Enum: "created" "activating" "activated" "terminated"

Allows to filter systems list on the provided status(es)

siteId
string

Allows to filter systems list on the siteIds provided in this option.

companyId
string

Allows to filter systems list on the siteIds linked to companyIds provided in this option.

bpId
string

Allows to filter systems list on the bpIds provided in this option.
Only superadmin, support and bp_admin users can use bpId filter.
bp_admin users can only use bpId filter with bpId they manage (their own BP company or companies being in their BP organisation).

isShared
boolean

Allows to filter systems list by the status isShared.

isCentrex
boolean

Allows to filter systems list by the status isCentrex.

isSharedOrCentrex
boolean

Allows to filter systems list having the requested flag isShared or isCentrex.

  • If isSharedOrCentrex=true, only systems having isShared=true or isCentrex=true are returned.
  • If isSharedOrCentrex=false, only systems having isShared=false and isCentrex=false are returned.
isOxoManaged
boolean

Allows to filter systems list by the setting isOxoManaged.

fromCreationDate
string <date-time>

Allows to filter systems list from provided date (ISO 8601 format).

toCreationDate
string <date-time>

Allows to filter systems list until provided date (ISO 8601 format).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "usePbxMainBundlePrefix": true
}

Link a system to a site

This API allows administrator to link a system to a given site

A PABX can be multi tenant.
When a PABX is shared, that means in our data model: 'A system is shared between several sites'.
This API makes possible to add a link between a system and a site that belongs to the same company or not.
If the link still exists, no error is thrown.

superadmin and support can link any systems to any sites existing in Rainbow.
bp_admin can only link systems being already linked to sites of End Customer companies for which their bp_admin's company is the BP company to sites of End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only link systems being already linked to sites of companies under their organisation to sites of companies under their organisation.
company_admin can only link systems being already linked to sites of their company to sites of their company.
Access is denied for site_admin.

Specific feature: Sharing a system between several companies
Since 1.47.0 release, configuring companies sharing a multi-tenant system is possible.
An OXE can be multi-company.
A multi-tenant system, so called CENTREX, allows sharing a call-server between several entities. For us an entity is a company with the flag isCentrex=true.
A company in this environment can only have a single site. It has automatically the flag isCentrex = true
Only one sytem having the flag isCentrex = true can be linked with a site having the same flag value.
A system having the flag isCentrex = true can be shared by several sites having the same flag value.
A specific error "Inconsistent link. A multi-tenant system must be shared by a multi-tenant company only" 43709 is thrown when we try to link an incompatible system to a site.
When set during the system creation, isCentrex flag is readonly.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
siteId
required
string

Site unique identifier

Request Body schema: application/json
systemId
required
string

System unique identifier { "systemId": "5749ab92245015fe0d36e96a" }

Responses

Request samples

Content type
application/json
{
  • "systemId": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Systems

Delete a system

This API allows administrator to delete a given system.

superadmin can delete systems linked to all sites existing in Rainbow.
bp_admin can only delete systems linked to sites of End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only delete systems linked to sites of companies under their organisation.
company_admin can only delete systems linked to sites of their company.
site_admin can only delete the systems linked to the site they administrate.

Warning: all configuration data and phoneNumbers associated to this system will be deleted, and if these phoneNumbers were associated to a Rainbow user, it won't be anymore.
jid_pbxagent and jid_pbxpcg XMPP accounts will also be deleted from XMPP.

PCG is notified of the system deletion with the following XMPP message. Once PCG has acknowledged the IQ, the system is deleted from mongoDB, jid_pbxagent and jid_pbxpcg XMPP accounts are deleted from XMPP, and all phoneNumbers objects linked to this system are deleted (therefore PCG don't have to call delete for all deleted system's phoneNumbers).

<iq id="8413b42e-563c-4437-9a53-06f638b5ab69_0"
       from="pcloud@openrainbow.com/172440802160413612281463752830017532"
       to="pbxpcg_7ca2d0aefb024c949303b508fcecdad2@openrainbow.com/pbxpcg"
       xmlns="jabber:client">
    <config xmlns="urn:xmpp:pbxagent:config:1">
        <pbx action="delete">
    </config>
</iq>
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "status": "Systems 569d0ef3ef7816921f7e94fa successfully deleted",
  • "data": [ ]
}

Get a system data

This API allows administrator to retrieve a given system.

superadmin and support can get all systems existing in Rainbow.
bp_admin can only get systems linked to sites of End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only get systems linked to sites of companies under their organisation.
company_admin can only get systems linked to sites of their company.
site_admin can only get the systems linked to the site they administrate.

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
connectionHistory
boolean

Allows to return connection history

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a system

This API allows administrator to update a given system.

superadmin can update systems linked to all sites existing in Rainbow.
bp_admin can only update systems linked to sites of End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only update systems linked to sites of companies under their organisation.
company_admin can only update systems linked to sites of their company.
site_admin can only update the systems linked to the site they administrate.

When the system is updated, PCG is notified on its corresponding JID pbxpcg with the following XMPP message:

<message id="8413b42e-563c-4437-9a53-06f638b5ab69_0"
          from="pcloud@openrainbow.com/172440802160413612281463752830017532"
          to="pbxpcg_7ca2d0aefb024c949303b508fcecdad2@openrainbow.com"
          xmlns="jabber:client">
     <config xmlns="urn:xmpp:pbxagent:config:1"/>
         <pbx action="update">
     </config>
</message>

Don't use this api to move a isCentrex system to another site.
Use instead DELETE /api/rainbow/admin/v1.0/sites/:siteId/systems then
POST /api/rainbow/admin/v1.0/sites/:siteId/systems

isShared setting can be updated with the following restrictions:

  • If isShared is enabled, at least 1 site must be set or bpId must be set (automatically filled if logged in user is bp_admin)
  • If isShared is disabled, system must have 1 site and only 1
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
bpId
string

Link the system to the corresponding Business partner company.
bpId must correspond to a valid company having isBP equal to true.
Only directly settable by superadmin.

Array of objects (putSystemsCcdPolicy)

Indicates the cdd configuration of the PBX

country
string 3 characters

System country (ISO 3166-1 alpha3 format)

displaySecretIdentityService
boolean
Default: false

Used to inform Rainbow client before about the Secret Identity service can be displayed or not

isCallFromPbxAuthorized
boolean

Indicates a call from the PBX is authorized

isCallToPbxAuthorized
boolean

Indicates a call to the PBX is authorized

isShared
boolean

Indicates if the system is multi-company (shared across multiple companies).

  • isShared flag can't be set to true if isCentrex flag is true (these settings are exclusives).
  • Shared systems can be linked to several sites from different companies.
  • Several shared PBX can be attached to a same Rainbow company, as well as "standard" systems (i.e. systems without isShared flag, and so being linked only to this company).
  • Companies being linked to shared PBX can't be attached to centrex systems.
  • It is understood that this approach exposes all users of the shared PBX to all companies that have users on this PBX (for association, for dial by name).
    Anyway it seats on a PBX infra where all PBX users can directly dial (by short num and DBN) any other users of the network from their deskphones.
  • In cases the underlying infra is an homogeneous network of PBX, PBX grouping has to be managed.
  • isShared flag can be updated to true only if the system has isCentrex=false and is linked to at least one site or if a bpId is set.
  • isShared flag can be updated to false only if the system is linked to one site (exactly). In that case, bpId field is automatically reset to null.
name
string

System name/description

pbxInternationalPrefix
string [ 0 .. 32 ] characters

International prefix

pbxLdapId
string

custom "pbxId" declared in an external DB (ldap), used to correlate to Rainbow pbxId.

pbxMainBundlePrefix
string

CCA config data

pbxNationalPrefix
string [ 0 .. 32 ] characters

National prefix

Array of objects (putSystemsPbxNumberingTranslator)

List of several regular expressions used to validate internal or external phone numbers. Up to 100 regular expressions are allowed. (64 max char by regexp). To reset the list, use []

reverseConsistentSecret
boolean
Default: false

Uses to revert secret identiy flag when OXE configuration demand it

searchResultOrder
Array of strings
Default: "RAINBOW,PERSONAL_DIRECTORY,BUSINESS_DIRECTORY,O365,PBX"

List of directory types to search results for phone number resolution, the order in the Array gives the priority if a number match on several sources:

  • RAINBOW: PBX devices of the system, if associated to a Rainbow user (PBX devices of all systems belonging to the system's group if applicable).
  • PERSONAL_DIRECTORY: Personal directory database associated to the user for which the phone number resolution is requested.
  • BUSINESS_DIRECTORY: Business directory database associated to the company(ies) to which is(are) linked the system for which the phone number resolution is requested.
  • O365: Office365 database associated to the company(ies) to which is(are) linked the system for which the phone number resolution is requested.
  • PBX: phonebook of the system (phonebooks of all systems belonging to the system's group if applicable).
serverPingTimeout
number
Default: 120

CCA config data

siteId
string

Site from which the system is linked with.

type
string
Enum: "oxo" "oxe" "third_party" "undefined"

CCA type.

usePbxMainBundlePrefix
boolean

Whether or not pbxMainBundlePrefix is used by PCG

version
string

CCA software version

voipEmergencyCall
boolean
Default: false

Uses PBX for emergency calls

Responses

Request samples

Content type
application/json
{
  • "bpId": "string",
  • "ccdPolicy": [
    ],
  • "country": "str",
  • "displaySecretIdentityService": false,
  • "isCallFromPbxAuthorized": true,
  • "isCallToPbxAuthorized": true,
  • "isShared": true,
  • "name": "string",
  • "pbxInternationalPrefix": "string",
  • "pbxLdapId": "string",
  • "pbxMainBundlePrefix": "string",
  • "pbxNationalPrefix": "string",
  • "pbxNumberingTranslator": [
    ],
  • "reverseConsistentSecret": false,
  • "searchResultOrder": "RAINBOW,PERSONAL_DIRECTORY,BUSINESS_DIRECTORY,O365,PBX",
  • "serverPingTimeout": 120,
  • "siteId": "string",
  • "type": "oxo",
  • "usePbxMainBundlePrefix": true,
  • "version": "string",
  • "voipEmergencyCall": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all systems

This API allows administrator to retrieve systems they can administrate.

superadmin and support get all systems existing in Rainbow.
bp_admin only get systems linked to sites of End Customer companies for which their bp_admin's company is the BP company.
organization_admin only get systems linked to sites of companies under their organisation.
company_admin only get systems linked to sites of their company.
site_admin only get the systems linked to the site they administrate.

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems?type=oxe&status=activated&format=small&limit=100&offset=0&sortField=name&sortOrder=-1

Specific feature: Sharing a system between several companies

  • Since 1.47.0 release, configuring companies sharing a multi-tenant system is possible.
    This corresponds to OTEC-S OXEs, which are multi-tenant.
    A multi-tenant system, so called centrex, allows sharing a call-server between several entities by setting the flag isCentrex=true on the system. This flag is set during the system creation and can't be changed (the system would have to be deleted first and then re-created without the flag isCentrex).
    For Rainbow, an entity is a site with the flag isCentrex=true linked to a company with the flag isCentrex=true (the company and site must both have the flag isCentrex=true to be linked to a system with isCentrex=true).
    A company with the flag isCentrex=true can only have a single site (the site will have automatically the flag isCentrex=true when it is created).
    Getting a list having the status isCentrex=true is possible using query parameter filter isCentrex.
  • Since 1.73.0 release, configuring companies sharing a multi-company system is possible.
    A shared multi-company system, so called shared, allows sharing a call-server between several sites from different companies.
    No specific configuration is applied on the PBX, the specific configuration is only on Rainbow side, by setting the flag isShared=true on the system. This flag is set during the system creation and can't be changed (the system would have to be deleted first and then re-created without the flag isShared).
    It is understood that this approach exposes all users of the PBX to all companies that have users on this PBX (for association, for dial by name). Anyway it seats on a PBX infra where all PBX users can directly dial (by short num and DBN) any other users of the network from their deskphones.
    A site being linked to such systems can be linked to other systems (shared or not, but not centrex).
    Getting a list having the status isShared=true is possible using query parameter filter isShared.
  • It is possible to get the list of systems being shared or centrex using query parameter filter isSharedOrCentrex.
Authorizations:
BearerBearer-x-rainbow-api-key
query Parameters
connectionHistory
boolean

Allows to return connection history

format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less system details in response.
- small: id pbxId version
- medium: id name pbxId serialNumber version status
- full: all system fields

limit
number
Default: 100

Allow to specify the number of systems to retrieve.

offset
number

Allow to specify the position of first system to retrieve (first site if not specified). Warning: if offset > total, no results are returned.

sortField
string
Default: "pbxId"

Sort system list based on the given field.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting pbx list.

name
string

Allows to filter systems list on field name.

The filtering is case insensitive and on partial name match: all systems containing the provided name value will be returned (whatever the position of the match).
Ex: if filtering is done on oxe1, systems with the following names are match the filter 'OXE1', 'Oxe1', 'My oxe1', 'oxe12', 'My OXE12', ...

type
string
Enum: "oxo" "oxe" "third_party" "cloud_pbx" "undefined"

Allows to filter systems list on the provided type(s)

status
string
Enum: "created" "activating" "activated" "terminated"

Allows to filter systems list on the provided status(es)

siteId
string

Allows to filter systems list on the siteIds provided in this option.

companyId
string

Allows to filter systems list on the siteIds linked to companyIds provided in this option.

bpId
string

Allows to filter systems list on the bpIds provided in this option.
Only superadmin, support and bp_admin users can use bpId filter.
bp_admin users can only use bpId filter with bpId they manage (their own BP company or companies being in their BP organisation).

isShared
boolean

Allows to filter systems list by the status isShared.

isCentrex
boolean

Allows to filter systems list by the status isCentrex.

isSharedOrCentrex
boolean

Allows to filter systems list having the requested flag isShared or isCentrex.

  • If isSharedOrCentrex=true, only systems having isShared=true or isCentrex=true are returned.
  • If isSharedOrCentrex=false, only systems having isShared=false and isCentrex=false are returned.
isOxoManaged
boolean

Allows to filter systems list by the setting isOxoManaged.

fromCreationDate
string <date-time>

Allows to filter systems list from provided date (ISO 8601 format).

toCreationDate
string <date-time>

Allows to filter systems list until provided date (ISO 8601 format).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "usePbxMainBundlePrefix": true
}

Create a system

This API allows administrator to create a system.
A system hosts the CCA (Call Control Agent) configuration.

superadmin can create systems linked to all sites existing in Rainbow.
bp_admin can only create systems linked to sites of End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only create systems linked to sites of companies under their organisation.
company_admin can only create systems linked to sites of their company.
site_admin can only create the systems linked to the site they administrate.

Specific feature: Sharing a system between several companies

  • Since 1.47.0 release, configuring companies sharing a multi-tenant system is possible.
    This corresponds to OTEC-S OXEs, which are multi-tenant.
    A multi-tenant system, so called centrex, allows sharing a call-server between several entities by setting the flag isCentrex=true on the system. This flag is set during the system creation and can't be changed (the system would have to be deleted first and then re-created without the flag isCentrex).
    For Rainbow, an entity is a site with the flag isCentrex=true linked to a company with the flag isCentrex=true (the company and site must both have the flag isCentrex=true to be linked to a system with isCentrex=true).
    A company with the flag isCentrex=true can only have a single site (the site will have automatically the flag isCentrex=true when it is created).
    Getting a list having the status isCentrex=true is possible using query parameter filter isCentrex.
  • Since 1.73.0 release, configuring companies sharing a multi-company system is possible.
    A shared multi-company system, so called shared, allows sharing a call-server between several sites from different companies.
    No specific configuration is applied on the PBX, the specific configuration is only on Rainbow side, by setting the flag isShared=true on the system.
    This flag can be set during the system creation, and can then be updated with the following restrictions:
    • If isShared is enabled, at least 1 site must be set or bpId must be set (automatically filled if logged in user is bp_admin).
    • If isShared is disabled, system must have 1 site and only 1.
    It is understood that this approach exposes all users of the PBX to all companies that have users on this PBX (for association, for dial by name). Anyway it seats on a PBX infra where all PBX users can directly dial (by short num and DBN) any other users of the network from their deskphones.
    A site being linked to such systems can be linked to other systems (shared or not, but not centrex).
    Getting a list having the status isShared=true is possible using query parameter filter isShared.
  • It is possible to get the list of systems being shared or centrex using query parameter filter isSharedOrCentrex.
Authorizations:
BearerBearer-x-rainbow-api-key
Request Body schema: application/json
activationCode
string [ 1 .. 256 ] characters

Currently, the activation code is a random 4 digits value (between 1000 and 9999) generated by the admin portal. With activationCode field, it's possible to set a custom value. In the Http success response the value is available in the 'jid_pbxagent_password' field. activationCode is only taken in account during a system creation.

bpId
string

Link the system to the corresponding Business partner company.
bpId must correspond to a valid company having isBP equal to true.
Only directly settable by superadmin.
If the system is created by a bp_admin, bpId is automatically set to bp_admin's system id.

Array of objects (postSystemsCcdPolicy)

Indicates the cdd configuration of the PBX

country
required
string 3 characters

System country (ISO 3166-1 alpha3 format)

isCentrex
boolean
Default: false

Indicates if the system is one tenant or multi-tenant (OXE - OTEC-S or third_party).

  • isCentrex flag can't be set to true if isShared flag is true (these settings are exclusives).
isOxoManaged
boolean

Indicates if the system is an OXO managed.
Only settable if type is set to oxo.
This setting can only be set at system creation, then it can't be modified.
Only one OXO Managed PBX is allowed for a company.

isShared
boolean
Default: false

Indicates if the system is multi-company (shared across multiple companies).

  • isShared flag can't be set to true if isCentrex flag is true (these settings are exclusives).
  • Shared systems can be linked to several sites from different companies.
  • Several shared PBX can be attached to a same Rainbow company, as well as "standard" systems (i.e. systems without isShared flag, and so being linked only to this company).
  • Companies being linked to shared PBX can't be attached to centrex systems.
  • It is understood that this approach exposes all users of the shared PBX to all companies that have users on this PBX (for association, for dial by name).
    Anyway it seats on a PBX infra where all PBX users can directly dial (by short num and DBN) any other users of the network from their deskphones.
  • In cases the underlying infra is an homogeneous network of PBX, PBX grouping has to be managed.
name
required
string

System name/description

pbxId
string

CCA (Call Control Agent) hosted by a System needs an account to XMPP. This is the login to access to XMPP server. It should be given during system creation or automatically generated.

pbxInternationalPrefix
string [ 0 .. 32 ] characters

International prefix

pbxLdapId
string

custom "pbxId" declared in an external DB (ldap), used to correlate to Rainbow pbxId.

pbxMainBundlePrefix
Array of strings

CCA config data: array of String

pbxNationalPrefix
string [ 0 .. 32 ] characters

National prefix

Array of objects (postSystemsPbxNumberingTranslator)

List of several regular expressions used to validate internal or external phone numbers. Up to 100 regular expressions are allowed. (64 max char by regexp). To reset the list, use []

searchResultOrder
Array of strings
Default: "RAINBOW,PERSONAL_DIRECTORY,BUSINESS_DIRECTORY,O365,PBX"

List of directory types to search results for phone number resolution, the order in the Array gives the priority if a number match on several sources:

  • RAINBOW: PBX devices of the system, if associated to a Rainbow user (PBX devices of all systems belonging to the system's group if applicable).
  • PERSONAL_DIRECTORY: Personal directory database associated to the user for which the phone number resolution is requested.
  • BUSINESS_DIRECTORY: Business directory database associated to the company(ies) to which is(are) linked the system for which the phone number resolution is requested.
  • O365: Office365 database associated to the company(ies) to which is(are) linked the system for which the phone number resolution is requested.
  • PBX: phonebook of the system (phonebooks of all systems belonging to the system's group if applicable).
serverPingTimeout
number
Default: 120

CCA config data

siteId
required
string

Site from which the system is linked with.

type
required
string
Enum: "oxo" "oxe" "third_party" "undefined"

CCA type.

usePbxMainBundlePrefix
boolean

Whether or not pbxMainBundlePrefix is used by PCG

version
string

CCA software version

voipEmergencyCall
boolean
Default: false

Use PBX for emergency calls.

Responses

Request samples

Content type
application/json
{
  • "activationCode": "string",
  • "bpId": "string",
  • "ccdPolicy": [
    ],
  • "country": "str",
  • "isCentrex": false,
  • "isOxoManaged": true,
  • "isShared": false,
  • "name": "string",
  • "pbxId": "string",
  • "pbxInternationalPrefix": "string",
  • "pbxLdapId": "string",
  • "pbxMainBundlePrefix": [
    ],
  • "pbxNationalPrefix": "string",
  • "pbxNumberingTranslator": [
    ],
  • "searchResultOrder": "RAINBOW,PERSONAL_DIRECTORY,BUSINESS_DIRECTORY,O365,PBX",
  • "serverPingTimeout": 120,
  • "siteId": "string",
  • "type": "oxo",
  • "usePbxMainBundlePrefix": true,
  • "version": "string",
  • "voipEmergencyCall": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get list of countries allowed for systems

This API allows to retrieve the list of countries supported by Rainbow Server for systems country field.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get a system data by pbxId

This API allows administrator to retrieve a given system from its pbxId.

superadmin and support can get all systems existing in Rainbow.
bp_admin can only get systems linked to sites of End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only get systems linked to sites of companies under their organisation.
company_admin can only get systems linked to sites of their company.
site_admin can only get the systems linked to the site they administrate.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
pbxId
required
string

Pbx unique identifier known by PCG

query Parameters
connectionHistory
boolean

Allows to return connection history

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Systems Reset Password

Reset CCCA jid password

It would be necessary to reset the password used by the CCCA to join rainbow infrastructure.
Among system data fields, jid_pbxagent and jid_pbxagent_password are used by the CCCA to try an authentication.
The new API :

  • regenerate an activation code which is stored in the Admin portal and XMPP server (four digits)
  • does not change the existing pbxId
  • replace the system status from "activated" to "created"

To finalize CCCA authentication refer to (Get a pbx data using API GET /api/rainbow/pcg/v1.0/pbxs/{pbxId}).
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Systems Groups

Remove a system from a group

Remove system to a group. If the system doesn't exist in the group, an error is raised (404 Not found)
A systems group is a logical set of systems (pabx), sharing the same dial plan and linked through a private network.
Systems belonging to this group may either belonging to the same Site, or belonging from several sites under the same company.
Waiting for a real use case, it is possible to federate inside the same group, systems belonging to companies under the same organization.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier

groupId
required
string

SystemsGroup unique identifier

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add a new system to a group

Add a new system to a group. If the system already exists in the group or inside another one, an error is raised (409 Conflict)
A systems group is a logical set of systems (pabx), sharing the same dial plan and linked through a private network.
Systems belonging to this group may either belonging to the same Site, or belonging from several sites under the same company.
Waiting for a real use case, it is possible to federate inside the same group, systems belonging to companies under the same organization.

Specific feature: Sharing a system between several companies
Since 1.47.0 release, configuring companies sharing a multi-tenant system is possible.
An OXE or third_party system can be multi-company.
A multi-tenant system, so called CENTREX, allows sharing a call-server between several entities. For us an entity is a company with the flag isCentrex=true.
A multi-tenant system can't be set inside a systems group. That does not make sense.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier

groupId
required
string

SystemsGroup unique identifier

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a systems group

Delete a systems groups.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
groupId
required
string

SystemsGroup unique identifier

Responses

Response samples

Content type
application/json
{
  • "status": "SystemsGroup 57ed149c7473a55c17b1d238 successfully deleted",
  • "data": [ ]
}

Get systems group data

A systems group is a logical set of systems (pabx), sharing the same dial plan and linked through a private network.
Systems belonging to this group may either belonging to the same Site, or belonging from several sites under the same company.

According with api permission, the response is not the same.
- Superadmin, Support and organization_admin must see all Systems inside the group.
- bp_admin, company_admin may see Systems hosted by sites under his company.
- site_admin only see systems of his site, inside the group>.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
groupId
required
string

SystemsGroup unique identifier

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Rename a systems group

Only allow a systems group renaming.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
groupId
required
string

SystemsGroup unique identifier

Request Body schema: application/json
name
required
string

Group name describing a private network of pabx

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all systems groups

Get all systems groups.
A systems group is a logical set of systems (pabx), sharing the same dial plan and linked through a private network.
Systems belonging to this group may either belonging to the same Site, or belonging from several sites under the same company.
According with api permission, the response is not the same.
- Superadmin and Support see all SystemsGroups
- bp_admin, organization_admin and company_admin may see several SystemsGroups, but some systems could be hidden for company_admin.
- site_admin only see SystemsGroups hosting some systems of his site, but some systems could be hidden as they are hosted by another site.

Authorizations:
BearerBearer-x-rainbow-api-key
query Parameters
name
string

Allows to filter systems groups list on the name provided in this option.

The filtering is case insensitive and on each word start match: all systems groups containing the provided name value will be returned (whatever the position of the word(s) matching).

If several words are given (space separator), only the system groups matching all words will be returned.

Ex:

  • if filtering is done on My, systems groups with the following names are matched 'My group', 'my group', 'This is my group', ...
  • if filtering is done on is gro, only the systems groups with the following name is matched 'This is my group'.
format
string
Default: "small"
Enum: "small" "medium" "full"

Should allow to retrieve more or less group details in response. But in fact whatever the choice:
- small: _id, name, companies, systems (all SystemsGroup fields)
- medium: all SystemsGroup fields
- full: all SystemsGroup fields

limit
number
Default: 100

Allow to specify the number of companies to retrieve.

offset
number

Allow to specify the position of first company to retrieve (first company if not specified). Warning: if offset > total, no results are returned.

sortField
string
Default: "name"

Sort company list based on the given field.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting company list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 2
}

Create a systems group

A systems group is a logical set of systems (pabx), sharing the same dial plan and linked through a private network.
Systems belonging to this group may either belonging to the same Site, or belonging from several sites under the same company.
Waiting for a real use case, it is possible to federate inside the same group, systems belonging to companies under the same organization.
It's not possible to include multi-tenant systems (isCentrex = true) inside a systems group.

Specific feature: Sharing a system between several companies
Since 1.47.0 release, configuring companies sharing a multi-tenant system is possible.
An OXE or third_party system can be multi-company.
A multi-tenant system, so called CENTREX, allows sharing a call-server between several entities. For us an entity is a company with the flag isCentrex=true.
A multi-tenant system can't be set inside a systems group. That does not make sense.

Authorizations:
BearerBearer-x-rainbow-api-key
Request Body schema: application/json
companies
required
Array of strings

List of Company unique identifier. A least one Id. This field is wanted to classify SystemsGroups inside the rainbow infrastructure.

name
required
string

Group name describing a private network of pabx

systems
Array of strings

List of Systems unique identifier. May be empty. Several checks were done. Possible error cases are: (404 not found), (409 conflict - Systems already belongs to another group), (403 forbidden - one of the systems mustn't be administrated by the administrator)

Responses

Request samples

Content type
application/json
{
  • "companies": [
    ],
  • "name": "string",
  • "systems": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Systems Phone Numbers

Get all system phone numbers

This API allows to list all phoneNumbers associated to a given system (pbx).

Users with superadmin or support role can retrieve phoneNumbers from any system.
bp_admin can only retrieve phoneNumbers linked to systems of End Customer companies for which their bp_admin's company is the BP company.
Users with admin role (and not having superadmin nor support role) can only retrieve phoneNumbers of systems that they manage.
In a Multi-Layer organization that describes a hierarchy including ORGANIZATIONS/COMPANIES/SITES/SYSTEMS, an admin role of a upper layer is allowed to see systems within their's reach.
Notes:

  • systemId field returned in response corresponds to portal's internal mongoDB id, while pbxId is the id handled by PCG.
  • This API is paginated.
  • phoneNumbers list can be filtered on the following fields:
    • shortNumber: allow to retrieve only phoneNumbers starting by the provided value.
      Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phone-numbers?shortNumber=123
    • internalNumber: allow to retrieve only phoneNumbers starting by the provided value.
      Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phone-numbers?internalNumber=123
    • pbxUserId: allow to retrieve only phoneNumbers having the provided pbxUserId value.
      Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phone-numbers?pbxUserId=123
    • isMonitored: allow to retrieve only phoneNumbers for which monitoring in Rainbow application is activated (true) or deactivated (false).
      Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phone-numbers?isMonitored=true
    • isAssignedToUser: allow to retrieve only phoneNumbers being associated (true) or not (false) to a Rainbow user.
      Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phone-numbers?isAssignedToUser=true
    • userId: allow to retrieve only phoneNumbers being associated to the requested Rainbow user id.
      Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phone-numbers?userId=57960e4fa1ab69c4243415b1
    • companyPrefix: allow to retrieve only phoneNumbers having the provided companyPrefix value. See below 'Sharing a system between several companies'
      Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phone-numbers?companyPrefix=8210 This filter is not taken in account for role admin.
  • Filters can be combined.
    Example: retrieve the list of phoneNumbers being associated to a Rainbow user and for which monitoring is enabled in Rainbow application: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phone-numbers?isAssignedToUser=true&isMonitored=true


Specific feature: Sharing a system between several companies
Since 1.47.0 release, configuring companies sharing a multi-tenant system is possible.
An OXE or third_party system can be multi-company.
A multi-tenant system, so called CENTREX, allows sharing a call-server between several entities.
When directoryNumber are got from this system two more data are available: "companyName", "companyPrefix".
These data are stored and it's now possible to get all phoneNumbers having the given "companyPrefix".
A company-admin can only see, then give to a rainbow user, numbers of his company.
Note that these data are stored only if the system is declared with `isCentrex`=true, otherwise they are ignored.
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
shortNumber
string

Allow to filter phoneNumbers list on phoneNumbers having shortNumber field starting with the provided value.

internalNumber
string

Allow to filter phoneNumbers list on phoneNumbers having internalNumber field starting with the provided value.

pbxUserId
string

Allow to filter phoneNumbers list on phoneNumbers having pbxUserId field equal to provided value.

companyPrefix
string

When the system is a centrex server (multi-tenant OXE or third_party), allow to filter phoneNumbers list on companyPrefix.
The companyPrefix value to set is named 'tenantCallNumber' in companies data model.
Example: companyPrefix=8210: return all phoneNumbers having the prefix 8210, then allocated to the company having the 'tenantCallNumber' 8210 (exact match)

isMonitored
boolean
Enum: true false

Allow to filter phoneNumbers list on phoneNumbers having isMonitored field equal to provided value.

name
string

Allow to filter phoneNumbers list on phoneNumbers having firstName or lastName starting with the provided value.

nameOrShortNumber
string

Allow to filter phoneNumbers list on phoneNumbers having either firstName, lastName or shortNumber starting with the provided value.

nameOrShortNumber filter can't be used with name or shortNumber filters

deviceName
string

Allow to filter phoneNumbers list on phoneNumbers having deviceName field equal to provided value.

userType
string
Enum: "CCD" "agent" "Pro" "ACD"

Allow to filter phoneNumbers list on phoneNumbers having userType field equal to provided value.

isAssignedToUser
boolean
Enum: true false

Allow to filter phoneNumbers list on phoneNumbers being assigned or not to a Rainbow user, according to provided value.

  • true: return all phoneNumbers having userId !== null
  • false: return all phoneNumbers having userId === null
format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less phone numbers details in response.
- small: id shortNumber internalNumber numberE164
- medium: id shortNumber internalNumber voiceMailNumber number numberE164 isFromSystem pbxId systemId
- full: all phone numbers fields

limit
number
Default: 100

Allow to specify the number of phone numbers to retrieve.

offset
number

Allow to specify the position of first phone number to retrieve (first phone number if not specified). Warning: if offset > total, no results are returned.

sortField
string
Default: "shortNumber"

Sort phone numbers list based on the given field.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting phone numbers list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 2
}

Get a system phone number

This API allows to retrieve a specific phoneNumber associated to a given system (pbx).

Users with superadmin or support role can retrieve phoneNumbers from any system.
bp_admin can only retrieve phoneNumbers linked to systems of End Customer companies for which their bp_admin's company is the BP company.
Users with admin role (and not having superadmin nor support role) can only retrieve phoneNumbers of systems that they manage.
In a Multi-Layer organization that describes a hierarchy including ORGANIZATIONS/COMPANIES/SITES/SYSTEMS, an admin role of a upper layer is allowed to see systems within their's reach.

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phoneNumbers/5790fd2256b61a4d865839fe

Specific feature: Sharing a system between several companies
Since 1.47.0 release, configuring companies sharing a multi-tenant system is possible.
An OXE or third_party system can be multi-company.
A multi-tenant system, so called CENTREX, allows sharing a call-server between several entities.
When a company-admin or a site-admin wants to get one of the directoryNumber of this system we have to check if the "tenantCallNumber" of his company matches with "companyPrefix".
Else an HTTP error 404 Not Found is thrown.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

phoneNumberId
required
string

PhoneNumber unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a system phone number

This API allows to update a phone number for a given system (pbx).

It can be used to link a system phoneNumber to a Rainbow user by setting userId parameter. If userId parameter is provided, jid_im, jid_tel, jid_password and rainbowNumber of the corresponding user are automatically set in phoneNumber.

It can also be used to enable monitoring of this phoneNumber by PCG (set isMonitored parameter to true).

Note that pbxId, systemId, shortNumber and pbxUserId can't be modified.

When the phoneNumber is updated with this API, PCG is notified on its corresponding JID pbxpcg with the following XMPP iq:

<iq id="8413b42e-563c-4437-9a53-06f638b5ab69_0"
          from="pcloud@openrainbow.com/172440802160413612281463752830017532"
          to="pbxpcg_7ca2d0aefb024c949303b508fcecdad2@openrainbow.com"
          xmlns="jabber:client">
     <config xmlns="urn:xmpp:pbxagent:config:1">
         <user action="update"/>
            <shortNumber>1001</shortNumber>
            <internalNumber>20001</internalNumber>
            <voiceMailNumber>9999</voiceMailNumber>
            <numberE164>+33300001001</numberE164>
            <isMonitored>false</isMonitored>
            <userId>57960e4fa1ab69c4243415b1</userId>
            <jid_im>82fc7375cf34403a9c711ae7eda0929f@openrainbow.com</jid_im>
            <jid_tel>tel_82fc7375cf34403a9c711ae7eda0929f@openrainbow.com</jid_tel>
            <jid_password>fd6806bca74942598f57c288b0d50baa</jid_password>
     </config>
</iq>

The API waits that PCG has taken into account the phoneNumber update before processing the update in database and sending the response to client.

Rights depending on logged in user's roles:

  • Users with superadmin role can update phoneNumbers objects of any system.
  • bp_admin can only update phoneNumbers linked to systems of End Customer companies for which their bp_admin's company is the BP company.
  • Users with admin role (and not having superadmin) can only update phoneNumbers objects on systems that they manage. In a Multi-Layer organization that describes a hierarchy including ORGANIZATIONS/COMPANIES/SITES/SYSTEMS, an admin role of a upper layer is allowed to see systems within their's reach.

Sharing a system between several companies:
Since 1.47.0 release, configuring companies sharing a multi-tenant system is possible.
An OXE or third_party system can be multi-company. A multi-tenant system, so called CENTREX, allows sharing a call-server between several entities. For us an entity is a company with the flag isCentrex=true.
It's not possible to update the internalNumber for a phone number supplied by this kind of system. The specific error "internalNumber 3000 is readonly because it belongs to a multi-tenant system","errorDetailsCode": 409553 is thrown.

CCD use cases:
In the case if the CCD feature, a user can have 2 phoneNumbers assigned (a main and a secondary phoneNumbers).
The first CCD phoneNumber assigned to a user becomes his main phoneNumber, the second CCD phoneNumber assigned becomes his secondary phoneNumber. Depending on the CCD phoneNumbers assigned to the user, three use cases are defined:

  • CCD Default:
    • main phoneNumber => userType=CCD Agent / deviceName=CCD Agent|Remote Extension
    • secondary phoneNumber is not visible on the user but directly assigned at PCG level from a pool of phoneNumbers having userType=Pro ACD / deviceName=Remote Extension
  • CCD Fixed:
    • main phoneNumber => userType=CCD Agent / deviceName=CCD Agent|Remote Extension
    • secondary phoneNumber => userType=Pro ACD / deviceName=Remote Extension
  • CCD Mixed:
    • main phoneNumber => userType=Pro ACD / deviceName=Remote Extension
    • secondary phoneNumber => userType=CCD Agent / deviceName=CCD Agent|Remote Extension A field ccdRole describes if the phoneNumber corresponds to the main or secondary phoneNumber of the user.
      A field ccdMode describes which CCD use case is applied to the user (default, fixed or mixed).
      The user must have the feature TELEPHONY_CCD_AGENT_PROFILE to be able to use the CCD Fixed or CCD Mixed use cases (the check done when assigning the secondary phoneNumber to the user)

Example: PUT https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phoneNumbers/5790fd2256b61a4d865839fe

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

phoneNumberId
required
string

PhoneNumber unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
forceAttach
boolean
Default: false

In the case the phoneNumber is requested to be assigned to a user having already another phoneNumber assigned and forceAttach is set to true, the API will automatically dissociate the other phoneNumber from this user before assigning the requested phoneNumber to this user. If forceAttach is disabled, an error is returned in this case (legacy behavior).

Details of use cases handled by forceAttach:

  • "Standard" use case: in the case the phoneNumber is requested to be assigned to a user having already another phoneNumber assigned, the API will automatically dissociate the other phoneNumber from this user before assigning the requested phoneNumber to this user. In the case the user was configured with CCD phoneNumber(s), the API will automatically dissociate the secondary CCD phoneNumber and the main CCD phoneNumber from this user.
  • CCD use cases:
    • in the case the phoneNumber is requested to be assigned as secondary CCD phoneNumber on a user having already another secondary CCD phoneNumber assigned, the API will automatically dissociate the previous secondary CCD phoneNumber from this user before assigning the requested phoneNumber to this user as secondary CCD phoneNumber.
    • in the case the phoneNumber is requested to be assigned as main CCD phoneNumber on a user having already another main CCD phoneNumber and a secondary CCD phoneNumber assigned, the API will automatically:
      • dissociate the secondary CCD phoneNumber from this user (if any)
      • dissociate the previous main CCD phoneNumber from this user
      • assign the requested phoneNumber to this user as main CCD phoneNumber
      • re-assign the secondary CCD phoneNumber to this user (if any)
    • in the case the phoneNumber is not a CCD phoneNymber and is requested to be assigned on a user having a main CCD phoneNumber and a secondary CCD phoneNumber assigned, the API will automatically:
      • dissociate the secondary CCD phoneNumber from this user (if any)
      • dissociate the main CCD phoneNumber from this user
      • assign the requested phoneNumber to this user
    • in the case the phoneNumber is requested to be dissociated while being currently assigned as main CCD phoneNumber on a user, the API will automatically:
      • dissociate the secondary CCD phoneNumber from this user (if any)
      • dissociate the requested main CCD phoneNumber from this user
  • if forceAttach is NOT set to false, the API returns an error in the cases detailed above (legacy behavior).
Request Body schema: application/json
deviceName
string

device name

deviceType
string
Default: "landline"
Enum: "landline" "mobile" "fax" "other"

Phone number device type
Note that the deviceType of phoneNumbers linked to a PBX (isFromSystem=true) can't be changed (their value must be landline)

firstName
string

firstname

internalNumber
string

Internal phone number. Usable within a PBX group. By default, it is equal to shortNumber.
internalNumber must be unique in the whole system group to which the related PhoneNumber belong (an error 409 is raised if someone tries to update internalNumber to a number already used by another PhoneNumber in the same system group).

isMonitored
boolean

Specifies if the PhoneNumber is monitored by agent (i.e. telephony events are notified to Rainbow user through XMPP)

isRedirectNumberEditable
boolean

Allows a user to edit its redirect phone number

isVisibleByOthers
boolean

Allow user to choose if the phone number is visible by other users or not.
Note that administrators can see all the phone numbers, even if isVisibleByOthers is set to false.
Note that phone numbers linked to a system (isFromSystem=true) are always visible, isVisibleByOthers can't be set to false for these numbers.

lastName
string

lastname

number
string

Raw phone number (DDI) Note: If numberE164 can't be computed from number and computed country fields, an error 400 is returned (ex: wrong phone number, phone number not matching country code, ...)

redirectNumber
string

User redirect phone number

type
string
Default: "work"
Enum: "home" "work" "other"

Phone number type
Note that the type of phoneNumbers linked to a PBX (isFromSystem=true) can't be changed (their value must be work)

userId
string

Rainbow userId to which is linked the phoneNumber

Responses

Request samples

Content type
application/json
{
  • "deviceName": "string",
  • "deviceType": "landline",
  • "firstName": "string",
  • "internalNumber": "string",
  • "isMonitored": true,
  • "isRedirectNumberEditable": true,
  • "isVisibleByOthers": true,
  • "lastName": "string",
  • "number": "string",
  • "redirectNumber": "string",
  • "type": "work",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Systems Phone Numbers Multi Companies

Get all companyPrefix for a isCentrex system

Sharing a system between several companies
Since 1.47.0 release, configuring companies sharing a multi-tenant system is possible.
An OXE or third_party system can be multi-company.
A multi-tenant system, so called CENTREX, allows sharing a call-server between several entities.
When directoryNumber are got from this system two more data are available: "companyName", "companyPrefix".
These data are stored and it's now possible to get all "companyPrefix".

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

Response samples

Content type
application/json
{
  • "data": [ ]
}

Systems Telephony Keys

Remove one Phone touch of a system

This API can be used to delete one programmable phone touch of a user or of a company's keys group.
Example: DELETE https://openrainbow.com/api/rainbow/admin/v1.0/systems/56d0277a0261b53142a5cab5/telephony-keys/60e45024c8da191a7051575c

Remaining telephony keys are returned as data.


A message stanza is sent to each user having selected this key. This is an asynchronous task!

<message type="management" id="1644ac58-c69c-4a15-879c-3faf5ee329a7_0"
       to="ab353de6856e442b88f96f68e55f474a@francky1-all-in-one-rd-dev-1.opentouch.cloud" xmlns="jabber:client">
 <telephony-key keyId="60e6bfeed32f29208298d209" xmlns="jabber:iq:configuration" action="delete">
     <type>speedDialing</type>
     <origin>personal</origin>
     <locked>false</locked>
     <name>Mom</name>
     <number>0388000001</number>
 </telephony-key>
</message>
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 56d0277a0261b53142a5cab5)

keyId
required
string

Telephony key unique identifier

Responses

Response samples

Content type
application/json
{
  • "status": "Telephony key 60e45024c8da191a7051575c successfully deleted",
  • "data": {
    }
}

Update one Phone touch shareable

This API can be used to modify one programmable phone touch of a system, users or company's group linked with this system can share.


A message stanza is sent to each user having selected this key. This is an asynchronous task!

<message type="management" id="1644ac58-c69c-4a15-879c-3faf5ee329a7_0"
       to="ab353de6856e442b88f96f68e55f474a@francky1-all-in-one-rd-dev-1.opentouch.cloud" xmlns="jabber:client">
 <telephony-key keyId="60e6bfeed32f29208298d209" xmlns="jabber:iq:configuration" action="update">
     <type>speedDialing</type>
     <origin>shared</origin>
     <locked>true</locked>
     <active>true</active>
     <name>CareTaker</name>
     <number>0388000001</number>
 </telephony-key>
</message>
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 56d0277a0261b53142a5cab5)

keyId
required
string

Telephony key unique identifier

Request Body schema: application/json
active
boolean

This key can be used directly by a user.

featureCodeSubType
string

For featureCode key type only, this is the type of the field number

  • dial – a number to dial
  • dtmf – a DTMF sequence
featureCodeSupportedTelStates
Array of strings

For featureCode key type only, this are supported telephony states [optional] The supported telephony state is the list of telephony state which are compatible with the feature code.

  • Example: the call back request must be played in ringing state
locked
boolean

The key is created by an administrator and can't be updated by the end user

name
string [ 1 .. 32 ] characters

Label of the key

number
string [ 1 .. 32 ] characters

The key content for keys of type speedDialing and featureCode.

restrictedUse
boolean

The key is created by an administrator for some users sharing the same system (PBX). It is assigned by an administrator only

  • When restrictedUse is set to true, the body parameter <b>active</b> is ignored and the key is forced to inactive state (active = false)
type
string

The type of the key

  • speedDialing – contains a number to dial
  • featureCode – contains either a dialing code or a multi-frequency code

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "featureCodeSubType": "string",
  • "featureCodeSupportedTelStates": [
    ],
  • "locked": true,
  • "name": "string",
  • "number": "string",
  • "restrictedUse": true,
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Programmable Phone touch shareable

This API can be used to list all the programmable phone touch of a system.

This keys can be of different types:

  • Speed dialing – contains a number to dial
  • Feature code – contains either a dialing code or a MF code

All of them are managed by an administrator, and some of them can be locked to prevent the end user to override the content.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 56d0277a0261b53142a5cab5)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add one Phone touch shareable

This API can be used to create one programmable phone touch of a system, users linked with this system can share.

This keys can be of different types:

  • Speed dialing – contains a number to dial
  • Feature code – contains either a dialing code or a MF code

By default shareable key are locked and active at creation.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 56d0277a0261b53142a5cab5)

Request Body schema: application/json
active
boolean

This key can be used directly by a user.

featureCodeSubType
string

For featureCode key type only, this is the type of the field number

  • dial – a number to dial
  • dtmf – a DTMF sequence
featureCodeSupportedTelStates
Array of strings

For featureCode key type only, this are supported telephony states [optional] The supported telephony state is the list of telephony state which are compatible with the feature code.

  • Example: the call back request must be played in ringing state
locked
boolean

The key is created by an administrator and can't be updated by the end user

name
required
string [ 1 .. 32 ] characters

Label of the key

number
string [ 1 .. 32 ] characters

The key content for keys of type speedDialing and featureCode.

restrictedUse
boolean

The key is created by an administrator for some users sharing the same system (PBX). It is assigned by an administrator only

type
required
string

The type of the key

  • speedDialing – contains a number to dial
  • featureCode – contains either a dialing code or a multi-frequency code

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "featureCodeSubType": "string",
  • "featureCodeSupportedTelStates": [
    ],
  • "locked": true,
  • "name": "string",
  • "number": "string",
  • "restrictedUse": true,
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get shared key assigned to a user

This API can be used to get the list of shared telephony keys already assigned to a user.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 56d0277a0261b53142a5cab5)

userId
required
string

User unique identifier

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Assign one shared key to a user or to a company keys group

This API can be used to assign one programmable phone touch of a system, users or company keys group linked with this system use.

If the key assigned is active (active = true), then the feature keys bellow are taken into account before the assigment. (errorDetailCode: 403620)

  • TELEPHONY_MAX_SPEED_DIALING_KEYS
  • TELEPHONY_MAX_FEATURE_CODE_KEYS


A message stanza is sent to the user to warn him a new key is available.

<message type="management" id="1644ac58-c69c-4a15-879c-3faf5ee329a7_0"
       to="ab353de6856e442b88f96f68e55f474a@francky1-all-in-one-rd-dev-1.opentouch.cloud" xmlns="jabber:client">
 <telephony-key keyId="60e6bfeed32f29208298d209" xmlns="jabber:iq:configuration" action="add">
     <type>speedDialing</type>
     <origin>shared</origin>
     <locked>true</locked>
     <active>true</active>
     <name>CareTaker</name>
     <number>0388000001</number>
 </telephony-key>
</message>
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 56d0277a0261b53142a5cab5)

keyId
required
string

Telephony key unique identifier

query Parameters
position
integer <int32>

By default the key is created in the top of the list. It's possible to insert it in another place. 0 is the first place.

Request Body schema: application/json
active
boolean

This key can be used directly by a user.

featureCodeSubType
string

For featureCode key type only, this is the type of the field number

  • dial – a number to dial
  • dtmf – a DTMF sequence
featureCodeSupportedTelStates
Array of strings

For featureCode key type only, this are supported telephony states [optional] The supported telephony state is the list of telephony state which are compatible with the feature code.

  • Example: the call back request must be played in ringing state
locked
boolean

The key is created by an administrator and can't be updated by the end user

name
string [ 1 .. 32 ] characters

Label of the key

number
string [ 1 .. 32 ] characters

The key content for keys of type speedDialing and featureCode.

restrictedUse
boolean

The key is created by an administrator for some users sharing the same system (PBX). It is assigned by an administrator only

  • When restrictedUse is set to true, the body parameter <b>active</b> is ignored and the key is forced to inactive state (active = false)
telephonyKeysGroupId
string

Telephony keys group of company unique identifier
note: If the userId parmeter is not specified, this one must be.

type
string

The type of the key

  • speedDialing – contains a number to dial
  • featureCode – contains either a dialing code or a multi-frequency code
userId
string

User unique identifier

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "featureCodeSubType": "string",
  • "featureCodeSupportedTelStates": [
    ],
  • "locked": true,
  • "name": "string",
  • "number": "string",
  • "restrictedUse": true,
  • "telephonyKeysGroupId": "string",
  • "type": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Unassign one shared key from a user or a company group

This API can be used to unassign one programmable phone touch of a system, users or company's keys group linked with this system use.


A message stanza is sent to the user to warn him a new key is available.

<message type="management" id="1644ac58-c69c-4a15-879c-3faf5ee329a7_0"
       to="ab353de6856e442b88f96f68e55f474a@francky1-all-in-one-rd-dev-1.opentouch.cloud" xmlns="jabber:client">
 <telephony-key keyId="60e6bfeed32f29208298d209" xmlns="jabber:iq:configuration" action="add">
     <type>speedDialing</type>
     <origin>shared</origin>
     <locked>true</locked>
     <active>true</active>
     <name>CareTaker</name>
     <number>0388000001</number>
 </telephony-key>
</message>
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
systemId
required
string

System unique identifier (like 56d0277a0261b53142a5cab5)

keyId
required
string

Telephony key unique identifier

Request Body schema: application/json
active
boolean

This key can be used directly by a user.

featureCodeSubType
string

For featureCode key type only, this is the type of the field number

  • dial – a number to dial
  • dtmf – a DTMF sequence
featureCodeSupportedTelStates
Array of strings

For featureCode key type only, this are supported telephony states [optional] The supported telephony state is the list of telephony state which are compatible with the feature code.

  • Example: the call back request must be played in ringing state
locked
boolean

The key is created by an administrator and can't be updated by the end user

name
string [ 1 .. 32 ] characters

Label of the key

number
string [ 1 .. 32 ] characters

The key content for keys of type speedDialing and featureCode.

restrictedUse
boolean

The key is created by an administrator for some users sharing the same system (PBX). It is assigned by an administrator only

  • When restrictedUse is set to true, the body parameter <b>active</b> is ignored and the key is forced to inactive state (active = false)
telephonyKeysGroupId
string

Telephony keys group of company unique identifier

type
string

The type of the key

  • speedDialing – contains a number to dial
  • featureCode – contains either a dialing code or a multi-frequency code
userId
string

User unique identifier

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "featureCodeSubType": "string",
  • "featureCodeSupportedTelStates": [
    ],
  • "locked": true,
  • "name": "string",
  • "number": "string",
  • "restrictedUse": true,
  • "telephonyKeysGroupId": "string",
  • "type": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Users

Delete a user

This API can be used to delete a user.

BP Admin and BP Finance users can only delete users being in a company linked to their BP company.
Admin users can only delete users being in their own company. (superadmin, organization_admin, company_admin)

Depending current user initialization, the behaviour to follow may change

  • user never initialized and never logged, user with the role 'guest':
    • delete the user from xmpp and database
  • user currently initialized or logged at least one time
    • change loginEmail, change rainbow password, change jid_password, warn clients about account deletion, disconnect all user's clients
    • delete personal phone numbers and free system phone numbers
    • flag pending invite as canceled
    • flag join company requests as canceled
    • for all rooms where the user privilege is not 'moderator' or not le last, he gets the status 'deleted'
    • for all rooms where the user is the last moderator, the room is 'archived', that is to say all users of the room get the status 'unsubscribed'
    • delete avatar and warn clients
    • set user flag 'isTerminated' and move him to the dedicated company 'Terminated'
The following XMPP message is sent to the user 2 seconds before his XMPP resources are disconnected: 
<message id="8413b42e-563c-4437-9a53-06f638b5ab69_0" type="management"
    from="pcloud_enduser_1@openrainbow.com/172440802160413612281463752830017532"
    to="5abb735b2d3c4e50adde276c50ec489c@@openrainbow.com"
    xmlns="jabber:client">
    <no-store xmlns="urn:xmpp:hints"/>
    <userterminated action="delete" xmlns="jabber:iq:configuration"/>
</message>

The following XMPP message is sent to all users being in deleted user's roster:

<message id="8413b42e-563c-4437-9a53-06f638b5ab69_0" type="management"
    from="pcloud_enduser_1@openrainbow.com/172440802160413612281463752830017532"
    to="5abb735b2d3c4e50adde276c50ec489c@@openrainbow.com"
    xmlns="jabber:client">
    <useraccount id="56c5c19f94141765119f896c" action="update" xmlns="jabber:iq:configuration"
</message>


Only a migration script is planned to delete permanently a user 'terminated' after a legal delay time.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56c5c19f94141765119f896c)

query Parameters
pendingTerminated
boolean
Value: false

Allows to pending the user account for 10 days before terminate it or restore it.
When true, the user is put in this “pending_termination” state rather than the “terminated” state. It remains in this state for a grace period of 10 days.

Notes:

  • This query parameter is not taken in account when the user comes from the 'default' company - Rainbow. Only users of customer's companies can be in grace period.
  • The company must have the feature COMPANY_USER_PENDING_TERMINATION to delete a user with grace period (without the feature, the user is immediately deleted, even if pendingTerminated parameter is set to true).

Responses

Response samples

Content type
application/json
{
  • "status": "User 56c5c19f94141765119f896c successfully disabled",
  • "data": {
    }
}

Get a user data

This API can be used to get a user.

Users with superadmin, business_admin, customer_success_admin, support role can retrieve any user whatever the company.
Users with sales_analytics role can retrieve users from companies they manage as sales.
Users with support role retrieve additional data lastLoginIOSDate and lastLoginAndroidDate.

Users with bp_admin or bp_finance role can only retrieve users from company being End Customers of their BP company (i.e. all the companies having bpId equal to their companyId).

Users with admin role can only retrieve users belonging to companies they can manage. That is to say:

  • an organization_admin can only get users belonging to a company he can manage (i.e. companies having organisationId equal to his organisationId)
  • a company_admin can only get a user being in his company
  • a site_admin can only get a user being in his company

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/users/56c5cb38e8078d7512c43985
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56c5c19f94141765119f896c)

query Parameters
format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less user details in response.

  • small: id, loginEmail, firstName, lastName, displayName, companyId, companyName, isTerminated
  • medium: id, loginEmail, firstName, lastName, displayName, jid_im, jid_tel, companyId, companyName, lastUpdateDate, lastAvatarUpdateDate, isTerminated, terminatedStatus, guestMode
  • full: all user fields

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a user

This API can be used to update data of a user.

A presence stanza is sent to updated user's resources and users being in user's roster. This allow clients to be notified that this user has been updated:

<presence from='3ae059e2a91c40d9bdd7df0eedc911ca@openrainbow.com'>
    <x xmlns='vcard-temp:x:update'>
        <data/>
    </x>
</presence>

Unlike end-user PUT /users/id API, this admin API allows to update these fields: loginEmail, password, roles and isActive.

A user can't modify his own roles.

Only superadmin users can update loginEmail field (but they can't update their own loginEmail).

Rights depending on logged in user's roles:

  • BP Admin and BP Finance users can only update users being in a company linked to their BP company.
  • Admin users can only update users being in their own company.
  • Support users can only update user password.
  • Business_admin users can only update roles of other users than himself.

When user password is changed:

  • if user account was locked (because of too many login attempts failures), user account will be unlocked once password is changed.
  • all user's previously generated authentication token (JWT) are revoked.
  • jid_password of user's jid_im and jid_tel is updated with a new password,
  • all connected jid_im and jid_tel resources are disconnected.
  • Therefore, clients have to login again with this user in order to retrieve a new valid authentication token JWT and its new jid_password.
  • the following XMPP message is sent to user's jid_im to warn that the password has changed:
    <message id="8413b42e-563c-4437-9a53-06f638b5ab69_0" type="management"
  from="pcloud_enduser_1@openrainbow.com/172440802160413612281463752830017532"
  to="5abb735b2d3c4e50adde276c50ec489c@@openrainbow.com"
  xmlns="jabber:client">
  <userpassword action="update" xmlns="jabber:iq:configuration"
</message>

Phone numbers:

In some cases, creating a user with guest role may be sufficient. Here are guest role specificity:

  • guest is a single role that can't be modified
  • Created by a company_admin only, in his company
  • Has limited rights to chat, audio and video conversations
  • Is never notified by email
  • Can't receive welcome message by Emily
  • Can't manage its password (reset)
  • By default, can't be search inside or outside his company
  • Can't be moved to another company
  • Definitely deleted (his user experience is not kept: conversations ...)
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56c5c19f94141765119f896c)

Request Body schema: application/json
adminType
string
Enum: "organization_admin" "company_admin" "site_admin"

Mandatory if roles array contains admin role: specifies at which entity level the administrator has admin rights in the hierarchy ORGANIZATIONS/COMPANIES/SITES/SYSTEMS

authenticationExternalUid
string

User external authentication ID Allows to authenticate the user based on an external identifier (company's SSO server (SAML or OIDC), Teams, Outlook, ...)

authenticationType
string
Enum: "DEFAULT" "RAINBOW" "SAML" "OIDC"

User authentication type (if not set company default authentication will be used)

companyId
string

User company unique identifier (like 569ce8c8f9336c471b98eda1)
companyName field is automatically filled on server side based on companyId.

country
string 3 characters

User country (ISO 3166-1 alpha3 format)

The list of allowed countries can be obtained using the API GET /api/rainbow/enduser/v1.0/countries

customData
object

User's custom data.
Object with free keys/values.
It is up to the client to manage the user's customData (new customData provided overwrite the existing one).

Restrictions on customData Object:

  • max 20 keys,
  • max key length: 64 characters,
  • max value length: 4096 characters.


User customData can only be created/updated by:
  • the user himself
  • `company_admin` or `organization_admin` of his company,
  • `bp_admin` and `bp_finance` of his company,
  • `superadmin`.
department
string [ 1 .. 255 ] characters

User department

Array of objects (putUsersEmails)

Array of user emails addresses objects

firstName
string [ 1 .. 255 ] characters

User first name

isActive
boolean
Default: true

Is user active

isInitialized
boolean
Default: false

Is user initialized

jobTitle
string [ 1 .. 255 ] characters

User job title

language
string/^([a-z]{2})(?:(?:(-)[A-Z]{2}))?$/

User language

Language format is composed of locale using format ISO 639-1, with optionally the regional variation using ISO 3166‑1 alpha-2 (separated by hyphen).
Locale part is in lowercase, regional part is in uppercase. Examples: en, en-US, fr, fr-FR, fr-CA, es-ES, es-MX, ...
More information about the format can be found on this link.

lastName
string [ 1 .. 255 ] characters

User last name

loginEmail
string [ 3 .. 255 ] characters

User email address (used for login).
Must be unique (409 error is returned if a user already exists with the same email address).

It's forbidden for any admin (superadmin, BP admin, EC admin) to update a terminated user, except the loginEmail when this user is in grace period

  • isTerminated = true
  • terminatedStatus = account_pending_termination
object

User phone number (used for login).

mfaRainbowPolicyId
string

Rainbow multifactor policy unique identifier (only if authenticationType is RAINBOW) Note: specifically in the case of users with admin rights (superadmin, admin,, bp_admin), a mfaRainbowPolicyId can be set even if authenticationType is set to a SSO method (this mfaRainbowPolicyId will be used by the admin in case the Rainbow authentication is used instead of SSO (fallback mechanism)).

nickName
string [ 1 .. 255 ] characters

User nickName

password
string [ 8 .. 64 ] characters

User password.

Rules:

  • more than 8 characters,
    • ⚠️ Warning: the minimal password length will soon be increased to 12, planned to be effective mid-june 2023 (8 characters are still accepted until this date)
  • at least 1 capital letter,
  • 1 number,
  • 1 special character.
Array of objects (putUsersPhoneNumbers)

Array of user PhoneNumbers objects

Provided PhoneNumbers data overwrite previous values:

  • PhoneNumbers which are not known on server side are added,
  • PhoneNumbers which are changed are updated,
  • PhoneNumbers which are not provided but existed on server side are deleted.
  • This does not applies to PhoneNumbers linked to a system (isFromSystem=true), which can only be updated (addition and deletion of system PhoneNumbers are ignored).

When number field is set, the server tries to compute the associated E.164 number (numberE164 field):

  • If number is already in E.164 format, the value is simply duplicated as is in numberE164 field, and country field is computed from this E.164 number,
  • Otherwise numberE164 is computed using provided number and country field (if country is provided this value is used, otherwise user's country is set in country field).
  • If numberE164 can't be computed from number and country fields, an error 400 is returned (ex: wrong phone number, phone number not matching country code, ...)

PhoneNumber linked to a system (isFromSystem=true) can also be updated. In that case, shortNumber and systemId of the existing system PhoneNumber must be provided with the fields to update (see example bellow).

System phoneNumbers can't be created nor deleted using this API, only PCG can create/delete system PhoneNumbers

rainbowPasswordlessPolicyId
string

Rainbow passwordless policy unique identifier (must correspond to a valid user's company's rainbowPasswordlessPolicies' passwordlessId).
Notes:

  • The passwordless policy set in user's rainbowPasswordlessPolicyId field is only used by the user if its authenticationType is set to RAINBOW (otherwise, if authenticationType is not set, the default company's authentication method is used).
  • Passwordless authentication is not compatible with Multi-Factor Authentication, so is the user has a MFA configuration, this one is cleared when Passwordless configuration is applied.
rainbowPasswordlessPolicyName
string

Rainbow passwordless policy name to set to the user (must correspond to a valid user's company's rainbowPasswordlessPolicies' passwordlessName).
Notes:

  • rainbowPasswordlessPolicyName is not saved in the user, the associated company's rainbowPasswordlessPolicies' passwordlessId is stored in rainbowPasswordlessPolicyId,
  • The passwordless policy set in user's rainbowPasswordlessPolicyId field is only used by the user if its authenticationType is set to RAINBOW (otherwise, if authenticationType is not set, the default company's authentication method is used).
  • Passwordless authentication is not compatible with Multi-Factor Authentication, so is the user has a MFA configuration, this one is cleared when Passwordless configuration is applied. This parameter is meant to apply the passwordless policy using its name, especially from CSV file (as admins don't know the rainbowPasswordlessPolicyId).

    Rainbow passwordless policy can be unset by setting rainbowPasswordlessPolicyName to null or empty String ("").
rainbowPasswordlessPolicySendToEmail
string

Optional email used to send passwordless code to the user (instead of his loginEmail address) when passwordless authentication is enabled and the associated company's passwordless policy has sendEmail=true.
rainbowPasswordlessPolicySendToEmail can be unset by setting its value to null or empty String ("").

roles
Array of strings
Default: ["user"]
Items Enum: "guest" "user" "admin" "bp_admin" "bp_finance" "ec_analytics" "company_support" "all_company_channels_admin" "public_channels_admin" "closed_channels_admin" "all_organization_channels_admin" "organization_public_channels_admin" "organization_closed_channels_admin" "app_admin" "app_support" "app_superadmin" "directory_admin" "supervisor" "support" "superadmin" "webinar_host" "attendant"

List of user roles

The general rule is that a user must have the roles that the wants to assign to someone else.

Examples:

  • an admin can add or remove the role admin to another user of the company(ies) he manages,
  • an bp_admin can add or remove the role bp_admin to another user of the company(ies) he manages,
  • an app_superadmin can add or remove the role app_superadmin to another user...

Here are some explanations regarding the roles available in Rainbow:

  • admin, bp_admin and bp_finance roles are related to company management (and resources linked to companies, such as users, systems, subscriptions, ...).
  • bp_admin and bp_finance roles can only be set to users of a BP company (company with isBP=true).
  • app_admin, app_support and app_superadmin roles are related to application management.
  • all_company_channels_admin, public_channels_admin and closed_channels_admin roles are related to channels management.
  • ec_analytics role allows a user to consult its own analytics.
  • supervisor allows users to supervise (telephony) other users from their company.
    • This role can be assigned manually to a user using this API, otherwise it is automatically set when a user is a added to a supervision group as supervisor.
    • This role can be removed manually to a user using the PUT /api/rainbow/admin/v1.0/users/:userId API, in that case the user is automatically removed from all the supervision groups in which he was supervisor.
    • This role is automatically removed from a user when he is removed from the last supervision group in which he was supervisor.
  • A user with webinar_host role will be able to create webinars. Note: to be able to give this role, company should first subscribe to a webinar offer.
  • A user with attendant role will be the attendant of the Cloud PBX of its company. Note : to be able to give this role, feature TELEPHONY_BASIC_ATTENDANT_CONSOLE must be available for the user , as so this role cannot be assigned during User creation
  • A user with admin rights (admin, bp_admin, superadmin) can't change his own roles, except for roles related to channels (all_company_channels_admin, public_channels_admin and closed_channels_admin).
  • Only superadmin can set superadmin and support roles to a user.
selectedDeviceFirmware
string
Default: "same_as_company"
Enum: "same_as_company" "released" "latest"

Cloudpbx default device firmware

  • same_as_company: Default value. Device firmware for the user's devices will be the one defined at company level.
  • released: Device firmware will be the official released one.
  • latest: Device firmware can be a more up to date binary (e.g. early adopters)
    If allowed by superadmin, company admin can then select the kind of firmware for all the users, or only for some of them.
selectedTheme
string

Set the selected theme for the user.

siteId
string

User company site unique identifier (like 569ce8c8f9336c471b98eda2)

state
string
Enum: "null" "AA" "AE" "AP" "AK" "AL" "AR" "AZ" "CA" "CO" "CT" "DC" "DE" "FL" "GA" "GU" "HI" "IA" "ID" "IL" "IN" "KS" "KY" "LA" "MA" "MD" "ME" "MI" "MN" "MO" "MS" "MT" "NC" "ND" "NE" "NH" "NJ" "NM" "NV" "NY" "OH" "OK" "OR" "PA" "PR" "RI" "SC" "SD" "TN" "TX" "UT" "VA" "VI" "VT" "WA" "WI" "WV" "WY" "AB" "BC" "MB" "NB" "NL" "NS" "NT" "NU" "ON" "PE" "QC" "SK" "YT"

When country is 'USA' or 'CAN', a state can be defined. Else it is not managed (null).

The list of allowed states can be obtained using the API GET /api/rainbow/enduser/v1.0/countries for the associated countries.

  • List of allowed states for USA:
    • AA: "Armed Forces America",
    • AE: "Armed Forces",
    • AP: "Armed Forces Pacific",
    • AK: "Alaska",
    • AL: "Alabama",
    • AR: "Arkansas",
    • AZ: "Arizona",
    • CA: "California",
    • CO: "Colorado",
    • CT: "Connecticut",
    • DC: Washington DC",
    • DE: "Delaware",
    • FL: "Florida",
    • GA: "Georgia",
    • GU: "Guam",
    • HI: "Hawaii",
    • IA: "Iowa",
    • ID: "Idaho",
    • IL: "Illinois",
    • IN: "Indiana",
    • KS: "Kansas",
    • KY: "Kentucky",
    • LA: "Louisiana",
    • MA: "Massachusetts",
    • MD: "Maryland",
    • ME: "Maine",
    • MI: "Michigan",
    • MN: "Minnesota",
    • MO: "Missouri",
    • MS: "Mississippi",
    • MT: "Montana",
    • NC: "North Carolina",
    • ND: "North Dakota",
    • NE: "Nebraska",
    • NH: "New Hampshire",
    • NJ: "New Jersey",
    • NM: "New Mexico",
    • NV: "Nevada",
    • NY: "New York",
    • OH: "Ohio",
    • OK: "Oklahoma",
    • OR: "Oregon",
    • PA: "Pennsylvania",
    • PR: "Puerto Rico",
    • RI: "Rhode Island",
    • SC: "South Carolina",
    • SD: "South Dakota",
    • TN: "Tennessee",
    • TX: "Texas",
    • UT: "Utah",
    • VA: "Virginia",
    • VI: "Virgin Islands",
    • VT: "Vermont",
    • WA: "Washington",
    • WI: "Wisconsin",
    • WV: "West Virginia",
    • WY: "Wyoming"
  • List of allowed states for CAN:
    • AB: "Alberta",
    • BC: "British Columbia",
    • MB: "Manitoba",
    • NB: "New Brunswick",
    • NL: "Newfoundland and Labrador",
    • NS: "Nova Scotia",
    • NT: "Northwest Territories",
    • NU: "Nunavut",
    • ON: "Ontario",
    • PE: "Prince Edward Island",
    • QC: "Quebec",
    • SK: "Saskatchewan",
    • YT: "Yukon"
tags
Array of strings

An Array of free tags associated to the user.
A maximum of 5 tags is allowed, each tag can have a maximum length of 64 characters.
tags can only be set by users who have administrator rights on the user. The user can't modify the tags.
The tags are visible by the user and all users belonging to his organisation/company, and can be used with the search API to search the user based on his tags.

timeToLive
number

Duration in second to wait before automatically starting a user deletion from the creation date.
Once the timeToLive has been reached, the user won't be usable to use APIs anymore (error 401523). His account may then be deleted from the database at any moment.
Value -1 means timeToLive is disable (i.e. user account will not expire).
If created user has role guest and no timeToLive is provided, a default value of 172800 seconds is set (48 hours).
If created user does not have role guest and no timeToLive is provided, a default value of -1 is set (no expiration).

timezone
string

User timezone name
Allowed values: one of the timezone names defined in IANA tz database
Timezone name are composed as follow: Area/Location (ex: Europe/Paris, America/New_York,...)

title
string [ 1 .. 40 ] characters

User title (honorifics title, like Mr, Mrs, Sir, Lord, Lady, Dr, Prof,...)

userInfo1
string [ 0 .. 64 ] characters

Free field that admin can use to link their users to their IS/IT tools / to perform analytics (this field is output in the CDR file)

userInfo2
string [ 0 .. 64 ] characters

2nd Free field that admin can use to link their users to their IS/IT tools / to perform analytics (this field is output in the CDR file)

visibility
string
Enum: "same_than_company" "public" "private" "closed" "isolated" "hotspot" "none"

User visibility
Define if the user can be searched by users being in other company and if the user can search users being in other companies.
Visibility can be:

  • same_than_company: The same visibility than the user's company's is applied to the user. When this user visibility is used, if the visibility of the company is changed the user's visibility will use this company new visibility.
  • public: User can be searched by external users / can search external users. User can invite external users / can be invited by external users
  • private: User can't be searched by external users / can search external users. User can invite external users / can be invited by external users
  • closed: User can't be searched by external users / can't search external users. User can invite external users / can be invited by external users
  • isolated: User can't be searched by external users / can't search external users. User can't invite external users / can't be invited by external users
  • hotspot: User can be searched by hotspot attached company's users (users from any company if the user belong to the default company) / can't search any users (even in their company) | user can't invite external users / can be invited by hotspot attached company's users (users from any company if the user belong to the default company)
  • none: Default value reserved for guest. User can't be searched by any users (even within the same company) / can search external users. User can invite external users / can be invited by external users External users mean 'public user not being in user's company nor user's organisation nor a company visible by user's company.

Responses

Request samples

Content type
application/json
{
  • "adminType": "organization_admin",
  • "authenticationExternalUid": "string",
  • "authenticationType": "DEFAULT",
  • "companyId": "string",
  • "country": "str",
  • "customData": { },
  • "department": "string",
  • "emails": [
    ],
  • "firstName": "string",
  • "isActive": true,
  • "isInitialized": false,
  • "jobTitle": "string",
  • "language": "string",
  • "lastName": "string",
  • "loginEmail": "string",
  • "loginPhone": {
    },
  • "mfaRainbowPolicyId": "string",
  • "nickName": "string",
  • "password": "stringst",
  • "phoneNumbers": [
    ],
  • "rainbowPasswordlessPolicyId": "string",
  • "rainbowPasswordlessPolicyName": "string",
  • "rainbowPasswordlessPolicySendToEmail": "string",
  • "roles": [
    ],
  • "selectedDeviceFirmware": "same_as_company",
  • "selectedTheme": "string",
  • "siteId": "string",
  • "state": "null",
  • "tags": [
    ],
  • "timeToLive": 0,
  • "timezone": "string",
  • "title": "string",
  • "userInfo1": "string",
  • "userInfo2": "string",
  • "visibility": "same_than_company"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "mfaRainbowAuth": {
    },
  • "rainbowPasswordlessPolicy": {
    },
  • "useExternalStorage": "same_than_company",
  • "useRainbowStorage": "same_than_company",
  • "mainStorage": "Rainbow Storage"
}

Restore a pending user account deletion

Instead of deactivate a user account definitely, it is allowed to pending the user account for 10 days before terminate it or restore it.
DELETE /api/rainbow/admin/v1.0/users/:userId?pendingTermination=true All Admin can restore this user to active state, during this grace period of 10 days, upon request to support, using this API. When restored, the user recovers all information (IM, bubbles etc) he had before, but some services are not restored as Phone association, licenses, admin roles.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56c5c19f94141765119f896c)

Responses

Response samples

Content type
application/json
{
  • "status": "User 56c5c19f94141765119f896c successfully restored",
  • "data": {
    }
}

Confirm a pending user account deletion

Instead of deactivate a user account definitely, it is allowed to pending the user account for 10 days before terminate it or restore it.
DELETE /api/rainbow/admin/v1.0/users/:userId?pendingTermination=true All Admin can stop the grace period, upon request to support, using this API. Then, the loginEmail is changed, and some user data are discarded.

No mail is sent to the enduser because it was already sent when the user account was set to "account_pending_termination" status.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56c5c19f94141765119f896c)

Responses

Response samples

Content type
application/json
{
  • "status": "User 56c5c19f94141765119f896c successfully disabled",
  • "data": {
    }
}

Get all users

This API allows administrators to list users.

Users with superadmin, business_admin, customer_success_admin, support role can retrieve users from any company.
Users with sales_analytics role can retrieve users from companies they manage as sales.
Users with support role can retrieve lastLoginIOSDate and lastLoginAndroidDate providing format option full.

Users with bp_admin, sales_analytics or bp_finance role retrieve only users from company being End Customers of their BP company (i.e. all the companies having bpId equal to their companyId).

Users with admin role retrieve only users belonging to companies they can manage. That is to say:

  • an organization_admin gets all users belonging to each companies he manages (i.e. companies having organisationId equal to his organisationId)
  • a company_admin gets all users being in his company
  • a site_admin gets all users being in his company

Note:
  • To hide GUEST, the filter roles=user is applied by default. Then all multi-roles like admin, bp_admin or bp_finance stay retrievable.
    To get only guest belonging to a company, use GET /api/rainbow/admin/v1.0/users?roles=guest

This API can return more or less user information using format option in query string arguments (default is small).
This API implement pagination, using limit and offset options in query string arguments (default is limit on 100 users). Result sorting can also be done using sort and order options (default is sort on displayName on ascending order).

This API allows to filter results on several criterion by providing appropriate options in query string arguments (displayName, companyName, loginEmail, jid_im, jid_tel, companyId).

Examples:
  • basic: GET https://openrainbow.com/api/rainbow/admin/v1.0/users
  • with format options: GET https://openrainbow.com/api/rainbow/admin/v1.0/users?format=full
  • with pagination options: GET https://openrainbow.com/api/rainbow/admin/v1.0/users?limit=10&offset=20&sortField=loginEmail&sortOrder=-1
  • with filter options: GET https://openrainbow.com/api/rainbow/admin/v1.0/users?displayName=john doe&companyId=56d6f0d441255dd54b5b61b3 56b89d26f7ab94c69ad41584
Authorizations:
BearerBearer-x-rainbow-api-key
query Parameters
phoneNumbers
number

Allows to filter users list on the given number(s) on their phoneNumbers on the following fields (exact match):

  • shortNumber
  • internalNumber
  • number
  • numberE164
phoneNumber
number

Allows to filter users list on the given number(s) on field phoneNumbers.internalNumber (number starts with requested string).

searchEmail
string

Allows to filter users list on the loginEmail field using the word provided in this option.

companyId
string

Allows to filter users list on the companyIds provided in this option.

In the case of admin (without superadmin, support roles), provided companyIds should correspond to companies visible by logged in user's company (if some of the provided companyId are not visible by logged in user's company, users from these companies will not be returned).

siteId
string

Allows to filter users list on the siteIds provided in this option.

In the case of admin (without superadmin, support roles), provided siteIds should correspond to sites from companies visible by logged in user's company (if some of the provided siteIds are not visible by logged in user's company, users from these companies will not be returned).

roles
string
Default: "user"

Allows to filter users list on the role(s) provided in this option.

This allow for example to get all users with role bp_admin.
By default, only users having (at least) the role user are listed.

excludeRoles
string

Allows to exclude users having the role(s) provided in this option.

This allow for example to exclude users with role tv from the results.

tags
string

Allows to filter users list on the tag(s) provided in this option.

departments
string

Allows to filter users list on the department(s) provided in this option.

includePendingTermination
string
Default: "false"

Specifies that the users being terminated but still with the status account_pending_termination have to be included in the results.

Notes:

  • when includePendingTermination query parameter is provided with value true, isTerminated filter is ignored and replaced by the condition "isTerminated=false OR terminatedStatus=account_pending_termination".
  • when includePendingTermination query parameter is provided with value true, terminatedStatus filter is ignored and replaced by the condition "isTerminated=false OR terminatedStatus=account_pending_termination".
isTerminated
string
Default: "false"

Allows to filter users list on the status 'isTerminated'.

By default, terminated users are not listed.

Notes:

  • when terminatedStatus query parameter is provided, isTerminated filter is ignored and forced to true.
  • when includePendingTermination query parameter is provided with value true, isTerminated filter is ignored and replaced by the condition "isTerminated=false OR terminatedStatus=account_pending_termination".
terminatedStatus
string
Enum: "account_pending_termination" "account_deactivated" "account_anonymized"

Allows to filter users on their terminatedStatus.

terminatedStatus query parameter will help BP/EC admin to see users in account_pending_termination state (see DELETE /api/rainbow/admin/v1.0/users?pendingTerminated=true)

Notes:

  • when terminatedStatus query parameter is provided, isTerminated filter is ignored and forced to true.
  • when includePendingTermination query parameter is provided with value true, terminatedStatus filter is ignored and replaced by the condition "isTerminated=false OR terminatedStatus=account_pending_termination".
isActivated
string
Enum: "true" "false"

Allows to filter users list for users which have logged in at least once ("true") or never ("false").

fileSharingCustomisation
string

Allows to filter users list on fileSharing feature restriction (enabled, disabled, same_than_company)

userTitleNameCustomisation
string

Allows to filter users list on user's profile update restriction (enabled, disabled, same_than_company)

softphoneOnlyCustomisation
string

Allows to filter users list on use softphone part of the UCaas application restriction (enabled, disabled, same_than_company)

useRoomCustomisation
string

Allows to filter users list on use room (bubble) restriction (enabled, disabled, same_than_company)

phoneMeetingCustomisation
string

Allows to filter users list on can join a PSTN conference restriction (enabled, disabled, same_than_company)

useChannelCustomisation
string

Allows to filter users list on use channels restriction (enabled, disabled, same_than_company)

useScreenSharingCustomisation
string

Allows to filter users list on sharing screen restriction (enabled, disabled, same_than_company)

useWebRTCVideoCustomisation
string

Allows to filter users list on use screen sharing restriction (enabled, disabled, same_than_company)

useWebRTCAudioCustomisation
string

Allows to filter users list on use Web RTC audio restriction (enabled, disabled, same_than_company)

useWebRTCOnlyIfMobileLoggedCustomisation
string

Allows to filter users list on receive web RTC call if mobile app is signed in (enabled, disabled, same_than_company)

instantMessagesCustomisation
string

Allows to filter users list on use Instant Messages restriction (enabled, disabled, same_than_company)

userProfileCustomisation
string

Allows to filter users list on modify a profile restriction (enabled, disabled, same_than_company)

fileStorageCustomisation
string

Allows to filter users list on use Rainbow file storage restriction (enabled, disabled, same_than_company)

overridePresenceCustomisation
string

Allows to filter users by the ability to modify manually presence state (enabled, disabled, same_than_company)

alert
string

notification] Allows to filter users by the ability to receive alert notification(enabled, disabled, same_than_company)

changeTelephonyCustomisation
string

Allows to filter users by the ability to modify telephony settings (enabled, disabled, same_than_company)

changeSettingsCustomisation
string

Allows to filter users by the ability to change client general setting (enabled, disabled, same_than_company)

recordingConversationCustomisation
string

Allows to filter users by the ability to record conversation (enabled, disabled, same_than_company)

useGifCustomisation
string

Allows to filter users by the ability to use GIFs in conversations (enabled, disabled, same_than_company)

useDialOutCustomisation
string

Allows to filter users by the ability to be called by the Rainbow conference bridge. (enabled, disabled, same_than_company)

fileCopyCustomisation
string

Allows to filter users by the ability to copy any file he receives in his personal cloud space.

fileTransferCustomisation
string

Allows to filter users by the ability to copy a file from a conversation then share it inside another conversation.

forbidFileOwnerChangeCustomisation
string

Allows to filter users by the ability to loose the ownership on one file.

readReceiptsCustomisation
string

Allows to filter users by the ability to authorize a sender to check if a chat message is read.

useSpeakingTimeStatistics
string

Allows to filter users by the ability to see speaking time statistics about a WebRTC meeting.

eLearningCustomisation
string

Allows to filter users by the ability to participate on an Elearning training.

eLearningGamificationCustomisation
string

Allows to filter users by the ability to earn badges for Elearning progress.

meetingRecordingCustomisation
string

Allows to filter users by the ability to record a meeting.

selectedAppCustomisationTemplate
string

Allows to filter users by the last application customisation template applied.

useOtherPhoneMode
string

Allows to filter users by the other phone mode usage.

useComputerMode
string

Allows to filter users by the computer mode usage.

canCallParticipantPbxNumberCustomisation
string

Allows to filter users by the kind of call participant PBX number.

canSetInvisiblePresenceCustomisation
string

Allows to filter users by the restriction to receive file to protect from data coming from a foreign user of the company

receivedFileCustomisation
string

Allows to filter users by the ability to set invisible presence.

withFeature
string

Allows to filter users by profiles supporting the given feature.

format
string
Default: "small"
Enum: "small" "medium" "full"

Allows to retrieve more or less user details in response.

  • small: id, loginEmail, firstName, lastName, displayName, companyId, companyName, isTerminated
  • medium: id, loginEmail, firstName, lastName, displayName, jid_im, jid_tel, companyId, companyName, lastUpdateDate, lastAvatarUpdateDate, isTerminated, terminatedStatus, guestMode
  • full: all user fields
limit
number
Default: 100

Allow to specify the number of users to retrieve.

offset
number

Allow to specify the position of first user to retrieve (first user if not specified). Warning: if offset > total, no results are returned.

sortField
string
Default: "displayName"

Sort user list based on the given field.

sortOrder
number
Default: 1
Enum: -1 1

Specify order when sorting user list.

displayName
string

Allows to filter users list on the given keyword(s) on field displayName.

useEmails
boolean

used with displayName, allows to filter users list on the given keyword(s) on field displayName for loginEmails too.

companyName
string

Allows to filter users list on the given keyword(s) on field companyName.

loginEmail
string

Allows to filter users list on the loginEmails provided in this option.

email
string

Allows to filter users list on the emails provided in this option.

visibility
string
Enum: "same_than_company" "public" "private" "closed" "isolated" "none"

Allows to filter users list on the visibility(ies) provided in this option.

organisationId
string

Allows to filter users list on the organisationIds provided in this option.

Option is reserved for superAdmin or admin allowed to manage the given organisationId.

jid_im
string

Allows to filter users list on the jid_ims provided in this option.

jid_tel
string

Allows to filter users list on the jid_tels provided in this option.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": 2,
  • "limit": 100,
  • "offset": 0
}

Create a user

This api creates a user in Rainbow application.

Jabber identifiers (IM and TEL) are generated and user is created in XMPP server.

Rights depending on logged in user's roles:

  • Users with bp_admin or bp_finance role can only create users in companies being End Customers of their BP company (i.e. all the companies having bpId equal to their companyId).
  • Users with admin role can only create users in companies they can manage. That is to say:
    • an organization_admin can create users only in a company he can manage (i.e. companies having organisationId equal to his organisationId)
    • a company_admin can only create users in his company
    • a site_admin can't create users
  • Admin users can only set roles guest, user and admin.

Phone numbers:

In some cases, creating a user with guest role may be sufficient. Here are guest role specificity:

  • guest is a single role that can't be modified
  • Created by a company_admin only, in his company
  • Has limited rights to chat, audio and video conversations
  • Is never notified by email
  • Can't receive welcome message by Emily
  • Can't manage its password (reset)
  • By default, can't be search inside or outside his company
  • Can't be moved to another company
  • Definitely deleted (his user experience is not kept: conversations ...)
Authorizations:
Request Body schema: application/json
adminType
string
Enum: "organization_admin" "company_admin" "site_admin"

Mandatory if roles array contains admin role: specifies at which entity level the administrator has admin rights in the hierarchy ORGANIZATIONS/COMPANIES/SITES/SYSTEMS

authenticationExternalUid
string

User external authentication ID Allows to authenticate the user based on an external identifier (company's SSO server (SAML or OIDC), Teams, Outlook, ...)

authenticationType
string
Enum: "DEFAULT" "RAINBOW" "SAML" "OIDC"

User authentication type (if not set company default authentication will be used)

companyId
string

User company unique identifier (like 569ce8c8f9336c471b98eda1).
If not provided, users are attached to a "Default" company.
companyName field is automatically filled on server side based on companyId.

country
string 3 characters

User country (ISO 3166-1 alpha3 format)

The list of allowed countries can be obtained using the API GET /api/rainbow/enduser/v1.0/countries

customData
object

User's custom data.
Object with free keys/values.
It is up to the client to manage the user's customData (new customData provided overwrite the existing one).

Restrictions on customData Object:

  • max 20 keys,
  • max key length: 64 characters,
  • max value length: 4096 characters.


User customData can only be created/updated by:
  • the user himself
  • `company_admin` or `organization_admin` of his company,
  • `bp_admin` and `bp_finance` of his company,
  • `superadmin`.
department
string [ 1 .. 255 ] characters

User department

Array of objects (postUsersEmails)

Array of user emails addresses objects

firstName
string [ 1 .. 255 ] characters

User first name

isActive
boolean
Default: true

Is user active

isInitialized
boolean
Default: false

Is user initialized
If isInitialized is set to true and sendInvitationEmail query parameter is set to true, the user receives an email "Your Rainbow account has been activated".

jobTitle
string [ 1 .. 255 ] characters

User job title

language
string/^([a-z]{2})(?:(?:(-)[A-Z]{2}))?$/

User language

Language format is composed of locale using format ISO 639-1, with optionally the regional variation using ISO 3166‑1 alpha-2 (separated by hyphen).
Locale part is in lowercase, regional part is in uppercase. Examples: en, en-US, fr, fr-FR, fr-CA, es-ES, es-MX, ...
More information about the format can be found on this link.

lastName
string [ 1 .. 255 ] characters

User last name

loginEmail
required
string [ 3 .. 255 ] characters

User email address (used for login).
Must be unique (409 error is returned if a user already exists with the same email address).

object

User phone number (used for login).

mfaRainbowPolicyId
string

Rainbow multifactor policy unique identifier (only if authenticationType is RAINBOW) Note: specifically in the case of users with admin rights (superadmin, admin,, bp_admin), a mfaRainbowPolicyId can be set even if authenticationType is set to a SSO method (this mfaRainbowPolicyId will be used by the admin in case the Rainbow authentication is used instead of SSO (fallback mechanism)).

nickName
string [ 1 .. 255 ] characters

User nickName

password
string [ 8 .. 64 ] characters

User password.

Rules:

  • more than 8 characters,
    • ⚠️ Warning: the minimal password length will soon be increased to 12, planned to be effective mid-june 2023 (8 characters are still accepted until this date)
  • at least 1 capital letter,
  • 1 number,
  • 1 special character.

If password is not set, the user will have to use the reset-password feature to define his password so that he can login to Rainbow (except if the user is configured to use a Single Sign On method (SAML or OIDC)).

Array of objects (postUsersPhoneNumbers)

Array of user phone numbers objects

For each provided phoneNumber Object, the server tries to compute the associated E.164 number (numberE164 field):

  • If number is already in E.164 format, the value is simply duplicated as is in numberE164 field, and country field is computed from this E.164 number,
  • Otherwise numberE164 is computed using provided number and country field (if country is provided this value is used, otherwise user's country is set in country field).
  • If numberE164 can't be computed from number and country fields, an error 400 is returned (ex: wrong phone number, phone number not matching country code, ...)

System phoneNumbers can't be created using this API, only PCG can create system PhoneNumbers

rainbowPasswordlessPolicyId
string

Rainbow passwordless policy unique identifier (must correspond to a valid user's company's rainbowPasswordlessPolicies' passwordlessId).
Notes:

  • The passwordless policy set in user's rainbowPasswordlessPolicyId field is only used by the user if its authenticationType is set to RAINBOW (otherwise, if authenticationType is not set, the default company's authentication method is used).
  • Passwordless authentication is not compatible with Multi-Factor Authentication, so is the user has a MFA configuration, this one is cleared when Passwordless configuration is applied.
rainbowPasswordlessPolicyName
string

Rainbow passwordless policy name to set to the user (must correspond to a valid user's company's rainbowPasswordlessPolicies' passwordlessName).
Notes:

  • rainbowPasswordlessPolicyName is not saved in the user, the associated company's rainbowPasswordlessPolicies' passwordlessId is stored in rainbowPasswordlessPolicyId,
  • The passwordless policy set in user's rainbowPasswordlessPolicyId field is only used by the user if its authenticationType is set to RAINBOW (otherwise, if authenticationType is not set, the default company's authentication method is used).
  • Passwordless authentication is not compatible with Multi-Factor Authentication, so is the user has a MFA configuration, this one is cleared when Passwordless configuration is applied. This parameter is meant to apply the passwordless policy using its name, especially from CSV file (as admins don't know the rainbowPasswordlessPolicyId).

    Rainbow passwordless policy can be unset by setting rainbowPasswordlessPolicyName to null or empty String ("").
rainbowPasswordlessPolicySendToEmail
string

Optional email used to send passwordless code to the user (instead of his loginEmail address) when passwordless authentication is enabled and the associated company's passwordless policy has sendEmail=true.
rainbowPasswordlessPolicySendToEmail can be unset by setting its value to null or empty String ("").

roles
Array of strings
Default: ["user"]
Items Enum: "guest" "user" "admin" "bp_admin" "bp_finance" "ec_analytics" "company_support" "all_company_channels_admin" "public_channels_admin" "closed_channels_admin" "all_organization_channels_admin" "organization_public_channels_admin" "organization_closed_channels_admin" "app_admin" "app_support" "app_superadmin" "directory_admin" "supervisor" "support" "superadmin" "webinar_host" "attendant"

List of user roles

The general rule is that a user must have the roles that the wants to assign to someone else.

Examples:

  • an admin can add or remove the role admin to another user of the company(ies) he manages,
  • an bp_admin can add or remove the role bp_admin to another user of the company(ies) he manages,
  • an app_superadmin can add or remove the role app_superadmin to another user...

Here are some explanations regarding the roles available in Rainbow:

  • admin, bp_admin and bp_finance roles are related to company management (and resources linked to companies, such as users, systems, subscriptions, ...).
  • bp_admin and bp_finance roles can only be set to users of a BP company (company with isBP=true).
  • app_admin, app_support and app_superadmin roles are related to application management.
  • all_company_channels_admin, public_channels_admin and closed_channels_admin roles are related to channels management.
  • ec_analytics role allows a user to consult its own analytics.
  • supervisor allows users to supervise (telephony) other users from their company.
    • This role can be assigned manually to a user using this API, otherwise it is automatically set when a user is a added to a supervision group as supervisor.
    • This role can be removed manually to a user using the PUT /api/rainbow/admin/v1.0/users/:userId API, in that case the user is automatically removed from all the supervision groups in which he was supervisor.
    • This role is automatically removed from a user when he is removed from the last supervision group in which he was supervisor.
  • A user with webinar_host role will be able to create webinars. Note: to be able to give this role, company should first subscribe to a webinar offer.
  • A user with attendant role will be the attendant of the Cloud PBX of its company. Note : to be able to give this role, feature TELEPHONY_BASIC_ATTENDANT_CONSOLE must be available for the user , as so this role cannot be assigned during User creation
  • A user with admin rights (admin, bp_admin, superadmin) can't change his own roles, except for roles related to channels (all_company_channels_admin, public_channels_admin and closed_channels_admin).
  • Only superadmin can set superadmin and support roles to a user.
selectedTheme
string

Set the selected theme for the user.

siteId
string

User company site unique identifier (like 569ce8c8f9336c471b98eda2)

state
string
Enum: "null" "AA" "AE" "AP" "AK" "AL" "AR" "AZ" "CA" "CO" "CT" "DC" "DE" "FL" "GA" "GU" "HI" "IA" "ID" "IL" "IN" "KS" "KY" "LA" "MA" "MD" "ME" "MI" "MN" "MO" "MS" "MT" "NC" "ND" "NE" "NH" "NJ" "NM" "NV" "NY" "OH" "OK" "OR" "PA" "PR" "RI" "SC" "SD" "TN" "TX" "UT" "VA" "VI" "VT" "WA" "WI" "WV" "WY" "AB" "BC" "MB" "NB" "NL" "NS" "NT" "NU" "ON" "PE" "QC" "SK" "YT"

When country is 'USA' or 'CAN', a state can be defined. Else it is not managed (null).

The list of allowed states can be obtained using the API GET /api/rainbow/enduser/v1.0/countries for the associated countries.

  • List of allowed states for USA:
    • AA: "Armed Forces America",
    • AE: "Armed Forces",
    • AP: "Armed Forces Pacific",
    • AK: "Alaska",
    • AL: "Alabama",
    • AR: "Arkansas",
    • AZ: "Arizona",
    • CA: "California",
    • CO: "Colorado",
    • CT: "Connecticut",
    • DC: Washington DC",
    • DE: "Delaware",
    • FL: "Florida",
    • GA: "Georgia",
    • GU: "Guam",
    • HI: "Hawaii",
    • IA: "Iowa",
    • ID: "Idaho",
    • IL: "Illinois",
    • IN: "Indiana",
    • KS: "Kansas",
    • KY: "Kentucky",
    • LA: "Louisiana",
    • MA: "Massachusetts",
    • MD: "Maryland",
    • ME: "Maine",
    • MI: "Michigan",
    • MN: "Minnesota",
    • MO: "Missouri",
    • MS: "Mississippi",
    • MT: "Montana",
    • NC: "North Carolina",
    • ND: "North Dakota",
    • NE: "Nebraska",
    • NH: "New Hampshire",
    • NJ: "New Jersey",
    • NM: "New Mexico",
    • NV: "Nevada",
    • NY: "New York",
    • OH: "Ohio",
    • OK: "Oklahoma",
    • OR: "Oregon",
    • PA: "Pennsylvania",
    • PR: "Puerto Rico",
    • RI: "Rhode Island",
    • SC: "South Carolina",
    • SD: "South Dakota",
    • TN: "Tennessee",
    • TX: "Texas",
    • UT: "Utah",
    • VA: "Virginia",
    • VI: "Virgin Islands",
    • VT: "Vermont",
    • WA: "Washington",
    • WI: "Wisconsin",
    • WV: "West Virginia",
    • WY: "Wyoming"
  • List of allowed states for CAN:
    • AB: "Alberta",
    • BC: "British Columbia",
    • MB: "Manitoba",
    • NB: "New Brunswick",
    • NL: "Newfoundland and Labrador",
    • NS: "Nova Scotia",
    • NT: "Northwest Territories",
    • NU: "Nunavut",
    • ON: "Ontario",
    • PE: "Prince Edward Island",
    • QC: "Quebec",
    • SK: "Saskatchewan",
    • YT: "Yukon"
tags
Array of strings

An Array of free tags associated to the user.
A maximum of 5 tags is allowed, each tag can have a maximum length of 64 characters.
tags can only be set by users who have administrator rights on the user. The user can't modify the tags.
The tags are visible by the user and all users belonging to his organisation/company, and can be used with the search API to search the user based on his tags.

timeToLive
number

Duration in second to wait before automatically starting a user deletion from the creation date.
Once the timeToLive has been reached, the user won't be usable to use APIs anymore (error 401523). His account may then be deleted from the database at any moment.
Value -1 means timeToLive is disable (i.e. user account will not expire).
If created user has role guest and no timeToLive is provided, a default value of 172800 seconds is set (48 hours).
If created user does not have role guest and no timeToLive is provided, a default value of -1 is set (no expiration).

timezone
string

User timezone name
Allowed values: one of the timezone names defined in IANA tz database
Timezone name are composed as follow: Area/Location (ex: Europe/Paris, America/New_York,...)

title
string [ 1 .. 40 ] characters

User title (honorifics title, like Mr, Mrs, Sir, Lord, Lady, Dr, Prof,...)

userInfo1
string [ 0 .. 64 ] characters

Free field that admin can use to link their users to their IS/IT tools / to perform analytics (this field is output in the CDR file)

userInfo2
string [ 0 .. 64 ] characters

2nd Free field that admin can use to link their users to their IS/IT tools / to perform analytics (this field is output in the CDR file)

visibility
string
Enum: "same_than_company" "public" "private" "closed" "isolated" "hotspot" "none"

User visibility
Define if the user can be searched by users being in other company and if the user can search users being in other companies.
Visibility can be:

  • same_than_company: The same visibility than the user's company's is applied to the user. When this user visibility is used, if the visibility of the company is changed the user's visibility will use this company new visibility.
  • public: User can be searched by external users / can search external users. User can invite external users / can be invited by external users
  • private: User can't be searched by external users / can search external users. User can invite external users / can be invited by external users
  • closed: User can't be searched by external users / can't search external users. User can invite external users / can be invited by external users
  • isolated: User can't be searched by external users / can't search external users. User can't invite external users / can't be invited by external users
  • hotspot: User can be searched by hotspot attached company's users (users from any company if the user belong to the default company) / can't search any users (even in their company) | user can't invite external users / can be invited by hotspot attached company's users (users from any company if the user belong to the default company)
  • none: Default value reserved for guest. User can't be searched by any users (even within the same company) / can search external users. User can invite external users / can be invited by external users External users mean 'public user not being in user's company nor user's organisation nor a company visible by user's company.

Responses

Request samples

Content type
application/json
{
  • "adminType": "organization_admin",
  • "authenticationExternalUid": "string",
  • "authenticationType": "DEFAULT",
  • "companyId": "string",
  • "country": "str",
  • "customData": { },
  • "department": "string",
  • "emails": [
    ],
  • "firstName": "string",
  • "isActive": true,
  • "isInitialized": false,
  • "jobTitle": "string",
  • "language": "string",
  • "lastName": "string",
  • "loginEmail": "string",
  • "loginPhone": {
    },
  • "mfaRainbowPolicyId": "string",
  • "nickName": "string",
  • "password": "stringst",
  • "phoneNumbers": [
    ],
  • "rainbowPasswordlessPolicyId": "string",
  • "rainbowPasswordlessPolicyName": "string",
  • "rainbowPasswordlessPolicySendToEmail": "string",
  • "roles": [
    ],
  • "selectedTheme": "string",
  • "siteId": "string",
  • "state": "null",
  • "tags": [
    ],
  • "timeToLive": 0,
  • "timezone": "string",
  • "title": "string",
  • "userInfo1": "string",
  • "userInfo2": "string",
  • "visibility": "same_than_company"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Users Networks

Add users to user network

This API can be used to add users to requested user networks.

BETA: this API is currently in beta. Restriction: only 1 user can be provided in users array (others are ignored)

superadmin can set user network from any users existing in Rainbow.
bp_admin or bp_finance can only set user network for users being in companies being End Customers of their BP company (i.e. all the companies having bpId equal to their companyId) and their own BP company.
organization_admin can only set user network for users being in companies under their organisation.
company_admin can only set user network for users being in their company.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56c5c19f94141765119f896c)

Request Body schema: application/json
presence
boolean
Default: false

Specify if presence subscription has to be set when adding the users in mutual networks.

users
required
Array of strings

Array of user unique identifiers (like 56c5c19f94141765119f896c) of the users to add in requested user network

Responses

Request samples

Content type
application/json
{
  • "presence": false,
  • "users": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Users Presence

Get user presence information

Company admin shall be able to check if a user can be reached or not, by checking the presence information (available, busy, away, etc). Admin will have to select a user to get a presence snapshot when opening the user configuration profile.
Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/users/56d0277a0261b53142a5cab5/presence

A brute force defense is activated when too much request have been requested by the same administrator, to not overload the backend. As a result, an error 429 "Too Many Requests" will be returned .

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56c5c19f94141765119f896c)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Users Profiles Features

Get a user profiles features

This API can be used to get features associated to the user through its profiles.

A user can be assigned to several profiles (if an admin has assigned subscription licences to the user).

By default, user is at least assigned to the subscription of his company to the default offer (i.e. Essential).

Each profile has his own list of features with his own values. This API allows to aggregate all features from all user's profiles.

superadmin and support can get features available for any existing user in Rainbow. bp_admin and bp_finance can only retrieve features available for users being in End Customer companies linked to their BP company. organization_admin can only retrieve features available for users being in companies under their organisation. company_admin can only get features available for users being in their company.

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/users/56d0277a0261b53142a5cab5/profiles/features

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Users Profiles

Delete a user profile

This API can be used to un-assign a company's subscription from user profiles.

Profile linked to company's default subscription can't be removed.

superadmin can remove a profile from any user existing in Rainbow.
business_admin can remove a profile linked to a demo offer from any user existing in Rainbow.
bp_admin and bp_finance can remove a profile for users being in End Customer companies linked to their BP company and from users being in their own BP company (or organisation).
organization_admin can only remove a profile for users being in companies under their organisation.
company_admin can only remove a profile for users being in their company.

Example: DELETE https://openrainbow.com/api/rainbow/admin/v1.0/users/56d0277a0261b53142a5cab5/profiles/subscriptions/59396b2918f2e75c2bd3bb5b

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

subscriptionId
required
string

Company subscription unique identifier.

Responses

Response samples

Content type
application/json
application/json
text/xml
{
  • "data": [ ],
  • "status": "User profile linked to subscription 59396b2918f2e75c2bd3bb5b successfully deleted"
}

Add a user profile

This API can be used to assign a company's subscription to user profiles (user must be in the same company than the company which own the subscription).

By default, when users are created or moved to a company, user's company's subscription to the default offer (Essential) is automatically added to user's profiles (therefore user's profiles should never be empty)

superadmin can add a profile from any user existing in Rainbow.
business_admin can add a profile linked to a demo offer to any user existing in Rainbow.
bp_admin and bp_finance can add a profile to users being in End Customer companies linked to their BP company and to users being in their own BP company (or organisation).
organization_admin can only add a profile to users being in companies under their organisation.
company_admin can only add a profile to users being in their company.

Provided subscriptionId must be one of the subscriptions available in user's company's subscriptions list (it can be the company's subscription to the default offer (Essential)).
The subscription must have the status active and not being synchronizing with Business Store / Zuora (syncOngoing equal to false), otherwise 403 errors are returned.
Subscription with businessModel flat_fee or nb_services can not be assigned to user profiles (they are fees at company level).
If the subscription has a maxNumberUsers and the subscription is already assigned to this number of users, the assignation to the user is denied.
If the provided subscriptionId is already assigned to user's profiles, a conflict error is returned.

Example: POST https://openrainbow.com/api/rainbow/admin/v1.0/users/56d0277a0261b53142a5cab5/profiles/subscriptions/5808afeb4372eb19547e90cf

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

subscriptionId
required
string

Company subscription unique identifier.

Responses

Response samples

Content type
application/json
application/json
text/xml
{
  • "data": {
    }
}

Get a user profiles

This API can be used to get a user's profiles.

superadmin and support can get profiles from any existing user in Rainbow.
bp_admin and bp_finance can only retrieve profiles of users being in End Customer companies linked to their BP company.
organization_admin can only retrieve profiles of users being in companies under their organisation.
company_admin can only get profiles of users being in their company.

Example: GET https://openrainbow.com/api/rainbow/admin/v1.0/users/56d0277a0261b53142a5cab5/profiles

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Users Tags

Users Telephony Keys

Remove one Phone touch of a user

This API can be used to delete one programmable phone touch of a user.
Example: DELETE https://openrainbow.com/api/rainbow/admin/v1.0/users/56d0277a0261b53142a5cab5/telephony-keys/60e45024c8da191a7051575c

Remaining telephony keys are returned as data.


A message stanza is sent to the end user

<message type="management" id="1644ac58-c69c-4a15-879c-3faf5ee329a7_0"
       to="ab353de6856e442b88f96f68e55f474a@francky1-all-in-one-rd-dev-1.opentouch.cloud" xmlns="jabber:client">
 <telephony-key keyId="60e6bfeed32f29208298d209" xmlns="jabber:iq:configuration" action="delete">
     <position>1</position>
     <type>speedDialing</type>
     <origin>personal</origin>
     <locked>false</locked>
     <name>Mom</name>
     <number>0388000001</number>
 </telephony-key>
</message>
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

keyId
required
string

Telephony key unique identifier

Responses

Response samples

Content type
application/json
{
  • "status": "Telephony key 60e45024c8da191a7051575c successfully deleted",
  • "data": {
    }
}

Update one Phone touch of a user

This API can be used to modify a programmable phone touch of a user. For example to lock or unlock a key.

It's also possible to only modify the position of a key in the user's list.
So it’s allowed to both update a key content and it’s position. Use the url parameter position.
Note however that in the case a telephony keys group is assigned to the user, the position of keys coming from this group (origin=group) can't be modified with this API:

  • The keys from the group are always in front of user's personal and shared keys.
  • Only the position of keys with origin=personal or origin=shared can be modified, and they can't be set to a position in the range of the keys with origin=group.

If the type of the telephony key is changed while the key is active or when it is set to active state, then the feature keys bellow are taken into account before allowing a programmable key update. (errorDetailCode: 403620)

  • TELEPHONY_MAX_SPEED_DIALING_KEYS
  • TELEPHONY_MAX_FEATURE_CODE_KEYS


A message stanza is sent to the end user

<message type="management" id="1644ac58-c69c-4a15-879c-3faf5ee329a7_0"
       to="ab353de6856e442b88f96f68e55f474a@francky1-all-in-one-rd-dev-1.opentouch.cloud" xmlns="jabber:client">
 <telephony-key keyId="60e6bfeed32f29208298d209" xmlns="jabber:iq:configuration" action="update">
     <position>1</position>
     <type>speedDialing</type>
     <origin>personal</origin>
     <locked>false</locked>
     <active>false</active>
     <name>Mom</name>
     <number>0388000001</number>
 </telephony-key>
</message>
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

keyId
required
string

Telephony key unique identifier

query Parameters
position
integer <int32>

By default the key is created in the end of the list. It's possible to move it in another place. 0 is the first place.
If a telephony keys group is assigned to the user, the position must be chosen outside the range of keys of the group (origin=group). To change the position of a key of the group, please use the API PUT /api/rainbow/admin/v1.0/companies/:companyId/telephony-keys-groups/:groupId/keys/:keyId

Request Body schema: application/json
active
boolean

This key can be used directly by a user.

featureCodeSubType
string

For featureCode key type only, this is the type of the field number

  • dial – a number to dial
  • dtmf – a DTMF sequence
featureCodeSupportedTelStates
Array of strings

For featureCode key type only, this are supported telephony states [optional] The supported telephony state is the list of telephony state which are compatible with the feature code.

  • Example: the call back request must be played in ringing state
locked
boolean

The key is created by an administrator and can't be updated by the end user

name
string [ 1 .. 32 ] characters

Label of the key

number
string [ 1 .. 32 ] characters

The key content for keys of type speedDialing and featureCode.

restrictedUse
boolean

The key is created by an administrator for some users sharing the same system (PBX). It is assigned by an administrator only

  • When restrictedUse is set to true, the body parameter <b>active</b> is ignored and the key is forced to inactive state (active = false)
type
string

The type of the key

  • speedDialing – contains a number to dial
  • featureCode – contains either a dialing code or a multi-frequency code

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "featureCodeSubType": "string",
  • "featureCodeSupportedTelStates": [
    ],
  • "locked": true,
  • "name": "string",
  • "number": "string",
  • "restrictedUse": true,
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Programmable Phone touch of a user

This API can be used to list all the programmable phone touch of a user.

Users with a paid Rainbow license (business or enterprise) can manage and use programmable keys for their softphone.

This keys can be of different types:

  • Speed dialing – contains a number to dial
  • Feature code – contains either a dialing code or a MF code

All of them can be managed by an administrator, and some of them can be locked to prevent the end user to override the content.
note: If the user is associated to a company's group, the keys of the group are prepend in the list by respected the user limits.

This API returns always an empty set of programmable keys when the user haven't the right license.

Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add one Phone touch of a user

This API can be used to create one programmable phone touch of a user.

This keys can be of different types:

  • Speed dialing – contains a number to dial
  • Feature code – contains either a dialing code or a MF code

It can be locked at creation. By default the key is not locked and active at creation.

Feature keys bellow are taken into account before allowing a programmable key creation. (errorDetailCode: 403620)

  • TELEPHONY_MAX_KEYS
  • TELEPHONY_MAX_SPEED_DIALING_KEYS
  • TELEPHONY_MAX_FEATURE_CODE_KEYS


A message stanza is sent to the end user

<message type="management" id="1644ac58-c69c-4a15-879c-3faf5ee329a7_0"
       to="ab353de6856e442b88f96f68e55f474a@francky1-all-in-one-rd-dev-1.opentouch.cloud" xmlns="jabber:client">
 <telephony-key keyId="60e6bfeed32f29208298d209" xmlns="jabber:iq:configuration" action="create">
     <position>1</position>
     <type>speedDialing</type>
     <origin>personal</origin>
     <locked>false</locked>
     <active>true</active>
     <name>Mom</name>
     <number>0388000001</number>
 </telephony-key>
</message>
Authorizations:
BearerBearer-x-rainbow-api-key
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

query Parameters
position
integer <int32>

By default the key is created in the end of the list. It's possible to insert it in another place. 0 is the first place.
If a telephony keys group is assigned to the user, the position must be chosen outside the range of keys of the group (origin=group). To change the position of a key of the group, please use the API PUT /api/rainbow/admin/v1.0/companies/:companyId/telephony-keys-groups/:groupId/keys/:keyId

Request Body schema: application/json
active
boolean

This key can be used directly by a user.

featureCodeSubType
string

For featureCode key type only, this is the type of the field number

  • dial – a number to dial
  • dtmf – a DTMF sequence
featureCodeSupportedTelStates
Array of strings

For featureCode key type only, this are supported telephony states [optional] The supported telephony state is the list of telephony state which are compatible with the feature code.

  • Example: the call back request must be played in ringing state
locked
boolean

The key is created by an administrator and can't be updated by the end user

name
required
string [ 1 .. 32 ] characters

Label of the key

number
string [ 1 .. 32 ] characters

The key content for keys of type speedDialing and featureCode.

restrictedUse
boolean

The key is created by an administrator for some users sharing the same system (PBX). It is assigned by an administrator only

type
required
string

The type of the key

  • speedDialing – contains a number to dial
  • featureCode – contains either a dialing code or a multi-frequency code

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "featureCodeSubType": "string",
  • "featureCodeSupportedTelStates": [
    ],
  • "locked": true,
  • "name": "string",
  • "number": "string",
  • "restrictedUse": true,
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}