Signature Envelopes

A Signature Envelope coordinates multiple signers on one PDF when a Signature Template assigns fields to more than one signer role—typically employee and company. Each signer receives a unique link at /sign/{access_token}. Signatures apply in Parallel routing: all parties may sign in any order. When every signer completes their fields, the envelope becomes Fully Executed and stores the Final Signed Document.

Envelopes power dual-signature employment contracts, offer letters requiring HR countersignature, and onboarding documents where both the new hire and onboarding owner must sign the same PDF.

Help URL: smoothhiring.com/help/hrms/documents-compliance/signature-envelopes

Table of Contents

1. Overview
2. Who this is for
3. When Smooth HR creates an envelope
4. Desk paths
5. Step-by-step: template setup for multi-signer
6. Step-by-step: onboarding envelope flow
7. Step-by-step: monitor and complete
8. Parallel signing mechanics
9. Status lifecycle
10. Key fields
11. Signature Envelope Signer child records
12. Desk actions
13. Tips
14. Troubleshooting
15. Related guides

Overview

Important limitation: Parallel envelopes are not supported for AcroForm (native fillable) PDFs. The sign page displays an error if the template is flagged as AcroForm. Use a flat PDF or a single-signer Signature Request instead.

Who this is for

When Smooth HR creates an envelope

Smooth HR creates a Signature Envelope automatically when:

1. A Signature Template PDF has fields tagged with two or more distinct signer roles (for example employee and company), and
2. A send is triggered from Employee Onboarding (portal Sign document) or another flow that calls the parallel-envelope API.

It does not create an envelope when:

• Only one signer role exists on the template → Signature Request instead.
• Template is AcroForm → error thrown; parallel not available.
• Template has multi-role fields but fewer than two roles resolved → validation error.

The Routing field supports Parallel (implemented) and Sequential (reserved for future ordering). Onboarding envelopes always use Parallel.

Desk paths

Step-by-step: template setup for multi-signer

Step 1: Upload PDF

1. Open /app/signature-template/new-signature-template.
2. Set Template Type = PDF Upload; attach Document File (PDF).
3. Use a non-AcroForm, non-password-protected PDF for best results.

Step 2: Place fields with roles

1. In the placement editor, add fields (Signature, Date, Initials, Text, Number).
2. For each field, set Signer Role:
   • employee → new hire / employee party
   • company → HR or hiring manager party
3. Ensure at least one field exists for each role that must sign.

Step 3: Configure settings

Save the template with Is Active checked.

Step-by-step: onboarding envelope flow

1. Employee Onboarding Template → Required Documents row links your multi-role Signature Template.
2. HR creates and submits Employee Onboarding; employee linked with valid email.
3. Employee opens /app/onboarding-portal → Sign document on the row.
4. API _create_onboarding_signature_envelope:
   • Creates Signature Envelope with reference to onboarding + document row.
   • Creates Signature Envelope Signer for each role:
     • employee → Employee name and email
     • company → Onboarding owner name and email
   • Sets status Sent, computes Expires On from template.
   • Stores envelope name on onboarding document row (signature_envelope).
5. Employee redirected to /sign/{token} for their fields.
6. Company signer receives separate link (email when notifications enabled; HR can copy from Signing links).
7. When all signers complete → Fully Executed → PDF syncs to onboarding row attachment.

Step-by-step: monitor and complete

1. Open /app/signature-envelope/{name}.
2. Check Status:
   • Sent — no signer has finished yet
   • Partially Signed — at least one signer done, waiting on others
   • Fully Executed — all complete; download Final Signed Document
3. Click Signing links to see each signer's role, status, Open signing page, and Copy link.
4. Review Audit Trail on envelope for "Envelope sent", "Signer completed", "Fully executed".
5. If onboarding-linked and signing must restart, use Re-request signing (cancels current envelope, creates new round—previous PDFs remain on cancelled record).

Parallel signing mechanics

Unlike sequential tools where signer B waits for signer A, Parallel routing allows any order:

1. Original Document — copy of template PDF at envelope creation.
2. Signer A completes — system builds PDF with A's fields → saves as Staged Document.
3. Signer B completes — overlays B's fields onto current staged PDF → updates staged.
4. All done — final staged PDF copied to Final Signed Document; Final Document Hash (SHA-256) stored.

Each signer only interacts with fields matching their signer_role. The sign page filters signature_fields accordingly.

If a signer opens their link after already signing, they see a message that they have signed and may be waiting on others (envelope_waiting_others).

Status lifecycle

Draft ──send──► Sent ──first signature──► Partially Signed ──all signers──► Fully Executed
                  │                              │
                  ├──cancel──► Cancelled         └──timeout──► Expired
                  └──all sign at once ──► Fully Executed (skip Partially Signed)

Key fields

Signature Envelope Signer child records

Each signer is a separate Signature Envelope Signer record (naming: HR-SIGS-.#####):

Guest sign page resolves token against Signature Envelope Signer first, then falls back to Signature Request.

Desk actions

Tips

• Resolve company signer early. For onboarding, company party uses onboarding document owner—ensure owner has correct email.
• Send company link proactively. Onboarding may skip email notification (skip_notification=1); HR should copy company link from Signing links.
• Do not use AcroForm PDFs for dual-signature contracts.
• Watch Partially Signed. Nudge the pending party; offer links expire per template Expiry Days.
• Final PDF on envelope is source of truth after Fully Executed—not individual signer staging files.
• Re-request signing preserves audit history on cancelled envelope—use when signer made error or wrong party signed.

Troubleshooting

Related guides

• Documents & Compliance Overview
• Signature Templates
• Signature Requests
• Signing Portal (/sign)
• Onboarding Templates
• Employee Onboarding

Last updated: May 2026