On Sunday 2 August 2020, we are releasing Version 5 of our API.
Version 5 is more secure, has a new Segments endpoint, includes some new fields in the Transactional and CCS survey responses, and enables you to retrieve Segments, Contacts and Support Groups.
All previous versions of our API will continue to function until 31 January 2021, when they will be retired.
Please plan to migrate to Version 5 of our API sometime between 2 August 2020 and 31 January 2021.
Documentation on Version 5 can be found here with the article headings suffixed with "v5 (Being released 2 August 2020)"
Changes to security
In versions of our API prior to Version 5, your Portal Code and API Key are part of the URL of the API call.
In version 5, the Portal Code and API Key need to be included in the HTTP request header instead of the URL. 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 Portal Code, a single colon, and your API Key (found in the Preferences of the Portal).
New endpoint for Segments
Version 5 includes a new API endpoint for adding, updating, deleting and retrieving Segments:
https://app.cio-pulse.com/api/v5/segmentsNew ability to retrieve Contacts and Support Groups
Version 5 of the Contacts and Support Groups endpoints enable you to issue a GET request to retrieve the information about one or all Contacts or Segments.
Changes to endpoint names
- Add/update/delete/retrieve a Contact:
https://app.cio-pulse.com/api/v5/contacts - Add/update/delete/retrieve a Support Group:
https://app.cio-pulse.com/api/v5/support-groups - Add/update/delete/retrieve a Segment:
https://app.cio-pulse.com/api/v5/segments(new endpoint) - Retrieve Transactional Surveys:
https://app.cio-pulse.com/api/v5/ts-surveys - Retrieve CCS Surveys:
https://app.cio-pulse.com/api/v5/ccs-surveys - Retrieve a Transactional NPS:
https://app.cio-pulse.com/api/v5/ts-score
System ID moved to URL
Prior to Version 5, API PUT requests required the System ID of the Contact or Support Group being added or updated, to be specified in the JSON payload in the system_id field.
In Version 5, PUT, GET and DELETE requests require the System ID to be included in the URL. E.g. To add/update/delete/retrieve a Support Group with a System ID of abc123def456:
https://app.cio-pulse.com/api/v5/support-groups/abc123def456Preservation of field values when updating
When using the Version 5 Contact, Support Group or Segment endpoint to perform an update, the value of any fields not included in the JSON payload are now preserved.
The Version 4 Support Group endpoint already behaves this way.
Version 3 Contact and Support Group endpoints require all fields to be specified in the JSON payload. And so, with Version 3, there is no way to preserve existing values without specifying them in the JSON.
New data returned by Transactional & CCS Surveys endpoints
The Transactional Surveys endpoint now returns three new fields in addition to the existing fields: SR Notes, Survey Description and Survey Language. SR Notes contain any Service Recovery Notes completed for the survey (otherwise the field will contain null).
The CCS Surveys endpoint now returns two new fields in addition to the existing fields: Survey Description and Survey Language.
If you have any questions about these changes, please email us at [email protected]