Application Programming Interface¶

Table Queries¶

Tables are lists of objects that can be accessed and modified to affect multiple objects at once.

URI Format: <niu-ha>/n11/api/<object>?<optionalparameters>

Table queries may contain the following parameters, all of which are optional:

{
        "sort": {},
        "search": {},
        "like": {},
        "sort_function": {},
        "icontains": {},
        "limit": {},
        "offset": {}
}

sort

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.

search

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.

like

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.

sort_function

A string that overrides ‘sort’. Pass in ::{:}*.

icontains

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.

limit

An integer that is the number of records to retrieve at a time. The default value is 10.

offset

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/n11/api/cdr"?offset=0&limit=25&sort=column:asc

Call Detail Records¶

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>",
        "routing_id": "<integer>",
        "service_provider_name": "<string>",
        "subscriber_name": "<string>",
        "cdrs": "<array>"
}

Endpoints

/n11/api/n11_cdr

GET - Retrieve all CDRs that match the specified criteria.

/n11/api/n11_cdr/{service_provider}

GET - Retrieve the CDRs associated with a particular Service Provider.

/n11/api/n11_cdr/{service_provider}/{subscriber}

GET - Retrieve the CDRs associated with a particular Subscriber.

/n11/api/n11_cdr/{service_provider}/{subscriber}/{original_called_number}

GET - Retrieve the CDRs associated with a particular originally called number.

administrator¶

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"
}

username

A unique string that is the user name for this user. Limit of 64 characters. Can contain only lowercase characters, numbers, or underscores.

role_id

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>

first_name (optional)

A string that is the first name of this user. Limit of 250 characters.

last_name (optional)

A string that is the last name of this user. Limit of 250 characters.

email (optional)

A string that is the email address for this user. Limit of 250 characters.

permissions (optional)

An array of permission groups that this user is a member of. Permissions are dependent on the specified role_id of the created administrator.

• n11_platform_administrator_provision

• n11_platform_administrator_view

• n11_platform_administrator_edit

• n11_service_provider_provision

• n11_service_provider_view

• n11_service_provider_edit

• n11_service_provision

• n11_service_view

• n11_service_edit

• n11_call_pattern_provision

• n11_call_pattern_view

• n11_call_pattern_edit

• n11_service_administrator_provision

• n11_service_administrator_view

• n11_service_administrator_edit

• n11_settings_view

• n11_settings_edit

• n11_statistics_view

Endpoints

/n11/api/administrator/{role_id}

GET - Retrieve all administrators with the specified role.

POST - Create an administrator with the specified role.

/n11/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.

/n11/api/administrator/{role_id}/{username}/reset

POST - Reset this user’s password, returning a reset token.

service_provider¶

The following information is used in the body of a request to create and edit different Service Providers.

{
        "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",
}

name

A unique string that is the name of this Service Provider. Limit of 64 characters.

display_name (optional)

An unconstrained string used as a display name. Limit of 250 characters.

first_name (optional)

A string that is the first name of a contact for this Service Provider. Limit of 250 characters.

last_name (optional)

A string that is the last name of a contact for this Service Provider. Limit of 250 characters.

email (optional)

A string that is the email address of this Service Provider, where notifications and password reset requests will be sent. Limit of 250 characters.

address (optional)

A string that is the physical address of this Service Provider. Limit of 250 characters.

phone (optional)

A string that is the primary phone number of this Service Provider. Limit of 250 characters.

notes (optional)

A string that is a free-form notes field. Limit of 2048 characters.

Endpoints

/n11/api/service_provider

GET - Retrieve all Service Providers.

POST - Create a new Service Provider.

/n11/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.

subscriber¶

The following information is used in the body of a request to create and edit different Subscribers.

{
        "name": "examplesubscriber",
        "display_name": "ExampleSubscriber",
        "service_provider_name": "exampleserviceprovider",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jdoe@example.com",
        "address": "123 Main St",
        "phone": "5851234321",
        "notes": "This is an example Subscriber.",
}

name

A unique string that is the name of this Subscriber. Limit of 64 characters.

display_name (optional)

An unconstrained string used as a display name. Limit of 250 characters.

service_provider_name

A unique string that is the name of the Service Provider for this Subscriber. Must match an existing Service Provider.

first_name (optional)

A string that is the first name of a contact for this Subscriber. Limit of 250 characters.

last_name (optional)

A string that is the last name of a contact for this Subscriber. Limit of 250 characters.

email (optional)

A string that is the email address of this Subscriber, where notifications and password reset requests will be sent. Limit of 250 characters.

address (optional)

A string that is the physical address of this Subscriber. Limit of 250 characters.

phone (optional)

A string that is the primary phone number of this Subscriber. Limit of 250 characters.

notes (optional)

A string that is a free-form notes field. Limit of 2048 characters.

Endpoints

/n11/api/subscriber/{service_provider_name}

GET - Retrieve all Subscribers owned by the specified Service Provider.

POST - Create a new Subscriber.

/n11/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.

audio¶

The following information is used in the body of a request to create and edit audio files.

{
        "file": "example.wav",
        "location": "/tmp/audio",
        "server": "lab-niu01.lab.redcom.com",
        "label": "example",
        "service_provider_name": "exampleserviceprovider"
}

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$”.

label (optional)

A string that is a nickname or label to help identify this audio file.

location

A string that is the exact location of the audio file.

server

A string that is the server (NIU or secondary) where the audio file is stored.

service_provider_name

A unique string that is the Service Provider who uses this audio file. Must match an existing Service Provider.

Endpoints

/n11/api/audio/{service_provider_name}

GET - Retrieve all audio files for the specified Service Provider.

POST - Create a new audio file for the specified Service Provider.

/n11/api/audio/{service_provider_name}/{file}

GET - Retrieve the specified audio file.

PUT - Modify the file if it exists, otherwise create the file.

DELETE - Archive the specified audio file.

call_plan¶

The following information is used in the body of a request to create and edit call plans.

{
        "n11": "311",
        "service_provider_name": "exampleserviceprovider",
        "subscriber_name": "examplesubscriber",
        "timezone": "gmt",
        "rules": "[]"
}

n11

A string that is the number this call plan routes calls to based on geographic location. This value must be three numbers. The first number must be 0-9 and the second and third numbers must be 1 or 8.

service_provider_name

A unique string that is the Service Provider who owns this call plan. Must match an existing Service Provider.

subscriber_name

A unique string that is the Subscriber who uses this call plan. Must match an existing Subscriber.

timezone

A string that is the time zone used by the call plan to determine call routing.

rules (optional)

An array of additional routing rules applied to this call plan.

Endpoints

/n11/api/call_plan/{service_provider_name}

GET - Retrieve all call plans for the specified Service Provider.

POST - Create a new call plan for the specified Service Provider.

/n11/api/call_plan/{service_provider_name}/{subscriber_name}

GET - Retrieve all call plans for the specified Subscriber.

POST - Create a new call plan for the specified Subscriber.

/n11/api/call_plan/{service_provider_name}/{subscriber_name}/{n11}

GET - Retrieve the specified call plan.

PUT - Modify the call plan if it exists, otherwise create the call plan.

DELETE - Archive the specified call plan.

/n11/api/call_plan/{service_provider_name}/{subscriber_name}/{n11}/activate

POST - Activate the specified call plan.

N11 Not Installed¶

When making an API call to a server that does not have N11 installed, the following message will be seen.

curl -X POST \
         -H "Content-Type:application/json" \
         <niu-ha>/n11/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 /n11/api/authenticate was not found on this server.</p>
</body></html>

Incorrect Log In¶

When logging in to the API with incorrect or missing information, the following message will be seen.

curl -X POST \
         -d '{"username":"n11_administrator"}' \
         localhost/n11/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: n11_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/n11
< 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": "N11 Abbreviated Dialing",
        "short_name": "n11",
        "author": "IMSWorkX, Inc."
        }
}

Unauthorized Action¶

When attempting to perform an action without the proper user permissions, such as a Service Provider creating another Service Provider, the following message will be seen.

{"meta": {
        "scope": "exception",
        "message": "You do not have permission to perform that operation.",
        "code": 403,
        "encoding": "ascii"},
"jsonapi": {"version": "1.2-11",
"name": "N11 Abbreviated Dialing",
"short_name": "n11",
"author": "IMSWorkX, Inc."}
}

Not Provisioned¶

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/n11/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: n11_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/n11
< 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": "N11 Abbreviated Dialing",
        "short_name": "n11",
        "author": "IMSWorkX, Inc."
        }
}

Object Does Not Exist¶

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/n11/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: n11_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/n11
< 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": "N11 Abbreviated Dialing",
        "short_name": "n11",
        "author": "IMSWorkX, Inc."
        }
}

Required Field Missing¶

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/n11/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: n11_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/n11
< 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": "N11 Abbreviated Dialing",
        "short_name": "n11",
        "author": "IMSWorkX, Inc."
        }
}

No Method at Endpoint¶

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/n11/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: n11_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/n11
<
* Connection #0 to host localhost left intact
* Closing connection #0

Successful API Call¶

When making a successful API call, the following message will be seen.

curl -X GET \
        -H "Authorization: Basic <secure-access-token>" \
        localhost/n11/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: n11_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/n11
< 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": "N11 Abbreviated Dialing",
        "short_name": "n11",
        "author": "IMSWorkX, Inc."
        }
}

The above responses can be seen as responses from a stable N11 API. If you encounter other undocumented API errors, please contact support@imsworkx.com with the API call and output.