Access Device Management

Retrieve Access Device list

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/

Retrieve the access devices list.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/access_devices/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "access_devices":
      [
         {
            "status": "Online",
            "deviceName": "APIO Test Device",
            "version": "",
            "macAddress": "221100CCBBAA",
            "netAddress": "",
            "freePorts": 99999,
            "deviceType": "Generic SIP Phone"
         },
         {
            "status": "Online",
            "deviceName": "DP_ApioUserTest",
            "version": "pjsip python",
            "macAddress": "",
            "netAddress": "",
            "freePorts": 99999,
            "deviceType": "Generic SIP Phone"
         }
      ]
}
Response JSON Object:
Status Codes:

Retrieve Access Device details

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/(string: instance_name)/

Retrieve the access device details.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/access_devices/APIO%20Test%20Device%20New/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "configurationFileName": "",
   "macAddress": "332211CCBBAA",
   "useCustomUserNamePassword": false,
   "protocol": "SIP 2.0",
   "stunServerNetAddress": "",
   "numberOfAssignedPorts": 0,
   "netAddress": "",
   "version": "",
   "deviceType": "Generic SIP Phone",
   "outboundProxyServerNetAddress": "",
   "status": "Online",
   "numberOfPorts": -1,
   "description": "APIO Test Device New",
   "userName": "",
   "physicalLocation": "",
   "transportProtocol": "Unspecified",
   "serialNumber": "",
}
Response JSON Object:
Status Codes:

Create an access device

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/

Create a new access device..

Authorization rights: minimum Group Admin.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/access_devices/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "deviceName": "APIO Test Device",
   "deviceType": "Generic SIP Phone",
   "protocol": "SIP 2.0",
   "macAddress": "221100CCBBAA",
   "description": "APIO Test Device",
   "transportProtocol": "Unspecified",
   "useCustomUserNamePassword": false
}
Request JSON Object:

Example response:

Response:

Similar to GET list method response. Should be the instance!

Status Codes:

Update an access device

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/(string: instance_name)/

Update the access device settings.

Authorization rights: minimum Group Admin.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/access_devices/APIO%20Test%20Device%20New/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "macAddress": "110022BBAACC",
   "description": "APIO Test Device Modified"
}
Request JSON Object:

Example response:

Response:

Similar to GET instance method response.

Status Codes:

Remove an access device

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/(string: instance_name)/

Delete an access device from the Group.

Authorization rights: minimum Group Admin.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/access_devices/APIO%20Test%20Device%20New/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Status Codes:

Retrieve a group device profile file

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/(string: instance_name)/config_files/(string: sub_instance_name)/

Retrieve a group device profile file.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/access_devices/foodevice/config_files/foofile/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "fileSource": "Default",
   "configurationFileName": "/var/broadworks/IpDeviceConfig/type/CTYealink-T48G/%BWMACADDRESS%.cfg.template",
   "accessUrl": "http://10.0.12.78:80/dms/CTYealinkT48G/{%25BWMACADDRESS%25}.cfg",
   "repositoryUrl": "http://fileadmin:1234567@sfocps.netaxis.be:80/CTYealink-T48G/APIO%20Test%20Device%20Buttons%20(Group%20ApioSpTest-ApioGrpTest).cfg",
   "templateUrl": "http://device_management:d*2m*$ment@10.0.12.74:80/DeviceManagement/type/CTYealink-T48G/%25BWMACADDRESS%25.cfg.template",
   "extendedCaptureEnabled": false
}
Response JSON Object:
Status Codes:

Update a group device profile file

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/(string: instance_name)/config_files/(string: sub_instance_name)/

Update a group device profile file.

Authorization rights: minimum Group Admin.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/access_devices/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "fileSource": "Custom",
   "fileContent": "IyBUZXN0IGNvbmZpZyBmaWxlIGZvciBhY2Nlc3MgZGV2aWNlCg=="
}
Request JSON Object:

  • fileSource (string) – See fileSource from Device file attributes.

  • fileContent (optional) (string) – The file to upload, base64 encoded.

  • extendedCaptureEnabled (boolean) – See extendedCaptureEnabled from Device file attributes.

Example response:

Response:

Similar to GET list method response. Should be the instance!

Status Codes:

Retrieve a list of device files

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/(string: instance_name)/config_files/

