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).

Searching submissions by meaning

getFormsDataByVectorSearch(body, langCode, offset, limit) runs a semantic (vector) search over submissions: you pass a natural-language queryText and get back the records that match it in meaning, not by literal keyword.

Its records use a different type from the rest of the module - IFormDataSearchEntity instead of IFormDataEntity. Both carry id, formIdentifier, time and formData, but the search entity additionally exposes the moderation and sender fields of the raw record:

Field	Type	Meaning
status	'sent' | 'banned' | 'deleted' | 'moderation' | 'approved'	Moderation status of the record
ip	string	IP address the form was submitted from
fingerprint	string	Device fingerprint of the sender
isUserAdmin	boolean	Whether an admin submitted the record
userIdentifier	string	Who submitted the form
entityIdentifier	string	The entity the record belongs to
parentId	number	Parent form data record

---

📊 Quick Reference Table

Method	Description	Use Case
postFormsData()	Submit new form data	User submits contact form
getFormsDataByMarker()	Get submissions for specific form	View all contact form submissions
updateFormsDataByid() 🔐	Update a form submission by id	Edit a stored submission
updateFormsDataStatusByid() 🔐	Update a submission's status by id	Mark as processed/archived
deleteFormsDataByid() 🔐	Delete a form submission by id	Remove a submission
getFormsDataByVectorSearch()	Semantic (vector) search for form data	Find submissions by meaning, not keywords

🔐 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

• Forms Module - Fetch form structures to submit against
• FileUploading Module - Handle file uploads in forms
• Events Module - Set up event-driven notifications
• Users Module - Manage users who submit forms

---