🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms DocuSeal Premium Add-on Setup Guide

Updated 8 min read Gravity Forms Integrations A–Z
On this page
  1. Video walkthrough
  2. What you need
  3. DocuSeal cloud or self-hosted
  4. Get your DocuSeal API key
  5. The settings page
  6. Create a feed
  7. Template and email
  8. Map the signer and prefill fields
  9. When to send
  10. What is written to the entry
  11. Privacy and safety
  12. Frequently asked questions
  13. Troubleshooting

Video walkthrough

Gravity Forms DocuSeal Add-On Setup Guide: API Key, Base URL and Feed (WordPress Side)
Video setup guide: Gravity Forms DocuSeal Watch on YouTube

The Gravity Forms DocuSeal Premium Add-on connects your Gravity Forms to your own DocuSeal account. When someone submits a form, the add-on creates a signing submission from one of your DocuSeal templates and sends the signer a signature request by email, mapping the signer’s details and prefilling the template fields you choose. Everything runs through your own DocuSeal API key, so your documents stay in your account and nothing passes through GravityExtra.

The add-on works with both DocuSeal cloud and a self-hosted DocuSeal server: leave the base URL blank to use the cloud, or point it at your own installation. A call that fails at DocuSeal never stops the form either, so a submission is always saved as a Gravity Forms entry even on the rare day the API is slow, and a note on the entry tells you exactly what happened.

What you need

  • WordPress with Gravity Forms 2.9 or newer.
  • PHP 7.4 or newer.
  • An active license key for this add-on.
  • A DocuSeal account (cloud or self-hosted) with at least one template and an API key.

If Gravity Forms is missing or older than 2.9, the add-on shows a notice in the WordPress admin and does nothing else, so a form is never left half connected.

DocuSeal cloud or self-hosted

