REST API

The XiVO Centralized User Management (XCU) exposes some REST API that you can use to integrate with your tools.

General form

http://$my-server-ip:$xcuport/api/1.0/$method

withHeaders((“Content-Type”, “application/json”))

  • $xcuport : XCU port number (default 9001)
  • $method : See available methods below

Login

A login request is required before subsequent API calls in order to get a session cookie.

POST /api/1.0/login

Payload parameters :

login (String)
Login to connect with
password (String)
Password corresponding to the login

The server will return a cookie and you will be able to do other API calls. Example with CURL :

curl 'http://localhost:9000/api/1.0/login' -H 'Content-Type: application/json' -c 'xcu-cookie' --data-binary '{"login":"admin","password":"superpass"}'
curl 'http://localhost:9000/api/1.0/xivo' -H 'Content-Type: application/json' -b 'xcu-cookie'

XiVO

The following methods allow you to operate on the XiVOs managed by XCU.

List

List all the XiVOs configured on XCU.

GET /api/1.0/xivo
{
  "items": [
    {
      "id": 1,
      "uuid": "8f159082-4b25-48b3-afec-1873491a60be",
      "name": "xivo-220",
      "host": "192.168.29.220",
      "remainingSlots": 664
    },
    {
      "id": 2,
      "uuid": "15585b75-1d75-45b1-8678-520d1210ec59",
      "name": "xivo-221",
      "host": "192.168.29.221",
      "remainingSlots": 280
    }
  ]
}

Get

Get a XiVO by its id.

GET /api/1.0/xivo/$id
{
  "id": 1,
  "uuid": "8f159082-4b25-48b3-afec-1873491a60be",
  "name": "xivo-220",
  "host": "192.168.29.220",
  "remainingSlots": 664
}

Create

Create a new XiVO.

POST /api/1.0/xivo

Payload parameters :

name (String)
Display name of the XiVO
host (String)
Hostname or IP address of the XiVO
configure (Boolean)
If set to true, XCI will immediately make the necessary configurations on the XiVO. If set to false, it will only be added to XCI but not configured.

Synchronize configuration files

GET /api/1.0/xivo/synchronize_config_files

Entities

The following methods allow you to operate on the entities made available by the XiVOS.

List

List all the entities available.

GET /api/1.0/entities
{
  "items": [
    {
      "id": 17,
      "combinedId": "[email protected]",
      "name": "default",
      "displayName": "default",
      "xivo": {
        "id": 2,
        "uuid": "15585b75-1d75-45b1-8678-520d1210ec59",
        "name": "xivo-221",
        "host": "192.168.29.221",
        "remainingSlots": 280
      },
      "intervals": [
        {
          "start": "1700",
          "end": "1799"
        },
        {
          "start": "1961",
          "end": ""
        },
        {
          "start": "2600",
          "end": "2799"
        }
      ],
      "presentedNumber": "inbNo"
    },
    {
      "id": 22,
      "combinedId": "[email protected]",
      "name": "default_analogique",
      "displayName": "default_analogique",
      "xivo": {
        "id": 2,
        "uuid": "15585b75-1d75-45b1-8678-520d1210ec59",
        "name": "xivo-221",
        "host": "192.168.29.221",
        "remainingSlots": 280
      },
      "intervals": [
        {
          "start": "3990000",
          "end": "3999999"
        },
        {
          "start": "39990000",
          "end": "39999999"
        }
      ],
      "presentedNumber": "inbNo"
    }
  ]
}

Get

Get an entity by its combinedId.

GET /api/1.0/entities/$combinedId
{
  "id": 22,
  "combinedId": "[email protected]",
  "name": "default_analogique",
  "displayName": "default_analogique",
  "xivo": {
    "id": 2,
    "uuid": "15585b75-1d75-45b1-8678-520d1210ec59",
    "name": "xivo-221",
    "host": "192.168.29.221",
    "remainingSlots": 280
  },
  "intervals": [
    {
      "start": "3990000",
      "end": "3999999"
    },
    {
      "start": "39990000",
      "end": "39999999"
    }
  ],
  "presentedNumber": "inbNo"
}

Create

Create a new entity.

POST /api/1.0/entities

Payload parameters :

name (String)
Name of the entity
displayName (String)
Displayed name of the entity
xivoId (Integer)
Id of the XiVO the entity will be attached to
intervals (Array)

Intervals of numbers this entity will support

start (String)
Starting number of the interval
end (String)
Ending number of the interval
presentedNumber (String)
Number to show on outgoing calls

Delete

Delete an entity.

DELETE /api/1.0/entities/$combinedId

Edit

Edit an entity. See Create entity for fields details.

PUT /api/1.0/entities/$combinedId

