Form submissions are handled with the submitGfForm mutation.
This mutation can be used either to submit an Entry or to submit a draft entry, by toggling the saveAsDraft input to true .
The fieldValues input takes an array of objects containing the id of the field, and a value input that corresponds to the Gravity Forms Field type.
Note: Due to GraphQL's current lack of support for Input Union types, you must use the specific value type specific to that field. A full list of field value types and their corresponding field fragments are below.
| Field Value Input Type | Used for | Sub-fields |
|---|---|---|
addressValues ( obj ) |
AddressField |
city country lineTwo state street zip |
chainedSelectValues ( [ obj ] ) 1 |
ChainedSelectField |
inputId value |
checkboxValues ( [ obj ] ) |
CheckboxField QuizField 3 |
inputId value |
consentValue ( boolean ) |
ConsentField |
|
emailValues ( obj ) |
EmailField |
confirmationValue value |
fileUploadValues ( [ Upload ] )2 |
FileUploadField |
See Submitting File Uploads |
listValues ( [ obj ] ) |
ListField |
rowValues ( [ String ] ) |
nameValues ( obj ) |
NameField |
first last midele prefix suffix |
postImageValues ( obj ) 2 |
PostImageField |
altText caption description image (Upload)2 title |
value ( string ) |
CaptchaField 3ConsentField DateField HiddenField NumberField PhoneField PostContentField PostExcerptField PostTitleField QuizField 4RadioField SelectField SignatureField TextAreaField TextField TimeField WebsiteField Also used by default for custom fields. |
n/a |
values ( [ string ] ) |
MultiSelectField PostCategoryField PostCustomField PostTagsField |
n/a |
1: In order to use chainedSelectValues you must install and activate Gravity Forms Chained Selects.
2: In order to use fileUploadValues or postImageValues , you must install and activate WPGraphQL Upload. See Submitting File Uploads below.
2: The value for a Captcha field is its validation token. See Captcha Validation below.
3: Gravity Forms Quiz Fields can be either a Checkbox, Radio, or Select field. The field value input type is assigned accordingly.
{
submitGfForm(
input: {
formId: 50
entryMeta {
createdById: 1 # The user ID.
ip: "" # IP address
}
fieldValues: [
{
# Text field value
id: 1
value: "This is a text field value."
}
{
# MultiSelect field value
id: 2
values: ["First Choice", "Second Choice"]
}
{
# Address field value
id: 3
addressValues: {
street: "1600 Pennsylvania Avenue NW"
lineTwo: "Office of the President"
city: "Washington"
state: "DC"
zip: "20500"
country: "USA"
}
}
{
# ChainedSelect field value
id: 4
chainedSelectValues: [
{ inputId: 4.1, value: "Choice 1" }
{ inputId: 4.2, value: "Choice 2" }
]
}
{
# Checkbox field value
id: 5
checkboxValues: [
{ inputId: 5.1, value: "This checkbox field is selected" }
{ inputId: 5.2, value: "This checkbox field is also selected" }
]
}
{
# Email field value
id: 6
emailValues: {
value: "myemail@email.test"
confirmationValue: "myemail@email.test" # Only necessary if Email confirmation is enabled.
}
}
{
# Multi-column List field value
id: 6
listValues: { rowValues: ["a", "b", "c"] }
}
{
# Name field value
id: 7
nameValues: {
prefix: "Mr."
first: "John"
middle: "Edward"
last: "Doe"
suffix: "PhD"
}
}
]
saveAsDraft: false # If true, the submission will be saved as a draft entry.
# Set the following to validate part of a multipage form without saving the submission.
sourcePage: 1
targetPage: 0
}
) {
confirmation {
type
message # The message HTML - if the confirmation type is a "MESSAGE".
url # The redirect URL - if the confirmation type is a "REDIRECT".
}
errors {
id # The field that failed validation.
message
}
entry {
# See docs on querying Entries.
id
... on GfSubmittedEntry {
databaseId
}
... on GfDraftEntry {
resumeToken
}
}
}
}In addition to any frontend, or GraphQL validation checks, Gravity Forms validates the values of each formField , and returns them in the errors field.
If the field is updated successfully, the errors field will be null, the confirmation field will be a SubmissionConfirmation object, and the entry in the response will be the newly updated GfEntry object which resolves to either a GfSubmittedEntry or GfDraftEntry.
If the field is NOT updated successfully, such as when a field validation error occurs, the confirmation and entry objects in the response will be null , and the errors field will provide data about the error. Example:
"errors": [
{
"id": "1",
"message": "The text entered exceeds the maximum number of characters."
}
]As of v0.11.0, WPGraphQL for Gravity Forms supports server-side captcha validation. This is particularly useful with Google reCAPTCHA, as it keeps your API secret key hidden.
To validate a reCAPTCHA field, you need to fetch the captcha response token, and pass that to the field's value input argument:
mutation submit( $token: String ) {
submitGfForm(
input: {
formId: 50
fieldValues: [
# other form fields would go here.
{
# Captcha Field
id: 1
value: $token # The google reCAPTCHA response token.
}
}
}
) {
errors {
id
message
}
confirmation {
message
}
entry {
databaseId
}
}
}To enable WPGraphQL support for submitting files (via the fileUploadValues or postImageValues inputs ), you must first install and activate the WPGraphQL Upload extension, which will add the Upload scalar type to the GraphQL schema.
Note: The GraphQL Spec - and many GraphQL clients - does not natively implement support the graphql-multipart-request-spec, and may require an additional dependency such as apollo-upload-client.
mutation submit( $exampleUploads: [ Upload ], $exampleImageUpload: Upload ){
submitGfForm(
input: {
formId: 50
fieldValues: [
# other form fields would go here.
{
# FileUpload field
id: 1
fileUploadValues: $exampleUploads # An array of Upload objects.
}
{
# PostImage field
id: 2
postImageValues {
altText: "Some alt text"
caption: "Some caption"
image: $exampleImageUpload # The Upload object
description: "Some description"
title: "Some title"
}
}
}
}
) {
errors {
id
message
}
confirmation {
message
}
entry {
databaseId
}
}
}