Skip to main content
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.
CommandEndpointsGETPUTPOSTDELETE
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

ParameterTypeDescription
——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

ParameterTypeDescription
formIdstringRequired 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

ParameterTypeDescription
formIdstringRequired field
Technical ID of the form (retrievable via form/getAll)
fieldIdstringRequired 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

ParameterTypeDescription
inquiryIdstringRequired 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

ParameterTypeDescription
formIdstringRequired field
Technical ID of the form (retrievable via form/getAll)
emailstringRequired field
Sender/reply email address of the inquiring person.
formobjectRequired 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

CodeDescription
captchaFailedA captcha is configured for the form and the captcha provided is incorrect.
invalidFormIdThe specified form ID is invalid.
createInquiryFailedInternal error. Please contact WEBSALE support.