GET /api/v1/forms/{formId}/responses
state=submitted (default) uses status, profile, sort=date|score and cursor. state=incomplete uses offset (default 0) and limit (1–50, default 50). Incomplete responses have no score or decision; their secret is never returned.
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 | Refused — 403 |
| Requirement | Rule |
|---|
| Business role | None; additional setter/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 |
| Parameter | Type | Default | Description |
|---|
| state | submitted or incomplete | submitted | Response lifecycle |
| status | string | none | Submitted triage status: untreated, processed, to_follow_up, qualified, disqualified |
| profile | string | none | Profile key or none |
| sort | date or score | date | Submitted sort |
| cursor | string | none | Submitted next page position |
| offset | integer | 0 | Incomplete row offset |
| limit | integer 1–50 | 50 | Incomplete page size |
curl -X GET "https://your-school.cohorte.app/api/v1/forms/{formId}/responses" \
-H "x-api-key: YOUR_API_KEY"
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. Submitted data contains rows, nextCursor and qualificationProfiles; incomplete data is {data,total}. Incomplete rows expose id, formVersionId, candidateName, candidateEmail, definition, answers, revision, createdAt and updatedAt.
{
"success": true,
"data": {
"rows": [],
"nextCursor": null,
"qualificationProfiles": null
},
"correlationId": "00000000-0000-4000-8000-000000000002"
}
state=submitted (default) uses status, profile, sort=date|score and cursor. state=incomplete uses offset (default 0) and limit (1–50, default 50). Incomplete responses have no score or decision; their secret is never returned.
