Create Assignment

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}/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}/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}/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>",
  "dataset_id": "<string>",
  "organization_id": "<string>",
  "facility_id": {},
  "data_owner_user_id": {},
  "data_owner_email": "<string>",
  "created_at": {},
  "updated_at": {}
}

POST

custom-kpi-datasets

{dataset_id}

assignments

Create Assignment

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}/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}/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}/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>",
  "dataset_id": "<string>",
  "organization_id": "<string>",
  "facility_id": {},
  "data_owner_user_id": {},
  "data_owner_email": "<string>",
  "created_at": {},
  "updated_at": {}
}

Create Assignment

Create a new assignment linking a data owner to a dataset. Each assignment specifies who will receive campaign invitations and submit KPI values for a given organization (and optionally a specific facility).

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 datasetExample: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Body Parameters

string

required

UUID of the organization this assignment applies to

string

required

Email address of the data owner who will receive campaign invitationsExample: "facility-manager@example.com"

string

UUID of a specific facility. Omit for an organization-level assignment.

string

UUID of an existing Dcycle user. If provided, the user sees in-app KPI forms.

Response

Returns the created assignment (HTTP 201).

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).

Example

curl -X POST "https://api.dcycle.io/v1/custom-kpi-datasets/${DATASET_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",
    "facility_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

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}/assignments",
    headers=headers,
    json={
        "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
        "data_owner_email": "facility-manager@example.com",
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
    },
)

assignment = response.json()
print(f"Assigned: {assignment['data_owner_email']} → {assignment['id']}")

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}/assignments`, {
  organization_id: 'a8315ef3-dd50-43f8-b7ce-d839e68d51fa',
  data_owner_email: 'facility-manager@example.com',
  facility_id: '550e8400-e29b-41d4-a716-446655440000',
}, { headers })
.then(response => console.log(`Assigned: ${response.data.id}`));

Successful Response

{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "data_owner_user_id": null,
  "data_owner_email": "facility-manager@example.com",
  "created_at": "2025-02-01T09: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: Dataset not found

{
  "detail": "Dataset not found"
}

422 Validation Error

Cause: Invalid email address

{
  "detail": [
    {
      "loc": ["body", "data_owner_email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

List Assignments

View all data owner assignments

Update Assignment

Change the data owner

​Create Assignment

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Validation Error

​Related Endpoints

List Assignments

Update Assignment

Create Assignment

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

Related Endpoints