logo
Documentation Powered by ReDoc

Rainbow admin portal (1.170.5)

Download OpenAPI specification:Download

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

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:
Bearer
path Parameters
companyId
required
string

Company for which list of administrators is requested

header Parameters
accept
required
string

application/json

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.
Authorizations:
Bearer
path Parameters
companyId
required
string

Company for which list of administrators is requested

Responses

Response samples

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

Get company's avatar

This API can be used to retrieve company's avatar (logo).
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 2048px:

  • If no size option is requested, avatar 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 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).
Authorizations:
Bearer
path Parameters
companyId
required
string

Company for which list of administrators is requested

query Parameters
size
required
number
Default: 80

Specify avatar size in pixels (square size x size)

Responses

Response samples

Content type
application/json
{
  • "Content-Type": "image/jpeg",
  • "Date": "2019-08-24T14:15:22Z",
  • "Dims-cached": "string",
  • "Last-Modified": "2019-08-24T14:15:22Z",
  • "Content": "string"
}

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:
Bearer
path Parameters
companyId
required
string

Company for which list of administrators is requested

header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
companyId
required
string

Company for which list of administrators is requested

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:
Bearer
path Parameters
companyId
required
string

Company for which list of administrators is requested

query Parameters
size
required
number
Default: 80

Specify avatar size in pixels (square size x size)

Responses

Response samples

Content type
application/json
{
  • "Content-Type": "image/jpeg",
  • "Date": "2019-08-24T14:15:22Z",
  • "Dims-cached": "string",
  • "Last-Modified": "2019-08-24T14:15:22Z",
  • "Content": "string"
}

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).
Authorizations:
Bearer
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
customData
required
object

Responses

Request samples

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

Response samples

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

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:
Bearer
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.

header Parameters
accept
required
string

application/json

Responses

Response samples

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

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 (except for company_admin asking to delete his company if he is alone in it)

If company has default subscriptions and/or subscriptions with status equal terminated, company won't be deleted but only disabled (status and name of company changed to terminated) 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:
Bearer
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

header Parameters
accept
required
string

application/json

Responses

Response samples

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

Get a company data

Users with 'superadmin', 'support' 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:
Bearer
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, country, website, slogan, description, size, economicActivityClassification, lastAvatarUpdateDate, lastBannerUpdateDate, avatarShape, visibility
- full for superadmin, support, business_admin, 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)

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.
header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
adminAllowedUpdateSubscriptionsOps
string
Enum: "all" "increase_only"

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

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.

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

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.

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

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

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.

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

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

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!

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)

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.

postalCode
string [ 0 .. 64 ] characters

Company postal code

salesforceAccountId
string [ 0 .. 64 ] characters

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

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

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

Company support email
supportEmail is case sentive.

supportUrlFAQ
string [ 0 .. 2000 ] characters

Company support url

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,
  • "alertNotificationReception": "disabled",
  • "alertNotificationSending": "disabled",
  • "allowCloudPbxRecording": "false",
  • "allowDeviceFirmwareSelection": "false",
  • "allowPhoneNumbersVisibility": "false",
  • "allowUsersSelectPublicTheme": "true",
  • "allowUsersSelectTheme": "true",
  • "avatarShape": "square",
  • "billingModel": "monthly",
  • "bpApplicantNumber": "string",
  • "bpBusinessModel": "referral",
  • "bpBusinessType": [
    ],
  • "bpCRDid": "string",
  • "bpHasRightToConnect": true,
  • "bpHasRightToSell": true,
  • "bpId": "string",
  • "bpIsContractAccepted": "false",
  • "bpType": "IR",
  • "catalogId": "string",
  • "city": "string",
  • "cloudPbxRecordingInboundOnly": "true",
  • "companyCallNumber": "string",
  • "companyContactId": "string",
  • "country": "FRA",
  • "currency": "USD",
  • "customData": { },
  • "ddiReadOnly": true,
  • "defaultLicenseGroup": "string",
  • "defaultOptionsGroups": [
    ],
  • "description": "string",
  • "disableCCareAdminAccess": true,
  • "disableCCareAdminAccessCustomers": true,
  • "disableCCareAdminAccessResellers": true,
  • "economicActivityClassification": "A",
  • "externalReference": "string",
  • "externalReference2": "string",
  • "giphyEnabled": true,
  • "isBP": true,
  • "isCentrex": true,
  • "mobilePermanentConnectionMode": "false",
  • "name": "string",
  • "offerType": "freemium",
  • "postalCode": "string",
  • "salesforceAccountId": "string",
  • "selectedDeviceFirmware": "released",
  • "selectedTheme": {
    },
  • "selectedThemeCustomers": {
    },
  • "sendPrepaidSubscriptionsNotification": true,
  • "size": "self-employed",
  • "slogan": "string",
  • "state": "null",
  • "status": "initializing",
  • "street": "string",
  • "superadminComment": "string",
  • "supportEmail": "string",
  • "supportUrlFAQ": "string",
  • "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' 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.
    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:
