GBNE Agent API

Table of Content

  1. Protocol Description
  2. Command Execution (HTTP Request)
  3. Command Output (XML Document)
  4. Commands
    1. Account Signup
    2. Trigger Callback
    3. Get Calling Plan List
    4. Get DID Group List
    5. Balance Update
    6. Get Call Records
    7. Get Call Rates
    8. Get/Set Account Status
    9. ANI Register
    10. View Account
    11. Voicemail
    12. Update Customer Information
    13. Recharge Calling Plan
    14. Change Calling Plan
    15. Assigns MAC Address
    16. View Transactions
    17. Remove Child DID
    18. Add Child DID
    19. View Call Forwarding Configuration
    20. Set Call Forwarding
    21. Second Line Signup
    22. VoIP Box Details
    23. Web Site Content
  5. Error Codes

Parameter table key:

* Required parameter
1 Available for VoIP agents only
2 Available for Callingcard agents only
3 Used by the internal "Transaction Control System". (Not available for all agents)
4 Sensitive information, communicated and stored as plain text. Provide at your own risk. (Agent API system will never postback the sensitive information)

 

Protocol Description

GBNE Agent API allows clients' applications to securely connect directly to the GBNE Application/Web Server and submit transaction data. All requests will be initiated by the client. The client submits the data as HTTP-Post. The Http Post must consist of a set of fields that are required for each transaction, and a set of fields that are optional. The server responds with an XML document of transaction data and result via same HTTP stream (Note: GBNE Agent API XML document is NOT SOAP compliant).
XML document has common structure for all transactions except for the output section where you will receive the command specific result (details on the XML document structure is on the "Command Output section").

To implement, a developer would design a script that does the following:

  1. Obtains all of the information needed to process a transaction.
  2. Initiates a HTTP Post from their server to http://agent.gbne.net/api/agentapi.php
  3. Receives the response (XML Document over HTTP) from the gateway and processes the response to display the appropriate result to the end user.

back
 

Command Execution (HTTP Request)

In order to execute GBNE Agent API commands (commands), you need to post a HTTP request with all the required parameters and other optional parameters to http://agent.gbne.net/api/agentapi.php
Following is a list of required parameters common to all commands.

Parameter Type Description
api_agent* string (16)

API username assigned to your agent account by GBNE.
api_agent_password* string (16) Correct password for the above username
api_command* integer Command ID you need to execute (Refer "Commands")

Sample HTTP request:

POST /api/agentapi.php HTTP/1.1
Host: agent.gbne.net
Content-Length: length

api_agent=your_username&api_agent_password=your_password&api_command=your_command_id&parameter1=value1&parameter2=value2...

Note: Above sample shows the minimum HTTP header information for your understanding, your actual request may/will include much other information depending on the browser or the programming language you use.

back
 

Command Output (XML Document)

For all the requests you make (via HTTP post) Agent API system response with a XML document via same HTTP stream. XML document win always confirm to the following structure.

<?xml version="1.0" encoding="utf-8" ?>
<gbne_agent_api>
  <response>
    <code>0</code>
    <message>Successful</message>
  </response>
  <request>
    <transaction_id>89982CD8-0F203738-B8C4BD55-3151920D</transaction_id>
    <transaction_datetime>2005-05-22 06:30:42 PM</transaction_datetime>
    <remote_ip>127.0.0.1</remote_ip>
    <remote_host>localhost</remote_host>
    <parameters>
      <api_agent>your_username</api_agent>
      <api_command>your_command_id</api_command>
      <parameter1>value1</parameter1>
      <parameter2>value2</parameter2>
      <!-- list of parameters and values you have posted -->
    </parameters>
  </request>
  <output>
    <!-- command specific output structure -->
  </output>
</gbne_agent_api>

As you can see in the above sample Agent API response is an XML document with the root node "gbne_agent_api". Root node contains 3 sub-nodes Response, Request and Output.

Response Section
This sub node of the XML document indicates the system's internal status of the command execution process.

Sub-node Type Description
code integer

API command status. This will be 0 (Zero) when command is successfully executed. And incase of the failure "code" will contain the corresponding error value (Refer "Error Codes")
message string Descriptive text corresponding to the code

Request Section
This section contains some statistics related to the HTTP request you have posted. Content of this section should always be submitted when reporting an issue related to the Agent API.

