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": "default@15585b75-1d75-45b1-8678-520d1210ec59",
      "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": "default_analogique@15585b75-1d75-45b1-8678-520d1210ec59",
      "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": "default_analogique@15585b75-1d75-45b1-8678-520d1210ec59",
  "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": "default_analogique@15585b75-1d75-45b1-8678-520d1210ec59",
        "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": "default_analogique@15585b75-1d75-45b1-8678-520d1210ec59",
    "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": [
      "default@8f159082-4b25-48b3-afec-1873491a60be"
    ]
  }
]

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": [
    "default@8f159082-4b25-48b3-afec-1873491a60be"
  ]
}

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