Private beta Request access

Submissions

Read and manage the responses collected by a form.

List submissions

GET /api/v1/forms/{id}/submissions

Returns a page of the form's submissions. Submissions flagged as spam are excluded.

Service account scope: submissions:read

path parameters

id string required
Form ID.

query parameters

limit integer default 25
Maximum number of items to return.
offset integer default 0
Number of items to skip.
status string
Only return submissions with this status. One of new, in_review, approved, rejected, archived, pending_payment

Example request

curl "https://acme.formcel.com/api/v1/forms/ID/submissions" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

  • 200 A page of submissions.
  • 400 The request body or parameters are invalid.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Response body SubmissionList

data array of SubmissionSummary required
total integer required
limit integer required
offset integer required

SubmissionSummary

id string required
form_id string required
data object required
The answers keyed by field. Its shape follows the form and is not part of the API contract.
schema_version integer required
Form version the submission was made against.
status string required
Submission workflow status. New values may be added. One of new, in_review, approved, rejected, archived, pending_payment
created_at string (date-time) required

Get a submission

GET /api/v1/forms/{id}/submissions/{subId}

Service account scope: submissions:read

path parameters

id string required
Form ID.
subId string required
Submission ID.

Example request

curl "https://acme.formcel.com/api/v1/forms/ID/submissions/SUB_ID" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

  • 200 The submission.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Response body SubmissionDetail

id string required
form_id string required
data object required
The answers keyed by field. Its shape follows the form and is not part of the API contract.
schema_version integer required
Form version the submission was made against.
status string required
Submission workflow status. New values may be added. One of new, in_review, approved, rejected, archived, pending_payment
created_at string (date-time) required

Delete a submission

DELETE /api/v1/forms/{id}/submissions/{subId}

Moves the submission to the trash and emits submission.deleted. Requires the owner or editor role.

Service account scope: submissions:write

path parameters

id string required
Form ID.
subId string required
Submission ID.

Example request

curl -X DELETE "https://acme.formcel.com/api/v1/forms/ID/submissions/SUB_ID" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

  • 204 The submission was moved to the trash.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Update a submission's status

PATCH /api/v1/forms/{id}/submissions/{subId}/status

Moves the submission to another workflow status. A change is recorded in the submission's status history and emits submission.status_changed. Requires the owner or editor role.

Service account scope: submissions:write

path parameters

id string required
Form ID.
subId string required
Submission ID.

Request body

status string required
Submission workflow status. New values may be added. One of new, in_review, approved, rejected, archived, pending_payment

Example request

curl -X PATCH "https://acme.formcel.com/api/v1/forms/ID/submissions/SUB_ID/status" \
  -H "Authorization: Bearer $FORMCEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"approved"}'

Responses

  • 200 The updated submission.
  • 400 The request body or parameters are invalid.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Response body SubmissionDetail

id string required
form_id string required
data object required
The answers keyed by field. Its shape follows the form and is not part of the API contract.
schema_version integer required
Form version the submission was made against.
status string required
Submission workflow status. New values may be added. One of new, in_review, approved, rejected, archived, pending_payment
created_at string (date-time) required