Documentation
Access Dev CenterSuggest a FeatureContact SupportCreate SandboxRequest a Demo
Start typing to search…

Create and Send Your First Document

Build a working document workflow from start to finish in 15 minutes

In this tutorial, you'll create and send your first document using the PandaDoc API. By the end, you'll have a working document that gets sent to a recipient for signing.

What You'll Build

By the end of this tutorial, you'll have built a complete document workflow that demonstrates the core PandaDoc API capabilities:

Your Document Workflow:

  • Create a contract document from a PDF file using the API
  • Pre-fill document fields with data (like recipient names)
  • Wait for PandaDoc to process the document
  • Send the document to recipients with a custom email message
  • Experience the complete signing process from the recipient's perspective

API Skills You'll Learn:

  • Authenticate with the PandaDoc API using your API key
  • Make POST requests to create documents from files
  • Handle asynchronous document processing (polling for status changes)
  • Send documents with customized email content
  • Understand the document lifecycle from creation to completion

What You'll End Up With:
A working integration that takes a PDF file, turns it into an interactive document with fillable fields and signature areas, and delivers it to recipients via email - all controlled through API calls.

Prerequisites

  • Basic understanding of making HTTP requests
  • A PandaDoc developer account (sign up here)
  • A way to make HTTP requests (curl, Postman, or any programming language)

Two Ways to Create Documents

Before we start building, you need to understand that PandaDoc has two main approaches for creating documents:

1. From PandaDoc Templates

Create documents using PandaDoc Templates you build in the PandaDoc web app. Great for consistent documents like proposals or contracts.

2. From Files

Create documents from PDF, DocX, or RTF files. Great for one-off documents or when you don't have a template. You can either:

  • Upload the file directly with your request
  • Reference a publicly available file URL

In this tutorial, we'll use the file approach because it's simpler to get started.

Making Files Interactive

When you create a document from a file, PandaDoc can automatically convert certain elements into interactive fields that recipients can fill out:

  • Form Fields: PDF form elements created with PDF editing software
  • Field Tags: Special text markers like {{signature:client}} in your document

For this tutorial, we'll use a sample PDF that already has field tags set up.

Step 1: Get Your API Key

First, you need to authenticate with PandaDoc.

  1. Log into your PandaDoc account
  2. Go to Dev Center → Configuration
  3. Create a new Sandbox API key
  4. Copy the key - you'll need it for the next steps

Test your connection:

curl -X GET "https://api.pandadoc.com/public/v1/templates" \
  -H "Authorization: API-Key YOUR_API_KEY_HERE"
  • Replace YOUR_API_KEY_HERE with your actual API key.

If it works, you'll see a JSON response with your templates (might be empty if you haven't created any yet).

Step 2: Create Your First Document

Now let's create a document from a sample PDF file that already has interactive fields set up.

curl -X POST "https://api.pandadoc.com/public/v1/documents" \
  -H "Authorization: API-Key YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Contract",
    "url": "https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FieldTags.pdf",
    "recipients": [
        {
            "email": "[email protected]",
            "first_name": "John",
            "last_name": "Doe",
            "role": "user"
        }
    ],
    "fields": {
        "name": {
            "value": "Mr. John Doe"
        },
        "like": {
            "value": true
        }
    },
    "parse_form_fields": false
  }'
  • Replace YOUR_API_KEY_HERE with your actual API key.
  • Replace [email protected] with the email address you want to use.

Note: For security reasons, PandaDoc sandbox keys can only send email notifications to an address that has the same domain as your PandaDoc account.

What just happened:

  • You created a document using a sample PDF
  • Added a recipient (John Doe) with your email
  • Pre-filled the "name" field with "John Doe"
  • Set parse_form_fields: false because we're using field tags, not PDF form fields

You'll get a response like:

{
  "id": "BhVzRcxH9Z2LgfPPGXFUqo",
  "name": "My First Contract",
  "status": "document.uploaded",
  "date_created": "2025-08-15T10:30:00.000Z"
}

Save that document ID! You'll need it for next steps.

Step 3: Wait for the Document to Process

When you create a document from a file, PandaDoc needs time to process it. The document starts with status document.uploaded and changes to document.draft when it's ready to send.

Let's check the status of the document:

curl -X GET "https://api.pandadoc.com/public/v1/documents/YOUR_DOCUMENT_ID" \
  -H "Authorization: API-Key YOUR_API_KEY_HERE"
  • Replace YOUR_DOCUMENT_ID with the ID from step 2.
  • Replace YOUR_API_KEY_HERE with your actual API key.

Keep checking every few seconds until you see:

{
  "id": "YOUR_DOCUMENT_ID",
  "name": "My First Contract",
  "status": "document.draft"
}

Tip: It usually takes 2-5 seconds for a simple PDF to process.

Step 4: Send the Document

Once the status is document.draft, you can send it!

curl -X POST "https://api.pandadoc.com/public/v1/documents/YOUR_DOCUMENT_ID/send" \
  -H "Authorization: API-Key YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Please review and sign this contract",
    "message": "Hello Mr. John Doe! Please review and sign this contract. Thanks!",
    "silent": false
  }'
  • Replace YOUR_DOCUMENT_ID with the ID from step 2.
  • Replace YOUR_API_KEY_HERE with your actual API key.

If successful, you'll get a 204 No Content response, which means "success, no data to return."

🎉 Success! Check Your Email

Within a few minutes (usually within few seconds), you should receive an email with your document! Click the link to open the document in PandaDoc to see:

  1. Your document with the name field pre-filled with "John Doe"
  2. Interactive fields you can click on to fill out
  3. A signature area where you can sign

Try filling out and signing the document to complete the full workflow.

What You Just Learned

Congratulations! You've successfully:

  • ✅ Created a document from a PDF file using the API
  • ✅ Verified the document is ready
  • ✅ Sent the document to a recipient
  • ✅ Experienced the full document lifecycle from creation to signing

Key Concepts to Remember

  1. Document creation is asynchronous - You must wait for document.draft status before sending
  2. Two main creation methods - From PandaDoc Templates or from files (PDF/DocX/RTF)
  3. Recipients need roles - Each recipient gets a role like "client" or "manager"
  4. Fields are role-based - Pre-fill fields and assign them to specific recipient roles

What's Next?

Now that you understand the basics, you can explore more features:

  • Create Documents from PandaDoc Templates
  • Upload your own PDF files instead of using sample files
  • Add multiple recipients with different roles
  • Use advanced field types and validation
  • Use form fields instead of field tags

Troubleshooting

Document stuck indocument.uploaded status?

  • Wait longer - complex PDFs can take up more time to process
  • Check if your PDF has any errors or is password-protected

Not receiving emails?

  • Check your spam folder
  • Make sure you used your real email address in the recipient field
  • Verify the document was actually sent (status should be document.sent)

Getting authentication errors?

  • Double-check your API key is correct
  • Verify the Authorization: API-Key YOUR_KEY header format

Ready to build something more complex? Check out our API Reference for full set of APIs.

Updated 3 days ago