Guide to ISPsystem software API

API (Application Programming Interface) is an interface that allows programs to interact with each other. The BILLmanager API allows you to manage the platform programmatically by calling its functions via HTTP requests. Using the API, you can retrieve data, perform actions on behalf of users, integrate with external systems, and automate billing platform tasks.

The article describes request and response formats, authorization methods, and ways to call functions. It also provides examples of interacting with the platform via the API using various tools and programming languages.

Authorization management

Authorization is required before calling platform functions.

You can authorize using one of the methods:

• session authorization;
• authorization using the authinfo function;
• pass-through authorization by key.

Session authorization

Use the method:

• for scripts that perform multiple requests to the platform;
• for accessing the platform through a browser.

1. Send a GET request:
   
   Common request type:

   https://IP address:1500/billmgr?out=xml&func=auth&username=username&password=passwd

   Details

   • IP address:1500 —  IP address and port of the server with the platform
   • out=xml — response format
   • func=auth — authorization function
   • username=username — username in BILLmanager
   • password=passwd — user password
2. Get an XML response:
   General view of answer:

   <doc>
       <auth id="session number" level="access level">session number</auth>
   ...
   </doc>

3. Use the received identifier in subsequent requests:
   
   Common request type:

   https://IP address:1500/billmgr?auth=session_number&out=xml&func=function&parameter1=value&parameter2=value...

The session is valid for one hour from the last request. If no requests were made within an hour, the authorization becomes invalid — please perform authorization again.

Authorization using the authinfo function

Use the method:

• for one-time requests to the platform;
• for remote access to the platform without the need to maintain a session.

Send a GET request:

https://IP address:1500/billmgr?authinfo=admin1:mypasswd&out=xml&func=function&parameter1=value&parameter2=value...

Method features:

• the authorization method is one-time — pass the authinfo parameter in each request to the platform. A session is not created or maintained;
• authorization via authinfo can be restricted to certain IP addresses and networks. To do this, configure a "whitelist" of trusted networks:
  • via the RestrictAuthinfoRange and Option RestrictAuthinfo parameters of the configuration file;
  • via authorization settings.

Pass-through authorization by key

Use the method when you need to provide login to the platform using only the administrator's login and password.

If a client is identified by an external script, for example, a billing platform, and needs to be redirected to BILLmanager, skipping the authorization step:

1. Generate a secret key. The key length must be at least 16 characters:

   Command to generate secret key

   pwgen -s 16 1

   Example of a generated key: 1234567890qwertyuiop

2. Execute the request:

   Common request type:

   https://IP address:1500/billmgr?out=xml&authinfo=root:secret&func=session.newkey&username=alex&key=1234567890qwertyuiop

   Details

   • IP address:1500 — IP address and port of the server with the platform
   • authinfo=root:secret — BILLmanager administrator credentials
   • func=session.newkey — pass-through authorization key creation function
   • username=alex — login of the user to be authorized
   • key=1234567890qwertyuiop — generated key
3. Get a response. If the response is ok, the operation is successful. In case of an error, check the administrator's rights and the correctness of the parameters.
4. If the response is ok, redirect the user for authorization by key:
   
   Common request type:

   https://IP address:1500/billmgr?func=auth&username=alex&key=1234567890qwertyuiop&checkcookie=no

   Details

   • IP address:1500 — IP address and port of the server with the platform
   • func=auth — authorization function
   • username=alex — user login
   • key=1234567890qwertyuiop — previously generated key
   • checkcookie=no — disable cookie check

After following the URL, the user will be automatically authorized on the platform, and the used key will be deleted.

The key is single-use. The key can be set from any IP address. When using the method, the user is subject to restrictions on login by IP address. It is not possible to authorize from a non-allowed IP using the key.

Terminating a user session

Forced session termination is used for:

• security — upon detection of unauthorized or suspicious access to the platform;
• administrative management — when it is necessary to immediately terminate a user's active session. For example:
  • after access revocation;
  • when an account is blocked;
• debugging and testing — when developing integrations or external modules where it is necessary to control session states.

To terminate a user session, execute an API request:

https://IP address:1500/billmgr?func=session.delete&elid=`session number`&sok=ok

You can view current active sessions in one of the following ways:

• in the platform's web interface, go to the System state → Active sessions section;
• in the platform's database, execute a query to the core_session table:

  SELECT * FROM core_session WHERE status = 'active';

Request and result formats

API request format for BILLmanager

To send API requests to BILLmanager, use the HTTP methods GET and POST.

The request consists of the following parts:

• function — the function name that must be passed in the func parameter of the request. For example, pricelist, auth, session.delete;
• parameters — a list of parameters in parameter=value format. For example, elid=12345.

https://IP-address:1500/billmgr?func=function_name&parameter1=value1&parameter2=value2...

Depending on the function type, there are several types of results:

• list of elements (table);
• list of object parameters (form);
• successful operation (action);
• error message.

Result output formats

You can get the function output in XML format, text format, and JSON format. To specify the result format, specify the out=format_name parameter in the request.

Supported values for the out parameter:

If the out parameter is not specified, the platform returns the response in HTML format intended for display in a browser.

List of elements (table)

Returns a table of objects — for example, a list of users or tariffs. The XML document looks like:

<doc>
    <elem>list element parameters</elem>
    <elem>list element parameters</elem>
    ...
    <elem>list element parameters</elem>
</doc>

The function result describes only those list element parameters that can vary between elements. Each parameter is represented by one or more XML nodes — with attributes and values. Everything else that is the same for all elements is not included in the description — it is implied to be common to the entire structure. For example:

<doc>
    <elem>
        <elid>5001</elid>
        <date>2024-04-10</date>
        <sum>150.00</sum>
        <currency>USD</currency>
        <status>processed</status>
        <account>1024</account>
        <paymethod>bank_transfer</paymethod>
    </elem>
    <elem>
        <elid>5002</elid>
        <date>2024-04-12</date>
        <sum>75.50</sum>
        <currency>USD</currency>
        <status>pending</status>
        <account>1025</account>
        <paymethod>credit_card</paymethod>
    </elem>
</doc>

The response contains fields <date>, <currency> and others contained within <elem>, but does not contain fields that are the same for all list elements.

List of object parameters (form)

Returns data of one object — for example, when editing. The XML document looks like:

<doc>
    <elid>unique object identifier</elid>
    object parameters
</doc>

The function result describes only the object parameters. The object parameters are one or more XML nodes with possible attributes and values describing the properties of this object. For example:

<doc>
    <elid>1024</elid>
    <username>jackblack</username>
    <<email>client567@example.com</email>
    <project>2,3,1</project>
    <client_lang>ru</client_lang>
    <country>182</country>
    <state></state>
    <realname>John Doe</realname>
    <employee>1</employee>
    <note></note>
    <notify>off</notify>
    <recovery>off</recovery>
    <status>active</status>
    <created>2024-04-15</created>
</doc>

Successful operation (action)

Confirms that the action was performed. The result is issued when creating, modifying, deleting, enabling, or disabling an object. The XML document looks like:

<doc>
    <ok/>
</doc>

Error message

Returns an error description for an incorrect request. The XML document looks like:

<doc>
  <error type="exists" object="user" lang="ru">
    <param name="object" type="msg" msg="User">user</param>
    <param name="value">ben</param>
    <stack>
      <action level="30" user="jen">admin.edit</action>
    </stack>
    <group>__object__ with value '__value__' already exists</group>
    <msg>User with value 'ben' already exists</msg>
  </error>
</doc>

Methods for forming an API request

List of functions and parameters

You can view the complete list of platform functions and their parameters in the article List of API functions. Also, up-to-date information is available on the server with the platform.

To get a complete list of BILLmanager functions, use the command:

/usr/local/mgr5/sbin/mgrctl -m billmgr -i

To get a description of the data output with the list of users, use the command:

/usr/local/mgr5/sbin/mgrctl -m billmgr -i user lang=en

You can also define the required function via an API request or URL.

Composing an API request from the log

To compose an API request, perform an action in the BILLmanager interface and look at the function and parameters in the log:

1. Open the platform log file using the tail command:

   Log opening command

   tail -f /usr/local/mgr5/var/billmgr.log | grep Request

2. Perform the required action in the BILLmanager interface. In the open log file, you will see the function being executed and its parameters (starts with INFO Request).

   For example, creating a domain name (DNS) in the BILLmanager log looks like this:

   Example of information in log file

   Feb  6 08:08:07 [2346:23826] core_module INFO Request [188.120.252.33][root] 'clicked_button=ok&email_inaccess=&func=domain.edit&ip=8.8.8.8&ip_existing=&maildomain=off&name=domain.name&ns=ns1.example.com.%20ns2.example.com.&operafake=1486357687433&owner=www%2Droot&owner_admins=off&progressid=false&reversezone=&sfrom=ajax&sok=ok&web_inaccess=&webdomain=off&zoom-ip=&zoom-ns='

3. Compose an API request based on the function obtained from the log function. For more details, see the section API request format for BILLmanager of this article.

   Request API format

   https://IP address:1500/billmgr?func=function_name&parameter1=value1&parameter2=value2...
   
   

   Details

   • IP address:1500 — IP address and port of the server with the platform

   To get the API request, exclude from the request:

   1. optional parameters:

      1. sfrom.
      2. progressid.
   2. parameters equal to the * sign. Usually data that should not be displayed in the log. For example, if the request has password=*, replace * with the required value.

   3. parameters with empty values.

      Request example:

      https://123.123.123.123:443/billmgr?auth=a4b9816e498e&func=domain.edit&ip=8.8.8.8&maildomain=off&webdomain=off&name=domain.name&ns=ns1.example.com.%20ns2.example.com.&owner=www%2Droot&sok=ok&out=xml

Getting data from a URL

To get the required function and the values of its parameters, study the URL address of the form in the billing platform.

For example, to determine the URL for a specific payment, go to the Clients → Clients → select a client → Payments button → select a payment → Edit button. The URL of the payment edit form will look like:

https://IP address:1500/billmgr?func=payment.edit&elid=1256&elname=pfx%2F1256&plid=334

To get the link, click the icon next to the section title.

Operation features

Calling functions with the rights of another user

To call a BILLmanager function on behalf of another user, add the su=user_login parameter to the request. Чтобы обратиться к функции BILLmanager от имени другого 

Access rights:

• platform administrator — can call functions with the rights of any platform user;
• client with full rights — can only call functions with the rights of their clients;
• other roles — do not have the right to use the su parameter.

https://IP-address:1500/billmgr?auth=token&func=user.info&su=target_user&out=xml

Getting results in a specific language

To get the function execution result or an error message in a specific language, add the parameter to the request: lang=language_code. For example lang=de or lang=en. If a non-existent or unsupported language code is specified, the default language will be used.

Local requests to the platform

To execute API requests to the platform locally — from scripts or shell — it is recommended to use the mgrctl utility. Advantages of mgrctl:

• direct access to the platform core — bypasses the web server, does not depend on its status and settings;
• automatic authorization — requests are executed on behalf of the user who ran the command. No need to store passwords. To perform actions on behalf of another user, use the su=employee login parameter. For more details, see the section Calling functions with the rights of another user;
• built-in help — description of all functions and their parameters, relevant for the server in use.

For more information, see the article Mgrctl utility.

Operation confirmation

To apply the changes transmitted in the request, add the sok=ok parameter to the request. The sok=ok parameter in the request emulates clicking the confirmation button in the web interface — Ok, Apply, To cart, etc.

Sending a request without the sok=ok parameter is equivalent to simply opening the form. The request returns the form for editing or the current parameter values — changes are not applied.

The parameter is not required:

• in data reading requests. For example, getting current values, viewing an object;
• in functions that are not implemented as forms. For example, bulk operations.

https://IP address:1500/billmgr?func=invoice.generate&company=12&gentype=all&fromdate=2025-03-31&todate=2025-09-30&sok=ok

Redirection

To perform a redirection to another form after request execution — usually an authorization or registration request that contains sok=ok — add the redirect=startform=some.form parameter to the request, where some.form is the API function of the required form. For more details, see List of API functions.

The redirect parameter is used:

• after successful request execution, usually containing sok=ok;
• in primary requests where sok=ok is not used. For example, func=register (registration) and func=logon (authorization).

The value of the startform=some.form parameter must be URL-encoded, i.e., special characters (space, =, &, etc.) must be replaced with a sequence like %XX, where XX is the hexadecimal code of the character. For example, startform=some.form must be replaced with startform%3Dsome.form.

https://IP address:1500/billmgr?func=modifying.action&sok=ok&redirect=startform%3Dsome.form

Examples of getting a list of tariffs

As an example, getting a list of tariffs is considered. Other functions can be called in a similar way. Replace the server IP address, login, and password specified in the examples with real data.

curl

curl -k -s "https://IP address:1500/billmgr?authinfo=login:password&out=xml&func=pricelist"

mgrctl

/usr/local/mgr5/sbin/mgrctl -m billmgr pricelist

Perl language

To make a URL request from Perl, you need to install the LWP library. To work with XML documents, the XML::LibXML library is required.

#!/usr/bin/perl -w
use CGI::Carp qw(fatalsToBrowser);
print "Content-type: text/html\n\n";

use LWP::UserAgent;
use XML::LibXML;

my $result;

# Let's create a pseudo-browser that will "pretend" to be MSIE and send a request
$ua = LWP::UserAgent->new;
$ua->agent("Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)");
my $req = HTTP::Request->new(POST => 'https://IP address:1500/billmgr');


$req->content("authinfo=login:password&out=xml&func=pricelist");

my $res = $ua->request($req);

# Let's check the result
if ($res->is_success) {
    $result = $res->content;
} else {
    die $res->status_line."\n";
}

# After this, the $result variable will contain an XML document with a list of tariffs, or an error message

my $parser = XML::LibXML->new();
my $doc = $parser->parse_string( $result );
my $root = $doc->documentElement();

# Get the list of tariff names
my @tariffs = ();
for( $root->findnodes( "elem/name" ) ){
    push @tariffs, $_->textContent;
}

# Output the result to the screen
for( sort @tariffs ){
    print $_."<br>\n";
}

PHP language

The PHP language provides the ability to work with URLs as with standard files. The DOM XML library is used to process XML documents.

<?php
   $result = "";
   $fh = fopen( "http://IP-ADDR:1500/billmgr?authinfo=login:password&out=xml&func=pricelist", "r" );
   while( $data = fread( $fh, 4096 ) ){
     $result .= $data;
   }
   fclose( $fh );

   // After this, the $result variable will contain an XML document with a list of tariffs,
   // or an error message

   $doc = new DOMDocument();
   if( $doc -> loadXML( $result ) ){
       $root = $doc->documentElement;
       foreach ( $root->childNodes as $elem ){
           foreach ($elem->childNodes as $node){
               if( $node->tagName == "name" ){
                   echo $node->nodeValue;
                   echo "\n";
               }
           }
       }
   }
?>

Python language

To make a URL request from Python, the urllib2 library is used. To work with XML documents — the xml.dom.minidom library.

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from urllib2 import urlopen
from xml.dom import minidom

print "Content-type: text/html\n\n"
res = urlopen('http://IP-ADDR:1500/billmgr?authinfo=login:password&func=pricelist&out=xml')

# After this, the res variable will contain an XML document with a list of tariffs,
# or an error message

xmldoc = minidom.parse(res)

# Get the list of tariff names and output the result to the screen

for node in xmldoc.getElementsByTagName('elem'):
        for name in node.getElementsByTagName('name'):
                print ('%s<br>' % name.firstChild.nodeValue)