Update Campaign

const options = {
  method: 'PATCH',
  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>'
  })
};

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

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

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

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id} \
  --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>"
}
'

{
  "id": "<string>",
  "dataset_id": "<string>",
  "name": "<string>",
  "period_start": "<string>",
  "period_end": "<string>",
  "deadline": "<string>",
  "locked_at": {},
  "created_at": {},
  "updated_at": {}
}

PATCH

custom-kpi-datasets

{dataset_id}

campaigns

{campaign_id}

Update Campaign

const options = {
  method: 'PATCH',
  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>'
  })
};

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

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

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

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id} \
  --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>"
}
'

{
  "id": "<string>",
  "dataset_id": "<string>",
  "name": "<string>",
  "period_start": "<string>",
  "period_end": "<string>",
  "deadline": "<string>",
  "locked_at": {},
  "created_at": {},
  "updated_at": {}
}

Update Campaign

Update the name, reporting period, or deadline of an existing campaign. Only send the fields you want to change.

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

Body Parameters

All fields are optional.

string

Campaign name (1–255 characters)

string

Start of the reporting period (ISO date)

string

End of the reporting period. Must be after period_start when both are provided.

string

Submission deadline. Must be after period_start when both are provided.

Response

Returns the updated campaign (HTTP 200).

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

Submission deadline (ISO 8601 date).

string | null

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

datetime

Creation timestamp (ISO 8601).

string | null

Last update timestamp (ISO 8601).

Example

curl -X PATCH "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}" \
  -H "Content-Type: application/json" \
  -d '{"deadline": "2025-05-01", "name": "Q1 2025 Water Survey (Extended)"}'

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"
campaign_id = "b2c3d4e5-f6a7-8901-bcde-f12345678901"

response = requests.patch(
    f"https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}",
    headers=headers,
    json={"deadline": "2025-05-01", "name": "Q1 2025 Water Survey (Extended)"},
)

print(f"Updated: deadline → {response.json()['deadline']}")

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

axios.patch(`https://api.dcycle.io/v1/custom-kpi-datasets/${datasetId}/campaigns/${campaignId}`, {
  deadline: '2025-05-01',
  name: 'Q1 2025 Water Survey (Extended)',
}, { headers })
.then(response => console.log(`Updated: ${response.data.name}`));

Successful Response

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Q1 2025 Water Survey (Extended)",
  "period_start": "2025-01-01",
  "period_end": "2025-03-31",
  "deadline": "2025-05-01",
  "locked_at": null,
  "created_by": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "updated_by": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "created_at": "2025-06-15T10:00:00Z",
  "updated_at": "2025-06-18T14:00:00Z"
}

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

422 Validation Error

Cause: Invalid or missing required fields in the request body

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

Get Campaign

View campaign with recipients

Lock Campaign

Prevent further submissions

​Update Campaign

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Validation Error

​Related Endpoints

Get Campaign

Lock Campaign

Update Campaign

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

Related Endpoints