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

← Custom KPI 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 toRetrieve available options from GET /v2/organizations/tree

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.Retrieve available options from GET /v1/facilities

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

​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

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

Related Endpoints