PUT /api/v1/forms/{formId}/submission-settings
full_submission (default) saves only the final send. partial_submission permits progressive anonymous saving after a valid name and email. Publish to expose the changed mode.
Use x-api-key with an active organization-bound API key. Its holder keeps their current Organization, CASL and resource permissions.
| Role in the organization | Access |
|---|
| OWNER | Allowed |
| ADMIN | Allowed |
| MEMBER | Head of Sales only — otherwise 403 |
| Requirement | Rule |
|---|
| Business role | Owner, admin or Head of Sales; setter and closer roles do not grant access |
| Resource scope | Organization bound to the verified key |
| Participation | None |
| Resource state | Published valid draft for publication; otherwise the command determines state |
| Parameter | Type | Required | Description |
|---|
| formId | UUID | yes | Form in the key’s organization |
| Header | Required | Description |
|---|
| x-api-key | yes | Organization-bound key |
| Idempotency-Key | yes | Stable key for one intention; reuse on retry |
Request body
{
"submissionMode": "partial_submission"
}
All fields shown are required unless described as optional above. Never send an organization identifier; the verified key chooses the school.
curl -X PUT "https://your-school.cohorte.app/api/v1/forms/{formId}/submission-settings" \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: form-intention-1" \
-H "Content-Type: application/json" \
-d '{"submissionMode": "partial_submission"}'
Success: 200. 400 invalid_request for malformed input or missing key; 401 unauthorized for invalid authentication; 403 forbidden for permission refusal; 404 not_found for missing or other-organization resources; 409 conflict for a conflicting state; 500 internal_error for an unexpected failure.
The envelope has success, data, and correlationId, plus replayed for a retry. A form exposes id, title, description, theme, chrome flags, submissionMode, identityFields, definition, qualification, programIds, cohortIds, isActive, slug, publishedVersion (id, version, publishedAt) and updatedAt. The list is an array and additionally includes responseCount.
{
"success": true,
"replayed": false,
"data": {
"id": "00000000-0000-4000-8000-000000000001",
"title": "Applications",
"description": "Tell us about your goals.",
"theme": "base",
"showChrome": true,
"showPoweredBy": true,
"submissionMode": "partial_submission",
"identityFields": null,
"definition": {
"questions": [
{
"key": "goal",
"type": "long_text",
"label": "Your goal",
"required": true
}
]
},
"qualification": null,
"programIds": [],
"cohortIds": [],
"isActive": true,
"slug": "applications",
"publishedVersion": {
"id": "00000000-0000-4000-8000-000000000003",
"version": 1,
"publishedAt": "2026-10-13T09:00:00.000Z"
},
"updatedAt": "2026-10-13T09:00:00.000Z"
},
"correlationId": "00000000-0000-4000-8000-000000000002"
}
full_submission (default) saves only the final send. partial_submission permits progressive anonymous saving after a valid name and email. Publish to expose the changed mode.
Commands claim idempotency before the write. Replays suppress repeat audit/events and return current resource state. New intentions need a new key. Qualification updates do not re-score existing responses automatically.
