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>/easy0/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/easy0/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>",
        "switch_point_code": "<string>",
        "calling_number": "<string>",
        "start_time": "<timestamp>",
        "end_time": "<timestamp>",
        "service_provider_name": "<string>",
        "route": "<object>",
        "cdrs": "<array>"
}

Endpoints

/easy0/api/easy0_cdr

GET - Retrieve all CDRs that match the specified criteria.

/easy0/api/easy0_cdr/{service_provider}

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

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>

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.

• easy0_platform_administrator_provision

• easy0_platform_administrator_view

• easy0_platform_administrator_edit

• easy0_service_provider_provision

• easy0_service_provider_view

• easy0_service_provider_edit

• easy0_service_provision

• easy0_service_view

• easy0_service_edit

• easy0_call_pattern_provision

• easy0_call_pattern_view

• easy0_call_pattern_edit

• easy0_service_administrator_provision

• easy0_service_administrator_view

• easy0_service_administrator_edit

• easy0_settings_view

• easy0_settings_edit

• easy0_statistics_view

Endpoints

/easy0/api/administrator/{role_id}

GET - Retrieve all administrators with the specified role.

POST - Create an administrator with the specified role.

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

/easy0/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",
        "point_codes": "[]",
        "via": "[]",
        "first_name": "John",
        "last_name": "Smith",
        "email": "jsmith@example.com",
        "address": "123 Main St",
        "phone": "5851231234",
        "timezone": "gmt",
        "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.

point_codes (optional)

An array of strings that are the point codes associated with this Service Provider.

via (optional)

An array of strings that are the SIP Via headers associated with this Service Provider.

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.

timezone

A string that is the time zone used by this Service Provider.

notes (optional)

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

Endpoints

/easy0/api/service_provider

GET - Retrieve all Service Providers.

POST - Create a new Service Provider.

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

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

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

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

{
        "name": "examplecallplan",
        "display_name": "Example",
        "rules": "[]",
        "priority": "1",
        "service_provider_name": "exampleserviceprovider"
}

name

A string that is the name of this call plan. This value must be at least 6 characters and no more than 64 characters.

display_name (optional)

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

rules (optional)

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

priority

An integer that is the priority of this call plan. Call plans are evaluated by the routing engine in ascending order.

service_provider_name

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

Endpoints

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

/easy0/api/call_plan/{service_provider_name}/{name}

GET - Retrieve the specified call plan.

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

DELETE - Archive the specified call plan.

service_key¶

The following information is used in the body of a request to create and edit Caller Name Delivery (CNAM) service keys. CNAM is used to provide name identification of the calling party, which is displayed in the Caller ID information.

{
        "type_of_digits": "ROUTING_NUMBER",
        "nature_of_number": "NATIONAL_NUM_PRES_ALLOWED",
        "numbering_plan": "UNKNOWN_NOT_APPLICABLE",
        "encoding_scheme": "IA5",
        "digits": "1234",
        "service_provider_name": "serviceprovider",
        "priority": "2",
        "id": "1"
}

type_of_digits

A string that defines what the digits represent. Accepted values are:

• NOT_USED

• CALLED_PARTY_NUM_DIALED

• CALLING_PARTY_NUM_ANI

• CALLER_INTERACTION

• ROUTING_NUMBER

• BILLING_NUMBER

• DESTINATION_NUMBER

• LATA

• CARRIER

• LAST_CALLING_PARTY

• LAST_PARTY_CALLED

• CALLING_DIRECTORY_NUMBER

• VMSR_IDENTIFIER

• ORIGINAL_CALLED_NUMBER

• REDIRECTING_NUMBER

• CONNECTED_NUMBER

nature_of_number

A string that defines whether the number is national or international and whether number presentation is allowed. Accepted values are:

• NATIONAL_NUM_PRES_ALLOWED

• NATIONAL_NUM_PRES_RESTRICTED

• INTERNATIONAL_NUM_PRES_ALLOWED

• INTERNATIONAL_NUM_PRES_RESTRICTED

numbering_plan

A string that is the type of numbering plan to use. Accepted values are:

• UNKNOWN_NOT_APPLICABLE

• ISDN_NUMBERING_PLAN

• TELEPHONY_NUMBERING_PLAN

• DATA_NUMBERING_PLAN

• TELEX_NUMBERING_PLAN

• MARITIME_MOBILE_NUMBERING_PLAN

• LAND_MOBILE_NUMBERING_PLAN

• PRIVATE_NUMBERING_PLAN

encoding_scheme

A string that is the type of encoding to use. Accepted values are “BCD” or “IA5”.

digits

A string that is the digits for this service key.

service_provider_name

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

priority

An integer that is the priority of this service key. Service keys are added in ascending order.

id

An integer that is the autoincrementing ID for this service key.

Endpoints

/easy0/api/service_key/{service_provider_name}

GET - Retrieve all service keys for the specified Service Provider.

POST - Create a new service key for the specified Service Provider.

/easy0/api/service_key/{service_provider_name}/{id}

GET - Retrieve the specified service key.

PUT - Modify the service key if is exists, otherwise create the service key.

DELETE - Archive the specified service key.

Easy 0 Not Installed¶

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

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

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