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
DELETE: Delete a resource
POST to <base_uri>/authenticate with the username and password parameters.
The response will contain the following:
{ "token": "<secure-access-token>" }
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>
GET /icr/api/service_provider/IMSWorkX
Which would provide a 200 message if the object specified exists:
{
"meta": {
"scope": "success",
"code": "200",
"records_page_size": "request.parameters.limit",
"archive": "request.parameters.archive",
"records_page_offset": "request.parameters.offset"
},
"data": [
{
"scope": "service_provider",
"meta": {
"modified_by": "< string >",
"modified": "< datetime >",
"created_by": "< string >",
"created": "< datetime >"
},
"attributes": {
"first_name": "< string >",
"last_name": "< string >",
"display_name": "< string >",
"name": "< single >",
"legacy_service_provider_id": "< int >",
"notes": "< string >",
"phone": "< string >",
"address": "< string >",
"email": "< string >"
}
}
]
}
Or would provide a 404 error if the specified object does not exist:
{
"meta": {
"scope": "error",
"message": "The record requested was not found.",
"code": 404
}
}
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:
offset = <offset> The offset to start from.
limit = <limit> The maximum number of records to return.
search = <column>:<value> Denotes the value to search for. This is an exact match.
search = <column>:<value1>:<value2> Denotes the values to search for. This is a range search.
like = “string” Denotes a fuzzy search of the string.
sort = <column>:<asc|desc> Indicates the direction in which to sort a column.
For example:
?offset=0&limit=25&sort=column:asc
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:
POST /icr/api/service_provider
{"name": "IMSWorkX", "first_name": "Jane", "last_name": "Doe"...}
Which adds 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:
PUT /icr/api/service_provider/IMSWorkX
{"first_name": "John", "last_name": "Smith"}
Which changes the name from Jane Doe to John Smith.
{
"body": {
"username": {
"pkey": true,
"required": true,
"type": "single",
"description": "The username of this user.",
"ref": "auth_user.username"
}
"first_name": {
"required": false,
"type": "string",
"description": "The first name of this user."
}
"last_name": {
"required": false,
"type": "string",
"description": "The last name of this user."
}
"role_id": {
"pkey": true,
"required": true,
"type": "single",
"description": "The role id of this user.
"ref": "auth_user.role_id"
}
"email": {
"required": false,
"type": "string",
"description": "An e-mail address at which to reach this user."
}
"permissions": {
"required": false,
"type": "array",
"description": "An array of permission groups that this user is a member of."
}
}
}
{
"body": {
"label": {
"required": false,
"type": "string"
"description": "A label to help identify this file."
}
"location": {
"required": true,
"type": "string"
"description": "The exact location of the destination file."
}
"file": {
"regex match": "^.*?.wav$",
"required": true,
"type": "string"
"description": "The file name.",
"pkey": true,
}
"server": {
"required": true,
"type": "string"
"description": "The server (niu or secondary) that has the file."
}
"service_provider_name": {
"type": "single"
"required": true,
"ref": "service_provider.name",
"description": "The name of the service provider attached to this file.",
"pkey": true,
}
}
}
Note
The “location” parameter must point to a path that actually exists on each Application Server. To upload audio, use the web UI.
{
"body": {
"far_end_pickup_destination_type": {
"default": "NONE",
"accepts": "[u'NONE', u'SIP', u'NUMBER', u'TRUNK', u'TRUNK-OUTPULSE']"
"required": false,
"type": "string",
"description": "The type of far end pickup destination.",
}
"display_name": {
"required": false,
"type": "string",
"description": "The display name for this call plan."
}
"name": {
"pkey": true,
"required": true,
"type": "string",
"description": "The name for this call plan."
}
"subscriber_name": {
"type": "single",
"required": true,
"ref": "subscriber.name",
"description": "The name of the subscriber this label is under.",
"pkey": true,
}
"rules": {
"default": "[]"
"required": false,
"type": "array",
"description": "Rules for a call plan. See object description for syntax."
}
"far_end_pickup_destination_values": {
"default": "[]"
"required": false,
"type": "json",
"description": "The values for tne far end destination."
}
"service_provider_name": {
"type": "single",
"required": true,
"ref": "subscriber.service_provider_name",
"description": "The name of the service provider this label is under.",
"pkey": true
}
}
}
{
"body": {
"description": {
"required": false,
"type": "string",
"description": "The call destination constraint description."
}
"value": {
"required": true,
"type": "string",
"description": "The call destination constraint value in regex format."
}
"label": {
"pkey": true,
"type": "string",
"description": "The call destination constraint label."
}
"type": {
"accepts": "[u'REQUIRE', u'BLOCK']"
"required": false,
"type": "string",
"description": "Either require or block the call destination constraint."
}
"service_provider_name": {
"pkey": true,
"ref": "service_provider.name",
"type": "single",
"description": "The service provider name."
}
}
}
{
"body": {
"parameters": {
"required": false,
"type": "json",
"description": "Any advanced parameters associated with this destination"
}
"destination_value": {
"required": true,
"type": "array",
"description": "The destination to route calls to"
}
"label": {
"required": true,
"type": "string",
"description": "The label to ascribe to the item"
}
"service_provider_name": {
"type": "string",
"required": true,
"ref": "subscriber.service_provider_name",
"description": "The name of the service provider this label is under.",
"pkey": true
}
"subscriber_name": {
"type": "single",
"required": true,
"ref": "subscriber.name",
"description": "The name of the subscriber this label is under.",
"pkey": true
}
"destination_type": {
"required": true,
"type": "string",
"description": "Type of the destination value"
}
"type": {
"required": true,
"type": "string",
"description": "The type of the item being labeled"
}
}
}
{
"body": {
"called_number
"default": "*",
"regex_match": "^[0-9xX]+$",
"required": false,
"type": "string",
"maxlength": "50",
}
"switch_point_code": {
"maxval": "24BIT_MAX",
"required": false,
"type": "number"
}
"via": {
"required": false,
"type": "string",
"maxlength": "1024",
}
"name": {
"required": true,
"type": "string",
"description": "The name of this routeable.",
"maxlength": "50"
}
"parameters": {
"required": false,
"type": "jsonb"
}
"timezone_key": {
"required": true,
"type": "string",
"maxlength": "50",
}
"calling_number": {
"minlength": "10",
"required": false,
"type": "string",
"regex_match": "^[0-9xX]+$",
"maxlength": "50"
}
"geo_routing": {
"default": "0",
"required": false,
"type": "number"
}
}
}
{
"body": {
"call_plan_name: {
"pkey": true
"ref": "call_plan.name",
"description": "The call plan name to tie this routing entry to.",
"type": "single"
}
"number: {
"pkey": true
"ref": "number.number",
"description": "The number for this routing entry.",
"type": "single"
}
"priority: {
"default": "0",
"required": false,
"type": "int",
"description": "The priority for this call plan. Lower numbers are evaluated first."
}
"call_plan_subscriber_name: {
"pkey": true
"ref": "call_plan.subscriber_name",
"description": "The subscriber name.",
"type": "single"
}
"call_plan_service_provider_name: {
"pkey": true
"ref": "call_plan.service_provider_name",
"description": "The service provider name.",
"type": "single"
}
}
}
{
"body": {
"first_name": {
"required": false,
"type": "string",
"description": "The first name of a contact for this service provider."
}
"last_name": {
"required": false,
"type": "string",
"description": "The last name of a contact for this service provider."
}
"display_name": {
"required": false,
"type": "string",
"description": "A name to display. This is unconstrained."
}
"name": {
"type": "single",
"required": true,
"ref": "auth_service_provider.name",
"description": "The name of this service provider.",
"pkey": true
}
"legacy_service_provider_id" {
"required": false,
"type": "int",
"description": "Service Provider ID for legacy API use"
}
"notes": {
"required": false,
"type": "string",
"description": "A freeform notes field for CSRs.",
"maxlength": 2048
}
"phone": {
"required": false,
"type": "string",
"description": "The phone number of a contact for this service provider. This number is not provisioned into the service."
}
"address": {
"required": false,
"type": "string",
"description": "The address for this service provider. For actuarial use only - does not affect the application."
}
"email": {
"required": false,
"type": "string",
"description": "An e-mail address to reach this service provider at. For actuarial use only."
}
}
}
{
"body": {
"first_name": {
"required": false,
"type": "string",
"description": "The first name of a contact for this subscriber."
},
"last_name": {
"required": false,
"type": "string",
"description": "The last name of a contact for this subscriber."
},
"display_name": {
"required": false,
"type": "string",
"description": "A name to display. This is unconstrained."
},
"name": {
"pkey": true,
"ref": "auth_subscriber.name",
"description": "The name of this subscriber.",
"type": "single"
},
"notes": {
"required": false,
"type": "string",
"description": "A freeform notes field for CSRs.",
"maxlength": 2048
},
"phone": {
"required": false,
"type": "string",
"description": "The phone number of a contact for this subscriber. This number is not provisioned into the service."
},
"legacy_subscriber_id" {
"required": false,
"type": "int",
"description": "Subscriber ID for legacy API use"
}
"address": {
"required": false,
"type": "string",
"description": "The address for this subscriber. For actuarial use only - does not affect the application."
},
"email": {
"required": false,
"type": "string",
"description": "An e-mail address to reach this service provider at. For actuarial use only."
}
"service_provider_name": {
"type": "single",
"required": true,
"ref": "auth_subscriber.service_provider_name",
"description": "The name of the service provider this subscriber is under.",
"pkey": true
}
}
}
{
"body": {
"name": {
"required": true,
"type": "string",
}
"utc_offset_minutes": {
"required": true,
"type": "number",
}
"utc_offset_hours": {
"required": true,
"type": "number",
}
"dst_savings": {
"required": true,
"type": "number",
}
"key": {
"pkey": true,
"required": true,
"type": "string",
}
}
}
{
"body": {
"subscriber_name": {
"type": "single",
"required": true,
"ref": "subscriber.name"
}
"number": {
"ref": "routeable.called_number",
"required": true,
"type": "single",
"pkey": true
}
"params": {
"required": false,
"type": "json",
"description": "A set of parameters for this number."
}
"timezone": {
"ref": "timezone.key",
"required": true,
"type": "single"
}
"service_provider_name": {
"type": "single",
"required": true,
"ref": "subscriber.service_provider_name"
}
}
}
APIPostValueError: Returns an HTTP 400 response code and is raised when bad or malformed data is provided in a POST request to an API call. For example:
{
"code": 400, // The HTTP status code returned
"expected": string | object, // A string or object representation of the expected data
"post": string | object, // The original post data
"message": string // The error message, describes why the data was bad if possible
}
APIQueryValueError: Returns an HTTP 400 response code and is raised when a bad or malformed query is provided in a GET request to an API call. For example:
{
"code": 400, // The HTTP status code returned
"expected": string | object, // A string or object representation of the expected data
"query": string | object, // The original query
"message": string // The error messages, describes what went wrong
}
ConstraintViolation: Returns an HTTP 400 response code and is raised when a data constraint is violated such as when adding a subscriber with a number that is being used by another subscriber. For example:
{
"code": 400, // The HTTP status code returned
"type": string, // The type of constraint violated: check | foreign key | unique ... etc.
"field": string, // The field of the object that violated the constraint
"message": string // The error message
}
Unauthorized: Returns an HTTP 401 response code and is raised when a resources request or POST is not authorized. For example:
{
"code": 401, // The HTTP status code returned
"message": "invalid access token"
}
ResourceNotFound: Returns an HTTP 404 response code and is raised when a resource is not found. For example:
{
"code": 404, // The HTTP status code returned
"message": "resource not found"
}
NotImplemented: Returns an HTTP 501 response code and is raised when an API call is made to an unimplemented feature. For example:
{
"code": 501, // The HTTP status code returned
"message": "The request provided calls into an unimplemented API feature"
}
ScopeException: returns an HTTP 500 response code, raised when an attempt to access or modify an object does not contain the correct scope information. For example:
{
"code": 500, // The HTTP status code returned
"message": "Object out of scope"
}
Exception: Returns an HTTP 500 response code and is raised when an unknown error occurs. For example:
{
"code": 500, // The HTTP status code returned
"message": string // The Exception message
}
Audit logs are automatically generated every day and stored as a CSV file. The location of these can be configured and changed at any time.
The xpressworkx-log-reader can be used to view logs including audit logs. For information about the commands used in the xpressworkx-log-reader, press h to view helpful information.