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>/dnd/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/dnd/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>",
        "called_number": "<string>",
        "calling_number": "<string>",
        "service_provider_name": "<string>",
        "subscriber_name": "<string>",
        "events": "<string>"
}

Endpoints

/dnd/api/dnd_cdr

GET - Retrieve all CDRs that match the specified criteria.

/dnd/api/dnd_cdr/{service_provider}

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

/dnd/api/dnd_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.

• add_permission_group_entries

• alter_permission_group

• alter_platform_owner_user

• alter_service_provider_user

• alter_subscriber_user

• create_permission_group

• default:platform_owner

• default:service_provider

• list_permission_group_entries

• list_permission_groups

• dnd_default:dnd_application_provisioning

• dnd_default:dnd_platform_owner_administration

• dnd_default:dnd_platform_owner_platform_administration

• dnd_default:dnd_platform_owner_provisioning

• dnd_default:dnd_platform_owner_user_administration

• dnd_default:dnd_platform_owner_views

• dnd_default:dnd_service_provider_platform_administration

• dnd_default:dnd_service_provider_provisioning

• dnd_default:dnd_service_provider_user_administration

• dnd_default:dnd_service_provider_views

• dnd_default:dnd_subscriber_administration

• dnd_default:dnd_subscriber_platform_administration

• dnd_default:dnd_subscriber_provisioning

• dnd_default:dnd_subscriber_user_administration

• dnd_default:dnd_subscriber_views

• dnd_view_screening_rule

• remove_permission_group

• remove_permission_group_entries

• screening_engine_view_screening_treatment

• view_permission_group

• view_service_provider

• view_subscriber

• view_subscriber_user

• default:subscriber

Endpoints

/dnd/api/administrator/{role_id}

GET - Retrieve all administrators with the specified role.

POST - Create an administrator with the specified role.

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

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

/dnd/api/service_provider

GET - Retrieve all Service Providers.

POST - Create a new Service Provider.

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

/dnd/api/subscriber/{service_provider_name}

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

POST - Create a new Subscriber.

/dnd/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",
        "timezone": <string>,
        "ivr_pin": "1111",
        "override_pin": "2222",
        "service_enabled": true,
        "dnd_time_period": null,
        "schedule_enabled": true,
        "schedule_source": "1234567",
        "priority_list_source": "1235467",
        "priority_list": [],
        "schedule": [],
        "rejection_message": "5442",
        "voicemail_number": <string>,
        "voicemail_location": <string>
}

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.

timezone

A string that is the time zone for this number.

ivr_pin

A string that is the PIN used by this number to log in to the IVR interface.

override_pin

A string that is the PIN used to allow a caller to complete the call when DND service is enabled.

service_enabled (optional)

A boolean value that determines whether the DND service is enabled for this number. The default value is true.

dnd_time_period (optional)

A string that defines the length of time to enable the DND service for. Set this value to null for no time limit.

schedule_enabled (optional)

A boolean value that determines whether the schedule is enabled for this number.

schedule_source (optional)

A string that is the number that this number is copying its schedule from.

priority_list_source (optional)

A string that is the number that this number is copying its caller priority list from.

priority_list (optional)

An array that defines the numbers on the caller priority list for this number.

schedule (optional)

An array of the preprogrammed schedule to determine when the DND service is active.

rejection_message (optional)

A string that is the rejection message to play when a call to this number is blocked. The default value is “5442”. Accepted values are “5442”, “5443”, and “5444”.

voicemail_number (optional)

A string that is the number for the voice mail service for this number.

voicemail_location (optional)

A string that is the location of the voice mailbox for this number.

Endpoints

/dnd/api/number

GET - Retrieve all numbers.

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

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

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

DND Not Installed¶

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

curl -X POST \
         -H "Content-Type:application/json" \
         <niu-ha>/dnd/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 /dnd/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":"dnd_administrator"}' \
         localhost/dnd/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: dnd_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/dnd
< 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": "Do Not Disturb",
        "short_name": "dnd",
        "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": "Do Not Disturb",
"short_name": "dnd",
"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/dnd/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: dnd_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/dnd
< 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": "Do Not Disturb",
        "short_name": "dnd",
        "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/dnd/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: dnd_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/dnd
< 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": "Do Not Disturb",
        "short_name": "dnd",
        "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/dnd/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: dnd_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/dnd
< 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": "Do Not Disturb",
        "short_name": "dnd",
        "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/dnd/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: dnd_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/dnd
<
* 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/dnd/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: dnd_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/dnd
< 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": "Do Not Disturb",
        "short_name": "dnd",
        "author": "IMSWorkX, Inc."
        }
}

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