Gravity Forms ability reference
Reference for the GoBuildWP Pro 1.12.4 and Free 1.18.6 source. Installed schemas and policy remain authoritative.
This Gravity Forms ability reference covers how an agent can build and change Gravity Forms forms with their fields, notifications and confirmations, and work through the entries each form has collected: reading, starring, correcting, trashing and exporting them. Gravity Forms is sold as a single paid plugin with no Lite edition, so there is no vendor edition split: with GoBuildWP Pro, every call is on offer whenever the plugin passes the version check, and GoBuildWP Free covers only listing forms and entries.
Read-only, write and destructive groups describe the source annotations. They do not establish a minimum safety profile, human approval or undo support. Those controls are separate: check the installed ability, the connected user and the active site policy before calling it. A read can still return sensitive data. These pages are not evidence that every operation passed an end-to-end runtime test.
What Gravity Forms needs before these load
2 of the 29 also ship in GoBuildWP Free 1.18.6 under the same names, marked “Also in GoBuildWP Free” below. They need no GoBuildWP Pro licence, but each retains its own dependency, feature and permission checks. Where Free's copy does less, its own description follows Pro's. When Pro's richer copy passes its gates, it registers first and answers.
Gravity Forms 2.7 or newer must be active. Pro's manifest gate looks for the GFForms and GFAPI classes and compares GFForms::$version with that floor, the release where GFAPI::current_user_can_any() and the current field registry settled. Below it, or with the plugin off, the gravityforms category is not registered. Each call checks Gravity Forms' own capabilities through GFAPI::current_user_can_any(), so the gform_user_can_any filter still applies: gravityforms_view_entries to read entries, gravityforms_edit_entries and gravityforms_delete_entries to change them, gravityforms_export_entries to export. A refusal returns gravityforms_capability_missing (403). The free plugin's entry read withholds email and phone answers too and has no include_sensitive; editing, exporting and flagging entries and every form write are Pro's.
- Minimum (base)
- 2.7
WPPILOT_PRO_GRAVITYFORMS_MIN_VERSION - Gravity Forms editions
- free, pro
- Agent skills shipped
gravityforms-integration,form-model-schema,form-model-migration
What a Gravity Forms entry shows the agent
Entry values are keyed by input id, so a Name field arrives as several keys such as "1.3" rather than one string. A field whose type is password, creditcard, fileupload, post_image or signature, or whose label reads like a card number, CVV or IBAN, comes back as [REDACTED] and is named in redacted_fields; the submitter's ip gets the same treatment. Clear values need include_sensitive=true together with confirm=true after the user has asked, and include_sensitive on its own is refused with form_entries_sensitive_confirm_required.
Search is narrowed too. Gravity Forms' keyless "any field" filter looks inside every input, which would let an agent confirm a guessed password by noticing which entries matched. Without the sensitive opt-in, wppilot/gravityforms-list-entries and the export search the readable inputs one by one. A search combined with the starred or read filter is answered from two id lists capped at 20000 ids each, and returns gravityforms_unsupported on a build that lacks GFAPI::get_entry_ids().
Trash, force and the writes nothing can reverse
Gravity Forms keeps its forms and entries in its own gf_* tables, with the form definition held as JSON meta beside the wp_gf_form row. Deleting a form or an entry trashes it by default, so the owner can restore it from the Gravity Forms admin; force=true removes it for good, and for a form that takes every entry, note and meta row with it. A trashed form refuses edits with gravityforms_form_trashed (410).
The change ledger records every Gravity Forms write as irreversible, because it lands in those tables, so wppilot/rollback-change cannot help here. wppilot/gravityforms-edit-entry is marked destructive for the same reason: Gravity Forms keeps no revision of an entry, and GoBuildWP holds the call until confirm=true. Passing expected_date_updated from your last read turns a clash with another editor into gravityforms_concurrent_modification (409). wppilot/gravityforms-edit-form-settings replaces the whole settings bucket and drops keys you leave out, and deleting a field never renumbers the others, because stored entries point at field ids.
Before accepting the result
A field edit and a settings-bucket replacement have different scope. Read the whole settings bucket before replacing it, then inspect a synthetic rendered submission and test notification in an authorized mail sandbox.
Representative call sequence
This sequence describes the documented calls and checks to perform. It is not a recorded result from an installed WordPress site. Inspect returned errors and partial results, then verify the saved values and affected output before proceeding.
Correct a misspelt first name on last week's quote request and star it for follow-up.
- 01
wppilot/gravityforms-list-entriesFilters the quote form by date_from and returns compact rows with ids, is_read and is_starred; the ip column reads [REDACTED]. - 02
wppilot/gravityforms-get-entryReturns the values keyed by input id, with the first name under a key such as "1.3", plus the date_updated to guard the next write. - 03
wppilot/gravityforms-edit-entryWrites the corrected value to that input id with expected_date_updated set, once the user confirms, and lists the key in updated_fields. - 04
wppilot/gravityforms-mark-entrySets flag starred to true; changed is false if the entry was already starred.
Questions about Gravity Forms
Can the agent read card numbers or uploaded files from Gravity Forms entries?
Not by default. Those values and the IP come back as [REDACTED]. With GoBuildWP Pro they are released when include_sensitive=true and confirm=true are passed after the user has asked for them; GoBuildWP Free never releases them.
Does duplicating a Gravity Forms form copy its entries?
No. wppilot/gravityforms-duplicate-form copies fields, settings, notifications and confirmations, and the copy starts inactive unless you set its status, so it cannot quietly start taking submissions.
How do I get back a form the agent deleted?
Restore it from the trash in the Gravity Forms admin, which is where a delete without force=true puts it. A forced delete has no way back, and the change ledger cannot restore Gravity Forms tables.
Gravity Forms reads
| Ability | What it does |
|---|---|
wppilot/gravityforms-check-setupCheck Gravity Forms Setup | Reports the Gravity Forms environment: whether the plugin is active, its version, the field types this install can use, the WP capabilities that gate form/entry management, and the form count. Gravity Forms is a single-SKU paid plugin (no Lite/Pro split), so every form, entry, notification and confirmation surface is available whenever the plugin is active. Call this first before any other gravityforms ability. |
wppilot/gravityforms-export-entriesExport Gravity Forms Entries | Export one form's entries as CSV or JSON with field labels as headers, via GFAPI::get_entries. Filters: status (active | spam | trash | any), date_from / date_to, starred, read, search (any field value; the redacted password, card, file and signature fields and the IP are searched only with include_sensitive=true and confirm=true). Up to 5000 rows per call (a ~200 KiB budget may stop sooner); pass next_cursor back as cursor until it is null. Password, credit-card, file-upload, signature and IP columns are [REDACTED] unless include_sensitive=true with confirm=true. |
wppilot/gravityforms-get-entryGet Gravity Forms Entry | Return one Gravity Forms entry. Includes the entry meta (id, form_id, status, date_created, date_updated, is_read, is_starred, ip, user_agent, source_url, created_by) and the field values keyed by input id (so for a "1.3" sub-input the key is "1.3"). Each field value is a string - multi-input fields (name, address, checkbox) surface as multiple keys. |
wppilot/gravityforms-get-field-type-schemaGet Gravity Forms Field Type Schema | Describe one Gravity Forms field type - the human-readable label, the description, and the configuration options the agent may set when adding or editing a field of that type. Call check-setup first for the authoritative list of types this install can use; this ability returns gravityforms_unknown_type for a slug not registered (e.g. a Pro add-on field type when the add-on is inactive). |
wppilot/gravityforms-get-field-types-schemaList Gravity Forms Field Types | Return the catalog of every Gravity Forms field type the integration can build via add-field / edit-field on this install. Output is compact: per entry {type, label, category, pro_only}. Use this FIRST when constructing a form, then call wppilot/gravityforms-get-field-type-schema for the per-type settings whitelist + supports[]. Gravity Forms has no Lite/Pro license split - pro_only is always false; categories reflect the Gravity field-editor groupings (standard, advanced, post_fields, pricing_fields). Mirrors the catalog-vs-detail pattern used by wpforms-get-field-types-schema, fluentforms-get-field-types-schema, formidable-get-field-types-schema. |
wppilot/gravityforms-get-formGet Gravity Forms Form | Return the full definition of one Gravity Forms form: fields (indexed array), notifications (id-keyed map), confirmations (id-keyed map), and settings (button, save, pagination, schedule, limit-entries, require-login, post-creation, animation, css classes, etc.). Use include_* flags to slim the response when only inspecting one section. |
wppilot/gravityforms-get-form-canonicalGet Gravity Forms Form (Canonical) | Reads a single Gravity Forms form by id and returns it mapped to the plugin-agnostic form-model-schema vocabulary (17 canonical types: text/email/tel/url/number/textarea/date/time/datetime/select/radio/checkbox/file/hidden/submit/consent/group) used by the form-model-migration skill. The ~47 Gravity Forms native field types fold onto those 17 - composites (name, address) collapse to canonical group with sub-fields; structural-only types (section, page, html) drop with informational warnings; payment and post-creation types (creditcard, product, singleproduct, quantity, option, shipping, total, donation, post_*, calculation) drop with structural warnings. Output keys: fields[] with canonical types, mail_config{} from the first active notification, notifications[] from the remaining ones, messages{} (empty - Gravity Forms has no built-in message catalogue), conditional_rules[] from per-field GF conditionalLogic (mapped 1:1 when expressible), meta{} (source plugin + version + confirmations / settings echo for round-trip), plus warnings[] for everything that does not fit the canonical shape (multi-page forms, anti-spam captcha, complex conditional logic, payment + post-creation fields). Honours the same max_field_bytes truncation contract as wpforms-get-form-canonical (default 8192 bytes for mail_config.body, notifications[].body, with *_truncated flags); pass max_field_bytes: 0 to disable truncation when full-fidelity canonical is required before an execute-mode migration. Returns WP_Error gravityforms_form_not_found when the id does not exist or refers to a trashed form. Use this ability inside the form-model-migration workflow (Phase 2 - read source schema); for ad-hoc inspection outside the migration pipeline, prefer gravityforms-get-form which returns the Gravity-native shape. |
wppilot/gravityforms-list-confirmationsList Gravity Forms Confirmations | List every confirmation configured on a Gravity Forms form, keyed by id. Confirmations decide what the visitor sees after submitting: a message, a redirect to a page, or a redirect to an arbitrary URL. |
wppilot/gravityforms-list-entriesList Gravity Forms EntriesAlso in GoBuildWP Free | List entries (form submissions) for one form. Returns compact rows (id, form_id, status, date_created, date_updated, is_read, is_starred, ip) - call get-entry to read a single entry's field values. Paginated with limit (default 25, max 200) and offset; filterable by status (active | spam | trash | any) and a date range. In GoBuildWP Free: List one Gravity Forms form's entries, newest first, with their answers: id, form_id, status, date_created, date_updated, is_read, is_starred, ip (always [REDACTED]) and answers (field_id, label, type, value; a field of several inputs, such as a name or address, gives its parts by input label). Filters: status (active | spam | trash | any, default active), date_from / date_to (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS, inclusive), starred, read; orderby id, date_created or date_updated. limit defaults to 20 (max 100), offset pages. Contact details and sensitive fields are withheld (names and other answers are not):email and phone answers, passwords, card and payment data, file uploads, signatures and the submitter's IP come back as "[REDACTED]" with a redacted reason, and email addresses or phone numbers typed into any other answer are cut out of it (redacted: "contact_in_text"). There is no option to return them here; the full values need the Pro edition (with the person's explicit approval) or the Gravity Forms Entries screen. |
wppilot/gravityforms-list-formsList Gravity Forms FormsAlso in GoBuildWP Free | List Gravity Forms forms with a compact row per form (id, title, status, dates, entry count). Paginated with limit (default 50, max 500) and offset; filterable by status (active | inactive | trash | any). Use get-form to read a single form's full definition (fields, settings, notifications, confirmations). In GoBuildWP Free: List Gravity Forms forms with a compact row per form (id, title, status, dates, entry count). Paginated with limit (default 50, max 500) and offset; filterable by status (active | inactive | trash | any). Use wppilot/gravityforms-list-entries for a form's submissions. |
wppilot/gravityforms-list-notificationsList Gravity Forms Notifications | List every notification configured on a Gravity Forms form, keyed by id. Use before crafting a notification mutation so you know what already exists and what id to target. |
Gravity Forms writes
| Ability | What it does |
|---|---|
wppilot/gravityforms-add-fieldAdd Gravity Forms Field | Append a field to a Gravity Forms form. Required: form_id, type, label. Type must be in check-setup.available_field_types (an unknown type is rejected). The new field gets the next sequential id from GFFormsModel::get_next_field_id and is appended to the fields[] array. Pass options for type-specific knobs (choices for select/checkbox/radio, inputMask for phone, etc.). |
wppilot/gravityforms-create-confirmationCreate Gravity Forms Confirmation | Append a confirmation to a Gravity Forms form. Required: form_id, name, type (message | page | redirect). For type=message, pass message (defaults to "Thanks for contacting us!"); for type=page, pass pageId (a published page must exist); for type=redirect, pass url (must be a valid absolute URL). New confirmation gets a fresh 13-char id. |
wppilot/gravityforms-create-formCreate Gravity Forms Form | Create a new Gravity Forms form. Required: title. Optional: description, status (active | inactive, default active), and an initial settings override (button, save, pagination, schedule, limit-entries, require-login, etc.). The new form starts empty (no fields) - add fields with add-field in a later step. Returns the new form id plus the same compact row list-forms emits. |
wppilot/gravityforms-create-notificationCreate Gravity Forms Notification | Append a notification to a Gravity Forms form. Required: form_id, name, to. Optional: subject, message, fromName, from, replyTo, bcc, event (form_submission | feed_processed, default form_submission), enabled (default true). Merge tags ({admin_email}, {all_fields}, {Field Name:N}) are accepted verbatim. The new notification gets a fresh 13-char id (uniqid-style). |
wppilot/gravityforms-duplicate-formDuplicate Gravity Forms Form | Duplicate an existing Gravity Forms form. Required: form_id. Optional: title (defaults to "<original title> - Copy 1" - GF auto-bumps the suffix on collision) and status (defaults to "inactive" so the duplicate does not silently start accepting submissions). The new form copies fields, settings, notifications, and confirmations from the source. Entries are NOT copied. |
wppilot/gravityforms-edit-confirmationEdit Gravity Forms Confirmation | Edit a confirmation on a Gravity Forms form. Pass any of: name, type, message, pageId, url, queryString. Switching type validates the new payload (e.g. switching to page requires a valid pageId). |
wppilot/gravityforms-edit-fieldEdit Gravity Forms Field | Edit a field on a Gravity Forms form by id. Pass any of: label, description, required, cssClass, adminLabel, options (type-specific keys merged flat). The field type cannot change here - delete + add for a type change. The returned field is the result after the patch is applied. |
wppilot/gravityforms-edit-formEdit Gravity Forms Form | Edit a Gravity Forms form's top-level properties (title, description, is_active) AND/OR apply a partial settings patch. Fields, notifications and confirmations are NOT touched by this ability - use manage-fields / manage-notifications / manage-confirmations for those. Optimistic concurrency: pass expected_date_updated (the value from the last get-form / list-forms call) to detect a concurrent write - the call returns gravityforms_concurrent_modification (409) instead of overwriting. |
wppilot/gravityforms-edit-notificationEdit Gravity Forms Notification | Edit a notification on a Gravity Forms form by id. Pass any of: name, to, subject, message, fromName, from, replyTo, bcc, event, enabled. An empty to is rejected (would silently clear the recipient list). |
wppilot/gravityforms-mark-entryMark Gravity Forms Entry | Toggle a binary flag on an entry: read (is_read) or starred (is_starred). Returns the previous and new values so the caller can see whether the call actually flipped anything (idempotent: passing the existing value is a no-op). |
wppilot/gravityforms-reorder-fieldsReorder Gravity Forms Fields | Reorder the fields[] array of a Gravity Forms form. Pass field_ids as the new positional list - every existing field id MUST appear exactly once, missing or extra ids are rejected. Field ids are NOT renumbered; only the array order changes. |
Destructive Gravity Forms calls
| Ability | What it does |
|---|---|
wppilot/gravityforms-delete-confirmationDelete Gravity Forms Confirmation | Remove a confirmation from a Gravity Forms form by id. Returns the removed confirmation for confirmation. A missing confirmation is treated as idempotent success. |
wppilot/gravityforms-delete-entryDelete Gravity Forms Entry | Delete a Gravity Forms entry. Default trashes the entry (status flips to "trash" - restorable from the GF admin). Pass force=true to permanently delete (irreversible). Returns the previous status so the caller can confirm what was removed. |
wppilot/gravityforms-delete-fieldDelete Gravity Forms Field | Remove a field from a Gravity Forms form by id. The remaining fields keep their positions and ids (gaps are NOT compacted - entries already submitted reference field ids directly, so renumbering would corrupt them). Returns the removed field for confirmation. |
wppilot/gravityforms-delete-formDelete Gravity Forms Form | Delete a Gravity Forms form. Default trashes the form (is_trash flips to 1 - restorable from the Gravity Forms admin or by re-editing the form). Pass force=true to permanently delete the form AND all its entries (irreversible). A form already in trash is a no-op when force=false (idempotent); call with force=true to permanently delete a trashed form. |
wppilot/gravityforms-delete-notificationDelete Gravity Forms Notification | Remove a notification from a Gravity Forms form by id. Returns the removed notification for confirmation. A missing notification is treated as idempotent success. |
wppilot/gravityforms-edit-entryEdit Gravity Forms Entry | Update field values on one Gravity Forms entry. Pass fields as a map of input id → new value (e.g. {"1": "New Name", "2.3": "Last"}). Multi-input fields (name, address, checkbox) accept individual sub-input ids ("1.3"). Optional expected_date_updated enables optimistic concurrency - the call rejects with gravityforms_concurrent_modification (409) if the entry was touched since the last read. |
wppilot/gravityforms-edit-form-settingsEdit Gravity Forms Form Settings | Replace the settings block of a Gravity Forms form. Settings is the bucket of top-level keys that are NOT fields / notifications / confirmations: button, save, pagination, scheduleForm*, limitEntries*, requireLogin*, postCreation, animation, css classes, etc. The new settings map fully replaces existing settings keys; structural keys (id, title, fields, notifications, confirmations, dates, is_active, is_trash) are protected and cannot be overwritten via this ability. Use edit-form to change title / description / is_active. |
For the task-level view of Gravity Forms, with worked requests and what to check afterwards, see Gravity Forms integration page.