CIOPulse Knowledge Base

1.2 Support Groups API v5

Updated on

By using the Support Groups API endpoint you can:

  • Add or edit a Support Group with an HTTP PUT request and providing the Support Group's information as a JSON payload.
  • Delete a Support Group using an HTTP DELETE request.
  • Retrieve support group information for one or all Support Groups using an HTTP GET request.

A common use of the Support Groups endpoint is to keep CIOPulse Support Group information in sync with your customer support software.

The API returns data in JSON format which is readily decodable by all modern programming languages.

To use the API you must be on our Corporate or Enterprise Plan and have a 40 character API key. The key can be found in the Portal at the bottom of the Preferences page. If your key is blank, please email us at [email protected].

The Support Group API endpoint cannot be used to add or edit Support Groups unless you are also using the Contacts API endpoint to maintain your Contacts.

If you have setup IP address security in the CIOPulse Portal, the IP address of the server making the API call must be included in your list of valid IP addresses.

Authentication

Adding or Updating Support Groups

Adding a Support Group

Updating a Support Group

Deleting a Support Group

Retrieving Support Group information

Error Handling

Authentication

All our API endpoints require HTTP basic authentication as specified in RFC 7616 from 2015. The HTTP Header of your request must contain a header field in the form of:

Authorization: Basic {credentials}

Where {credentials} is the Base64 encoding of: your Client Portal Code, a single colon, and your API Key (found in the Preferences of the Portal).

Here's a snippet of PHP script using CURL to set the authentication header.

$portal_code = 'ABC123'; 
$api_key = 'SMzYECYJYLpNw8PrfX8EtPO2tcP0XaKJvZ4FW5VL';

$header = array('Authorization: Basic '. base64_encode($portal_code .":". $api_key) );

$curl_session = curl_init();
curl_setopt($curl_session, CURLOPT_HTTPHEADER, $header);

Adding or Updating Support Groups

To use the Support Groups endpoint to add or edit a Support Group, issue an HTTP PUT request with this URL:

https://app.cio-pulse.com/api/v5/support-groups/{system_id}

{system_id} is a unique identifier for the Support Group you are adding or updating, e.g. the Unique ID of the team/queue from your customer support software. This is often the same as the support_group_code, but it doesn't have to be.

Your PUT request must be accompanied by a JSON payload that carries the field values for the Support Group you wish to add or update.

The JSON payload may only contain information for a single Support Group and looks like this:

{
"support_group_name": "Service Desk",
"support_group_code": "80a45geb4faec211f6a144g18110c73d",
"support_lead_system_id": "3587d564370fc61167315aa543990e25",
"department_system_id": "7c697fc2376d9e008b795aa543990eae",
"also_alert_1_system_id": "05860aa0374bc60097315aa543990e42",
"also_alert_2_system_id": "0587e564370bc60097315aa543990e24",
"also_alert_3_system_id": null,
"also_alert_4_system_id": null,
"also_alert_5_system_id": null,
"also_alert_6_system_id": null,
"ccs_only": "n",
"active": "y"
}

To delete an existing field value, use null in the JSON. Do not surround null with quotes. null must be in lowercase

The fields allowed in the JSON payload are:

  • support_group_name is the name of the Support Group.
  • support_group_code is the unique Support Group Code that your customer support software will pass through in the rgid parameter of the transactional or CCS survey URL.
  • support_lead_system_id is the System ID of the Contact who is the Support Lead of this Support Group (as set by the Contacts API endpoint).
  • department_system_id is the System ID of a Support Group that is a Department (as set by the Support Groups API endpoint). Use this to make this Support Group a Team of this Department. When this field is set to null, the Department field of the Support Group will be set to blank, i.e. the new Support Group will be a Department (not a Team).
  • also_alert_x_system_id (where x = 1 to 6) is used to set the Also Alerts for the Support Group by setting these values to the System ID of the Contact. When set to null, the corresponding Also Alert will be set to blank.
  • ccs_only is either y or n. Set to y for Support Groups that are only used to collect Compliments, Complaints & Suggestions. When set to y, the Support Group must be a Department and not a Team.
  • active is either y or n. Set to n for Support Groups that you are no longer collecting feedback for.  A Department cannot be set to inactive if it has one or more Teams that are active. See here for more information on the 'Active?' field of Support Groups.

