PUT /api/v1/forms/{formId}/qualification
Update enabled, general settings or one question slice. settings objectives: high_ticket, low_ticket, event, info, custom. Profiles contain key, label, description, temperature (hot/warm/cold/eliminated), minScore 0–100. Up to 8 profiles. A question slice is ; null clears it. Question settings support points by option value, eliminatory values, numeric thresholds , and criterion. Points range -100–100. AI enabling requires explicit consent or existing recorded consent; consent identity/time are recorded by Cohorte. A first consent spends school credits and is refused (403) to a Head of Sales, who can still edit a form already consented.
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
{
"settings": {
"objective": "custom",
"lookingFor": "A concrete learning goal",
"profiles": [
{
"key": "warm",
"label": "Promising",
"description": "Clear goal",
"temperature": "warm",
"minScore": 50
}
],
"eliminatedProfileKey": null,
"ai": {
"enabled": false,
"consent": false
}
}
}
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}/qualification" \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: form-intention-1" \
-H "Content-Type: application/json" \
-d '{"settings": {"objective": "custom", "lookingFor": "A concrete learning goal", "profiles": [{"key": "warm", "label": "Promising", "description": "Clear goal", "temperature": "warm", "minScore": 50}], "eliminatedProfileKey": null, "ai": {"enabled": false, "consent": false}}}'
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"
}
Update enabled, general settings or one question slice. settings objectives: high_ticket, low_ticket, event, info, custom. Profiles contain key, label, description, temperature (hot/warm/cold/eliminated), minScore 0–100. Up to 8 profiles. A question slice is ; null clears it. Question settings support points by option value, eliminatory values, numeric thresholds , and criterion. Points range -100–100. AI enabling requires explicit consent or existing recorded consent; consent identity/time are recorded by Cohorte. A first consent spends school credits and is refused (403) to a Head of Sales, who can still edit a form already consented.
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.
