GXV33XX & WP820 - Web API User Guide

Overview

This document explains in detail the external HTTP-based application programming interface and parameters of functions via the supported method. The HTTP API is firmware dependent. Please refer to the related firmware Release Note for the supported functions.

The implemented web APIs abide by RESTful API style, supporting GET and POST HTTP request types that provide access and control over phone’s related data. Operations such as checking account status, adding/editing/deleting a contact number, making a phone call, and so on can be performed with correct API requests.

Web authentication and credentials might be required for certain API requests. To successfully perform API requests, please follow the formats and rules as shown in Web API Definitions.

Web Authentication Guide

This section discusses the available authorization methods that are used by Web API.

Web API Base URL

Request for Random Number

Endpoint

Usage

Get the random number from server for authentication.

Parameters

Query Parameter	Value
N/A

Response

Response	Value Type	Description
Random number	String	The random number requests from the server which would be used for only once.

Password Token Authentication

Endpoint

Usage

Use username and encrypted password to pass the authentication.

Parameters

The request must contain the following parameters in query string:

Query Parameter	Value
Username	The default username is “gmiadmin”.
Secret	Using MD5 algorithm to encrypt the string that is connected by username, random number, and password. The default passcode is “admin”. MD5(“gmiadmin” + “:” + ${random} + “:” + password)

Authentication Validate Prototype

The following figure shows an illustration of the authentication validation process:

Web API Definitions

This section provides the definition of the GXV32XX/33XX Web API.

Web API Base URL

Return Values Request

Endpoint

Usage

Get stored values on a device.

Authentication

None (limited return), Forms of authentication [admin|user]

Parameters

Query Parameter	Value
request	The request value names separated by “:”. Example: request=2:68:vendor_name

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":{     
         "68":"11.16.8.20",   
         "1561":"",   
         "7033":"1.0.1.7",   
         "vendor_name":"Grandstream",   
         "vendor_fullname":"Grandstream Networks, Inc.",   
         "hw_rev":"V2.2A",   
         "tp_fw_version":"22" 

       } 

   }

Response object

Key	Value Type	Description
response	String	The status of the response.
body	Object of the request values	Request values being bound to an object using key and value pair.

Post Values Request

Endpoint

Usage

Modify/update values on a device.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter	Value
PVALUE_NAME	Value of given PVALUE. NOTE: Name must start with “P”. Example: P2=admin

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":{     
         "status":"right"   
      }   
   } 

Response object

Key	Value Type	Description
response	String	The status of the response.
body	Object of the request values	Object contains the update status.

Change Password

Endpoint

Usage

Change admin or user password.

Authentication

Forms Authentication [admin|user]

Note:

Parameters

Body Parameter	Value
oldadmin	Current admin password.
P2	New admin password. Must include valid “oldadmin” password when intended to change admin password.
olduser	Current user password.
P196	New user password. Must include valid “olduser” password when intend to change user password.

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":{     
         "status":"right"   
      }   
   }  

Response object

Key	Value Type	Description
response	String	The status of the response.
body	Object of the request values	Object contains the update status.

Get Contact

Endpoint

Usage

Query the existing contacts.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter	Value
contactid	[OPTIONAL] Set contactid as an existing id will get the corresponding details for the contact.
contactname	[OPTIONAL] Use contactname as keyword to search if contact name in database contain the keyword, if yes, it will be returned.
groupid	[OPTIONAL] Return the contacts information in the corresponding group.

Note:

Examples of Request URI:

Response Format

   { 

      "res":"success", 

      "msg":[ 

   { 

      "contactID":"0", 

      "contactName":"xxx", 

      "groupID":"0", 

      "work":"8819", 

      "home":"",  

      "mobile":"", 

      "fax":"", 

      "email":"" 

   },  

   { 

      "contactID":"1", 

      "contactName":"grandstream", 

      "groupID":"0", 

      "work":"3587", 

      "home":"",  

      "mobile":"", 

      "fax":"", 

      "email":"" 

   } 

      ] 

   } 

Response object

Key	Value Type	Description
res	String	The status of the response.
msg	Array of contact object	Return of the contact objects.

Contact object

Key	Value Type	Description
contactID	Integer	Contact’s ID
contactName	String	Contact’s name
groupID	Integer	The group id for the contact
work	String	Work phone number
home	String	Home phone number
mobile	String	Mobile phone number
fax	String	Fax number
email	String	Email address

Save/Edit Contact

Endpoint

Usage

Save phone book contact.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter	Value
id	[OPTIONAL] Contact ID number. Leave id blank will insert a new contact record, and wen set as an exist id will edit the corresponding contact information.
firstname	Contact’s first name
lastname	Contact’s last name
group	[OPTIONAL] Contact’s group ID
newphone1	[OPTIONAL] Contact’s new phone number (Work)
newphone2	[OPTIONAL] Contact’s new phone number (Home)
newphone3	[OPTIONAL] Contact’s new phone number (Mobile)
newphone4	[OPTIONAL] Contact’s new phone number (Work Fax)
email	[OPTIONAL] Contact’s Email

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":""   
   }  

Response object

Key	Value Type	Description
response	String	The status of the response.
body	String	<Empty>

Delete All Contacts

Endpoint

Usage

Delete all phonebook contacts.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter	Value
N/A

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":""   
   }  

Response object

Key	Value Type	Description
response	String	The status of the response.
body	String	<Empty>

Delete Contact

Endpoint

Usage

Delete phone book contact.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter	Value
id	Contact ID number. The contact id can be obtained from Get Contact API.

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":""   
   }  

Response object

Key	Value Type	Description
response	String	The status of the response.
body	String	<Empty>

Add Contact Group

Endpoint

Usage

Add new contact group.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter	Value
name	Name of the new contact group.

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":""   
   }  

