REST API

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

Contents

• REST API

  • General form

  • Login

  • XiVO

    • List

    • Get

    • Create

    • Synchronize configuration files

  • Entities

    • List

    • Get

    • Create

    • Delete

    • Edit

    • List users

    • List available numbers

  • Users

    • Get

    • Create

    • Delete

    • Edit

  • Templates

    • List

    • Get

    • Create

    • Delete

    • Edit

  • Administrators

    • List

    • Get

    • Create

    • Delete

    • Edit

  • Example (Python 3)

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