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>/cin/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/cin/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).

{
        "cdr_id": "<string>",
        "start_time": "<timestamp>",
        "end_time": "<timestamp>",
        "additional_data": "<array>",
        "service_provider_name": "<string>",
        "subscriber_name": "<string>",
        "called_party": "<string>",
        "calling_party": "<string>",
        "events": "<string>"
}

Endpoints

/cin/api/cin_cdr

GET - Retrieve all CDRs that match the specified criteria.

/cin/api/cin_cdr/{service_provider}

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

/cin/api/cin_cdr/{service_provider}/{subscriber}

GET - Retrieve the CDRs associated with a particular Subscriber.

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.

Endpoints

/cin/api/administrator/{role_id}

GET - Retrieve all administrators with the specified role.

POST - Create an administrator with the specified role.

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

/cin/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

/cin/api/service_provider

GET - Retrieve all Service Providers.

POST - Create a new Service Provider.

/cin/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.",
        "voicemail": [],
        "service_enabled": true
}

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.

voicemail (optional)

A string that is the voice mail service location for this Subscriber.

service_enabled

A boolean value that determines whether the CIN service is active on this Subscriber’s account.

Endpoints

/cin/api/subscriber/{service_provider_name}

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

POST - Create a new Subscriber.

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

number¶

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

{
        "number": "5851239876",
        "subscriber_name": "examplesubscriber",
        "service_provider_name": "exampleserviceprovider",
        "nickname": "optionalname",
        "ivr_pin": "1111",
        "override_pin": "2222",
        "vip": [],
        "blocked": []
}

number

A unique string that must be a valid phone number. Limit of 250 characters.

subscriber_name

A unique string that is the name of the Subscriber who uses this number. Must match an existing Subscriber.

service_provider_name

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

nickname (optional)

A string that is an optional display name to identify this number. Limit of 250 characters.

ivr_pin (optional)

A string that is the PIN used by this number to log in to the IVR interface. This value must be at least 4 digits.

override_pin (optional)

A string that is the PIN used to allow a caller to complete the call when CIN service is enabled. This value must be at least 4 digits.

vip (optional)

An array of numbers that are on the VIP list associated with this number. Calls from any number defined in this list will always be allowed.

blocked (optional)

An array of numbers that are on the blocked list associated with this number. Calls from any number defined in this list will always be blocked.

Endpoints

/cin/api/number

GET - Retrieve all numbers.

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

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

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

CIN Not Installed¶

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

curl -X POST \
         -H "Content-Type:application/json" \
         <niu-ha>/cin/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 /cin/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":"cin_administrator"}' \
         localhost/cin/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: cin_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cin
< 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": "Call Intercept",
        "short_name": "cin",
        "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": "Call Intercept",
"short_name": "cin",
"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/cin/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: cin_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cin
< 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": "Call Intercept",
        "short_name": "cin",
        "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/cin/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: cin_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cin
< 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": "Call Intercept",
        "short_name": "cin",
        "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/cin/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: cin_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cin
< 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": "Call Intercept",
        "short_name": "cin",
        "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/cin/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: cin_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cin
<
* 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/cin/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: cin_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cin
< 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": "Call Intercept",
        "short_name": "cin",
        "author": "IMSWorkX, Inc."
        }
}

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