Pro module22 abilities

Ninja Forms ability reference

Reference for the GoBuildWP Pro 1.12.4 source. Installed schemas and policy remain authoritative.

This Ninja Forms ability reference covers how an agent can create, duplicate and edit Ninja Forms forms and fields, manage the email actions that serve as notifications, and read, trash or export submissions. No paid Ninja tier gates any of these calls; which field types are available depends on the Ninja add-ons installed.

By GoBuildWPContent updated 12 October 2026How we check claims

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 Ninja Forms needs before these load

Ninja Forms 3.13.0 or newer must be active. The gate checks for the Ninja_Forms class and reads its Ninja_Forms::VERSION constant, since Ninja defines no top-level version constant; 3.13.0 is the floor because the source's version note records that release, on Ninja's maintained line, as passing the integration smoke suite, while 3.6 and 3.7 fail on PHP 8; below it nothing registers. Every call requires manage_options and returns ninja_forms_forbidden (403) without it. wppilot/ninja-forms-check-setup also reports storage_ready; false means Ninja's NF3 upgrader has not finished, and opening the Ninja Forms admin page once completes it. The calls drive Ninja's PHP model directly and do not need Ninja's own ninjaforms/* abilities.

Minimum (base): 3.13.0 WPPILOT_PRO_NINJAFORMS_MIN_VERSION
Ninja Forms editions: free, pro
Agent skills shipped: ninja-forms-integration, form-model-schema, form-model-migration

What a Ninja submission reveals

wppilot/ninja-forms-get-submission returns answers with field id, field key and label, skipping display fields (submit, html, hr, note). Password, credit-card, file-upload and signature answers are [REDACTED] and listed in redacted_fields until include_sensitive=true with confirm=true. The submission must belong to the form_id you pass, or the call answers ninja_forms_submission_not_found.

A Ninja export row carries the submission id, sequence number, date and status, then one column per answer; there is no IP column and no starred or read flag to filter on. Notifications have a separate filter: wppilot/ninja-forms-get-notification redacts setting values that look like secrets and sets has_secrets when it has done so.

Forms in nf3 tables, submissions as posts

Ninja keeps forms, fields and actions in its nf3_forms, nf3_fields and nf3_actions tables and caches each form in nf3_upgrades, with an nf_form_<id> option as fallback; the module clears that cache after structural writes so the next read is current. Submissions are nf_sub posts holding each answer in _field_<id> meta beside a _seq_num.

Storage decides the undo. Form, field and notification writes are recorded as irreversible. Deleting a submission trashes the post, which the ledger can restore with wppilot/rollback-change, while force=true deletes it permanently. wppilot/ninja-forms-delete-form has no trash at all: the form, its fields, its actions and every submission go together.

Nothing is locked. Ninja rewrites a form's or field's whole settings row on save, so two parallel edits to the same item end with the later one replacing the entire blob; run them one after another. Field keys are derived from the label and made distinct per form, so read the returned key back. Create-form appends a submit button when fields[] has none.

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.

Copy the event sign-up form for next year and send its notification to the new organiser.

01 wppilot/ninja-forms-duplicate-form Creates the copy with new_title set, carrying settings, fields and actions but no submissions, and returns its id.
02 wppilot/ninja-forms-list-notifications Lists the email actions on the new form with their ids and recipients, active and inactive alike.
03 wppilot/ninja-forms-edit-notification Changes to on that notification and returns changed[] naming the native keys that were written.

Questions about Ninja Forms

Can an editor account use the Ninja Forms tools?

Not unless it holds manage_options. Every call checks that capability and returns ninja_forms_forbidden otherwise.

Can I get back a Ninja Forms submission the agent deleted?

Yes, if it was deleted without force=true: it sits in the trash as an nf_sub post, and wppilot/rollback-change or the WordPress admin can restore it. A forced delete, or a deleted form, cannot be recovered.

Why does check-setup say storage is not ready?

Ninja's NF3 upgrader has not completed on this site. Opening the Ninja Forms admin page once lets it finish, after which the other calls work.

Ninja Forms reads

Ability	What it does
`wppilot/ninja-forms-check-setup`Check Ninja Forms Setup	Reports the Ninja Forms runtime state. Returns the plugin version, the minimum version GoBuildWP Pro accepts, whether the NF3 storage tables exist, the number of forms on this install, the number of field types the install can build, the capability flags for the current user, and site-global anti-spam integration flags (hCaptcha / reCAPTCHA / Turnstile). Call this FIRST before any other ninja-forms-* ability so the agent can fail fast when Ninja Forms is inactive, below the minimum version, or has not finished its NF3 upgrader. All Ninja Forms management (forms / fields / notifications / submissions) is driven through the GoBuildWP ninja-forms-* abilities - this integration does not require the native ninjaforms/* abilities.
`wppilot/ninja-forms-export-entries`Export Ninja Forms Submissions	Export one form's submissions as CSV or JSON with field labels as headers. Filters: status (active \| trashed \| any), date_from / date_to, search (any field value; the redacted email, phone, password, card, file and signature fields are searched only with include_sensitive=true and confirm=true). Ninja Forms has no starred / read flags. Up to 5000 rows per call (a ~200 KiB budget may stop sooner); pass next_cursor back as cursor until it is null. Email, phone, password, credit-card, file-upload and signature columns are [REDACTED] unless include_sensitive=true with confirm=true. The export has no IP column. Use ninja-forms-list-submissions to browse.
`wppilot/ninja-forms-get-field-type-schema`Get Ninja Forms Field Type Schema	Describe one Ninja Forms field type - its human label, its editor section, and the WHITELIST of setting keys add-field / edit-field accept under the field descriptor for that type (e.g. label, label_pos, required, default, placeholder, classes, key, …). Call wppilot/ninja-forms-get-field-types-schema first for the catalog of available type slugs, then this ability per chosen type before crafting an add-field payload. Returns ninja_forms_field_type_not_found when the slug is not registered on this install (the add-on that provides it is inactive).
`wppilot/ninja-forms-get-field-types-schema`List Ninja Forms Field Types	Return the catalog of every Ninja Forms field type this install can build via add-field / edit-field. Output is compact: per entry {type, label, category, pro_only}. Use this FIRST when constructing a form, then call wppilot/ninja-forms-get-field-type-schema for the per-type supported-settings whitelist. The catalog is read from the live Ninja Forms field registry (Ninja_Forms()->fields), so it already reflects whichever add-ons are installed - a type only appears when the install can actually render it, so `pro_only` is always false and `pro_active` is always true (Ninja Forms has no single Lite/Pro edition split; payment / extra types come from separate add-ons and simply are or are not in the registry). `category` is the Ninja editor section (common / userinfo / misc / layout / other). Mirrors the catalog-vs-detail pattern used by `gravityforms-get-field-types-schema`, `wpforms-get-field-types-schema`, `fluentforms-get-field-types-schema`, `formidable-get-field-types-schema`.
`wppilot/ninja-forms-get-form`Get a Ninja Forms Form	Fetch one Ninja Forms form by id. Always returns the compact attributes {id, title, key, created_at, updated_at, fields_count, actions_count, submissions_count}. The heavy blocks are OPT-IN via the `include` array - progressive disclosure keeps the default payload small. Valid include values: "fields" (each field as {id, type, key, label, required, order, settings} where settings is the full per-field settings map, including list-field options), "actions" (each action as {id, type, label, active, settings}), "settings" (the full form-level settings object). Returns ninja_forms_form_not_found (404) when the id is absent.
`wppilot/ninja-forms-get-form-canonical`Get Ninja Forms Form (Canonical)	Reads a single Ninja 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. Reads the form through the GoBuildWP-native Ninja Forms model layer (the same source as ninja-forms-get-form), then folds the Ninja field shape onto the 17 canonical types: composites (`firstname` + `lastname` flat, `address` + `address2` + `city` + `zip` flat) emit `warnings[]` because Ninja does not nest them; native list types (`listcheckbox`, `listradio`, `listselect`, `listmultiselect`, `listcountry`, `liststate`, `listimage`, `listmodifier`) map to canonical `select` / `radio` / `checkbox` with cardinality; Ninja-specific UI types without a canonical equivalent (`starrating`, `signature`, `quantity`, `product`, `shipping`, `total`, `creditcard`) emit `warnings[]` with severity `structural`; anti-spam types (`hcaptcha`, `recaptcha`, `recaptchav3`, `turnstile`, `spam`, `timedsubmit`) emit `warnings[]` with severity `informational`. Output keys: `fields[]` with canonical types, `mail_config{}` from the first email-action (the first `actions[]` entry with `type: "email"`), `notifications[]` from the remaining email-actions, `messages{}` from the form-level success / error / spam strings, `meta{}` (source plugin + version + edition + non-email actions echo for round-trip), plus `warnings[]` for everything that does not fit the canonical shape (composite collapse, Pro / spam fields, redirect actions, save-action, multi-action forms). Honours the `max_field_bytes` truncation contract (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 `ninjaforms_form_not_found` when the id does not exist. Use this ability inside the form-model-migration workflow (Phase 2 - read source schema); for ad-hoc inspection of the Ninja-native shape, use ninja-forms-get-form (include=["fields","actions","settings"]).
`wppilot/ninja-forms-get-notification`Get a Ninja Forms Notification	Fetch one email notification by id with its FULL settings (recipient, subject, message body, from/reply-to, cc/bcc, format). Required: form_id, notification_id. Secret-looking setting values are redacted and `has_secrets` flags whether any were; large string values (the message body) are byte-capped at `max_field_bytes` (default 8192, 0 disables). Returns ninja_forms_notification_not_found (404) when the id is not an email action on this form. Returns {form_id, notification: {id, type, label, active, settings, has_secrets}}.
`wppilot/ninja-forms-get-submission`Get a Ninja Forms Submission	Fetch one Ninja Forms submission by id with its decoded field answers. Required: form_id, submission_id (the submission MUST belong to form_id, else ninja_forms_submission_not_found). Optional: fields (a whitelist of field keys - only those answers are returned); max_field_bytes (per-answer byte cap, default 8192, 0 disables - large textarea / file values are truncated with a marker and a `full_size`). No-value display fields (submit / html / hr / note) are omitted. Returns {form_id, submission_id, seq_num, status, date, answers: [{field_id, field_key, label, value, truncated, full_size}]}.
`wppilot/ninja-forms-list-forms`List Ninja Forms	List the Ninja Forms on this site, paginated, as compact rows: {id, title, key, fields_count, actions_count, submissions_count, created_at, updated_at}. The field / action / submission counts are accurate live counts (not the cached nf3_forms.subs column). Does NOT return field or action definitions - call ninja-forms-get-form (with include) for one form's full shape. Optional `search` filters by title substring. Pagination: `page` (default 1), `per_page` (default 25, max 200). Returns {forms: [...], pagination: {page, per_page, total, total_pages}}.
`wppilot/ninja-forms-list-notifications`List Ninja Forms Notifications	List every email notification on a Ninja Forms form. A notification is a Ninja "email" action; the other action types (redirect / success message / save / webhook) are NOT returned here - read them via ninja-forms-get-form (include=["actions"]). Required: form_id. Returns {form_id, notifications: [{id, label, active, to, subject, form_id}]} - compact rows (no message body / headers); call ninja-forms-get-notification for the full settings. Includes both active and inactive notifications (branch on `active`).
`wppilot/ninja-forms-list-submissions`List Ninja Forms Submissions	List the submissions of a Ninja Forms form, newest first. Submissions are `nf_sub` posts. Required: form_id. Optional: status ("active" = live submissions [default], "trashed", or "any"); per_page (default 25, max 100); page (1-based). Returns COMPACT rows {id, seq_num, status, date, form_id} with NO field values - call ninja-forms-get-submission for the decoded answers of one. Includes a pagination block {page, per_page, total, total_pages}.

Ninja Forms writes

Ability	What it does
`wppilot/ninja-forms-add-field`Add a Ninja Forms Field	Add one field to an existing Ninja Forms form. Required: form_id, type (a slug from ninja-forms-get-field-types-schema - an unknown type fails with ninja_forms_invalid_input). Optional: label, key (auto-derived from the label when omitted, made unique per form - read the returned key back, do not guess), required (bool), order (1-based position; omit to append at the end), settings (object of extra per-type setting keys, e.g. placeholder / default / options for list fields; see ninja-forms-get-field-type-schema for the whitelist). Returns the new field as a compact row {id, type, key, label, required, order, form_id} plus warnings[] (e.g. a key that was uniquified). Does NOT auto-add a submit button - that is a create-form concern. Use ninja-forms-get-form (include=["fields"]) for the full per-field settings afterwards.
`wppilot/ninja-forms-create-form`Create a Ninja Forms Form	Create a new Ninja Forms form. Required: title (non-empty string). Optional: fields[] - each {type (required, must be a slug from ninja-forms-get-field-types-schema), label?, key? (auto-derived from label when omitted, made unique per form), required? (bool), settings? (object of extra per-type settings)}; actions[] - each {type (e.g. "email", "successmessage", "redirect"), label?, active? (bool, default true), settings? (object)}. A submit button is appended automatically when fields are supplied and none is of type "submit" (a Ninja form is unusable without one). Field types are validated up front - an unknown type fails the whole call with ninja_forms_invalid_input. Returns the new form as a compact row {id, title, key, fields_count, actions_count, submissions_count, created_at, updated_at} plus warnings[] (auto-added submit, derived/uniquified keys).
`wppilot/ninja-forms-create-notification`Create a Ninja Forms Notification	Add an email notification to a form. Required: form_id, to (recipient - an email address or a Ninja merge tag like {field:email}). Optional: subject, message (the body), label (admin name), active (bool, default true), and `settings` (an object of extra native email-action keys, e.g. from_name, from_address, reply_to, cc, bcc, email_format - see ninja-forms-get-notification on an existing one for the shape). The friendly `subject`/`message` map to the native email_subject/email_message keys. Returns the new notification as a compact row {id, label, active, to, subject, form_id}.
`wppilot/ninja-forms-duplicate-form`Duplicate a Ninja Forms Form	Duplicate an existing Ninja Forms form - copies the form settings, every field, and every action into a brand-new form (submissions are NOT copied). Uses Ninja Forms' own synchronous duplication, so the copy is complete and immediately readable. By default the new title is "<original> - copy"; pass `new_title` to set it explicitly. Returns the new form as a compact row. Returns ninja_forms_form_not_found (404) when the source id is absent.
`wppilot/ninja-forms-edit-field`Edit a Ninja Forms Field	Partial-merge edit of one field on a form. Identify the field by `field_id` (numeric) OR `field_key` (slug from get-form) - field_id wins when both are given; the field MUST belong to `form_id` (a stray id/key returns ninja_forms_field_not_found). Mutable: label, key (renamed key is uniquified per form), required (bool), order, and `settings` (an object merged onto the field's current settings - only the keys you pass are touched). The `type` is NOT mutable (Ninja re-renders unpredictably on a type swap) - delete the field and add-field a new one instead; a `type` key inside `settings` is ignored. Returns the updated compact field + the list of changed setting keys (idempotent: a no-op re-run returns an empty changed[]).
`wppilot/ninja-forms-edit-form`Edit a Ninja Forms Form	Edit the FORM-LEVEL settings of an existing Ninja Forms form - a shallow merge: only the keys you pass are touched, the rest are preserved. Pass `title` to rename, and/or `settings` (an object of form-level setting keys, e.g. {default_label_pos, show_title, clear_complete, success message keys}). This ability does NOT touch fields or actions - use ninja-forms-add-field / edit-field / delete-field for fields and ninja-forms-create-notification / edit-notification for notifications; passing a `fields` or `actions` key here is rejected with ninja_forms_invalid_input. Returns the updated compact form + the list of changed setting keys. Returns ninja_forms_form_not_found (404) when the id is absent.
`wppilot/ninja-forms-edit-notification`Edit a Ninja Forms Notification	Partial-merge edit of one email notification. Required: form_id, notification_id. Optional (only the keys you pass are touched): to, subject, message, label, active, and `settings` (merged onto the action's current settings). The friendly subject/message map to email_subject/email_message. The action `type` stays "email" (not mutable). Returns ninja_forms_notification_not_found (404) when the id is not an email action on the form. Returns {notification, changed} (idempotent: a no-op re-run returns an empty changed[]).

Destructive Ninja Forms calls

Ability	What it does
`wppilot/ninja-forms-delete-field`Delete a Ninja Forms Field	Permanently delete one field from a form. Identify it by `field_id` (numeric) OR `field_key` (slug from get-form); the field MUST belong to `form_id`. Idempotent: deleting an already-missing field is a no-op that returns deleted=false (re-running is safe, not a 404). The field row and its `nf3_field_meta` rows are removed by the model layer; there is no soft-delete / trash for fields. Note a Ninja form needs a submit field to be usable - do not delete the only submit unless you are replacing it.
`wppilot/ninja-forms-delete-form`Delete a Ninja Forms Form	Permanently delete a Ninja Forms form by id. This CASCADES: the form, all its fields, all its actions, AND all its submissions are removed (Ninja Forms has no per-form trash - deletion is immediate and irreversible). Idempotent: deleting a form that does not exist returns {deleted: false} rather than an error, so a retry is safe. Returns {deleted: bool, form_id}.
`wppilot/ninja-forms-delete-notification`Delete a Ninja Forms Notification	Permanently delete one email notification from a form. Required: form_id, notification_id. Idempotent: deleting an already-missing notification (or an id that is not an email action) is a no-op that returns deleted=false. To temporarily silence a notification without losing it, use ninja-forms-edit-notification with active=false instead. Returns {form_id, notification_id, deleted}.
`wppilot/ninja-forms-delete-submission`Delete a Ninja Forms Submission	Delete one submission of a form. Required: form_id, submission_id (must belong to form_id). By default the submission is TRASHED (reversible - restore it from the WordPress admin or via wppilot/execute-php wp_untrash_post). Pass force=true to PERMANENTLY delete it (the `nf_sub` post + all its `_field_*` postmeta, no undo). Idempotent: deleting an already-missing submission, or re-trashing an already-trashed one, is a no-op that returns deleted=false. Returns {form_id, submission_id, deleted, permanent}.

For the task-level view of Ninja Forms, with worked requests and what to check afterwards, see Ninja Forms integration page.