Retrieve a list of device files.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/access_devices/foodevice/config_files/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "access_devices": [
      {
         "fileFormat": "%BWMACADDRESS%.cfg",
         "isAuthenticated": "true",
         "accessUrl": "http://10.0.12.78:80/dms/CTYealinkT48G/{%25BWMACADDRESS%25}.cfg",
         "repositoryUrl": "http://fileadmin:1234567@sfocps.netaxis.be:80/CTYealink-T48G/APIO%20Test%20Device%20Buttons%20(Group%20ApioSpTest-ApioGrpTest).cfg",
         "templateUrl": "http://device_management:d*2m*$ment@10.0.12.74:80/DeviceManagement/type/CTYealink-T48G/%25BWMACADDRESS%25.cfg.template"
      },
      {
         "fileFormat": "y000000000035.cfg",
         "isAuthenticated": "true",
         "accessUrl": "http://10.0.12.78:80/dms/CTYealinkT48G/y000000000035.cfg",
         "repositoryUrl": "http://fileadmin:1234567@sfocps.netaxis.be:80/CTYealink-T48G/y000000000035-2017.10.13%2017:22:40:940%20CEST.cfg",
         "templateUrl": "http://device_management:d*2m*$ment@10.0.12.74:80/DeviceManagement/type/CTYealink-T48G/y000000000035.cfg.template"
      }
   ]
}
Response JSON Object:
Status Codes:

Reboot an access device

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/(string: instance_name)/reboot_phone/

This API will ask the phone to reboot (via the Application Server).

Authorization rights: minimum Group Admin.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/access_devices/foodevice/reboot_phone/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{}
Status Codes:

Retrieve List of Users connected to an Access Device

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/(string: instance_name)/connected_users/

Retrieve the access device connected users list.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/access_devices/APIO%20Test%20Device/connected_users/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "connected_users": [{
         "linePort": "LP_ApioUserTest1@sip.netaxis.be",
         "lastName": "Test1",
         "firstName": "Test1",
         "phoneNumber": "025126778",
         "userId": "ApioUserTest1@sip.netaxis.be",
         "userType": "Normal",
         "endpointType": "Primary",
         "order": 1,
         "primary": false,
         "extension": "5001",
         "department": {
            "tenantId": "ApioSpTest",
            "groupId": "ApioGrpTest",
            "departmentName": "test_department_initial",
            "fullPathName": "test_department_initial"
         },
         "emailAddress": ""
      },
      {
         "linePort": "LP_ApioUserTest2@sip.netaxis.be",
         "lastName": "Test2",
         "firstName": "Test2",
         "phoneNumber": "",
         "userId": "ApioUserTest2@sip.netaxis.be",
         "userType": "Normal",
         "endpointType": "Primary",
         "order": 3,
         "primary": false,
         "extension": "5002",
         "emailAddress": ""
      }
   ],
   "noLineReOrdering": false,
   "staticLineReOrdering": true
}
Response JSON Object:

  • connected_users (array) – a list of access devices connected users. See User connected to a Device attributes.

  • noLineReOrdering (boolean) – indicate if the line/port reordering feature is disabled or not. It it is disabled then no PUT is allowed for that particular end point/

  • staticLineReOrdering (boolean) – indicate if the line/port reorderign feature supports static ordering (gaps allowed) or not.

Status Codes:

Update the port (order) of the Users connected to an Access Device

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/(string: instance_name)/connected_users/

Update the port/line/order of the users connected to a phone. This is mainly usefull for DECT phones and phones with multiple lines

This feature is not supported by all type of phones and when not supported not always in the same way:

  • Virtual Devices, such as Generic SIP Phones, does not support theis feature

  • Device with dynamic port ordering allow to specify the order but not have gaps between ports (so 1, 2, 3 is supported but not 1,2 4)

  • Devices with static port ordering allow to specify the exact port (such as port 1, 2 and 4 used but not the 3).

Authorization rights: minimum Group Admin.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/access_devices/APIO%20Test%20Device/connected_users/ HTTP/1.1
Host: example.com

{
   "connected_users": [{
         "linePort": "LP_ApioUserTest1@sip.netaxis.be",
         "userId": "ApioUserTest1@sip.netaxis.be",
         "order": 2,
      },
      {
         "linePort": "LP_ApioUserTest2@sip.netaxis.be",
         "userId": "ApioUserTest2@sip.netaxis.be",
         "order": 1,
      }
   ]
}

or
{
   "connected_users": ["LP_ApioUserTest2@sip.netaxis.be", "LP_ApioUserTest1@sip.netaxis.be"]
}