Bearer
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, country, website, slogan, description, size, economicActivityClassification, lastAvatarUpdateDate, lastBannerUpdateDate, avatarShape, visibility
  • full for superadmin, support, business_admin, bp_admin and bp_finance: All fields
  • full for admin: All fields except BP fields (bpType, bpBusinessModel, bpApplicantNumber, bpCRDid, bpHasRightToSell, bpHasRightToConnect, 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, 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.

limit
number
Default: 100
Value: 0

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, 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, 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, support or bp_admin can use this filter.

header Parameters
accept
required
string

application/json

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.

  • 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:
Bearer
Request Body schema: application/json
adminAllowedUpdateSubscriptionsOps
string
Enum: "all" "increase_only"

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

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.

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

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.

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

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

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.

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

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

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!

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)

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

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

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

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
object
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 sentive.

supportUrlFAQ
string [ 0 .. 2000 ] characters

Company support url

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,
  • "alertNotificationReception": "disabled",
  • "alertNotificationSending": "disabled",
  • "allowDeviceFirmwareSelection": "false",
  • "allowUsersSelectPublicTheme": "true",
  • "allowUsersSelectTheme": "true",
  • "avatarShape": "square",
  • "billingModel": "monthly",
  • "bpApplicantNumber": "string",
  • "bpBusinessModel": "referral",
  • "bpBusinessType": [
    ],
  • "bpCRDid": "string",
  • "bpHasRightToConnect": true,
  • "bpHasRightToSell": true,
  • "bpId": "string",
  • "bpIsContractAccepted": "false",
  • "bpType": "IR",
  • "catalogId": "string",
  • "city": "string",
  • "companyCallNumber": "string",
  • "companyContactId": "string",
  • "country": "FRA",
  • "currency": "USD",
  • "customData": { },
  • "ddiReadOnly": true,
  • "defaultLicenseGroup": "string",
  • "defaultOptionsGroups": [
    ],
  • "description": "string",
  • "disableCCareAdminAccess": true,
  • "disableCCareAdminAccessCustomers": true,
  • "disableCCareAdminAccessResellers": true,
  • "economicActivityClassification": "A",
  • "externalReference": "string",
  • "externalReference2": "string",
  • "giphyEnabled": true,
  • "isBP": true,
  • "isCentrex": true,
  • "mobilePermanentConnectionMode": "false",
  • "name": "string",
  • "offerType": "freemium",
  • "postalCode": "string",
  • "privateDC": "string",
  • "salesforceAccountId": "string",
  • "selectedDeviceFirmware": "released",
  • "selectedTheme": {
    },
  • "selectedThemeCustomers": {
    },
  • "sendPrepaidSubscriptionsNotification": true,
  • "size": "self-employed",
  • "slogan": "string",
  • "state": "null",
  • "status": "initializing",
  • "street": "string",
  • "superadminComment": "string",
  • "supportEmail": "string",
  • "supportUrlFAQ": "string",
  • "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:
Bearer
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, 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.

header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
companyId
required
string

Company for which service description file is requested

header Parameters
accept
required
string

application/json

Responses

Response samples

Content type
application/json
{
  • "Content-Type": "application/pdf",
  • "Content-disposition": "string",
  • "pdf": "string"
}

Get company App Customisation Deprecated

See (Company gets a given theme)

Authorizations:
Bearer
path Parameters
companyId
required
string

Company for which list of custom elements is requested.

header Parameters
accept
required
string

application/json

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:
Bearer
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:
Bearer
path Parameters
companyId
required
string

Company for which list of custom feature elements is requested.

header Parameters
accept
required
string

application/json

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:
Bearer
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:
Bearer
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, country, website, slogan, description, size, economicActivityClassification, lastAvatarUpdateDate, lastBannerUpdateDate, avatarShape
- full for superadmin and support: All fields
- full for admin: All fields except BP fields (bpType, bpBusinessModel, bpApplicantNumber, bpCRDid, bpHasRightToSell, bpHasRightToConnect, 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.
header Parameters
accept
required
string

application/json

Responses

Response samples

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

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:
Bearer
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

joinCompanyLinkId
required
string

Join company link unique identifier (like 086e997557924910bc838f93aee7b25d)

header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
companyId
required
string

Company unique identifier (like 569ce8c8f9336c471b98eda1)

joinCompanyLinkId
required
string

Join company link unique identifier (like 086e997557924910bc838f93aee7b25d)

header Parameters
accept
required
string

application/json

Responses

Response samples

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

Organisations Companies

Unlink the company to an organization

Authorizations:
Bearer
path Parameters
companyId
required
string

Company unique identifier (like 5749ab92245015fe0d36e96a)

organisationId
required
string

Organisation unique identifier (like 569ce8c8f9336c471b98eda1)

header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
organisationId
required
string

Organisation 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
- full: all company fields

header Parameters
accept
required
string

application/json

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:
Bearer
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": {
    }
}

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:
Bearer
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 company 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.

header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
organisationId
required
string

Organisation unique identifier (like 569ce8c8f9336c471b98eda1)

header Parameters
accept
required
string

application/json

Responses

Response samples

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

Update an organisation

Authorizations:
Bearer
path Parameters
organisationId
required
string

Organisation unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
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
{
  • "name": "string",
  • "visibility": "private"
}

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:
Bearer
path Parameters
siteId
required
string

Site unique identifier

systemId
required
string

System unique identifier

header Parameters
accept
required
string

application/json

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:
Bearer
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" "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).

header Parameters
accept
required
string

application/json

Responses

Response samples

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

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:
Bearer
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": {
    }
}

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:
Bearer
path Parameters
siteId
required
string

Site unique identifier (like 569ce8c8f9336c471b98eda1)

header Parameters
accept
required
string

application/json

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 sites linked to End Customer companies for which their bp_admin's company is the BP company.
organization_admin can only get sites linked to companies under their organisation.
company_admin can only get sites linked to their company.
site_admin can only get the site they administrate.

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

Authorizations:
Bearer
path Parameters
siteId
required
string

Site unique identifier (like 569ce8c8f9336c471b98eda1)

header Parameters
accept
required
string

application/json

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

Authorizations:
Bearer
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.

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",
  • "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:
Bearer
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.

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.

header Parameters
accept
required
string

application/json

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:
Bearer
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": {
    }
}

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:
Bearer
path Parameters
systemId
required
string

System unique identifier

groupId
required
string

SystemsGroup unique identifier

header Parameters
accept
required
string

application/json

content-type
required
string

application/json

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:
Bearer
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:
Bearer
path Parameters
groupId
required
string

SystemsGroup unique identifier

header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
groupId
required
string

SystemsGroup unique identifier

header Parameters
accept
required
string

application/json

Responses

Response samples

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

Rename a systems group

Only allow a systems group renaming.

Authorizations:
Bearer
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:
Bearer
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.

header Parameters
accept
required
string

application/json

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:
Bearer
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:
Bearer
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.

deviceName
string

Allow to filter phoneNumbers list on phoneNumbers having deviceName 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.

header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

phoneNumberId
required
string

PhoneNumber unique identifier (like 569ce8c8f9336c471b98eda1)

header Parameters
accept
required
string

application/json

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.

Example: PUT https://openrainbow.com/api/rainbow/admin/v1.0/systems/569d0ef3ef7816921f7e94fa/phoneNumbers/5790fd2256b61a4d865839fe

Authorizations:
Bearer
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

phoneNumberId
required
string

PhoneNumber unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
deviceName
string

device name

deviceType
string
Default: "landline"
Enum: "landline" "mobile" "fax" "other"

Phone number device type

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)

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, ...)

type
string
Default: "work"
Enum: "home" "work" "other"

Phone number type

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,
  • "isVisibleByOthers": true,
  • "lastName": "string",
  • "number": "string",
  • "type": "work",
  • "userId": "string"
}

Response samples

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

Systems Phone Numbers Multi Companies

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:
Bearer
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

Responses

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:
Bearer
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
systemId
required
string

System unique identifier (like 569ce8c8f9336c471b98eda1)

query Parameters
connectionHistory
boolean

Allows to return connection history

header Parameters
accept
required
string

application/json

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:
Bearer
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.

country
string 3 characters

System country (ISO 3166-1 alpha3 format)

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

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 []

searchResultOrder
Array of strings
Items Enum: "RAINBOW" "LDAP" "PBX"

List of directory types to order search results:

  • RAINBOW: phone numbers defined in Rainbow users
  • LDAP: phone numbers defined in directories according to the following priority order:
    • personal directory of the user
    • company directory (of the company(ies) to which the PBX is linked)
    • office365 directory (of the company(ies) to which the PBX is linked)
serverPingTimeout
string
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

Responses

Request samples

Content type
application/json
{
  • "bpId": "string",
  • "country": "str",
  • "isShared": true,
  • "name": "string",
  • "pbxInternationalPrefix": "string",
  • "pbxMainBundlePrefix": "string",
  • "pbxNationalPrefix": "string",
  • "pbxNumberingTranslator": [
    ],
  • "searchResultOrder": [
    ],
  • "serverPingTimeout": "120",
  • "siteId": "string",
  • "type": "oxo",
  • "usePbxMainBundlePrefix": true,
  • "version": "string"
}

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:
Bearer
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" "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).

header Parameters
accept
required
string

application/json

Responses

Response samples

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

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:
Bearer
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.

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

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
Items Enum: "RAINBOW" "LDAP" "PBX"

List of directory types to order search results:

  • RAINBOW: phone numbers defined in Rainbow users
  • LDAP: phone numbers defined in directories according to the following priority order:
    • personal directory of the user
    • company directory (of the company(ies) to which the PBX is linked)
    • office365 directory (of the company(ies) to which the PBX is linked)
  • PBX: phone numbers defined in the phone book of the PBX
serverPingTimeout
string
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

Responses

Request samples

Content type
application/json
{
  • "activationCode": "string",
  • "bpId": "string",
  • "country": "str",
  • "isCentrex": "false",
  • "isOxoManaged": true,
  • "isShared": "false",
  • "name": "string",
  • "pbxId": "string",
  • "pbxInternationalPrefix": "string",
  • "pbxMainBundlePrefix": [
    ],
  • "pbxNationalPrefix": "string",
  • "pbxNumberingTranslator": [
    ],
  • "searchResultOrder": [
    ],
  • "serverPingTimeout": "120",
  • "siteId": "string",
  • "type": "oxo",
  • "usePbxMainBundlePrefix": true,
  • "version": "string"
}

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.

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:
Bearer
path Parameters
pbxId
required
string

Pbx unique identifier known by PCG

query Parameters
connectionHistory
boolean

Allows to return connection history

header Parameters
accept
required
string

application/json

Responses

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 deleted user clients for disconnection
    • 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 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:
Bearer
path Parameters
userId
required
string

User unique identifier (like 56c5c19f94141765119f896c)

header Parameters
accept
required
string

application/json

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, support role can retrieve any user whatever the company.
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:
Bearer
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, guestMode
  • full: all user fields
header Parameters
accept
required
string

application/json

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, accountType 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:
Bearer
path Parameters
userId
required
string

User unique identifier (like 56c5c19f94141765119f896c)

Request Body schema: application/json
accountType
string
Default: "free"
Enum: "free" "basic" "advanced"

User subscription type

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 (return by identity provider in case of SAML or OIDC authenticationType)

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

Can only be set by users with role superadmin.

nickName
string [ 1 .. 255 ] characters

User nickName

password
string [ 8 .. 64 ] characters

User password.
Rules: more than 8 characters, 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

roles
Array of strings
Default: ["user"]
Items Enum: "guest" "user" "admin" "bp_admin" "bp_finance" "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.
  • 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.

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
{
  • "accountType": "free",
  • "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",
  • "nickName": "string",
  • "password": "stringst",
  • "phoneNumbers": [
    ],
  • "roles": [
    ],
  • "selectedDeviceFirmware": "same_as_company",
  • "selectedTheme": "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": {
    }
}

Get all users

This API allows administrators to list users.

Users with superadmin, business_admin, support role can retrieve users from any company.
Users with support role can retrieve lastLoginIOSDate and lastLoginAndroidDate providing format option full.

Users with bp_admin 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:
Bearer
query Parameters
phoneNumber
number

Allows to filter users list on the given number(s) on field phone number.

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

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.

isTerminated
string
Default: "false"

Allows to filter users list on the status 'isTerminated'.

By default, terminated users are not listed.

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)

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.

selectedAppCustomisationTemplate
string

Allows to filter users by the last application customisation template applied.

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

siteId
string

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

Option is reserved for superAdmin or admin allowed to manage the given siteIds.

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.

header Parameters
accept
required
string

application/json

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 ...)
Request Body schema: application/json
accountType
string
Default: "free"
Enum: "free" "basic" "advanced"

User subscription type

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 (return by identity provider in case of SAML or OIDC authenticationType)

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

nickName
string [ 1 .. 255 ] characters

User nickName

password
string [ 8 .. 64 ] characters

User password.
Rules: more than 8 characters, 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

roles
Array of strings
Default: ["user"]
Items Enum: "guest" "user" "admin" "bp_admin" "bp_finance" "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.
  • 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.

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
{
  • "accountType": "free",
  • "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",
  • "nickName": "string",
  • "password": "stringst",
  • "phoneNumbers": [
    ],
  • "roles": [
    ],
  • "selectedTheme": "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:
Bearer
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:
Bearer
path Parameters
userId
required
string

User unique identifier (like 56c5c19f94141765119f896c)

header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

header Parameters
accept
required
string

application/json

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:
Bearer
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

subscriptionId
required
string

Company subscription unique identifier.

header Parameters
accept
required
string

application/json

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:
Bearer
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:
Bearer
path Parameters
userId
required
string

User unique identifier (like 56d0277a0261b53142a5cab5)

header Parameters
accept
required
string

application/json

Responses

Response samples

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

Connectors

Send a command to a ldap connector user

This API can be used to send a command to a ldap connector user.

BP Admin and BP Finance users can only control users being in a company linked to their BP company.
Admin users can only control users being in their own company. (superadmin, organization_admin, company_admin)

  • the following XMPP message is sent to connector's jid_im to send the command:
    <message id="8413b42e-563c-4437-9a53-06f638b5ab69_0" type="management"
  from="pcloud_enduser_1@openrainbow.com/172440802160413612281463752830017532"
  to="5abb735b2d3c4e50adde276c50ec489c@@openrainbow.com"
  xmlns="jabber:client">
  <connectorcommand command="manual_synchro" commandId="xyz" xmlns="jabber:iq:configuration"
</message>
Authorizations:
Bearer
path Parameters
ldapId
required
string

ldap connector unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
command
required
string

Allows to specify a command to be performed by the ldap connector.
Allowed commands are: "manual_synchro", "manual_dry_run", "manual_synchro_directories", "manual_dry_run_directories".

Responses

Request samples

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

Response samples

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

Delete a ldap connector user

This API can be used to delete a ldap connector 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)

