logo
Documentation Powered by ReDoc

Rainbow Mass Provisioning portal (1.170.1)

Download OpenAPI specification:Download

Rainbow Mass Provisioning API guide

Preamble

Download Postman collection

Introduction

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

Protocol

REST interface is used for sending/receiving OT rainbow API messages.
HTTP request GET and POST 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.
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

Users And Devices

Check CSV data

This API checks a CSV UTF-8 content for mass-provisioning. Caution: To use the comment character ('%' by default) in a field value, surround this value with double quotes.

Authorizations:
Bearer

Responses

Response samples

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

check CSV data for synchronization using useranddevice mode

This API checks a CSV UTF-8 content for mass-provisioning for useranddevice mode. Caution: To use the comment character ('%' by default) in a field value, surround this value with double quotes.

  • In case a query parameter commandId is added, the following XMPP message is sent to the initiator of 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">
  <command_ended  commandId="xyz" xmlns="jabber:iq:configuration"/>
</message>
Authorizations:
Bearer

Responses

Response samples

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

Delete an import status report.

This API allows to delete the report of an import identified by its reqId.

path Parameters
reqId
required
string

the import request id

Responses

Response samples

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

Get an import status report.

This API allows to access the report of an import identified by its reqId.

Authorizations:
Bearer
path Parameters
reqId
required
string

the import request id

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

Allows to retrieve more or less report details.
- small: reporting without operation details
- full: reporting with operation details

header Parameters
accept
required
string

application/json

Responses

Response samples

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

get the check CSV report by commandId

This API retrieves the last checks CSV UTF-8 content for mass-provisioning for useranddevice mode, performed by an admin (using a commandId).

Authorizations:
Bearer
path Parameters
commandId
required
string

commandId used in the check csv request which came from connector on behalf of admin command

header Parameters
accept
required
string

application/json

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "report": {
    }
}

Get information on imports

This API provides information on all imports of the administrator's company.

query Parameters
companyId
required
string

companyId to list imports of

Responses

Response samples

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

Import CSV data

This API allows to manage Rainbow users or devices through a CSV UTF-8 encoded file.
The first line of the CSV data describes the content format. Most of the field names are the field names of the admin createUser API.

Caution: To avoid multiple imports of same CSV data, the reqId returned to access the import status is a hash of the CSV data. If you really need to apply same CSV data again, you will have to delete its associated import report first.

Supported fields for "user" management are:

  • __action__    delete, update or create (by default)
  • loginEmail    (mandatory)
  • password    (mandatory)
  • title
  • firstName
  • lastName
  • nickName
  • businessPhone{n}    (n is a number starting from 0 or 1)
  • mobilePhone{n}    (n is a number starting from 0 or 1)
  • email{n}    (n is a number starting from 0 or 1)
  • tags{n}    (n is a number starting from 0 to 4)
  • jobTitle
  • department
  • userInfo1
  • userInfo2
  • country
  • language
  • timezone
  • visibility
  • isInitialized
  • authenticationType
  • selectedAppCustomisationTemplateName
  • service{n}
  • accountType
  • photoUrl

Supported fields for "device" management are:

  • __action__    detach, attach or force_attach
  • loginEmail    (mandatory)
  • pbxId
  • pbxShortNumber
  • pbxInternalNumber
  • number

Caution: To use the comment character ('%' by default) in a field value, surround this value with double quotes.

Error codes

  • 1001 'phoneNumber {pbxId}/{shortNumber} has no system id'
  • 1002 'phoneNumber {pbxId}/{shortNumber} has no id'
  • 1003 'phoneNumber {pbxId}/{shortNumber} does not exist'
  • 1004 'cannot lookup phoneNumber {pbxId}/{shortNumber}'
  • 1005 'found {count} phoneNumber(s) for {companyId}/{shortNumber}'
  • 1006 'failed to find one single PBX for {companyId}/{shortNumber}'
  • 1007 'user has already a phoneNumber {pbxId}/{shortNumber}'
  • 1008 'phoneNumber {pbxId}/{shortNumber} already associated to user {userId}'
  • 1009 'failed to attach phoneNumber {pbxId}/{shortNumber}'
  • 1010 'user {userId} has no phoneNumber'
  • 1011 'user {userId} has too many phoneNumbers'
  • 1012 'failed to detach phoneNumber {pbxId}/{shortNumber}'
Authorizations:
Bearer

Responses

Response samples

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

get the import CSV report by commandId

