Get Campaign

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

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} \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "id": "<string>",
  "dataset_id": "<string>",
  "name": "<string>",
  "period_start": "<string>",
  "period_end": "<string>",
  "deadline": "<string>",
  "locked_at": {},
  "created_by": {},
  "updated_by": {},
  "created_at": {},
  "updated_at": {},
  "campaign_assignments": {
    "id": "<string>",
    "campaign_id": "<string>",
    "assignment_id": "<string>",
    "last_invited_at": {},
    "completed_at": {},
    "status": "<string>",
    "assignment": {
      "id": "<string>",
      "dataset_id": "<string>",
      "organization_id": "<string>",
      "facility_id": {},
      "data_owner_user_id": {},
      "data_owner_email": "<string>",
      "created_at": {},
      "updated_at": {}
    },
    "created_at": {},
    "updated_at": {}
  }
}

GET

custom-kpi-datasets

{dataset_id}

campaigns

{campaign_id}

Get Campaign

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

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} \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "id": "<string>",
  "dataset_id": "<string>",
  "name": "<string>",
  "period_start": "<string>",
  "period_end": "<string>",
  "deadline": "<string>",
  "locked_at": {},
  "created_by": {},
  "updated_by": {},
  "created_at": {},
  "updated_at": {},
  "campaign_assignments": {
    "id": "<string>",
    "campaign_id": "<string>",
    "assignment_id": "<string>",
    "last_invited_at": {},
    "completed_at": {},
    "status": "<string>",
    "assignment": {
      "id": "<string>",
      "dataset_id": "<string>",
      "organization_id": "<string>",
      "facility_id": {},
      "data_owner_user_id": {},
      "data_owner_email": "<string>",
      "created_at": {},
      "updated_at": {}
    },
    "created_at": {},
    "updated_at": {}
  }
}

Get Campaign

Retrieve a campaign including all campaign-assignments (recipients) with their derived statuses: awaiting, completed, or locked.

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

string

required

UUID of the campaign

Response

Returns the campaign with nested campaign_assignments array (HTTP 200).

string

Campaign UUID.

string

UUID of the parent dataset this campaign belongs to.

string

Campaign display name.

string

Data collection period start date (ISO 8601 date).

string

Data collection period end date (ISO 8601 date).

string

Deadline for recipients to submit responses (ISO 8601 date).

string | null

Timestamp when the campaign was locked. null if still open.

string | null

UUID of the user who created the campaign.

string | null

UUID of the user who last updated the campaign.

datetime

Creation timestamp (ISO 8601).

string | null

Last update timestamp (ISO 8601).

array[object]

Recipients assigned to this campaign with their completion status.

Show Campaign Assignment Object

string

Campaign-assignment UUID.

string

Parent campaign UUID.

string

Underlying dataset assignment UUID.

string | null

When the invite email was last sent.

string | null

When the recipient completed all KPIs. null if pending.

string

Derived status: awaiting, completed, or locked.

object

Embedded dataset assignment with recipient details.

Show Assignment Object

string

Assignment UUID.

string

Parent dataset UUID.

string

Organization UUID the assignment targets.

string | null

Facility UUID if the assignment is facility-scoped.

string | null

User UUID of the data owner (if they have a Dcycle account).

string

Email address of the recipient.

datetime

Creation timestamp (ISO 8601).

string | null

Last update timestamp (ISO 8601).

datetime

Creation timestamp (ISO 8601).

string | null

Last update timestamp (ISO 8601).

Example

curl -X GET "https://api.dcycle.io/v1/custom-kpi-datasets/${DATASET_ID}/campaigns/${CAMPAIGN_ID}" \
  -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"
campaign_id = "b2c3d4e5-f6a7-8901-bcde-f12345678901"

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

campaign = response.json()
for ca in campaign["campaign_assignments"]:
    print(f"  {ca['assignment']['data_owner_email']}: {ca['status']}")

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';
const campaignId = 'b2c3d4e5-f6a7-8901-bcde-f12345678901';

axios.get(`https://api.dcycle.io/v1/custom-kpi-datasets/${datasetId}/campaigns/${campaignId}`, { headers })
  .then(response => {
    response.data.campaign_assignments.forEach(ca =>
      console.log(`${ca.assignment.data_owner_email}: ${ca.status}`)
    );
  });

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": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "updated_by": null,
  "created_at": "2025-06-15T10:00:00Z",
  "updated_at": null,
  "campaign_assignments": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "campaign_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "assignment_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "last_invited_at": "2025-06-16T09:00:00Z",
      "completed_at": null,
      "status": "awaiting",
      "assignment": {
        "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
        "facility_id": null,
        "data_owner_user_id": null,
        "data_owner_email": "supplier@example.com",
        "created_at": "2025-06-10T08:00:00Z",
        "updated_at": null
      },
      "created_at": "2025-06-15T10:00:00Z",
      "updated_at": null
    },
    {
      "id": "a2b3c4d5-e6f7-8901-abcd-ef2345678901",
      "campaign_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "assignment_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "last_invited_at": "2025-06-16T09:00:00Z",
      "completed_at": "2025-06-20T14:30:00Z",
      "status": "completed",
      "assignment": {
        "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
        "dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
        "facility_id": "660e8400-e29b-41d4-a716-446655440000",
        "data_owner_user_id": "b9f1e2d3-0000-0000-0000-000000000001",
        "data_owner_email": "ana.garcia@company.com",
        "created_at": "2025-06-10T08:00:00Z",
        "updated_at": null
      },
      "created_at": "2025-06-15T10:00:00Z",
      "updated_at": null
    }
  ]
}

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: Campaign not found

{
  "detail": "Campaign not found"
}

Update Campaign

Change campaign name or dates

Send Invites

Notify recipients

​Get Campaign

​Request

​Headers

​Path Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

Update Campaign

Send Invites

Get Campaign

Request

Headers

Path Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints