Add a standalone Cisco phone#

Overview#

This API POST call adds a standalone Cisco phone.

POST https://<hostname>/api/api/view/AddPhone

References:

Using POST AddPhone#

The API call involves the following tasks:

  1. Identify the customer and customer hierarchy, and the site and site hierarchy.

  2. Provide phone details:

    • Phone MAC address

    • Phone model

    • Phone description

  3. Provide line details:

    • Directory numbers

    • Line labels

    • Display names

Step 1: Identify Customer+Customer Hierarchy and Site+Site Hierarchy#

  1. Fetch the list of customers and populate a drop-down list. Allow the operator to select a customer from the list. <Customer Name>

    Refer to (GET) Customers for deployments with or without HCM-F.

  2. Fetch available site hierarchies for the selected customer (<Customer Name>). Allow the operator to select the site where the phone will be added.

    Refer to (GET) All Sites Belonging to the Customer

  3. Resolve <Customer Hierarchy> and <Site Hierarchy>.

    • <Customer Hierarchy> is the entry in the earlier step that ends with the <Customer Name>.

      For example, if <Customer Name> is Innovia, the <Customer Hierarchy> will be sys.hcs.CS-P.CS-NB.Innovia.

    • <Site Hierarchy> is the entry in the earlier step that the operator selects.

      For example, sys.hcs.CS-P.CS-NB.Innovia.INV-Reading, sys.hcs.CS-P.CS-NB.Innovia.INV-New York

Step 2: Provide phone details#

  1. Fill out a phone description <PhoneDescription> for the description field.

  2. Select a phone model:

    • Populate device_type with phone models currently available to the customer.

      Refer to (GET) Phone Models by passing <Customer Hierarchy>.

    • User chooses a phone model, and the choice is resolved into <PhoneModel>.

  3. Fill out the MAC address of the new phone in the name field.

    Note

    Note the input conditions for MAC address in the OpenAPI example for view/AddPhone

Step 2: Provide line details#

  1. List all available directory numbers (DN) to populate lines.

    Refer to (GET) Directory Numbers.

  2. User chooses a directory number (directory_number).

    Note

    Multiple lines can be added to one phone. Two or more lines can be ordered 1,2,… (<line_(n)>).

  3. For each directory number selected, user fills out:

    • A line label (label: <Label (n)>)

    • A display name (display: <Display Name (n)>)

    Note

    Note the input conditions in the OpenAPI example for view/AddPhone

Query parameters#

Parameter

Value

hierarchy

Site

Request Payload (Body)#

The box lists all parameters that could be included in the call request. These parameters are described in the table below the box:

{
   "standalone": true,
   "name": "<MACAddress>",
   "device_type": "<PhoneModel>",
   "description": "<PhoneDescription>",
   "lines": [
      {
         "directory_number": "<line_1>",
         "label": "<Label 1>",
         "display": "<Display Name 1>"
      }
   ],
   "request_meta": {
   "external_id": "<id>",
   "external_reference": "<Reference>",
   "callback_url": "<url_string>",
   "callback_username": "<callback_username>",
   "callback_password": "<callback_password>"
   }
}

The table describes the parameters in the request:

Parameter

Description

Type

Notes

name

The MAC address or phone name of the new phone.

string

The form field should check the following inputs:

  • Max value: 15 characters

  • The first 3 characters must be SEP

  • Following the first 3 characters, the next 12 characters must consist of hexadecimal characters.

device_type

The phone model.

string

A drop-down with available phone types. The operator selects a phone model.

description

The phone description.

string

Max value: 30 characters

lines

Line details for each line added.

array

Line is populated by listing all directory numbers (DNs) available, and then allowing the user to select a DN. Multiple lines can be added to a phone. Two or more lines can be ordered 1,2,… (<line (n)>)

  • <directory_number> (Line number)

  • <label> (Line Label)

    • User input text field

    • Value <Label (n)>

    • Max characters (for each line added): 30

  • <display> (Display Name)

    • User input text field

    • Value: <Display Name (n)>

    • Max characters (for each line added): 30

request_meta

Contains callback details.

object

These details enable VOSS Automate to update the status when the initiated transaction is complete.