Plantronics + Polycom. Now together as Poly Logo

[FAQ] REST API

Highlighted
Polycom Employee & Community Manager

[FAQ] REST API

Since UC Software 5.8.0 the REST API is publicly available to everybody.

 

27/02/2018: Addedd Trio Rest API document

 

The attached manual applies to the following Polycom VVX models: 101, 150, 201, 250, 300, 301, 310, 311, 350, 400, 401, 410, 411, 450, 500, 501, 600, 601,1500, Trio 8800 and Trio 8500.

 

  • UC Software 6.1.0 REST API Document >here<
  • UC Software 6.0.0 REST API Document >here<
  • UC Software 5.9.0 REST API Document >here<

 

To enable simply logon to the Web Interface and browse to Settings > Applications > REST API

 

REST_API.png

 

This can also be enabled via configuration:

 

<test apps.restapi.enabled="1" />

IMPORTANT:

 

  • The password must be changed from 456 to anything else or the REST API will not work
  • The Username is Polycom

Power Shell Examples

 

RESET:

 

Attached is the PDF explaining all supported parameters and below is an example of how to Reset a Phone using Windows Power Shell

 

 

$username = "Polycom"
$password = "789" | ConvertTo-SecureString -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential($username,$password)

add-type @"
        using System.Net;
        using System.Security.Cryptography.X509Certificates;

            public class IDontCarePolicy : ICertificatePolicy {
            public IDontCarePolicy() {}
            public bool CheckValidationResult(
                ServicePoint sPoint, X509Certificate cert,
                WebRequest wRequest, int certProb) {
                return true;
            }
        }
"@
[System.Net.ServicePointManager]::CertificatePolicy = new-object IDontCarePolicy 
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls11


 Invoke-RestMethod -Uri "https://10.252.149.61/api/v1/mgmt/safeRestart" -Credential $cred  -Method Post -ContentType "application/json"  -TimeoutSec 2

 

 

 

The above will use the following hardcoded values:

  • Username: Polycom
  • Password: 789
  • Phone IP: 10.252.149.61

Dial a number:

 

The below example dials 123

 

 

$username = "Polycom"
$password = "789" | ConvertTo-SecureString -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential($username,$password)

add-type @"
        using System.Net;
        using System.Security.Cryptography.X509Certificates;

            public class IDontCarePolicy : ICertificatePolicy {
            public IDontCarePolicy() {}
            public bool CheckValidationResult(
                ServicePoint sPoint, X509Certificate cert,
                WebRequest wRequest, int certProb) {
                return true;
            }
        }
