Submissions

Create Submission

Submit a new response to a form using the SharaForms API. This endpoint allows you to programmatically collect form data without requiring user authentication.

POST

Submit a new response to a form using the SharaForms 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.

#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 endpoint)
Form fields configured according to your validation requirements

Tip

You can find your form's slug in the SharaForms dashboard under form settings, or use the form's UUID which is also displayed in the dashboard.

#Request

#Path Parameters

slugstring required

The form identifier - either a human-readable slug (e.g., customer-feedback) or UUID. You can find this in your SharaForms dashboard under form settings.

#Request Body

[field_id]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"

completion_timenumber

Time in seconds it took the user to complete the form. Used for analytics and form optimization insights.

is_partialbooleandefault: 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.

#Response

#Success Response Fields

typestring

Response type indicator. Always "success" for successful submissions.

messagestring

Human-readable success message describing the submission result.

submission_idstring|null

Unique identifier for the created submission. Returns null for partial submissions.

is_first_submissionboolean

Indicates whether this is the first submission for this form. Useful for triggering welcome flows or first-time user experiences.

redirectboolean

Indicates if the form has a custom redirect URL configured. Always false for API submissions.

submission_hashstring|null

Unique hash for partial submissions that can be used to update the submission later. Only present when is_partial: true.

#Use Cases

#Basic Form Submission

Submit a complete contact form with validation:

javascript

const submitContactForm = async (formData) => {
    try {
        const response = await fetch(
            "https://api.sharaforms.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.sharaforms.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.sharaforms.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();
};