A submission represents one completed response to a form. Each submission stores the respondent’s answers keyed by field ID, along with metadata such as IP address and referrer.
List submissions GET /forms/{id}/submissionsReturns a paginated list of submissions for a specific form, ordered from newest to oldest.
Path parameters The form ID whose submissions you want to retrieve.
Query parameters Number of submissions to return per page. Maximum 100.
Pagination cursor from a previous response’s next_cursor. Omit to start from the most recent submission.
ISO 8601 datetime. Only return submissions created after this timestamp, e.g. 2025-01-01T00:00:00Z.
ISO 8601 datetime. Only return submissions created before this timestamp.
Response Array of submission objects. Show Submission object properties
Unique submission identifier, prefixed with sub_.
The ID of the form this submission belongs to.
Key-value map of field IDs to submitted values. The key is the field’s id (e.g. fld_a1B2c3D4) and the value is whatever the respondent entered.
Contextual metadata captured at submission time. IP address of the respondent.
Browser user-agent string.
URL of the page the form was submitted from, if available.
ISO 8601 timestamp of when the submission was received.
Cursor for the next page. null when you are on the last page.
true if there are more submissions beyond this page.
curl --request GET \ --url "https://api.formflows.ai/v1/forms/frm_8kQmP2xNvL/submissions?limit=25" \ --header "Authorization: Bearer sk_live_your_api_key"
Example response: { "data" : [ { "id" : "sub_7vHnM4rKpQ" , "form_id" : "frm_8kQmP2xNvL" , "data" : { "fld_a1B2c3D4" : "Jane Smith" , "fld_e5F6g7H8" : "[email protected] " , "fld_i9J0k1L2" : [ "Keynote" , "Workshop A" ] }, "metadata" : { "ip" : "203.0.113.42" , "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" , "referrer" : "https://www.example.com/register" }, "submitted_at" : "2025-01-15T14:32:00Z" }, { "id" : "sub_2bCdE5fGhI" , "form_id" : "frm_8kQmP2xNvL" , "data" : { "fld_a1B2c3D4" : "Marcus Johnson" , "fld_e5F6g7H8" : "[email protected] " , "fld_i9J0k1L2" : [ "Workshop B" , "Networking Lunch" ] }, "metadata" : { "ip" : "198.51.100.17" , "user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" , "referrer" : null }, "submitted_at" : "2025-01-15T13:18:00Z" } ], "next_cursor" : "cur_eyJpZCI6InN1Yl8yIn0" , "has_more" : true }
Get a submission GET /forms/{id}/submissions/{submission_id}Returns a single submission by ID.
Path parameters The submission ID, e.g. sub_7vHnM4rKpQ.
Response Returns the full submission object (same structure as in the list response above).
curl --request GET \ --url "https://api.formflows.ai/v1/forms/frm_8kQmP2xNvL/submissions/sub_7vHnM4rKpQ" \ --header "Authorization: Bearer sk_live_your_api_key"
POST /forms/{id}/submissionsCreates a new submission for a form without going through the public form URL. Use this to submit data on behalf of a user from your own backend.
This endpoint bypasses CAPTCHA and rate limiting that applies to the public form URL. Only call it from a trusted server-side environment — never from client-side code or a browser. Submissions created this way are tagged as api in the source field.
Path parameters The form ID to submit to.
Body parameters Key-value map of field IDs to values. Use the id of each field (visible in the form object) as the key. You must provide values for all required fields; optional fields can be omitted.
Response Returns the created submission object with a 201 Created status.
curl --request POST \ --url "https://api.formflows.ai/v1/forms/frm_8kQmP2xNvL/submissions" \ --header "Authorization: Bearer sk_live_your_api_key" \ --header "Content-Type: application/json" \ --data '{ "data": { "fld_a1B2c3D4": "Priya Patel", "fld_e5F6g7H8": "[email protected] ", "fld_i9J0k1L2": ["Keynote", "Networking Lunch"] } }'
Example response: { "id" : "sub_9wXyZ0aB1C" , "form_id" : "frm_8kQmP2xNvL" , "data" : { "fld_a1B2c3D4" : "Priya Patel" , "fld_e5F6g7H8" : "[email protected] " , "fld_i9J0k1L2" : [ "Keynote" , "Networking Lunch" ] }, "metadata" : { "ip" : null , "user_agent" : null , "referrer" : null , "source" : "api" }, "submitted_at" : "2025-01-15T16:05:00Z" }
Delete a submission DELETE /forms/{id}/submissions/{submission_id}Deleting a submission is permanent and cannot be undone. The submission data is removed from FormFlows.ai storage immediately and cannot be recovered.
Path parameters The submission ID to delete.
Response Returns a 204 No Content response on success, with no body.
curl --request DELETE \ --url "https://api.formflows.ai/v1/forms/frm_8kQmP2xNvL/submissions/sub_7vHnM4rKpQ" \ --header "Authorization: Bearer sk_live_your_api_key"
