Understanding the Document Workflow Lifecycle

Overview

The PandaDoc API covers every stage of a document's life -- creating it, preparing it for recipients, delivering it for signing, and retrieving the finished result. At each stage, you can choose between a fully API-driven approach or embedding PandaDoc experiences directly into your platform so users never have to leave your app.

Understanding how these stages and capabilities connect helps you design integrations that use the right approach at the right time.

The diagram below shows the full lifecycle:

Stages of the lifecycle

1. Create

Every workflow starts by creating a document. The API supports three approaches, each suited to different scenarios:

Method	Best for	Guide
From a PandaDoc template	Standardized documents with reusable structure, fields, and branding	Create from Template
From a file upload	Existing PDFs, DocX, or RTF files that need signatures	Create from File
From a public URL	PDFs already hosted on a CDN or cloud storage	Create from Public URL

All three methods return a document ID that connects every subsequent operation. See Understanding Document Creation Methods for a deeper comparison.

At creation time you can also customize the document with pre-filled fields, pricing tables, images, content placeholders, and more. See the Manage Document Content guides for what's available.

2. Wait for draft

Document creation is asynchronous. The document must reach document.draft status before it can be sent. See Understanding Asynchronous Document Creation for details.

3. Prepare documents with embedded editing and sending

Instead of building documents entirely through API calls, you can embed PandaDoc experiences directly in your app so your users prepare documents without leaving your platform.

Embedded editing

Embed the full PandaDoc editor so your users (Revenue Ops, HR Ops) can create and edit templates and documents with all fields, blocks, and signers -- directly within your app. This is useful when document content isn't fully automatable and needs human input. See Embedded Editing.

Embedded sending

Embed a simplified editor so your users (Sales Reps, Recruiters) can upload a PDF, drag and drop signature and form fields onto it, assign recipients, and send for eSignature -- all in a single flow. This is ideal when documents originate outside PandaDoc but need interactive fields before sending. See Embedded Sending.

	Embedded Editing	Embedded Sending
What's embedded	Full PandaDoc editor	Simplified editor for field placement on a PDF
Who uses it	Revenue Ops, HR Ops	Sales Reps, Recruiters
What can the user do?	Create and edit templates and documents with all fields, blocks, and signers	Upload a PDF, drag and drop fields, assign recipients, and send for eSignature
End user license required?	No*	No*

*The end user doesn't need a PandaDoc license, but your organization must be a PandaDoc client to implement embedding.

Try it yourself: Embedded Editing/Signing Playground (no account needed).

4. Send

Sending transitions the document to document.sent, which locks the draft and enables recipient interactions. You have two delivery modes:

Email notification (silent: false) -- recipients receive an email with a link to the document
Silent (silent: true) -- no email is sent; use this when you'll deliver the document through embedded signing or a shared link

Even if you plan to embed the document, the send step is required to advance the status. See How to Send a Document via API.

5. Deliver for signing

Once sent, you choose how recipients interact with the document:

Delivery method	Description	Guide
Email link	Recipients receive a link via the send step above	Send Document
Embedded signing	Document is displayed inside your application so end users (clients, candidates, employees) sign without being redirected to PandaDoc	Embedded Signing
Shared link	Generate a session URL to share directly (e.g., via SMS, chat, or your own UI)	Create Document Session

For embedded signing and shared links, you generate a session via POST /documents/{id}/session, which returns a time-limited URL. See Shared Links vs Embedded Sessions for a comparison.

All three embedded experiences (editing, sending, and signing) can be combined in a single platform. For example, Revenue Ops build templates via embedded editing, Sales Reps prepare PDFs via embedded sending, and Buyers sign via embedded signing -- all without leaving your app.

6. Track progress

As recipients view and interact with the document, the status progresses through document.viewed, document.waiting_approval, and eventually document.completed. You can track these transitions via:

Webhooks -- receive real-time document_state_changed events. See Webhook Setup.
Polling -- check the Document Status endpoint periodically.

7. Download

After all required actions are complete, retrieve the finished document via GET /documents/{id}/download. See How to Download a Completed Document.

Key considerations

Every document goes through the same status progression regardless of creation method or delivery approach. The stages above apply universally.
The send step is always required to enable recipient interactions, even when using embedded signing with silent: true.
Webhooks are the recommended integration pattern for production workflows. Polling works for prototyping but doesn't scale as well.
Session URLs are temporary -- the default lifetime is 3600 seconds. Generate a new session if the previous one expires.

Related concepts

Understanding Document Creation Methods
Understanding Asynchronous Document Creation
Shared Links vs Embedded Sessions
Embedded Editing -- embed the full PandaDoc editor
Embedded Sending -- embed field placement and sending for PDFs
Embedded Signing -- embed the signing experience