List users

List users attached to an entity.

GET /api/1.0/entities/$combinedId/users
{
  "items": [
    {
      "id": 559,
      "entity": {
        "id": 22,
        "combinedId": "[email protected]",
        "name": "default_analogique",
        "displayName": "default_analogique",
        "xivo": {
          "id": 2,
          "uuid": "15585b75-1d75-45b1-8678-520d1210ec59",
          "name": "xivo-221",
          "host": "192.168.29.221",
          "remainingSlots": 280
        },
        "intervals": [
          {
            "start": "3990000",
            "end": "3999999"
          },
          {
            "start": "39990000",
            "end": "39999999"
          }
        ],
        "presentedNumber": "inbNo"
      },
      "firstName": "Sous sol Logistique",
      "lastName": "CLF 88:40 P3",
      "internalNumber": "6260",
      "externalNumber": "\"Sous sol Logistique CLF 88:40 P3\"",
      "mail": null,
      "ctiLogin": null,
      "ctiPassword": null,
      "provisioningNumber": "114133"
    }
  ]
}

List available numbers

List available numbers for an entity

GET /api/1.0/entities/$combinedId/available_numbers
{
  "items": [
    "3990000",
    "3990001",
    "3990002",
    "3990003",
    "3990004"
  ]
}

Users

The following methods allow you to operate on the users made available by the XiVOS.

Get

Get a user by its id.

GET /api/1.0/users/$id
{
  "id": 559,
  "entity": {
    "id": 22,
    "combinedId": "[email protected]",
    "name": "default_analogique",
    "displayName": "default_analogique",
    "xivo": {
      "id": 2,
      "uuid": "15585b75-1d75-45b1-8678-520d1210ec59",
      "name": "xivo-221",
      "host": "192.168.29.221",
      "remainingSlots": 280
    },
    "intervals": [
      {
        "start": "3990000",
        "end": "3999999"
      },
      {
        "start": "39990000",
        "end": "39999999"
      }
    ],
    "presentedNumber": "inbNo"
  },
  "firstName": "Sous sol Logistique",
  "lastName": "CLF 88:40 P3",
  "internalNumber": "6260",
  "externalNumber": null,
  "mail": null,
  "ctiLogin": null,
  "ctiPassword": null,
  "provisioningNumber": "114133"
}

Create

Create a new user.

POST /api/1.0/users

Payload parameters :

entityCId (String)
Entity combinedId the user will be attached to
templateId (Integer)
Line template to apply to the user
firstName (String)
First name of the user
lastName (String)
Last name of the user
internalNumber (String)
Internal phone number of the user
ctiLogin (String) Optional
CTI login of the user
ctiPassword (String) Optional
CTI password of the user

Delete

Delete a user.

DELETE /api/1.0/users/$id

Edit

Edit a user. See Create user for fields details.

PUT /api/1.0/users/$id

Templates

The following methods allow you to operate on the line templates used to create users.

List

List all the templates available.

GET /api/1.0/templates
[
  {
    "id": 1,
    "name": "Modèle 220",
    "peerSipName": "auto",
    "routedInbound": false,
    "callerIdMode": "incomingNo",
    "ringingTime": 30,
    "voiceMailEnabled": false,
    "voiceMailNumberMode": "short_number",
    "xivos": [
      1
    ],
    "entities": [
      "[email protected]"
    ]
  }
]

Get

Get a template by its id.

GET /api/1.0/templates/$id
{
  "id": 1,
  "name": "Modèle 220",
  "peerSipName": "auto",
  "routedInbound": false,
  "callerIdMode": "incomingNo",
  "ringingTime": 30,
  "voiceMailEnabled": false,
  "voiceMailNumberMode": "short_number",
  "xivos": [
    1
  ],
  "entities": [
    "[email protected]"
  ]
}

Create

Create a new template.

POST /api/1.0/templates

Payload parameters :

name (String)
Name of the template
xivos (Array of Integer)
List of XiVOs ids the template will be available to
entities (Array of String)
List of entities combinedIds the template will be available to
peerSipName (String)
Possible values are auto or model
ringingTime (Integer)
Number of seconds before incoming call is rejected
routedInbound (Boolean)
Whether or not the phone can be called from the outside
routedInboundPrefix (String) Compulsory if routedInbound is true
SDA prefix to call the phone
callerIdMode (String)
Option specifying what number is displayed on outgoing call. Possible values are :
  • incomingNo : use the SDA prefix
  • anonymous : masked call
  • custom : a custom number
customCallerId (String) Compulsory if callerIdMode is custom
Custom number to display on outgoing call
voiceMailEnabled (Boolean)
Whether or not to enable the voice mail
voiceMailNumberMode (Boolean)
Option specifying what number is used to call the voice mail. Possible values are :
  • short_number : use the default short number
  • custom : a custom number
