This RESTful API provides the building blocks developers need to programmatically integrate ICR with other network elements and systems. The API works over HTTP or HTTPS.
Individual objects that can be manipulated through the API include ICR administrators, service providers, and more. This chapter is a developer reference for connecting a currently used system to ICR.
The API is available at https://<niu or HA address>/icr/api.
Note
For more information about JSON, see http://json.org/ .
The following shows the base URI and the format used by the API:
Base URI: <niu-ha>/icr/api
Where niu-ha is the host address of the primary NIU.
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>/<subscriber>
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. For more information, see Provisioning.
DELETE: Delete a resource
Note
The DELETE method can be used to archive and purge data. For more information, see Archiving, Restoring, and Purging Data.
POST to <base_uri>/authenticate with the username and password parameters.
For example:
curl -X POST \
-H "Content-Type:application/json" \
<niu-ha>/icr/api/authenticate \
-d '{"username":"<username>","password":"<password>"}'
The response will contain the following:
"data": [
{"token": "<secure-access-token>"}
],
"jsonapi": {"version": "2.0-3",
"name": "Intelligent Call Routing",
"short_name": "icr",
"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.
URI Format: <niu-ha>/icr/api/<object>/<object-id>
curl -X GET \
-H "Content-Type:application/json" \
-H "Authorization:Basic <secure-access-token>" \
"http://localhost/icr/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": "< single >",
"number": "< single >",
"subscriber_name": "< single >"
}
}
]
}
Tables are lists of objects that can be accessed and modified to affect multiple objects at once.
URI Format: <niu-ha>/icr/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/icr/api/cdr"?offset=0&limit=25&sort=column:asc
The following information is returned after a request to retrieve Call Detail Records (CDRs).
{
"original_called_number": "<string>",
"called_number": "<string>",
"calling_number": "<string>",
"start_time": "<timestamp>",
"end_time": "<timestamp>",
"route": "<object>",
"service_provider_name": "<string>",
"subscriber_name": "<string>",
"cdrs": "<array>"
}
Endpoints
/icr/api/icr_cdr
GET - Retrieve all CDRs.
/icr/api/icr_cdr/{service_provider_name}
GET - Retrieve the CDRs associated with the specified Service Provider account.
/icr/api/icr_cdr/{service_provider_name}/{subscriber_name}
GET - Retrieve the CDRs associated with the specified Subscriber account.
/icr/api/icr_cdr/{service_provider_name}/{subscriber_name}/{original_called_number}
GET - Retrieve the CDRs associated with the specified originally called number.
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>/icr/api/service_provider -d \
'{"display_name": "IMSWorkX", "name": "IMSWorkX", "notes": "Some more notes", "address": "1 Main St.↵Rochester, NY", "email": "example@example.com", "first_name": "Jane", "last_name": "Doe", "phone": "5858675309"}'
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>/icr/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": "exampleadministrator",
"role_id": "service_provider:<exampleadministrator>",
"first_name": "John",
"last_name": "Doe",
"email": "jdoe@example.com",
"permissions": "default:service_provider"
}
A unique string of lowercase characters that is the user name for this user. Limit 64 characters.
A string that defines the type of administrator that is being created. Accepted values are:
platform_owner
service_provider:<service_provider_name>
subscriber:<service_provider_name>:<subscriber_name>
A string that is the first name of this user. Limit 250 characters.
A string that is the last name of this user. Limit 250 characters.
A string that is the email address for this user. Limit 250 characters.
An array of permission groups that this user is a member of. Permissions are dependent on the role_id of the created administrator.
add_permission_group_entries
alter_platform_owner_user
alter_service_provider_user
create_permission_group
default:service_provider
default:subscriber
icr_default:icr_platform_owner_views
icr_default:icr_service_provider_provisioning
icr_default:icr_service_provider_views
icr_provision_audio
icr_view_audio
list_permission_groups
view_subscriber
Endpoints
/icr/api/administrator/{role_id}
GET - Retrieve all administrators with the specified role.
POST - Create an administrator with the specified role.
/icr/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.
/icr/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 audio files.
{
"file": "Hello.wav",
"location": "/temp/audio",
"server": "lab-niu01.lab.redcom.com",
"label": "Hello",
"service_provider_name": "Name"
}
A string that is the server (NIU or secondary) where the audio file is stored.
A string that is the exact location of the audio file.
A string that is the name of the audio file. This must be a .wav file. While searching for all files, can use a regex match “^.*?.wav$”.
A string that is a nickname or label to help identify this audio file.
A unique string that is the Service Provider for this audio file. Must match an existing Service Provider.
Endpoints
/icr/api/audio/{service_provider_name}
GET - Retrieve all audio files under the specified Service Provider.
POST - Create a new audio file.
/icr/api/audio/{service_provider_name}/{file}
GET - Download a specific audio file.
PUT - Modify the audio file if it exists, otherwise create the audio file.
DELETE - Archive the specified audio file.
The following information is used in the body of a request to create and edit call plans.
{
"service_provider_name": "Name",
"display_name": "ExampleCallPlan",
"name": "examplecallplan",
"subscriber_name": "examplesubscriber",
"rules": "[{\"label\":\"rule_name\",\"criteria\":{\"always\":true},\"destination\":{\"number\":[\"1112223333\"],\"parameters\":{}}]",
"timeout": "30",
"far_end_pickup_destination_type": "NUMBER",
"far_end_pickup_destination_values": "{\"number\":\"5551231234\"}"
}
A unique string that is the Service Provider for this call plan. Must match an existing Service Provider.
A string that is the type of far end pickup destination. The default value is “NONE”. Accepted values are:
NONE
SIP
NUMBER
TRUNK
TRUNK-OUTPULSE
A string that is the display name for this call plan. Limit 250 characters.
A string that is the name for this call plan. Limit 250 characters.
A unique string that is the name of the Subscriber that uses this call plan. Must match an existing Subscriber.
A JSON object or an escaped JSON string specifying the rules for a call plan. Rules also support multiple destinations by populating a route_advance property on the destination. If ICR is unable to connect the call to a destination, the next configured route will be tried. For example,
{
"label": "New Rule",
"criteria": {
"always": true
},
"destination": {
"number": [
"1112223333"
],
"route_advance": {
"number": [
"2223334444"
]
}
},
"parameters": {}
}
An integer that is the number of seconds to wait before a call is considered failed. The default value is 30.
A JSON object or an escaped JSON string specifying the value for the far end destination. The default value is {}.
Endpoints
/icr/api/call_plan/{service_provider_name}
GET - Retrieve all call plans under the specified Service Provider.
POST - Create a new call plan under the specified Service Provider.
/icr/api/call_plan/{service_provider_name}/{subscriber_name}
GET - Retrieve all call plans under the specified Subscriber.
POST - Create a new call plan under the specified Subscriber.
/icr/api/call_plan/{service_provider_name}/{subscriber_name}/{name}
GET - Retrieve the call plan under the specified Subscriber and with the specified name.
PUT - Modify the call plan if it exists, otherwise create the call plan.
DELETE - Archive the specified call plan.
The following information is used in the body of a request to create and edit rules used by a call plan.
{
"type": "REQUIRE",
"description": "Requires the destination to have a 315 area code.",
"value": "1315xxxxxxx",
"label": "Require315",
"service_provider_name": "Name"
}
A string that determines if the constraint requires or blocks the call based on the value. Accepted values are ‘REQUIRE’ or ‘BLOCK’.
A string that describes the call destination constraint. Limit 250 characters.
A string that is the call destination constraint value. Uses regex format.
A string that is the call destination constraint label. Limit 250 characters.
A unique string that is the Service Provider for this constraint. Must match an existing Service Provider.
Endpoints
/icr/api/constraint/{service_provider_name}
GET - Retrieve all call destination constraints under the specified Service Provider.
POST - Create a call destination constraint under the specified Service Provider.
/icr/api/constraint/{service_provider_name}/{label}
GET - Retrieve the specified call destination constraint.
PUT - Modify the call destination constraint if it exists, otherwise create the audio file.
DELETE - Archive the specified call destination constraint.
The following information is used in the body of a request to create and edit different routing tables. Routing tables are used to order call plans by priority, where lower priority call plans are evaluated first.
{
"priority": "10",
"call_plan_name": "ExampleCallPlan",
"number": "5851231234",
"call_plan_service_provider_name": "Name",
"call_plan_subscriber_name": "ExampleSubscriber",
"call_plan_display_name": "ExampleCallPlan"
}
An integer that is the priority for this call plan. A lower value priority is checked before a higher value priority. The default value is 0. Limit values from 0 to 99.
A unique string that is the call plan that uses this routing entry. Must match an existing Call Plan.
A unique string that is the number that uses this routing entry.
A unique string that is the Service Provider for this call plan that uses this routing entry. Must match an existing Service Provider.
A unique string that is the Subscriber for this call plan that uses this routing entry. Must match an existing Subscriber.
A unique string that is the display name of the call plan that uses this routing entry. Limit 250 characters.
Endpoints
/icr/api/routing_table/{service_provider_name}
GET - Retrieve all routing tables under the specified Service Provider.
POST - Create a routing table under the specified Service Provider.
/icr/api/routing_table/{service_provider_name}/{call_plan_subscriber_name}
GET - Retrieve all routing tables under the specified Subscriber.
POST - Create a routing table under the specified Subscriber.
/icr/api/routing_table/{service_provider_name}/{call_plan_subscriber_name}/{call_plan_name}
GET - Retrieve all routing tables under the specified call plan.
POST - Create a routing table under the specified call plan.
icr/api/routing_table/{call_plan_service_provider_name}/{call_plan_subscriber_name}/{call_plan_name}/{number}
GET - Retrieve the specific routing table.
PUT - Modify the specific routing table if it exists, otherwise create the routing table.
DELETE - Archive the specific routing table.
The following information is used in the body of a request to create and edit different Service Providers.
Note
These are not administrator accounts.
{
"first_name": "John",
"last_name": "Smith",
"display_name": "JSMITH",
"name": "exampleserviceprovider",
"legacy_service_provider_id": {},
"notes": "Any string here.",
"phone": "5851231234",
"address": "123 Main St",
"email": "jsmith@example.com"
}
A string that is the first name of a contact for this Service Provider. Limit 250 characters.
A string that is the last name of a contact for this Service Provider. Limit 250 characters.
An unconstrained string used as a display name. Limit 250 characters.
A unique string of lowercase characters that is the name of this Service Provider. Limit 64 characters.
An integer that was the Service Provider ID for legacy API use.
A string that is a free-form notes field. Limit 2048 characters.
A string that is the primary phone number of this Service Provider. Limit 250 characters.
A string that is the physical address of this Service Provider. Limit 250 characters.
A string that is the email address of this Service Provider. Limit 250 characters.
Endpoints
/icr/api/service_provider
GET - Retrieve all Service Providers.
POST - Create a new Service Provider.
/icr/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 Subscribers.
Note
These are not administrator accounts.
{
"first_name": "Jane",
"last_name": "Doe",
"display_name": "ExampleSubscriber",
"name": "examplesubscriber",
"notes": "This is an example Subscriber.",
"phone": "5851234321",
"address": "123 Main St",
"email": "jdoe@example.com",
"legacy_subscriber_id": "",
"service_provider_name": "Name"
}
A string that is the first name of a contact for this Subscriber. Limit 250 characters.
A string that is the last name of a contact for this Subscriber. Limit 250 characters.
An unconstrained string used as a display name. Limit 250 characters.
A unique string of lowercase characters that is the name of this Subscriber. Limit 64 characters.
A string that is a free-form notes field. Limit 2048 characters.
A string that is the primary phone number of this Subscriber. Limit 250 characters.
A string that is the physical address of this Subscriber. Limit 250 characters.
A string that is the email address of this Subscriber. Limit 250 characters.
An integer that was the Subscriber ID for legacy API use.
A unique string that is the Service Provider for this Subscriber. Must match an existing Service Provider.
Endpoints
/icr/api/subscriber/{service_provider_name}
GET - Retrieve all Subscribers owned by the specified Service Provider.
POST - Create a new Subscriber.
/icr/api/subscriber/{service_provider_name}/{name}
GET - Retrieve the Subscriber with the specified name.
PUT - Modify the Subscriber if it exists, otherwise create the Subscriber.
DELETE - Archive the specified Subscriber.
The following information is used in the body of a request to create and edit numbers.
{
"timezone": "CST",
"params": "",
"number": "5851239876",
"subscriber_name": "examplesubscriber",
"service_provider_name": "exampleserviceprovider"
}
A unique string that is the time zone for this number.
A JSON object that defines a set of parameters for this number.
A unique string that is this number. This should be a valid phone number. Limit 250 characters.
A unique string that is the name of the Subscriber who uses this number. Must match an existing Subscriber.
A unique string that is the name of the Service Provider for the subscriber who uses this number. Must match an existing Service Provider.
Endpoints
/icr/api/number/{service_provider_name}
GET - Retrieve all numbers owned by the specified Service Provider.
POST - Create a new number owned by the specified Service Provider.
/icr/api/number/{service_provider_name}/{subscriber_name}
GET - Retrieve all numbers owned by the specified Subscriber.
POST - Create a new number owned by the specified Subscriber.
/icr/api/number/{service_provider_name}/{subscriber_name}/{number}
GET - Retrieve the specified number.
PUT - Modify the number if it exists, otherwise create the number.
DELETE - Archive the specified number.
The following information is used in the body of a request to edit settings. The following example uses the default values.
{
"menu_forwarding_configuration_file": "/usr/sipxpress/config/icr-menu-forwarding-configuration.yml",
"routing_engine_uri": "http://niu:{{ application_port_start + 1 }}/routing-engine",
"download_directory": "/var/opt/xpressworkx/app-manager/icr/media/download",
"upload_directory": "/var/opt/xpressworkx/app-manager/icr/media/upload",
"job_log_directory": "/var/opt/xpressworkx/app-manager/icr/media/download",
"default_route_on": "1",
"application_username": "icr_application_manager",
"application_password": "<password>",
"routing_interface_impl": "com.imsworkx.routingEngine.callflow.HttpClient",
"menu_destination": "12345",
"csr_location": "",
"use_contact": true,
branding": {
"imsworkx": {
"color_hue": "202",
"highlight_hue": "198",
"logo": "logo.png",
"label": "Evolve Cellular Inc. ®"
}
},
"restworkx": {
"archive_max_days": "7",
"audit_log_directory": "/var/opt/xpressworkx/app-manager/icr/logs/audit-logs/",
"log_duration": "1"
},
"web_settings": {
"help_page": "http://www.imsworkx.com",
"password_length": "8",
"number_mask": "{+ddd }(ddd) ddd-dddd",
"audio_package": "xpressworkx"
},
"routing_engine": {
"egress_route": "",
"default_no_route_behavior": "404",
"redirect_address": "",
"point_code_format": "ansi",
"sip_routing_prefix": "",
"sip_connection_type": "redirect",
"sip_play_media_on_error": false,
"route_call_timeout": 1,
"calling_number_source": "",
"calling_sources_config": [
{
"source": "hdr.from",
"policy": {
"user_phone_missing_context": null,
"attempt_implicit_user_phone": false,
"heuristic_digits": "longest-digit-substring"
},
"post": []
}
{
"source": "hdr.p_asserted_identity",
"policy": {
"user_phone_missing_context": null,
"attempt_implicit_user_phone": false,
"heuristic_digits": "longest-digit-substring"
},
"post": []
}
],
"called_sources_config": [
{
"source": "hdr.to",
"policy": {
"user_phone_missing_context": null,
"attempt_implicit_user_phone": false,
"heuristic_digits": "as-is"
},
"post": []
},
{
"source": "request_uri",
"policy": {
"user_phone_missing_context": null,
"attempt_implicit_user_phone": false,
"heuristic_digits": "as-is"
},
"post": []
}
],
}
"security": {
"client_cert": null,
"client_key": null,
"ca_bundle": null,
"allow_insecure": false
}
"icr": {
"custom_criteria": false,
"custom_fields": "",
"csv_retention_days": 30,
"strip_prefix_enabled": false,
"strip_prefix": "",
"strip_prefix_min_digits": 0,
"strip_country_code_enabled": false
},
"menu": {
"data": {
"schema_name": "icr",
"schema_version": "<version>",
"table_schema": "routing_engine",
"table_name": "menu"
},
"redirect": {
"schema_name": "icr",
"schema_version": "<version>",
"table_schema": "routing_engine",
"table_name": "menu_redirect"
}
}
The following settings are set automatically during installation and should not need to be changed:
menu_forwarding_configuration_file
routing_engine_uri
download_directory
upload_directory
job_log_directory
application_username
application_password
routing_interface_impl
If true, the host from the Contact header of the INVITE will be used as the egress route. This setting has a service provider override option.
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/icr/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 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. This setting has a service provider override option.
password_length: (Integer) Minimum number of characters allowed in a password. This setting has a service provider override option.
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.
audio_package: (String) The prompt set that will be used in the web UI.
Contains settings used to determine call flow.
egress_route: (String) The host to use when connecting a call to the called party. This setting has a service provider override option.
default_no_route_behavior: (String) The default behavior for SIP calls when no route is found for the call. The options available directly correspond to SIP final response codes. This setting has a service provider override option.
redirect_address: (String) The address a SIP redirect message will be sent. This setting has a service provider override option.
point_code_format: (String: “ansi”, “itu”) The format that point codes will be in.
sip_routing_prefix: (String) A prefix value added to the call during the call processing. This setting has a service provider override option.
sip_connection_type: (String) The type of SIP connection. This setting has a service provider override option.
sip_play_media_on_error: (String) The sounds a subscriber will hear as the called party is answering.
route_call_timeout: (Integer) Number of seconds to wait for a destination before the call times out.
Contains settings related to called number source and calling number source configuration.
source: (String: “hdr.from”, “hdr.p_asserted_identity”, “request_uri”, “hdr.to”, “hdr.diversion”) The source that the called number is pulled from.
policy: Contains policy settings.
user_phone_missing_context: (String) The configured ‘;phone-context=’ value is used if the URI is being treated as a tel-URI and the number is not global and does not contain an existing ‘phone-context’ parameter.
attempt_implicit_user_phone: (Boolean) If true, the user part of the called source will be processed as ‘;user=phone’ even if that is not present.
heuristic_digits: (String: “longest-digit-substring”, “as-is”) ‘Longest Digit Substring’ uses the longest substring of digits 0-9 present in the user part of the SIP URI as the digits. If there are two or more substrings that meet this criteria, the first one is used. ‘As Is’ uses the user part of the SIP URI as the digits.
post: Contains post-processing settings.
strip_prefix: Requires a
prefixproperty with a string. If that string is found to be a prefix of thedigitsproperty of the number object, that prefix is removed, thedigitsproperty is set to the remainder, and theprefixproperty is set on the number object with that prefix. Otherwise, the number object is returned unchanged.extract_substring: Requires a
rangeproperty which is an array of two numbers. These numbers indicate the interval to extract from thedigitsproperty of the number object being processed. The interval includes the first number and excludes the second. Any other parts of thedigitsproperty are discarded.set_cc: Requires a
country_codeproperty which must be a valid country code string. This is set on the number object as thecountry_codeproperty. If the object had acontextproperty, this property is removed.default_cc: Requires a
country_codeproperty which must be a valid country code string. This behaves as forset_cc, unless acountry_codeproperty already exists on the number object.require_digits: When evaluated, an error is generated if the
digitsproperty of the number object contains any non-digit characters. Additionally, whenmin_lengthis specified, if the length of thedigitsproperty is less than the number, an error will be raised.
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.
Note
To enable the service provider override option for any applicable settings, format the setting as follows:
{
"settings": {
"__override__": {
"web_settings": {
"password_length": true
}
}
}
}
Endpoints
/icr/api/settings/
GET - Retrieve the settings for the current user.
PUT - Modify the settings.
The following common responses may be encountered while using the ICR 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 ICR installed, the following message will be seen.
curl -X POST \
-H "Content-Type:application/json" \
<niu-ha>/icr/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 /icr/api/authenticate was not found on this server.</p>
</body></html>
Note
This response is not controlled by the ICR 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":"icr_administrator"}' \
localhost/icr/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: icr_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/icr
< 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": "Intelligent Call Routing",
"short_name": "icr",
"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/icr/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: icr_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/icr
< 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": "Intelligent Call Routing",
"short_name": "icr",
"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/icr/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: icr_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/icr
< 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": "Intelligent Call Routing",
"short_name": "icr",
"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/icr/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: icr_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/icr
< 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": "Intelligent Call Routing",
"short_name": "icr",
"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/icr/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: icr_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/icr
<
* 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/icr/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: icr_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/icr
< 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": "Intelligent Call Routing",
"short_name": "icr",
"author": "IMSWorkX, Inc."
}
}
The above responses can be seen as responses from a stable ICR 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/icr/logs/audit-logs and are named audit-<year>.<month>.<day>.log.