Authorizations:
Bearer
path Parameters
ldapId
required
string

ldap connector unique identifier (like 569ce8c8f9336c471b98eda1)

header Parameters
accept
required
string

application/json

Responses

Response samples

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

delete a config for the ldap connector

This API can be used to delete a ldap connector config.

BP Admin and BP Finance users can only delete a ldap config being in a company linked to their BP company.
Admin users can only delete ldap config being in their own company. (superadmin, organization_admin, company_admin)

Authorizations:
Bearer
path Parameters
ldapConfigId
required
string

ldap connector unique identifier (like 569ce8c8f9336c471b98eda1)

header Parameters
accept
required
string

application/json

Responses

Response samples

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

retrieve a config for the ldap connector by ldapConfigId

This API allows to retrieve the configuration for the connector with the ldapConfigId.

A template is available : use GET /api/rainbow/admin/v1.0/connectors/ldaps/config/template.

Users with superadmin, support role can get the connectors configuration from any company.

Users with bp_admin or bp_finance role can only get the connectors configurationin 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 get the connectors configuration in companies they can manage. That is to say:

  • an organization_admin can get the connectors configuration only in a company he can manage (i.e. companies having organisationId equal to his organisationId)
  • a company_admin can only get the connectors configuration in his company.
Authorizations:
Bearer
path Parameters
ldapConfigId
required
string

ldap connector unique identifier (like 569ce8c8f9336c471b98eda1)

header Parameters
accept
required
string

application/json

content-type
required
string

application/json

Responses

Response samples

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

update a config for the ldap connector

This API allows update the configuration for the connector.

A template is available : use GET /api/rainbow/admin/v1.0/connectors/ldaps/config/template.

Users with superadmin, support role can update the connectors configuration from any company.

Users with bp_admin or bp_finance role can only update the connectors configurationin 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 update the connectors configuration in companies they can manage. That is to say:

  • an organization_admin can update the connectors configuration only in a company he can manage (i.e. companies having organisationId equal to his organisationId)

  • a company_admin can only update the connectors configuration in his company.

  • the following XMPP message is sent to connector's jid_im to warn that the config 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">
  <connectorconfig action="update" configId="56c5c19f94141765119f896c" xmlns="jabber:iq:configuration"
</message>
Authorizations:
Bearer
path Parameters
ldapConfigId
required
string

ldap connector unique identifier (like 569ce8c8f9336c471b98eda1)

Request Body schema: application/json
name
required
string

name of this configuration

required
object
strict
boolean
Default: "false"

Allows to specify if all the previous fields must be erased or just update/push new fields.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "settings": {
    },
  • "strict": "false"
}

Response samples

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

get the list of configs for the ldap connector

This API allows to retrieve the configurations list for the connector.

A template can be retrieve : use GET /api/rainbow/admin/v1.0/connectors/ldaps/config/template.

Only one config object type is allowed for a company

Users with superadmin, support role can retrieve the connectors configuration from any company.

Users with bp_admin or bp_finance role can only retrieve the connectors configurationin 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 retrieve the connectors configuration in companies they can manage. That is to say:

  • an organization_admin can retrieve the connectors configuration only in a company he can manage (i.e. companies having organisationId equal to his organisationId)
  • a company_admin can only retrieve the connectors configuration in his company.
Authorizations:
Bearer
query Parameters
companyId
string

Allows to filter connectors config list on the companyId provided in this option.