Response object

Key	Value Type	Description
response	String	The status of the response.
body	String	<Empty>

Get Contact Group

Endpoint

Usage

Query the existing groups.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter	Value
Id	[OPTIONAL]. Leaving id blank will get all records of groups. Setting it as an existing id will get the corresponding details for the group.

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   { 

      "res":"success", 

      "msg":[ 

   { 

      "groupID":"0",
      "groupName":"default" 


   },  

   {
      "groupID":"100",
      "groupName":"blacklist" 
   } 

      ] 

   } 

Response object

Key	Value Type	Description
res	String	The status of the response.
msg	Array of group object	Return of the group objects.

Group object

Key	Value Type	Description
goupID	Integer	The group ID.
body	String	The group Name.

Edit/delete Contact Group

Endpoint

Usage

Edit or delete existing contact group.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter	Value
id	Group ID, which can be obtained from get groups API.
name	New group name. Leaving the name blank will delete the group.

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {   

      "response":"success", 

      "body":"" 

   } 

Response object

Key	Value Type	Description
Response	String	The status of the response.
body	String	<Empty>

Get Account Status

Endpoint

Usage

Get device account status.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter	Value
registered	[OPTIONAL] Filter only to return the registered accounts. Can be set to “1” or “true” to enable.

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":[     
         {     
            "id":1,   
            "sip_server":"pbx.grandstream.com",   
            "sip_id":"699",   
            "name":"John Somebody",   
            "reg":1   
         },   
         {     
            "id":2,   
            "sip_server":"96.31.248.32",   
            "sip_id":"9064",   
            "name":"9064 (openser)",   
            "reg":1   
         },   
         {     
            "id":3,   
            "sip_server":"172.18.26.124",   
            "sip_id":"1025",   
            "name":"1025",   
            "reg":1   
         },   
         {     
            "id":4,   
            "sip_server":"as.iop1.broadworks.net",   
            "sip_id":"1016",   
            "name":"1016 (BS)",   
            "reg":0   
         }   
      ]   
   } 

Response object

Key	Value Type	Description
Response	String	The status of the response.
body	Array of account status object	Return of the account’s status objects.

Account Status object

Key	Value Type	Description
Id	Integer	Account ID.
sip_server	String	Account SIP server address.
sip_id	String	Account SIP user ID.
name	String	Account display name.
reg	Integer	Account register status.

Get Line Status

Endpoint

Usage

Get device line status.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter	Value
line	[OPTIONAL] Filter only to return the given line status. 0 to maximum available lines.

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":[     
         {     
            "line":1,   
            "state":"2",   
            "acct":"",   
            "name":"",   
            "number":"",   
            "active":0   
         },   
         {     
            "line":2,   
            "state":"3",   
            "acct":"",   
            "name":"",   
            "number":"",   
            "active":0   
         },   
         {     
            "line":3,   
            "state":"3",   
            "acct":"",   
            "name":"",   
            "number":"",   
            "active":0   
         },   
         {     
            "line":4,   
            "state":"8",   
            "acct":"",   
            "name":"",   
            "number":"",   
            "active":0   
         }   
      ]   
   } 

Response object

Key	Value Type	Description
response	String	The status of the response.
body	Array of line status object	Return of the line’s status objects.

Line Status object

Key	Value Type	Description
line	Integer	Line ID
state	String	Line Status 0 = idle 2 = ringing 3 = calling 4 = in call 5 = hold 8 = failed
acct	String	The account that is currently used on this line.
name	String	Remote party name
number	String	Remote party number
active	String	Whether the line is active or not.

Get Phone Status

Endpoint

Usage

Get phone/device session status.

Authentication

None | Forms Authentication [admin|user] | Password Token Authentication

Parameters

Query Parameter	Value
N/A

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":"available",   
      "misc":"0"   
   }

Response object

Get System Time

Endpoint

Usage

Get system time.

Authentication

Forms Authentication [admin|user]

Parameters

Query Parameter	Value
N/A

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "date":"Tue 08/30/2016",   
      "time":" 11:30AM",   
      "uptime":" 21 days, 1 hour, 50 minutes, 23seconds"   
   } 

Response object

Key	Value Type	Description
date	String	Current system date
time	String	Current system time
uptime	String	System uptime

Make Call

Endpoint

Usage

Dial an outgoing call.

Authentication

Forms Authentication [admin|user] | Password Token Authentication

Parameters

Query Parameter	Value
phonenumber	Dialed number
account	Account used for this call

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":""   
   }  

Response object

Key	Value Type	Description
response	String	The status of the response.
body	String	<Empty>

Phone/Call Operations

Endpoint

Usage

Perform a phone operation.

Authentication

Forms Authentication [admin|user] | Password Token Authentication

Parameters

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":"true"   
   }  

Response object

Key	Value Type	Description
response	String	The status of the response.
body	String	“true” when the command is handled successfully.

System Operations

Endpoint

Usage

Perform a system operation.

Authentication

Forms Authentication [admin|user] | Password Token Authentication

Parameters

Query Parameter	Value
request	Request Operation: REBOOT = reboot the device RESET = factory reset the device (required admin) PROV = provision the device (required admin)

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body in JSON format:

   {     
      "response":"success",   
      "body":"reset"   
   }  

Response object

Key	Value Type	Description
response	String	The status of the response.
body	String	Operation handle status.

Phonebook Download

Endpoint

Usage

Download the phonebook XML.

Authentication

Forms Authentication [admin|user]

Parameters

Query Parameter	Value
N/A

Example of Request URI:

Response Format

On SUCCESS, the HTTP status code in the response header is 200 OK and the response body is in Phonebook XML format (Please refer to GXP2200 XML Based Downloadable Phonebook Guide for detailed format description).