Storefront API Forms

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`

Error format

All errors are answered with HTTP 400 and the following body:

{
  "error": "actionFailed",
  "detail": "Action Failed",
  "actionErrors": [
    { "code": "missingFormId", "subCode": "", "field": "formId", "text": "…", "details": {} }
  ]
}

error = invalidParameters for errors in parameters/field types (details in paramErrors, key = parameter name, value {"type": "missing" | "invalidFormat" | "invalidValue" | "unknownField" | …}).
error = actionFailed for functional errors. The error codes listed in the following tables then appear in actionErrors[].code.
A call with a wrong HTTP method is answered with HTTP 404 (not 405).
If the session (x-session) is missing, the response is HTTP 400.

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.

The endpoint has no parameters. The response is a JSON array of form objects. The order corresponds to the configuration order. The name field of each object is the formId for form/get, form/getField, and form/send.

Example response

[
  {
    "email": {
      "fromAddress": "contact@myshop.de",
      "fromName": "myshop sender",
      "merchantEmail": "dev-test@websale.de",
      "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": "contact@myshop.de",
      "fromName": "myshop sender",
      "merchantEmail": "dev-test@websale.de",
      "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"
  }
]

Each field object in fields[] can additionally contain the following fields:

Field	Type	Description
`name`	string	Technical field name, also the key in the `form` object of `form/send`.
`label`	string	Label of the field.
`value`	string	Currently submitted value (empty for a plain retrieval).
`defaultValue`	string	Prefill of the field.
`required`	bool	Required field. Can depend on other field values via form rules.
`visible`	bool	If the field is `false`, it is neither expected nor validated on the server side.
`validations`	Array	Configured checks, each with `name` (for example `maxLength`) and `type` (for example `dataChecker`).

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": "contact@myshop.de",
    "fromName": "myshop sender",
    "merchantEmail": "dev-test@websale.de",
    "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"
}

Each field object in fields[] additionally contains value, defaultValue, and visible; see the field table under form/list.

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" }
  ]
}

The field object additionally contains value, defaultValue, and visible; see the field table under form/list.

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": "test@example.de",
    "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": "test@example.de",
  "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.
`missingFormId`	`formId` was not passed.
`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.

Interfaces

Admin Interface API

Storefront API

More

Supported methods

Error format

Methods for forms

GET form/list

Parameter overview

Example response

GET form/get

Parameter overview

Example response

GET form/getField

Parameter overview

Example response

GET form/loadInquiry

Parameter overview

Example response

POST form/send

Example request

Parameter overview

Example response

Error codes

​Supported methods

​Error format

​Methods for forms

​GET form/list

​Parameter overview

​Example response

​GET form/get

​Parameter overview

​Example response

​GET form/getField

​Parameter overview

​Example response

​GET form/loadInquiry

​Parameter overview

​Example response

​POST form/send

​Example request

​Parameter overview

​Example response

​Error codes

Supported methods

Error format

Methods for forms

GET form/list

Parameter overview

Example response

GET form/get

Parameter overview

Example response

GET form/getField

Parameter overview

Example response

GET form/loadInquiry

Parameter overview

Example response

POST form/send

Example request

Parameter overview

Example response

Error codes