Skip to main content
POST
Submit Response
← Custom KPI Submit a Custom KPI response with values and optional evidence attachments. This is the authenticated submission flow — the caller must be a logged-in member of the organization. In-app responses are accepted until the campaign is locked, even after its deadline: the deadline only closes the magic-link portal and invite sends. A locked campaign returns 409 CAMPAIGN_LOCKED.
Submissions from external data owners arrive through the magic-link portal, which posts to an internal endpoint authenticated with Dcycle’s own webhook key — it is not callable with an organization API key, so it is not documented here.

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

Body Parameters

string
required
UUID of the organization this response belongs toRetrieve available options from GET /v2/organizations/tree
string
required
UUID of the campaign being responded to
string
UUID of the facility (optional — used to match an assignment)Retrieve available options from GET /v1/facilities
array[object]
required
KPI values to submit (1–1000 entries). One entry per KPI, except a number_breakdown KPI: one entry per category it answers, each with the amount and the category’s option_id. Two entries with the same kpi_id and option_id are rejected. Each entry:A number_breakdown KPI’s value is the sum of the amounts of its newest submission, so send every category that has an amount. For example, fuel consumed by category:
array[string]
UUIDs of evidence files previously uploaded via Presigned URL. Max 20 files.

Response

Returns the created response set with saved values and attachment metadata (HTTP 201).
string
Response set UUID
string
Resolved campaign-assignment UUID
string
ISO 8601 timestamp
array[object]
Saved value objects
array[object]
Attachment metadata:

Example

Successful Response

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

403 Forbidden

Cause: The authenticated user is not a member of the organization

422 Validation Error

Cause: Two entries for the same KPI (or the same category of a number_breakdown KPI) in the values array
Cause: Two entries with different option_ids for a KPI that is not a number_breakdown
Cause: option_id sent for a KPI without options

Presigned URL

Upload evidence files before submitting

Dataset Values

View all submitted values across campaigns