CIOPulse Knowledge Base

1.1 Contacts API v5

Updated on

By using the Contacts API endpoint you can:

  • Add or edit a Contact with an HTTP PUT request and providing the contact's information as a JSON payload.
  • Delete a Contact using an HTTP DELETE request.
  • Retrieve contact information for one or all Contacts using an HTTP GET request.

A common use of the Contacts endpoint is to keep CIOPulse contact information in sync with your customer support software.

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].

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 Contacts

Adding a new Contact

Updating a Contact

Deleting a Contact

Retrieving Contact 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 Contacts

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

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

{system_id} is a unique identifier for the Contact you are adding or updating, e.g. the Unique ID of an agent from your customer support software.

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

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

{
"first_name": "Tim",
"last_name": "Test",
"job_title": null,
"email": "[email protected]",
"mobile": "+61411112233"
}

The fields allowed in the JSON payload are:

  • first_name is the first name of the Contact.
  • last_name is the last name of the Contact.
  • email is the email address of the Contact. It must be a valid email address and must be unique - two contacts cannot share the same email address.
  • job_title is the job title of the Contact.
  • mobile is the mobile phone number of the Contact. It is required if you wish CIOPulse to send SMS alerts to this Contact. It must start with a "+" followed by a country code and the phone number with the leading zero removed. No spaces or hyphens are allowed.

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

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

The Contacts endpoint behaves as follows:

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

Adding a new Contact

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

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

  • first_name
  • last_name
  • email

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

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

$payload_json = '{   
	"first_name": "Ajay",
	"last_name": "Patel",
	"email": "[email protected]"
}';

$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/contacts/80a45geb4faec211f6a144g18110c73d');

curl_exec($curl_session);

Updating a Contact

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

When updating a Contact, any 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 Contact's mobile number, remove the job title and leave the other fields unchanged:

{"mobile": "+61444111222","job_title": null}

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

Deleting a Contact

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

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

{system_id} is a unique identifier for the Contact you are deleting, e.g. the Unique ID of the agent from your customer support software.

The Contact to be deleted must not be the Support Lead or Also Alert for any Support Group.

Retrieving Contact information

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

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

{system_id} is a unique identifier for the Contact you wish to retrieve information for, e.g. the Primary Key value of the person from your customer support software.

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

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

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 Contacts):

{"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: Contact updated or information successfully retrieved.
  • 201 Success: Contact created.
  • 202 Success: Contact 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 Contact with this System ID was not found.
  • 422 Another Contact already has this email address.
  • 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}
Next Article 1.2 Support Groups API v5

Our API & Webhooks

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