bookmark_borderAPI Functions

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.

In addition to the documentation on this page, you may also view the inline code documentation for the GFAPI Class.

Forms

get_form

Returns the form object for a given Form ID.

public static function get_form( $form_id ) {}

Parameters

  • $form_id integer

    The ID of the form to be returned.

Returns

Usage Example

$form = GFAPI::get_form( $form_id );

get_forms

Returns an array of form objects.

public static function get_forms( $active, $trash ) {}

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.

Returns

Usage Example

$forms = GFAPI::get_forms();

delete_forms

Deletes the forms with the given Form IDs.

public 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

$result = GFAPI::delete_forms( $form_ids );

delete_form

Deletes the form with the given Form ID.

public static function delete_form( $form_id ) {}

Parameters

  • $form_id integer

    The ID of the Form to be deleted.

Returns

Usage Example

$result = GFAPI::delete_form( $form_id );

update_forms

Updates the forms with an array of form objects.

public static function update_forms( $forms ) {}

Parameters

Returns

Usage Example

$result = GFAPI::update_forms( $forms );

update_form

Updates the form with a given form object.

public 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

Usage Example

$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

public 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

Usage Example

$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

public 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

Usage Example

$result = GFAPI::update_form_property( $form_id, $property_key, $value );

add_forms

Adds multiple form objects.

public static function add_forms( $forms ) {}

Parameters

Returns

  • $result mixed

    Either an array of new form IDs or a WP_Error instance.

Usage Example

$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.

public static function add_form( $form ) {}

Parameters

Returns

  • $result mixed

    Either the new Form ID or a WP_Error instance.

Usage Example

$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 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.

public 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:

    'is_valid' => boolean true
    'page_number' => int 0
    'source_page_number' => int 1
    'confirmation_message' => string 'confirmation message [snip]'
    

    Example output for failed validation:

    '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:

    '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

$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.

public 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

    $search_criteria['status'] = 'active';

    Filter by any column in the main table

    $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

    $search_criteria['start_date'] = $start_date;
    $search_criteria['end_date'] = $end_date;
    

    Filter by Field Values

    $search_criteria['field_filters'][] = array( 'key' => '1', 'value' => 'gquiz159982170' );
    

    Filter Operators

    // 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)

    $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)

    $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

    $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)

    $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

    $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:

    // 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.

    // 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

Example 1: simple

$entries = GFAPI::get_entries( $form_id );

Example 2: two field filters

$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

$search_criteria = array();
$sorting         = array( 'key' => '5', 'direction' => 'ASC' );
$entries         = GFAPI::get_entries( $form_id, $search_criteria, $sorting );

Example 4: paging

$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

$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

$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.

public 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

Usage Example

$result = GFAPI::count_entries( $form_ids, $search_criteria );

get_entry

Returns the entry object for a given entry ID.

public static function get_entry( $entry_id ) {}

Parameters

  • $entry_id integer

    The ID of the Entry.

Returns

Usage Example

$entry = GFAPI::get_entry( $entry_id );

add_entries

Adds multiple Entry objects.

public 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

Usage Example

$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).

public 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

$entry_id = GFAPI::add_entry( $entry );

update_entry_property

Updates a single property of an entry.

public 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

$result = GFAPI::update_entry_property( $entry_id, $property, $value );

update_entry_field

Updates a single field of an entry.

public 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

$result = GFAPI::update_entry_field( $entry_id, $input_id, $value );

update_entry

Updates a single Entry object.

public 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

Usage Example

$result = GFAPI::update_entry( $entry );

update_entries

Updates multiple Entry objects.

public static function update_entries( $entries ) {}

Parameters

Returns

Usage Example

$result = GFAPI::update_entries( $entries );

delete_entry

Deletes a single Entry.

public static function delete_entry( $delete_entry ) {}

Parameters

  • $entry_id integer

    The ID of the Entry to be deleted.

Returns

Usage Example

$result = GFAPI::delete_entry( $delete_entry );

Feeds

get_feeds

Returns all the feeds for the given criteria.t.

public static function get_feeds( $feed_ids = null, $form_id = null, $addon_slug = null, $is_active = true ) {}

Parameters

  • $feed_ids mixed

    Optional. The ID of the Feed or an array of Feed IDs.

  • $form_id string

    Optional. The ID of the Form to which the Feeds belong.

  • $addon_slug string

    Optional. The slug of the add-on to which the Feeds belong.

  • $is_active boolean

    Optional. Default true. Only return active feeds.

Returns

Usage Example

$result = GFAPI::get_feeds();

delete_feed

Deletes a single Feed.

public static function delete_feed( $feed_id ) {}

Parameters

Returns

Usage Example

$result = GFAPI::delete_feed( $feed_id );

update_feed

Updates a single Feed.

public static function update_feed( $feed_id, $feed_meta, $form_id = null ) {}

Parameters

Returns

Usage Example

$result = GFAPI::update_feed( $feed_id, $feed_meta, $form_id );

add_feed

Adds a feed with the given Feed object.

public static function add_feed( $form_id, $feed_meta, $addon_slug ) {}

Parameters

  • $form_id integer

    The ID of the form to which the feed belongs.

  • $feed_meta array

    The feed properties, see the meta property of the Feed Object.

  • $addon_slug string

    The slug of the add-on to which the Feed belongs.

Returns

  • $result mixed

    The ID of the newly created Feed or a WP_Error instance.

Usage Example

$result = GFAPI::add_feed( $form_id, $feed_meta, $addon_slug );

Notifications

send_notifications

Sends all active notifications for a form given an entry object and an event.

public 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

GFAPI::send_notifications( $form, $entry, 'user_registered' );

Fields

get_fields_by_type

Returns an array containing the form fields of the specified type or types.

public 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

$fields = GFAPI::get_fields_by_type( $form, array( 'checkbox' ), true );

Inline Code Documentation

http://inlinedocs.gravityhelp.com/class-GFAPI.html