API docs by Redocly

API Example (1.0.0)

Download OpenAPI specification:Download

Refer to the documentation links for further details and how to obtain parameter values.
Select the name from the Example dropdown in the Response samples to see example output.
See also:
Return to the API Guide.

GET /tool/Macro

Syntax:

GET https://<hostname>/api/tool/Macro/
    ?hierarchy=<hierarchy>
    &method=evaluate
    &input='<macro>'

Parameter values:

  • the hierarchy specified in the <hierarchy> parameter
  • the macro specified in the <input> parameter

GET /tool/Macro with example parameters

Links provide details in the API Guide. To see a response in Response samples, select it from Example dropdown.

Customers (with HCM-F)

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB&method=evaluate
&input='{# device.hcmf.Customer.shortName,extendedName,dealIDInfo | type: Customer #}'
  • with dealIDInfo:
    GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB&method=evaluate
&input='{# device.hcmf.Customer. shortName,extendedName | dealIDInfo:01150015 | type: Customer #}'

Customers (without HCM-F)

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB&method=evaluate
&input='{# data.HCSHcmfCustomerDAT.shortName,extendedName,dealIDInfo #}'
  • with dealIDInfo:
    GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB&method=evaluate
&input='{# data.HCSHcmfCustomerDAT.shortName,extendedName | dealIDInfo:VC-1010 #}'