The Support Group API endpoint behaves as follows:

  • If a Support Group with this system_id is NOT found in the Portal, a new Support Group will be added using the values in the JSON payload.
  • If a Support Group with this system_id IS found in the Portal, the existing Support Group will be updated using the values in the JSON payload.

Add &clean to the end of your URL and any invalid characters in the support_group_name (e.g. em dashes or colons) will be replaced with hyphens when the Support Group is added or updated.

Your JSON must never include a backslash (\) anywhere within it. Backslashes will prevent your API call from working.

The support_lead_system_id and also_alert_x_system_id values must be the same value as the system_id of a Contact you have already created via the Contacts API endpoint.

The department_system_id value must be the same value as the system_id of a Support Group you have already created via this Support Group API endpoint.  The Support Group with this system_id must be a Support Group with a null department_system_id, i.e. it must be a Department.

Adding a new Support Group

If a Support Group with this system_id is not found in the Portal, a new Support Group will be added using the values in the JSON payload.

The following fields are mandatory in the JSON when adding a new Support Group:

  • support_group_name
  • support_group_code
  • support_lead_system_id

The following fields are optional in the JSON when adding a new Support Group:

  • department_system_id  (defaults to null when omitted).
  • also_alert_x_system_id (where x = 1 to 6) (defaults to null when omitted).
  • ccs_only (defaults to n when omitted).
  • active (defaults to y when omitted).

Here's a snippet of PHP script using CURL to add a new Support Group:

$portal_code = 'ABC123'; 
$api_key = 'SMzYECYJYLpNw8PrfX8EtPO2tcP0XaKJvZ4FW5VL';

$payload_json = '{   
	"support_group_code": "80a45geb4faec211f6a144g18110c73d",
	"support_group_name": "Service Desk",
	"support_lead_system_id": "PID-12345"
}';

$headers = array(
	'Authorization: Basic '. base64_encode($portal_code .":". $api_key),
	'Content-Type:application/json',
	'Content-Length: ' . strlen($payload_json)
);
	
$curl_session = curl_init();

curl_setopt($curl_session, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl_session, CURLOPT_POSTFIELDS,$payload_json);
curl_setopt($curl_session, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl_session, CURLOPT_URL, 'https://app.cio-pulse.com/api/v5/support-groups/80a45geb4faec211f6a144g18110c73d');

curl_exec($curl_session);

Note that, in this example, the System ID (used in the URL) and the Support Group Code (used in the JSON payload) are the same.

Updating a Support Group

If a Support Group with this system_id is found in the Portal, the existing Support Group will be updated.

When updating a Support Group, each of the fields allowed in the JSON may be set to a value, to null, or the field can be omitted from the JSON altogether:

  • Set to value - Update the field to this value.
  • Set to null - Set the field to 'no value'.
  • Omitted - Leave the current field value unchanged.

For example, this JSON payload would update the Support Group Name, remove the Also Alert 1 Contact and leave all other fields unchanged:

{"support_group_name": "Service Desk - Remote Outpost",
	"also_alert_1_system_id": null}

To remove a field value, use null in the JSON. NULL will not work.

Deleting a Support Group

To use the Support Groups endpoint to delete a Support Group, issue an HTTP DELETE request with this URL:

https://app.cio-pulse.com/api/v5/support-groups/{system_id}

{system_id} is a unique identifier for the Support Group you are deleting, e.g. the Primary Key value of the team/queue from your customer support software.

The Support Group to be deleted must not have any Survey Responses or CCS feedback completed for it. And it must not be a Department that has Teams belonging to it.

If you are unable to delete a Support Group, you may want to use a PUT request to update the Support Group and set it to inactive.

Retrieving Support Group information

To use the Support Groups endpoint to get the information for a single Support Group, issue an HTTP GET request with this URL:

https://app.cio-pulse.com/api/v5/support-groups/{system_id}

