Gravity Forms REST API Feature Add-On

Introduction

This is the development version of the Gravity Forms Web API version 2. When it's ready it'll be integrated into the Gravity Forms core.

This is currently a beta version and should not be run on production sites without a full understanding of the possible risks that may be encountered when running beta software.

Authentication

Authentication can be performed using the same methods as the WordPress REST API. For further information on WordPress' authentication, the following resources are available:

• WordPress REST API authentication documentation
• WP REST API: Setting Up and Using Basic Authentication
• WP REST API: Setting Up and Using OAuth 1.0a Authentication

API Path

The API can be accessed as route from the WordPress REST API. This should look something like this:

https://localhost/wp-json/gf/v2/

For example, to obtain the Gravity Forms entry with ID 5, your request would be made to the following:

https://localhost/wp-json/gf/v2/entries/5

Sending Requests

PHP

// Define the URL that will be accessed.
$url = rest_url( 'gf/v2/entries' );

// Example using Basic Authentication
$args = array(
    'Authorization' => 'Basic ' . base64_encode( 'admin' . ':' . '12345' ),
    'headers'       => array( 'Content-type' => 'application/json' ),
);

// Make the request to the API.
$response = wp_remote_get( $url, $args );

// Check the response code.
if ( wp_remote_retrieve_response_code( $response ) != 200 || ( empty( wp_remote_retrieve_body( $response ) ) ) ){
    // If not a 200, HTTP request failed.
    die( 'There was an error attempting to access the API.' );
}

// Result is in the response body and is json encoded.
$body = json_decode( wp_remote_retrieve_body( $response ), true );

// Check the response body.
if( $body['status'] > 202 ){
    die( "Could not retrieve forms." );
}

// Entries retrieved successfully.
$entries = $body['response'];

In this example, the $entries variable contains the response from the API request.

Endpoints

GET /entries

Gets all entries.

Path

https://localhost/wp-json/gf/v2/entries

Response [json]

The response will contain a JSON object which contains the entry details. An example can be found below:

Example Response

{
  "id":           "71",
  "form_id":      "1",
  "date_created": "2016-11-28 18:12:17",
  "is_starred":   0,
  "is_read":      0,
  "ip":           "127.0.0.1",
  "source_url":   "http:\/\/localhost\/pagename",
  "post_id":      null,
  "created_by":   "2",
  "user_agent":   "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_2) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.87 Safari\/537.36",
  "status":       "active",
  "1":            "",
  "2":            "",
  "3":            "",
  "4":            "",
  "5":            "",
  "6.1":          "",
  "6.2":          "",
  "6.3":          ""
}

Optional Arguments

• form_id [int]

  Gets entries only from specific form IDs.

  • Usage

    • Passing a single form ID:

        https://localhost/wp-json/gf/v2/entries?form_id=1

    • Passing multiple form IDs (semicolon separated, URL encoded):

        https://localhost/wp-json/gf/v2/entries?form_id=1%3B2%3B3%3B4

• entry_id [int]

  Gets specific entries, based on the entry ID.

  • Usage

    • Passing a single entry ID:

        https://localhost/wp-json/gf/v2/entries?entry_id=1

    • Passing multiple form IDs (semicolon separated, URL encoded):

        https://localhost/wp-json/gf/v2/entries?form_id=1%3B2%3B3%3B4

• field_ids [int|string]

  Gets only specific field IDs from the entries.

  • Usage

    • Passing a single field ID:

        https://localhost/wp-json/gf/v2/entries?field_id=1

    • Passing multiple field IDs (semicolon separated, URL encoded):

        https://localhost/wp-json/gf/v2/entries?field_ids=1%3B2%3B3%3B4

• labels [int]

  Enabled the inclusion of field labels in the results.

  • Usage

      https://localhost/wp-json/gf/v2/entries?labels=1

  • Example Response

      {
        "id":           "71",
        "form_id":      "1",
        "date_created": "2016-11-28 18:12:17",
        "is_starred":   0,
        "is_read":      0,
        "ip":           "127.0.0.1",
        "source_url":   "http:\/\/localhost\/pagename",
        "post_id":      null,
        "created_by":   "2",
        "user_agent":   "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_2) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.87 Safari\/537.36",
        "status":       "active",
        "1":            "",
        "2":            "",
        "3":            "",
        "4":            "",
        "5":            "",
        "6.1":          "",
        "6.2":          "",
        "6.3":          "",
        "labels": {
          "1":  "Single Line Text",
          "2":  "Paragraph Text",
          "13": "File",
          "3":  "Drop Down",
          "4":  "Multi Select",
          "5":  "Number",
          "6": {
            "6.1": "Checkboxes First Choice",
            "6.2": "Checkboxes Second Choice",
            "6.3": "Checkboxes Third Choice"
          }
        }
      }

  • search [json]

    The search criteria.

    • Properties

      • field_filters [array]

        An array of filters to search by.

      • key [int|float]

        The field ID.

      • value [string]

        The value to search for.

      • operator [string]

        The comparison operator to use.

    • Usage

        {
          "field_filters": [{
            "key":      1,
            "value":    "Field Value",
            "operator": "contains"
          }]
        }

  • paging [array]

    The paging criteria.

    • Properties

      • page_size [int]

        The number of results per page.

      • current_page [int]

        The current page to pull details from.

      • offset [int]

        The offset to begin with.

    • Usage

        https://localhost/wp-json/gf/v2/entries?paging[page_size]=20&paging[current_page]=2&paging[offset]=30

  • sorting [array]

    The sorting criteria.

    • Properties

      • key [string|int]

        The key to sort by.

      • direction [string]

        The direction. Either ASC or DESC.

      • is_numeric [bool]

        If the key is numeric.

    • Usage

        https://localhost/wp-json/gf/v2/entries?sorting[key]=id&sorting[direction]=ASC&sorting[is_numeric]=true