In the case of admin (except superadmin and support roles), provided companyId should correspond to a company visible by logged in user's company (if some of the provided companyId are not visible by logged in user's company, connectors from these companies will not be returned).
if not provided, default is admin's company.

header Parameters
accept
required
string

application/json

content-type
required
string

application/json

Responses

Response samples

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

get list of config templates for the ldap connector

This API allows to retrieve all the configuration templates for the connector.

Authorizations:
Bearer
header Parameters
accept
required
string

application/json

content-type
required
string

application/json

Responses

Response samples

Content type
application/json
""

Get all ldap connector users data

This API allows administrators to retrieve all the ldap connectors.

Users with superadmin, support role can retrieve the connectors from any company.

Users with bp_admin or bp_finance role can only retrieve the connectors 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 retrieve the connectors in companies they can manage. That is to say:

  • an organization_admin can retrieve the connectors only in a company he can manage (i.e. companies having organisationId equal to his organisationId)
  • a company_admin can only retrieve the connectors in his company.

This API can return more or less connector information using format option in query string arguments (default is small).

Examples:

Authorizations:
Bearer
query Parameters
companyId
string

Allows to filter connectors list on the companyIds provided in this option.

In the case of admin (except superadmin and 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, connectors from these companies will not be returned).

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

header Parameters
accept
required
string

application/json

Responses

Response samples

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

get a config for the ldap connector

This API allows to retrieve the configuration for the connector.

A template can be retrieve : use GET /api/rainbow/admin/v1.0/connectors/ldaps/config/template.

Only one config object type is allowed for a company

Users with superadmin, support role can retrieve the connectors configuration from any company.

Users with bp_admin or bp_finance role can only retrieve the connectors configurationin 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 retrieve the connectors configuration in companies they can manage. That is to say:

  • an organization_admin can retrieve the connectors configuration only in a company he can manage (i.e. companies having organisationId equal to his organisationId)
  • a company_admin can only retrieve the connectors configuration in his company.
Authorizations:
Bearer
query Parameters
companyId
string

Allows to filter connectors config list on the companyId provided in this option.

In the case of admin (except superadmin and support roles), provided companyId should correspond to a company visible by logged in user's company (if some of the provided companyId are not visible by logged in user's company, connectors from these companies will not be returned).
if not provided, default is admin's company.

type
string
Default: "ldap_config"

Allows to filter connectors config list on the type provided in this option.
Allowed types are: "ldap_config", "ldap_config_directories".

header Parameters
accept
required
string

application/json

content-type
required
string

application/json

Responses

Response samples

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

create a config for the ldap connector

This API allows create configuration for the connector.

A template is available : use GET /api/rainbow/admin/v1.0/connectors/ldaps/config/template. This template will provide the list of settings that can be pushed.

Users with superadmin, support role can create the connectors configuration from any company.

Users with bp_admin or bp_finance role can only create the connectors configurationin 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 the connectors configuration in companies they can manage. That is to say:

  • an organization_admin can create the connectors configuration only in a company he can manage (i.e. companies having organisationId equal to his organisationId)

  • a company_admin can only create the connectors configuration in his company.

  • the following XMPP message is sent to connector's jid_im to warn that the config 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">
  <connectorconfig action="update" configId="56c5c19f94141765119f896c" xmlns="jabber:iq:configuration"
</message>
Authorizations:
Bearer
Request Body schema: application/json
companyId
required
string

Allows to specify for which company the connectors configuration is done..

name
required
string

name of this configuration

required
object
type
string
Default: "ldap_config"

specify for which type of synchronisation this config is .
Allowed types are: "ldap_config", "ldap_config_directories".

Responses

Request samples

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

Response samples

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

get a config template for the ldap connector

This API allows to retrieve the configuration template for the connector.

Authorizations:
Bearer
query Parameters
type
string
Default: "ldap_template"

Allows to filter connectors config list on the type provided in this option.
Allowed types are: "ldap_template", "ldap_template_directories".

header Parameters
accept
required
string

application/json

content-type
required
string

application/json

Responses

Response samples

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