About the Spam Submissions API

The Spam Submissions API lets you check form submissions for spam and manage the submissions of Wix Forms forms that were flagged as spam.

With the Spam Submissions API, you can:

• Check whether a submission is spam.
• Query, retrieve, and count a form's spam submission reports.
• Report a submission as spam.
• Restore a spam submission as a regular submission.
• Delete spam submission reports.

A submission flagged as spam is stored as a form spam submission report, which holds the submitted values, the submitter, and the reason the submission was flagged. Regular submissions are managed with the Form Submissions API, and forms are managed with the Form Schemas API.

How spam is detected

Wix Forms checks new submissions for spam automatically. You don't need to call Check For Spam for this.

Which checks run depends on the form's spamFilterProtectionLevel in the Form Schemas API:

• NONE: Spam moderation service plugins installed on the site.
• BASIC: Moderation service plugins, blocklisted IP addresses and email addresses, and too many submissions from the same email address in a short time.
• ADVANCED: All basic checks, plus AI-based checks of the submission text.

The reportReason field of each report shows which check flagged the submission.

Spam submission lifecycle

A form spam submission report goes through these stages:

• Reported as spam: A report is created, and the original submission is deleted. This happens when an automatic check flags a submission, or when you call Report Spam Submission.
• Restored as not spam: When you call Report Not Spam Submission, a new submission is created from the report's data, with a new submission ID, and the report is deleted. A submission that was PENDING when reported is restored as CONFIRMED. Any other status is kept. Submission automations run as they do for any new submission, and uploaded files are kept.
• Deleted: When you call Delete Form Spam Submission Report, the report is permanently deleted, together with its uploaded files.
• Expired: Reports are deleted automatically after 30 days, together with their uploaded files.

To store a spam submission that was never saved as a regular submission, call Create Form Spam Submission Report. Unlike Report Spam Submission, it doesn't delete a submission.

Site owners see spam submission reports in the spam section of the form's submissions in the Wix dashboard. When a report is restored, the submission appears again in the form's submissions.

Before you begin

It's important to note the following points before starting to code:

• The Spam Submissions API works with forms of the Wix Forms app. Call Get App Instance to confirm that the app named wix_forms is installed on the site.
• The API supports forms in the Wix Forms namespace, wix.form_app.form. Calls for forms in other namespaces fail with a permission error.
• When you query or count reports, specify the namespace. Query filters must include namespace, and Count Form Spam Submission Reports requires the namespace parameter.

Use cases

• Manage a form's spam folder
• Let site owners mark submissions as spam
• Clear spam flagged for a specific reason

Terminology

• Form spam submission report: A stored copy of a submission that was flagged as spam, with the reason it was flagged.
• Namespace: The app that a form belongs to. For Wix Forms, wix.form_app.form.
• Spam protection level: A form setting that controls which spam checks run on its submissions.
• Spam moderation service plugin: An app extension that checks submissions for spam and can flag them.