This API retrieves the last import CSV UTF-8 content for mass-provisioning for useranddevice mode, performed by an admin (using a commandId).

Authorizations:
Bearer
path Parameters
commandId
required
string

commandId used in the import csv request which came from connector on behalf of admin command

header Parameters
accept
required
string

application/json

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "report": {
    }
}

create the report by commandId

This API allows to create a report for a commandId in case no other API is called (no action to be performed, error, ...).

Authorizations:
Bearer
path Parameters
commandId
required
string

commandId used in the import csv request which came from connector on behalf of admin command

Request Body schema: application/json
details
required
string

details that can be provided about the command execution

status
required
string
Enum: "success" "failure"

status for the execution of the command

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "status": "success",
  • "report": {
    }
}

synchronize with CSV data

This API allows to synchronize Rainbow users or devices through a CSV UTF-8 encoded file. it is a merge from user mode and device mode
The first line of the CSV data describes the content format. Most of the field names are the field names of the admin createUser API.

Supported fields for "user" management are:

  • __action__    delete, upsert, sync or detach
  • loginEmail    (mandatory)
  • password    (mandatory)
  • title
  • firstName
  • lastName
  • nickName
  • businessPhone{n}    (n is a number starting from 0 or 1)
  • mobilePhone{n}    (n is a number starting from 0 or 1)
  • email{n}    (n is a number starting from 0 or 1)
  • tags{n}    (n is a number starting from 0 to 4)
  • jobTitle
  • department
  • userInfo1
  • userInfo2
  • country
  • language
  • timezone
  • visibility
  • isInitialized
  • authenticationType
  • service{n}
  • accountType
  • photoUrl

Supported fields for "device" management are:

  • loginEmail    (mandatory)
  • pbxId
  • pbxShortNumber
  • pbxInternalNumber
  • number

detach: allows to detach an PBX extension from a user. delete: allows to delete a user. upsert: allows to modify user (update or create if doesn't exists) and device (force attach if filled) with filled fields. Remark: empty fields are not taken into account. sync: allows to modify user (update or create if doesn't exists) and device (force attach if filled, detach if empty) with filled fields. Remark: empty fields are taken into account (if a field is empty we will try to update it with empty value).

Caution: To use the comment character ('%' by default) in a field value, surround this value with double quotes. Caution: for sync action:

  • As empty fields are taken into account, all fields must be filled to avoid a reset of these values
  • As empty fields are taken into account, it is better to avoid mixing sync __action__ with others actions

Error codes

  • 1001 'phoneNumber {pbxId}/{shortNumber} has no system id'
  • 1002 'phoneNumber {pbxId}/{shortNumber} has no id'
  • 1003 'phoneNumber {pbxId}/{shortNumber} does not exist'
  • 1004 'cannot lookup phoneNumber {pbxId}/{shortNumber}'
  • 1005 'found {count} phoneNumber(s) for {companyId}/{shortNumber}'
  • 1006 'failed to find one single PBX for {companyId}/{shortNumber}'
  • 1007 'user has already a phoneNumber {pbxId}/{shortNumber}'
  • 1008 'phoneNumber {pbxId}/{shortNumber} already associated to user {userId}'
  • 1009 'failed to attach phoneNumber {pbxId}/{shortNumber}'
  • 1010 'user {userId} has no phoneNumber'
  • 1011 'user {userId} has too many phoneNumbers'
  • 1012 'failed to detach phoneNumber {pbxId}/{shortNumber}'
  • In case a query parameter commandId is added, the following XMPP message is sent to the initiator of 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">
  <command_ended  commandId="xyz" xmlns="jabber:iq:configuration"/>
</message>
Authorizations:
Bearer

Responses

Response samples

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

Generate a CSV template

This API provides a CSV template.

Authorizations:
Bearer
query Parameters
companyId
string

companyId to generate a template for, default to admin's companyId

mode
string
Default: "user"
Enum: "user" "device" "useranddevice" "rainbowvoice"

Select template to return.
- user: provider the user management template
- device: provider the device management template
- useranddevice: provider the user and device management template (both user and device)
- rainbowvoice : provider the user and subscriber/DDI/device association management template

comment
string
Default: "false"

Only the template comment.

header Parameters
accept
required
string

application/json

Responses

Response samples

Content type
application/json
application/json
text/csv
{
  • "Content-Type": "text/csv",
  • "Content-disposition": "string",
  • "CSV": [
    ]
}