Sub-node Type Description
transaction_id string (35) A unique identifier assigned to each command execution process.
transaction_datetime datetime Date and time system received the HTTP request for the command execution. (in "YYYY-MM-DD HH:MM:SS AM/PM" format)
remote_ip string (15) IP address of the HTTP request origination.
remote_host string Host name of the remote system. This could be blank depending on the parameters of HTTP header.
parameters xml node Collection of all the parameters and their values your request has posted (except for the "api_agent_password" parameter and its value). You can use this data to verify your request.

Output Section
This is the final first-level sub node of the XML document. Content of this sub-node will differ from command to command. Refer each command's output for details

back
 

Commands


Command ID Name Details
101 Account Signup  
102 Trigger Callback Callback products only
103 Get Calling Plan List VoIP agents only
104 Get DID Group List VoIP agents only
105 Balance Update  
106 Get Call Records  
107 Get Call Rates  
108 Get/Set Account Status  
109 ANI Register Callingcard products only
110 View Account  
111 Voicemail VoIP agents only
112 Update Customer Information  
113 Recharge Calling Plan VoIP agents only
114 Change Calling Plan VoIP agents only
115 Assigns MAC Address VoIP agents only
116 View Transactions  
117 Remove Child DID VoIP agents only
118 Add Child DID VoIP agents only
119 View Call Forwarding Configuration VoIP agents only
120 Set Call Forwarding VoIP agents only
121 Second Line Signup VoIP agents only
122 VoIP Box Details VoIP agents only
123 Web Site Content  
back
 

 

Command - 101:Account Signup

This command enables you to configure and activate a customer account (Callingcard, Callback or VoIP). Account signup fetch a next available PIN from agent's "Retail Accounts" product and issue it to the customer by activating it, if you don't have unused PINs left in your retail product, this command will fail.

Account activation on signup depends on the agent account's configuration. If your agent account is set to "Signup Post Authorization" mode account will be created as an inactive/pending. Before customer use this account you need to authorize it from GBNE Agent MIS customer maintenance section. You can configure you agent account to send a notification to a URL on your website on customer account post authorization, this will cause the system to post PIN of the authorized customer account to your URL. In addition to the PIN, HTTP post will contain a parameter named "command" with value "POSTAUTHORIZE" in order to indicate that this is a post authorization notification.
If your agent account is set to online account authorization, customer accounts will be automatically activated at signup and be ready to use.

Account signup command takes in following parameters:

Parameter Type Description
account_balance* double Prepaid account balance used for web callback and toll free calls.
account_calling_plan1 integer

Must be a valid id of a calling plan belongs to retail product of the agent. Invalid calling plan id will cause an error and stop the command from proceeding.

You can get a list of available calling plans by executing the command 103.
account_did_code1 string (3)

3 digit (string) area code of the DID you want to assigned to this account.
When this parameter is empty a virtual phone number (1555xxxxxxx) will be assigned to your account.

If provided area code is invalid or there are no available phone numbers in that are, command will fail.

You can get a list of available DID groups (area codes) by executing the command 104.

voip_box_id1 integer

If not provided a VoIP box (phone adapter hardware) will not be issued for the account.

You can get a list of available VoIP boxes by executing the command 122.
registered_phone2 string (32)  
customer_first_name string (30)  
customer_last_name string (30)  
customer_phone string (20)  
customer_email string (50) Invoices will only be emailed to customer if email address is available
customer_password string (16) If not provided, system will generate a password for each customer profile
customer_ip3 string (15)  
customer_address_street1 string (30) Billing address of the customer.
customer_address_street2 string (30)  
customer_address_city string (30)  
customer_address_state string (20)  
customer_address_zipcode string (10)  
customer_address_country string (50)  
shipping_address_street1 string (30) Shipping address. This address will be used to ship VoIP hardware.
shipping_address_street2 string (30)  
shipping_address_city string (30)  
shipping_address_state string (20)  
shipping_address_zipcode string (10)  
shipping_address_country string (50)  
creditcard_number3,4 string (20) Customer credit cards are never charged by GBNE. Agent must do the credit card validation and charge the customer. This information is collected only for the reference of agents.
creditcard_expiration_month3 integer  
creditcard_expiration_year3 integer  
creditcard_security_code3 string (3)  
creditcard_holder string (50)  
back

System will respond with following data on the Output block of the XML document

