GXV33XX & WP820 - Web API User Guide

  • Updated on June 14, 2022

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

[http/https]://{ipaddress}/cgi-bin/

Request for Random Number

Endpoint

GET loginrealm

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

GET login

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:

A picture containing diagram

Description automatically generated
Figure 1: Authentication validation process

Web API Definitions

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

Web API Base URL:

[http/https]://{ipaddress}/cgi-bin/

Return Values Request

Endpoint

GET api-values.get

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:

http://172.16.2.127/cgi-bin/api-values.get?request=2:68:vendor_name

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

GET api-values.post

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:

http://172.16.2.127/cgi-bin/api-values.post?P2=admin&P196=123

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

GET api-change_password

Usage

Change admin or user password.

Authentication

Forms Authentication [admin|user]

Note:

User account is only allowed to change his/her own password.

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:

http://172.16.2.127/cgi-bin/api-change_password?oldadmin=admin&P2=newadmin&olduser=123&P196=123456

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

GET api-get_contacts

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:

Leaving contactid, contactname and groupid blank will return all data for contacts.

Examples of Request URI:

http://172.16.2.127/cgi-bin/api-get_contacts?contactid=1

http://172.16.2.127/cgi-bin/api-get_contacts?contactname=abc

http://172.16.2.127/cgi-bin/api-get_contacts?groupid=2

http://172.16.2.127/cgi-bin/api-get_contacts

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

GET api-save_edit_contact

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:

http://172.16.2.127/cgi-bin/api-save_edit_contact?firstname=Jack&lastname=Brown&newphone1=123456

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

GET api-delete_all_contact

Usage

Delete all phonebook contacts.

Authentication

Forms Authentication [admin|user]

Parameters

Body Parameter

Value

N/A

Example of Request URI:

http://172.16.2.127/cgi-bin/api-delete_all_contact

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

GET api-delete_contact

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:

http://172.16.2.127/cgi-bin/api-delete_contact?id=1

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

GET api-add_group

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:

http://172.16.2.127/cgi-bin/api-add_group?name=newGroup

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

Get api-get_groups

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:

http://172.16.2.127/cgi-bin/api-get_groups

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

GET api-edit_delete_group

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:

http://172.16.2.127/cgi-bin/api-edit_delete_group?id=1&name=

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

GET api-get_accounts

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:

http://172.16.2.127/cgi-bin/api-get_accounts?registered=true

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

GET api-get_line_status

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:

http://172.16.2.127/cgi-bin/api-get_line_status?line=0

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

GET api-get_phone_status

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:

http://172.16.2.127/cgi-bin/api-get_phone_status

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

Key

Value Type

Description

Response

String

The status of the response.

body

String

Status of the device:

unauthorized = the session is expired or the given credential is invalid.


available = the device is registered and idle.


ringing = the device has at least one line is currently ringing.


busy = the device is currently in busy state.

misc

Misc.information.

1 = Click to dial is currently enabled.

Get System Time

Endpoint

GET api-get_time

Usage

Get system time.

Authentication

Forms Authentication [admin|user]

Parameters

Query Parameter

Value

N/A

Example of Request URI:

http://172.16.2.127/cgi-bin/api-get_time

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

GET api-make_call

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:

http://172.16.2.127/cgi-bin/api-make_call?phonenumber=123456&account=0

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:

GET api-phone_operation

Usage

Perform a phone operation.

Authentication

Forms Authentication [admin|user] | Password Token Authentication

Parameters:

Query Parameter

Value

cmd

Operation command:

endcall = End the call on the given line (needs arg).

holdcall = Hold the call on the given line (needs arg).

acceptcall = Accept the call on the given line (needs arg).

rejectcall = Reject the call on the given line (needs arg).

Line

Line ID.

Example of Request URI:

http://172.16.2.127/cgi-bin/api-phone_operation?cmd=endcall&line=0

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

GET api-sys_operation

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:

http://172.16.2.127/cgi-bin/api-sys_operation?request=REBOOT

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

GET phonebook_download

Usage

Download the phonebook XML.

Authentication

Forms Authentication [admin|user]

Parameters

Query Parameter

Value

N/A

Example of Request URI:

http://172.16.2.127/cgi-bin/phonebook_download

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).

Was this article helpful?

Related Articles

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support

Leave a Comment

We use cookies in order to give you the best possible experience on our website. By continuing to use this site, you agree to our use of cookies.
Accept