V5 ITSM API

The ciopulse V5 REST API lets your ITSM or scripts keep ciopulse in sync automatically — pushing your support groups, contacts and segments — and pull survey results back out for your own reporting.

If you only need to send surveys, you don’t need the API — a survey URL or the ServiceNow app is enough. Use the API when you want to automate data sync or extract responses.

Base URL

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

Authentication

Every request is authenticated with your Portal Code and API Key. You’ll find the API Key in the Portal under Preferences. Keep it secret — treat it like a password.

You can authenticate in any of these ways:

• HTTP Basic Auth (recommended) — username is your Portal Code, password is your API Key:

  curl -u "YOURCODE:your_api_key" https://app.cio-pulse.com/api/v5/support-groups

• Authorization header — Base64-encode portal_code:api_key:

  curl -H "Authorization: Basic $(echo -n 'YOURCODE:your_api_key' | base64)" \
    https://app.cio-pulse.com/api/v5/support-groups

• X-API-Key header — pass the key in the header and your Portal Code in the URL:

  curl -H "X-API-Key: your_api_key" \
    "https://app.cio-pulse.com/api/v5/support-groups?portal_code=YOURCODE"

Caution

If you’ve restricted access by IP address in the Portal, API calls must also come from an allowed IP range.

Reference data — keep ciopulse in sync

These resources let you create, update, read and delete the data ciopulse uses to organise feedback. Each record is keyed by your ITSM’s own identifier (for ServiceNow, the sys_id), so you can upsert directly from your system.

Resource	Endpoint	Methods
Support Groups	/support-groups	GET, PUT (add/update), DELETE
Contacts	/contacts	GET, PUT, DELETE
Segments	/segments	GET, PUT, DELETE
Relationship Surveys	/relationship-surveys	GET, PUT, DELETE

A typical use case is a scheduled job in your ITSM that upserts your assignment groups and their support leads into ciopulse so the two stay aligned without manual updates.

How create / update / delete behave

• The system ID goes in the URL, e.g. PUT /api/v5/support-groups/{system_id}. The body is a JSON payload for a single record.
• PUT is an upsert: if no record with that system ID exists, it’s created; if one exists, it’s updated.
• On update, a field you omit is left unchanged; a field set to null (lowercase, unquoted) is cleared; a field with a value is updated.
• Dependencies: Support Groups reference Contacts by system ID, so maintain Contacts before Support Groups. A Contact who is a Support Lead or Also Alert can’t be deleted; a Support Group with responses can’t be deleted (set it inactive instead).
• Add &clean to a write to auto-replace invalid characters (em dashes, colons) in names with hyphens. Never include a backslash (\) in the JSON.

Key fields

• Contacts — first_name, last_name, email (unique; mandatory on create), job_title, mobile (+country code, no spaces).
• Support Groups — support_group_name, support_group_code, support_lead_system_id, department_system_id (null = it’s a Department), also_alert_1_system_id…also_alert_6_system_id, ccs_only (y/n), active (y/n).
• Segments — segment_code, segment_name, active.
• Relationship Surveys — survey_name, survey_code, invitation_count, close_date_gmt, survey_series_code (null = no series).

Survey data — pull results out

These read-only GET endpoints return your survey results and scores in JSON.

Data	Endpoint
Transactional survey responses	/ts-surveys
Relationship survey responses	/rs-surveys
CCS responses	/ccs-surveys
Transactional NPS score	/ts-score
Experience factor labels	/factor-labels
Service Recovery — timeliness of first call	/service-recovery/timeliness-of-first-call

Common query parameters (prefix the first with ?, the rest with &):

• Scope: rgid (Support Group) with combine=y/n, tid (ticket), cid (customer), agid (agent), sgid (segment). For relationship responses, rsid is required.
• Time window: isofrom / isoto in ISO-8601 UTC (2026-06-13T16:30:00Z, always with the trailing Z, no offset), eom (previous calendar month), or limit (most recent N). These are mutually exclusive.
• Filter: min / max rating (1–10).

A single call returns at most 10,000 responses (a 422 is returned if your filters would exceed that). In responses, the eight experience factors are encoded as 1 (selected by a Promoter), -1 (selected by a Passive/Detractor) or 0 (not selected), and SR_Notes holds any Service Recovery Note (otherwise null).

Webhooks

If you’d rather receive results as they happen than poll for them, ciopulse can push each completed survey to an endpoint you host — available for transactional and relationship surveys. Turn them on in Preferences → Integration: set the webhook URL and, if your endpoint needs it, an HTTP Basic username and password (the password is stored encrypted).

• ciopulse POSTs the single response as JSON within a few minutes of submission.
• If your endpoint doesn’t return HTTP 200, ciopulse retries up to 4 times (5 attempts total) at increasing gaps — roughly 5, 10, 20 then 40 minutes — before marking it failed.
• Every call is recorded in the Portal’s Webhook Log, where you can inspect the payload/response and click Resend.
• If your endpoint expects ServiceNow’s wrapper, ask support to enable the ServiceNow payload format.

Error codes

API calls return standard HTTP codes: 200 success (updated/retrieved), 201 created, 202 deleted; 400 malformed/invalid parameters, 401 bad credentials, 404 not found, 422 business-rule violation (e.g. >10,000 results, or max < min), 500 server error. Every error also returns a JSON description.

Still need help? Email support@cio-pulse.com.