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 Relationship Surveys endpoint to add or edit a Relationship Survey, issue an HTTP PUT request with this URL:

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

{system_id} is a unique identifier for the Relationship Survey you are adding or updating, e.g. the Unique ID of the Project from your customer support or project management software. This is often the same as the relationship_survey_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 Relationship Survey you wish to add or update.

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

{
"survey_name": "CRM Version 3 Upgrade Project",
"survey_code": "project123",
"invitation_count": 150,
"close_date_gmt": "2021-02-28",
"survey_series_code": "projects"
}

The fields allowed in the JSON payload are:

• survey_name is the name of the Relationship Survey.
• survey_code is the unique Relationship Survey Code that can be used in the rsid= parameter when requesting a Relationship Survey Responses report or viewing a relationship survey dashboard.
• invitation_count is the number of people you are inviting to complete the survey.
• close_date_gmt is the close date of the survey (GMT) in yyyy-mm-dd format. Surveys received after this date will not be used for calculating the NPS for this survey.
• survey_series_code is the Series Code of the Series you wish this Survey to be part of.  If you don't want this Relationship Survey to be linked to a Series, use null. Do not surround null with quotes. null must be in lowercase.

The Relationship Survey API endpoint behaves as follows:

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

To use the Relationship Surveys endpoint to delete a Relationship Survey, issue an HTTP DELETE request with this URL:

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

{system_id} is a unique identifier for the Relationship Survey you are deleting.

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

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

{system_id} is a unique identifier for the Relationship Survey you wish to retrieve information for.

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

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

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

The Relationship Survey information returned by the API looks like this (which shows 3 Relationship Surveys):

{"relationship_surveys":[

{"relationship_survey":{"Relationship_Survey_System_ID":"sysid-001","Survey_Code":"TEST001",
"Survey_Name":"Survey 123",
"Series_Code":"NONE","Series_Name":"No Series",
"Invitation_Count":99,"Close_Date_GMT":"2021-12-31"}},

{"relationship_survey":{"Relationship_Survey_System_ID":"sysid-002","Survey_Code":"TEST002",
"Survey_Name":"Survey 456",
"Series_Code":"NONE","Series_Name":"No Series",
"Invitation_Count":50,"Close_Date_GMT":"2022-02-28"}},

{"relationship_survey":{"Relationship_Survey_System_ID":"sysid-003","Survey_Code":"TEST003",
"Survey_Name":"Survey 789",
"Series_Code":"TEST","Series_Name":"Testing",
"Invitation_Count":150,"Close_Date_GMT":"2021-11-30"}}

]}

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

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