Using form spam protection with the Application API

When Form Spam Protection is enabled, a new property isFormSpamProtectionEnabled, is added to the Application API 2.0 Form endpoints. This topic explains how this feature changes working with the Application API endpoints.

Note: This feature is currently released under our Controlled Availability program. To request access to this feature, please contact your account representative for more information.

In this topic:

Impacted Endpoints

When Form Spam Protection is enabled, the following endpoints are impacted:

2.0

Retrieve a list of forms: GET /api/REST/2.0/assets/forms

Default depth is minimal.
Retrieve a form: GET /api/REST/2.0/assets/form/ {id}

Default depth is complete.
Create a form: POST /api/REST/2.0/assets/form

Default depth is complete.
Update a form: PUT /api/REST/2.0/assets/form/{id}

Default depth is complete.
Partially update a form: PATCH /api/REST/2.0/assets/form/{id}

Default depth is complete.

isFormSpamProtectionEnabled Notes

isFormSpamProtectionEnabled is returned at complete depth, when retrieving, updating, or creating a form.
isFormSpamProtectionEnabled is returned as a string with the only two possible values being "true" or "false".
When creating a new form in Eloqua isFormSpamProtectionEnabled is set to "false" by default.
Forms created prior to enabling this feature will have isFormSpamProtectionEnabled set to "false".
When creating a form using the API, if isFormSpamProtectionEnabled is not included in the request, isFormSpamProtectionEnabled will be set to "false".
When updating a form using the API, if isFormSpamProtectionEnabled is not included in the request, isFormSpamProtectionEnabled will be set to "false".
When creating a form using the API, if isFormSpamProtectionEnabled is set to "true", or updating/patching a form if changing isFormSpamProtectionEnabled from "false" to "true" honeypotHtmlName must be included in the request, and if generating custom form html, then the API user must include honeypotHtmlName in the html.
- User must have Change Form Spam Protection Status action permission in order to set isFormSpamProtectionEnabled to "true". Learn more about setting the action permissions for a security group. Learn more about Enabling spam protection for forms.
- If you'd like Eloqua to generate the html, open the form in Eloqua and click Save.
The Application API 1.0 Form endpoints will not return isFormSpamProtectionEnabled, and if included in a Application API 1.0 Form request it will be ignored.

Example requests

Creating new form without specifying isFormSpamProtectionEnabled

Request:

POST /api/REST/2.0/assets/form
{
  "name": "isFormSpamProtectionEnabled not included",
  "elements": [
    {
      "type": "FormField",
      "name": "Favorite color.",
      "style": "{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",
      "dataType": "text",
      "displayType": "text",
      "htmlName": "favCol"
    }
  ],
  "processingType": "externalEmail"
}

Response:

201 Created
{
    "type": "Form",
    "currentStatus": "Draft",
    "id": "84",
    "createdAt": "1639173843",
    "createdBy": "11",
    "depth": "complete",
    "folderId": "7",
    "name": "isFormSpamProtectionEnabled not included",
    "permissions": [
        "Retrieve",
        "SetSecurity",
        "Delete",
        "Update"
    ],
    "updatedAt": "1639173843",
    "updatedBy": "11",
    "archived": "false",
    "elements": [
        {
            "type": "FormField",
            "id": "419",
            "name": "Favorite color.",
            "style": "{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",
            "dataType": "text",
            "displayType": "text",
            "htmlName": "favCol",
            "useGlobalSubscriptionStatus": "False",
            "validations": []
        }
    ],
    "formJson": "{\"type\":\"responsiveForm\",\"version\":\"1\"}",
    "isFormSpamProtectionEnabled": "false",
    "isHidden": "false",
    "isResponsive": "true",
    "processingSteps": [],
    "processingType": "externalEmail"
}

Creating new form setting isFormSpamProtectionEnabled to "true" requires also setting honeypotHtmlName

Request:

POST /api/REST/2.0/assets/form
{
  "name": "isFormSpamProtectionEnabled true",
  "elements": [
    {
      "type": "FormField",
      "name": "Favorite color.",
      "style": "{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",
      "dataType": "text",
      "displayType": "text",
      "htmlName": "favCol"
    }
  ],
  "processingType": "externalEmail",
  "isFormSpamProtectionEnabled": "true"
  "honeypotHtmlName": "address5"
}

Response:

{
    "type": "Form",
    "currentStatus": "Draft",
    "id": "85",
    "createdAt": "1639174129",
    "createdBy": "11",
    "depth": "complete",
    "folderId": "7",
    "name": "isFormSpamProtectionEnabled true",
    "permissions": [
        "Retrieve",
        "SetSecurity",
        "Delete",
        "Update"
    ],
    "updatedAt": "1639174129",
    "updatedBy": "11",
    "archived": "false",
    "elements": [
        {
            "type": "FormField",
            "id": "420",
            "name": "Favorite color.",
            "style": "{\"fieldSize\":\"large\",\"labelPosition\":\"top\"}",
            "dataType": "text",
            "displayType": "text",
            "htmlName": "favCol",
            "useGlobalSubscriptionStatus": "False",
            "validations": []
        }
    ],
    "formJson": "{\"type\":\"responsiveForm\",\"version\":\"1\"}",
    "honeypotHtmlName": "address5",
    "isFormSpamProtectionEnabled": "true",
    "isHidden": "false",
    "isResponsive": "true",
    "processingSteps": [],
    "processingType": "externalEmail"
}

Learn more

Application API

Eloqua API tutorials