Introduction
The form submissions endpoint was added in Gravity Forms 2.4, it is used to create an entry by sending input values through the complete form submission process.
This includes the following features and processes:
- Saving progress for the save and continue feature
- Validation
- Configured anti-spam checks e.g. honeypot, captcha, Akismet etc.
- Saving the entry to the database
- Add-on feeds
- Notifications
- Confirmations
- All the filters and action hooks triggered by a regular form submission
If you only want to validate submission values, without performing the other processes above, see Validating Forms with REST API v2.
Authentication
See REST API v2 Authentication.
Gravity Forms capabilities are not required to use this endpoint.
Method
This endpoint only accepts POST requests.
Path
/gf/v2/forms/[FORM_ID]/submissions
Content-Type
This endpoint supports the application/json, application/x-www-form-urlencoded, and multipart/form-data content types.
File uploads for single file upload type fields are only supported when using multipart/form-data.
Required Properties
The request body should contain the submitted values using the field input names (e.g. input_1) as the keys.
The expected input names are identical to the input names found in the form markup. If you have any doubts about the name of an input, use your browsers developer tools to inspect the inputs via the form preview page.
Optional Properties
The request body can also include the following properties.
| Key | Type | Description |
|---|---|---|
| field_values | array | An array of dynamic population parameter keys with their corresponding values used to populate the fields. Useful for evaluating conditional logic rules to determine which fields should be validated and saved. |
| target_page | integer | Default is 0. For multi-page forms; indicates which page would be loaded next if the current page passes validation. |
| source_page | integer | Default is 1. For multi-page forms; indicates which page was active when the values were submitted for validation. |
Response [json]
The response will contain a JSON object which contains the following:
| Key | Type | Description |
|---|---|---|
| is_valid | bool | The form validation result. |
| validation_messages | array|object | Only present when is_valid is false. An array of validation messages for the fields that failed validation. |
| page_number | integer | For multi-page forms. The page that should be displayed. |
| source_page_number | integer | For multi-page forms. The page that was submitted. |
| confirmation_message | string | Only present when is_valid is true.The resume or confirmation message. |
| confirmation_type | string | Only present when is_valid is true.The type of confirmation being used for the current submission. message or redirect |
| confirmation_redirect | string | Only present when is_valid is true and the confirmation_type is redirect.The URL the submission should redirect to. |
| entry_id | integer | Only present when is_valid is true and the user authenticating the request has permission to view or edit entries.The ID of the entry created by the submission. |
| resume_token | string | Only present if the value of the gform_save input in the request body was true.The token that can be used to repopulate the embedded form with the saved values. |
Important: When the confirmation_type is set to redirect, the URL specified in confirmation_redirect will be included in the response’s Location header. Certain REST clients will automatically follow this header, resulting in a redirection to the specified URL instead of displaying or using the JSON response. If you are unable to prevent your REST client from automatically following redirects, you can utilize the rest_post_dispatch filter to remove the Location header from the response. The filter can be used in the theme functions.php file, a custom functions plugin, or a code snippets plugin.`
add_filter( 'rest_post_dispatch', function ( $response, $server, $request ) {
if ( $response->get_status() !== 200
|| $request->get_method() !== 'POST'
|| empty( $request['form_id'] )
|| $request->get_route() !== "/gf/v2/forms/{$request['form_id']}/submissions"
) {
return $response;
}
$headers = $response->get_headers();
unset( $headers['Location'] );
$response->set_headers( $headers );
return $response;
}, 10, 3 );
Usage Examples
application/json
cURL Request
curl --location --request POST 'https://example.com/wp-json/gf/v2/forms/1/submissions' \
--header 'Content-Type: application/json' \
--data-raw '{
"input_1": "value",
"input_2": "another value",
"input_4_3": "first",
"input_4_6": "last"
}'
Response
{
"is_valid": true,
"page_number": 0,
"source_page_number": 1,
"confirmation_message": "<div id='gform_confirmation_wrapper_1' class='gform_confirmation_wrapper '><div id='gform_confirmation_message_1' class='gform_confirmation_message_1 gform_confirmation_message'>Thanks for contacting us! We will get in touch with you shortly.</div></div>",
"confirmation_type": "message"
}
multipart/form-data
cURL Request
curl --location --request POST 'https://example.com/wp-json/gf/v2/forms/1/submissions' \
--form 'input_1="value"' \
--form 'input_3=@"/path/to/file.jpg"'
Response
{
"is_valid": false,
"validation_messages": {
"3": "The uploaded file type is not allowed. Must be one of the following: pdf"
},
"page_number": 1,
"source_page_number": 1
}