PUT /api/v1/forms/{formId}/identity-fields
Replace the fixed Name and Email display labels and help. Keys, types, order and required status cannot change. Publish to expose changes; already-started responses keep their original presentation.
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
{
"identityFields": {"candidateName": {"label": "Your full name", "help": "As you want us to address you"}, "candidateEmail": {"label": "Contact email", "help": "For our reply"}}
}
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}/identity-fields" \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: form-intention-1" \
-H "Content-Type: application/json" \
-d '{"identityFields": {"candidateName": {"label": "Your full name", "help": "As you want us to address you"}, "candidateEmail": {"label": "Contact email", "help": "For our reply"}}}'
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 contains success, replayed, data and correlationId. data contains candidateName and candidateEmail, each with label/help, or null when reset to localized defaults.
{
"success": true,
"replayed": false,
"data": {
"candidateName": {
"label": "Your full name",
"help": "As you want us to address you"
},
"candidateEmail": {
"label": "Contact email",
"help": "For our reply"
}
},
"correlationId": "00000000-0000-4000-8000-000000000002"
}
Replace the fixed Name and Email display labels and help. Keys, types, order and required status cannot change. Publish to expose changes; already-started responses keep their original presentation.
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.
Labels are trimmed, nonblank and at most 120 characters when provided; null restores the localized default. Help is at most 500 characters; null restores default and an empty string hides it. Send {"identityFields":null} to restore both fields. Send both candidateName/candidateEmail when replacing. Name/email never enter AI qualification; custom criteria use stable question keys.