:<json array connected_users: the re-ordered list of the users connected connected to the access device. It can either be an ordered list of strings (the linePort of the connected user) of a list of objects (As defined in :ref:`access_device_connected_user_list_attributes`).

If the **connected_users** is a list of strings, the port/order is the index in the list.
If the **connected_users** is a list of objects, the port/order is defined by the **order** attribute of the object

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "connected_users": [{
         "linePort": "LP_ApioUserTest1@sip.netaxis.be",
         "lastName": "Test1",
         "firstName": "Test1",
         "phoneNumber": "025126778",
         "userId": "ApioUserTest1@sip.netaxis.be",
         "userType": "Normal",
         "endpointType": "Primary",
         "order": 2,
         "primary": false,
         "extension": "5001",
         "department": {
            "tenantId": "ApioSpTest",
            "groupId": "ApioGrpTest",
            "departmentName": "test_department_initial",
            "fullPathName": "test_department_initial"
         },
         "emailAddress": ""
      },
      {
         "linePort": "LP_ApioUserTest2@sip.netaxis.be",
         "lastName": "Test2",
         "firstName": "Test2",
         "phoneNumber": "",
         "userId": "ApioUserTest2@sip.netaxis.be",
         "userType": "Normal",
         "endpointType": "Primary",
         "order": 1,
         "primary": false,
         "extension": "5002",
         "emailAddress": ""
      }
   ]
}
Response JSON Object:
Status Codes:

  • 200 OK – no error

  • 400 Bad Request –

    Impossible to reorder the ports. With, among others, the following specific cases:

    • 56: UNSUPPORTED_OPERATION, “This type of device does not support users reordering”

    • 2: INVALID_PARAMETERS, “Each port (order) can only be present once”

    • 2: INVALID_PARAMETERS, “All connected users must he provided in the PUT, no partial update allowed”

    • 2: INVALID_PARAMETERS, “All linePorts in the new values mmust be present in the old values”

    • 2: INVALID_PARAMETERS, “A port (order) can not be bigger than the maximum number of ports of the device”

Retrieve the list of tags available for a group device profile

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/access_devices/(string: instance_name)/available_tags/

Retrieve the list of tags available for the access device. It is the combination of the tags defined at System level, tags defined at Group level for the Device Profile Type and tags defined for that particular Device.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/access_devices/foodevice/available_tags/ HTTP/1.1
Host: example.com
Request JSON Object:

  • tagSetName (string) – (Optional) list only the tags from that specific System level Tags Set (warning: System Default is not considered as a tags set).

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
    "availableTags": [
        {
            "name": "%Tag_Yealink_1%",
            "value": "",
            "level": "System_DeviceType",
            "tagSetName": "Yealink-T4x_Tags",
            "regionName": ""
        },
        {
            "name": "%Tag_System_1%",
            "value": "",
            "level": "System_Default",
            "tagSetName": "System Default",
            "regionName": ""
        },
        {
            "name": "%Tag_Yealink_2%",
            "value": "99",
            "level": "System_DeviceType",
            "tagSetName": "Yealink-T4x_Tags",
            "regionName": ""
        },
        {
            "name": "%Tag_Yealink_3%",
            "value": "",
            "level": "System_DeviceType",
            "tagSetName": "Yealink-T4x_Tags",
            "regionName": ""
        },
        {
            "name": "%Tag_Group_DT_1%",
            "value": "",
            "level": "Group_DeviceType",
            "tagSetName": "",
            "regionName": ""
        },
        {
            "name": "%Tag_System_2",
            "value": "",
            "level": "System_Default",
            "tagSetName": "System Default",
            "regionName": ""
        },
        {
            "name": "%Tag_DP%",
            "value": "",
            "level": "DeviceProfile",
            "tagSetName": "",
            "regionName": ""
        }
    ]
}
Response JSON Object:

  • availableTags (array) – The list of available tags, with the structure defined below.

Status Codes:

  • 200 OK – no error

  • 404 Not Found – in case of Device Profile not found or Tag Set Name not found

Available Tags Item Attributes

Name

Type

Method

Description

GET

name

String

A

The name of the tag.

value

String

A

The value configured for that tag.

level

String

A

The level where the tag has been defined: “System_Default”, “System_DeviceType”, “Group_DeviceType”, “DeviceProfile”.

tagSetName

String

A

The name of the tags set of type “System_DeviceType” defined for this device profile type.

regionName

String

A

The name of the region relevant for this tag.