Skip to main content

postFormsData

Send form data to OneEntry platform.

🎯 What does this method do?​

This method submits form data to the OneEntry platform. Think of it like clicking "Submit" on a contact form - it sends all the user's input (name, email, message, files, etc.) to the server.

Use cases:

  • 📝 Contact forms
  • 📋 Registration forms
  • 💬 Feedback forms
  • 📤 File uploads
  • 🎫 Support tickets

📖 Simple Explanation​

When a user fills out a form on your website, you need to send that data somewhere. This method does exactly that - it takes all the form fields (text, numbers, files, etc.) and sends them to OneEntry.

Think of it as:

User fills form → Your code calls postFormsData() → Data saved in OneEntry ✅

🚀 Super Simple Example (Start Here!)​

Scenario: You have a contact form with just a name field.

// Step 1: User fills the form (e.g., enters "John Doe")
// Step 2: Send it to OneEntry

const response = await FormData.postFormsData({
  formIdentifier: "contact_us",        // 👈 Your form's name
  formModuleConfigId: 2,               // 👈 Form config ID (from OneEntry admin)
  moduleEntityIdentifier: "blog",      // 👈 Where to save it (from OneEntry)
  replayTo: null,                      // 👈 Reply email (optional)
  status: "sent",                      // 👈 "sent" or "draft"
  formData: [                          // 👈 The actual form data
    {
      marker: "name",                  // 👈 Field name
      type: "string",                  // 👈 Field type
      value: "John Doe"                // 👈 User's input
    }
  ]
});

// ✅ Done! Form submitted successfully
console.log("Form submitted, ID:", response.formData.id);

That's it! Now let's see how to handle different field types...

📋 What You Need to Know Before Using​

Before calling this method, you need these 3 things from OneEntry admin panel:

  1. formIdentifier - Your form's unique name (e.g., "contact_us")
  2. formModuleConfigId - Form configuration ID (a number, e.g., 2)
  3. moduleEntityIdentifier - Where to store data (e.g., "blog", "contacts")

How to find these?

  • Login to OneEntry Admin
  • Go to Forms section
  • Copy the values from your form configuration

🔧 Method Signature​

FormData.postFormsData(

body*, langCode

);

Parameters schema​

Schema (body)

body(required): IBodyPostFormData
Request body
example:

{
  "formIdentifier": "test-form",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "name",
      "type": "string",
      "value": "Test"
    }
  ]
}

body.formIdentifier(required): string
Text identifier (marker) of the form.
example: "form"

body.formModuleConfigId(required): number
The unique identifier of the form module configuration.
example: 2

body.moduleEntityIdentifier(required): string
Text identifier (marker) of the module entity.
example: "blog"

body.replayTo(required): string | null
Email to reply to.
example: "some@email.com"

body.status(required): string
Status of the form.
example: "sent"

body.formData(required): FormDataType[]
Array of form data objects.
example:

[
  {
    "marker": "name",
    "type": "string",
    "value": "Jack"
  }
]

body.fileQuery: IUploadingQuery
Optional file query for uploading files.
example:

{
  "type": "page",
  "entity": "editor",
  "id": 3787
}

fileQuery.type(required): string
Type, determines the folder name in the storage.
example: "page"

fileQuery.entity(required): string
Entity name from which the file is uploaded, determines the folder name in the storage.
example: "editor"

fileQuery.id(required): number
Identifier of the object from which the file is uploaded, determines the folder name in the storage.
example: 3787

fileQuery.width: number
Width parameter.
example: 0

fileQuery.height: number
Height parameter.
example: 0

fileQuery.compress: boolean
Flag of optimization (compression) for images.
example: true

langCode: string
Language code. Default: "en_US"
example: "en_US"

Examples​

Minimal example​


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "last_name",
      "type": "string"
      "value": "Andrey"
    }
  ]
};

const response = await FormData.postFormsData(body);

Example with a simple type attribute "string", "number", "float"​


const body = {
  "formIdentifier": "test-form",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "string_marker",
      "type": "string",
      "value": "Username"
    },
    {
      "marker": "number_marker",
      "type": "number",
      "value": 1
    },
    {
      "marker": "float_marker",
      "type": "float",
      "value": 2.256
    }
  ]
};

const response = await FormData.postFormsData(body);

Example with a simple type attribute "date", "dateTime", "time"​


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "date_marker",
      "type": "date",
      "value": {
        "fullDate": "2024-05-07T21:02:00.000Z",
        "formattedValue": "08-05-2024 00:02",
        "formatString": "DD-MM-YYYY HH:mm"
      }
    }
  ]
};

const response = await FormData.postFormsData(body);

Example with a simple type attribute "text" (Only one of htmlValue, plainValue or mdValue can be provided)​


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "about_marker",
      "type": "text",
      "value": [
        {
          "htmlValue": "<p>Hello world</p>",
          "params": {
            "isImageCompressed": true,
            "editorMode": "html"
          }
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Example with a simple type attribute "textWithHeader" (Only one of htmlValue, plainValue or mdValue can be provided)​


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      marker: "textwithheader_marker",
      type: "textWithHeader",
      value: [
        {
          "header": "Headline",
          "htmlValue": "<p>Hello World</p>",
          "params": {
            "isImageCompressed": true,
            "editorMode": "html"
          }
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

An already-uploaded file is not passed through as-is

The value of an image / groupOfImages field is an IImageValue (filename, downloadLink, size, previewLink, params), and the value of a file field is an IFileValue (filename, downloadLink, size).

That is not the object FileUploading.upload() returns: it also carries contentType, which the form-data endpoint rejects. Pick the fields listed above when you attach a file you uploaded earlier. When you hand postFormsData the file itself (the file + fileQuery form below), the SDK uploads it and strips contentType for you.

Also note the type of an image group is groupOfImages - plural. groupOfImage is answered with 400 formData's marker '…' type must be one of […].

Example with attribute type "image"​


const testImageUrl = 'https://your-project.oneentry.cloud/cloud-static/files/project/product/2954/image/7e0a6a70-a23d-410f-8b6a-f8b4f7483244.png';
const filename = 'test-image.png';

/* In real world scenario you should use File API to create file from URL but for the sake of simplicity we will use predefined file URL and use createFileFromUrl method for this example */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      marker: "image_marker",
      type: "image",
      value: [
        file
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Example with attribute type "groupOfImages"​


const testImageUrl = 'https://your-project.oneentry.cloud/cloud-static/files/project/product/2954/image/7e0a6a70-a23d-410f-8b6a-f8b4f7483244.png';
const filename = 'test-image.png';

/* In real world scenario you should use File API to create file from URL but for the sake of simplicity we will use predefined file URL and use createFileFromUrl method for this example */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      marker: "groupofimages_marker",
      type: "groupOfImages",
      value: [
        file
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Example with attribute type "files"​


const testImageUrl = 'https://your-project.oneentry.cloud/cloud-static/files/project/product/2954/image/7e0a6a70-a23d-410f-8b6a-f8b4f7483244.png';
const filename = 'test-image.png';

/* In real world scenario you should use File API to create file from URL but for the sake of simplicity we will use predefined file URL and use createFileFromUrl method for this example */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "picture_marker",
      "type": "file",
      "value": [
        {
          "filename": "files/project/page/10/image/Screenshot-from-2024-05-02-15-23-14.png",
          "downloadLink": "http://my-site.com/cloud-static/files/project/page/10/image/Screenshot-from-2024-05-02-15-23-14.png",
          "size": 392585
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Example with attribute type "radioButton" or "list"​


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "selector_marker",
      "type": "list",
      "value": ["Tom Hoffart"]
    }
  ]
};

const response = await FormData.postFormsData(body);

⚠️ A submission sends the chosen options as strings. The [{ title, value }] shape a page attribute stores is refused here with 400 formData's marker '<marker>' value[0] must be a string.

Example with attribute type "spam" (captcha)​

The platform generates Google reCAPTCHA v3 keys — there is no checkbox and no picture puzzle. The visitor is not asked anything: the token is obtained in the browser as the form is submitted, and the score is evaluated on the server.

Read the site key from the form itself: a spam field carries it in settings.captcha.key, next to domainNames — the domain the key was issued for. Take it from getFormByMarker rather than hard-coding it, and mind that a key issued for localhost will not pass on a production domain.

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>

const siteKey = form.attributes.find((a) => a.type === 'spam').settings.captcha.key;

const token = await window.grecaptcha.execute(siteKey, { action: 'submit' });

const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "contact-us",
  "replayTo": null,
  "status": "sent",
  "formData": [
    { "marker": "your_name", "type": "string", "value": "John Doe" },
    {
      "marker": "spam",
      "type": "spam",
      "value": { "event": { "token": token, "siteKey": siteKey } }
    }
  ]
};

const response = await FormData.postFormsData(body);

⚠️ The value is the event object, not the token string. A bare token, an empty value or a wrong shape are all refused with the same sentence — 400 Captcha Validation Failed, captcha type is: google — so a malformed request is indistinguishable from a bot. Check the shape before blaming the score.

A form whose spam field is configured but not sent is refused with 400 formData doesn't have spam attribute.

Example with attribute type "entity" (nested list)​


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "entity_marker",
      "type": "entity",
      "value": [25, 32, 24]
    }
  ]
};

const response = await FormData.postFormsData(body);

Value - numerical identifiers for pages and string identifiers for products. Identifiers for products should include the prefix 'p-', for example, 'p-1-', 'p-2-', etc. p-[parentId]-[productId]

Example with attribute type "timeInterval"​


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      marker: 'timeinterval_marker',
      type: 'timeInterval',
      value: [
        [
          "2025-02-11T16:00:00.000Z",
          "2025-02-13T16:00:00.000Z"
        ]
      ]
    },
  ]
};

const response = await FormData.postFormsData(body);

value — array of interval arrays in ISO 8601 format. for example 2025-02-11T16:00:00:000Z

2025 — year; 02 — month; 11 — day of the month; T — separator between date and time; 16:00:00 — time in hours:minutes:seconds format; 000Z — milliseconds and time zone indication. Z means that the time is specified in UTC format.

Example return:​

{
  "formData": {
    "formIdentifier": "test-form",
    "time": "2026-09-25T17:21:39.663Z",
    "formData": [
      {
        "marker": "name",
        "type": "string",
        "value": "Test"
      }
    ],
    "userIdentifier": "test@test.ru",
    "entityIdentifier": "blog",
    "fingerprint": "UQ_d19a29b4-70fc-4765-a345-799144057cb0",
    "isUserAdmin": false,
    "formModuleId": 2,
    "parentId": null,
    "id": 8955
  },
  "actionMessage": ""
}

Response schema​

Schema: IPostFormResponse

formData: object
Form data.
example:

{
  "id": 42,
  "formIdentifier": "contact_form",
  "time": "2023-10-01T12:00:00Z",
  "entityIdentifier": "blog",
  "isUserAdmin": false,
  "formModuleId": 2,
  "parentId": null,
  "userIdentifier": null,
  "formData": [
    {
      "marker": "name",
      "type": "string",
      "value": "Jack"
    }
  ]
}

formData.id: number
The unique identifier of the form page.
example: 12345

formData.formIdentifier: string
The identifier of the form.
example: "contact_form"

formData.time: string
The time of the form submit.
example: "2023-10-01T12:00:00Z"

formData.entityIdentifier: string
The entity identifier.
example: "blog"

formData.isUserAdmin: boolean
Is user admin.
example: false

formData.formModuleId: number
The form module identifier.
example: 2

formData.userIdentifier: string | null
The user identifier.
example: null

formData.parentId: number | null
The parent identifier.
example: null

formData.formData: FormDataType[]
Form fields data.
example:

[
  {
    "marker": "name",
    "type": "string",
    "value": "Jack"
  }
]

actionMessage: string
Action message for the form data (can be localized).
example: "Form submitted successfully"

Usage examples​

Step-by-step walkthroughs in the documentation:

  • Submit a form — collect contact form input and post it back to OneEntry.
  • Entity form — submit a form with entity-type fields (pages or products).

Try it live​

Run this method interactively in the JS SDK sandbox — connect your Project URL and App Token on first visit, then open any scenario below to see real form submissions:

  • Submit a form — collect contact form input and post it back to OneEntry.
  • Entity form — submit a form with entity-type fields (pages or products).
  • File form — submit a form that includes a file attachment.
  • Spam form — submit a form with spam protection.
  • Schedule form — submit a selected time slot via a timeInterval field.