Developers

Responses API

Submit, list, read, export and review responses.

Submit a response (server-to-server)

POST /forms/{id}/responses · scope responses:write

curl -X POST https://your-domain/api/v1/forms/$FORM_ID/responses \
  -H "Authorization: Bearer $CAF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "answers": { "full_name": "Ada", "email": "ada@example.com" } }'

The form must be published and Allow API submissions must be on (default). Answers are validated exactly like web submissions; approval scoring and webhooks run as usual. Returns 201 with the stored response.

List responses

GET /forms/{id}/responses · scope responses:read

{
  "data": [{
    "id": "6650c1f2a9e4b3d2c1f0a9b8",
    "form_version": 3,
    "created_at": "2026-10-18T09:24:11.502Z",
    "answers": { "email": "ada@example.com", "cv": [{ "file_id": "…", "name": "cv.pdf", "size": 48211, "type": "application/pdf" }] },
    "approval": { "status": "approved", "score": 5, "max_score": 6, "percent": 83.33, "matched": ["exp", "ts"], "failed_required": [], "decided_by": "auto" },
    "source": "web",
    "duration_ms": 95120
  }],
  "next_cursor": "6650c1f2a9e4b3d2c1f0a9b7",
  "total": 42
}

Get one response

GET /forms/{id}/responses/{responseId} — includes the definition of the version the respondent answered.

Download a file

GET /forms/{id}/responses/{responseId}/files/{fileId} — returns the file as an attachment.

Override the approval decision

PUT /forms/{id}/responses/{responseId}/approval · scope responses:write

{ "status": "approved", "note": "Strong portfolio" }

Send "status": null to restore the automatic decision.

Delete

DELETE /forms/{id}/responses/{responseId} — deletes the response and its files.

Export

GET /forms/{id}/responses/export?format=csv (or json) — up to 100,000 responses.

Analytics

GET /forms/{id}/analytics — daily counts (30 days), approval totals, per-question distributions and averages.