{system_id} is a unique identifier for the Support Group you wish to retrieve information for, e.g. the Primary Key value of the team/queue from your customer support software.

To use the Support Groups endpoint to get the information for all Support Groups, issue an HTTP GET request without the system id:

https://app.cio-pulse.com/api/v5/support-groups

A normal response will result in an HTTP response code of 200 being returned in the header.

The support group information returned by the API looks like this (which shows 3 Support Groups):

{"support_groups":[

{"support_group":{"Support_Group_System_ID":"TEAM123","Support_Group_Name":"Service Desk","Support_Group_Code":"SDESK","Department_Code":"SDEL","Department_System_ID":"TEAM789","Support_Lead_Email":"[email protected]","Support_Lead_System_ID":"CONTACT123","Also_Alert_1_Email":"[email protected]","Also_Alert_1_System_ID":CONTACT456,"Also_Alert_2_Email":null,"Also_Alert_2_System_ID":null,"Also_Alert_3_Email":null,"Also_Alert_3_System_ID":null,"Also_Alert_4_Email":null,"Also_Alert_4_System_ID":null,"Also_Alert_5_Email":null,"Also_Alert_5_System_ID":null,"Also_Alert_6_Email":null,"Also_Alert_6_System_ID":null,"Active":"Y","CCS_Only":"N","Exclude_From_NPS":"N"}},

{"support_group":{"Support_Group_System_ID":"TEAM456","Support_Group_Name":"Complaints Department","Support_Group_Code":"CCS","Department_Code":"SDEL","Department_System_ID":"TEAM789","Support_Lead_Email":"[email protected]","Support_Lead_System_ID":"CONTACT456","Also_Alert_1_Email":null,"Also_Alert_1_System_ID":null,"Also_Alert_2_Email":null,"Also_Alert_2_System_ID":null,"Also_Alert_3_Email":null,"Also_Alert_3_System_ID":null,"Also_Alert_4_Email":null,"Also_Alert_4_System_ID":null,"Also_Alert_5_Email":null,"Also_Alert_5_System_ID":null,"Also_Alert_6_Email":null,"Also_Alert_6_System_ID":null,"Active":"Y","CCS_Only":"N","Exclude_From_NPS":"N"}},

{"support_group":{"Support_Group_System_ID":"TEAM789","Support_Group_Name":"Service Delivery","Support_Group_Code":"SRVD","Department_Code":null,"Department_System_ID":null,"Support_Lead_Email":"[email protected]","Support_Lead_System_ID":"CONTACT789","Also_Alert_1_Email":null,"Also_Alert_1_System_ID":null,"Also_Alert_2_Email":null,"Also_Alert_2_System_ID":null,"Also_Alert_3_Email":null,"Also_Alert_3_System_ID":null,"Also_Alert_4_Email":null,"Also_Alert_4_System_ID":null,"Also_Alert_5_Email":null,"Also_Alert_5_System_ID":null,"Also_Alert_6_Email":null,"Also_Alert_6_System_ID":null,"Active":"Y","CCS_Only":"N","Exclude_From_NPS":"N"}}

]}

Error Handling

A successful API call will result in one of these codes being returned in the HTTP header:

  • 200 Success: Support Group updated or information successfully retrieved .
  • 201 Success: Support Group created.
  • 202 Success: Support Group deleted.

If there is a problem, one of these error codes will be returned in the HTTP header:

  • 400 Field value invalid or missing or JSON is malformed.
  • 401 Invalid security credentials (portal code and/or API key missing or invalid).
  • 404 A Support Group with this System ID was not found.
  • 422 Another Support Group already has this Support Group Code.
  • 500 Transaction failed. Contact CIOPulse support for assistance.

In each of these error situations, a description of the error will also be returned in JSON format.

{"message":"Invalid security credentials","status":401}
Previous Article 1.1 Contacts API v5
Next Article 1.3 Segments API v5

Our API & Webhooks

1. Reference Data 3
2. Transactional Surveys 3
3. Relationship Surveys 3
4. Compliments, Complaints & Suggestions 1