REST API v2 Guide

Introduction

The REST API v2 add-on (which was released as a beta initially back in late 2016) was incorporated into Gravity Forms core from Gravity Forms 2.4, released in the Fall of 2018. The original Web API functionality supported by previous releases of Gravity Forms is now renamed to REST API Version 1. This document describes some of the changes between the two API versions as well as a full description on all REST API Version 2 endpoints.

If you need information on version 1 of the REST API, see the REST API v1 documentation

Upgrading to Version 2

The API is intended to feel as familiar as possible to developers who have worked with the WordPress REST API while
maintaining as much functionality as possible as version 1. The endpoints are largely the same as version 1, however,
the responses are slightly different and authentication has changed.

The following breaking changes are required by clients to consume version 2:

Authentication

The REST API version 2 now supports Basic Authentication as well as OAuth 1.0a Authentication. In order to use the new version 2 endpoints, users will first need to create API Keys on the REST API setting page, then configure Basic or OAuth 1.0a Authentication. For more information, see the Authentication section below.

Specify the Content Type when appropriate

The content-type application/json must be specified when sending JSON.

Example

curl --data [EXAMPLE_DATA] --header "Content-Type: application/json" https://localhost/wp-json/gf/v2

No Response Envelope

The response will not be enveloped by default. This means that the response will not be a JSON string containing the
“status” and “response” – the body will contain the response and the HTTP code will contain the status.

The WP-API will envelope the response if the _envelope param is included in the request.

Example

Standard response:

{
"3":                "Drop Down First Choice",
"created_by":       "1",
"currency":         "USD",
"date_created":     "2016-10-10 18:06:12",
"form_id":          "1",
"id":               "1",
"ip":               "127.0.0.1",
"is_fulfilled":     null,
"is_read":          0,
"is_starred":       0,
"payment_amount":   null,
"payment_date":     null,
"payment_method":   null,
"payment_status":   null,
"post_id":          null,
"source_url":       "http://localhost?gf_page=preview&id=1",
"status":           "active",
"transaction_id":   null,
"transaction_type": null,
"user_agent":       "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.143 Safari/537.36"
}

Response with _envelope parameter:

{
"body": {
"3":                "Drop Down First Choice",
"created_by":       "1",
"currency":         "USD",
"date_created":     "2016-10-10 18:06:12",
"form_id":          "1",
"id":               "1",
"ip":               "127.0.0.1",
"is_fulfilled":     null,
"is_read":          0,
"is_starred":       0,
"payment_amount":   null,
"payment_date":     null,
"payment_method":   null,
"payment_status":   null,
"post_id":          null,
"source_url":       "http://localhost?gf_page=preview&id=1",
"status":           "active",
"transaction_id":   null,
"transaction_type": null,
"user_agent":       "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.143 Safari/537.36"
},
"headers": {
"Allow": "GET, POST, PUT, PATCH, DELETE"
},
"status": 200
}

Form Submissions

The Form Submissions endpoint now accepts application/json, application/x-www-form-urlencoded and multipart/form-data
content types. With the introduction of support for multipart/form-data now files can be sent to single file upload fields.

Request values should be sent all together instead of in separate elements for input_values, field_values, target_page
and source_page.

Example

Example body of a JSON request:

{
"input_1":      "test",
"field_values": "",
"source_page":  1,
"target_page":  0
}

POST Single Resources

In order to maintain consistency with the WP API, the POST /entries and POST /forms endpoints no longer accept
collections. This means that it’s no longer possible to create multiple entries or forms in a single request.

DELETE now trashes

Sending DELETE requests will send the resource to the trash instead of deleting it permanently.
Repeating the DELETE request will not delete the resource permanently but it will generate a 401 (Gone) response code.
Use the ‘force’ parameter to delete the entry or form permanently.

DELETE, POST and PUT responses

Successful DELETE, POST and PUT requests now return the deleted, updated or created entry or form instead of a confirmation message.

Unit Tests

The unit tests can be installed from the terminal using:

bash tests/bin/install.sh [DB_NAME] [DB_USER] [DB_PASSWORD] [DB_HOST]

If you’re using VVV you can use this command:

bash tests/bin/install.sh wordpress_unit_tests root root localhost

API Documentation

Authentication

See the Rest API V2 Authentication article.

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

See the following articles:

Forms

Notifications

Feeds

Fields

Entries


GET /forms/[FORM_ID]/results

Gets form details, including entry details.
Returns the aggregate results (entry counts) for each of the fields in the given form.

Path

https://localhost/wp-json/gf/v2/forms/1/results

Response

{
"entry_count": 11,
"field_data": {
"1": 11,
"3": 10
},
"status": "complete",
"timestamp": 1540320989,
"labels": {
"1": "Test",
"3": "Name"
}
}

Required Properties

There are no required properties.

Optional Properties

  • search – The search criteria.
    The search encompasses the following:
            field_filters – An array of filters to search by.
            key – The field ID.
            value – The value to search for.
            operator – The comparison operator to use.

Sample Usage