GravityAgent documentation

Requirements

Gravity Forms 2.6+, WordPress 6.0+, PHP 7.4+. The free tier needs no card and no key.

Install and activate

Install and activate Gravity Forms 2.6 or later.
Install GravityAgent and activate it.
Go to Forms → Settings → GravityAgent and press Activate this site. The free tier needs no licence key and no card.
Open a form's Settings → GravityAgent tab and switch scoring on. Repeat for each form you want scored — nothing is scored until you say so.
Optional, and worth two minutes: on the settings page, describe your business in the notes field, and untick any field whose contents should never leave your site.

Preconditions

Confirm WordPress 6.0 or later, PHP 7.4 or later, and Gravity Forms 2.6 or later are installed and active (wp core version, wp eval 'echo PHP_VERSION;', wp plugin get gravityforms --field=version).
Confirm you are logged in as a user with the install_plugins and activate_plugins capabilities.

The slug is confirmed in this page's Requirements section the day the listing goes live; until then the plugin info API returns 404 for it.

A. From WordPress.org (once the listing is approved)

In wp-admin go to Plugins → Add New Plugin, search "GravityAgent", click Install Now, then Activate. Or run wp plugin install gravityagent --activate. Or POST /wp-json/wp/v2/plugins with {"slug":"gravityagent","status":"active"} (slug only, no zip).

B. From the zip (before the listing)

Download the zip from https://gravityagent.io/download/ and verify its SHA-256 against the value printed on that page. In wp-admin go to Plugins → Add New Plugin → Upload Plugin, choose the zip, click Install Now, then Activate. Or wp plugin install {zip URL} --activate.

Then, in both cases

