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
<?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
- Creating Forms with the REST API v2
- Getting Forms with the REST API v2
- Updating Forms with the REST API v2
- Submitting Forms with REST API v2
- Validating Forms with REST API v2
- Deleting Forms with the REST API v2
Notifications
Feeds
Fields
Entries
- Creating Entries with the REST API v2
- Searching and Getting Entries with the REST API v2
- Updating Entries with the REST API v2
- Deleting Entries with the REST API v2