This RESTful API provides the building blocks that developers need to programmatically integrate PCS with other network elements and systems. The API works over HTTP or HTTPS.
Individual objects that can be manipulated through the API include PCS administrators, service providers, and more. This chapter is a developer reference for connecting a currently used system to PCS.
The API is available at https://<NIU or HA address>/pcs/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>/pcs/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 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>/pcs/api/authenticate \
-d '{"username":"<username>","password":"<password>"}'
The response will contain the following:
"data": [
{"token": "<secure-access-token>"}
],
"jsonapi": {"version": "2.0-3",
"name": "Personal Call Screening",
"short_name": "pcs",
"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>/pcs/api/<object>/<object-id>
curl -X GET \
-H "Content-Type:application/json" \
-H "Authorization:Basic <secure-access-token>" \
"http://localhost/pcs/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>/pcs/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/pcs/api/cdr"?offset=0&limit=25&sort=column:asc
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
/pcs/api/pcs_cdr
GET - Retrieve all CDRs that match the specified criteria.
/pcs/api/pcs_cdr/{service_provider}
GET - Retrieve the CDRs associated with a particular Service Provider.
/pcs/api/pcs_cdr/{service_provider}/{subscriber}
GET - Retrieve the CDRs associated with a particular Subscriber.
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>/pcs/api/service_provider -d \
'{"name": "IMSWorkX", "display_name": "IMSWorkX", "first_name": "Jane", "last_name": "Doe", "email": "example@example.com", "address": "1 Main St. Rochester, NY", "phone": "5858675309", "notes": "more notes"}'
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>/pcs/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 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. Can contain only lowercase characters, numbers, or underscores.
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>
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.
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
pcs_default:pcs_application_provisioning
pcs_default:pcs_platform_owner_administration
pcs_default:pcs_platform_owner_platform_administration
pcs_default:pcs_platform_owner_provisioning
pcs_default:pcs_platform_owner_user_administration
pcs_default:pcs_platform_owner_views
pcs_default:pcs_service_provider_platform_administration
pcs_default:pcs_service_provider_provisioning
pcs_default:pcs_service_provider_user_administration
pcs_default:pcs_service_provider_views
pcs_default:pcs_subscriber_administration
pcs_default:pcs_subscriber_platform_administration
pcs_default:pcs_subscriber_provisioning
pcs_default:pcs_subscriber_user_administration
pcs_default:pcs_subscriber_views
pcs_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
/pcs/api/administrator/{role_id}
GET - Retrieve all administrators with the specified role.
POST - Create an administrator with the specified role.
/pcs/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.
/pcs/api/administrator/{role_id}/{username}/reset
POST - Reset this user’s password, returning a reset token.
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",
"whitelist": ["5855551234"],
"blacklist": ["5859879876"]
}
A unique string that is the name of this Service Provider. Limit of 64 characters.
An unconstrained string used as a display name. Limit of 250 characters.
A string that is the first name of a contact for this Service Provider. Limit of 250 characters.
A string that is the last name of a contact for this Service Provider. Limit of 250 characters.
A string that is the email address of this Service Provider, where notifications and password reset requests will be sent. Limit of 250 characters.
A string that is the physical address of this Service Provider. Limit of 250 characters.
A string that is the primary phone number of this Service Provider. Limit of 250 characters.
A string that is a free-form notes field. Limit of 2048 characters.
An array of strings of phone numbers that are always allowed. This is a global list that is applied to all of this Service Provider’s Subscribers.
An array of strings of phone numbers that are always blocked. This is a global list that is applied to all of this Service Provider’s Subscribers.
Note
For whitelist and blacklist, numbers that include a country code must be preceded by a ‘+’. If there is no ‘+’ at the beginning of an entry, the Default Country Code will be prepended to the entry.
Endpoints
/pcs/api/service_provider
GET - Retrieve all Service Providers.
POST - Create a new Service Provider.
/pcs/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 edit the service selection criteria.
{
"service_provider_name": "exampleserviceprovider",
"screening_group": "examplegroup",
"point_code_ranges": "",
"called_ccs": "",
"source_ips": ""
}
The name of the service provider this subscriber is under.
The name of the screening group these criteria apply to.
An array of array point code ranges used to identify this service.
An array of country codes for the called party used to identify this service.
An array of SIP Addresses used to identify this service.
Endpoints
/pcs/api/service_selection_criteria/<service_provider>
GET - Retrieve all service selection criteria for the specified Service Provider.
POST - Create a new service selection criteria for the specified Service Provider.
Note
If no group_name is included in the body, it will be set to “pcs:<service_provider>” by default.
The following information is used in the body of a request to edit the global screening rules.
{
"whitelist": {
"personal": false,
"global": true,
"override": false,
"stir_shaken": true,
"match": "continue",
"no_match": "next",
"priority": "2"
},
"blacklist": {
"personal": false,
"global": true,
"override": false,
"stir_shaken": true,
"match": "terminate",
"no_match": "next",
"priority": "3"
},
"call_guardian": {
"enabled": true,
"override": false,
"lower_threshold": "-2",
"lower_treatment": "terminate",
"mid_treatment": "next",
"upper_threshold": "3",
"upper_treatment": "continue",
"priority": "4",
"timeout": "10",
"customer_identifier": "exampleuser",
"database_address": "10.10.10.10"
},
"captcha": {
"enabled": true,
"override": false,
"audio": "/usr/sipxpress/media/local/afrar5aghsyunasf.wav",
"first_digit_timeout": "4000",
"inter_digit_timeout": "8000",
"pass": {"treatment": "continue", "audio": "default"},
"fail": {"treatment": "next", "audio": "default"},
"digit_length": "4",
"retries": "1",
"priority": "5"
},
"recorded_greeting": {
"enabled": true,
"override": false,
"audio_called": "default",
"audio_calling": "usr/sipxpress/media/local/audio.wav",
"option_1": "continue",
"option_2": "terminate",
"option_3": "terminate_solicitor",
"option_4": "voicemail",
"priority": "6"
},
"stir_shaken": {
"enabled": true,
"override": false,
"auth_address": "10.10.10.10",
"invalid": "terminate",
"priority": "1"
},
"error_treatment": "continue",
"service_provider_name": "exampleserviceprovider"
}
Note
For every rule that is included in the screening_rule object, all configuration for that rule must also be included.
A JSON object that controls the Whitelist screening rule.
A JSON object that controls the Blacklist screening rule.
A JSON object that controls the TNS Call Guardian screening rule.
A JSON object that controls the Audio CAPTCHA screening rule.
A JSON object that controls the Recorded Greeting screening rule.
A JSON object that controls the STIR/SHAKEN screening rule.
A string that is the treatment to use if none is provided. Accepted values are “continue”, “terminate”, “terminate_solicitor”, and “next”.
A unique string that is the name of the Service Provider using these screening rules. Must match an existing Service Provider.
whitelist
A boolean value that determines if a personal list is used. The value “true” means a personal list is used, while “false” means a personal list is not enabled.
A boolean value that determines if a global list is used. The value “true” means the global list is used, while “false” means the global list is not enabled.
A boolean value that determines if a Subscriber can turn this feature on and off. The value “true” means the Subscriber can disable or enable this rule.
A boolean value that determines if this rule requires a valid signature to match.
A string that is the treatment for a case with a match. Accepted values are “continue”, “terminate”, “terminate_solicitor”, “voicemail”, and “next”.
A string that is the treatment for a case without a match. Accepted values are “continue”, “terminate”, “terminate_solicitor”, “voicemail”, and “next”.
An integer that determines the order in which rules are evaluated. A lower value priority is evaluated before a higher value priority.
blacklist
A boolean value that determines if a personal list is used. The value “true” means a personal list is used, while “false” means a personal list is not enabled.
A boolean value that determines if a global list is used. The value “true” means the global list is used, while “false” means the global list is not enabled.
A boolean value that determines if a Subscriber can turn this feature on and off. The value “true” means the Subscriber can disable or enable this rule.
A boolean value that determines if this rule requires a valid signature to match.
A string that is the treatment for a case with a match. Accepted values are “continue”, “terminate”, “terminate_solicitor”, “voicemail”, and “next”.
A string that is the treatment for a case without a match. Accepted values are “continue”, “terminate”, “terminate_solicitor”, “voicemail”, and “next”.
An integer that determines the order in which rules are evaluated. A lower value priority is evaluated before a higher value priority.
call_guardian
A boolean value that determines if this rule is enabled. A value of “true” means the rule is enabled.
A boolean value that determines if a Subscriber can turn this feature on and off. The value “true” means the Subscriber can disable or enable this rule.
An integer that is the maximum rating to receive the treatment from lower treatment.
A string that is the treatment for the lower threshold and below. Accepted values are “continue”, “terminate”, “terminate_solicitor”, “voicemail”, and “next”.
A string that is the treatment for the ratings between the lower and upper thresholds. Accepted values are “continue”, “terminate”, “terminate_solicitor”, “voicemail”, and “next”.
An integer that is the minimum rating to receive the treatment from upper treatment.
A string that is the treatment for the upper threshold and above. Accepted values are “continue”, “terminate”, “terminate_solicitor”, “voicemail”, and “next”.
An integer that determines the order in which rules are evaluated. A lower value priority is evaluated before a higher value priority.
An integer that is the time in seconds to wait for a response from the Call Guardian database before moving to the next screening rule.
A string that is the user of TNS Call Guardian.
A string that is the location of the TNS Call Guardian database.
captcha
A boolean value that determines if this rule is enabled. A value of “true” means the rule is enabled.
A boolean value that determines if a Subscriber can turn this feature on and off. The value “true” means the Subscriber can disable or enable this rule.
A string that is the audio file that will play as the audio CAPTCHA. Accepted values are “default” for the default audio or the full file path of the location of the audio file on the AS.
An integer that determines the time, in milliseconds, that the caller has to dial the first digit in the sequence after the audio prompt has finished playing.
An integer that determines the time, in milliseconds, that the caller has in between dialing each digit in the sequence.
An array that contains the string that is the treatment for passing the audio CAPTCHA and the string that is the audio file to play after the digits are processed. Accepted values for treatment are “continue”, “terminate”, “terminate_solicitor”, “voicemail”, and “next”. Accepted values for audio are “default” for the default audio or the full file path of the location of the audio file on the AS.
An array that contains the string that is the treatment for failing the audio CAPTCHA and the string that is the audio file to play after the digits are processed. Accepted values for treatment are “continue”, “terminate”, “terminate_solicitor”, “voicemail”, and “next”. Accepted values for audio are “default” for the default audio or the full file path of the location of the audio file on the AS.
An integer that is the number of digits used in the audio CAPTCHA.
An integer that determines the number of times that a caller is allowed to fail the prompt before the rule is considered failed. Each attempt will generate a new sequence of digits.
An integer that determines the order in which rules are evaluated. A lower value priority is evaluated before a higher value priority.
recorded_greeting
A boolean value that determines if this rule is enabled. A value of “true” means the rule is enabled.
A boolean value that determines if a Subscriber can turn this feature on and off. The value “true” means the Subscriber can disable or enable this rule.
A string that is the audio file that will play to the called party during the treatment. Accepted values are “default” for the default audio or the full file path of the location of the audio file on the AS.
A string that is the audio file that will play to the calling party during the treatment. Accepted values are “default” for the default audio or the full file path of the location of the audio file on the AS.
A string that is the treatment for dialing 1. Accepts the values “continue”, “terminate”, “terminate_solicitor”, and “voicemail”.
A string that is the treatment for dialing 2. Accepts the values “continue”, “terminate”, “terminate_solicitor”, and “voicemail”.
A string that is the treatment for dialing 3. Accepts the values “continue”, “terminate”, “terminate_solicitor”, and “voicemail”.
A string that is the treatment for dialing 4. Accepts the values “continue”, “terminate”, “terminate_solicitor”, and “voicemail”.
An integer that determines the order in which rules are evaluated. A lower value priority is evaluated before a higher value priority.
stir_shaken
A boolean value that determines if this rule is enabled. A value of “true” means the rule is enabled.
A boolean value that determines if a Subscriber can turn this feature on and off. The value “true” means the Subscriber can disable or enable this rule.
A string that is the address of root certificate to validate against.
A string that is the treatment when the signature is present but invalid. Accepted values are “continue”, “terminate”, “terminate_solicitor”, “voicemail”, and “next”.
An integer that determines the order in which rules are evaluated. A lower value priority is evaluated before a higher value priority.
Endpoints
/pcs/api/screening_rule/{service_provider_name}
GET - Retrieve all screening plans owned by the specified Service Provider.
PUT - Modify the screening plan if it exists, otherwise create the screening plan.
The following information is used in the body of a request to create and edit audio files.
{
"file": "Hello.wav",
"location": "/temp/audio",
"server": "lab-niu01.lab.redcom.com",
"label": "Hello",
"service_provider_name": "Name"
}
A string that is the server (NIU or secondary) where the audio file is stored.
A string that is the exact location of the audio 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$”.
A string that is a nickname or label to help identify this audio file.
A unique string that is the Service Provider for this audio file. Must match an existing Service Provider.
Endpoints
/pcs/api/audio/{service_provider_name}
GET - Retrieve all audio files under the specified Service Provider.
POST - Create a new audio file.
/pcs/api/audio/{service_provider_name}/{file}
GET - Download a specific audio file.
PUT - Modify the audio file if it exists, otherwise create the audio file.
DELETE - Archive the specified audio file.
The following information is used in the body of a request to create and edit different Subscribers.
Note
These are not administrator accounts.
{
"name": "examplesubscriber",
"display_name": "ExampleSubscriber",
"service_provider_name": "exampleserviceprovider",
"first_name": "Jane",
"last_name": "Doe",
"email": "jdoe@example.com",
"address": "123 Main St",
"phone": "5851234321",
"notes": "This is an example Subscriber.",
"voicemail": "",
"service_enabled": true,
"whitelist": [],
"blacklist": [],
"override": {
"stir_shaken": false,
"whitelist": true,
"blacklist": true,
"call_guardian": false,
"captcha": false,
"recorded_greeting": false
}
}
A unique string that is the name of this Subscriber. Limit of 64 characters.
An unconstrained string used as a display name. Limit of 250 characters.
A unique string that is the name of the Service Provider for this Subscriber. Must match an existing Service Provider.
A string that is the first name of a contact for this Subscriber. Limit of 250 characters.
A string that is the last name of a contact for this Subscriber. Limit of 250 characters.
A string that is the email address of this Subscriber, where notifications and password reset requests will be sent. Limit of 250 characters.
A string that is the physical address of this Subscriber. Limit of 250 characters.
A string that is the primary phone number of this Subscriber. Limit of 250 characters.
A string that is a free-form notes field. Limit of 2048 characters.
A string that is the location of the Subscriber’s voice mail service.
A boolean that shows the state of this Subscriber’s PCS service. The value “true” means the service is active, and the value “false” means the service is off. The default value is “true”.
An array of strings of phone numbers that are always allowed.
An array of strings of phone numbers that are always blocked.
Note
For whitelist and blacklist, numbers that include a country code must be preceded by a ‘+’. If there is no ‘+’ at the beginning of an entry, the Default Country Code will be prepended to the entry.
A JSON object containing the screening rules that have been disabled by this Subscriber. The format of this JSON is as follows:
{
"stir_shaken": false,
"whitelist": true,
"blacklist": true,
"call_guardian": false,
"captcha": false,
"recorded_greeting": false
}
Note
Each screening rule override is a boolean where the value “true” means the service is disabled and the value “false” means the service is enabled.
Endpoints
/pcs/api/subscriber/{service_provider_name}
GET - Retrieve all Subscribers owned by the specified Service Provider.
POST - Create a new Subscriber.
/pcs/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.
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",
"whitelist": [],
"blacklist": []
}
A unique string that must be a valid phone number. Limit of 250 characters.
Note
A number that includes a country code must be preceded by a ‘+’. If there is no ‘+’ at the beginning of the number, the Default Country Code will be prepended to the number. This applies to all API operations.
A unique string that is the name of the Subscriber who uses this number. Must match an existing Subscriber.
A unique string that is the name of the Service Provider for the Subscriber who uses this number. Must match an existing Service Provider.
A string that is an optional display name to identify this number. Limit of 250 characters.
An array of strings of phone numbers that are always allowed.
An array of strings of phone numbers that are always blocked.
Note
For whitelist and blacklist, numbers that include a country code must be preceded by a ‘+’. If there is no ‘+’ at the beginning of an entry, the Default Country Code will be prepended to the entry.
Endpoints
/pcs/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.
/pcs/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.
/pcs/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.
The following information is used in the body of a request to create and edit origination sources.
{
"name": "server1",
"service_provider_name": "example_sp",
"source_ip": ["145.123.233.21", "192.168.1/24"],
"orig_id": "abc-433444-xyz",
"attest": "A",
"cert_name": "Certificate0",
"source_numbers": [
{
"numbers_n": ["585xxxxxxx","716555xxxx"],
"orig_id_n": "def-544333-uvw",
"attest_n": "B",
"cert_name_n": "Certificate1",
"priority": 0
},
{
"numbers_n": ["613xxxxxxx"],
"orig_id_n": "ghi-655222-rst",
"attest_n": "C",
"cert_name_n": "Certificate2",
"priority": 1
}
]
}
A unique string that is the name of this source. Limit of 64 characters and must contain only alphanumeric characters or underscores (_).
A string that is the name of the Service Provider for the Subscriber who uses this source. Must match an existing Service Provider.
An array of strings defining one or more IP addresses used to determine which origination source to use. Entries can be a single IP address or CIDR-notated blocks. The Via header of the INVITE will be checked for a matching source_ip to determine the source.
A unique string to identify the source in messaging. This will be the default value for this source.
A string to define the level of attestation. Use the value “A” for full attestation, “B” for partial attestation, “C” for gateway attestation, and “N” for no attestation. This will be the default value for this source.
A string used to identify the default certificate to use with this source for signing the Identity header of the INVITE. It must match an identifier of a certificate in the associated SKS.
An array of JSON-formatted data. The format of this JSON is as follows:
{
"service_provider_name": "ProviderName",
"source_name": "sourcename",
"numbers_n": ["585xxxxxxx","716555xxxx"],
"orig_id_n": "def-544333-uvw",
"attest_n": "B",
"cert_name_n": "Certificate1",
"priority": 0
},
A string that is the name of the Service Provider for the Subscriber who uses this source number. Must match an existing Service Provider.
A unique string that is the name of this source. Limit of 64 characters and must contain only alphanumeric characters or underscores (_).
An array of strings. Must have at least one entry. INVITEs from the source that match these numbers, with “x” being used as a wildcard digit, will be signed using the values in this entry.
The specific origination ID used for this mask.
The attestation level assigned for this mask.
The specific certificate identifier to use for signing with this mask.
The order that this mask should be checked in relation to other masks for the origination source. A lower value priority is checked before a higher value priority.
Endpoints
/pcs/api/origination_source/{service_provider_name}
GET - Retrieve all sources owned by the specified Service Provider.
POST - Create a new source owned by the specified Service Provider.
/pcs/api/origination_source/{service_provider_name}/{name}
GET - Retrieve the specified source.
PUT - Modify the source if it exists, otherwise create the source.
DELETE - Archive the specified source.
The following information is used in the body of a request to edit settings. The following example uses the default values.
{
"menu_forwarding_configuration_file": "/usr/sipxpress/config/pcs-menu-forwarding-configuration.yml",
"screening_engine_uri": "http://niu/pcs-screening-engine",
"download_directory": "/var/opt/xpressworkx/app-manager/pcs/media/download",
"upload_directory": "/var/opt/xpressworkx/app-manager/pcs/media/upload",
"job_log_directory": "/var/opt/xpressworkx/app-manager/pcs/media/download",
"application_username": "pcs_application_manager",
"application_password": "<password>",
"screening_interface_impl": "com.imsworkx.screeningEngine.xtml.ScreeningEngine",
"csr_location": "sip:csr@localhost",
"branding": {
"imsworkx": {
"color_hue": "202",
"highlight_hue": "198",
"logo": "logo.png",
"label": "Evolve Cellular Inc. ®"
}
},
"restworkx": {
"archive_max_days": "7",
"audit_log_directory": "/var/opt/xpressworkx/app-manager/pcs/logs/audit-logs/",
"log_duration": "1"
},
"web_settings": {
"help_page": "http://www.imsworkx.com",
"password_length": "8",
"number_mask": "(ddd) ddd-dddd",
"default_cc": "1"
},
"security": {
"client_cert": null,
"client_key": null,
"ca_bundle": null,
"allow_insecure": false
},
"screening_engine": {
"trunk_id_in_forward_call": false,
"egress_route": "",
"reject_with_media": false,
"voicemail_service_location": "",
"sip_routing_prefix": "",
"use_contact": true,
"default_treatment": "continue",
"ring_while_contacting_called_party": "silence",
"drop_anonymous_calls": false
},
"called_sources_config": [
{
"source": "hdr.to",
"policy": {
"user_phone_missing_context": null,
"attempt_implicit_user_phone": false,
"heuristic_digits": "as-is"
},
"post": []
},
{
"source": "request_uri",
"policy": {
"user_phone_missing_context": null,
"attempt_implicit_user_phone": false,
"heuristic_digits": "as-is"
},
"post": []
}
],
"calling_sources_config": [
{
"source": "hdr.from",
"policy": {
"user_phone_missing_context": null,
"attempt_implicit_user_phone": true,
"heuristic_digits": "as-is"
},
"post": [{"type":"require_digits","min_length":"3"}]
},
{
"source": "hdr.p_asserted_identity",
"policy": {
"user_phone_missing_context": null,
"attempt_implicit_user_phone": true,
"heuristic_digits": "longest-digit-substring"
},
"post": [{"type":"require_digits","min_length":"3"}]
}
],
"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."
}
}
}
}
The following settings are set automatically during installation and should not need to be changed:
menu_forwarding_configuration_file
screening_engine_uri
download_directory
upload_directory
job_log_directory
application_username
application_password
screening_interface_impl
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/pcs/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.
log_duration: (Integer) Number of days before rotating the log file.
audit_log_directory: (String) Should not be changed.
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. This setting has a service provider override option.
password_length: (Integer) Minimum number of characters allowed in a password. This setting has a service provider override option.
number_mask: (String) Determines how phone numbers appear. Lowercase ‘d’ represents a digit 0-9. Uppercase ‘D’ represents a digit 0-9 or an ‘X’ (denoting any digit). A lowercase ‘x’ denotes any character. Braces ({}) denote an optional grouping that will only be filled after all other groupings are filled. All other characters are taken literally as they are written but are not taken as part of the value when saving. Treat these as visual separators only. This setting has a service provider override option.
default_cc: (String) The Default Country Code. This is prepended to Numbers and List Entries that are provisioned without a country code.
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 to determine callflow.
egress_route: (String) The host to use when connecting a call to the called party. This setting has a service provider override option.
reject_with_media: (Boolean) If true, any disconnect treatments will play a message before disconnecting the call. This setting has a service provider override option.
voicemail_service_location: (String) SIP address to connect calls to when the voice mail treatment is selected. If only a hostname or IP address is provided, the called number will be used for the user. This setting has a service provider override option.
sip_routing_prefix: (String) A value prepended to the called party’s SIP address when connecting a call to the called party. This setting has a service provider override option.
use_contact: (Boolean) If true, the host from the Contact header of the INVITE will be used as the egress_route. This setting has a service provider override option.
default_treatment: (String: “continue”, “terminate”, “terminate_solicitor”, “voicemail”) The treatment used when an error is encountered determining the screening rules, including reaching the end of the enabled rules.
ring_while_contacting_called_party: (String: “silence”, “ulaw”, “alaw”) What to play while the called party is being presented with the recorded greeting menu. Available options are Silence, μLaw 440/480 Hz Ringtone, or aLaw 440/480 Hz Ringtone. This setting has a service provider override option.
drop_anonymous_calls: (Boolean) If true, any call determined to be anonymous will be immediately dropped. A call is considered to be anonymous when the calling number either has “anonymous” populated in the user part of the From header or has a Privacy header configured. This setting has a service provider override option.
Contains settings related to called number source configuration.
source: (String: “request_uri”, “hdr.to”, “hdr.diversion”) The source that the called number is pulled from.
policy: Contains policy settings.
user_phone_missing_context: (String) The configured ‘;phone-context=’ value is used if the URI is being treated as a tel-URI and the number is not global and does not contain an existing ‘phone-context’ parameter.
attempt_implicit_user_phone: (Boolean) If true, the user part of the called source will be processed as ‘;user=phone’ even if that is not present.
heuristic_digits: (String: “longest-digit-substring”, “as-is”) ‘Longest Digit Substring’ uses the longest substring of digits 0-9 present in the user part of the SIP URI as the digits. If there are two or more substrings that meet this criteria, the first one is used. ‘As Is’ uses the user part of the SIP URI as the digits.
post: Contains post-processing settings.
strip_prefix: Requires a
prefixproperty with a string. If that string is found to be a prefix of thedigitsproperty of the number object, that prefix is removed, thedigitsproperty is set to the remainder, and theprefixproperty is set on the number object with that prefix. Otherwise, the number object is returned unchanged.extract_substring: Requires a
rangeproperty which is an array of two numbers. These numbers indicate the interval to extract from thedigitsproperty of the number object being processed. The interval includes the first number and excludes the second. Any other parts of thedigitsproperty are discarded.set_cc: Requires a
country_codeproperty which must be a valid country code string. This is set on the number object as thecountry_codeproperty. If the object had acontextproperty, this property is removed.default_cc: Requires a
country_codeproperty which must be a valid country code string. This behaves as forset_cc, unless acountry_codeproperty already exists on the number object.require_digits: When evaluated, an error is generated if the
digitsproperty of the number object contains any non-digit characters. Additionally, whenmin_lengthis specified, if the length of thedigitsproperty is less than the number, an error will be raised.
source: (String: “hdr.from”, “hdr.diversion”, “hdr.p_asserted_identity”, “hdr.history_info”) The source that the calling number is pulled from.
policy: Contains policy settings.
user_phone_missing_context: (String) The configured ‘;phone-context=’ value is used if the URI is being treated as a tel-URI and the number is not global and does not contain an existing ‘phone-context’ parameter.
attempt_implicit_user_phone: (Boolean) If true, the user part of the called source will be processed as ‘;user=phone’ even if that is not present.
heuristic_digits: (String: “longest-digit-substring”, “as-is”) ‘Longest Digit Substring’ uses the longest substring of digits 0-9 present in the user part of the SIP URI as the digits. If there are two or more substrings that meet this criteria, the first one is used. ‘As Is’ uses the user part of the SIP URI as the digits.
post: Contains post-processing settings.
strip_prefix: Requires a
prefixproperty with a string. If that string is found to be a prefix of thedigitsproperty of the number object, that prefix is removed, thedigitsproperty is set to the remainder, and theprefixproperty is set on the number object with that prefix. Otherwise, the number object is returned unchanged.extract_substring: Requires a
rangeproperty which is an array of two numbers. These numbers indicate the interval to extract from thedigitsproperty of the number object being processed. The interval includes the first number and excludes the second. Any other parts of thedigitsproperty are discarded.set_cc: Requires a
country_codeproperty which must be a valid country code string. This is set on the number object as thecountry_codeproperty. If the object had acontextproperty, this property is removed.default_cc: Requires a
country_codeproperty which must be a valid country code string. This behaves as forset_cc, unless acountry_codeproperty already exists on the number object.require_digits: When evaluated, an error is generated if the
digitsproperty of the number object contains any non-digit characters. Additionally, whenmin_lengthis specified, if the length of thedigitsproperty is less than the number, an error will be raised.
Contains settings for automated email messages for password changes.
use_email: (Boolean) If true, activation and recovery email messages will be sent.
host: (String) Host for email client to send messages through.
user: (String) Username for email service that 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.
Note
To enable the service provider override option for any applicable settings, format the setting as follows:
{
"settings": {
"__override__": {
"web_settings": {
"password_length": true
}
}
}
}
Endpoints
/pcs/api/settings/
GET - Retrieve the settings for the current user.
PUT - Modify the settings.
The following common responses may be encountered while using the PCS 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 PCS installed, the following message will be seen.
curl -X POST \
-H "Content-Type:application/json" \
<niu-ha>/pcs/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 /pcs/api/authenticate was not found on this server.</p>
</body></html>
Note
This response is not controlled by the PCS 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":"pcs_administrator"}' \
localhost/pcs/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: pcs_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/pcs
< 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": "Personalized Call Screening",
"short_name": "pcs",
"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/pcs/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: pcs_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/pcs
< 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": "Personalized Call Screening",
"short_name": "pcs",
"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/pcs/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: pcs_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/pcs
< 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": "Personalized Call Screening",
"short_name": "pcs",
"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/pcs/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: pcs_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/pcs
< 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": "Personalized Call Screening",
"short_name": "pcs",
"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/pcs/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: pcs_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/pcs
<
* 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/pcs/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: pcs_sessionid=<cookie>; expires=<datetime>; httponly; Max-Age=1209600; Path=/pcs
< 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": "Personalized Call Screening",
"short_name": "pcs",
"author": "IMSWorkX, Inc."
}
}
The above responses can be seen as responses from a stable PCS 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/pcs/logs/audit-logs and are named audit-<year>.<month>.<day>.log.