Submitting Forms with the GFAPI

Introduction

The GFAPI::submit_form() method is used to create an entry by sending input values through the complete form submission process.

This includes the following features and processes:

Saving progress for the save and continue feature
Validation
Configured anti-spam checks e.g. honeypot, captcha^{(see note)}, Akismet etc.
Saving the entry to the database
Add-on feeds
Notifications
Confirmations
All the filters and action hooks triggered by a regular form submission

This is exactly equivalent to submitting a Gravity Forms form embeded in a post or page.

Source Code

public static function submit_form( $form_id, $input_values, $field_values = array(), $target_page = 0, $source_page = 1 ) {}

This method is located in /includes/api.php.

Parameters

Param	Type	Description
$form_id	integer	The ID of the form this submission belongs to.
$input_values	array	An associative array containing the values to be saved using the field input names as the keys. The input names expected by this function are identical to the input names found in the form markup so if you have any doubts about the name of an input, just check the form preview.
$field_values	array	Optional. An array of dynamic population parameter keys with their corresponding values used to populate the fields.
$target_page	integer	Optional. Default is `0`. Useful for multi-page forms to indicate which page is to be loaded if the current page passes validation.
$source_page	integer	Optional. Default is `1`. Useful for multi-page forms to indicate which page of the form was just submitted.

Returns

An associative array containing the result properties or a WP_Error instance if an unspecified error occurs.

Key	Type	Description
is_valid	bool	The form validation result.
validation_messages	array	Only present when `is_valid` is `false`. An array of validation messages for the fields that failed validation.
page_number	integer	For multi-page forms. The page that should be displayed.
source_page_number	integer	For multi-page forms. The page that was submitted.
confirmation_message	string	Only present when `is_valid` is `true`. The resume or confirmation message.
confirmation_type	string	Only present when `is_valid` is `true`. The type of confirmation being used for the current submission. `message` or `redirect`
confirmation_redirect	string	Only present when `is_valid` is `true` and the `confirmation_type` is `redirect`. The URL the submission should redirect to.
entry_id	integer	Only present when `is_valid` is `true`. The ID of the entry created by the submission.
resume_token	string	Only present if `$input_values['gform_save']` was `true`. The token that can be used to repopulate the form with the saved values.

Usage Examples

Save Progress

This example shows how you can submit values for some fields and get a resume token.

$form_id                    = 52;
$input_values               = array();
$input_values['input_1']    = 'Single line text';
$input_values['input_2_3']  = 'First name';
$input_values['input_2_6']  = 'Last name';
$input_values['input_5']    = 'A paragraph of text.';
$input_values['gform_save'] = true;

$result = GFAPI::submit_form( $form_id, $input_values );
if ( ! is_wp_error( $result ) ) {
	$resume_token   = rgar( $result, 'resume_token' );
	$resume_message = rgar( $result, 'confirmation_message' );
}

Form Submission

This example shows how you can submit values and handle the form submission result.

$form_id                    = 52;
$input_values               = array();
$input_values['input_1']    = 'Single line text';
$input_values['input_2_3']  = 'First name';
$input_values['input_2_6']  = 'Last name';
$input_values['input_5']    = 'A paragraph of text.';

$result = GFAPI::submit_form( $form_id, $input_values );
if ( is_wp_error( $result ) ) {
	$error_message = $result->get_error_message();
	GFCommon::log_debug( __METHOD__ . '(): GFAPI Error Message => ' . $error_message );
	// Do something with the error message.
	return;
}

if ( ! rgar( $result, 'is_valid' ) ) {
	$error_message = 'Submission is invalid.';
	$field_errors  = rgar( $result, 'validation_messages', array() );
	GFCommon::log_debug( __METHOD__ . '(): GFAPI Field Errors => ' . print_r( $field_errors ) );
	// Do something with the message and errors.
	return;
}

if ( rgar( $result, 'confirmation_type' ) === 'redirect' ) {
	$redirect_url = rgar( $result, 'confirmation_redirect' );
	GFCommon::log_debug( __METHOD__ . '(): GFAPI Redirect URL => ' . $redirect_url );
	if ( wp_redirect( $redirect_url ) ) {
		exit;
	}
} else {
	$confirmation_message = rgar( $result, 'confirmation_message' );
	GFCommon::log_debug( __METHOD__ . '(): GFAPI Confirmation Message => ' . $error_message );
	// Do something with the confirmation message.
}

Multiple submissions in one request

GFAPI::submit_form() isn’t designed to process multiple submissions during a single request, such as in for/foreach loops. It is possible but requires performing some cleanup after each call to ensure the next submission is processed correctly.

$form_id = 52;

foreach ( $submissions as $input_values ) {
    $result = GFAPI::submit_form( $form_id, $input_values );
    $_POST = array();
    GFFormsModel::flush_current_lead();
    GFFormDisplay::$submission = array();
}

Skip reCAPTCHA validation for REST API submissions

add_filter( 'gform_field_validation', function ( $result, $value, $form, $field ) {
	if ( $field->type === 'captcha' && defined( 'REST_REQUEST' ) && REST_REQUEST ) {
		$result['is_valid'] = true;
		$result['message']  = '';
	}

	return $result;
}, 10, 4 );