"@
[System.Net.ServicePointManager]::CertificatePolicy = new-object IDontCarePolicy 
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls11

 				$body = @"
{
`"data`":
{
`"Dest`": `"123`", 
`"Line`": `"1`",
`"Type`": `"SIP`"
}
}

"@
 Invoke-RestMethod -Uri "https://10.252.149.61/api/v1/callctrl/dial" -Credential $cred  -body $body -Method Post -ContentType "application/json"  -TimeoutSec 2
LineInfo:



The below prints the Line Info

$username = "Polycom"
$password = "789" | ConvertTo-SecureString -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential($username,$password)

add-type @"
        using System.Net;
        using System.Security.Cryptography.X509Certificates;

            public class IDontCarePolicy : ICertificatePolicy {
            public IDontCarePolicy() {}
            public bool CheckValidationResult(
                ServicePoint sPoint, X509Certificate cert,
                WebRequest wRequest, int certProb) {
                return true;
            }
        }
"@
[System.Net.ServicePointManager]::CertificatePolicy = new-object IDontCarePolicy 
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls11
 Invoke-RestMethod -Uri "https://10.252.149.61/api/v1/mgmt/lineInfo" -Credential $cred  -Method Get -ContentType "application/json"  -TimeoutSec 2

 

 

Simulate Touch

 

 

$step1=$args[0]
$username = "Polycom"
$password = "789" | ConvertTo-SecureString -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential($username,$password)

add-type @"
        using System.Net;
        using System.Security.Cryptography.X509Certificates;

            public class IDontCarePolicy : ICertificatePolicy {
            public IDontCarePolicy() {}
            public bool CheckValidationResult(
                ServicePoint sPoint, X509Certificate cert,
                WebRequest wRequest, int certProb) {
                return true;
            }
        }
"@
[System.Net.ServicePointManager]::CertificatePolicy = new-object IDontCarePolicy 
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls11

 				$body = @"
{`"data`": {`"Type`": `"Tap`", `"Positions`": [
{`"X`": `"70`",`"Y`": `"34`"}
]}}

"@
 Invoke-RestMethod -Uri "https://$step1/api/v1/mgmt/simulateTouch" -Credential $cred  -body $body -Method Post -ContentType "application/json"  -TimeoutSec 2

 

 

 

The above example add's the IP address to the PowerShell command aka:

 

  • .\REST_API_simulateTouch.ps1 10.252.149.62

It expects a hardcoded Password of:

 

  • 789

and hardcoded coordinates of the X and Y

 

  • 70 and 34

Which in this example is the Missed Call Icon on a VVX600

RestAPI_VoiceMail.png

 

Touch using a Swipe motion from left to right:

 

 

$step1=$args[0]
$username = "Polycom"
$password = "789" | ConvertTo-SecureString -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential($username,$password)

add-type @"
        using System.Net;
        using System.Security.Cryptography.X509Certificates;

            public class IDontCarePolicy : ICertificatePolicy {
            public IDontCarePolicy() {}
            public bool CheckValidationResult(
                ServicePoint sPoint, X509Certificate cert,
                WebRequest wRequest, int certProb) {
                return true;
            }
        }
"@
[System.Net.ServicePointManager]::CertificatePolicy = new-object IDontCarePolicy 
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls11

 				$body = @"
{
`"data`": {`"Type`": `"Swipe`", `"Positions`": [
{`"X`": `"68`",`"Y`": `"121`"}
,
{`"X`": `"320`",`"Y`": `"156`"}
],
`"Duration`": `"100`"
}
}

"@
 Invoke-RestMethod -Uri "https://$step1/api/v1/mgmt/simulateTouch" -Credential $cred  -body $body -Method Post -ContentType "application/json"  -TimeoutSec 2

 

 

 

The above original example is now using additional Swipe motion with new coordinates

 

REST_API_TOUCH_Swipe.png

The above example "swipes" the screen during an active call to the display showing the Line View

 

Setting Device Parameters:

 

 

 

$step1=$args[0]
$username = "Polycom"
$password = "789" | ConvertTo-SecureString -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential($username,$password)

add-type @"
        using System.Net;
        using System.Security.Cryptography.X509Certificates;

            public class IDontCarePolicy : ICertificatePolicy {
            public IDontCarePolicy() {}
            public bool CheckValidationResult(
                ServicePoint sPoint, X509Certificate cert,
                WebRequest wRequest, int certProb) {
                return true;
            }
        }
"@
[System.Net.ServicePointManager]::CertificatePolicy = new-object IDontCarePolicy 
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls11

 				$body = @"
{
`"data`":
{
`"device.set`": `"1`", 
`"device.prov.serverName.set`": `"1`",
`"device.prov.serverName`": `"10.252.149.102`"
}
}

"@
 Invoke-RestMethod -Uri "https://$step1/api/v1/mgmt/config/set" -Credential $cred  -body $body -Method Post -ContentType "application/json"  -TimeoutSec 8

 

 

 

The above example sets the Provisioning Server to 10.252.149.102

 

Curl Examples:

 

REST API command Format for GET:

 

 

 

curl -X GET -H "Content-Type: application/JSON" http://Polycom:789@10.221.72.163/api/v1/mgmt/transferType/get

 

 

 

HTTPS Example:

 

 

 

curl -k -X GET -H "Content-Type: application/JSON" https://Polycom:777@10.252.149.59/api/v1/mgmt/network/stats

 

 

 

the -k disables the certificate check

 

For POST Method to dial a number:

 

 

 

curl -d "{\"data\": {\"Dest\": 123,\"Line\": 1,\"Type\": \"SIP\"}}" -H "Content-Type: application/json" http://Polycom:789@10.221.72.163/api/v1/callctrl/dial

 

 

 

the -d is being used to send the actual data

 

Signing Into Skype for Business:

 

 

 

curl -k -d "{\"data\": {\"Address\": \"test.user@poly.com\",\"User\": \"test.user@poly.com\",\"Password\": \"MyPassword\", \"Domain\":\"\" ,\"LockCode\":\"\" }}" -H "Content-Type: application/json" https://Polycom:789@10.252.149.60/api/v1/mgmt/skype/signIn

 

 

 

-k is for HTTPS and -d is the data

 

In the above, we used Skype for Business online with the Username and Sign In address the same. We did not supply a Domain or a code to unlock the phone.

 

Sign Out of Skype

 

 

 

curl -X POST -H "Content-Type: application/json" -d "" -k https://Polycom:789@10.252.149.59/api/v1/mgmt/skype/signOut

 

 

 

In the below example, we change the Provisioning Server via Device Parameters

 

 

 

curl -k -d "{\"data\": {\"device.set\": \"1\",\"device.prov.serverName.set\": \"1\",\"device.prov.serverName\": \"10.252.149.102\" }}" -H "Content-Type: application/json" https://Polycom:789@10.252.149.62/api/v1/mgmt/config/set

 

 

 

Restart Example:

 

 

 

curl -X POST -H "Content-Type: application/json" -d "" http://Polycom:777@10.252.149.59/api/v1/mgmt/safeRestart

 

 

 

in this case, we use the -d as the device does not like an empty CURL request and would answer with a "411 Length Required" error

 

Get Call Details and Hangup Call:

 

In order to get the call reference via the REST API use the webCallControl/callStatus:

 

 

curl -k -X GET -H "Content-Type: application/JSON" https://Polycom:789@10.252.149.62/api/v1/webCallControl/callStatus

 

 

 

The above will return this:

 

 

{"data": {"CallHandle": "0x2341880", "LineId": "1", "Type": "Outgoing", "Protocol": "Sip", "CallState": "Connected", "RemotePartyName": "123", "DurationInSeconds": "2", "RemotePartyNumber": "123"}, "Status": "2000"}

 

 

 

The CallHandle Value without the 0x is the Call_Reference.

 

Disconnecting the call:

 

 

 

curl -d "{\"data\": {\"Ref\": 2341880}}" -H "Content-Type: application/JSON" -k https://Polycom:789@10.252.149.62/api/v1/callctrl/endCall

 

 

 

Ends the call:

 

 

{"Status": "2000"}

 

 

 

Using POSTMAN to send and Receive REST API info:

 

Sending a GET request

 

  1. Select GET as the request type
  2. Enter the full address and REST command into the command bar
    REST_API_GET_01.png
  3. Click the Authorization tab and enter the required username and password as “Basic Auth”
    REST_API_GET_02.png
  4. Optionally, add the command to a “collection” so that it is easily resent at a later time without re-writing the full command.
  5. Press the send button, the response will appear in the box below
  6. Select “JSON” as the display type
    REST_API_GET_03.png

 

Sending a POST request

  1. Select POST as the request type
  2. Enter the full address and REST command into the command bar
  3. Click the Authorization tab and enter the required username
    REST_API_POSt_01.png
  4. Click the “Body” tab and select the “Raw” radio button
  5. Choose “JSON” as the format if you would like syntax highlighting
  6. Enter the required parameters in JSON format
    REST_API_POSt_02.png
  7. Optionally, add the command to a “collection” so that it is easily resent at a later time without re-writing the full command.
  8. Press the send button, the response will appear in the box below
  9. Select “JSON” as the display type

 

Troubleshooting:

 

Set the Presentation and the overall logging to Debug:

 

  • Settings > Logging > Global Settings > Global Log Level Limit > Debug
  • Settings > Logging > Module Log Level Limits > Rest API > Debug

And check Diagnostics > View & Download Logs > UCS Application

 

0904183359|rest |0|00|At wappRestApiHandlerC::Handle. Received request is NOT for REST API handler. path=/Diagnostics/log
0904183359|rest |0|00|At wappRestApiHandlerC::Handle. Received request is NOT for REST API handler. path=/images/ajax-loader.gif
0904183405|rest |0|00|At wappRestApiHandlerC::Handle. Authentication failed, sending authDemand
0904183405|rest |0|00|At wappRestApiHandlerC::Handle. Moved REST API to request processing mode.
0904183405|rest |0|00|At wappRestApiHandlerC::Handle. Request's HTTP method POST
0904183405|rest |0|00|At wappRestApiHandlerC::Handle. JSON prepared as per input parameters - {
"data": {
"Type": "Tap", 
"Positions": [
{
"X": "70",
"Y": "34"
}
]
}
}

0904183405|rest |0|00|At wappRestApiHandlerC::Handle. Returning from Handle.
0904183407|rest |0|00|At wappRestApiHandlerC::Handle. Received request is NOT for REST API handler. path=/images/ajax-loader.gif

Finding the Coordinates of the Touch Screen:

 

Set the Presentation and the overall logging to Debug:

 

  • Settings > Logging > Global Settings > Global Log Level Limit > Debug
  • Settings > Logging > Module Log Level Limits > Presentation > Event 3

Touch the screen at the desired position:

 

 

 

0904183707|pgui |3|00|CLayoutMgr::onFilteredMouseEvent: mouse event detected at (x,y)=(438,254), state = 1, wheel = 0

 

 

 

In the above example, I touched the more Softkey on a VVX600

 

REST_API_Coordinates_Touch.png

----------------

Notice: This community forum is not an official Poly support resource, thus responses from Poly employees, partners, and customers alike are best-effort in attempts to share learned knowledge. If you need immediate and/or official assistance please open a service ticket through your proper support channels.
Please also ensure you always check the VoIP , Video Endpoint , Skype for Business , PSTN or RPM FAQ's