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);

To use the Segments endpoint to add or edit a Segment, issue an HTTP PUT request with this URL:

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

{system_id} is a unique identifier for the Segment you are adding or updating, e.g. the Unique ID of a business unit or location from your customer support software.

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

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

{
"segment_name": "Victoria",
"segment_code": "VIC",
"active":"y"
}

The fields allowed in the JSON payload are:

• segment_code is the unique Segment Code that your customer support software will pass through in the sgid parameter of the transactional survey URL, or the rgid1 or rgid2 parameters of the relationship survey URL.
• segment_name is the name of the Segment.
• active is either y or n. Set to n for Segments that you are no longer collecting feedback for. Inactive segments will not appear on the Customer Segment League Table or in the Segments filter of your interactive dashboards.

The Segment endpoint behaves as follows:

• If a Segment with this system_id is NOT found in our database, a new Segment record will be created using the values in the JSON payload.
• If a Segment with this system_id IS found in our database, the existing Segment record will be updated as per the JSON payload.

To use the Segments endpoint to delete a Segment, issue an HTTP DELETE request with this URL:

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

{system_id} is a unique identifier for the Segment you are deleting, e.g. the Unique ID of the business unit or location from your customer support software.

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

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

{system_id} is a unique identifier for the Segment you wish to retrieve information for, e.g. the Primary Key value of the business unit or location from your customer support software.

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

https://app.cio-pulse.com/api/v5/segments

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

The segment information returned by the API looks like this (which shows 3 Segments):

{"segments":

[{"segment":{"Segment_System_ID":"SEG123","Segment_Code":"NZ","Segment_Name":"New Zealand","Active":"Y"}},

{"segment":{"Segment_System_ID":"SEG456","Segment_Code":"AUS","Segment_Name":"Australia","Active":"Y"}},

{"segment":{"Segment_System_ID":"SEG789","Segment_Code":"EMEA","Segment_Name":"EMEA","Active":"Y"}},

]}

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

• 200 Success: Segment updated or information retrieved successfully.
• 201 Success: Segment created.
• 202 Success: Segment 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 Segment with this System ID was not found.
• 422 Another Segment already has this Segment 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}