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 data collection campaign within a dataset
POST
/
v1
/
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": {}
}
}
}← Custom KPI
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
Path Parameters
Body Parameters
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.Recipients linked to this campaign. Empty if no
assignment_ids were provided.Show Campaign Assignment Object
Show Campaign Assignment Object
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"
}
]
}
Related Endpoints
Send Invites
Send invite emails to recipients
List Campaigns
View all campaigns
Was this page helpful?