On Successful Signup

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <new_account>
    <customer_number>001</customer_number>
    <account_number>0123456789</account_number>
    <serial_number>00100100000001</serial_number>
    <account_balance>10.00</account_balance>
    <calling_plan_balance>500.0000</calling_plan_balance>
    <account_status>1</account_status>
    <voip_did>15551234567</voip_did>
    <calling_plan>01</calling_plan>
    <mac_address>00-00-00-00-00-00</mac_address>
    <customer>
      <first_name></first_name>
      <last_name></last_name>
      <billing_address1></billing_address1>
      <billing_address2></billing_address2>
      <billing_city></billing_city>
      <billing_state></billing_state>
      <billing_zipcode></billing_zipcode>
      <billing_country></billing_country>
      <shipping_address1></shipping_address1>
      <shippingg_address2></shippingg_address2>
      <shipping_city></shipping_city>
      <shipping_state></shipping_state>
      <shipping_zipcode></shipping_zipcode>
      <shipping_country></shipping_country>
      <phone></phone>
      <email>customer@email.com</email>
      <box_id>1</box_id>
      <password>12345</password>
    </customer>
  </new_account>
</output>

On Failed Signup

<output>
  <api_return_code>1</api_return_code>
  <api_return_message>error description</api_return_message>
</output>

Account signup may fail due to following reasons

Error Code Description
1 Provided calling plan id is invalid. Calling plan must belong to the "Retail Accounts" product of the agent.
2 Provided DID area code is invalid or there are no available phone numbers in the group.
3 Agent doesn't have a "Retail Accounts" product
4 No available (unused) PINs in the agent's retail product.
5 Agent doesn't have enough credit for the transaction.
101 Customer credit card provided for the transaction is blacklisted by the "Transaction Control System"
102 Customer IP provided for the transaction is blacklisted by the "Transaction Control System"
103 Customer email address provided for the transaction is blacklisted by the "Transaction Control System"
201 Customer credit card provided for the transaction exceeds the limits allowed by "Transaction Control System"
202 Customer IP provided for the transaction exceeds the limits allowed by "Transaction Control System"
203 Customer email address provided for the transaction exceeds the limits allowed by "Transaction Control System"
back
 

 

Command - 102:Trigger Callback

This command enables you to trigger web callback.

Trigger callback command takes in following parameters:

Parameter Type Description
account_number* string Customer account number (PIN)
call_origination* string Caller (origination) phone number.
call_origination_extension string  
call_destination string Destination phone number
call_delay integer If a number is provided, system will delay the call in "call_delay" minutes.
back

System will respond with following data on the Output block of the XML document

On Successful Signup

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>error description</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <account_balance>9.00</account_balance>
  <calling_plan_balance>100.00</calling_plan_balance>
  <current_time>2005-05-23 07:55:23 PM</current_time>
  <call_time>2005-05-23 08:00:00 PM</call_time>
</output>

On Failed Signup

<output>
  <api_return_code>1</api_return_code>
  <api_return_message>error description</api_return_message>
</output>

Trigger callback may fail due to following reasons

Error Code Description
1 Customer account provided for the call is invalid
2 Customer account is inactive
3 Customer account doesn't have enough credit
4 Customer account has expired
5 Customer account already inuse (active call on same account)
6 Caller (Origination) phone number is invalid
7 Destination phone number is invalid
8 Technical failure
9 Delay parameter exceeds the allowed limit (1 to 10080 minutes)
back
 

 

Command - 103:Get Calling Plan List

This command returns all the calling plans and their related information of the agent's "Retail Accounts" product.

Get calling plan list command takes in following parameters:

Parameter Type Description
calling_plan_id integer If provided a valid calling plan id, only details of that plan will be returned.

System will respond with following data on the Output block of the XML document. If there are no calling plans, output sub-node will be empty.

<output>
  <calling_plans>
    <node_0>
      <calling_plan_id>1</calling_plan_id>
      <name>USA 100</name>
      <cost>100</cost>
      <allow_out_plan_calls>0</allow_out_plan_calls>
      <description></description>
      <destinations>
        <node_0>
          <destination_id>1</destination_id>
          <destination_name>USA</destination_name>
          <destination_prefix>1</destination_prefix>
          <allowed_minutes>100</allowed_minutes>
          <rate_per_minute>0.0100</rate_per_minute>
          <buy_rate>0.0010</buy_rate>
        </node_0>
        <!-- other calling plan destinations in node_1, node_2, ect.-->
      </destinations>
      <fees>
        <node_0>
          <fee_type_id>1</fee_type_id>
          <description>Setup Fee </description>
          <amount>0.95</amount>
        </node_0>
        <!-- other calling plan fees in node_1, node_2, ect.-->
      </fees>
    </node_0>
    <!-- other calling plans in node_1, node_2, ect.-->
  </calling_plans>
</output>

Get calling plan list doesn't have any error codes.

back
 

 

Command - 104:Get DID Group List

This command returns all the DID area codes and their related information.

Get DID group list command takes in following parameters:

Parameter Type Description
did_group_id integer If provided a valid DID group id, only details of that DID group will be returned.
did_group_code string Area code (NPA) of the DID group

System will respond with following data on the Output block of the XML document. If there are no DID groups, output sub-node will be empty.

<output>
  <did_groups>
    <node_0>
      <did_group_id>1</did_group_id>
      <area_code>202</area_code>
      <name>WASHINGTON D.C.</name>
    </node_0>
    <!-- other DID groups in node_1, node_2, ect.-->
  </did_groups>
</output>

Get DID group list doesn't have any error codes.

back
 

 

Command - 105:Balance Update

This command enables you to adjust or view balance (prepaid) of a single account.

Balance update command takes in following parameters:

Parameter Type Description
account_number* string  
adjustment_method* ENUM (string) Valid values are "VIEW", "EXACT", "CREDIT" and "DEBIT". See details of each value below.
adjustment_amount double If amount is not provided it's assumed as 0 (Zero)

Parameter "adjustment_method".
 

Value Description
VIEW No changes will be done to the account balance. Returns the balance details.
EXACT Account balance is set to the exact amount passed in "adjustment_amount" parameter.
CREDIT Amount passed in "adjustment_amount" parameter is credited to the customer account.
DEBIT Amount passed in "adjustment_amount" parameter is taken off from the customer account.

back

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>error description</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <previous_balance>10.00</previous_balance>
  <adjustment_amount>1.50</adjustment_amount>
  <account_balance>11.50</account_balance>
  <calling_plan_balance>100.00</calling_plan_balance>
</output>

Balance update doesn't have any error codes.

back
 

 

Command - 106:Get Call Records

Returns the call record of a customer account during a specified period.

Get call records command takes in following parameters:

Parameter Type Description
account_number* string  
date_from datetime If not provided, all the call records from account activation date up-to-date will be returned. Date/time should be in "YYYY-MM-DD HH:mm:SS" format.
date_to datetime If not provided, all the call records from account activation date up-to-date will be returned. Date/time should be in "YYYY-MM-DD HH:mm:SS" format.
record_page integer If not provided, all the records pages will be returned
record_page_size integer If not provided, all the records pages will be returned
sort_flag integer see below for the details

Parameter "sort_flag".
 

Value Description
1 Sort call records by call date/time. This is the default value for this parameter .
3 Sort by cost of the call.
back

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>error description</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <account_balance>10.00</account_balance>
  <calling_plan_balance>100.00</calling_plan_balance>
  <record_page>1</record_page>
  <record_page_count>10</record_page_count>
  <call_records>
    <node_0>
      <call_date_time>2005-05-23 22:47:22</call_date_time>
      <origination>15551234567</origination>
      <destination>15551234568</destination>
      <minutes>10</minutes>
      <cost>0.15</cost>
      <in_plan>1</in_plan>
      <call_type>CB</call_type>
    </node_0>
    <!-- more call records in node_1, node_2, ect.-->
  </call_records>
</output>

Parameter "call_type".
 

Value Description
CB Callback
TF Toll-free
S2P VoIP to regular phone
P2S Regular phone to VoIP
S2S VoIP to VoIP
P2F Forwarded to regular phone
S2F Forwarded to VoIP
VM Voice mail access

Get call records may fail due to following reasons

Error Code Description
1 Customer account provided is invalid
back
 

 

Command - 107:Get Call Rates

Returns the call rates of an agent product based on access number or calling plan.

Get call rates command takes in following parameters:

Parameter Type Description
access_number* string Respective Toll-free number for callingcard rates, "VOIP" for VoIP rates or "CALLBACK" for callback rates.
calling_plan_id integer Required if "access_number" is "VOIP".*
destination_letter string (1) If provided only the rates of destination names starting with "destination_letter" will be returned.

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>error description</api_return_message>
  <product_id>100</product_id>
  <product_name>product name</product_name>
  <rates>
    <node_0>
      <prefix>1</prefix>
      <destination>US Domestic</destination>
      <rate>0.0500</rate>
    </node_0>
    <!-- other rates in node_1, node_2, ect.-->
  </rates>
</output>

Get call rates may fail due to following reasons

Error Code Description
1 Failed to determine agent product/rate for the provided access number or calling plan.
back
 

 

Command - 108:Get/Set Account Status

Returns or adjust the status of a customer account.

Get/Set account status command takes in following parameters:

Parameter Type Description
account_number* string  
account_status integer Valid values are 1 (One) or 0 (Zero).

If not provided command only returns the account status.

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>error description</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <previous_status>1</previous_status>
  <adjustment_status></adjustment_status>
  <account_status>1</account_status>
</output>

Get/Set account status may fail due to following reasons

Error Code Description
1 Customer account provided is invalid
back
 

 

Command - 109:ANI Register

Register a phone number with a callingcard account for automatic account recognition.

ANI register command takes in following parameters:

Parameter Type Description
account_number* string  
new_ani_list CSL Comma seperated list of ANIs (phone numbers) to be registered with the account.
delete_ani_list CSL Comma seperated list of ANIs (phone numbers) to be unregistered with the account.

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>error description</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <previous_ani_list>
    <node_1>15551234567</node_1>
    <!-- other ANIs in node_1, node_2, ect.-->
  </previous_ani_list>
  <deleted_ani_list>15551234567, 15551234568</deleted_ani_list>
  <added_ani_list>15551234569</added_ani_list>
  <ani_list>
    <node_1>15551234569</node_1>
    <!-- other ANIs in node_1, node_2, ect.-->
  </ani_list>
</output>

ANI register may fail due to following reasons

Error Code Description
1 Customer account provided is invalid
back
 

 

Command - 110:View Account

Registers the customer and account details by account number (PIN), VoIP phone number (DID) or serial number.

View account command takes in following parameters:

Parameter Type Description
search_using* ENUM (string) see detail below
search_for* string value to search for

Parameter "search_using".
 

Value Description
PIN Search by account number
DID Search by VoIP phone number
SERIAL Search by account serial number

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <serial_number>00100100000001</serial_number>
  <account_number>0123456789</account_number>
  <voip_did>15551234567</voip_did>
  <account_status>1</account_status>
  <line_status>ACTIVE</line_status>
  <account_balance>10.00</account_balance>
  <plan_balance>500.0000</plan_balance>
  <plan_id>01</plan_id>
  <plan_name>calling plan name</plan_name>
  <mac_address>00-00-00-00-00-00</mac_address>
  <first_used_date></first_used_date>
  <next_bill_date>2005-06-01 00:00:00</next_bill_date>
  <customer>
    <first_name></first_name>
    <last_name></last_name>
    <billing_address1></billing_address1>
    <billing_address2></billing_address2>
    <billing_city></billing_city>
    <billing_state></billing_state>
    <billing_zipcode></billing_zipcode>
    <billing_country></billing_country>
    <shipping_address1></shipping_address1>
    <shippingg_address2></shippingg_address2>
    <shipping_city></shipping_city>
    <shipping_state></shipping_state>
    <shipping_zipcode></shipping_zipcode>
    <shipping_country></shipping_country>
    <phone></phone>
    <email>customer@email.com</email>
    <box_id>1</box_id>
    <password>12345</password>
  </customer>
  <child_did>
    <child_did_1>15551234560</child_did_1>
    <!-- other additional DIDs in child_did_1, child_did_2, ect.-->
  </child_did>
  <phone_lines>
    <node_0>
      <serial_number>00100100000002</serial_number>
      <account_number>9876543210</account_number>
      <voip_did>15551234566</voip_did>
      <account_status>1</account_status>
      <account_balance>5.00</account_balance>
      <plan_balance>100.00</plan_balance>
      <plan_id>2</plan_id>
    </node_0>
    <!-- other phone lines in node_1, node_2, ect.-->
  </phone_lines>
</output>

View account may fail due to following reasons

Error Code Description
1 Account not found
back
 

 

Command - 111:Voicemail

This command performs several sub functions based on the "sub_command" parameter. All functions are related to VoIP account's voice mail access feature.

Voicemail command takes in following parameters:

