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 Transactional Survey Responses endpoint, use the HTTP GET method with this URL:

https://app.cio-pulse.com/api/v5/ts-surveys

You can add any of the following parameters to this URL to define your filters. The first parameter must be prefixed with a ? and all subsequent parameters with a &:

These parameters define the entity you want to return the surveys for:

• rgid Optional. Return survey responses for the Team or Department with this Support Group Code.
• combine  Optional.  Only used when rgid specified. When y, returns survey responses for the Department and for the Teams that belong to that Department. When n, returns survey responses just for the Department. This parameter is ignored when the Support Group Code specifies a Team rather than a Department. You can learn more about how the combine parameter works, in this article.
• tid. Optional. Specify a ticket id to return the survey response for this Ticket.
• cid Optional. Specify a customer id to return the survey responses from this Customer.
• agid Optional. Specify an agent id to return the survey responses for this Agent.
• sgid Optional. Return survey responses for this Customer Segment.

These parameters define the period of time you want to return the surveys for:

• limit Optional. Specify a number, n, to limit the number of survey responses to the most recent n surveys that meet the selection criteria. n must be 10000 or less. Cannot be used with the isofrom, isoto or eom parameters.
• isofrom Optional. Return responses received on or after this UTC/GMT date/time. The date/time must be in ISO8601 format:  yyyy-mm-ddThh:mm:ssZ, e.g. 2016-10-13T16:30:00Z. Cannot be used with the limit or eom parameters.
• isoto Optional.  Return responses received on or before this UTC/GMT date/time. The date/time must be in ISO8601 format:  yyyy-mm-ddThh:mm:ssZ, e.g. 2016-10-14T16:29:59Z. Cannot be used with the limit or eom parameters.
• eom Optional. Returns surveys from the previous month (GMT). Cannot be used with the isofrom, isoto or limit parameters.

Additional filter parameters:

• min Optional. Returns survey responses where overall satisfaction rating > = this value (1-10).
• max Optional. Returns survey responses where overall satisfaction rating < = this value (1-10).

The surveys returned by the API look like this (which shows three surveys):

{"surveys":[

{"survey":{"Response_ID":"3621","Response_Datetime_UTC":"2020-07-08 20:27:52","Ticket_ID":"INC222333","Support_Group_Code":"DEMOSD","Support_Group_Name":"Service Desk","Agent_ID":"Adam","Segment_Code":"UK","Segment_Name":"United Kingdom","Customer":"Carole","Responsiveness":"-1","Interpersonal":"0","Knowledge":"-1","Communication":"0","Speed":"0","Confirmation":"0","Effort":"0","Other":"0","Overall":"4","Comments":"feedback","SR_Notes":null,"Survey_Description":"English new TS survey","Survey_Language":"English"}},

{"survey":{"Response_ID":"3622","Response_Datetime_UTC":"2020-07-08 20:27:52","Ticket_ID":"INC04072001","Support_Group_Code":"DEMOSD","Support_Group_Name":"Service Desk","Agent_ID":"Adam","Segment_Code":"AUS","Segment_Name":"Australia-APAC","Customer":"Carole","Responsiveness":"-1","Interpersonal":"0","Knowledge":"0","Communication":"0","Speed":"0","Confirmation":"0","Effort":"0","Other":"0","Overall":"1","Comments":"Too slow to pick up phone","SR_Notes":"Sunday, 5 Jul 2020 - [email protected] (Spoke? No): Here are some notes\nMonday, 6 Jul 2020 - Sam Special (Spoke? No): I range Carole and explained our Service Desk Hours (she needed help on a Saturday) and how she can get help in an emergency outside of those hours\nMonday, 6 Jul 2020 - Sam Special (Spoke? No): Have published Service Desk hours on front page of Portal","Survey_Description":"English new TS survey","Survey_Language":"English"}},

{"survey":{"Response_ID":"3623","Response_Datetime_UTC":"2020-07-08 20:27:52","Ticket_ID":"INC04072002","Support_Group_Code":"DEMOSD","Support_Group_Name":"Service Desk","Agent_ID":"Adam","Segment_Code":"AUS","Segment_Name":"Australia-APAC","Customer":"Carole","Responsiveness":"0","Interpersonal":"0","Knowledge":"0","Communication":"0","Speed":"-1","Confirmation":"0","Effort":"0","Other":"0","Overall":"5","Comments":"Way to long to fix","SR_Notes":"Monday, 6 Jul 2020 - Sam Special (Spoke? Yes): Spoke to Carole and promised I'd look int this","Survey_Description":"English new TS survey","Survey_Language":"English"}}

]}

Experience Factors

Within the JSON, the eight experience factors from Q2 of the survey are represented like this, e.g.

"Responsiveness":"-1"

Following the name of each experience factor will be a 0, 1 or -1.

For Detractors and Passives, the factors selected in Q2 of the survey are given as -1s.

For Promoters, the factors selected in Q2 of the survey are given as 1s.

Unselected factors are given as 0s.

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

• 401 Invalid security credentials (Client Portal Code and/or API key invalid).
• 400 Malformed syntax, e.g. missing/invalid parameters.
• 422 Valid syntax but not processed due to business rules (e.g. max > min or isoto > isofrom).
• 404 No surveys found that match the criteria specified.
• 500 Server error, e.g. database connection couldn't be established.

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

{"message":"No surveys were found that matched this criteria","status":404}