This RESTful API provides the building blocks that developers need to programmatically integrate CC with other network elements and systems. The API works over HTTP or HTTPS.
Individual objects that can be manipulated through the API include CC administrators, service providers, and more. This chapter is a developer reference for connecting a currently used system to CC.
The API is available at https://<NIU or HA address>/cc/api.
Note
For more information about JSON, see http://json.org/ .
The following shows the base URI and the format used by the API:
Base URI: <niu-ha>/cc/api
Where niu-ha is the host address of the primary NIU.
Following the base URI, the scope and scope ID are added to show which role the actions are to be completed as.
URI Format: /<object>
Many objects will use the following URI: /<object>/<service_provider>/<subscriber>
The API uses the following methods:
GET: Access a resource
PUT: Create or modify a resource
POST: Create a resource
Note
The POST method can be used to import and export data. For more information, see Provisioning.
DELETE: Delete a resource
Note
The DELETE method can be used to archive, restore, and purge data. For more information, see Archiving, Restoring, and Purging Data.
POST to <base_uri>/authenticate with the username and password parameters.
For example:
curl -X POST \
-H "Content-Type:application/json" \
<niu-ha>/cc/api/authenticate \
-d '{"username":"<username>","password":"<password>"}'
The response will contain the following:
"data": [
{"token": "<secure-access-token>"}
],
"jsonapi": {"version": "1.7-6",
"name": "Calling Card",
"short_name": "cc",
"author": "IMSWorkX, Inc."}}
The secure access token must be passed back as the value of the Authorization header. For example:
Authorization: Basic <secure-access-token>
Note
Tokens expire after 24 hours.
URI Format: <niu-ha>/cc/api/<object>/<object-id>
curl -X GET \
-H "Content-Type:application/json" \
-H "Authorization:Basic <secure-access-token>" \
"http://localhost/cc/api/service_provider/IMSWorkX"
This GET command will provide a 200 message if the specified object exists:
{
"meta": {
"scope": "success",
"code": "200",
"records_page_size": "request.parameters.limit",
"archive": "request.parameters.archive",
"records_page_offset": "request.parameters.offset"
},
"data": [
{
"scope": "number",
"meta": {
"modified_by": "<string>",
"modified": "<datetime>",
"created_by": "<string>",
"created": "<datetime>"
},
"attributes": {
"rules": "<array>",
"timezone": "<string>",
"number": "<string>",
"subscriber_name": "<string>"
}
}
]
}
Tables are lists of objects that can be accessed and modified to affect multiple objects at once.
URI Format: <niu-ha>/cc/api/<object>?<optionalparameters>
Table queries may contain the following parameters, all of which are optional:
{
"sort": {},
"search": {},
"like": {},
"sort_function": {},
"icontains": {},
"limit": {},
"offset": {}
}
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.
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.
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.
A string that overrides ‘sort’. Pass in ::{:}*.
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.
An integer that is the number of records to retrieve at a time. The default value is 10.
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/cc/api/cdr"?offset=0&limit=25&sort=column:asc
The following information is returned after a request to retrieve Call Detail Records (CDRs).
{
"access_number": "<string>",
"calling_number": "<string>",
"start_time": "<datetime>",
"end_time": "<datetime>",
"account_number": "<string>",
"charge_number": "<string>",
"serial_number": "<string>",
"product_offering_type": "<string>",
"product_offering_name": "<string>",
"service_provider_name": "<string>",
"rates": "<json>",
"event": "<json>"
}
Endpoints
/cc/api/cc_cdr
GET - Retrieve all CDRs.
/cc/api/cc_cdr/{service_provider_name}
GET - Retrieve the CDR associated with the specified Service Provider.
Use the POST command without specifying an object ID to create an object. At this time, the object will be given an object ID that can be modified later.
For example:
curl -X POST \
-H "Content-Type:application/json" \
-H "Authorization:Basic <secure-access-token>" \
<ha_address>/cc/api/service_provider -d \
'{"name": "IMSWorkX", "first_name": "Jane", "last_name": "Doe"...}'
This example POST command will add a new Service Provider named IMSWorkX.
When the PUT command is used and the object ID is included in the command, the object is modified.
For example:
curl -X PUT \
-H "Content-Type:application/json" \
-H "Authorization:Basic <secure-access-token>" \
<ha_address>/cc/api/service_provider/IMSWorkX -d \
'{"first_name": "John", "last_name": "Smith"}'
This example PUT command will change the name of the Service Provider from Jane Doe to John Smith.
The following information is used in the body of a request to create and edit different access numbers.
{
"number": "5555555555",
"language": "eng",
"first_greeting": "hello.wav",
"play_language_selection": true,
"csr_uri": "CSR@CustomerService.com",
"service_provider_name": "exampleserviceprovider",
"access_number_screening_entries": "[]"
}
A string that is the access number used to call into the system.
A string that determines the language of the initial greeting for the access number. The default value is “eng”, and the other accepted value is “thai”.
A string that is the audio file that first plays after this access number is dialed.
A boolean value that determines if the language selection prompt is played. The default value is “true”.
A string that is the location to redirect calls to customer service for this access number.
A unique string that is the name of the Service Provider using this access number. Must match an existing Service Provider.
An array of objects containing the numbers to screen and the type of screening to apply to each number.
Endpoints
/cc/api/access_number
GET - Retrieve all access numbers.
/cc/api/access_number/{service_provider_name}
GET - Retrieve all access numbers for the specified Service Provider.
POST - Create an access number for the specified Service Provider.
/cc/api/access_number/{service_provider_name}/{number}
GET - Retrieve the specified access number.
PUT - Modify the specified access number if it exists, otherwise create the number.
DELETE - Archive the specified access number.
The following information is used in the body of a request to create and edit different accounts.
{
"number": "123456789",
"pin": "1234",
"current_pin": "1234",
"require_pin_one_step": false,
"initial_balance": "{"value": 5.00, "unit": "usd"}",
"current_balance": "{"value": 3.00, "unit": "usd"}",
"status": "GENERATED",
"activation_date": "01012020",
"default_expiration_type": "PRODUCT_OFFERING_EXPIRATION",
"expiration_date": "01012030",
"first_use_expiration_duration": "{"value": 0, "unit": "days"}",
"first_use_activation_type": "FIRST_USE_IVR",
"one_step_numbers": "[]",
"use_phone_me": false,
"phone_me_numbers": "[]",
"speed_dial_numbers": "[]",
"first_name": "john",
"last_name": "doe",
"email": "email@example.com",
"constraint_overrides": [],
"product_offering_name": "productoffering",
"product_offering_service_provider_name": "serviceprovider",
"service_provider_name": "serviceprovider",
"charge_number": "123456789",
"serial_number": "123456789",
"identity": "",
"params": "",
}
A unique string that is the card number of the account.
A string that is the PIN of this account.
A string that is the PIN of this account. If an account owner is changing a PIN, this is a required field.
A boolean value that determines whether the PIN is required when using one-step numbers. If this is null, this defaults to the setting for the associated product offering.
A JSON object that is the initial balance of the account containing the value and the unit being used.
A JSON object that is the current balance of the account containing the value and the unit being used.
A string that is the status of the account. This field accepts the following values: “ACTIVATED”, “BLOCKED”, “EMPTY”, “EXPIRED”, “GENERATED”, or “UPLOADED”. The default value is “GENERATED”.
A datetime that is the activation date of the account.
A string that is the expiration type for this account. This field accepts the following values: “PRODUCT_OFFERING_EXPIRATION”, “NO_EXPIRATION”, “FIXED_EXPIRATION”, or “DAYS_FROM_FIRST_USE”. The default value is “PRODUCT_OFFERING_EXPIRATION”.
A datetime that is the expiration date of the account.
A JSON object that is the number of units after the first time the account is used that it will expire containing the integer value and the unit being used. The default unit is “days”.
A string that determines the activation type when the default_expiration_type is “DAYS_FROM_FIRST_USE”. This field accepts either “FIRST_USE_IVR” or “FIRST_BILLED_CALL”.
An array of one step numbers that are associated with the account.
A boolean value where a value of “true” will set calls to default deny, unless a number is on the phone me list. The default value is “false”.
An array of phone me numbers that are associated with the account.
An array of speed dial numbers that are associated with the account.
A string that is the first name of a contact for this account.
A string that is the last name of a contact for this account.
A string that is the email address of this account.
An array of calling destination constraint overrides used within this account.
A unique string that is the product offering that is used by this account. Must match an existing product offering.
A unique string that is the Service Provider who provisioned the product offering that this account uses. Must match an existing Service Provider.
A unique string that is the Service Provider who provisioned this account. Must match an existing Service Provider.
A string that is the number used for billing that will appear in CDRs.
A string that is the serial number used for identifying this account.
A string that, if set, will set the P-Asserted-Identity header in outbound calls.
A JSON object that is a set of parameters to apply to every call.
Endpoints
/cc/api/account
GET - Retrieve all accounts.
/cc/api/account/{service_provider_name}
GET - Retrieve all accounts for the specified Service Provider.
POST - Create a new account.
/cc/api/account/{service_provider_name}/{number}
GET - Retrieve the specified account.
PUT - Modify the account if it exists, otherwise create the account.
DELETE - Archive the specified account.
/cc/api/account/{service_provider_name}/{number}/history
GET - Retrieve a call’s history.
/cc/api/account/{service_provider_name}/{number}/reset
POST - Reset an account’s PIN.
/cc/api/account/{service_provider_name}/{number}/activate
POST - Activate or deactivate an account.
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"
}
A unique string that is the user name for this user. Limit of 64 characters.
A string that defines the type of administrator that is being created. Accepted values are:
platform_owner
service_provider:<service_provider_name>
A string that is the first name of this user. Limit of 250 characters.
A string that is the last name of this user. Limit of 250 characters.
A string that is the email address for this user. Limit of 250 characters.
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
/cc/api/administrator/{role_id}
GET - Retrieve all users with the specified role.
POST - Create a user with the specified role.
/cc/api/administrator/{role_id}/{username}
GET - Retrieve the user with the specified role and user name.
PUT - Modify the user if it exists, otherwise create the user.
DELETE - Archive the specified user.
/cc/api/administrator/{role_id}/{username}/reset
POST - Reset the password for the specified user, returning a reset token.
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"
}
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$”.
A string that is a nickname or label to help identify this audio file.
A string that is the exact location of the audio file.
A string that is the server (NIU or secondary) where the audio file is stored.
A unique string that is the Service Provider who uses this audio file. Must match an existing Service Provider.
Endpoints
/cc/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.
/cc/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.
The following information is used in the body of a request to create and edit different calling services.
{
"name": "callingservice",
"display_name": "callingservice",
"description": "An example calling service.",
"rate_plans": [],
"minimum_billing": {"value: 0, "unit": "sec"},
"default_rounding_interval": {"value": 1, "unit": "sec"},
"rounding_threshold": {"value": 1, "unit": "sec"},
"call_markup": {"value": 0.0, "unit": "percent"},
"service_provider_name": "exampleserviceprovider",
"promotion_active": true,
"promotion_duration": "INDEFINITE",
"promotion_start": "01012020",
"promotion_end": "01012030",
"promotion_discount": {"value": 0.0, "unit": "percent"}
}
A unique string that is the name of this calling service.
An unconstrained string used as a display name for this calling service.
A string that is a description of the calling service.
An array of the rate plans used for this calling service.
A JSON object that defines the length of time that a call must be for billing to apply containing the integer value and the unit being used. The default value is “0” and the default unit is “sec”.
A JSON object that is the amount of time used for rounding total call time containing the integer value and the unit being used. The default value is “1” and the default unit is “sec”.
A JSON object that defines the length of time after which rounding applies containing the integer value and the unit being used. The default value is “1” and the default unit is “sec”.
A JSON object that is the surcharge to be applied after a call is completed containing the value and the unit being used. The default value is “0.00” and the default unit is “percent”.
A unique string that is the Service Provider who uses this calling service. Must match an existing Service Provider.
A boolean value where a value of “true” means the promotion periods are in use. The default value is “false”.
A string that is the duration of the promotion. This field accepts either “INDEFINITE” or “DATE_PERIOD”. The default value is “INDEFINITE”.
A timestamp of when the promotion starts.
A timestamp of when the promotion ends.
A JSON object that is the promotion value for the calling service containing the value and the unit being used. The default value is “0.00” and the default unit is “percent”.
Endpoints
/cc/api/calling_service/{service_provider_name}
GET - Retrieve all calling services for the specified Service Provider.
POST - Create a new calling service for the specified Service Provider.
/cc/api/calling_service/{service_provider_name}/{name}
GET - Retrieve the specified calling service.
PUT - Modify the calling service if it exists, otherwise create the calling service.
DELETE - Archive the specified calling service.
The following information is used in the body of a request to create and edit different calling destination constraints that can be applied to product offerings.
{
"label": "constraint",
"description": "Requires 585 area code",
"type": "REQUIRE",
"value": "585xxxxxxx",
"service_provider_name": "exampleserviceprovider"
}
A unique string that is the name of this constraint.
A string that is a description of the constraint.
A string that determines whether to require or block the call destination constraint. This field accepts either “REQUIRE” or “BLOCK”.
A string that is the call destination constraint value in regex format.
A unique string that is the Service Provider who uses this constraint. Must match an existing Service Provider.
Endpoints
/cc/api/constraint/{service_provider_name}
GET - Retrieve all constraints for the specified Service Provider.
POST - Create a new constraint for the specified Service Provider.
/cc/api/constraint/{service_provider_name}/{label}
GET - Retrieve the specified constraint.
PUT - Modify the constraint if it exists, otherwise create the constraint.
DELETE - Archive the specified constraint.
The following information is used in the body of a request to create and edit different product offerings.
{
"name": "productoffering",
"display_name": "productoffering"
"description": "An example Product Offering",
"type": "PREPAID_CALLING_CARD",
"default_expiration_type": "NO_EXPIRATION",
"default_expiration_date": "01012030"
"first_use_expiration_duration": {"value": 0, "unit": "days"},
"first_use_activation_type": "FIRST_USE_IVR",
"require_pin": true,
"require_pin_one_step": false,
"access_numbers": [],
"maximum_call_duration": {"value": 60, "unit": "minutes"},
"limit_simultaneous_calls": false,
"maximum_simultaneous_calls": 1,
"allow_one_step_list": false,
"maximum_one_step_numbers": 0,
"allow_speed_dial_list": false,
"allow_phone_me_list": false,
"maximum_phone_me_numbers": 0,
"routing_prefix": "0110",
"minimum_balance": {"value": 0.0, "unit": "usd"},
"maximum_balance": {"value": 50.0, "unit": "usd"},
"allow_inbound_balance_transfer": false,
"allow_outbound_balance_transfer": false,
"disable_account_after_transfer": false,
"sweep_balance": false,
"sweep_balance_threshold": {"unit": "usd", "value": 0.00}
"sweep_balance_activity_threshold": {"value": 0, "unit": "day"},
"allow_identity": false,
"allow_charge_number": false,
"constraints": [],
"calling_services": [],
"service_provider_name": "exampleserviceprovider",
"extend_expiration_after_transfer", false,
"expiration_extension_type": "EXPIRATION_INTERVAL",
"expiration_extension": {"value": 0, "unit": "day"}
"balance_type": "PERSISTENT",
"periodic_recharge_amount": {"unit": "usd", "value": 10.0}
"periodic_recharge_type": "MONTHLY",
"periodic_recharge_timing": 1,
"last_periodic_recharge": "01012030"
"second_greeting": "hello.wav",
"extend_session_balance": false,
"extended_balance": {"value": 0.00, "unit": "usd"},
"params": {}
}
A string that is the name of this product offering.
An unconstrained string used as a display name for this product offering.
A string that is a description of the product offering. Limit 248 characters.
A string that is the product offering type. This field accepts the following values: “PREPAID_CALLING_CARD”, “PREPAID_RESIDENTIAL”, “POSTPAID_CALLING_CARD”, or “POSTPAID_RESIDENTIAL”. The default value is “PREPAID_CALLING_CARD”.
A string that is the product offering expiration type. This field accepts the following values: “NO_EXPIRATION”, “FIXED_EXPIRATION”, and “DAYS_FROM_FIRST_USE”. The default value is “NO_EXPIRATION”.
A datetime that is the expiration date of the product offering.
A JSON object that is the number of units after the product offering is first used that the account cards will expire containing the integer value and the unit being used. The default value is “0” and the default unit is “days”.
A string that is the activation type for first use expiration. This field accepts either “FIRST_USE_IVR” or “FIRST_BILLED_CALL”. The default value is “FIRST_USE_IVR”.
A boolean value where a value of “false” does not require the associated account to use a PIN to log in. The default value is “true”.
A boolean value that determines whether the PIN is required when using one-step numbers. The default value is “false”.
An array of access numbers associated with this product offering.
A JSON object that is the maximum call duration for any call using this product offering containing the integer value and the unit being used. The default value is “0” and the default unit is “minutes”.
A boolean value where a value of “true” limits the number of simultaneous calls an account can make. The default value is “false”.
An integer that is the maximum number of simultaneous call that can be made from an account. The default value is “1”.
A boolean value where a value of “true” allows an account to maintain a one-step list. The default value is “false”.
An integer that is the maximum number of allowed entries in the one-step list. The default value of “0” means there is no limit.
A boolean value where a value of “true” allows an account to maintain a speed dial list. The default value is “false”.
A boolean value where a value of “true” allows an account to maintain a phone me list. The default value is “false”.
An integer that is the maximum number of allowed entries in the phone me list. The default value of “0” means there is no limit.
A string that will be prepended to all outbound calls after leading zeros are stripped.
A JSON object that is the minimum balance that an account is allowed to have containing the value and the unit being used. The default value is “0.00” and the default unit is “usd”.
A JSON object that is the maximum balance that an account is allowed to have containing the value and the unit being used. The default value is “0.00” and the default unit is “usd”.
A boolean value where a value of “true” allows a balance to be transferred to these accounts. The default value is “false”.
A boolean value where a value of “true” allows a balance to be transferred from these accounts. The default value is “false”.
A boolean value where a value of “true” will disable an account after a balance transfer if the minimum balance is not maintained. The default value is “false”.
A boolean value where a value of “true” will cause an account to expire when the balance falls bellow a minimum. The default value is “false”.
A JSON object that is the minimum balance an account must have to be exempt from a balance sweep expiration containing the value and the unit being used. The default value is “0.00” and the default unit is “usd”.
A JSON object that defines how long to wait for an account to have no activity before expiring it due to the sweep_balance setting containing the integer value and the unit being used. The default value is “0” and the default unit is “day”. The “unit” of this JSON accepts the following values: “hour”, “day”, or “year”.
A boolean value where a value of “true” allows an account owner to set their own identity. The default value is “false”.
A boolean value where a value of “true” allows an account owner to set the charge number on their account. The default value is “false”.
An array of calling destination constraints within this product offering.
An array of calling services for this product offering.
A unique string that is the Service Provider who uses this product offering. Must match an existing Service Provider.
A boolean value where a value of “true” will extend the expiration date of accounts after a balance transfer. The default value is “false”.
A string that is the type expiration extension that occurs. This field accepts either “TRANSFER_INTERVAL” or “EXPIRATION_INTERVAL”. The default value is “TRANSFER_INTERVAL”.
A JSON object that is how long the expiration date is extended containing the integer value and the unit being used. The default value is “0” and the default unit is “day”. The “unit” of this JSON accepts the following values: “hour”, “day”, or “year”.
A string that is the balance type. This field accepts either “PERSISTENT” or “PERIODIC”. A balance type of persistent has no periods associated with it. A balance type of periodic sets up a maximum/minimum amount per period.
A JSON object that is the amount a user will be permitted to debit/credit during a given period containing the value and the unit being used. The default value is “0.00” and the default unit is “usd”.
A string that is when a periodic recharge should occur, in conjunction with the periodic_recharge_value setting. This field accepts the following values: “DAILY”, “WEEKLY”, or “MONTHLY”.
An integer that is the timing description for the periodic recharge type. If the periodic recharge type is DAILY, this is the hour (0-23) that the recharge occurs. If the periodic recharge type is WEEKLY, this is the day of the week (0-6, Monday-Sunday) that the recharge occurs. If the periodic recharge type is MONTHLY, this is the day of the month (1-31) that the recharge occurs.
A datetime that is the last time a periodic recharge will occur.
A string that is an audio file to play after authentication.
A boolean value where a value of “true” will extend the balance when within a session. The default value is “false”.
A JSON object that is the separate balance used for establishing sessions and cutting off sessions, when the extend_session_balance setting is set to “true”, containing the value and the unit being used. The default value is “0.00” and the default unit is “usd”.
A JSON object that is a set of parameters to apply to all calls.
Endpoint
/cc/api/product_offering
GET - Retrieve all product offerings.
/cc/api/product_offering/{service_provider_name}
GET - Retrieve all product offerings for the specified Service Provider.
POST - Create a new product offering for the specified Service Provider.
/cc/api/product_offering/{service_provider_name}/{name}
GET - Retrieve the specified product offering.
PUT - Modify the product offering if it exist, otherwise create the product offering.
DELETE - Archive the specified product offering.
The following information is used in the body of a request to create and edit different rates.
{
"name": "thisrate",
"display_name": "thisrate",
"description": "The rate description.",
"type": "ACCESS_NUMBER",
"effective_date": "01012020",
"end_date": "01012030",
"charge_method": "PER_MINUTE",
"amount": {"announced": true, "value": {"unit": "usd", "value": 0.10}},
"surcharge": {"announced": true, "value": {"unit": "percent", "value": 0.50}},
"if_no_sub_rates_exist": "USE_PARENT_AS_DEFAULT",
"service_provider_name": "exampleserviceprovider",
"children": []
}
A unique string that is the name of this rate. This name must be at least 6 characters long and no more than 64 characters long.
An unconstrained string used as a display name for this rate.
A string that is a description of the rate. Limit 248 characters.
A string that is the rate type. This field accepts the following values: “ACCESS_NUMBER”, “BUCKET_OF_MINUTES”, “DOMESTIC_DESTINATION”, “DOMESTIC_ORIGINATION”, “INTERNATIONAL_DESTINATION”, “INTERNATIONAL_ORIGINATION”, “MATRIX_DOMESTIC”, “MATRIX_GLOBAL”, or “PAYPHONE”. The default value is “ACCESS_NUMBER”.
A datetime that is the start date of the rate.
A datetime that is the end date of the rate.
A string that is the charge method used to determine the rate. This field accepts either “PER_MINUTE” or “EVENT”. The default value is “PER_MINUTE”.
A JSON object that determines the charge for the rate containing the value, the unit being used, and whether the amount is announced. The default value is “0.00” and the default unit is “usd”.
A JSON object that determines the rate surcharge containing the value, the unit being used, and whether the amount is announced. The default value is “0.00” and the default unit is “percent”.
A string that is the rate behavior if no sub rates have been created. This field accepts the following values: “USE_PARENT_AS_DEFAULT”, “APPLY_NO_RATE”, or “BLOCK_EVENT”. The default value is “USE_PARENT_AS_DEFAULT”.
A unique string that is the Service Provider who uses this rate. Must match an existing Service Provider.
An array of sub rate values.
Endpoints
/cc/api/rate/{service_provider_name}
GET - Retrieve all rates for the specified Service Provider.
POST - Create a new rate for the specified Service Provider.
/cc/api/rate/{service_provider_name}/{name}
GET - Retrieve the specified rate.
PUT - Modify the rate if it exists, otherwise create the rate.
DELETE - Archive the specified rate.
The following information is used in the body of a request to create and edit different rate plans.
{
"name": "rateplan",
"display_name": "rateplan",
"description": "An example Rate Plan.",
"modifier_schedule": [],
"rates": [],
"service_provider_name": "exampleserviceprovider"
}
A unique string that is the name of this rate plan.
An unconstrained string used as a display name for this rate plan.
A string that is a description of the rate plan. Limit of 248 characters.
An array that is when the rate plan will be active.
An array of rates associated with this rate plan.
A unique string that is the Service Provider who uses this rate plan. Must match an existing Service Provider.
Endpoints
/cc/api/rate_plan/{service_provider_name}
GET - Retrieve all rate plans for the specified Service Provider.
POST - Create a new rate plan for the specified Service Provider.
/cc/api/rate_plan/{service_provider_name}/{name}
GET - Retrieve the specified rate plan.
PUT - Modify the rate plan if it exists, otherwise create the rate plan.
DELETE - Archive the specified rate plan.
The following information is used in the body of a request to create and edit different Service Providers.
Note
These are not administrator accounts.
{
"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."
}
A unique string that is the name of this Service Provider. This name must be at least 8 characters long and no more than 128 characters long.
An unconstrained string used as a display name for this Service Provider.
A string that is the first name of a contact for this Service Provider.
A string that is the last name of a contact for this Service Provider.
A string that is the email address of this Service Provider, where notifications and password reset requests will be sent.
A string that is the physical address of this Service Provider.
A string that is the primary phone number of this Service Provider.
A string that is a free-form notes field. Limit of 2048 characters.
Endpoints
/cc/api/service_provider
GET - Retrieve all Service Providers.
POST - Create a new Service Provider.
/cc/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.
The following information is used in the body of a request to create and edit UCard integration settings.
{
"account_number": "1234",
"service_provider_name": "exampleserviceprovider",
"access_number": "1234",
"balance": "0.00"
}
A string that is the number of this UCard account.
A unique string that is the Service Provider who uses this UCard account. Must match an existing Service Provider.
A string that is the number to access this UCard account.
A value that is the current balance of this UCard account.
Endpoints
/cc/api/ucard_account/{service_provider_name}
POST - Create a new UCard account for the specified Service Provider.
/cc/api/service_provider/{account_number}
DELETE - Archive the specified UCard account.
The following information is used in the body of a request to edit settings. The following example uses the default values.
{
"branding": {
"imsworkx": {
"color_hue": "75",
"highlight_hue": "79",
"logo": "logo.png",
"label": "IMSWorkX, Inc. ®"
}
},
"restworkx": {
"archive_max_days": "7"
},
"web_settings": {
"help_page": "http://www.imsworkx.com",
"password_length": "8",
"curency": "usd"
},
"security": {
"client_cert": null,
"client_key": null,
"ca_bundle": null,
"allow_insecure": false
},
"cc_settings": {
"use_contact": true,
"egress_route": "127.0.0.1",
"radius_timeout":"5",
"rating_interval":"5",
"ring_type":"180",
"skip_account_reentry":false
},
"email_settings": {
"use_email": false,
"host": "",
"user": "",
"port": "",
"password": "",
"use_tls": false,
"messages": {
"recover": {
"subject": "Recover Your Account",
"headline": "Account Recovery",
"message": "Click the link below to recover your account."
},
"activate": {
"subject": "Activate Your Account",
"headline": "Account Activation",
"message": "Click the link below to activate your account."
}
}
}
}
Contains settings related to the look and feel of the website using the following parameters:
imsworkx: The default appearance settings. Additional fields can be added at this level under different names, which can then be appended to the URL for custom branding.
color_hue: (Integer) This will change the primary color used on the site. This value is a number between 0 and 360, using the HSL model where 0 is red, 120 is green, and 240 is blue.
highlight_hue: (Integer) This will change the secondary color used on the site. This value is a number between 0 and 360, using the HSL model where 0 is red, 120 is green, and 240 is blue.
logo: (String) Filename for the logo that will appear in the upper, left corner of the website. The image must be a PNG file and placed in the /var/opt/xpressworkx/app-manager/cc/static/img/ directory.
label: (String) The message displayed in the upper, right corner of the website. This is generally a company name.
Contains settings related to the platform and database.
archive_max_days: (Integer) Number of days to keep records in the archive table.
Contains settings for elements on the website.
help_page: (String) URL for the web page that is linked in the “Help” button on the upper, right corner of the page.
password_length: (Integer) Minimum number of characters allowed in a password.
currency: (String) A value that determines the default currency of CC. Acceptable values are “usd” or “bot”.
Contains settings related to SSL configuration.
client_cert: (String) File location of the client’s certificate.
client_key: (String) File location of the key used for the client’s certificate.
ca_bundle: (String) File location of the root certificate. This is the only setting that matters when SSL is configured by the configure-ssl command and is automatically set by that script.
allow_insecure: (Boolean) If true, the web UI will not check the NIU’s certificate against the configured ca_bundle when making API calls.
Contains settings used during the call flow.
use_contact: (Boolean) If true, the host from the Contact header of the INVITE will be used as the egress_route.
egress_route: (String) The host to use when connecting a call to the called party.
radius_timeout: (Integer) Time in seconds to wait for a Radius response before discontinuing the call.
rating_interval: (Ineger) Time in seconds a call rate is calculated.
ring_type: (String)
skip_account_reentry: (Boolean)
Contains settings for automated emails for password changes.
use_email: (Boolean) If true, activation and recovery emails will be sent.
host: (String) Host for email client to send messages through.
user: (String) Username for email service messages will be sent through.
port: (Integer) Port used for email host.
password: (String) Password for the email user.
use_tls: (Boolean) If true, TLS encryption will be used for the email.
messages: Contains settings for the contents of the email message.
recover: Contains settings for the contents of the email message sent when an account’s password is reset.
subject: (String) Subject line of the recovery email message.
headline: (String) Header of the recovery email message body.
message: (String) Message of the recovery email message.
activate: Contains settings for the contents of the email message sent when an account is created.
subject: (String) Subject line of the activation email message.
headline: (String) Header of the activation email message body.
message: (String) Message of the activation email message.
The following information is used in the body of a request to edit Service Provider settings. The following example uses the default values.
{
"web_settings":{
"pin_length":"04",
"ivr_pin_retries":"05",
"transfer_pin_retries":"15",
"ivr_pin_reset_duration":{
"value":"5",
"unit":"hours"},
"currency":"usd"},
"cc_settings":{
"block_with_media":false}
}
Contains settings for elements on the website.
pin_length: (Integer) The minimum number of digits that a PIN must be.
ivr_pin_retries: (Integer) The number of times an incorrect PIN can be entered before the account is locked out. This value must be between 3 and 100.
transfer_pin_retries: (Integer) The number of times an incorrect PIN can be entered when transferring a balance before the account is locked out. This value must be between 3 and 100.
ivr_pin_reset_duration: (Array) The length of time an account is locked out after the exceeding the values set for ivr_pin_retries or transfer_pin_retries.
currency: (String) A value that determines the default currency of CC. Acceptable values are “usd” or “bot”.
block_with_media: (Boolean) If true, an audio message is played on a blocked call.
Endpoints
/cc/api/settings/
GET - Retrieve the settings for the current user.
PUT - Modify the settings.
The following common responses may be encountered while using the CC API. The format of these responses may look different from the documented examples based on the tool used to make API calls.
Note
Many HTTP responses are a 200 OK due to the call to the API being successful. It is important to read the body of the response as it could contain an error.
When making an API call to a server that does not have CC installed, the following message will be seen.
curl -X POST \
-H "Content-Type:application/json" \
<niu-ha>/cc/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 /cc/api/authenticate was not found on this server.</p>
</body></html>
Note
This response is not controlled by the CC API and is entirely an HTTP response.
When logging in to the API with incorrect or missing information, the following message will be seen.
curl -X POST \
-d '{"username":"cc_administrator"}' \
localhost/cc/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: cc_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cc
< 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.6-7",
"name": "Calling Card",
"short_name": "cc",
"author": "IMSWorkX, Inc."
}
}
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/cc/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: cc_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cc
< 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.6-7",
"name": "Calling Card",
"short_name": "cc",
"author": "IMSWorkX, Inc."
}
}
Note
This is technically a successful call to the API, thus the 200 code return.
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/cc/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: cc_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cc
< 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.6-7",
"name": "Calling Card",
"short_name": "cc",
"author": "IMSWorkX, Inc."
}
}
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/cc/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: cc_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cc
< 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.6-7",
"name": "Calling Card",
"short_name": "cc",
"author": "IMSWorkX, Inc."
}
}
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/cc/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: cc_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cc
<
* Connection #0 to host localhost left intact
* Closing connection #0
When making a successful API call, the following message will be seen.
curl -X GET \
-H "Authorization: Basic <secure-access-token>" \
localhost/cc/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: cc_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/cc
< 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.6-7",
"name": "Calling Card",
"short_name": "cc",
"author": "IMSWorkX, Inc."
}
}
The above responses can be seen as responses from a stable CC API. If you encounter other undocumented API errors, please contact support@imsworkx.com with the API call and output.
Audit logs are generated every day by default and are stored as a CSV file. By default, these files are located in /var/opt/xpressworkx/app-manager/cc/logs/audit-logs and are named audit-<year>.<month>.<day>.log.