List Response Sets

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": {},
  "items[].id": "<string>",
  "items[].campaign_assignment_id": "<string>",
  "items[].submitted_at": "<string>",
  "items[].submitter_email": {},
  "items[].data_owner_email": "<string>",
  "items[].organization_name": "<string>",
  "items[].facility_name": {},
  "items[].values": {},
  "items[].values[].kpi_id": "<string>",
  "items[].values[].kpi_name": "<string>",
  "items[].values[].value_numeric": {},
  "items[].values[].value_text": {},
  "items[].values[].value_date": {},
  "items[].attachments": {},
  "total": 123
}

GET

custom-kpi-datasets

{dataset_id}

campaigns

{campaign_id}

response-sets

List Response Sets

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": {},
  "items[].id": "<string>",
  "items[].campaign_assignment_id": "<string>",
  "items[].submitted_at": "<string>",
  "items[].submitter_email": {},
  "items[].data_owner_email": "<string>",
  "items[].organization_name": "<string>",
  "items[].facility_name": {},
  "items[].values": {},
  "items[].values[].kpi_id": "<string>",
  "items[].values[].kpi_name": "<string>",
  "items[].values[].value_numeric": {},
  "items[].values[].value_text": {},
  "items[].values[].value_date": {},
  "items[].attachments": {},
  "total": 123
}

← Custom KPI Retrieve a paginated list of all survey submissions (response sets) in a campaign. Each response set includes the submitted KPI values, file attachments, and recipient information.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

string

required

UUID of the dataset

string

required

UUID of the campaign

Query Parameters

integer

default:"1"

Page number (min 1)

integer

default:"20"

Items per page (1–100)

Response

array[object]

List of response sets

string

Response set UUID

string

UUID of the campaign assignment this response belongs to

string

ISO 8601 timestamp of submission

string | null

Email of the person who submitted

string

Email of the assigned data owner

string

Organization name of the recipient

string | null

Facility name, if the assignment is facility-scoped

array[object]

Submitted KPI values

string

KPI UUID

string

KPI display name

number | null

Numeric value (for NUMBER/PERCENTAGE KPIs)

string | null

Text value (for TEXT/SELECT KPIs)

string | null

Date value (for DATE KPIs)

array[object]

File attachments included with the submission

integer

Total number of response sets

Example

curl "https://api.dcycle.io/v1/custom-kpi-datasets/${DATASET_ID}/campaigns/${CAMPAIGN_ID}/response-sets?page=1&size=10" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

response = requests.get(
    f"https://api.dcycle.io/v1/custom-kpi-datasets/{os.getenv('DATASET_ID')}"
    f"/campaigns/{os.getenv('CAMPAIGN_ID')}/response-sets",
    headers={
        "x-api-key": os.getenv("DCYCLE_API_KEY"),
        "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    },
    params={"page": 1, "size": 10},
)

data = response.json()
print(f"{data['total']} total submissions")
for rs in data["items"]:
    print(f"  {rs['data_owner_email']} ({rs['organization_name']}): {len(rs['values'])} values")

const axios = require('axios');

const response = await axios.get(
  `https://api.dcycle.io/v1/custom-kpi-datasets/${process.env.DATASET_ID}/campaigns/${process.env.CAMPAIGN_ID}/response-sets`,
  {
    headers: {
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
    },
    params: { page: 1, size: 10 },
  }
);

console.log(`${response.data.total} total submissions`);
response.data.items.forEach(rs =>
  console.log(`  ${rs.data_owner_email} (${rs.organization_name}): ${rs.values.length} values`)
);

Successful Response

{
  "items": [
    {
      "id": "response-set-uuid",
      "campaign_assignment_id": "assignment-uuid",
      "submitted_at": "2025-03-15T14:30:00Z",
      "submitter_email": "ana@acme.com",
      "submitter_user_id": "user-uuid",
      "data_owner_email": "ana@acme.com",
      "organization_name": "Acme Corp",
      "facility_name": "Madrid Office",
      "values": [
        {
          "kpi_id": "kpi-uuid-1",
          "kpi_name": "Water consumption",
          "kpi_unit": "m³",
          "value_numeric": 1250.5,
          "value_text": null,
          "value_date": null
        },
        {
          "kpi_id": "kpi-uuid-2",
          "kpi_name": "Recycling policy",
          "kpi_unit": null,
          "value_numeric": null,
          "value_text": "Yes",
          "value_date": null
        }
      ],
      "attachments": [
        {
          "file_id": "file-uuid",
          "file_name": "water-bill-q1.pdf",
          "file_url": "https://..."
        }
      ]
    }
  ],
  "total": 15
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

404 Not Found

Cause: The dataset or campaign does not exist or belongs to another organization

{"detail": "Not Found"}

List Campaign Values

View aggregated values across all recipients

Get Campaign

View campaign details

​Request

​Headers

​Path Parameters

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

List Campaign Values

Get Campaign

Request

Headers

Path Parameters

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints