Developer hooks and WP-CLI for Gravity Forms

Formsieve for Gravity Forms prefixes every hook with fsv_gf_, bundles its own copy of the Formsieve core under the namespace Formsieve\GF\Core\… and adds the WP-CLI command wp formsieve-gf. The examples below are ready to paste into a small plugin or a must-use plugin (wp-content/mu-plugins/). Filters that run when a form is submitted also work from a theme's functions.php, but fsv_gf_booted fires on plugins_loaded, before any theme is loaded, so a listener for it must live in a plugin or mu-plugin.

Filters

Actions

Context (Formsieve\GF\Core\Pipeline\Context) gives you the submission as the integration built it: form_id(), fields(), email_domain(), message(), text(), settings(), setting( $key ), site() and more. It contains visitor data: never log or send it as a whole. Verdict (Formsieve\GF\Core\Classifier\Verdict) offers verdict(), is_allow(), is_review(), is_block(), p(), spam_percent(), category(), reason(), reason_code(), stage(), model(), model_status(), provider(), request_id(), latency_ms(), input_tokens(), cost_micro_usd(), is_checked(), is_demo(), log_id() and with( array $changes ).

Examples

Skip one form entirely:

add_filter( 'fsv_gf_should_check', function ( $check, $ctx ) {
	return 12 === $ctx->form_id() ? false : $check;
}, 10, 2 );

Stricter blocking on one form:

add_filter( 'fsv_gf_thresholds', function ( $thresholds, $ctx ) {
	if ( 5 === $ctx->form_id() ) {
		$thresholds['block'] = 0.95;
	}
	return $thresholds;
}, 10, 2 );

Never block on one form; send its would-be blocks to review:

add_filter( 'fsv_gf_verdict', function ( $verdict, $ctx ) {
	if ( 3 === $ctx->form_id() && $verdict->is_block() ) {
		return $verdict->with( array( 'verdict' => 'review' ) );
	}
	return $verdict;
}, 10, 2 );

Tell the model more about your site (keep visitor text out of everything except state.submission):

add_filter( 'fsv_gf_payload', function ( $payload, $ctx ) {
	$payload['state']['site']['description'] .= ' We never buy SEO, marketing or web design services.';
	return $payload;
}, 10, 2 );

Changing the questions changes what the thresholds mean; see Calibration.

Log blocked submissions somewhere else:

add_action( 'fsv_gf_decided', function ( $verdict, $ctx ) {
	if ( $verdict->is_block() && 'model' === $verdict->stage() ) {
		error_log( sprintf( 'Formsieve blocked form %d at %d%% (request %s)', $ctx->form_id(), $verdict->spam_percent(), $verdict->request_id() ) );
	}
}, 10, 2 );

Read the key from the environment:

add_filter( 'fsv_gf_api_key', function ( $stored ) {
	$key = getenv( 'FORMSIEVE_KEY' );
	return $key ? $key : $stored;
} );

Word the validation message your way:

add_filter( 'fsv_gf_validation_message', function ( $message, $verdict, $ctx ) {
	return 'Sorry, this message could not be sent. Please call us instead.';
}, 10, 3 );

Never tag the notification that goes to your CRM mailbox:

add_filter( 'fsv_gf_tag_notification', function ( $tag, $notification, $form, $entry ) {
	return 'CRM import' === ( $notification['name'] ?? '' ) ? false : $tag;
}, 10, 4 );

Add your own pre-filter stage (it runs first here). The class is declared only when Formsieve for Gravity Forms is active, so the code cannot break the site when the plugin is deactivated:

add_action( 'plugins_loaded', function () {
	if ( ! interface_exists( 'Formsieve\GF\Core\Pipeline\Stage' ) ) {
		return;
	}

	final class My_Partner_Allowlist implements \Formsieve\GF\Core\Pipeline\Stage {
		public function id(): string {
			return 'partner_allowlist';
		}

		public function run( \Formsieve\GF\Core\Pipeline\Context $ctx, \Formsieve\GF\Core\Pipeline\Result $result ): void {
			if ( 'partner.example' === $ctx->email_domain() ) {
				$result->decided( 'allow', 'allowlist:partner' );
			}
		}
	}

	add_filter( 'fsv_gf_pipeline_stages', function ( $stages ) {
		array_unshift( $stages, new My_Partner_Allowlist() );
		return $stages;
	} );
}, 30 );

WP-CLI

wp formsieve-gf test [<form_id>] [--sample=spam|ham] [--yes] [--format=table|json]
wp formsieve-gf stats [--days=<n>] [--format=table|json]

• test without a form ID sends the canned Test connection sample with the saved route and key (about 500 tokens) and prints the result; nothing is logged. Like the button, it sends nothing until consent is given for the saved route. It exits with an error when the connection fails, so you can use it in monitoring.
• test <form_id> builds a synthetic spam (default) or ham (--sample=ham) submission for that form and classifies it exactly like a real one: pre-filters, one API call (or Test mode), decision and one log row, marked as a WP-CLI sample (source = cli). Its API call counts in the API calls, tokens and cost, but the sample is not counted as a submission. Outside Test mode it spends one API call, so it needs --yes. The category field of its output is the raw category ID.
• stats prints decision counts per band, API share, tokens, cost, latency and corrections for the last --days days (default 30), plus the month to date and the projection, with the same rules as the dashboard: the decision counts cover visitor submissions only, while API calls, tokens and cost include re-checks and WP-CLI samples. --format=json adds the daily breakdown, categories and breaker state.

Data for developers

• Decision log: table {$wpdb->prefix}fsv_gf_log. Numbers and identifiers only (times in UTC); read it, but do not write to it. The source column tells a visitor's submission (submission) from an administrator's Re-check (recheck) and a WP-CLI sample (cli); only submission rows count as submissions on the dashboard. category holds the raw ID (for example vendor_solicitation); \Formsieve\GF\Core\Admin\Format::category( $id ) returns the translated label the screens show.
• Options: fsv_gf_settings, fsv_gf_lists (the allow and block lists, not autoloaded), fsv_gf_route, fsv_gf_api_key (obfuscated, never read it directly) and more, all prefixed fsv_gf_.
• Gravity Forms entry meta: fsv_score, fsv_verdict, fsv_category, fsv_reason, fsv_model, fsv_model_status, fsv_provider, fsv_latency_ms, fsv_request_id, fsv_request_id_kind.
• REST (both require manage_options and the wp_rest nonce):
  • POST /wp-json/formsieve-gf/v1/test-connection backs the admin's Test connection button. It sends nothing until consent covers the tested route (error_code no_consent, sent: false), and it sends the saved key only to the saved route (no_key otherwise; type the key to test another route).
  • POST /wp-json/formsieve-gf/v1/log/<id>/label with label = spam or ham records an administrator's correction for one log row, as the Log tab does.