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`

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

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

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": "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.

Interfaces

Admin Interface API

Storefront API

More

Supported methods

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

​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

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