IntroductionFormsget_formget_formsdelete_formsdelete_formupdate_formsupdate_formupdate_forms_propertyupdate_form_propertyadd_formsadd_formsubmit_formEntriesget_entriescount_entriesentry_existsget_entryadd_entriesadd_entryupdate_entry_propertyupdate_entry_fieldupdate_entryupdate_entriesdelete_entryFeedsNotificationssend_notificationsFieldsget_fields_by_typeget_fieldNotes
Introduction
The Gravity Forms API Functions provides developers with a future-proof way to access some of the common core functionality in Gravity Forms.
The API Functions are automatically included when Gravity Forms loads and they will be available by the time add-ons load. The API class is called GFAPI and it can be found in /plugins/gravityforms/includes/api.php.
Forms
get_form
Returns the form object for a given Form ID.
1public static function get_form( $form_id ) {}
Parameters
$form_id integer
The ID of the form to be returned.
Returns
$form mixed
The Form Object array or false.
Usage Example
1$form = GFAPI::get_form( $form_id );
get_forms
Returns an array of form objects.
1public static function get_forms( $active = true, $trash = false, $sort_column = 'id', $sort_dir = 'ASC' ) {}
Parameters
$active boolean
Optional. Default is true. Determines if inactive forms should also be returned.
$trash boolean
Optional. Default is false. Determines if trashed forms should also be returned.
$sort_column string
Since version 2.5. Optional. Default is id. The column to sort the forms by. Accepted values: id, title, date_created, is_active, and is_trash.
$sort_dir string
Since version 2.5. Optional. Default is ASC. The direction to use when sorting. Accepted values: ASC or DESC.
Returns
$forms mixed
An array of Form Objects.
Usage Example
1$forms = GFAPI::get_forms();
delete_forms
Deletes the forms with the given Form IDs.
1public static function delete_forms( $form_ids ) {}
Parameters
$form_ids array
An array of form IDs to delete.
Returns
This function does not return anything.
Usage Example
1$result = GFAPI::delete_forms( $form_ids );
delete_form
Deletes the form with the given Form ID.
1public static function delete_form( $form_id ) {}
Parameters
$form_id integer
The ID of the Form to be deleted.
Returns
$result mixed
True for success or a WP_Error instance.
Usage Example
1$result = GFAPI::delete_form( $form_id );
update_forms
Updates the forms with an array of form objects.
1public static function update_forms( $forms ) {}
Parameters
$forms array
An array of Form Objects to be updated.
Returns
$result mixed
True for success or a WP_Error instance.
Usage Example
1$result = GFAPI::update_forms( $forms );
update_form
Updates the form with a given form object.
1public static function update_form( $form, $form_id = null ) {}
Parameters
$form Form Object
The modified form to be updated.
$form_id integer
Optional. If specified, then the ID in the Form object will be ignored.
Returns
$result mixed
True for success or a WP_Error instance.
Usage Example
1$result = GFAPI::update_form( $form );
update_forms_property
Updates a form property – a column in the main forms table. e.g. is_trash, is_active, title
1public static function update_forms_property( $form_ids, $property_key, $value ) {}
Parameters
$form_ids array
The IDs of the forms to update.
$property_key array
The names of the column in the database e.g. is_trash, is_active, title.
$value array
The new values.
Returns
$result mixed
The result of the query or a WP_Error instance.
Usage Example
1$result = GFAPI::update_forms_property( $form_ids, $property_key, $value );
update_form_property
Updates the property of one form – columns in the main forms table. e.g. is_trash, is_active, title
1public static function update_form_property( $form_id, $property_key, $value ) {}
Parameters
$form_ids integer
The ID of the form to update.
$property_key string
The name of the column in the database e.g. is_trash, is_active, title.
$value string
The new value.
Returns
$result mixed
The result of the query or a WP_Error instance.
Usage Example
1$result = GFAPI::update_form_property( $form_id, $property_key, $value );
add_forms
Adds multiple form objects.
1public static function add_forms( $forms ) {}
Parameters
$forms array
An array of Form Objects.
Returns
$result mixed
Either an array of new form IDs or a WP_Error instance.
Usage Example
1$result = GFAPI::add_forms( $forms );
add_form
Adds a new form using the given Form object. Warning, little checking is done to make sure it』s a valid Form object.
1public static function add_form( $form ) {}
Parameters
$form Form Object
The Form object.
Returns
$result Mixed
Either the new Form ID or a WP_Error instance.
Usage Example
1$result = GFAPI::add_form( $form );
submit_form
Submits a form. Use this function to send input values through the complete form submission process.
Supports field validation, notifications, confirmations, multiple-pages, save & continue and all the filters and actions that fire throughout the submission process. This includes the processing of any feeds configured for the form.
This is exactly equivalent to submitting a form rendered by a Gravity Forms shortcode. 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.
1public static function submit_form( $form_id, $input_values, $field_values, $target_page, $source_page ) {}
Parameters
$form_id integer
The ID of the form this submission belongs to.
$input_values array
An associative array containing the values to be saved.
$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
$result array
An array containing the result of the submission.
Example output for a successful submission:
1234'is_valid' => boolean true'page_number' => int 0'source_page_number' => int 1'confirmation_message' => string 'confirmation message [snip]'
Example output for failed validation:
123456'is_valid' => boolean false'validation_messages' => array 2 => string 'This field is required. Please enter the first and last name.''page_number' =>; int 1'source_page_number' => int 1'confirmation_message' => string ''
Example output for save and continue:
12345'is_valid' => boolean true'page_number' => int 1'source_page_number' => int 1'confirmation_message' => string 'Please use the following link to return to your form from any computer. [snip]''resume_token' => string '045f941cc4c04d479556bab1db6d3495'
Usage Example
1234567$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; // support for save and continue $result = GFAPI::submit_form( 52, $input_values );
Entries
get_entries
Returns an array of Entry objects for the given search criteria.
1public static function get_entries( $form_ids, $search_criteria = array(), $sorting = null, $paging = null, $total_count = null ) {}
Parameters
$form_ids integer|array
The ID of the form or an array IDs of the Forms. Zero for all forms.
$search_criteria array
Optional. An array containing the search criteria. The search criteria array is constructed as follows:
Filter by status
1$search_criteria['status'] = 'active';
Filter by any column in the main table
123$search_criteria['field_filters'][] = array( 'key' => 'currency', 'value' => 'USD' );$search_criteria['field_filters'][] = array( 'key' => 'is_read', 'value' => true );$search_criteria['field_filters'][] = array( 'key' => 'created_by', 'value' => $current_user->ID );
Filter by date range
12$search_criteria['start_date'] = $start_date;$search_criteria['end_date'] = $end_date;
Filter by Field Values
1$search_criteria['field_filters'][] = array( 'key' => '1', 'value' => 'gquiz159982170' );
Filter Operators
1234// Supported operators for scalar values: is/=, isnot, contains$search_criteria['field_filters'][] = array( 'key' => '1', 'operator' => 'contains', 'value' => 'Steve' );// Supported operators for array values: in/=, not in/!=$search_criteria['field_filters'][] = array( 'key' => '1', 'operator' => 'not in', 'value' => array( 'Alex', 'David', 'Dana' ) );
Filter by a checkbox value (not recommended)
1$search_criteria['field_filters'][] = array( 'key' => '2.2', 'value' => 'gquiz246fec995' );
Notes:
Using input IDs as search keys will work for checkboxes but it won』t work if the checkboxes have been re-ordered since the first submission.
the 『not in』 operator is not currently supported for checkbox values.
Filter by a checkbox value (recommended)
12$search_criteria['field_filters'][] = array( 'key' => '2', 'value' => 'gquiz246fec995' );$search_criteria['field_filters'][] = array( 'key' => '2', 'operator' => 'in', 'value' => array( 'First Choice', 'Third Choice' ) );
NOTE: Neither 『not in』 nor 」 operators are not currently supported for checkboxes using field IDs as search keys.
Filter by a global/free-form search of values of any form field
123$search_criteria['field_filters'][] = array( 'value' => $search_value );// OR$search_criteria['field_filters'][] = array( 'key' => 0, 'value' => $search_value );
Filter entries by Entry meta (added using the gform_entry_meta hook)
12$search_criteria['field_filters'][] = array( 'key' => 'gquiz_score', 'value' => '1' );$search_criteria['field_filters'][] = array( 'key' => 'gquiz_is_pass', 'value' => '1' );
Filter by ALL / ANY of the field filters
12$search_criteria['field_filters']['mode'] = 'all'; // default$search_criteria['field_filters']['mode'] = 'any';
$sorting array
Optional. An array containing the sorting criteria. Sorting: column, field or entry meta:
12// default$sorting = array( 'key' => $sort_field, 'direction' => 'ASC', 'is_numeric' => true );
$paging array
Optional. An array containing the paging criteria. Default is a page size of twenty.
IMPORTANT TIP: use paging to limit the number of entries otherwise you may find the database times out. On most servers we』ve found the optimum page size to be 200.
12// default$paging = array( 'offset' => 0, 'page_size' => 30 );
$total_count integer
Optional. An output parameter containing the total number of entries. Pass a non-null value to get the total count.
Returns
$result mixed
An array of Entry Objects or a WP_Error instance.
Example 1: simple
1$entries = GFAPI::get_entries( $form_id );
Example 2: two field filters
123456789101112131415$search_criteria = array( 'status' => 'active', 'field_filters' => array( 'mode' => 'any', array( 'key' => '1', 'value' => 'Second Choice' ), array( 'key' => '5', 'value' => 'My text' ) ));$entries = GFAPI::get_entries( $form_id, $search_criteria );
Example 3: sorting
123$search_criteria = array();$sorting = array( 'key' => '5', 'direction' => 'ASC' );$entries = GFAPI::get_entries( $form_id, $search_criteria, $sorting );
Example 4: paging
1234$search_criteria = array();$sorting = array();$paging = array( 'offset' => 0, 'page_size' => 25 );$entries = GFAPI::get_entries( $form_id, $search_criteria, $sorting, $paging );
Example 5: paging with total count
123456$search_criteria = array();$sorting = array();$paging = array( 'offset' => 0, 'page_size' => 25 );$total_count = 0;$entries = GFAPI::get_entries( $form_id, $search_criteria, $sorting, $paging, $total_count );// $total_count now contains the total number of entries matching the search criteria. This is useful for displaying pagination controls.
Example 6: entries in the last 30 days
12345678$search_criteria = array();$form_id = 4;$start_date = date( 'Y-m-d', strtotime('-30 days') );$end_date = date( 'Y-m-d', time() );$search_criteria['start_date'] = $start_date;$search_criteria['end_date'] = $end_date; GFAPI::get_entries($form_id, $search_criteria);
count_entries
Returns the total number of entries for the given search criteria.
1public static function count_entries( $form_ids, $search_criteria = array() ) {}
Parameters
$form_ids integer|array
The ID of the form or an array IDs of the Forms. Zero for all forms.
$search_criteria array
Optional. An array containing the search criteria. See get_entries() for examples of the search criteria.
Returns
$result integer
The total count.
Usage Example
1$result = GFAPI::count_entries( $form_ids, $search_criteria );
entry_exists
Checks if an entry exists for the supplied ID.
1public static function entry_exists( $entry_id ) {}
Parameters
$entry_id integer
The ID to be checked.
Returns
$result boolean
Whether or not an entry exists for the supplied ID.
Usage Example
1$result = GFAPI::entry_exists( 1 );
get_entry
Returns the entry object for a given entry ID.
1public static function get_entry( $entry_id ) {}
Parameters
$entry_id integer
The ID of the Entry.
Returns
$result mixed
The Entry Object or a WP_Error instance.
Usage Example
1$entry = GFAPI::get_entry( $entry_id );
add_entries
Adds multiple Entry objects.
1public static function add_entries( $entries, $form_id = null ) {}
Parameters
$entries array
An array of Entry Objects.
$form_id integer
Optional. If specified, the form_id in the Entry objects will be ignored.
Returns
$result mixed
An array of entry IDs or a WP_Error instance.
Usage Example
1$entry_ids = GFAPI::add_entries( $entries, $form_id );
add_entry
Adds a single Entry object. The usual hooks that are triggered while saving entries are not fired here.
Checks that the form id, field ids and entry meta exist and ignores legacy values (i.e. values for fields that no longer exist).
1public static function add_entry( $entry ) {}
Parameters
$entry Entry Object
An array containing the entry to be added.
Returns
$result mixed
The ID of the created entry or a WP_Error instance.
Usage Example
1$entry_id = GFAPI::add_entry( $entry );
update_entry_property
Updates a single property of an entry.
1public static function update_entry_property( $entry_id, $property, $value ) {}
Parameters
$entry_id integer
The ID of the Entry Object.
$property string
The property of the Entry object to be updated.
$value mixed
The value to which the property should be set.
Returns
$result boolean
Whether the entry property was updated successfully.
Usage Example
1$result = GFAPI::update_entry_property( $entry_id, $property, $value );
update_entry_field
Updates a single field of an entry.
1public static function update_entry_field( $entry_id, $input_id, $value ) {}
Parameters
$entry_id integer
The ID of the Entry Object.
$input_id string
The id of the input to be updated. For single input fields such as text, paragraph, website, drop down etc… this will be the same as the field ID.
For multi input fields such as name, address, checkboxes, etc… the input id will be in the format {FIELD_ID}.{INPUT NUMBER}. ( i.e. 『1.3』 ).
The $input_id can be obtained by inspecting the key for the specified field in the $entry object.
$value mixed
The value to which the field should be set.
Returns
$result boolean
Either True or false. Whether the entry field was updated successfully.
Usage Example
1$result = GFAPI::update_entry_field( $entry_id, $input_id, $value );
update_entry
Updates a single Entry object.
1public static function update_entry( $entry, $entry_id = null ) {}
Parameters
$entry Entry Object
An array containing the entry to be updated.
$entry_id integer
Optional. If specified, the ID in the Entry object will be ignored.
Returns
$result mixed
True for success or a WP_Error instance.
Usage Example
1$result = GFAPI::update_entry( $entry );
update_entries
Updates multiple Entry objects.
1public static function update_entries( $entries ) {}
Parameters
$entries array
An array of Entry Objects to be updated.
Returns
$result mixed
True for success or a WP_Error instance.
Usage Example
1$result = GFAPI::update_entries( $entries );
delete_entry
Deletes a single Entry.
1public static function delete_entry( $delete_entry ) {}
Parameters
$entry_id integer
The ID of the Entry to be deleted.
Returns
$result mixed
True for success or a WP_Error instance.
Usage Example
1$result = GFAPI::delete_entry( $delete_entry );
Feeds
See Managing Add-On Feeds With The GFAPI.
Notifications
send_notifications
Sends all active notifications for a form given an entry object and an event.
1public static function send_notifications( $form, $entry, $event = 'form_submission' ) {}
Parameters
$form Form Object
An array containing all the current form』s properties.
$entry Entry Object
An array containing the entry currently being processed.
$event string
Optional. Default is form_submission. The event for which notifications should be sent. Custom events can be listed in the event drop down on the edit notification page by using the gform_notification_events filter.
Returns
This function does not return anything.
Usage Example
1GFAPI::send_notifications( $form, $entry, 'user_registered' );
Fields
get_fields_by_type
Returns an array containing the form fields of the specified type or types.
1public static function get_fields_by_type( $form, $types, $use_input_type = false ) {}
Parameters
$form Form Object
An array containing all the current form』s properties.
$types string|array
Indicates the type or types of fields to be returned.
$use_input_type boolean
Optional. Default is false. If available should the fields inputType property be used instead of the type property.
Returns
$fields array
An array containing the Field Objects of the specified type or types. An empty array will be returned if no matching fields found.
Usage Example
1$fields = GFAPI::get_fields_by_type( $form, array( 'checkbox' ), true );
get_field
Returns the field object for the requested field or input ID from the supplied form or form ID.
1public static function get_field( $form_or_id, $field_id ) {}
Since
GFAPI::get_field() was added in Gravity Forms 2.3.
Parameters
$form_or_id Form Object|int
The Form Object or ID.
$field_id string|int
The field or input ID.
Returns
$field Field Object|boolean
The field object or false if the form or field are not found.
Usage Examples
12345678// Passing the form object with the field id.$field_one = GFAPI::get_field( $form, 1 ); // Passing the form id with the field id.$field_one = GFAPI::get_field( 2, 1 ); // Passing the form id with the input id.$field_one = GFAPI::get_field( 2, '1.3' );
Notes
See Managing Notes With The GFAPI.