Add Campaign Recipient

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    organization_id: '<string>',
    data_owner_email: '<string>',
    facility_id: '<string>',
    data_owner_user_id: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/assignments', 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}/assignments"

payload = {
    "organization_id": "<string>",
    "data_owner_email": "<string>",
    "facility_id": "<string>",
    "data_owner_user_id": "<string>"
}
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/{campaign_id}/assignments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "organization_id": "<string>",
  "data_owner_email": "<string>",
  "facility_id": "<string>",
  "data_owner_user_id": "<string>"
}
'

{
  "id": "<string>",
  "campaign_id": "<string>",
  "assignment_id": "<string>",
  "last_invited_at": {},
  "completed_at": {},
  "status": "<string>",
  "assignment": {}
}

POST

custom-kpi-datasets

{dataset_id}

campaigns

{campaign_id}

assignments

Add Campaign Recipient

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    organization_id: '<string>',
    data_owner_email: '<string>',
    facility_id: '<string>',
    data_owner_user_id: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/assignments', 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}/assignments"

payload = {
    "organization_id": "<string>",
    "data_owner_email": "<string>",
    "facility_id": "<string>",
    "data_owner_user_id": "<string>"
}
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/{campaign_id}/assignments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "organization_id": "<string>",
  "data_owner_email": "<string>",
  "facility_id": "<string>",
  "data_owner_user_id": "<string>"
}
'

{
  "id": "<string>",
  "campaign_id": "<string>",
  "assignment_id": "<string>",
  "last_invited_at": {},
  "completed_at": {},
  "status": "<string>",
  "assignment": {}
}

Add Campaign Recipient

Link a data owner to a campaign. If the data owner doesn’t have an existing dataset assignment, one is created automatically.

Adding a recipient does not send an invite email. Use Send Invites (bulk) or Resend Invite (individual) to notify them.

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

string

required

UUID of the organization this recipient belongs to

string

required

Email address of the data ownerExample: "facility-manager@example.com"

string

UUID of a specific facility (omit for org-level)

string

UUID of an existing Dcycle user

Response

Returns the campaign-assignment with embedded dataset assignment (HTTP 201).

string

Campaign-assignment UUID.

string

Parent campaign UUID.

string

Underlying dataset assignment UUID.

string | null

When the invite email was last sent. null until Send Invites is called.

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 (data_owner_email, organization_id, facility_id).

Example

curl -X POST "https://api.dcycle.io/v1/custom-kpi-datasets/${DATASET_ID}/campaigns/${CAMPAIGN_ID}/assignments" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
    "data_owner_email": "facility-manager@example.com"
  }'

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.post(
    f"https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/assignments",
    headers=headers,
    json={
        "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
        "data_owner_email": "facility-manager@example.com",
    },
)

ca = response.json()
print(f"Added recipient: {ca['assignment']['data_owner_email']} (status: {ca['status']})")

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.post(`https://api.dcycle.io/v1/custom-kpi-datasets/${datasetId}/campaigns/${campaignId}/assignments`, {
  organization_id: 'a8315ef3-dd50-43f8-b7ce-d839e68d51fa',
  data_owner_email: 'facility-manager@example.com',
}, { headers })
.then(response => console.log(`Added: ${response.data.id}`));

Successful Response

{
  "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": "facility-manager@example.com",
    "created_at": "2025-06-18T16:00:00Z",
    "updated_at": null
  },
  "created_at": "2025-06-18T16: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"
}

Send Invites

Notify all pending recipients

Remove Recipient

Unlink a recipient

​Add Campaign Recipient

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

Send Invites

Remove Recipient

Add Campaign Recipient

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints