Skip to main content
GET
/
v1
/
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));
{
  "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
}

​
List Response Sets

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

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Path Parameters

​
dataset_id
string
required
UUID of the dataset
​
campaign_id
string
required
UUID of the campaign

​
Query Parameters

​
page
integer
default:"1"
Page number (min 1)
​
size
integer
default:"20"
Items per page (1–100)

​
Response

​
items
array[object]
List of response sets
​
items[].id
string
Response set UUID
​
items[].campaign_assignment_id
string
UUID of the campaign assignment this response belongs to
​
items[].submitted_at
string
ISO 8601 timestamp of submission
​
items[].submitter_email
string | null
Email of the person who submitted
​
items[].data_owner_email
string
Email of the assigned data owner
​
items[].organization_name
string
Organization name of the recipient
​
items[].facility_name
string | null
Facility name, if the assignment is facility-scoped
​
items[].values
array[object]
Submitted KPI values
​
items[].values[].kpi_id
string
KPI UUID
​
items[].values[].kpi_name
string
KPI display name
​
items[].values[].value_numeric
number | null
Numeric value (for NUMBER/PERCENTAGE KPIs)
​
items[].values[].value_text
string | null
Text value (for TEXT/SELECT KPIs)
​
items[].values[].value_date
string | null
Date value (for DATE KPIs)
​
items[].attachments
array[object]
File attachments included with the submission
​
total
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}"

​
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