Go to Forms → Settings → GravityAgent and click Activate this site. The free tier needs no licence key and no card. Wait for the page to show the site as activated and the site-profile crawl as started.
Open the form to protect: Forms → (form) → Settings → GravityAgent. Switch scoring on and save. Repeat for each form; nothing is scored until you do this.
Optional: on the same tab untick any field whose value must never leave the site. On Forms → Settings → GravityAgent, write one or two sentences about the business in Describe your business.
Verify: submit a test entry on a scored form, open Forms → Entries, and confirm the GravityAgent column shows Passed, Spam or Not scored for it. If it shows Not scored, open the entry; the decision panel names one of five reasons (listed at #not-scored-reasons). Nothing was blocked either way: an unscored entry is admitted.
Report back: the plan and usage shown on Forms → Settings → GravityAgent, and the verdict on the test entry.

Multisite note: network activation is WP-CLI only (--activate-network); the REST route offers no network-active status. Each site activates and is metered separately.

What gets scored, and when

Only forms you switch on; scoring runs on Gravity Forms' own spam filter before notifications, feeds and confirmations; forms not switched on make no call.

The verdicts you will see

The three pills on the Entries column: Spam, Passed, Not scored; the "· corrected" suffix after a correction; the spam likelihood; the "Why?" link to the panel.

Entries3 of 3

Entry	GravityAgent
#1044 · Contact form	Passed3%Why?
#1043 · Contact form	Spam97%Why?
#1042 · Contact form	Not spam · correctedWhy?

The GravityAgent column on the Entries table: the verdict, the spam likelihood, and a link to the reasoning.

The decision panel

The reasoning; "What informed this decision" (Site Profile, Admin Context, Corrections, each with its version); "Decision details" (Model, Decision ID, Scored at, Action threshold, Contract / Policy / Context version).

Entry #1044 · GravityAgent

Passedspam likelihood 3%

Asks about Saturday emergency appointments, which matches the services and hours on the practice's own pages. No links, no offer, no request for payment details.

What informed this decision

Site profilev3 · 14 pages

Your notesv1

CorrectionsEntry #1042 · marked Not spam

Decision ID dec_7f3a…Scored at 09:14:02

The decision panel on an entry: the reasoning in plain language, what informed the decision, and the decision details.

Both panels are drawn from the plugin's own labels; the entry text and reasoning are samples.

Correcting a verdict

Use Gravity Forms' own Spam / Not Spam actions on the row or the entry; the acknowledgment "Correction noted — it informs future decisions for this site."; the panel line "You marked this not spam. Your correction informs future decisions for this site."

Corrections are examples for that form's later submissions, selected per submission. They live in your WordPress database and are read live from the entry; delete the entry and the example disappears.

"Not scored", and the reasons

The plugin admits the entry and records one of five reasons; the panel's plain-language line for each:

timeout: GravityAgent did not answer within its 3-second budget.
engine_error: GravityAgent could not be reached, or answered with something unusable.
quota_reached: This site has used every decision included in its current period; scoring resumes when the period renews or the plan is upgraded.
subscription_inactive: The subscription is not active; reactivate to resume.
not_activated: GravityAgent is not activated on this site yet.

Nothing is ever marked spam because of a failure on our side.

The suppression boundary

This is a Gravity Forms property, not a defect.

When GravityAgent marks an entry spam, Gravity Forms itself suppresses the notifications, feeds and confirmations for that entry, exactly as it does for any spam entry. One hook is outside that guarantee: Gravity Forms fires gform_after_submission for every submission, spam included. If you or another plugin send e-mail, call an API or create records directly from that hook, those actions will still run on spam entries. Use a feed, or check the entry's status in your hook, if that matters to you.

Site profile and your notes

GravityAgent reads your public pages at activation, on Re-crawl, and about every 60 days; nothing behind a login. The "Describe your business" field is sent as you write it and used on every decision for this site. Re-crawl is available once a day.

Keeping a field on this site

The form tab's "Fields to keep on this site"; excluded values never leave the site, including in later correction examples; passwords and presentation fields are never offered; file uploads send the file name only.

Plans, limits and the trial

Tier	Price	Sites	Scored submissions per month
Free	$0	1	250
Starter	$99 / year	1	2,000
Growth	$249 / year	5	10,000
Agency	$599 / year	25	50,000

The 10% grace allowance; admitted unscored past the limit; no overage; 14-day Growth trial, 1,000 scored submissions, once per customer and once per site; upgrades immediate, downgrades and cancellations at period end.

Several sites on one licence

Activate each site from its own settings page; "Sites using this licence" and "Free this slot"; deactivating frees the slot and stops scoring there while submissions keep coming through.

Multisite

Each site activates and is metered separately.

What is stored, and where

Entries stay in WordPress; GravityAgent keeps non-content decision records for about 90 days, daily outcome counts, and the site profile and notes until deactivation; stored data is US-only; the four legal pages.

What the plugin sends

When	Sent to `api.gravityagent.io`	Never sent
Every submission of an enabled form	The submitted field values minus excluded fields; file uploads as file name and field label; the submitter's IP address, user agent, timestamp and page URL; past corrections on that form as examples (field content read live from the entry, minus exclusions, plus the corrected label)	Excluded field values; file contents and file URLs; passwords and presentation fields
When you correct a verdict	The decision id, the label you corrected to, the direction of the correction	Any submission content
When you activate the site	The site's domain; on a paid plan, the licence key and merchant identifiers. The service then crawls the site's public pages	Anything behind a login; form entries
On the settings page	The Admin Context notes you type; the crawl's status is read	—
Once a day	Six counts: scored; not scored because of timeout, unreachable service, monthly limit, inactive subscription, site not activated	Form content, field values, entry or form identifiers, page URLs
Paid plans, trial, updates (Freemius)	Site URL, WordPress and PHP versions; if you opt in, administrator e-mail and a usage profile	Form submissions

GravityAgent is a hosted scoring service. The plugin cannot score anything on its own, so using it means sending form submissions to us. Exactly what is sent, when, and why:

1. The GravityAgent Decision Engine (https://api.gravityagent.io)

On every submission of a form you have enabled, the plugin sends one request containing:

The submitted field values of that entry — the same text your notification email would contain — minus any field you have excluded on the form's GravityAgent tab. Excluded field values are stripped before the request is built and never leave your site.
File uploads as metadata only: the file name and field label. File contents and file URLs are never sent.
Ambient submission metadata: the submitter's IP address, the browser user agent, the submission timestamp, and the URL of the page the form was on.
Past corrections you have made on that form, as examples. An example carries the same field content the original entry holds (read live from that entry, minus your exclusions) plus the label you corrected it to. If you delete the entry, the example disappears with it.

When you correct a verdict, the plugin sends the decision id, the label you corrected it to, and the direction of the correction — no submission content.

When you activate the site, the plugin sends your site's domain and, on a paid plan, your licence key and merchant identifiers, in exchange for an API token. The service then crawls your site's public pages — the same pages any search engine reads — to build a profile of what your business does, so that a genuine enquiry about your actual services is recognised as one. Nothing behind a login and no form entries are read by the crawl.

On the settings page, the plugin sends and retrieves the notes you type into the Admin Context field, and reads the crawl's status.

Once a day, an activated site asks the service for its current plan, usage and renewal date, so the settings page stays accurate on a site that has had nothing to score. That request carries six counts of what happened to submissions since the last successful one: how many were scored, and how many were not scored because the request timed out, the service could not be reached, your monthly limit was reached, your subscription was inactive, or the site was not activated. They are counts and nothing else — no form content, no field values, no entry or form identifiers, no page URLs. They exist so we can measure how often the plugin has to fail open and admit an entry unscored, which is the promise it is built on. There is no third-party analytics in this plugin, and nothing else is sent in the background.

Submissions are processed to return a verdict and are not used to train any model. The service is operated by GravityAgent.

Terms: https://gravityagent.io/terms/
Privacy policy: https://gravityagent.io/privacy/
Data Processing Addendum: https://gravityagent.io/dpa/
Subprocessors: https://gravityagent.io/subprocessors/

2. Freemius (https://freemius.com)

Licence activation, checkout, the trial and plugin updates are handled by Freemius, our merchant of record. Freemius receives your site URL, WordPress and PHP versions and, if you opt in, your administrator email address and a plugin usage profile. It is opt-in: the plugin works fully if you decline.

Terms: https://freemius.com/terms/
Privacy policy: https://freemius.com/privacy/

Stored by GravityAgent: no submission content, anywhere; non-content decision records (ids, label, confidence, model, latency, tokens) for about 90 days; daily outcome counts; the site profile and your notes until deactivation; stored data US-only; in-flight processing at the nearest Cloudflare edge and at Google. Deleting the entry deletes the content; deactivating the site deletes its profile and notes immediately. Nothing is used to train any model.

Uninstalling

Removes options, the corrections table and the activation, and hands the licence slot back; entries and their decision history are left untouched.

Getting help

[email protected]; the "Reference for support" id shown on a crawl error; the Decision ID on any entry.