2

VSXi REST API

 

The VSXi REST API allows you to manage VSXi systems in a simple, programmatic way using conventional HTTP requests. Most of the functionality that you are familiar with in the VSXi GUI is also available through the API, allowing you to script the complex actions that your situation requires.

The API documentation will start with a general overview and then break down the different components. To access the VSXi REST API,  basic HTTP knowledge is necessary: how an HTTP request is sent as {method url}, how to attach a file as input and save output into a file.

User authentication is done on each request using basic authentication. User has to input a valid GUI/API username/password and embed that in HTTPS basic authentication header.

All requests made to the VSXi follow a similar format, with user authentication performed on each HTTP request.

The syntax for REST is as follows:

curl -u $user:$pass -X $METHOD -k -$FLAG file.xml
            https://SERVER_IP:8888/SSConfig/webresources/<action>/{table}?{format=xml/json}

 

In the following sections we go into further detail on actions and tables.

The basic supports the following HTTP methods:

  • GET: For downloads, queries and stats commands.
  • POST: For inserts and changes.
  • DELETE: For deletions.

In combination with the HTTP method, the VSXi REST API defines several actions described below. Each action supports a specific HTTP method.

Downloads data from the specified table. HTTP GET.

Updates entries in the specified table. If the entry is not currently in the table this action functions as an insert. HTTP POST.

Deletes entries from the specified table. HTTP DELETE.

Uploads data in a XML file to the server and replaces the data in a specified table. HTTP POST.

Note: A replace is a wipe and insert operation. The large counterpart action is replaceLarge.

Commands that have “Large” as part of operation name are used to update, replace, delete or download data in zipped XML (binary) format. HTTP POST.

These actions are:

  • updateLarge
  • downloadLarge
  • deleteLarge
  • replaceLarge

Query specified table using the specified query string. HTTP GET.

Downloads real-time stats from specified table. HTTP GET.

Downloads system status or files.  HTTP GET.

The VSXi web interface is structured into parent tabs and child tabs. There are eight parent tabs: Monitoring, Trace, Routes, Resources, Digit Mappings, Service Ports, App Servers and System. In the scope of this document a table is defined as the different sub-tabs available on the system. For example, the Resources parent tab has the following tables: Resources, Registrar, Blocked Resources, SIP Profiles, Cause Code Profiles, Stop Route Profiles, SMC Profiles, SMC Data Files and CAC Profiles.

The following tables are supported via API. Tables are listed in the familiar parent-child structure. In parenthesis you will find the web UI reference in parent > child tab format. (e.g. Resources > Resources).

  • Monitoring:
    • active_calls (Monitoring > Active Answered Calls)
    • realtime (Monitoring > System Stats)
    • resource (Monitoring > Resource Stats)
    • resource_detail (Monitoring > Real-Time Stats)
    • sip_stats (Monitoring > SIP Stats)
    • sub_stats
  • Routes:
    • route (Routes > Routes)
    • routegroup (Routes > Route Groups)
    • routetable (Routes > Route Table)
  • Resources:
    • cac_index (Resources > CAC Profies)
    • resource (Resources > Resource)
    • resourceblock (Resources > Blocked Resources)
    • smcDataFile (Resources > SMC Data Files)
    • subscriber Resources > Registrar)
  • Digit Mappings:
    • digit_mapping (Digit Mappings > Digit Mappings)
    • digit_mapping_index (Digit Mappings > Digit Mapping Table)
  • Service Ports:
    • serviceport (Service Ports > Service Ports)
    • serviceport_certificates
    • media_server_profile (Service Port > Media Server Profiles)
    • virtualip
  • App Servers:
    • media_server (App Servers > Media Servers)
  • System:
    • hardwareConfiguration (System > Advanced: Save Hardware Info)
    • systemConfiguration (System > Save Config)
    • users ( System > Users)

The VSXi REST API is an evolution of the VSXi legacy SOAP/Web Services API. By default, if not specified, data will be downloaded or received in XML format. You can use the format parameter within the URL to specify the desired data format.

?{format=xml/json}

While XML/JSON are widely supported some tables or actions support CSV and plain text.

On any data input operation (UPDATE, DELETE, UPLOAD, REPLACE) you must submit the the entire payload. That is all XML/JSON elements that correspond to the table. All fields are required and omitting fields will result in an error. As an example if you are updating one field in the Resource table, you need to submit all fields not just the key element and the field being changed.  The best common practice is to download, edit and upload the file.

While files are most commonly used it is also possibly to send serial data with the full XML/JSON content if desired.

This is an example schema of a resource input file.

         "name" : "Example",
         "companyName" : "Example",
         "trunkId" : 1,
         "sgId" : 0,
         "capacity" : 50,
         "cpsLimit" : 5,
         "node" : [ {
            "fqdn" : "10.1.1.2",
            "netmask" : 32,
            "capacity" : 46,
            "cpsLimit" : 5,
            "cacProfileId" : 0
         }, {
            "fqdn" : "10.1.1.3",
            "netmask" : 32,
            "capacity" : 46,
            "cpsLimit" : 5,
            "cacProfileId" : 0
         } ],
         "rtid" : 0,
         "ingress1" : {
            "match" : "1",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "ingress2" : {
            "match" : "all",
            "action1" : "prepend",
            "digits1" : "1",
            "action2" : "none",
            "digits2" : ""
         },
         "egress1" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "egress2" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "outboundANI" : "pass",
         "techPrefix" : "default",
         "rnIngress1" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "rnIngress2" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "rnEgress1" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "rnEgress2" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "codecPolicy" : "transparent",
         "srtpEnable" : "disable",
         "srtpSize" : 80,
         "srtpDtls" : "disable",
         "groupPolicy" : "top_down",
         "dtid" : 1,
         "t38" : "enable",
         "rfc2833" : "enable",
         "payloadType" : 101,
         "tos" : "B8",
         "svcPortIndex" : 1,
         "radiusAuthGrpIndex" : 0,
         "radiusAcctGrpIndex" : 0,
         "lnpGrpIndex" : 1,
         "lnpEnhancedGrpIndex" : 0,
         "stiASGrpIndex" : 0,
         "stiVSGrpIndex" : 0,
         "cnamGrpIndex" : 0,
         "ersGrpIndex" : 0,
         "maxCallDuration" : 10800,
         "minCallDuration" : 0,
         "noAnswerTimeout" : 120,
         "noRingTimeout" : 30,
         "causeCodeProfile" : 0,
         "stopRouteProfile" : 0,
         "paiAction" : "Disable",
         "paiString" : "5555555013",
         "inheritedGenericHeader" : "",
         "outSMCProfileId" : 0,
         "stiIngressAuthentication" : "none",
         "stiIngressAuthFailBehavior" : "passthru",
         "stiEgressIdHdrTreatment" : "no-hdr",
         "stiIngressVerification" : "disable",
         "stiEgressVerifyFailBehavior" : "passthru"
      } ]
   }

 

Having an understanding of the supported HTTP methods, system tables and actions the following table provides a list of the possible "commands" that can be issued via API and supported data format.

HTTP Method Action Table Format
GET download route XML/JSON
GET download routegroup XML/JSON
GET download routetable XML/JSON
GET download resource XML/JSON
GET download resourceblock XML/JSON
GET download digit_mapping_index XML/JSON
GET download digit_mapping XML/JSON
GET download subscriber XML/JSON
GET download media_server_profile XML/JSON
GET download media_server XML/JSON
GET downloadLarge route Zip XML/JSON
GET downloadLarge subscriber Zip XML/JSON
GET downloadLarge digit_mapping Zip XML/JSON
GET download virtualip XML/JSON
GET downloadLarge systemConfiguration Zip SDC
GET downloadLarge hardwareConfiguration Zip SDC
       
GET downloadLarge smcDataFile Zip CSV
POST update route XML/JSON
POST update routegroup XML/JSON
POST update routetable XML/JSON
POST update resource XML/JSON
POST update resourceblock XML/JSON
POST update digit_mapping_index XML/JSON
POST update digit_mapping XML/JSON
POST update subscriber XML/JSON
POST update users XML/JSON
POST updateLarge route Zip XML/JSON
POST updateLarge subscriber Zip XML/JSON
POST updateLarge digit_mapping Zip XML/JSON
POST update virtualip XML
DELETE delete route XML/JSON
DELETE delete routegroup XML/JSON
DELETE delete routetable XML/JSON
DELETE delete resource XML/JSON
DELETE delete resourceblock XML/JSON
DELETE delete digit_mapping_index XML/JSON
DELETE delete digit_mapping XML/JSON
DELETE delete subscriber XML/JSON
DELETE delete sub_stats XML/JSON
DELETE delete active_calls XML/JSON
DELETE delete users XML/JSON
DELETE deleteLarge route Zip XML/JSON
DELETE deleteLarge subscriber Zip XML/JSON
DELETE deleteLarge digit_mapping Zip XML/JSON
POST upload route XML/JSON 
POST upload routegroup XML/JSON
POST upload routetable XML/JSON
POST upload resource XML/JSON
POST upload resourceblock XML/JSON
POST replaceLarge route Zip XML/JSON
POST replaceLarge routesInRouteTable Zip XML/JSON
POST replaceLarge subscriber Zip XML/JSON
POST replaceLarge digit_mapping Zip XML/JSON
POST replaceLarge digitMappingsInDigMapTable Zip XML/JSON
POST replaceLarge smcDataFile Zip CSV
GET query route XML/JSON
GET query resource XML/JSON
GET query subscriber XML/JSON
GET query digit_mapping XML/JSON
GET query active_calls XML/JSON
GET stats resource XML/JSON
GET stats realtime XML/JSON
GET stats resource_detail XML/JSON
GET stats media_server XML/JSON
GET stats sub_stats XML/JSON
GET stats sip_stats XML/JSON
GET stats active_calls XML/JSON
GET system realtime Text

Download

curl -u $user:$pass -X GET -k -o file.xml
            "https://SERVER_IP:8888/SSConfig/webresources/download/route"

Update

curl -u $user:$pass -X POST -k -T file.xml
             "https://SERVER_IP:8888/SSConfig/webresources/update/resource"

Delete

curl -u $user:$pass -X DELETE -k -T file.xml
              "https://SERVER_IP:8888/SSConfig/webresources/delete/resource"

Query

curl -u USERNAME:PASSWORD -X GET -o DMT.xml
              "https://SERVER_IP:8888/SSConfig/webresources/query/digit_mapping?queryString=alias like '%TEST%'"

or

curl -u USERNAME:PASSWORD -X GET -o DMT.xml
             "https://SERVER_IP:8888/SSConfig/webresources/query/digit_mapping?queryString=alias%20like%20%27%25TEST%25%27"

Stats

curl -u USERNAME:PASSWORD -X GET -k -o /root/stats.xml
             "https://SERVER_IP:8888/SSConfig/webresources/stats/realtime"

If you prefer sending the payload within the curl command instead of using a file this is an example syntax.

curl -u USERNAME:PASSWORD -X POST -k -H "Content-Type:text/xml" -d '<?xml version="1.0" encoding="UTF-8"?><DigitTranslationList><DigitTrans><alias>API_Test</alias><tableId>4</tableId><origAni>any</origAni><origAniMinLength>0</origAniMinLength><origAniMaxLength>40</origAniMaxLength><origDnis>555</origDnis><origDnisMinLength>0</origDnisMinLength><origDnisMaxLength>40</origDnisMaxLength>
<transAni>5555551234</transAni><transDnis></transDnis><aniAction>all</aniAction><dnisAction>passthrough</dnisAction></DigitTrans></DigitTranslationList>' "https://SERVER_IP:8888/SSConfig/webresources/update/digit_mapping"

Querying a table allows you to download just a portion of the content you are interested in instead of the entire table. This is the list of table parameters currently supported:

resource route digit_mapping
alias alias alias
allow_directMedia digit_match table_id
cause_code_profile_id end_tod oani
CNAME_group_index group_id odnis
codec_policy max_len tani
company_name min_len tdnis
cps_limit policy  
digit_trans_id resource_id_1  
direction resource_id_2  
DNC_group_index resource_id_3  
ERS_group_index resource_id_4  
LNP_group_index resource_id_5  
max_call_duration resource_id_6  
no_answer_timeout resource_id_7  
no_ring_timeout resource_id_8  
option_poll start_tod  
pai_action table_id  
pai_string    
RADIUS_acct_group_index    
RADIUS_auth_group_index    
service_port_index    
service_state    
sip_profile_index    
source_address    
stop_route_profile_id    
table_id    
tech_prefix    
trunk_id    
egress_smc_profile_id    
srtp_enable    
sti_ingress_authentication    
sti_ingress_verification    
sti_egress_id_hdr_treatment    
STI_AS_group_index    
STI_VS_group_index    
nat_peering    
     

This paragraph lists codes returned by VSXi server in response to various requests. Each return message has the return code and text message that describes the code.

Code Associated Message Description
200 200 OK General OK response.
  200 OK - uploadXmlFile success. File upload was OK.
300 Finished With Errors File was uploaded but some items failed validation and were discarded. Valid items were processed successfully.
400 400 fail - invalid table specified: + requested table name. Invalid table name.
    Invalid table name.
  400 fail - validation exception XML validation error.
  400 fail - digit match can not be empty Digit match has to be specified for RouteLookUp
  400 – failed Other types of errors (exception)
401 401 Fail - User Not Authorized: Invalid username or no read/write permissions. User is not authorized or doesn't have permissions
  401 Fail - User Not Authorized: invalid user password User password is invalid.
402 402 Fail - This action is not allowed while system is in Load-Balance Slave mode

No configuration changes are allowed on slave servers data can only be dowloaded

 

When data is uploaded to the VSXi server in plain-text the whole file is validated and if any error is found, the process is aborted and no changes are done to the system table.

In case when “Large” commands are used with compressed (zipped) data, if an error is found in one entry (XML element), that entry is thrown away and error is logged to the user log file. However, the process continues. For example, if one route is found to be invalid, it’s thrown away, but the other routes are processed and stored in DB (updated, replaced, deleted...). In that case the return code is 300, and the message describing the error is “300 Finished With Errors - Validation Errors were detected. Please see User Access Log file for details.”

In both cases errors are logged to User Access Log File that can be found and downloaded in GUI, Trace>User Log tab. Upper box on this page lists all User Log files available for download, and the lower box shows the latest entries in the latest file – user_access.log.

Starting in version VSXi-10.5.1.500 it is possible to delete entries in the Subscriber Stats page using SOAP or REST API.

The API request can specify from one or multiple fields to perform the delete. The following fields can be included:

  • "username",
  • "trunkID",
  • "id" (Subscriber ID),
  • "userDomain" (Host) or
  • "userIp" (Source IP)

Multiple entries are interpreted as an AND operator.

 
Example:

curl -u username:password -X DELETE -k -T sub_stats_delete.xml 'https://testip:8888/SSConfig/webresources/delete/sub_stats'

sub_stats_delete.xml

<?xml version="1.0" encoding="UTF-8"?>
<XBSubStatsList>
<XBSubStats>
<username>8_2216_M</username>
<userDomain>venice-domain-cs2</userDomain>
<id>3-7</id>
<userIp>72.197.139.18</userIp>
<trunkId>00006</trunkId>
</XBSubStats>
<XBSubStats>
<username>8_2215</username>
</XBSubStats>
</XBSubStatsList>

All requests receive a 200 OK.

Full payload response and fiefld defintion for sub_stats endpoint:

  • States:
    • Authenticated: Successful registration.
    • Unauthenticated: Registration with pending authentication.
    • Blocked: Endpoint has failed N number of authentication attempts.
    • Pending: Transient state normally indicates waiting for Feature Server/Registrar.
  • Trunk ID: Trunk ID associated with the registered user.
  • Create Time: Registration instance when the device first registered.
  • Username.
  • User Domain.
  • User IP: Source IP address of registering endpoint.
  • User Port: Source Port of registering endpoint.
  • ID: Registration ID created by the VSXi for internal tracking purposes.
  • NAT: Network Address Translation detection (Yes, No).
  • SPID: Origination Service Port ID.
  • Protocol:
    • UDP
    • TCP
    • TLS (TLS v1.0, TLS v1.1, TLS v1.2, TLS v1.3).
    • Note: TLS protocol version display added in VSXi-10.7.1.70+.
  • Expiration: Calculation of when this registration will expire if the device fails to re-register timely. This was designed for Push Notifications that may not re-register for days or weeks.
  • Agent: SIP User-Agent disclosed in the SIP REGISTER.
  • PN-PARAM: Push Notifications pn-param per RFC8599.
<XBSubStatsList>
   <XBSubStats>
      <states>AUTHENTICATED</states>
      <trunkId>00013</trunkId>
      <createTime>02-10-2023 17:20:52</createTime>
      <username>2200_06</username>
      <userDomain>sip.sansay.com</userDomain>
      <userIp>192.168.191.98</userIp>
      <userPort>5188</userPort>
      <id>2-1</id>
      <nat>Yes</nat>
      <spid>3</spid>
      <protocol>UDP</protocol>
      <expiration>03-13-2023 07:46:05</expiration>
      <agent>MicroSIP/3.21.3</agent>
      <pn-param></pn-param>
   </XBSubStats>

30 replies

null
    • Peter_Eisengrein
    • 5 yrs ago
    • Reported - view

    In which version of VSXi software is REST introduced?

      • cperez
      • 5 yrs ago
      • Reported - view

      Peter Eisengrein 

      REST API was introduced in version VSXi-10.1.1.x. Some objects were not added until VSXi-10.1.1.228, worth noting if you have an earlier release installed.

       

      Will add this note to the article, thanks Peter.

    • gene_lamoreaux
    • 5 yrs ago
    • Reported - view

    Is the REST api supported on the 10.2.2.x code base too?  (Specifically 10.2.2.138)  Asking as we would prefer to make use of the REST API as opposed to having to install the vsxi ws client in multiple places.  

      • cperez
      • 5 yrs ago
      • Reported - view

      gene. lamoreaux yes, REST API is supported in 10.2.2.x as well. Anything greater than 10.1.1.x supports REST API. 

      • gene_lamoreaux
      • 5 yrs ago
      • Reported - view

      Carlos Perez Thanks!  I guess we're waiting on a new 10.2.2.x build that will resolve the dtmf 0 not being transcoded into an rtp event.   

      • cperez
      • 5 yrs ago
      • Reported - view

      gene. lamoreaux That problem has been fixed 🙂

      • gene_lamoreaux
      • 5 yrs ago
      • Reported - view

      Carlos Perez   Yep, looks like build 10.2.2.153 fixes the missing inband 0 transcoded to rtpevent.  

    • gene_lamoreaux
    • 5 yrs ago
    • Reported - view

    How do I use curl to test the REST api function when it keeps returning "curl: (35) schannel: next InitializeSecurityContext failed: SEC_E_INVALID_TOKEN (0x80090308) - The token supplied to the function is invalid" for any curl issued command against the sbc?     I don't see anything noting Token garnering or how to use such in the RESTful API guide on this page. 

      • cperez
      • 5 yrs ago
      • Reported - view

      gene. lamoreaux You will need a valid SSL certificate to get past this error in Windows. (There may be other tricks to accept existing self-signed certificate). 

      • gene_lamoreaux
      • 5 yrs ago
      • Reported - view

        Carlos Perez Ok, and where is the process for getting that setup documented? 

      • cperez
      • 5 yrs ago
      • Reported - view

      gene. lamoreaux You can follow the basics of this procedure. It is titled SIP/TLS but it also applies for GUI/API SSL cert. Once Sansay has posession of .p12 file we will load it on the system. Let's continue the conversation in your ticket.

      https://support.sansay.com/t/18d310/generating-a-siptls-p12-file

    • voiceops
    • 4 yrs ago
    • Reported - view

    I hope you can help me. I'm getting a '401 Unauthorized' when trying to test the API as the example says.

    Example command:

    curl -i -k -XGET 'https://0.0.0.0:8888/SSConfig/webresources/downloadLarge/route' -u 'xxxxxxx:zzzzzzzzz'

      • gene_lamoreaux
      • 4 yrs ago
      • Reported - view

      voiceops  You probably have to create a superuser and then stipulate those creds when you make the curl call...  

      • cperez
      • 4 yrs ago
      • Reported - view

      voiceops  Try checking the User Log (Trace > User Log). You should see an error explaining the problem. Could be a user/pass error, could also be that you have yet to define the source IP as a Trusted Host (System > Trusted Hosts)

      • voiceops
      • 4 yrs ago
      • Reported - view

      Carlos Perez It's working fine now, thanks.

    • Jeremy_Van_Bortel
    • 4 yrs ago
    • Reported - view

    Hello,

    Is there a limit on download table size when using format=json?  I to get the following response and a 500 Internal Server Error, even on medium size tables. XML works fine, but requires more more work on non Java clients:

     

    convert xml2json failed(JAXB)

     

    Thanks,

    Jeremy

      • cperez
      • 4 yrs ago
      • Reported - view

      Jeremy Van Bortel We are checking on this, Jeremy. 

      • Jeremy_Van_Bortel
      • 4 yrs ago
      • Reported - view

      Carlos Perez This seems to have been resolved somewhere between 10.1.1.305 and 10.2.2.207.  On the device we upgraded last night to 10.2.2.207, I am able to pull all tables in json format without issue.

    • jhansen
    • 4 yrs ago
    • Reported - view

    What is the correct way to pass query string ?
    I try:
    https://SERVER_IP:8888/SSConfig/webresources/query/route?format=json&query=alias+like+%27anna16dec2+access%27

    but it doesn't work
     

      • cperez
      • 4 yrs ago
      • Reported - view

      jhansen Have you tried escaping the special characters? such as alias%20like%20%27 ...

    • voiceops
    • 4 yrs ago
    • Reported - view

    Hi, could someone assist me with a request? My purpose is to finish the active calls from a specific resource but I don't know if the syntax is correct, I wouldn't like to make a bad request then terminate all calls from all resources. The TID should be part of the URL params or as payload?

     

    Example (python):

    requests.get(f'https://{ip}:8888/SSConfig/webresources/delete/active_calls', auth = (config.user, config.psw), params = {'format': 'json'}, verify = False, json = {'orig_tid': 1234})

     

    Where:

    url-> https://{ip}:8888/SSConfig/webresources/delete/active_calls

    auth-> user:password

    params-> format=json

    verify-> ignore sertificate

    json-> payload = {'orig_tid': 1234}

      • cperez
      • 4 yrs ago
      • Reported - view

      voiceops 

      This would be the approach:

       

      curl -u  $USER:$PASS -X GET -o activecall.xml "https://$SYSTEM:8888/SSConfig/webresources/query/active_calls?queryString=dnis%20like%20%27%2519177%25%27"

      In bold can change from a like to an equals statement. For example orig_tid="1234". You will need to escape the = and ". Let us know if this does the trick for you.

      • voiceops
      • 4 yrs ago
      • Reported - view

      Carlos Perez Hi, Carlos. It works fine but it gives me active calls, what would be the URL to terminate a call? "delete/active_calls"?

      • Jeff_Anderson
      • 3 yrs ago
      • Reported - view

      voiceops 

      I was looking to do the same thing. Using the CSV example my file had one entry.

      cat mycall.csv
      callID:6b02bf1e548c7bc52f68fb948b2023e9

      Curl -k -u myuser:mypwd -X DELETE -k -T mycall.csv "https://host:8888/SSConfig/webresources/delete/active_calls

      It returns a 200 OK in response to the curl request

      The SIP BYE is sent in both directions from the INX. The reason says 'Q.850;cause=16;text="Manual Deletion"

      I found this url helpful to make the queries.

      https://support.sansay.com/t/63v0nr/management-of-answered-call-list

      • cperez
      • 11 mths ago
      • Reported - view

      Jeff Anderson After further review at this time only CSV and XML is supported. We will put in a feature request to support JSON. JSON only downloads calls but doesn't work to delete active calls.