DocuSeal icon

DocuSeal

Create documents, manage templates, and handle submissions with DocuSeal

Actions9

Overview

The DocuSeal Submission: Create operation allows you to programmatically create a new document submission in DocuSeal. This is useful for automating the process of sending documents for e-signature or form completion, pre-filling fields, specifying signers (submitters), and customizing preferences and notifications. Common scenarios include onboarding workflows, contract management, HR document processing, and any use case where documents need to be filled out and signed by multiple parties.

Example Use Cases:

  • Automatically send an employment contract to a new hire with their details pre-filled.
  • Initiate a sales agreement workflow where both client and internal staff must sign in sequence.
  • Collect signatures from multiple stakeholders on a compliance form, with custom instructions and redirect URLs.

Properties

Below are the supported input properties for the "Submission: Create" operation:

Display Name Type Description
Environment options Choose between production and test environment.
Template ID number ID of the template to create a submission for. Required. References the specific document template in DocuSeal.
Submitters json List of people who will sign or fill the document. Each submitter must have an email; can also include name, role, phone, external_id, values, metadata, and send_email. Example:
[{"email": "john@example.com", "name": "John Smith", "role": "Client"}]
Fields json Pre-filled values for form fields in the document. Keys are field names from the template; values are what you want to pre-fill. Supports simple values or complex objects for formatting. Example:
{"First Name": "John", "Amount": {"value": 100, "preferences": {"font_size": 12}}}
Preferences json Visual and behavioral preferences for the document (e.g., font size, color, theme, page size, orientation, margin). Example:
{"font_size": 12, "color": "blue", "theme": "light"}
Additional Options collection Optional advanced settings:
  • Completed Redirect URL (string): URL to redirect after completion
  • External ID (string): Custom identifier for tracking
  • Message (string): Custom message for submitters
  • Metadata (json): Additional custom data
  • Send Email (boolean): Whether to send email notifications
  • Send SMS (boolean): Whether to send SMS notifications
  • Submitter Types (json): Define custom types for submitters
Completed Redirect URL string URL to redirect submitters to after they complete the submission.
Expire At string Expiration date/time in format YYYY-MM-DD HH:MM:SS UTC. After this time, the submission is unavailable.
Message json Custom email message for all submitters. Format: {"subject": "...", "body": "..."}. Can include variables like {{template.name}}, {{submitter.link}}.
Send Email boolean Whether to send email notifications to submitters. Default: true.
Send SMS boolean Whether to send SMS notifications to submitters. Requires phone numbers and SMS capability. Default: false.
Order options Document signing order: "Preserved (Sequential)" or "Random (All at Once)".

Output

The node returns a JSON object representing the created submission. The structure typically includes:

{
  "id": 12345,
  "template_id": 6789,
  "status": "pending",
  "submitters": [
    {
      "id": 1,
      "email": "john@example.com",
      "role": "Client",
      // ...other submitter fields
    }
    // ...more submitters
  ],
  "values": {
    "First Name": "John",
    "Last Name": "Doe"
    // ...other pre-filled fields
  },
  "preferences": {
    "font_size": 12,
    "color": "blue"
    // ...other preferences
  },
  "completed_redirect_url": "https://example.com/thank-you",
  "expire_at": "2025-04-14 23:59:59 UTC",
  "message": {
    "subject": "Please sign",
    "body": "Hello, please review and sign."
  },
  "order": "preserved",
  "external_id": "custom-tracking-id",
  "metadata": {},
  "submitter_types": {},
  "send_email": true,
  "send_sms": false,
  // ...other fields as returned by DocuSeal API
}
  • If an error occurs and "Continue On Fail" is enabled, the output will contain an error field with the error message.

Dependencies

  • DocuSeal API: Requires access to the DocuSeal service.
  • API Key: You must configure DocuSeal API credentials in n8n.
  • n8n Configuration: No special environment variables required beyond standard credential setup.

Troubleshooting

Common Issues

  • Missing or Invalid Submitters: Each submitter must be an object with non-empty email and role string properties. If not, the node throws an error indicating which submitter is invalid.
  • Malformed JSON: If the Submitters, Fields, Preferences, or other JSON fields are not valid JSON, the node will throw a parsing error.
  • Required Fields Missing: If required fields like templateId or Submitters are missing, the node will fail.
  • DocuSeal API Errors: Any errors from the DocuSeal API (e.g., invalid template ID, permission issues) will be surfaced as node errors.

Error Messages

  • "Submitters data is required for creating a submission": Ensure the Submitters property is provided and correctly formatted.
  • "Invalid submitter at index X: Each submitter must be an object with non-empty 'email' and 'role' string properties.": Check that each submitter object has both email and role fields filled.
  • "Error creating submission: ...": Indicates an error response from the DocuSeal API. Review the error message for specifics (e.g., invalid template ID, authentication failure).

Links and References

Discussion