submitting-forms.md

Submitting Forms

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.

Supported Field Value input types

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	name type size tmp_name
listValues ( [ obj ] )	ListField	rowValues ( [ String ] )
nameValues ( obj )	NameField	first last midele prefix suffix
postImageValues ( obj ) 2	PostImageField	altText caption description image title
value ( string )	CaptchaField 3 ConsentField DateField HiddenField NumberField PhoneField PostContentField PostExcerptField PostTitleField QuizField 4 RadioField 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.
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.

Example Mutation

{
  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: "[email protected]"
            confirmationValue: "[email protected]" # 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
    }
  ) {
    errors {
      id # The field that failed validation.
      message
    }
    entry {
      # See docs on querying Entries.
      id
      ... on GfSubmittedEntry {
        databaseId
      }
      ... on GfDraftEntry {
        resumeToken
      }
    }
  }
}

Validation and Submission

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 , and the entry in the response will be the newly updated entry object. Depending on whether saveAsDraft is true , you will either get the new entryId or the resumeToken , with the other value set to null .

If the field is NOT updated successfully, such as when a field validation error occurs, the entry object 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."
  }
]

Captcha Validation

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:

submitGfForm( $token: String )
  input: {
    formId: 50
    fieldValues: [
      # other form fields would go here.
      {
        # Captcha Field
        id: 1
        value: $token # The google reCAPTCHA response token.
      }
    }
  }
) {
  errors {
    id
    message
  }
  entry {
    databaseId
  }
}