DocuSeal is an open-source document-signing tool. You can use the hosted service at DocuSeal cloud, or run DocuSeal on your own server. This add-on supports both. If you use the cloud, you leave the base URL blank and the add-on talks to the standard cloud API. If you self-host, you enter your DocuSeal address (for example https://sign.your-company.example) as the base URL, and the add-on talks to the API on your own server instead. Either way, the add-on only ever contacts the host you configured.

Get your DocuSeal API key

Sign in to DocuSeal and open Settings, then the API section. Copy your API key. The key is what lets this add-on create submissions in your account on your behalf, so treat it like a password: anyone who has it can read and change your documents. You will paste it into the add-on settings in a moment, where it is stored encrypted and is never shown again.

While you are in DocuSeal, it is worth noting the template you want to send and the names of its fields (for example Full Name or Company). The add-on reads your templates for you so you can pick one from a list, and the field names are what you prefill from your form.

The settings page

Install and activate the add-on like any plugin, after Gravity Forms. Then open Forms → Settings → DocuSeal. This page holds your license key, your DocuSeal API key and the optional base URL, and it confirms the connection.

The DocuSeal settings page in Gravity Forms: the license key box, the DocuSeal API key field, the self-hosted base URL field, and a connection status that shows how many templates were found
The settings page: your license key, your DocuSeal API key and the optional self-hosted base URL, with the connection status.

Paste the API key from DocuSeal and, if you self-host, enter your base URL; leave the base URL blank for the cloud. Save. The key is stored encrypted at rest, so the plain value is never left sitting in the database. After it is saved the field is shown blank with a note that a key is stored; leave it blank to keep it, or type a new key to replace it. The connection line then reads your account and tells you how many templates it found, which is the quickest way to confirm the key and base URL work before you build a feed.

Create a feed

A feed is one rule that says “when this form is submitted, start a document in DocuSeal like this.” Open a form, go to Settings → DocuSeal and add a feed. You can create several feeds on one form, each with its own template and its own conditions.

The DocuSeal feed list for a Gravity Forms form showing two feeds with the template each one creates a submission from
The feed list: each feed shows the template it creates a signing submission from.

Template and email

At the top of the feed you pick the template from a list read straight from your account, so you never have to copy an id by hand. (If the templates cannot be read yet — for example before the API key is saved — a small text box appears instead where you can type the numeric template id.) The Email the signer option, on by default, tells DocuSeal to email the signer a link to sign. Untick it to create the submission without sending the email, for example when you send the link yourself.

Map the signer and prefill fields

In the mapping section you connect your form fields to the signer and the document. The signer email is required, because that is who receives the signature request. The signer name is optional, and the signer role lets you name the role on a multi-signer template (for example First Party); leave it blank for a single-signer template. Under prefill template fields you add a row for each DocuSeal field you want filled in before the signer opens the document, choosing a form field or typing text with merge tags for the value.

The DocuSeal feed editor in Gravity Forms with the template chooser, the email-the-signer option, the signer email and name mapping, the signer role, prefill template field rows and the conditional logic section
The feed editor: template, signer mapping, prefilled fields and conditional logic in one place.

Signature and initials fields are deliberately left for the signer — the add-on never fills those. Everything you do prefill is cleaned of tags and control characters before it is sent, and a field name that does not exist on the template is simply ignored by DocuSeal, so a typo never breaks the submission.

When to send

Turn on conditional logic to send a signature request only for some submissions. A feed with a rule such as “Send a signature request if Document is NDA” runs only when that is true, and a different feed on the same form can start a different document from a different template. A feed with no conditions runs on every submission.

What is written to the entry

Every submission is saved as a normal Gravity Forms entry, and the add-on adds a note to it. On success the note reads something like “DocuSeal: signature request created for a***@example (submission #501)” with the email masked. If DocuSeal returns an error the note records the reason instead, the entry is still saved, and the call is not retried automatically, so you can see at a glance which submissions started a document and which did not.

A Gravity Forms entry detail page showing the submitted field values and the DocuSeal note confirming the signature request was created, with the signer email masked
The entry: the submitted values and the DocuSeal note with the masked signer email and the submission number.

Privacy and safety

The add-on only ever contacts the DocuSeal host you configured — the cloud API, or your own server — and it sends only what you mapped. Your API key is encrypted before it is stored, it is never written to an entry or a log, and it is never shown again in the settings. Because a failed call never blocks a submission, turning the add-on off or letting a key expire can never stop your forms from working — the worst case is that a document is not started, and the entry note tells you so.

Frequently asked questions

Does it work with a self-hosted DocuSeal? Yes. Enter your DocuSeal address as the base URL on the settings page; the add-on then talks to the API on your own server. Leave the base URL blank to use DocuSeal cloud.

How do I get an API key and base URL? The API key comes from DocuSeal under Settings and API. The base URL is only needed when you self-host — it is the address of your own DocuSeal installation. Cloud users leave it blank.

Can one form send different templates? Yes. Add several feeds to the form, give each a template and its own conditional logic, and each runs on its own.

Which template fields can I prefill? Any text-style field on the template, by its exact name. Signature, initials and similar fields are completed by the signer and are never prefilled by the add-on.

What does the signer receive? When the email option is on, DocuSeal emails the signer a link to open and sign the document, with any fields you prefilled already filled in. When the option is off, the submission is still created and you can share the signing link yourself.

What happens if DocuSeal is down? The entry is still saved and a note explains the error. The call is not retried automatically; you can resubmit or start the document in DocuSeal by hand.

Troubleshooting

If the connection line says it is not connected, the usual cause is a mistyped or revoked API key, or a base URL that points to the wrong place. Check the key in DocuSeal, confirm the base URL (blank for cloud, or your exact server address for self-hosted), paste a fresh key if needed and save, then watch the template count appear. If the template chooser shows a plain id box instead of a list in a feed, the key is either missing or cannot reach DocuSeal yet; save a working key and base URL on the settings page first, then reopen the feed.

If a submission did not start a document, open the entry and read its note. The note names the reason — an invalid key, a missing template, a validation error on a field, or a rate limit — so you can correct the cause and, if you wish, resubmit or create the submission in DocuSeal by hand. Because the call is never retried automatically, the entry note is always the single source of truth for what happened, and no signer is ever sent the same document twice for the same entry and feed thanks to a one-time done marker the add-on records.

If a prefilled value is not appearing on the document, check that the template field name in the feed exactly matches the name shown in DocuSeal, including capitalisation and spaces. A field name that does not exist on the template is ignored by DocuSeal rather than causing an error, so a small typo shows up as a blank field instead of a failed submission.

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr