This RESTful API provides the building blocks that developers need to facilitate the configuration of all installed IMS Suite applications. The API works over HTTP or HTTPS.
The API is available at https://<NIU or HA address>/vsui/api.
Note
For more information about JSON, see http://json.org/ or https://tools.ietf.org/html/rfc8259.
The following shows the base URI and the format used by the API:
Base URI: <niu-ha>/vsui/api
Where niu-ha is the virtual IP of the paired NIUs (the HA address) or the address of the single NIU when there is only one.
Following the base URI, the scope and scope ID are added to show which role the actions are to be completed as.
URI Format: /<object>
Many objects will use the following URI:
/<object>/<service_provider>
The API uses the following methods:
GET: Access a resource
PUT: Create or modify a resource
POST: Create a resource
Note
The POST method can be used to import and export data.
DELETE: Delete a resource
Note
The DELETE method can be used to archive and purge data.
POST to <base_uri>/authenticate with the username and password parameters.
For example:
curl -X POST \
-H "Content-Type:application/json" \
<niu-ha>/vsui/api/authenticate \
-d '{"username":"<username>","password":"<password>"}'
The response will contain the following:
"data": [
{"token": "<secure-access-token>"}
],
"jsonapi": {"version": "2.0-3",
"name": "VSUI",
"short_name": "vsui",
"author": "IMSWorkX, Inc."
The secure access token must be passed back as the value of the Authorization header. For example:
Authorization: Basic <secure-access-token>
Note
Tokens expire after 24 hours.
The format to access objects is as follows: <niu-ha>/vsui/api/<object>
Tables are lists of objects that can be accessed and modified to affect multiple objects at once.
URI Format: <niu-ha>/vsui/api/<object>?<optionalparameters>
Table queries may contain the following parameters, all of which are optional:
{
"sort": {},
"search": {},
"like": {},
"sort_function": {},
"icontains": {},
"limit": {},
"offset": {}
}
A string that defines how a column is ordered. Accepted values are ‘<column_name> ASC’ to be sorted by ascending value or ‘<column_name> DES’ to be sorted by descending value.
A string that is a comma-separated sequence of parameters to search by. There are two formats: ‘:string’ and ‘::’ where the first represents a string search (for example, ‘first_name:Bill’ would find any person with a first name of Bill) and the second represents a between search (for example, ‘customer_number:1000:2000’ would find all records with customer numbers between, but not including, 1000 and 2000). Note that this can also be a datetime object in ISO format.
A string that denotes a value to perform a ‘like’ search. This will perform a substring search on any string fields in the object and return if any of these fields are a partial match.
A string that overrides ‘sort’. Pass in ::{:}*.
A string that is a case insensitive ‘contains’ search. Similar to the ‘search’ parameter, you should pass in a comma-separated list of ‘:string’. Exact search takes precedence. The field being searched must be a string-type variable.
An integer that is the number of records to retrieve at a time. The default value is 10.
An integer that is the number of records to skip from the beginning. The default value is 0.
An example CDR query:
curl -X GET \
-H "Content-Type:application/json" \
-H "Authorization:Basic <secure-access-token>" \
"http://localhost/vsui/api/cdr"?offset=0&limit=25&sort=column:asc
The following information is returned after a request to retrieve Call Detail Records (CDRs).
{
"cdr_id": "<string>",
"start_time": "<timestamp>",
"end_time": "<timestamp>",
"additional_data": "<array>",
"events": "<array>"
}
Endpoints
/vsui/api/vsui_cdr
GET - Retrieve all CDRs associated by call.
/vsui/api/vsui_cdr/{cdr_id}
GET - Retrieve the CDRs associated with the specified call.
URI Format: <niu-ha>/vsui/api/<object>/<object-id>
curl -X GET \
-H "Content-Type:application/json" \
-H "Authorization:Basic <secure-access-token>" \
"http://localhost/vsui/api/service_provider/IMSWorkX"
This GET command will provide a 200 message if the specified object exists:
{
"meta": {
"scope": "success",
"code": "200",
"records_page_size": "request.parameters.limit",
"archive": "request.parameters.archive",
"records_page_offset": "request.parameters.offset"
},
"data": [
{
"scope": "number",
"meta": {
"modified_by": "<string>",
"modified": "<datetime>",
"created_by": "<string>",
"created": "<datetime>"
},
"attributes": {
"rules": "<array>",
"timezone": "<string>",
"number": "<string>",
"subscriber_name": "<string>"
}
}
]
}
Use the POST command without specifying an object ID to create an object. At this time, the object will be given an object ID that can be modified later.
For example:
curl -X POST \
-H "Content-Type:application/json" \
-H "Authorization:Basic <secure-access-token>" \
<ha_address>/vsui/api/service_provider -d \
'{"name": "IMSWorkX", "display_name": "IMSWorkX", "first_name": "Jane", "last_name": "Doe", "email": "example@example.com", "address": "1 Main St. Rochester, NY", "phone": "5858675309", "notes": "more notes"}'
This example POST command will add a new Service Provider named IMSWorkX.
When the PUT command is used and the object ID is included in the command, the object is modified.
For example:
curl -X PUT \
-H "Content-Type:application/json" \
-H "Authorization:Basic <secure-access-token>" \
<ha_address>/vsui/api/service_provider/IMSWorkX -d \
'{"first_name": "John", "last_name": "Smith"}'
This example PUT command will change the name of the Service Provider from Jane Doe to John Smith.
The following information is used in the body of a request to create and edit different administrator level users.
{
"username": "John_Doe_admin",
"role_id": "service_provider:exampleserviceprovider",
"first_name": "John",
"last_name": "Doe",
"email": "jdoe@example.com",
"permissions": "default:service_provider"
}
A unique string that is the user name for this user. Limit of 64 characters. Can contain only lowercase characters, numbers, or underscores.
A string that defines the type of administrator that is being created. Accepted values are:
platform_owner
service_provider:<service_provider_name>
A string that is the first name of this user. Limit of 250 characters.
A string that is the last name of this user. Limit of 250 characters.
A string that is the email address for this user. Limit of 250 characters.
Endpoints
/vsui/api/administrator/{role_id}
GET - Retrieve all administrators with the specified role.
POST - Create an administrator with the specified role.
/vsui/api/administrator/{role_id}/{username}
GET - Retrieve the administrator with the specified role and user name.
PUT - Modify the administrator if it exists, otherwise create the administrator.
DELETE - Archive the specified administrator.
/vsui/api/administrator/{role_id}/{username}/reset
POST - Reset this user’s password, returning a reset token.
The following information is used in the body of a request to create and edit different Service Providers.
Note
These are not administrator accounts.
{
"name": "exampleserviceprovider",
"display_name": "JSMITH",
"first_name": "John",
"last_name": "Smith",
"email": "jsmith@example.com",
"address": "123 Main St",
"phone": "5851231234",
"notes": "Any string here"
}
A unique string that is the name of this Service Provider. Limit of 64 characters.
An unconstrained string used as a display name. Limit of 250 characters.
A string that is the first name of a contact for this Service Provider. Limit of 250 characters.
A string that is the last name of a contact for this Service Provider. Limit of 250 characters.
A string that is the email address of this Service Provider, where notifications and password reset requests will be sent. Limit of 250 characters.
A string that is the physical address of this Service Provider. Limit of 250 characters.
A string that is the primary phone number of this Service Provider. Limit of 250 characters.
A string that is a free-form notes field. Limit of 2048 characters.
Endpoints
/vsui/api/service_provider
GET - Retrieve all Service Providers
POST - Create a new Service Provider.
/vsui/api/service_provider/{name}
GET - Retrieve the Service Provider with the specified name.
PUT - Modify the Service Provider if it exists, otherwise create the Service Provider.
DELETE - Archive the specified Service Provider.
The following information is used in the body of a request to create and edit different IMS domains.
{
"host": "example.lab.imsworkx.com",
"service_provider_name": "serviceprovidername",
"name": "exampledomain",
"configuration": "examplelab",
"notes": "Any string here"
}
A string that is the host for this domain. This value can be a host name, IPv4 address, or IPv6 address.
A unique string that is the name of the Service Provider using this domain. Must match an existing Service Provider.
A string that is the name of this domain.
A string that is the network that this domain is a part of and is set by a Service Provider.
A string that is a free-form notes field. Limit of 2048 characters.
Endpoints
/vsui/api/domain
GET - Retrieve all hosts.
POST - Create a host.
/vsui/api/domain/{service_provider_name}
GET - Retrieve all domains for the specified Service Provider.
POST - Create a domain for the specified Service Provider.
/vsui/api/domain/{service_provider_name}/{host}
GET - Retrieve the domain with the specified Service Provider and host.
PUT - Modify the domain if it exists, otherwise create the domain.
DELETE - Archive the specified domain.
The following information is used in the body of a request to create and edit different configuration values. For configuration value details and descriptions, see Provisioning Data.
{
"element": "icscf",
"key": "java-timeout",
"variables": "[]",
"value": "10"
}
A string that defines the element that the configuration value is tied to.
A string that defines the key for the configuration value.
An array of variables used to build the configuration value.
A string that defines the value for the specified key.
Endpoints
/vsui/api/configuration_value
GET - Retrieve all configuration values.
/vsui/api/configuration_value/{element}
GET - Retrieve all configuration values for the specified element.
/vsui/api/configuration_value/{element}/{key}
GET - Retrieve the configuration value for the specified element and key.
PUT - Modify the configuration value if it exists, otherwise create the configuration value.
The following information is used in the body of a request to create and edit different IFC rules.
Note
This endpoint is only applicable when S-CSCF is installed as part of the IMS Suite.
{
"id": "1",
"value":
"<InitialFilterCriteria>
<Priority>0</Priority>
<TriggerPoint>
<ConditionTypeCNF>1</ConditionTypeCNF>
<SPT>
<ConditionNegated>0</ConditionNegated>
<Group>0</Group>
<Method>INVITE</Method>
</SPT>
</TriggerPoint>
<ApplicationServer>
<ServerName>sip:test@192.86.3.161:5065;lr</ServerName>
<DefaultHandling>0</DefaultHandling>
</ApplicationServer>
<ProfilePartIndicator>1</ProfilePartIndicator>
</InitialFilterCriteria>"
}
A numeric ID for this set of IFC rules.
An XML formatted text that defines the IFC.
Note
IFC rules strictly follow specifications in Annex E “XML schema for the Cx interface user profile” of TS 129.228.
Endpoints
/vsui/api/scscf-ifc
GET - Retrieve all IFC rule sets.
POST - Create a new IFC rule set.
/vsui/api/scscf-ifc/{id}
GET - Retrieve the IFC rule set with the specified ID.
PUT - Modify the IFC rule set if it exists, otherwise create the IFC rule set.
DELETE - Archive the specified IFC rule set.
The following information is used in the body of a request for different IP-SM-GW rates.
Note
This endpoint is only applicable when IP-SM-GW is installed as part of the IMS Suite.
{
"id": "1234",
"rate5Min": "5",
"rate1Hr": "10",
"rate24Hr": "15",
"destRates": "[]"
}
An integer that is the ID number of the sender.
An integer that is the 5-minute rate.
An integer that is the 1-hour rate.
An integer that is the 24-hour rate.
An array of temporary destination numbers.
Endpoints
/vsui/api/ipsm_rate_details
GET - Retrieve all rates.
/vsui/api/ipsm_rate_details/{id}
GET - Retrieve the sender with the specified ID.
DELETE - Archive the sender with the specified ID.
The IP-SM-GW converts SIP messages to text messages, and the sender of these text messages can be configured. The following information is used in the body of a request to create and edit different IP-SM-GW senders.
Note
This endpoint is only applicable when IP-SM-GW is installed as part of the IMS Suite.
{
"senderNumber": "1234567",
"configKey": "example",
"temporaryNumbers": "[]"
}
A string that is the number of the sender.
A string that is the configuration key.
An array of temporary numbers that may also be used by the sender.
Endpoints
/vsui/api/ipsm_sender
GET - Retrieve all senders.
POST - Create a new sender.
/vsui/api/ipsm_sender/{id}
GET - Retrieve the sender with the specified ID.
PUT - Modify the sender if it exists, otherwise create the sender.
DELETE - Archive the sender with the specified ID.
The following information is used in the body of a request to edit settings. The following example uses the default values.
{
"download_directory": "/var/opt/xpressworkx/app-manager/vsui/media/download",
"upload_directory": "/var/opt/xpressworkx/app-manager/vsui/media/upload",
"job_log_directory": "/var/opt/xpressworkx/app-manager/vsui/media/download",
"plugin_directory": "/etc/opt/xpressworkx/app-manager/vsui/elements",
"application_username": "vsui_application_manager",
"application_password": "im5_wrkX",
"branding": {
"imsworkx": {
"color_hue": "75",
"highlight_hue": "79",
"logo": "logo.png",
"label": "IMSWorkX, Inc. ®"
}
},
"restworkx": {
"archive_max_days": "7",
"audit_log_directory": "/var/opt/xpressworkx/app-manager/vsui/logs/audit-logs/",
"log_duration": "1"
},
"security": {
"client_cert": null,
"client_key": null,
"ca_bundle": null,
"allow_insecure": false
},
"web_settings": {
"help_page": "http://www.imsworkx.com",
"password_length": "8",
"number_mask": "{+DDD }(DDD) DDD-DDDD"
},
"email_settings": {
"use_email": false,
"host": "",
"user": "",
"port": "",
"password": "",
"use_tls": false,
"messages": {
"recover": {
"subject": "Recover Your Account",
"headline": "Account Recovery",
"message": "Click the link below to recover your account."
},
"activate": {
"subject": "Activate Your Account",
"headline": "Account Activation",
"message": "Click the link below to activate your account."
}
}
}
}
The following settings are set automatically during installation and should not need to be changed:
download_directory
upload_directory
job_log_directory
plugin_directory
application_username
application_password
Contains settings related to the look and feel of the website using the following parameters:
imsworkx: The default appearance settings. Additional fields can be added at this level under different names, which can then be appended to the URL for custom branding.
color_hue: (Integer) This will change the primary color used on the site. This value is a number between 0 and 360, using the HSL model where 0 is red, 120 is green, and 240 is blue.
highlight_hue: (Integer) This will change the secondary color used on the site. This value is a number between 0 and 360, using the HSL model where 0 is red, 120 is green, and 240 is blue.
logo: (String) Filename for the logo that will appear in the upper, left corner of the website. The image must be a PNG file and placed in the /var/opt/xpressworkx/app-manager/vsui/static/img/ directory.
label: (String) The message displayed in the upper, right corner of the website. This is generally a company name.
Contains settings related to the platform and database.
archive_max_days: (Integer) Number of days to keep records in the archive table.
log_duration: (Integer) Number of days before rotating the log file.
audit_log_directory: (String) Should not be changed.
Contains settings related to SSL configuration.
client_cert: (String) File location of the client’s certificate.
client_key: (String) File location of the key used for the client’s certificate.
ca_bundle: (String) File location of the root certificate. This is the only setting that matters when SSL is configured by the configure-ssl command and is automatically set by that script.
allow_insecure: (Boolean) If true, the web UI will not check the NIU’s certificate against the configured ca_bundle when making API calls.
Contains settings for elements on the website.
help_page: (String) URL for the web page that is linked in the “Help” button on the upper, right corner of the page.
password_length: (Integer) Minimum number of characters allowed in a password.
number_mask: (String) Determines how phone numbers appear. Lowercase ‘d’ represents a digit 0-9. Uppercase ‘D’ represents a digit 0-9 or an ‘X’ (denoting any digit). A lowercase ‘x’ denotes any character. Braces ({}) denote an optional grouping that will only be filled after all other groupings are filled. All other characters are taken literally as they are written but are not taken as part of the value when saving. Treat these as visual separators only.
Contains settings for automated email messages for password changes.
use_email: (Boolean) If true, activation and recovery email messages will be sent.
host: (String) Host for email client to send messages through.
user: (String) Username for email service that messages will be sent through.
port: (Integer) Port used for email host.
password: (String) Password for the email user.
use_tls: (Boolean) If true, TLS encryption will be used for the email.
messages: Contains settings for the contents of the email message.
recover: Contains settings for the contents of the email message sent when an account’s password is reset.
subject: (String) Subject line of the recovery email message.
headline: (String) Header of the recovery email message body.
message: (String) Message of the recovery email message.
activate: Contains settings for the contents of the email message sent when an account is created.
subject: (String) Subject line of the activation email message.
headline: (String) Header of the activation email message body.
message: (String) Message of the activation email message.
The following common responses may be encountered while using the API. The format of these responses may look different from the documented examples based on the tool used to make API calls.
Note
Many HTTP responses are a 200 OK due to the call to the API being successful. It is important to read the body of the response as it could contain an error.
When making an API call to a server that does not have VSUI installed, the following message will be seen.
curl -X POST \
-H "Content-Type:application/json" \
<niu-ha>/vsui/api/authenticate \
-d '{"username":"<username>","password":"<password>"}'
-v
< HTTP/1.1 404 Not Found
< Date: <datetime>
< Server: Apache/2.2.15 (CentOS)
< Content-Length: 412
< Content-Type: text/html; charset=iso-8859-1
<
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
<h1>Not Found</h1>
<p>The requested URL /vsui/api/authenticate was not found on this server.</p>
</body></html>
Note
This response is not controlled by the VSUI API and is entirely an HTTP response.
When logging in to the API with incorrect or missing information, the following message will be seen.
curl -X POST \
-d '{"username":"vsui_administrator"}' \
localhost/vsui/api/authenticate
-v
< HTTP/1.1 200 OK
< Date: <datetime>
< Server: Apache/2.2.15 (CentOS)
< Expires: <datetime>
< Vary: Cookie
< Cache-Control: max-age=0
< Last-Modified: <datetime>
< Content-Type: application/json
< Set-Cookie: vsui_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/vsui
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact
* Closing connection #0
{"meta": {
"scope": "exception",
"message": "The username and password provided were not correct.",
"code": 401,
"encoding": "ascii"
},
"jsonapi": {
"version": "1.2-11",
"name": "VSUI",
"short_name": "vsui",
"author": "IMSWorkX, Inc."
}
}
When preforming a GET for data that has not been provisioned, the following message will be seen.
curl -X GET \
-H "Authorization: Basic <secure-access-token>" \
localhost/vsui/api/service_provider/service_test45 \
-v
< HTTP/1.1 200 OK
< Date: <datetime>
< Server: Apache/2.2.15 (CentOS)
< Expires: <datetime>
< Vary: Cookie
< Cache-Control: max-age=0
< Last-Modified: <datetime>
< Content-Type: application/json
< Set-Cookie: vsui_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/vsui
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact
* Closing connection #0
{"meta": {
"code": 200,
"encoding": "ascii",
"zoom": 0,
"records_shown": 0,
"records_total": 0,
"scope": "success",
"message": "",
"archive": false,
"authorization": "Basic <secure-access-token>"
},
"data": [],
"jsonapi": {
"version": "1.2-11",
"name": "VSUI",
"short_name": "vsui",
"author": "IMSWorkX, Inc."
}
}
Note
This is technically a successful call to the API, thus the 200 code return.
When creating an object that does not exist (for example, servi instead of service_provider), the following message will be seen.
curl -X GET \
-H "Authorization: Basic <secure-access-token>" \
localhost/vsui/api/servi
-v
< HTTP/1.1 200 OK
< Date: <datetime>
< Server: Apache/2.2.15 (CentOS)
< Expires: <datetime>
< Vary: Cookie
< Cache-Control: max-age=0
< Last-Modified: <datetime>
< Content-Type: application/json
< Set-Cookie: vsui_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/vsui
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact
* Closing connection #0
{"meta": {
"scope": "exception",
"message": "No object 'servi' exists.",
"code": "404"
},
"jsonapi": {
"version": "1.2-11",
"name": "VSUI",
"short_name": "vsui",
"author": "IMSWorkX, Inc."
}
}
If a required field is missing when creating an object, the following message will be seen.
curl -X POST \
-H "Authorization: Basic <secure-access-token>" \
localhost/vsui/api/service_provider \
-d '{"last_name":"api_test"}' \
-v
< HTTP/1.1 200 OK
< Date: <datetime>
< Server: Apache/2.2.15 (CentOS)
< Expires: <datetime>
< Vary: Cookie
< Cache-Control: max-age=0
< Last-Modified: <datetime>
< Content-Type: application/json
< Set-Cookie: vsui_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/vsui
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact
* Closing connection #0
{"meta": {
"scope": "exception",
"message": "ServiceProvider(): Field 'name' is required, but missing.",
"code": 400,
"encoding": "ascii"
},
"jsonapi": {
"version": "1.2-11",
"name": "VSUI",
"short_name": "vsui",
"author": "IMSWorkX, Inc."
}
}
When making a call with a method that is not valid at the specific endpoint, the following message will be seen.
curl -X GE \
-H "Authorization: Basic <secure-access-token>" \
localhost/vsui/api/service_provider/service_test45 \
-v
< HTTP/1.1 405 METHOD NOT ALLOWED
< Date: <datetime>
< Server: Apache/2.2.15 (CentOS)
< Expires: <datetime>
< Vary: Cookie
< Allow: GET, POST, PUT, DELETE
< Cache-Control: max-age=0
< Last-Modified: <datetime>
< Content-Length: 0
< Content-Type: text/html; charset=utf-8
< Set-Cookie: vsui_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/vsui
<
* Connection #0 to host localhost left intact
* Closing connection #0
When making a successful API call, the following message will be seen.
curl -X GET \
-H "Authorization: Basic <secure-access-token>" \
localhost/vsui/api/service_provider/ \
-v
< HTTP/1.1 200 OK
< Date: <datetime>
< Server: Apache/2.2.15 (CentOS)
< Expires: <datetime>
< Vary: Cookie
< Cache-Control: max-age=0
< Last-Modified: <datetime>
< Content-Type: application/json
< Set-Cookie: vsui_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/vsui
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact
* Closing connection #0
{"meta": {
"code": 200,
"encoding": "ascii",
"zoom": 0,
"records_page_offset": 0,
"records_shown": 1,
"records_total": 1,
"scope": "success",
"message": "",
"archive": false,
"authorization": "Basic <secure-access-token>",
"records_page_size": 10
},
"data": [{
<DATA FROM OBJECT>
}],
"jsonapi": {
"version": "1.2-11",
"name": "VSUI",
"short_name": "vsui",
"author": "IMSWorkX, Inc."
}
}
The above responses can be seen as responses from a stable API. If you encounter other undocumented API errors, please contact support@imsworkx.com with the API call and output.
Audit logs are generated every day by default and are stored as a CSV file. By default, these files are located in /var/opt/xpressworkx/app-manager/vsui/logs/audit-logs and are named audit-<year>.<month>.<day>.log.