Submitting Forms with the GFAPI


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.


$form_idintegerThe ID of the form this submission belongs to.
$input_valuesarrayAn 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.
An array of dynamic population parameter keys with their corresponding values used to populate the fields.
Default is 0.
Useful for multi-page forms to indicate which page is to be loaded if the current page passes validation.
Default is 1.
Useful for multi-page forms to indicate which page of the form was just submitted.


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

is_validboolThe form validation result.
validation_messagesarrayOnly present when is_valid is false.
An array of validation messages for the fields that failed validation.
page_numberintegerFor multi-page forms.
The page that should be displayed.
source_page_numberintegerFor multi-page forms.
The page that was submitted.
confirmation_messagestringOnly present when is_valid is true.
The resume or confirmation message.
confirmation_typestringOnly present when is_valid is true.
The type of confirmation being used for the current submission.
message or redirect
confirmation_redirectstringOnly present when is_valid is true and the confirmation_type is redirect.
The URL the submission should redirect to.
entry_idintegerOnly present when is_valid is true.
The ID of the entry created by the submission.
resume_tokenstringOnly 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.

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.

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 ) ) {
} 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();
    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 );