---

POST /entries

Creates an entry.

Path

https://localhost/wp-json/gf/v2/entries

Response [int]

When creating an entry, the response body will contain the created entry ID.

Example Response

59

Required Arguments

• form_id [int]

  The Form ID for the entry.

  • Example

    Associates the entry with form ID 1.

      form_id=1

Optional Arguments

• created_by [string]

  The user ID of the entry submitter.

  • Example

    Sets the entry submitter as the user with user ID 1.

      created_by=1

• date_created [string]

  The date the entry was created, in UTC.

  • Example

    Sets the date created as 2016-11-28 18:12:17.

      date_created=2016-11-28+18%3A12%3A17

• ip [string]

  The IP address of the entry creator.

  • Example

    Sets the entry IP as 127.0.0.1.

      ip=127.0.0.1

• is_fulfilled [bool]

  Whether the transaction has been fulfilled, if applicable.

  • Example

    Sets the entry as fulfilled.

      is_fulfilled=1

• is_read [bool]

  Whether the entry has been read.

  • Example

    Marks the entry as read.

      is_read=1

• is_starred [bool]

  Whether the entry is starred.

  • Example

    Stars the entry.

      is_starred=1

• source_url [string]

  The URL where the form was embedded.

  • Examples

    Set the source URL as http://localhost/pagename:

      source_url=http%3A%2F%2Flocalhost%2Fpagename

• status [string]

  The status of the entry.

  • Examples

    Sets the status to active:

       status=active

• user_agent [string]

  The user agent string for the browser used to submit the entry.

  • Examples

    Sets the user agent as Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.87 Safari/537.36

      user_agent=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_12_2%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F54.0.2840.87+Safari%2F537.36``

Payment Arguments

• payment_amount [int]

  The amount of the payment, if applicable.

  • Limitations

    Only applies when payment fields are present.

  • Examples

    Sets the payment amount of $2500.

      payment_amount=2500

• payment_date [string]

  The date of the payment, if applicable.

  • Limitations

    Only applies when payment fields are present.

  • Example

    Sets the payment date as 2016-11-28 18:12:17.

      payment_date=2016-11-28+18%3A12%3A17

• payment_method [string]

  The payment method for the payment, if applicable.

  • Limitations

    Only applies when payment fields are present.

  • Example

    Sets the payment method as Stripe.

      payment_method=Stripe

• payment_status [string]

  The status of the payment, if applicable.

  • Limitations

    Only applies when payment fields are present.

  • Example

    Sets the payment status as Paid.

      payment_status=Paid

• transaction_id [string]

  The transaction ID for the payment, if applicable.

  • Limitations

    Only applies when payment fields are present.

  • Example

    Sets the transaction ID as 1234.

      transaction_id=1234

• transaction_type [string]

  The type of the transaction, if applicable.

  • Limitations

    Only applies when payment fields are present.

  • Example

    Sets the Subscription transaction type.

      transaction_type=Subscription

---

GET /entries/[ENTRY_ID]

Gets an entry based on the entry ID.

Path

• Single entry

    https://localhost/wp-json/gf/v2/entries/1

• Multiple entries (semicolon separated)

    https://localhost/wp-json/gf/v2/entries/1;2;3;4

Response [json]

The response will contain a JSON object which contains the entry details. An example can be found below:

• Example

    {
      "id":           "71",
      "form_id":      "1",
      "date_created": "2016-11-28 18:12:17",
      "is_starred":   0,
      "is_read":      0,
      "ip":           "127.0.0.1",
      "source_url":   "http:\/\/localhost\/pagename",
      "post_id":      null,
      "created_by":   "2",
      "user_agent":   "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_2) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.87 Safari\/537.36",
      "status":       "active",
      "1":            "",
      "2":            "",
      "3":            "",
      "4":            "",
      "5":            "",
      "6.1":          "",
      "6.2":          "",
      "6.3":          ""
    }