Skip to main content

Introduction

Handle form submissions and retrieve form data.

More information about forms in the OneEntry admin panel: https://doc.oneentry.cloud/docs/category/forms

🎯 What does this module do?​

The FormData module lets you submit user-filled forms (contact forms, surveys, registrations) to OneEntry and retrieve, update, or delete submitted data for analysis, reporting, and management.

Think of it as your form submission manager - users submit forms, you store them in OneEntry, and retrieve them whenever you need to view responses, generate reports, or analyze data.

🚀 Quickstart​

Initialize the module from defineOneEntry:


const { FormData } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Build the body from the form's config and submit it:

// 1. Fetch the form to read its module config.
const form = await Forms.getFormByMarker("contact_form");
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// 2. Submit the user's input.
const response = await FormData.postFormsData({
  formIdentifier: "contact_form",
  formModuleConfigId,
  moduleEntityIdentifier,
  replayTo: null,
  status: "sent",
  formData: [
    { marker: "name", type: "string", value: "Jack" },
  ],
});

console.log(response);

To read submissions later, call getFormsDataByMarker(marker, formModuleConfigId, body?, isExtended?, langCode?, offset?, limit?).

✨ Key Concepts​

What is Form Data?​

Form data is the information users submit through a form. Each submission is built from a formData array of field objects (marker, type, value) plus the form's configuration identifiers.

Submission body structure​

postFormsData accepts an IBodyPostFormData:

const body = {
  formIdentifier: 'contact_form', // Form marker
  formModuleConfigId: 9,          // Module config ID (from the form)
  moduleEntityIdentifier: 'blog', // Module entity identifier (from the form)
  replayTo: null,                 // Email address to reply to (optional)
  status: 'sent',                 // Submission status (optional)
  formData: [                     // Form fields
    { marker: 'name', type: 'string', value: 'Test' },
  ],
};

📋 What You Need to Know​

Submitting requires the form's config​

Before submitting you need three values, all read from the form itself:

  1. Form marker (formIdentifier) — the form's text identifier
  2. formModuleConfigId — from the form's moduleFormConfigs
  3. moduleEntityIdentifier — from the form's moduleFormConfigs
const form = await Forms.getFormByMarker('contact_form');
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

Cache these values so you don't refetch the form on every submission.

formData fields​

Each entry in the formData array describes one field:

  • marker — must match a field marker from the form definition
  • type — the field type (used for validation and file handling)
  • value — the user's input

Fields of type file / image / groupOfImages are uploaded automatically through the FileUploading module when you pass a File/FileList/Blob as the value.

Submission status​

Use the status field to track submission state. "sent" is the typical value for new submissions; you can later move a submission to a reviewed/archived state with updateFormsDataStatusByid().

Updating and deleting submissions​

Submissions are not immutable. Authenticated users can change or remove them:

  • updateFormsDataByid(id, body) — edit a stored submission by id 🔐
  • updateFormsDataStatusByid(id, body) — change only a submission's status by id 🔐
  • deleteFormsDataByid(id) — delete a submission by id 🔐

Reading submissions​

getFormsDataByMarker returns submissions for a form. Page through results with offset / limit, and narrow with the request body (e.g. status, dateFrom, dateTo, userIdentifier).

📊 Quick Reference Table​

MethodDescriptionUse Case
postFormsData()Submit new form dataUser submits contact form
getFormsDataByMarker()Get submissions for specific formView all contact form submissions
updateFormsDataByid() 🔐Update a form submission by idEdit a stored submission
updateFormsDataStatusByid() 🔐Update a submission's status by idMark as processed/archived
deleteFormsDataByid() 🔐Delete a form submission by idRemove a submission

🔐 methods require user authorization — see AuthProvider. postFormsData() and getFormsDataByMarker() are public.

❓ Frequently Asked Questions (FAQ)​

How do I submit a form?​

Fetch the form with Forms.getFormByMarker(), read formModuleConfigId and moduleEntityIdentifier from its moduleFormConfigs, build the body, then call FormData.postFormsData(body). See the Quickstart section above.

Can I update or delete submitted form data?​

Yes. Submissions can be changed or removed via the SDK (these require user authorization):

  • updateFormsDataByid() — edit a stored submission by id
  • updateFormsDataStatusByid() — change only a submission's status by id
  • deleteFormsDataByid() — delete a submission by id

How do I handle file uploads in forms?​

Pass a File / FileList / Blob as a field's value and postFormsData() uploads it for you, or upload separately with the FileUploading module and include the returned URLs in formData.

How do I filter submissions by date?​

Pass dateFrom and dateTo in the request body of getFormsDataByMarker().

How do I paginate through all submissions?​

Use the offset and limit arguments of getFormsDataByMarker().

🎓 Best Practices​

  • Cache the form's config (formModuleConfigId, moduleEntityIdentifier) to avoid refetching the form on every submission.
  • Validate required fields client-side before submitting; OneEntry also validates server-side.
  • Paginate reads with offset / limit rather than fetching everything at once.
  • Reference forms by marker, not by numeric ID.
  • Use the status field (and updateFormsDataStatusByid) to organize submissions.
  • Handle errors with try/catch and check the IError return shape.

🔗 Related Documentation​