Submit Response

Submit a response to a form

Submit Form Response

Submit a response to a published form. This endpoint validates that all required fields are present before saving the response.

Endpoint

POST /api/forms/submit

Authentication

No authentication required. This endpoint is public to allow anyone with the form link to submit responses.

Request Body

formId · string · required

The UUID of the form to submit a response to

data · object · required

An object containing the form field values. Keys should match the field IDs defined in the form schema.

The structure varies based on the form, but generally:

• Keys are field IDs (e.g., “name”, “email”, “rating”)
• Values are the user’s input for each field

Response

success · boolean

Indicates whether the response was submitted successfully

message · string

Confirmation message: “Response submitted successfully”

responseId · string

Unique identifier for the submitted response

Validation Rules

The endpoint performs the following validations:

1. Form ID validation: Must be a non-empty string
2. Data validation: Must be a valid object (not null, not array)
3. Form existence: The form must exist in the database
4. Required fields: All fields marked as required: true in the form schema must be present in the data object

If any validation fails, the request is rejected with a 400 or 404 error.

Example Request

curl -X POST https://your-domain.com/api/forms/submit \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "cm3x7y2z1a0b1c2d3e4f5",
    "data": {
      "name": "John Doe",
      "email": "[e-mail]",
      "rating": 5,
      "comments": "Great service!"
    }
  }'

Example Response

{
  "success": true,
  "message": "Response submitted successfully",
  "responseId": "cm3z1a2b3c4d5e6f7g8h9"
}

Error Responses

Show 400 Bad Request - Missing Form ID

{
  "error": "Form ID is required and cannot be empty"
}

Returned when formId is missing or empty string.

Show 400 Bad Request - Invalid Data

{
  "error": "Form data is required and must be an object"
}

Returned when data is missing, null, or not an object.

Show 400 Bad Request - Invalid Form Fields

{
  "error": "Form fields are not in the correct format"
}

Returned when the form’s field schema is corrupted or invalid.

Show 400 Bad Request - Missing Required Field

{
  "error": "Required field missing: Email Address"
}

Returned when a required field is not present in the submitted data. The error message includes the field’s label to help users understand what’s missing.

Show 404 Not Found

{
  "error": "Form not found"
}

Returned when the specified form ID does not exist in the database.

Show 500 Internal Server Error

{
  "error": "Failed to submit form"
}

Returned when database operation fails or an unexpected error occurs.

Implementation Details

The submission process:

1. Validates the formId and data parameters
2. Looks up the form in the database
3. Retrieves the form’s field schema
4. Checks that all required fields are present in the submitted data
5. Creates a new response record in the formsResponses table
6. Returns the response ID

Source: app/api/forms/submit/route.ts:4

Example: Required Field Validation

Given a form with this field schema:

[
  { "id": "name", "label": "Your Name", "required": true },
  { "id": "email", "label": "Email", "required": true },
  { "id": "phone", "label": "Phone", "required": false }
]

Valid submission (phone is optional):

{
  "formId": "cm3x7y2z1a0b1c2d3e4f5",
  "data": {
    "name": "Jane Smith",
    "email": "[e-mail]"
  }
}

Invalid submission (missing required email):

{
  "formId": "cm3x7y2z1a0b1c2d3e4f5",
  "data": {
    "name": "Jane Smith"
  }
}

This would return:

{
  "error": "Required field missing: Email"
}