Parameter Type Description
voip_did* string  
sub_command ENUM (string) See detail below. Default (no "sub_command" will return the VM folder content.
vm_name string  
vm_email string  
vm_password string  
vm_folder string  

Parameter "sub_command".
 

Value Description
ADD_EXTENSION Enable voicemail box for the account
DELETE_EXTENSION Disable voicemail box for the account
MSG_REMOVE Delete voicemail message
MSG_PLAY Play voicemail message
back

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <voip_did>15551234567</voip_did>
  <account_balance>10.00</account_balance>
  <calling_plan_balance>500.0000</calling_plan_balance>
  <voice_mail_name>Voicemail Box 15551234567</voice_mail_name>
  <voice_mail_email></voice_mail_email>
  <voice_mail_password>1234</voice_mail_password>
  <voice_mail>
    <inbox>
      <name>INBOX</name>
      <message_count>2</message_count>
      <messages>
        <msg0001>
          <datetime>2005-05-24 01:39:43 AM</datetime>
          <from></from>
          <size>24</size>
          <priority>1</priority>
        </msg0001>
        <!-- other voicemail messages in msg0002, msg0003, ect.-->
      </messages>
    </inbox>
    <!-- other voicemail folders -->
  </voice_mail>
</output>

or (if "MSG_PLAY")

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <voip_did>15551234567</voip_did>
  <account_balance>10.00</account_balance>
  <calling_plan_balance>500.0000</calling_plan_balance>
  <voice_mail_name>Voicemail Box 15551234567</voice_mail_name>
  <voice_mail_email></voice_mail_email>
  <voice_mail_password>1234</voice_mail_password>
  <voice_mail>
    <message_path></message_path>
  </voice_mail>
</output>

Voicemail may fail due to following reasons

Error Code Description
1 VoIP phone number (DID) provided is invalid
2 Failed to play message
3 Failed to delete message
back
 

 

Command - 112:Update Customer Information

Update customer profile details. Only provided details will be updated in the customer profile, if not provided those values will remain unchanged.

Update customer information command takes in following parameters:

Parameter Type Description
account_number* string  
account_calling_plan integer  
customer_first_name string (30)  
customer_last_name string (30)  
customer_phone string (20)  
customer_email string (50)  
customer_password string (16)  
customer_address_street1 string (30)  
customer_address_street2 string (30)  
customer_address_city string (30)  
customer_address_state string (20)  
customer_address_zipcode string (10)  
customer_address_country string (50)  
shipping_address_street1 string (30)  
shipping_address_street2 string (30)  
shipping_address_city string (30)  
shipping_address_state string (20)  
shipping_address_zipcode string (10)  
shipping_address_country string (50)  
back

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <serial_number>00100100000001</serial_number>
  <account_number>0123456789</account_number>
  <voip_did>15551234567</voip_did>
  <account_status>1</account_status>
  <account_balance>10.00</account_balance>
  <plan_balance>500.0000</plan_balance>
  <plan_id>01</plan_id>
  <first_used_date></first_used_date>
  <customer>
    <first_name></first_name>
    <last_name></last_name>
    <billing_address1></billing_address1>
    <billing_address2></billing_address2>
    <billing_city></billing_city>
    <billing_state></billing_state>
    <billing_zipcode></billing_zipcode>
    <billing_country></billing_country>
    <shipping_address1></shipping_address1>
    <shippingg_address2></shippingg_address2>
    <shipping_city></shipping_city>
    <shipping_state></shipping_state>
    <shipping_zipcode></shipping_zipcode>
    <shipping_country></shipping_country>
    <phone></phone>
    <email>customer@email.com</email>
    <password>12345</password>
  </customer>
</output>

Update customer information may fail due to following reasons

Error Code Description
1 Provided calling plan id is invalid. Calling plan must belong to the "Retail Accounts" product of the agent.
2 Customer account is invalid
back
 

 

Command - 113:Recharge Calling Plan

Manually pay the calling plan monthly amount.

Recharge calling plan command takes in following parameters:

Parameter Type Description
account_number* string  
recharge_amount double Amount to add to prepaid account balance

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <voip_did>15551234567</voip_did>
  <account_balance>10.00</account_balance>
  <calling_plan_balance>500.0000</calling_plan_balance>
  <next_bill_date>2005-06-01 00:00:00</next_bill_date>
</output>

Recharge calling plan may fail due to following reasons

Error Code Description
1 Customer account is invalid
2 Calling plan id is invalid
3 Agent doesn't have enough credit for the transaction.
back
 

 

Command - 114:Change Calling Plan

Move customer account to a different calling plan.

Change calling plan command takes in following parameters:

Parameter Type Description
account_number* string  
new_plan* integer  

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <voip_did>15551234567</voip_did>
  <account_balance>10.00</account_balance>
  <calling_plan_balance>500.0000</calling_plan_balance>
  <calling_plan_name></calling_plan_name>
  <old_plan_id>1</old_plan_id>
  <new_plan_id>2</new_plan_id>
</output>

Change calling plan may fail due to following reasons

Error Code Description
1 Customer account is invalid
2 Calling plan id is invalid
back
 

 

Command - 115:Assigns MAC Address

Assign a MAC address (VoIP hardware) to newly signup account.

Assign MAC address command takes in following parameters:

Parameter Type Description
account_number* string  
new_plan* integer  

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <voip_did>15551234567</voip_did>
  <box_id>1</box_id>
  <mac_address>00-00-00-00-00-00</mac_address>
</output>

Assign MAC address may fail due to following reasons

Error Code Description
1 Customer account is invalid
2 Assignment failed (mostly due to boxes not available)
back
 

 

Command - 116:View Transactions

Returns transactions of the customer during a specified period.

View transactions command takes in following parameters:

Parameter Type Description
account_number* string  
date_from datetime If not provided, all the transaction records from account activation date up-to-date will be returned. Date/time should be in "YYYY-MM-DD HH:mm:SS" format.
date_to datetime If not provided, all the transaction records from account activation date up-to-date will be returned. Date/time should be in "YYYY-MM-DD HH:mm:SS" format.
record_page integer If not provided, all the records pages will be returned
record_page_size integer If not provided, all the records pages will be returned

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <serial_number>00100100000001</serial_number>
  <account_number>0123456789</account_number>
  <voip_did>15551234567</voip_did>
  <record_page>1</record_page>
  <record_page_count>10</record_page_count>
  <transactions>
    <node_0>
    <transaction_date>2005-05-24 02:26:45</transaction_date>
    <transaction_type>SIGNUP</transaction_type>
    <amount>100.00</amount>
    </node_0>
    <!-- more transaction records in node_1, node_2, ect.-->
  </transactions>
</output>

Parameter "transaction_type".
 

Value Description
AUTO_PAY Automatic payment
PLAN Calling plan manual payment
BALUP Balance update
RECHG Prepaid balance recharge
SIGNUP Account signup
EX_DID Additional DID purchase
BOX VoIP hardware purchase

View transactions may fail due to following reasons

Error Code Description
1 Customer account is invalid
2 No transactions found
back
 

 

Command - 117:Remove Child DID

Remove additional VoIP phone number (DID).

Remove child DID command takes in following parameters:

Parameter Type Description
account_number* string  
chid_did* string  

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <voip_did>15551234567</voip_did>
  <account_balance>10.00</account_balance>
  <calling_plan_balance>500.0000</calling_plan_balance>
</output>

Remove child DID plan may fail due to following reasons

Error Code Description
1 Customer account is invalid
2 Technical failure
back
 

 

Command - 118:Add Child DID

Add additional VoIP phone number (DID).

Add child DID command takes in following parameters:

Parameter Type Description
account_number* string  
did_group_id* integer  

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <voip_did>15551234567</voip_did>
  <account_balance>10.00</account_balance>
  <calling_plan_balance>500.0000</calling_plan_balance>
</output>

Add child DID plan may fail due to following reasons

Error Code Description
1 Customer account is invalid
2 Technical failure
back
 

 

Command - 119:View Call Forwarding Configuration

View VoIP call forwarding configuration.

View call forwarding configuration command takes in following parameters:

Parameter Type Description
account_number* string  

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <serial_number>00100100000001</serial_number>
  <account_number>0123456789</account_number>
  <voip_did>15551234567</voip_did>
  <account_balance>10.00</account_balance>
  <plan_balance>500.0000</plan_balance>
  <forward_to></forward_to>
</output>

View call forwarding configuration may fail due to following reasons

Error Code Description
1 Customer account is invalid
2 Technical failure
back
 

 

Command - 120:Set Call Forwarding

Enable/disable VoIP call forwarding feature.

Set call forwarding command takes in following parameters:

Parameter Type Description
account_number* string  
forward_number string  

System will respond with following data on the Output block of the XML document.

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <serial_number>00100100000001</serial_number>
  <account_number>0123456789</account_number>
  <voip_did>15551234567</voip_did>
  <account_balance>10.00</account_balance>
  <plan_balance>500.0000</plan_balance>
  <forward_to></forward_to>
</output>

Set call forwarding may fail due to following reasons

Error Code Description
1 Customer account is invalid
2 Technical failure
back
 

 

Command - 121:Second Line Signup

This command enables you to add a second phone line (account) to an existing customer profile.

Second line signup command takes in following parameters:

Parameter Type Description
account_number* string  
account_balance* double Prepaid account balance used for web callback and toll free calls.
account_calling_plan1 integer

Must be a valid id of a calling plan belongs to retail product of the agent. Invalid calling plan id will cause an error and stop the command from proceeding.

You can get a list of available calling plans by executing the command 103.
account_did_code1 string (3)

3 digit (string) area code of the DID you want to assigned to this account.
When this parameter is empty a virtual phone number (1555xxxxxxx) will be assigned to your account.

If provided area code is invalid or there are no available phone numbers in that are, command will fail.

You can get a list of available DID groups (area codes) by executing the command 104.

registered_phone2 string (32)  
customer_ip3 string (15)  
creditcard_number3,4 string (20) Customer credit cards are never charged by GBNE. Agent must do the credit card validation and charge the customer. This information is collected only for the reference of agents.
creditcard_expiration_month3 integer  
creditcard_expiration_year3 integer  
creditcard_security_code3 string (3)  
creditcard_holder string (50)  
back

System will respond with following data on the Output block of the XML document

<output>
  <api_return_code>0</api_return_code>
  <api_return_message>Signup successful</api_return_message>
  <customer_number>1</customer_number>
  <account_number>0123456789</account_number>
  <serial_number>00100100000001</serial_number>
  <account_balance>10.00</account_balance>
  <calling_plan_balance>500.0000</calling_plan_balance>
  <account_status>1</account_status>
  <voip_did>15551234567</voip_did>
  <calling_plan>1</calling_plan>
  <mac_address>00-00-00-00-00-00</mac_address>
  <customer>
    <first_name></first_name>
    <last_name></last_name>
    <billing_address1></billing_address1>
    <billing_address2></billing_address2>
    <billing_city></billing_city>
    <billing_state></billing_state>
    <billing_zipcode></billing_zipcode>
    <billing_country></billing_country>
    <shipping_address1></shipping_address1>
    <shippingg_address2></shippingg_address2>
    <shipping_city></shipping_city>
    <shipping_state></shipping_state>
    <shipping_zipcode></shipping_zipcode>
    <shipping_country></shipping_country>
    <phone></phone>
    <email>customer@email.com</email>
    <box_id>1</box_id>
    <password>12345</password>
  </customer>
</output>

Second line signup may fail due to following reasons

Error Code Description
1 Provided calling plan id is invalid. Calling plan must belong to the "Retail Accounts" product of the agent.
2 Provided DID area code is invalid or there are no available phone numbers in the group.
3 Agent doesn't have a "Retail Accounts" product
4 No available (unused) PINs in the agent's retail product.
5 Agent doesn't have enough credit for the transaction.
6 Customer account is invalid.
101 Customer credit card provided for the transaction is blacklisted by the "Transaction Control System"
102 Customer IP provided for the transaction is blacklisted by the "Transaction Control System"
103 Customer email address provided for the transaction is blacklisted by the "Transaction Control System"
201 Customer credit card provided for the transaction exceeds the limits allowed by "Transaction Control System"
202 Customer IP provided for the transaction exceeds the limits allowed by "Transaction Control System"
203 Customer email address provided for the transaction exceeds the limits allowed by "Transaction Control System"
back
 

 

Command - 122:VoIP Box Details

Get the list of available VoIP hardware.

VoIP box details command takes in following parameters:

Parameter Type Description
voip_box_id integer If provided a valid box id, only details of that VoIP box will be returned.

System will respond with following data on the Output block of the XML document. If there are no VoIP boxes, output sub-node will be empty.

<output>
  <voip_boxes>
    <node_0>
      <voip_box_id>1</voip_box_id>
      <name>PAP2</name>
      <price>100.00</price>
      <description>box details</description>
      <detail_url></detail_url>
    </node_0>
    <!-- other VoIP boxs in node_1, node_2, ect.-->
  </voip_boxes>
</output>

VoIP box details doesn't have any error codes.

back
 

 

Command - 123:Web Site Content

Get the content defined in the Agent MIS.

Web site content command takes in following parameters:

Parameter Type Description
content_key string If provided a valid key, only content of that key will be returned.

System will respond with following data on the Output block of the XML document. If there are no key/data, output sub-node will be empty.

<output>
  <contents>
    <key1>
      <node_0>value</node_0>
      <!-- other values in node_1, node_2, ect.-->
    </key1>
    <key2>value</key2>
    <!-- other keys -->
  </contents>
</output>

or (if key provided)

<output>
  <key1>
    <node_0>value</node_0>
    <!-- other values in node_1, node_2, ect.-->
  </key1>
</output>

VoIP box details doesn't have any error codes.

back
 

Error Codes

Error Code Description
2 Invalid "api_command" value.
3 Technical failure
4 Agent username/password invalid
5 Agent does not have access to Agent API or command
6 Required parameter is missing
7 Invalid value (by type) passed to a parameter
8 Command specific failure. More details on the "output" section.
back