Create Campaign

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    period_start: '<string>',
    period_end: '<string>',
    deadline: '<string>',
    assignment_ids: {}
  })
};

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"

payload = {
    "name": "<string>",
    "period_start": "<string>",
    "period_end": "<string>",
    "deadline": "<string>",
    "assignment_ids": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "period_start": "<string>",
  "period_end": "<string>",
  "deadline": "<string>",
  "assignment_ids": {}
}
'

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

POST

custom-kpi-datasets

{dataset_id}

campaigns

Create Campaign

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    period_start: '<string>',
    period_end: '<string>',
    deadline: '<string>',
    assignment_ids: {}
  })
};

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"

payload = {
    "name": "<string>",
    "period_start": "<string>",
    "period_end": "<string>",
    "deadline": "<string>",
    "assignment_ids": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "period_start": "<string>",
  "period_end": "<string>",
  "deadline": "<string>",
  "assignment_ids": {}
}
'

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

Create Campaign

Create a new campaign to collect KPI data from assigned data owners for a specific reporting period. Optionally link existing dataset assignments as recipients.

Creating a campaign does not send invite emails. Use Send Invites after creating the campaign to notify recipients.

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

Body Parameters

string

required

Campaign name (1–255 characters)Example: "Q1 2025 Water Survey"

string

required

Start of the reporting period (ISO date)Example: "2025-01-01"

string

required

End of the reporting period. Must be after period_start.Example: "2025-03-31"

string

required

Submission deadline. Must be after period_start.Example: "2025-04-15"

array[string]

UUIDs of dataset assignments to include as campaign recipients. Omit to add recipients later via Add Recipient.

Response

Returns the created campaign with its campaign-assignments (HTTP 201). The response uses the same shape as Get Campaign.

string

Campaign UUID.

string

UUID of the parent dataset.

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 for newly created campaigns.

string | null

UUID of the user who created the campaign.

datetime

Timestamp when the campaign was created

datetime | null

Timestamp when the campaign was last updated

array[object]

Recipients linked to this campaign. Empty if no assignment_ids were provided.

Show Campaign Assignment Object

string

Campaign-assignment UUID.

string

Parent campaign UUID.

string

Underlying dataset assignment UUID.

string

Derived status: awaiting (always for new campaigns).

object

Embedded dataset assignment with recipient details.

Show Assignment Object

string

Email address of the recipient.

string

Organization UUID the assignment targets.

string | null

Facility UUID if the assignment is facility-scoped.

Example

curl -X POST "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}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2025 Water Survey",
    "period_start": "2025-01-01",
    "period_end": "2025-03-31",
    "deadline": "2025-04-15",
    "assignment_ids": [
      "d4e5f6a7-b8c9-0123-defa-234567890123",
      "e5f6a7b8-c9d0-1234-efab-345678901234"
    ]
  }'

import requests
import os

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

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

response = requests.post(
    f"https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns",
    headers=headers,
    json={
        "name": "Q1 2025 Water Survey",
        "period_start": "2025-01-01",
        "period_end": "2025-03-31",
        "deadline": "2025-04-15",
        "assignment_ids": [
            "d4e5f6a7-b8c9-0123-defa-234567890123",
            "e5f6a7b8-c9d0-1234-efab-345678901234",
        ],
    },
)

campaign = response.json()
print(f"Created: {campaign['name']} ({len(campaign['campaign_assignments'])} recipients)")

const axios = require('axios');

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

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

axios.post(`https://api.dcycle.io/v1/custom-kpi-datasets/${datasetId}/campaigns`, {
  name: 'Q1 2025 Water Survey',
  period_start: '2025-01-01',
  period_end: '2025-03-31',
  deadline: '2025-04-15',
  assignment_ids: [
    'd4e5f6a7-b8c9-0123-defa-234567890123',
    'e5f6a7b8-c9d0-1234-efab-345678901234',
  ],
}, { headers })
.then(response => console.log(`Created: ${response.data.id}`));

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": null,
      "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
    }
  ]
}

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

422 Validation Error

Cause: period_end is not after period_start

{
  "detail": [
    {
      "loc": ["body", "period_end"],
      "msg": "period_end must be after period_start",
      "type": "value_error"
    }
  ]
}

Send Invites

Send invite emails to recipients

List Campaigns

View all campaigns

​Create Campaign

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Validation Error

​Related Endpoints

Send Invites

List Campaigns

Create Campaign

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Validation Error

Related Endpoints