Storefront API Forms

List, retrieve, and submit online forms through the Storefront API including field metadata, validations, and loading details of past inquiries.

The API endpoint for forms provides the online forms available in the shop and delivers their fields, required entries, and validations. The endpoint can be used to list all forms, retrieve an individual form or field, and submit completed forms.

---

Supported methods

List of all supported methods.

Command	Endpoints	GET	PUT	POST	DELETE
Retrieve all forms.	form/list
Retrieve a specific form.	form/get
Retrieve a specific form field.	form/getField
Send a form inquiry.	form/send
Retrieve details of a previously sent inquiry.	form/loadInquiry

Methods for forms

These methods cover the complete lifecycle of online forms in the shop. They read out all configured forms including the fields, the required marking, the validations, and the email settings. If required, an individual form or an individual field can be loaded specifically by ID. In addition, it is possible to submit completed forms. In doing so, a transaction ID (inquiryId) is provided, which enables later tracking or detail queries.

GET form/list

The following call returns all forms configured in the shop, including field definitions and email settings. It can be used to create forms including required fields and validations.

GET https://<your-shop>.de/api/v1/form/getAll

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

[
  {
    "email": {
      "fromAddress": "[e-mail]",
      "fromName": "myshop sender",
      "merchantEmail": "[e-mail]",
      "subject": "Your contact inquiry has been received.",
      "template": "contact.htm"
    },
    "fields": [
      { "label": "First name", "name": "firstName", "required": false, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Last name", "name": "lastName", "required": false, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Subject", "name": "subject", "required": true,  "validations": [ { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Customer number", "name": "customerNumber", "required": false, "validations": [ { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Text", "name": "text", "required": true, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] }
    ],
    "name": "contact"
  },
  {
    "email": {
      "fromAddress": "[e-mail]",
      "fromName": "myshop sender",
      "merchantEmail": "[e-mail]",
      "subject": "Your contact inquiry has been received.",
      "template": "contact.htm"
    },
    "fields": [
      { "label": "First name", "name": "firstName", "required": false, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Last name", "name": "lastName", "required": false, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Subject", "name": "subject", "required": true,  "validations": [ { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Customer number", "name": "customerNumber", "required": false, "validations": [ { "name": "maxLength", "type": "dataChecker" } ] },
      { "label": "Text", "name": "text", "required": true, "validations": [ { "name": "minLength", "type": "dataChecker" }, { "name": "maxLength", "type": "dataChecker" } ] }
    ],
    "name": "contact_friendlycaptcha"
  }
]

GET form/get

The following call lets you load an individual form by its technical ID (retrievable via “form/getAll”) including field definitions, required entries, validations, and email settings. It can be used to display a specific form.

Example call that loads a form with the formId contact:

GET https://<your-shop>.de/api/v1/form/get?formId=contact

Parameter overview

Parameter	Type	Description
formId	string	Required field Technical ID of the form (retrievable via form/getAll)

Example response

{
  "email": {
    "fromAddress": "[e-mail]",
    "fromName": "myshop sender",
    "merchantEmail": "[e-mail]",
    "subject": "Your contact inquiry has been received.",
    "template": "contact.htm"
  },
  "fields": [
    {
      "label": "First name",
      "name": "firstName",
      "required": false,
      "validations": [
        { "name": "minLength", "type": "dataChecker" },
        { "name": "maxLength", "type": "dataChecker" }
      ]
    },
    {
      "label": "Last name",
      "name": "lastName",
      "required": false,
      "validations": [
        { "name": "minLength", "type": "dataChecker" },
        { "name": "maxLength", "type": "dataChecker" }
      ]
    },
    {
      "label": "Subject",
      "name": "subject",
      "required": true,
      "validations": [
        { "name": "maxLength", "type": "dataChecker" }
      ]
    },
    {
      "label": "Customer number",
      "name": "customerNumber",
      "required": false,
      "validations": [
        { "name": "maxLength", "type": "dataChecker" }
      ]
    },
    {
      "label": "Text",
      "name": "text",
      "required": true,
      "validations": [
        { "name": "minLength", "type": "dataChecker" },
        { "name": "maxLength", "type": "dataChecker" }
      ]
    }
  ],
  "name": "contact"
}

GET form/getField

The following call loads a form field with label, required status, and validations. It can be used to display the field specifically without reloading the entire form.

Example call that loads the firstName field from the contact form:

GET https://<your-shop>.de/api/v1/form/getField?formId=contact&fieldId=firstName

Parameter overview

Parameter	Type	Description
formId	string	Required field Technical ID of the form (retrievable via form/getAll)
fieldId	string	Required field ID/name of the field in the form (e.g. firstName)

Example response

{
  "label": "First name",
  "name": "firstName",
  "required": false,
  "validations": [
    { "name": "minLength", "type": "dataChecker" },
    { "name": "maxLength", "type": "dataChecker" }
  ]
}

GET form/loadInquiry

The following call lets you load an already sent inquiry by its transaction ID. It can be used to display a confirmation page after submitting the form or to view an inquiry again later.

Example call that loads the inquiry with the ID 7930f7e9fa7bb07b:

GET https://<your-shop>.de/api/v1/form/loadInquiry?inquiryId=7930f7e9fa7bb07b

Parameter overview

Parameter	Type	Description
inquiryId	string	Required field Transaction ID of the inquiry (available, for example, from the response of form/send)

Example response

{
  "createdAt": "2025-11-11T14:36:03Z",
  "form": {
    "customerNumber": { "label": "Customer number", "value": "" },
    "firstName":      { "label": "First name",      "value": "Eren" },
    "lastName":       { "label": "Last name",       "value": "Jäger" },
    "subject":        { "label": "Subject",         "value": "Important message" },
    "text":           { "label": "Text",            "value": "tatakae!" }
  },
  "formId": "contact",
  "id": "7930f7e9fa7bb07b",
  "submitter": {
    "email": "[e-mail]",
    "ipAddress": "172.18.0.XXX",
    "sessionId": "4d1536fe...cd07d"
  }
}

POST form/send

The following call sends a form inquiry (e.g. a contact form) to the shop and creates a transaction for it. It can be used to submit a form and to display a confirmation including the transaction number.

POST https://<your-shop>.de/api/v1/form/send

Example request

{
  "formId": "contact",
  "email": "[e-mail]",
  "form": {
    "firstName": "Eren",
    "lastName": "Jäger",
    "subject": "Important message",
    "text": "tatakae!"
  }
}

Parameter overview

Parameter	Type	Description
formId	string	Required field Technical ID of the form (retrievable via form/getAll)
email	string	Required field Sender/reply email address of the inquiring person.
form	object	Required field Here the field IDs from the form definition (e.g. firstName, subject, text) are specified including their value (first name, subject, etc.).

Example response

{
  "inquiryId": "7930f7e9fa7bb07b"
}

InquiryId is the transaction ID of the sent inquiry.

Error codes

Code	Description
captchaFailed	A captcha is configured for the form and the captcha provided is incorrect.
invalidFormId	The specified form ID is invalid.
createInquiryFailed	Internal error. Please contact WEBSALE support.
emptyForm	The form object is empty.
missingEmail	email was not passed.
emailCheckFailed	The submitted email address is invalid.
formCheckFailed	At least one form field did not pass validation.

Field validation

Faulty fields are reported individually as separate errors with the code formCheckFailed. field contains the field name, subCode the reason:

• formCheck.required: required field without a value
• dataChecker.<name> (for example dataChecker.maxLength, dataChecker.minLength): the validation configured in the form failed
• formCheck.defaultMaxLength: no maxLength validation is configured for the field and the value is longer than 200 characters

Fields that are not visible according to the form configuration are not validated.