> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`        | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" /> |
| Retrieve a specific form.                      | `form/get`         | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" /> |
| Retrieve a specific form field.                | `form/getField`    | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" /> |
| Send a form inquiry.                           | `form/send`        | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Retrieve details of a previously sent inquiry. | `form/loadInquiry` | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" /> |

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/form/getAll
```

#### **Parameter overview**

| **Parameter** | **Type** | **Description**           |
| ------------- | -------- | ------------------------- |
| --            | --       | No additional parameters. |

#### **Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
  {
    "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`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/form/get?formId=contact
```

#### **Parameter overview**

| **Parameter** | **Type** | **Description**                                                                  |
| ------------- | -------- | -------------------------------------------------------------------------------- |
| `formId`      | string   | **Required field**<br />Technical ID of the form (retrievable via `form/getAll`) |

#### **Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/form/getField?formId=contact&fieldId=firstName
```

#### **Parameter overview**

| **Parameter** | **Type** | **Description**                                                                  |
| ------------- | -------- | -------------------------------------------------------------------------------- |
| `formId`      | string   | **Required field**<br />Technical ID of the form (retrievable via `form/getAll`) |
| `fieldId`     | string   | **Required field**<br />ID/name of the field in the form (e.g. `firstName`)      |

#### **Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/form/loadInquiry?inquiryId=7930f7e9fa7bb07b
```

#### **Parameter overview**

| **Parameter** | **Type** | **Description**                                                                                                  |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `inquiryId`   | string   | **Required field**<br />Transaction ID of the inquiry (available, for example, from the response of `form/send`) |

#### **Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
POST https://<your-shop>.de/api/v1/form/send
```

#### **Example request**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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**<br />Technical ID of the form (retrievable via `form/getAll`)                                                                                           |
| `email`       | string   | **Required field**<br />Sender/reply email address of the inquiring person.                                                                                                |
| `form`        | object   | **Required field**<br />Here the field IDs from the form definition (e.g. `firstName`, `subject`, `text`) are specified including their value (first name, subject, etc.). |

#### **Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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.                             |