Sites belonging to the Customer

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB&method=evaluate
&input={# device.hcmf.CustomerLocation.shortName | bkCustomer_shortName:Innovia #}

Directory numbers

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate
&input='{# data.InternalNumberInventory.internal_number,e164number,description,status,usage #}'

Next available number

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate
&input='{{ fn.one data.InternalNumberInventory.internal_number | status:Available | direction:up }}'

Phone models currently available to a customer

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate
&input='{{ data.PhoneConfigMapping.profiles.*.profile_name | name:Default }}'

Phone models currently offered to customers by the provider

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate
&input='{# data.HcsDeviceTypeDAT.name | name:/^Cisco \d\d\d\d/ | direction:up #}'

All phones belonging to the customer

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate&format=json
&input='{# device.cucm.Phone.__pkid,name,product,description,ownerUserName,lines.line.index,lines.line.dirn.pattern,lines.line.display,lines.line.displayAscii,lines.line.label,lines.recordingFlag,lines.recordingMediaSource,lines.recordingProfileName #}'

Subscriber PKID and Name

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate&format=json
&input='{# device.cucm.User.firstName,userid,__pkid,lastName #}'

All phones at a customer/site

customer:
GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate&format=json
&input='{{ fn.get_phone_choices ,,,down }}'
site:
GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate&format=json
&input='{{ fn.get_phone_choices ,,,local }}'

All phones belonging to a user

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate&format=json
&input='{{ fn.one device.cucm.User.associatedDevices.device | userid:ZAID.AL-FARHAN }}'

All Phones without associated user

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate
&input='{# device.cucm.Phone.name,description | ownerUserName:null | direction:local #}'

All DeviceProfiles without associated user

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate
&input='{# fn.list_set_left macro.DEVICEPROFILE_LIST,macro.PHONEPROFILE_LIST_FLATTENED #}'

All Line Details

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate
&input='{# device.cucm.Line.__pkid,pattern,description,alertingname,asciialertingname #}'

Subscribers Lines

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate
&input='{{ fn.get_associated_lines M.O.Alshahri }}'

Protocols supported

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate
&input='{{device.cucm.PhoneType.ProtocolTemplates.*.Protocol | PhoneType:Cisco 6901 | direction:up, device:macro.SITE_CUCM }}'

Phone Button Templates for Phone Model

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate
&input='{{ device.cucm.PhoneType.ProtocolTemplates.*.PBT| PhoneType:Cisco 9971, ProtocolTemplates.*.Protocol:SIP | direction:up, device:macro.SITE_CUCM }}'

Security Profiles for Phone Model

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate
&input='{{ device.cucm.PhoneType.ProtocolTemplates.*.SecurityProfile | PhoneType:Cisco 9951, ProtocolTemplates.*.Protocol:SIP | direction:up, device:macro.SITE_CUCM }}'

Subscriber Phones and Services

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate&nowait=true&format=json
&input='{{ fn.movesub_getguirules_on_username_change zaid.al-farhan }}'

Available Hierarchies of a Customer

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate
&input='{# fn.friendly_path_choices ,down #}'

Usernames at Customer and downwards

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate
&input='{{ fn.list_end_user_names down, fn.null }}'

User Details

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate&format=json
&input='{# data.User.username,first_name,last_name,email,sync_type | username: zaid.al-farhan #}'

Customer Common Phone Configs

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia&method=evaluate&format=json
&input='{# device.cucm.CommonPhoneConfig.name #}'

Available Quick Add Groups

GET /api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate&format=json
&input='{# data.QuickAddGroups.group_name || direction:up, to:Hcs #}'

Unassociated phones of specific model at Site

GET https://<hostname>/api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate&format=json
&input='{{ fn.get_phone_choices Cisco 8961,SIP,null,up }}'
query Parameters
hierarchy
required
string
Example: hierarchy=sys.hcs.CS-P.CS-NB

Hierarchy at which macro should be evaluated

method
required
string
Value: "evaluate"

The method=evaluate parameter is required for macros

input
required
string

The macro to be evaluated. Refer to Advanced Configuration Guide for macro syntax.

Responses

Response samples

Content type
application/json, text/plain
Example
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

ADD (standalone) Cisco Phone

This API call creates a standalone phone.

For details and how to obtain inputs, see: ADD (standalone) Phone

query Parameters
hierarchy
required
string

The site hierarchy

Request Body schema: application/json

Standalone phone data

standalone
boolean
name
string = 15 characters ^SEP[:xdigit:]{12}

The MAC address (specs above).

device_type
string

The phone model.

description
string <= 30 characters

The phone description.

Array of objects

Line details for each line added.

object

Contains callback details that will enable VOSS Automate can connect back and update the status when the initiated transaction is completed.

Responses

Request samples

Content type
application/json
{
  • "standalone": true,
  • "name": "SEP9971FFEEDDBB",
  • "device_type": "Cisco 9971",
  • "description": "Meeting Room 1 (x84000)",
  • "lines": [
    ],
  • "request_meta": {
    }
}

ADD Cisco Subscriber

This API call is used to create a new Subscriber.

For details and how to obtain inputs, see: ADD Subscriber

query Parameters
hierarchy
required
string

The site hierarchy

Request Body schema: application/json

Subscriber, devices and services details

lookUpForUser
boolean
username
string

The username. For local users, the operator enters the user details (username, firstname, lastname, and email) in the form. For Active Directory (AD) users, the user details (username, firstname, lastname, and email) are fetched from the system, and the form fields are read-only.

firstname
string

The user's first name. For local users, the operator enters the user details (username, firstname, lastname, and email) in the form. For Active Directory (AD) users, the user details (username, firstname, lastname, and email) are fetched from the system, and the form fields are read-only.

lastname
string

The user's last name. For local users, the operator enters the user details (username, firstname, lastname, and email) in the form. For Active Directory (AD) users, the user details (username, firstname, lastname, and email) are fetched from the system, and the form fields are read-only.

email
string

The user's email address. For local users, the operator enters the user details (username, firstname, lastname, and email) in the form. For Active Directory (AD) users, the user details (username, firstname, lastname, and email) are fetched from the system, and the form fields are read-only.

custom_string_1
string
password
string

The user's password. For local users, the operator enters the user password in the form. For Active Directory (AD) users, the user password is not relevant, and the password field is hidden on the form.

pin
string

Voicemail/extension mobility PIN.

Array of objects

One or more user lines. Multiple lines can be added to a phone, and are ordered 1,2, and so on, e.g. "directory_number":"line_1", "directory_number":"line_2", "directory_number":"line_n".

qagroup_name
string

The Quick Add Group name. Part of the desk phone details, which includes qagroup_name, phone_type, phone_protocol, phone_name.

voice
boolean
Default: false

Desk phone. Defines whether a desk phone is required. <deskphone_reqd_true_false>

phone_type
string

The phone model. Part of the desk phone details, which includes qagroup_name, phone_type, phone_protocol, phone_name. Displays when "voice" is True.

phone_protocol
string

The desk phone protocol. Part of the desk phone details, which includes qagroup_name, phone_type, phone_protocol, phone_name.

button_template
string

The desk phone button template name.

Array of objects

One or more phones. Includes the desk phone MAC address (phone_name) for each of the user's phones.

voicemail
boolean
Default: false

Voicemail service. Defines whether the voicemail service is required. <voicemail_reqd_true_false>

mobility
boolean
Default: false
Enum: true false

Extension mobility service. Defines whether the extension mobility service is required. <extnmobility_reqd_true_false>

jabber
boolean
Default: false

Jabber service. Allows allocation of soft phones. <jabber_reqd_true_false>

Array of objects

One or more Jabber devices. If <jabber>=True, the list of Jabber devices, specifying a value for <jabber_agent> and <device_name>.

Four types of jabber devices can be assigned

  • android
  • ipad
  • iphone
  • windows
custom_string_2
string
custom_string_3
string
object

Contains callback details that will enable VOSS Automate can connect back and update the status when the initiated transaction is completed.

Responses

Request samples

Content type
application/json
Example
{
  • "lookUpForUser": true,
  • "username": "syed.shahnawaz",
  • "firstname": "Syed",
  • "lastname": "Shahnawaz",
  • "email": "[email protected]",
  • "password": "C1&a2*B3$d4.",
  • "pin": "13579",
  • "lines": [
    ],
  • "qagroup_name": "99XX Reference Quick Add Group",
  • "voice": true,
  • "phone_type": "Cisco 9971",
  • "phone_protocol": "SIP",
  • "button_template": "Standard 9971 SIP",
  • "phones": [
    ],
  • "voicemail": true,
  • "mobility": true,
  • "jabber": true,
  • "jabber_devices": [
    ],
  • "request_meta": {
    }
}

Change CUCM PIN/Password and/or CUC PIN

This API call triggered is to reset the following:

  • CUCM (Cisco Unified Call Manager) PIN used for extension mobility
  • CUCM Password for Jabber ( if device is associated to a CUCM local user)
  • CUC ( Cisco Unified Unity - Voicemail) PIN

For details and how to obtain inputs, see: Change CUCM PIN/Password and/or CUC PIN

query Parameters
hierarchy
required
string

Site hierarchy

Request Body schema: application/json

User credentials, services applied

user
string

The username.

cucm
boolean
Default: false

Defines whether the password/PIN reset is for CUCM. Set to True to reset a CUCM PIN or password. <cucm_checkbox_boolean>

cuc
boolean
Default: false

Defines whether the password/PIN reset is for CUC. Set to True to reset a CUC PIN or password. <cuc_checkbox_boolean>

password
string

The Jabber password. When value for <cucm_checkbox_boolean> is True, set the Jabber password in <password_value>.

object

Contains callback details that will enable VOSS Automate can connect back and update the status when the initiated transaction is completed.

Responses

Request samples

Content type
application/json
Example
{
  • "user": "jo.bloggs",
  • "cucm": true,
  • "cuc": true,
  • "password": "A@e£%44e11223",
  • "pin": "82245698",
  • "request_meta": {
    }
}

Replace Cisco Phone

This API call is triggered to replace an existing Phone with a new one.

For details and how to obtain inputs, see: POST - Replace a Cisco phone

query Parameters
hierarchy
required
string

Site hierarchy

Request Body schema: application/json

Existing and new phone details

existing_phone
string = 15 characters ^SEP[:xdigit:]{12}

The MAC address (specs above).

replacement_phone
string = 15 characters ^SEP[:xdigit:]{12}

The MAC address (specs above).

replacement_model
string

Choose from existing phone models available.

protocol
string

The phone protocols that the replacement phone model supports.

pbt
string

The phone button template from those that are available in the system for the specified replacement phone model.

security_profile
string

The phone security profile for the replacement phone model.

replacement_description
string

A phone description for the new, replacement phone.

object

Contains callback details that will enable VOSS Automate can connect back and update the status when the initiated transaction is completed.

Responses

Request samples

Content type
application/json
{
  • "existing_phone": "SEP9951EEDDAABB",
  • "replacement_phone": "SEP8945EEAADDBB",
  • "replacement_model": "Cisco 8945",
  • "protocol": "SIP",
  • "pbt": "Standard 8945 SIP",
  • "security_profile": "Cisco 8945 - Standard SIP Non-Secure Profile",
  • "replacement_description": "Ismail x1084005",
  • "request_meta": {
    }
}

Associate existing Cisco Device / UDP to a Subscriber

This API call is to associate a standalone phone or standalone UDP to a Subscriber.

For details and how to obtain inputs, see: Associate existing Phone to existing Subscriber

query Parameters
hierarchy
required
string

Site hierarchy

Request Body schema: application/json

User and device details.

username
string

The username.

newDeviceName
string

The name of an unassociated device or unassociated device profile name

newDeviceType
string

Device type, either Cisco device (phone), or Cisco UDP (device profile).

object

Contains callback details that will enable VOSS Automate can connect back and update the status when the initiated transaction is completed.

Responses

Request samples

Content type
application/json
Example
{
  • "username": "jo.bloggs",
  • "newDeviceName": "SEP8945EEAADDBB",
  • "newDeviceType": "phone",
  • "request_meta": {
    }
}

Disassociate Cisco Phone associated to Subscriber

This API call is to remove a Subscriber-Phone association to make it a unassigned/standalone device.

For details and how to obtain inputs, see: Disassociate Phone associated to Subscriber

query Parameters
hierarchy
required
string

Site hierarchy

Request Body schema: application/json

User and device details

username
string

The username.

oldDeviceName
string

The name of the device you are removing.

object

Contains callback details that will enable VOSS Automate can connect back and update the status when the initiated transaction is completed.

Responses

Request samples

Content type
application/json
{
  • "username": "jo.bloggs",
  • "oldDeviceName": "SEP8945EEAADDBB",
  • "request_meta": {
    }
}

Move Cisco Subscriber between Sites

This API call is to move a Subscriber and its services/devices between Sites. One or more new Lines are created during the move process and the new line(s) are assigned to the devices / services.

For details and how to obtain inputs, see: Move Subscriber between Sites

query Parameters
hierarchy
required
string

Customer hierarchy

Request Body schema: application/json

Subscriber, sites and devices details

username
string

The username.

move_from_hn
string

The name of the site where you are moving the subscriber from.

move_to_hn
string

The name of the site where you are moving the subscriber to.

move_line
boolean
Default: false

Defines whether existing lines need to be moved to the new site.

AllowLineMove
boolean
Default: false

Whether to move lines.

new_line
boolean
Default: true

Defines whether to allocate new lines in the target site when moving the subscriber.

Array of objects

Line details. For each line you add, the directory number, the line label, and the line display name.

move_phone
boolean

Whether to move the phone.

new_phone
boolean

Whether to add a new phone.

new_phone_from_source
boolean

Whether to create a new phone from existing phone.

new_phone_config_source_product
string

The source phone type.

new_phone_config_source
string

New phone's configuration source.

phone_type
string

Phone type at target site.

name
string = 15 characters ^SEP[:xdigit:]{12}

The MAC address (specs above).

newCucUserTemplate
string

Default CUC template. This value is defined in the Site Defaults.

default_dp
boolean

Hardcoded to true.

default_css
boolean

The CSS. Hardcoded to true.

object

Contains callback details that will enable VOSS Automate can connect back and update the status when the initiated transaction is completed.

Responses

Request samples

Content type
application/json
Example
{
  • "username": "zaid.al-farhan",
  • "move_from_hn": "sys.hcs.CS-P.CS-NB.Innovia.INV-NewYork",
  • "move_to_hn": "sys.hcs.CS-P.CS-NB.Innovia.INV-JerseyCity",
  • "move_phone": true,
  • "move_line": false,
  • "new_line": true,
  • "lines": [
    ],
  • "default_css": true,
  • "newCucUserTemplate": "cu197-innovia-vms-2_usertemplate_1",
  • "request_meta": {
    }
}

Modify Line Data

This API call updates the following device line information:

  • Line description
  • Line alerting name
  • Line alerting ASCII name.

For details and how to obtain inputs, see: Modify Line Data

path Parameters
Line PKID
required
string

The PKID of the line to update.

query Parameters
hierarchy
required
string

Site hierarchy

Request Body schema: application/json
description
string <= 30 characters

Line description.

alertingName
string <= 30 characters

Line alerting name.

asciialertingname
string <= 30 characters

Line alerting ASCII name.

object

Contains callback details that will enable VOSS Automate can connect back and update the status when the initiated transaction is completed.

Responses

Request samples

Content type
application/json
{
  • "description": "FrontDesk x1084004",
  • "alertingName": "1084004",
  • "asciiAlertingName": "FrontDesk 1084004",
  • "request_meta": {
    }
}

Modify Phone Data - Line Recording Details

API call to modify the following Phone data: Phone Description, Line Label, Line Display Name, Line ASCII Display Name and Line Call Recording settings

For details and how to obtain inputs, see: Modify Phone Data - Line Recording Details

path Parameters
Phone PKID
required
string

The PKID of the phone to update.

query Parameters
hierarchy
required
string

Site hierarchy

Request Body schema: application/json
object (callback details)

Only one of these objects can be in the array. Contains callback details that will enable VOSS Automate can connect back and update the status when the initiated transaction is completed.

object (line data)

More than one of these objects can be in the array.

Responses

Request samples

Content type
application/json
Example
[
  • {
    },
  • {
    }
]

Delete a phone

Format: DELETE /api/relation/SubscriberPhone/<Removal_Phone_PKID>/?hierarchy=<Customer Hierarchy>&nowait=true&format=json

For details and how to obtain inputs, see Delete a phone

path Parameters
Removal_Phone_PKID
required
string

The phone PKID

query Parameters
hierarchy
required
string

Customer hierarchy

nowait
boolean

Set to true.

format
string

Set to json.

Responses

Response samples

Content type
application/json
{
  • "href": "/api/tool/Transaction/9095e5a2-6b62-45f8-abbb-93bd908a8bef/",
  • "transaction_id": "9095e5a2-6b62-45f8-abbb-93bd908a8bef",
  • "success": true
}

Delete a subscriber

This API call is used to delete a subscriber.

For details and how to obtain inputs, see: Delete a Subscriber

path Parameters
Deletion Subscriber PKID
required
string

PKID of the subscriber to delete.

query Parameters
hierarchy
required
string

Customer hierarchy

Responses

Response samples

Content type
application/json
{
  • "href": "/api/tool/Transaction/b471aa05-01d5-46c9-981e-685774b645be/",
  • "transaction_id": "b471aa05-01d5-46c9-981e-685774b645be",
  • "success": true
}