List Campaigns

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', 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"

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

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

print(response.text)

{
  "id": "<string>",
  "name": "<string>",
  "period_start": "<string>",
  "period_end": "<string>",
  "deadline": "<string>",
  "locked_at": "<string>",
  "recipient_count": 123,
  "response_count": 123,
  "completed_count": 123,
  "recipients_preview": [
    {}
  ]
}

GET

custom-kpi-datasets

{dataset_id}

campaigns

List Campaigns

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', 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"

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

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

print(response.text)

{
  "id": "<string>",
  "name": "<string>",
  "period_start": "<string>",
  "period_end": "<string>",
  "deadline": "<string>",
  "locked_at": "<string>",
  "recipient_count": 123,
  "response_count": 123,
  "completed_count": 123,
  "recipients_preview": [
    {}
  ]
}

List Campaigns

Retrieve all campaigns within a dataset. Each campaign is enriched with aggregate counts: total recipients, responses received, and completed assignments.

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 parent dataset

Response

Returns an array of campaign objects with aggregate stats (HTTP 200).

string

UUID

string

Campaign name

string

Reporting period start (ISO date)

string

Reporting period end (ISO date)

string

Submission deadline (ISO date)

string

Lock timestamp (nullable)

integer

Total assigned recipients

integer

Total responses received

integer

Recipients who completed all KPIs

array

First few recipients (email + user_id)

Example

curl -X GET "https://api.dcycle.io/v1/custom-kpi-datasets/${DATASET_ID}/campaigns" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
}

dataset_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.get(
    f"https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns",
    headers=headers,
)

for c in response.json():
    print(f"{c['name']}: {c['completed_count']}/{c['recipient_count']} complete")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
};

const datasetId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

axios.get(`https://api.dcycle.io/v1/custom-kpi-datasets/${datasetId}/campaigns`, { headers })
  .then(response => {
    response.data.forEach(c => console.log(`${c.name}: ${c.completed_count}/${c.recipient_count}`));
  });

Successful Response

[
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Q1 2025 Water Survey",
    "period_start": "2025-01-01",
    "period_end": "2025-03-31",
    "deadline": "2025-04-15",
    "locked_at": null,
    "created_by": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "created_at": "2025-01-10T08:00:00Z",
    "updated_at": null,
    "recipient_count": 5,
    "response_count": 12,
    "completed_count": 3,
    "recipients_preview": [
      {"data_owner_user_id": null, "data_owner_email": "manager-a@example.com"},
      {"data_owner_user_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "data_owner_email": "manager-b@example.com"}
    ]
  }
]

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 does not exist or belongs to another organization

{"detail": "Not Found"}

Create Campaign

Create a new collection campaign

Get Campaign

View campaign details with recipients

​List Campaigns

​Request

​Headers

​Path Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

Create Campaign

Get Campaign

List Campaigns

Request

Headers

Path Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints