Beautiful Open-Source Form Builder
Add create submission endpoint and documentation (#870)
Chirag Chhatralafb2e3a589e01
diff --git a/docs/api-reference/openapi.yaml b/docs/api-reference/openapi.yamlindex 35b44a444..4ae182e4d 100644--- a/docs/api-reference/openapi.yaml+++ b/docs/api-reference/openapi.yaml@@ -5,7 +5,6 @@ info:version: 1.0.0servers:- url: https://api.opnform.com- - url: https://opnform.testsecurity:- bearerAuth: []tags:@@ -474,6 +473,72 @@ paths:description: Deleted"403":description: Forbidden+ "/forms/{slug}/answer":+ post:+ tags:+ - Submissions+ summary: Create Submission+ description: "Create a new submission for a form. Public endpoint - no authentication required."+ security: []+ parameters:+ - name: slug+ in: path+ required: true+ schema:+ type: string+ requestBody:+ required: true+ content:+ application/json:+ schema:+ type: object+ additionalProperties: true+ properties:+ completion_time:+ type: number+ description: "Time in seconds it took to complete the form"+ is_partial:+ type: boolean+ description: "If you want to submit your form as partial"+ responses:+ "200":+ description: "Form submission saved successfully"+ content:+ application/json:+ schema:+ type: object+ properties:+ type:+ type: string+ example: "success"+ message:+ type: string+ example: "Form submission saved."+ submission_id:+ type: string+ nullable: true+ is_first_submission:+ type: boolean+ redirect:+ type: boolean+ "422":+ description: "Validation error"+ content:+ application/json:+ schema:+ type: object+ properties:+ message:+ type: string+ example: "The Name field is required."+ errors:+ type: object+ additionalProperties:+ type: array+ items:+ type: string+ "404":+ description: "Form not found""/open/forms/{id}/submissions":get:tags:diff --git a/docs/api-reference/submissions/create-submission.mdx b/docs/api-reference/submissions/create-submission.mdxnew file mode 100644index 000000000..3cde8741b--- /dev/null+++ b/docs/api-reference/submissions/create-submission.mdx@@ -0,0 +1,229 @@+---+openapi: post /forms/{slug}/answer+---++# Create Form Submission++Submit a new response to a form using the OpnForm API. This endpoint allows you to programmatically collect form data without requiring user authentication.++<Info>+ This is a public endpoint designed for form submissions. No API+ authentication is required.+</Info>++## Prerequisites++Before submitting to a form, you'll need:++- A published form with a valid slug or UUID+- Knowledge of the form's field IDs (available via the [Get Form](/api-reference/forms/get-form) endpoint)+- Form fields configured according to your validation requirements++<Tip>+ You can find your form's slug in the OpnForm dashboard under form settings,+ or use the form's UUID which is also displayed in the dashboard.+</Tip>++## Request++<RequestExample>+```http+POST /forms/{slug}/answer HTTP/1.1+Host: api.opnform.com+Content-Type: application/json++{+"completion_time": 10,+"3700d380-197b-47b9-a008-3acc31bbd506": "Alice",+"12461db5-0c19-429e-840b-8de1e359c42f": "[email protected]"+}++````++</RequestExample>++### Path Parameters++<ParamField path="slug" type="string" required>+ The form identifier - either a human-readable slug (e.g.,+ `customer-feedback`) or UUID. You can find this in your OpnForm dashboard+ under form settings.+</ParamField>++### Request Body++<ParamField body="[field_id]" type="string|number|boolean|array">+**Dynamic field data**: Each form field is identified by its unique UUID. The value type depends on the field type:+- Text fields: `string`+- Number fields: `number`+- Checkbox fields: `boolean`+- Multi-select fields: `array`++**Example**: `"3700d380-197b-47b9-a008-3acc31bbd506": "Alice Johnson"`++</ParamField>++<ParamField body="completion_time" type="number">+ Time in seconds it took the user to complete the form. Used for analytics+ and form optimization insights.+</ParamField>++<ParamField body="is_partial" type="boolean" default="false">+Submit the form as a partial submission. Only works if the form has "Collect partial submissions" enabled in its settings.++When `true`, the response includes a `submission_hash` that can be used to update the same submission later.++</ParamField>++## Response++<ResponseExample>+```json Success (200 OK)+{+ "type": "success",+ "message": "Form submission saved.",+ "submission_id": "sub_1234567890",+ "is_first_submission": true,+ "redirect": false,+ "submission_hash": null+}+````++```json Partial Success (200 OK)+{+ "type": "success",+ "message": "Partial form submission saved.",+ "submission_hash": "hash_abc123def456"+}+```++```json Validation Error (422)+{+ "message": "The Name field is required.",+ "errors": {+ "3700d380-197b-47b9-a008-3acc31bbd506": ["The Name field is required."],+ "12461db5-0c19-429e-840b-8de1e359c42f": [+ "The email field must be a valid email address."+ ]+ }+}+```++```json Form Not Found (404)+{+ "message": "Form not found.",+ "error": "The specified form slug does not exist or is not published."+}+```++</ResponseExample>++### Success Response Fields++<ResponseField name="type" type="string">+ Response type indicator. Always `"success"` for successful submissions.+</ResponseField>++<ResponseField name="message" type="string">+ Human-readable success message describing the submission result.+</ResponseField>++<ResponseField name="submission_id" type="string|null">+ Unique identifier for the created submission. Returns `null` for partial+ submissions.+</ResponseField>++<ResponseField name="is_first_submission" type="boolean">+ Indicates whether this is the first submission for this form. Useful for+ triggering welcome flows or first-time user experiences.+</ResponseField>++<ResponseField name="redirect" type="boolean">+ Indicates if the form has a custom redirect URL configured. Always `false`+ for API submissions.+</ResponseField>++<ResponseField name="submission_hash" type="string|null">+ Unique hash for partial submissions that can be used to update the+ submission later. Only present when `is_partial: true`.+</ResponseField>++## Use Cases++### Basic Form Submission++Submit a complete contact form with validation:++```javascript+const submitContactForm = async (formData) => {+ try {+ const response = await fetch(+ "https://api.opnform.com/forms/contact-us/answer",+ {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ "3700d380-197b-47b9-a008-3acc31bbd506": formData.name,+ "12461db5-0c19-429e-840b-8de1e359c42f": formData.email,+ "a8f5c2d1-9b7e-4c3f-8a1d-2e5f9c4b7a8e": formData.message,+ completion_time: formData.timeSpent,+ }),+ }+ );++ if (!response.ok) {+ throw new Error("Submission failed");+ }++ return await response.json();+ } catch (error) {+ console.error("Form submission error:", error);+ throw error;+ }+};+```++### Partial Submission Workflow++Save progress and complete later:++```javascript+// Save partial submission+const saveProgress = async (partialData) => {+ const response = await fetch(+ "https://api.opnform.com/forms/survey/answer",+ {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ ...partialData,+ is_partial: true,+ }),+ }+ );++ const result = await response.json();+ // Store submission_hash for later use+ localStorage.setItem("submission_hash", result.submission_hash);+ return result;+};++// Complete the submission later+const completeSubmission = async (finalData) => {+ const hash = localStorage.getItem("submission_hash");+ const response = await fetch(+ "https://api.opnform.com/forms/survey/answer",+ {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ ...finalData,+ submission_hash: hash,+ is_partial: false,+ }),+ }+ );++ return await response.json();+};+```diff --git a/docs/docs.json b/docs/docs.jsonindex 746e8d80a..90e88e903 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -89,6 +89,7 @@"group": "Submissions","pages": ["api-reference/submissions/list-submissions",+ "api-reference/submissions/create-submission","api-reference/submissions/export-submissions-csv","api-reference/submissions/update-submission","api-reference/submissions/delete-submission"