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

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

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 NPS for:

• rgid Optional. Returns the NPS for the Team or Department with this Support Group Code. When omitted, the endpoint will return your overall NPS.
• sgid Optional. Returns the NPS for this Customer Segment. Can't be used if combine or rgid specified.
• combine  Optional.  When y, returns the NPS based on all surveys received for the Department and the Teams that belong to that Department. When n, returns the NPS based just on the surveys received for the Department. This parameter is ignored when the Support Group Code specifies a Team rather than a Department. Defaults to n. You can learn more about how the combine parameter works, in this article.

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

• 30d Optional. This parameter requires no value. Returns the NPS based on surveys received in the last 30 days (30-Day NPS).
• eom Optional. This parameter requires no value. Returns the NPS based on all surveys received in the previous calendar month.
• period Optional. Returns the NPS for the specified month, e.g. period=2019-11.  Cannot be the current month.
• fromperiod and toperiod Optional. Returns the NPS based on all surveys received in this period range, e.g. fromperiod=2019-01&toperiod=2019-06. The range cannot included the current month.

The JSON returned by the API endpoint looks like this:

[{"entity_name":"Demo Corp","entity_code":"ABC123","entity_type":"Organisation","combined_status":"Not applicable","nps_30_day":"88","response_count":"305","promoter_count":"275","passive_count":23,"detractor_count":"7","promoter_percent":90,"passive_percent":8,"detractor_percent":2,"confidence_internal_low":86,"confidence_interval_high":90,"calculation_timestamp":"2018-09-23 06:20:01","timezone":"(GMT-08:00) Pacific Time (US & Canada)"}]

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. both rgid and sgid >specified).
• 404 No Net Promoter score found that matches 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 Net Promoter Score found that matched this criteria","status":404}