IntroductionUpgrading to Version 2AuthenticationSpecify the Content Type when appropriateExampleNo Response EnvelopeExampleForm SubmissionsExamplePOST Single ResourcesDELETE now trashesDELETE, POST and PUT responsesUnit TestsAPI DocumentationAuthenticationAPI PathSending RequestsPHPEndpointsGET /entriesPathResponse [json]Example ResponseRequired PropertiesOptional PropertiesSample UsageRetrieve specific fieldsInclude field labelsInclude specific formsInclude specific entriesUse PagingUse SortingSearchPOST /entriesPathInput [json]Example InputResponse [json]Example ResponseRequired PropertiesOptional PropertiesPayment PropertiesGET /entries/[ENTRY_ID]PathResponse [json]Response ExampleRequired PropertiesOptional PropertiesPUT /entries/[ENTRY_ID]PathInput [json]Example InputResponse [json]Example ResponseRequired PropertiesOptional PropertiesPayment PropertiesPOST /entries/[ENTRY_ID]/notificationsPathResponseRequired PropertiesOptional PropertiesSample UsageDELETE /entries/[ENTRY_ID]PathResponse [json]Successful ResponseFailed ResponseEntry Already Deleted ResponseRequired PropertiesOptional PropertiesGET /formsPathResponse [json]Required PropertiesOptional PropertiesSample UsagePOST /formsPathInputExample InputResponseSuccessful ResponseFailed ResponseRequired PropertiesPUT /forms/[FORM_ID]PathInputExample InputResponseSuccessful ResponseFailed ResponseRequired PropertiesDELETE /forms/[FORM_ID]PathResponseSuccessfully Deleted ResponseAttempt to Delete Trashed Form ResponseForce Delete ResponseFailed ResponseRequired PropertiesOptional PropertiesGET /forms/[FORM_ID]PathResponseSuccessful ResponseForm Not Found ResponseGET /forms/[FORM_ID]/entriesPathResponse [json]Example ResponseNo Entries Found ResponseOptional ArgumentsSample UsagePOST /forms/[FORM_ID]/entriesPathInput [json]Example InputResponse [json]Required PropertiesOptional PropertiesPayment PropertiesGET /forms/[FORM_ID]/resultsPathResponseRequired PropertiesOptional PropertiesSample UsagePOST /forms/[FORM_ID]/submissionsPathInputResponseRequired PropertiesOptional Properties
Notice: This article refers to version 2 of the Gravity Forms REST API, released as part of Gravity Forms core in Fall 2018.
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
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
{
"total_count": 2,
"entries": [
{
"2": "Creating using REST API v2",
"3": "Manually created using the POST route of the REST API v2",
"id": "311",
"form_id": "176",
"post_id": null,
"date_created": "2018-10-16 12:43:23",
"date_updated": "2018-10-16 19:33:56",
"is_starred": "0",
"is_read": "1",
"ip": "::1",
"source_url": "http://localhost/wp.dev/?gf_page=preview&id=176",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0",
"currency": "USD",
"payment_status": null,
"payment_date": null,
"payment_amount": null,
"payment_method": "",
"transaction_id": null,
"is_fulfilled": null,
"created_by": "1",
"transaction_type": null,
"status": "active",
"1.3": "Post",
"1.6": "Entries 2",
"1.2": "",
"1.4": "",
"1.8": "",
"_labels": {
"1": {
"1.2": "Prefix",
"1.3": "First",
"1.4": "Middle",
"1.6": "Last",
"1.8": "Suffix"
},
"2": "Untitled",
"3": "Untitled"
}
},
{
"2": "Creating using REST API v2",
"3": "Manually created using the POST route of the REST API v2",
"id": "310",
"form_id": "176",
"post_id": null,
"date_created": "2018-10-16 12:43:23",
"date_updated": "2018-10-16 19:32:16",
"is_starred": "0",
"is_read": "1",
"ip": "::1",
"source_url": "http://localhost/wp.dev/?gf_page=preview&id=176",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0",
"currency": "USD",
"payment_status": null,
"payment_date": null,
"payment_amount": null,
"payment_method": "",
"transaction_id": null,
"is_fulfilled": null,
"created_by": "1",
"transaction_type": null,
"status": "active",
"1.3": "Post",
"1.6": "Entries 1",
"1.2": "",
"1.4": "",
"1.8": "",
"_labels": {
"1": {
"1.2": "Prefix",
"1.3": "First",
"1.4": "Middle",
"1.6": "Last",
"1.8": "Suffix"
},
"2": "Untitled",
"3": "Untitled"
}
}
]
}
Required Properties
There are no required properties.
Optional Properties
_field_ids – A comma separated list of fields to include in the response.
_labels – Enables the inclusion of field labels in the results. Use the value 「1」 to include labels.
form_ids – An array of forms to include in the response.
include – An array of entries to include in the response. If an entry id included is not found in the database, no error is thrown.
paging – The paging criteria.
The paging encompasses the following:
page_size – The number of results per page.
current_page – The current page from which to pull details.
offset – The record number on which to start retrieving data. It is zero-based. If the current_page property is specified, then offset is not used.
search – The search criteria.
The search encompasses the following:
status – The status of the entry. Possible values are active, spam, trash.
The default status is active.
mode – The type of search to apply. Possible values are all, any. The default mode is all.
field_filters – An array of filters to search by. The array uses:
key – The field ID.
value – The value to search for.
operator – The comparison operator to use. The operator defaults to =.
Possible values are: is, =, contains, like, is not, isnot, <>, not in, in.
sorting – The sorting criteria. The default sort is by entry id, descending (most recent entries first).
The sorting encompasses the following:
key – The database field by which to sort. See the database structure for the wp_gf_entry table for fields that may be used.
direction – The direction. Either ASC, DESC, or RAND (random order).
is_numeric – If the key is numeric.
Sample Usage
Retrieve specific fields
//retrieve field ids 1, 6.1, 6.2, 6.3 and date_created for entry id 5
https://localhost/wp-json/gf/v2/entries/5?_field_ids=1,6.1,6.2,6.3,date_created
Include field labels
//include field labels in results
https://localhost/wp-json/gf/v2/entries?_labels=1
Include specific forms
//retrieve data for form id 1 and form id 30
//each form id needs to be represented as an array
//the first form is listed as form_ids[0], next forms_id[1], then forms_id[2]
https://localhost/wp-json/gf/v2/entries?form_ids[0]=1&form_ids[1]=30
Include specific entries
//retrieve data for entry id 1 and entry id 3
//each entry id needs to be represented as an array
//the first entry is listed as include[0], next include[1], then include[2]
https://localhost/wp-json/gf/v2/entries?include[0]=1&include[1]=3
Use Paging
//retrieve 20 results per page
https://localhost/wp-json/gf/v2/entries?paging[page_size]=20
//retrieve 20 results per page starting with the 16th row (offset starts at 0)
https://localhost/wp-json/gf/v2/entries?paging[page_size]=20&paging[offset]=15
//retrieve 5 results per page, starting with the second page
https://localhost/wp-json/gf/v2/entries?paging[page_size]=5&paging[current_page]=2
Use Sorting
//sort results ASCending by id
https://localhost/wp-json/gf/v2/entries?sorting[key]=id&sorting[direction]=ASC&sorting[is_numeric]=true
//sort results DESCending by date_created
https://localhost/wp-json/gf/v2/entries?sorting[key]=date_created&sorting[direction]=DESC&sorting
//sort results randomly
https://localhost/wp-json/gf/v2/entries?sorting[direction]=RAND
//sort results by post_id
https://localhost/wp-json/gf/v2/entries?sorting[key]=post_id
//sort results by field id 2
https://localhost/wp-json/gf/v2/entries?sorting[key]=2
Search
//retrieve entries where field id 2 contains the text **test**
https://localhost/wp-json/gf/v2/entries/?search={"field_filters": [{"key":2,"value":"test","operator":"contains"}]}
//retrieve entries where field id 2 AND field id 1.3 contains the text **squiffy**
//since the search mode is not specified **and** is used for the mode
https://localhost/wp-json/gf/v2/entries?search={"field_filters": [{"key":2,"value":"squiffy","operator":"contains"},{"key":1.3,"value":"squiffy","operator":"contains"}]}
//same search but setting mode to **any**
https://localhost/wp-json/gf/v2/entries?search={"field_filters":{"mode":"any","0":{"key":2,"value":"squiffy","operator":"contains"},"1":{"key":1.3,"value":"squiffy","operator":"contains"}}}
//retrieve entries created on a specific day (use the date_created field)
//this example returns entries created on September 10, 2019
https://localhost/wp-json/gf/v2/entries?search={"field_filters": [{"key":"date_created","value":"09/10/2019","operator":"is"}]}
POST /entries
Creates a single entry.
Path
https://localhost/wp-json/gf/v2/entries
Input [json]
The data sent must be in JSON format.
Example Input
{
"form_id" :"176",
"date_created" :"2018-10-16 12:43:23",
"is_starred" :0,
"is_read" :1,
"ip" :"::1",
"source_url" :"http://localhost/wp.dev/?gf_page=preview&id=176",
"currency" :"USD",
"created_by" :1,
"user_agent" :"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0",
"status" :"active",
"1.3" :"Post",
"1.6" :"Entries 2",
"2" :"Creating using REST API v2",
"3" :"Manually created using the POST route of the REST API v2"
}
Response [json]
When creating an entry, the response body will contain the newly created entry.
Example Response
{
"2": "Creating using REST API v2",
"3": "Manually created using the POST route of the REST API v2",
"form_id": 176,
"date_created": "2018-10-16 12:43:23",
"is_starred": 0,
"is_read": 1,
"ip": "::1",
"source_url": "http://localhost/wp.dev/?gf_page=preview&id=176",
"currency": "USD",
"created_by": 1,
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0",
"status": "active",
"1.3": "Post",
"1.6": "Entries 2",
"id": 313
}
Required Properties
form_id – The ID of the form to which the entry belongs.
Optional Properties
created_by – The user ID of the entry submitter.
date_created – The date the entry was created, in UTC.
ip – The IP address of the entry creator.
is_fulfilled – Whether the transaction has been fulfilled, if applicable.
is_read – Whether the entry has been read.
is_starred – Whether the entry is starred.
source_url – The URL where the form was embedded.
status – The status of the entry.
user_agent – The user agent string for the browser used to submit the entry.
Payment Properties
Payment properties only apply when payment fields are present.
payment_amount – The amount of the payment.
payment_date – The date of the payment.
payment_method – The payment method for the payment.
payment_status – The status of the payment.
transaction_id – The transaction ID for the payment.
transaction_type – The type of the transaction.
GET /entries/[ENTRY_ID]
Gets an entry based on the entry ID.
Path
https://localhost/wp-json/gf/v2/entries/1
Response [json]
The response will contain a JSON object with the entry details.
Response 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": ""
}
Required Properties
There are no required properties.
Optional Properties
_field_ids – A comma separated list of fields to include in the response.
_labels – Enables the inclusion of field labels in the results. Use the value 「1」 to include labels.
PUT /entries/[ENTRY_ID]
Updates an entry based on the specified entry ID.
Path
https://localhost/wp-json/gf/v2/entries/1
Input [json]
The data sent must be in JSON format.
Example Input
{
"form_id" :"176",
"date_created" :"2018-10-16 12:43:23",
"is_starred" :1,
"is_read" :1,
"ip" :"::1",
"source_url" :"http://localhost/wp.dev/?gf_page=preview&id=176",
"currency" :"USD",
"created_by" :1,
"user_agent" :"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0",
"status" :"active",
"1.3" :"Test Put",
"1.6" :"Update Entry 312",
"2" :"Creating using REST API v2",
"3" :"Manually created using the POST route of the REST API v2"
}
Response [json]
When updating an entry, the response body will contain the complete updated entry.
Example Response
{
"2": "Creating using REST API v2",
"3": "Manually created using the POST route of the REST API v2",
"id": "313",
"form_id": "176",
"post_id": null,
"date_created": "2018-10-16 12:43:23",
"date_updated": "2018-10-16 21:13:37",
"is_starred": "1",
"is_read": "1",
"ip": "::1",
"source_url": "http://localhost/wp.dev/?gf_page=preview&id=176",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0",
"currency": "USD",
"payment_status": null,
"payment_date": null,
"payment_amount": null,
"payment_method": "",
"transaction_id": null,
"is_fulfilled": null,
"created_by": "1",
"transaction_type": null,
"status": "active",
"1.3": "Test Put",
"1.6": "Update Entry 312",
"1.2": "",
"1.4": "",
"1.8": ""
}
Required Properties
There are no required properties, but values not provided WILL BE BLANKED OUT.
Optional Properties
created_by – The user ID of the entry submitter.
date_created – The date the entry was created, in UTC.
ip – The IP address of the entry creator.
is_fulfilled – Whether the transaction has been fulfilled, if applicable.
is_read – Whether the entry has been read.
is_starred – Whether the entry is starred.
source_url – The URL where the form was embedded.
status – The status of the entry.
user_agent – The user agent string for the browser used to submit the entry.
Payment Properties
Payment properties only apply when payment fields are present.
payment_amount – The amount of the payment.
payment_date – The date of the payment.
payment_method – The payment method for the payment.
payment_status – The status of the payment.
transaction_id – The transaction ID for the payment.
transaction_type – The type of the transaction.
POST /entries/[ENTRY_ID]/notifications
Sends the notifications for the given entry.
Path
https://localhost/wp-json/gf/v2/entries/1/notifications
Response
If successful, an array of the notification ids processed is returned.
[
"5bc65eb299da8",
"5bc63abd9601a"
]
Required Properties
There are no required properties
Optional Properties
_notifications – Comma-separated list of notification ids to be sent for the entry.
_event – The event to trigger. The default is 「form_submission」.
Sample Usage
https://localhost/wp-json/gf/v2/entries/1/notifications?_notifications=5bc65eb299da8,5bc63abd9601a
https://localhost/wp-json/gf/v2/entries/1/notifications?_event=form_submission
DELETE /entries/[ENTRY_ID]
Sends the specified entry to the trash. If the entry is already in the trash then repeating this request will not delete the entry permanently but the response code will be 410 (Gone). Use the 『force』 parameter to delete the entry permanently.
Path
https://localhost/wp-json/gf/v2/entries/1
https://localhost/wp-json/gf/v2/entries/1?force=1
Response [json]
Successful Response
A successful response will return a JSON string of the trashed or deleted entry.
{
"2": "x",
"3": "x",
"id": "314",
"form_id": "176",
"post_id": null,
"date_created": "2018-10-16 21:57:28",
"date_updated": "2018-10-16 21:57:28",
"is_starred": "0",
"is_read": "0",
"ip": "::1",
"source_url": "http://localhost/wp.dev/?gf_page=preview&id=176",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
"currency": "USD",
"payment_status": null,
"payment_date": null,
"payment_amount": null,
"payment_method": null,
"transaction_id": null,
"is_fulfilled": null,
"created_by": "1",
"transaction_type": null,
"status": "trash",
"1.3": "test",
"1.6": "test",
"1.2": "",
"1.4": "",
"1.8": ""
}
Failed Response
A failed response will provide a JSON string of the error code and message.
{
"code": "gf_cannot_delete",
"message": "Invalid entry id: 71",
"data": {
"status": 500
}
}
Entry Already Deleted Response
{
"code": "gf_already_trashed",
"message": "The entry has already been deleted.",
"data": {
"status": 410
}
}
Required Properties
There are no required properties.
Optional Properties
force – Deletes the entry permanently when setting to 「1」.
GET /forms
Gets the details of all forms.
Path
https://localhost/wp-json/gf/v2/forms
Response [json]
{
"4": {
"id": "4",
"title": "Multi-Page Form",
"entries": "2"
},
"1": {
"id": "1",
"title": "Test Form",
"entries": "60"
},
"5": {
"id": "5",
"title": "Test Form 2",
"entries": "2"
},
"6": {
"id": "6",
"title": "Test Form 3",
"entries": "2"
}
}
Required Properties
There are no required properties.
Optional Properties
include – An array of forms to include in the response.
Sample Usage
https://localhost/wp-json/gf/v2/forms?include[1]&include[3]
POST /forms
Creates a form.
Path
https://localhost/wp-json/gf/v2/forms
Input
The information for the new form will be in a JSON string.
Example Input
{
"title":"API Generated Form",
"description":"This is the description for the form generated by the API",
"labelPlacement":"top_label",
"button":{
"type":"text",
"text":"",
"imageUrl":""
},
"fields":[
{
"id" : "1",
"label" : "My Text",
"type" : "text"
},
{
"id" : "2",
"label" : "More Text",
"type" : "text"
}
],
"confirmations":{
"0":
{
"id" : 0,
"name" : "Default Confirmation",
"type" : "redirect",
"url" : "http://www.rocketgenius.com",
"isDefault" : true
},
"1":
{
"id" : 1,
"name" : "Confirmation 2",
"type" : "message",
"message" : "Thanks for contacting us! We will get in touch with you shortly.",
"isDefault" : false
}
}
}
Response
Successful Response
A successful response returns a JSON string of the newly created form.
{
"title":"API Generated Form(2)",
"description":"This is the description for the form generated by the API",
"labelPlacement":"top_label",
"button":{
"type":"text",
"text":"",
"imageUrl":""
},
"fields":[
{
"type":"text","id":1,
"label":"My Text",
"visibility":"visible",
"pageNumber":1,
"formId":179,
"adminLabel":"",
"description":"",
"isRequired":false,
"allowsPrepopulate":false,
"inputMask":false,
"inputMaskValue":"",
"inputType":"",
"size":"",
"errorMessage":"",
"labelPlacement":"",
"descriptionPlacement":"",
"subLabelPlacement":"",
"placeholder":"",
"cssClass":"",
"inputName":"",
"noDuplicates":false,
"defaultValue":"",
"inputs":"",
"choices":"",
"conditionalLogic":""
},
{
"type":"text",
"id":2,
"label":"More Text",
"visibility":"visible",
"pageNumber":1,
"formId":179,
"adminLabel":"",
"description":"",
"isRequired":false,
"allowsPrepopulate":false,
"inputMask":false,
"inputMaskValue":"",
"inputType":"",
"size":"",
"errorMessage":"",
"labelPlacement":"",
"descriptionPlacement":"",
"subLabelPlacement":"",
"placeholder":"",
"cssClass":"",
"inputName":"",
"noDuplicates":false,
"defaultValue":"",
"inputs":"",
"choices":"",
"conditionalLogic":""
}
],
"version":"2.3.4.3",
"id":179,
"notifications":[],
"confirmations":[
{
"id":0,
"name":"Default Confirmation",
"type":"redirect",
"url":"http://www.rocketgenius.com",
"isDefault":true
},
{
"id":1,
"name":"Confirmation 2",
"type":"message",
"message":"Thanks for contacting us! We will get in touch with you shortly.",
"isDefault":false
}
],
"is_active":"1",
"date_created":"2018-10-18 20:18:43",
"is_trash":"0"
}
Failed Response
The failed response will be a JSON string with the code and message.
{
"code": "missing_form_json",
"message": "The Form object must be sent as a JSON string in the request body with the content-type header set to application/json.",
"data": {
"status": 400
}
}
Required Properties
fields – A collection of Field Objects. See the example input above for how to format this.
title – The form title.
PUT /forms/[FORM_ID]
Updates a form.
Path
https://localhost/wp-json/gf/v2/forms
Input
The form information will be sent in a JSON string.
Example Input
{
"title":"My Form Updated Using PUT",
"description":"This is the description for the form generated by the API",
"labelPlacement":"top_label",
"button":{
"type":"text",
"text":"",
"imageUrl":""
},
"fields":[
{
"id" : "1",
"label" : "My Text",
"type" : "text"
},
{
"id" : "2",
"label" : "More Text",
"type" : "text"
}
]
}
Response
Successful Response
A successful response returns a JSON string of the updated form.
{
"title": "My Form Created by POSTing",
"description": "This is the description for the form generated by the API",
"labelPlacement": "top_label",
"button": {
"type": "text",
"text": "",
"imageUrl": ""
},
"fields": [
{
"type": "text",
"id": 1,
"label": "My Text",
"visibility": "visible",
"pageNumber": 1,
"fields": "",
"formId": "184",
"adminLabel": "",
"description": "",
"isRequired": false,
"allowsPrepopulate": false,
"inputMask": false,
"inputMaskValue": "",
"inputType": "",
"size": "",
"errorMessage": "",
"labelPlacement": "",
"descriptionPlacement": "",
"subLabelPlacement": "",
"placeholder": "",
"cssClass": "",
"inputName": "",
"noDuplicates": false,
"defaultValue": "",
"inputs": "",
"choices": "",
"conditionalLogic": ""
},
{
"type": "text",
"id": 2,
"label": "More Text",
"visibility": "visible",
"pageNumber": 1,
"fields": "",
"formId": "184",
"adminLabel": "",
"description": "",
"isRequired": false,
"allowsPrepopulate": false,
"inputMask": false,
"inputMaskValue": "",
"inputType": "",
"size": "",
"errorMessage": "",
"labelPlacement": "",
"descriptionPlacement": "",
"subLabelPlacement": "",
"placeholder": "",
"cssClass": "",
"inputName": "",
"noDuplicates": false,
"defaultValue": "",
"inputs": "",
"choices": "",
"conditionalLogic": ""
}
],
"version": "2.4-beta-1",
"id": "184",
"notifications": [],
"confirmations": [
{
"id": 0,
"name": "Default Confirmation",
"type": "redirect",
"url": "http://www.rocketgenius.com",
"isDefault": true
},
{
"id": 1,
"name": "Confirmation 2",
"type": "message",
"message": "Thanks for contacting us! We will get in touch with you shortly.",
"isDefault": false
}
],
"is_active": "0",
"date_created": "2018-10-22 22:08:08",
"is_trash": "0"
}
Failed Response
The failed response will be a JSON string with the code and message.
Form Not Found
{
"code": "not_found",
"message": "Form not found",
"data": {
"status": 404
}
}
Bad JSON string
{
"code": "missing_form_json",
"message": "The Form object must be sent as a JSON string in the request body with the content-type header set to application/json.",
"data": {
"status": 400
}
}
Required Properties
title – The form title.
NOTE: The title will be removed if you do not include it in the string.
fields – A collection of Field Objects. See the example input above for how to format this.
NOTE: If you do NOT include the fields collection, the form fields will be removed!
DELETE /forms/[FORM_ID]
Sends the specified form to the trash. If the form is already in the trash, then repeating this request will not delete
the form permanently, but the response code will be 410 (Gone). Use the force parameter to delete the form permanently.
Path
https://localhost/wp-json/gf/v2/forms/1
Response
Successfully Deleted Response
A successful response returns the deleted form. Notice the is_trash value is set to 「1」, meaning the form is no longer active and is in the Trash.
{
"title": "My Form Updated",
"labelPlacement": "top_label",
"fields": [
{
"type": "text",
"id": 1,
"label": "My Text",
"visibility": "visible",
"pageNumber": 1,
"fields": "",
"formId": "183",
"adminLabel": "",
"description": "",
"isRequired": false,
"allowsPrepopulate": false,
"inputMask": false,
"inputMaskValue": "",
"inputType": "",
"size": "",
"errorMessage": "",
"labelPlacement": "",
"descriptionPlacement": "",
"subLabelPlacement": "",
"placeholder": "",
"cssClass": "",
"inputName": "",
"noDuplicates": false,
"defaultValue": "",
"inputs": "",
"choices": "",
"conditionalLogic": ""
}
],
"version": "2.4-beta-1",
"id": "183",
"notifications": [],
"confirmations": [
{
"id": 0,
"name": "Default Confirmation",
"type": "redirect",
"url": "http://www.rocketgenius.com",
"isDefault": true
},
{
"id": 1,
"name": "Confirmation xxxxx",
"type": "message",
"message": "Thanks for contacting us! We will get in touch with you shortly.",
"isDefault": false,
"disableAutoformat": false,
"pageId": 0,
"url": "",
"queryString": "",
"conditionalLogic": {
"actionType": "show",
"logicType": "all",
"rules": [
{
"fieldId": "1",
"operator": "is",
"value": ""
}
]
}
}
],
"is_active": "0",
"date_created": "2018-10-22 21:39:12",
"is_trash": "1"
}
Attempt to Delete Trashed Form Response
{
"code": "gf_already_trashed",
"message": "The form has already been deleted.",
"data": {
"status": 410
}
}
Force Delete Response
Notice the deleted value of true in the response. The entire Form Object is also placed as the value for previous.
{
"deleted": true,
"previous": {
"title": "My Form Updated",
"labelPlacement": "top_label",
"fields": [
{
"type": "text",
"id": 1,
"label": "My Text",
"visibility": "visible",
"pageNumber": 1,
"fields": "",
"formId": "183",
"adminLabel": "",
"description": "",
"isRequired": false,
"allowsPrepopulate": false,
"inputMask": false,
"inputMaskValue": "",
"inputType": "",
"size": "",
"errorMessage": "",
"labelPlacement": "",
"descriptionPlacement": "",
"subLabelPlacement": "",
"placeholder": "",
"cssClass": "",
"inputName": "",
"noDuplicates": false,
"defaultValue": "",
"inputs": "",
"choices": "",
"conditionalLogic": ""
}
],
"version": "2.4-beta-1",
"id": "183",
"notifications": [],
"confirmations": [
{
"id": 0,
"name": "Default Confirmation",
"type": "redirect",
"url": "http://www.rocketgenius.com",
"isDefault": true
},
{
"id": 1,
"name": "Confirmation xxxxx",
"type": "message",
"message": "Thanks for contacting us! We will get in touch with you shortly.",
"isDefault": false,
"disableAutoformat": false,
"pageId": 0,
"url": "",
"queryString": "",
"conditionalLogic": {
"actionType": "show",
"logicType": "all",
"rules": [
{
"fieldId": "1",
"operator": "is",
"value": ""
}
]
}
}
],
"is_active": "0",
"date_created": "2018-10-22 21:39:12",
"is_trash": "1"
}
}
Failed Response
{
"code": "gf_form_invalid_id",
"message": "Invalid form id.",
"data": {
"status": 404
}
}
Required Properties
There are no required properties.
Optional Properties
force – Deletes the form permanently when setting to 「1」, instead of moving to the Trash.
GET /forms/[FORM_ID]
Gets the details of a form based on the specified form ID.
Path
https://localhost/wp-json/gf/v2/forms/185
Response
Successful Response
The Form Object is returned.
{
"title": "Simple Form",
"description": "",
"labelPlacement": "top_label",
"descriptionPlacement": "below",
"button": {
"type": "text",
"text": "Submit",
"imageUrl": ""
},
"fields": [
{
"type": "text",
"id": 1,
"label": "Test",
"adminLabel": "",
"isRequired": false,
"size": "medium",
"errorMessage": "",
"visibility": "visible",
"inputs": null,
"formId": 185,
"description": "",
"allowsPrepopulate": false,
"inputMask": false,
"inputMaskValue": "",
"inputType": "",
"labelPlacement": "",
"descriptionPlacement": "",
"subLabelPlacement": "",
"placeholder": "",
"cssClass": "",
"inputName": "",
"noDuplicates": false,
"defaultValue": "",
"choices": "",
"conditionalLogic": "",
"productField": "",
"enablePasswordInput": "",
"maxLength": "",
"multipleFiles": false,
"maxFiles": "",
"calculationFormula": "",
"calculationRounding": "",
"enableCalculation": "",
"disableQuantity": false,
"displayAllCategories": false,
"useRichTextEditor": false,
"pageNumber": 1,
"fields": ""
}
],
"version": "2.4-beta-1",
"id": 185,
"useCurrentUserAsAuthor": true,
"postContentTemplateEnabled": false,
"postTitleTemplateEnabled": false,
"postTitleTemplate": "",
"postContentTemplate": "",
"lastPageButton": null,
"pagination": null,
"firstPageCssClass": null,
"nextFieldId": 2,
"notifications": {
"5bcf58ccf39c8": {
"id": "5bcf58ccf39c8",
"to": "{admin_email}",
"name": "Admin Notification",
"event": "form_submission",
"toType": "email",
"subject": "New submission from {form_title}",
"message": "{all_fields}"
}
},
"confirmations": {
"5bcf58cd012e7": {
"id": "5bcf58cd012e7",
"name": "Default Confirmation",
"isDefault": true,
"type": "message",
"message": "Thanks for contacting us! We will get in touch with you shortly.",
"url": "",
"pageId": "",
"queryString": ""
}
},
"is_active": "1",
"date_created": "2018-10-23 17:22:20",
"is_trash": "0"
}
Form Not Found Response
{
"code": "gf_not_found",
"message": "Form not found",
"data": null
}
GET /forms/[FORM_ID]/entries
Gets entries associated with a specific form.
Path
https://localhost/wp-json/gf/v2/forms/185/entries
Response [json]
The response will contain a JSON object which contains the details for each entry, along with a total_count of how many entries were returned.
Example Response
{
"total_count": 2,
"entries": [
{
"1": "Test 2",
"id": "318",
"form_id": "185",
"post_id": null,
"date_created": "2018-10-23 17:29:47",
"date_updated": "2018-10-23 17:29:47",
"is_starred": "0",
"is_read": "0",
"ip": "::1",
"source_url": "https://localhost/wp.dev/?gf_page=preview&id=185",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.67 Safari/537.36",
"currency": "USD",
"payment_status": null,
"payment_date": null,
"payment_amount": null,
"payment_method": null,
"transaction_id": null,
"is_fulfilled": null,
"created_by": "1",
"transaction_type": null,
"status": "active",
"3.2": "",
"3.3": "",
"3.4": "",
"3.6": "",
"3.8": ""
},
{
"1": "Test",
"id": "317",
"form_id": "185",
"post_id": null,
"date_created": "2018-10-23 17:29:38",
"date_updated": "2018-10-23 17:29:38",
"is_starred": "0",
"is_read": "0",
"ip": "::1",
"source_url": "https://localhost/wp.dev/?gf_page=preview&id=185",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.67 Safari/537.36",
"currency": "USD",
"payment_status": null,
"payment_date": null,
"payment_amount": null,
"payment_method": null,
"transaction_id": null,
"is_fulfilled": null,
"created_by": "1",
"transaction_type": null,
"status": "active",
"3.2": "",
"3.3": "",
"3.4": "",
"3.6": "",
"3.8": ""
}
],
"_labels": {
"1": "Test",
"3": {
"3": "Name",
"3.2": "Prefix",
"3.3": "First",
"3.4": "Middle",
"3.6": "Last",
"3.8": "Suffix"
}
}
}
No Entries Found Response
{
"total_count": 0,
"entries": []
}
Optional Arguments
_field_ids – A comma separated list of fields to include in the response.
_labels – Enables the inclusion of field labels in the results. Use the value 「1」 to include labels.
paging – The paging criteria.
The paging encompasses the following:
page_size – The number of results per page.
current_page – The current page from which to pull details.
offset – The offset to begin with.
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.
sorting – The sorting criteria.
The sorting encompasses the following:
key – The key by which to sort.
direction – The direction. Either ASC or DESC.
is_numeric – If the key is numeric.
Sample Usage
https://localhost/wp-json/gf/v2/forms/1/entries?_field_ids=1,6.1,6.2,6.3,date_created
https://localhost/wp-json/gf/v2/forms/1/entries?_labels=1
https://localhost/wp-json/gf/v2/forms/1/entries?paging[page_size]=20&paging[current_page]=2&paging[offset]=30
https://localhost/wp-json/gf/v2/forms/1/entries/?search={"field_filters": [{"key":2,"value":"test","operator":"contains"}]}
https://localhost/wp-json/gf/v2/forms/1/entries?sorting[key]=id&sorting[direction]=ASC&sorting[is_numeric]=true
POST /forms/[FORM_ID]/entries
Creates an entry based on the specified form ID.
Path
https://localhost/wp-json/gf/v2/forms/1/entries
Input [json]
The data sent must be in JSON format.
Example Input
{
"date_created" :"2018-10-16 12:43:23",
"is_starred" :0,
"is_read" :1,
"ip" :"::1",
"source_url" :"http://localhost/wp.dev/?gf_page=preview&id=176",
"currency" :"USD",
"created_by" :1,
"user_agent" :"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0",
"status" :"active",
"1" :"POST using /forms/185/entries",
"3.3" :"API name",
"3.6" :"POST name"
}
Response [json]
The response body will contain the newly created entry.
{
"1": "POST using /forms/185/entries",
"date_created": "2018-10-16 12:43:23",
"is_starred": 0,
"is_read": 1,
"ip": "::1",
"source_url": "http://localhost/wp.dev/?gf_page=preview&id=176",
"currency": "USD",
"created_by": 1,
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0",
"status": "active",
"3.3": "API name",
"3.6": "POST name",
"form_id": 185,
"id": 327
}
Required Properties
There are no required properties.
Optional Properties
created_by – The user ID of the entry submitter.
date_created – The date the entry was created, in UTC.
ip – The IP address of the entry creator.
is_fulfilled – Whether the transaction has been fulfilled, if applicable.
is_read – Whether the entry has been read.
is_starred – Whether the entry is starred.
source_url – The URL where the form was embedded.
status – The status of the entry.
user_agent – The user agent string for the browser used to submit the entry.
Payment Properties
Payment properties only apply when payment fields are present.
payment_amount – The amount of the payment.
payment_date – The date of the payment.
payment_method – The payment method for the payment.
payment_status – The status of the payment.
transaction_id – The transaction ID for the payment.
transaction_type – The type of the transaction.
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
POST /forms/[FORM_ID]/submissions
Submits the specified form ID with the specified values.
Path
https://localhost/wp-json/gf/v2/forms/1/submissions
Input
The input is a JSON object containing each of the name-value pairs.
{
"input_1": "test",
"input_3_3" : "Rocket",
"input_3_6" : "Genius",
"field_values": "",
"source_page": 1,
"target_page": 0
}
Response
{
"is_valid":true,
"page_number":0,
"source_page_number":1,
"confirmation_message":"Thanks for contacting us! We will get in touch with you shortly.