voiceMailCustomNumber (String) Compulsory if voiceMailNumberMode is custom
Custom number to call the voice mail
voiceMailSendEmail (Boolean)
Whether or not to send an email when a new message is left

Delete

Delete a template.

DELETE /api/1.0/templates/$id

Edit

Edit a template. See Create template for fields details.

PUT /api/1.0/templates/$id

Administrators

The following methods allow you to operate on the administrators of the XCI.

List

List all the administrators present.

GET /api/1.0/administrators
{
  "items": [
    {
      "id": 1,
      "login": "admin",
      "name": "",
      "password": "+\/\/rIncoyp\/Ai\/8l3xSEeSY+P+x4uNle7cHkL6rpPS3ucgr2EAJIqnQbsIpSGwHj",
      "superAdmin": true,
      "ldap": false,
      "entities": [

      ]
    }
  ]
}

Get

Get an administrator by its id.

GET /api/1.0/administrators/$id
{
  "id": 1,
  "login": "admin",
  "name": "",
  "password": "+\/\/rIncoyp\/Ai\/8l3xSEeSY+P+x4uNle7cHkL6rpPS3ucgr2EAJIqnQbsIpSGwHj",
  "superAdmin": true,
  "ldap": false,
  "entities": [

  ]
}

Create

Create a new administrator.

POST /api/1.0/administrators

Payload parameters :

login (String)
Login of the administrator
name (String)
Displayed name of the administrator
ldap (Boolean)
Whether or not to use the LDAP authentication configured in application.conf
password (String) Compulsory if ldap is false
Password used by the administrator to login
superAdmin (Boolean)
Whether or not this administrator is a super-administrator. Super-administrators can manage everything in XCI.
entityIds (Array of Integer)
List of entities this administrator has the rights to manage

Delete

Delete an administrator.

DELETE /api/1.0/administrators/$id

Edit

Edit an administrator. See Create administrator for fields details.

PUT /api/1.0/administrators/$id

Example (Python 3)

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from urllib.parse import urlencode
from urllib.request import Request, urlopen
import json, sys

class XCIApiExample:
        base_url = None
        cookie = None

        def __init__(self, base_url, login, password):
                self.base_url = base_url
                self.make_login(login, password)

        def make_login(self, login, password):
                data = {"login": login, "password": password}
                response = self.make_post_request("/login", data)
                self.cookie = response.info()["Set-Cookie"]

        def get_entities(self):
                response = self.make_get_request("/entities")
                return self.handle_json_response(response)

        def get_available_numbers(self, entity):
                response = self.make_get_request("/entities/" + entity["combinedId"] + "/available_numbers")
                return self.handle_json_response(response)

        def create_line_template(self, data):
                self.make_post_request("/templates", data)

        def get_line_templates(self):
                response = self.make_get_request("/templates")
                return self.handle_json_response(response)

        def create_user(self, data):
                self.make_post_request("/users", data)

        def make_get_request(self, method):
                request = Request(self.base_url + method, headers = {"Cookie": self.cookie})
                response = urlopen(request)
                return response

        def make_post_request(self, method, data):
                header = {"Content-Type": "application/json", "Cookie": self.cookie if self.cookie else ""}
                request = Request(self.base_url + method, json.dumps(data).encode(), header)
                response = urlopen(request)
                return response

        def handle_json_response(self, response):
                return json.loads(response.read().decode())


# Initialize API
api_example = XCIApiExample("http://192.168.29.103:9001/api/1.0", "admin", "superpass")

# Get an entity and its XiVO
entities = api_example.get_entities()["items"]
if (len(entities) == 0):
        sys.exit("There isn't any XiVO configured yet or they don't have any entity !")
else:
        entity = entities[1]
        xivo = entity["xivo"]
        print("Selected entity \"%s\" in XiVO \"%s\""%(entity["name"], xivo["name"]))

# Create a line template
template_data = {
        "name": "My line template",
        "xivos": [xivo["id"]],
        "entities": [entity["combinedId"]],
        "peerSipName": "auto",
        "ringingTime": 30,
        "routedInbound": False,
        "callerIdMode": "anonymous",
        "voiceMailEnabled": False
}
api_example.create_line_template(template_data)
line_template = api_example.get_line_templates()[0]
print("New line template created")

# Create a user
user_data = {
        "entityCId": entity["combinedId"],
        "templateId": line_template["id"],
        "firstName": "Alice",
        "lastName": "In Wonderland",
        "internalNumber": api_example.get_available_numbers(entity)["items"][0]
}
api_example.create_user(user_data)
print("New user created")