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>/ecf/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/ecf/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>",
        "route": "<json>",
        "service_provider_name": "<string>",
        "subscriber_name": "<string>",
        "cdrs": "<array>"
}

Endpoints

/ecf/api/ecf_cdr

GET - Retrieve all CDRs that match the specified criteria.

/ecf/api/ecf_cdr/{service_provider_name}

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

/ecf/api/ecf_cdr/{service_provider_name}/{subscriber_name}

GET - Retrieve the CDRs associated with a particular Subscriber.

/ecf/api/ecf_cdr/{service_provider_name}/{subscriber_name}/{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.

Endpoints

/ecf/api/administrator/{role_id}

GET - Retrieve all administrators with the specified role.

POST - Create an administrator with the specified role.

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

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

/ecf/api/service_provider

GET - Retrieve all Service Providers.

POST - Create a new Service Provider.

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

{
        "service_provider_name": "exampleserviceprovider",
        "name": "examplesubscriber",
        "pin": "1234",
        "timezone": "",
        "call_manager": false,
        "screening": {"active": true, "pin": "2222"},
        "account_lock": false,
        "first_name": "Jane",
        "last_name": "Doe",
        "display_name": "ExampleSubscriber",
        "phone": "5851234321",
        "address": "123 Main St",
        "email": "jdoe@example.com",
        "speed_call_numbers": [],
        "acceptance_lists": [],
        "schedules": [],
        "default_number": "1234567890",
        "params": [],
        "notes": "This is an example Subscriber."
}

service_provider_name

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

name

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

pin

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

timezone (optional)

A string that is the time zone used by the Subscriber to determine call forwarding.

call_manager (optional)

A boolean value that determines whether this Subscriber can access additional features such as creating acceptance lists and forwarding schedules.

screening (optional)

A JSON object defining call screening behavior containing the following parameters:

active: A boolean value that determines whether call screening is active for this Subscriber.

pin: A 4-digit string that a caller must dial to be forwarded.

account_lock (optional)

A boolean value that determines whether this Subscriber account is locked after entering an invalid PIN too many times.

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.

display_name (optional)

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

phone (optional)

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

address (optional)

A string that is the physical address of 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.

speed_call_numbers (optional)

An array of speed call numbers that this Subscriber commonly forwards calls to.

acceptance_lists (optional)

An array of entries that define the acceptance list for this Subscriber, which are numbers that will always be forwarded regardless of the applied routing rules, containing the following parameters:

entries: An array numbers that are in the caller acceptance list.

active: A boolean value that determines whether the call acceptance list is active for this Subscriber.

schedules (optional)

An array of entries that define the forwarding schedule for this Subscriber containing the following parameters:

entries:

start: A string that is the start time for the schedule, in HH:MM.

end: A string that is the end time for the schedule, in HH:MM.

day: A string that are the days of the week this schedule applies to. Accepted values are MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, and SUNDAY.

number: A string that is the number all calls are forwarded to during the time that this schedule is active.

active: A boolean value that determines whether the forwarding schedule is active for this Subscriber.

default_number (optional)

A string that is the number calls will be forwarded to when no plans are active.

params (optional)

A JSON object of always active routing parameters for this Subscriber.

notes (optional)

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

Endpoints

/ecf/api/subscriber/{service_provider_name}

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

POST - Create a new Subscriber.

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

ECF Not Installed¶

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

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

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