tippyentertainment/pandadoc

Provided by TippyEntertainment

PandaDoc API Integration

Complete integration with PandaDoc Public API for document creation, e-signature workflows, template management, and webhook automation.

Overview

PandaDoc is a document automation platform that enables:

• Document creation from templates or file uploads
• E-signature collection with workflow automation
• Template management and content libraries
• Webhook notifications for document events
• Embedded signing sessions for seamless integration

Authentication

PandaDoc supports two authentication methods:

API Key Authentication (Recommended for Server-Side)

Authorization: API-Key {{api_key}}

How to obtain:

1. Log into PandaDoc account
2. Navigate to Settings → API & Integrations
3. Generate API Key (Sandbox for testing, Production for live)

Sandbox API Key: Use during development/free trial. Sender and recipient emails must be from the same domain.

Production API Key: Use for live integrations with real documents.

OAuth 2.0 Authentication (For Multi-Tenant Apps)

Authorization: Bearer {{oauth_token}}

OAuth Flow:

1. Create an Application in PandaDoc Developer Portal
2. Redirect user to authorization URL with client_id, redirect_uri, and state
3. User authorizes and is redirected back with code
4. Exchange code for access_token and refresh_token
5. Use access_token in Authorization header

Base URL

https://api.pandadoc.com/public/v1

Rate Limits

• Sandbox: 100 requests/minute
• Production: 500 requests/minute

Document Status Values

| Value | Status | Description | |-------|--------|-------------| | 0 | document.draft | Document is in draft state | | 1 | document.sent | Document has been sent | | 2 | document.completed | Document is completed | | 3 | document.uploaded | Document uploaded | | 4 | document.error | Document has an error | | 5 | document.viewed | Document has been viewed | | 6 | document.waiting_approval | Document is waiting for approval | | 7 | document.approved | Document has been approved | | 8 | document.rejected | Document has been rejected | | 9 | document.waiting_pay | Document is waiting for payment | | 10 | document.paid | Document has been paid | | 11 | document.voided | Document has been voided | | 12 | document.declined | Document has been declined | | 13 | document.external_review | Document is under external review |

---

Core Endpoints

Documents

List Documents

Retrieve all documents with filtering options.

Endpoint: GET /documents

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | No | Filter by specific document ID | | template_id | string | No | Filter by parent template ID | | form_id | string | No | Filter by parent form ID | | q | string | No | Search by document name or reference number | | membership_id | string | No | Filter by document owner's membership ID | | contact_id | string | No | Filter by recipient or approver contact ID | | status | integer | No | Filter by document status (see status values) | | status__ne | integer | No | Exclude documents with specified status | | folder_uuid | string | No | Filter by folder UUID | | tag | string | No | Filter by document tag | | metadata | object | No | Filter by metadata key-value pairs | | completed_from | datetime | No | Include documents completed after this date | | completed_to | datetime | No | Include documents completed before this date | | created_from | datetime | No | Include documents created after this date | | created_to | datetime | No | Include documents created before this date | | modified_from | datetime | No | Include documents modified after this date | | modified_to | datetime | No | Include documents modified before this date | | deleted | boolean | No | Include only deleted documents when true | | count | integer | No | Number of results per page (max: 100, default: 50) | | page | integer | No | Page number (starts from 1) | | order_by | string | No | Field to order results by |

---

Create Document from Template

Create a new document from an existing PandaDoc template.

Endpoint: POST /documents

Request Body:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | template_uuid | string | Yes | The ID of the template to use | | name | string | No | Document name | | folder_uuid | string | No | Folder UUID to store document | | owner | object | No | Document owner (email or membership_id) | | recipients | array | Yes | List of recipients | | fields | object | No | Field values to pre-fill | | tokens | array | No | Variables to populate | | metadata | object | No | Custom key-value data | | tags | array | No | Document tags |

Recipient Object:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | email | string | Yes* | Recipient email (or phone) | | phone | string | Yes | Recipient phone (*or email) | | first_name | string | No | Recipient first name | | last_name | string | No | Recipient last name | | role | string | No | Role name from template | | signing_order | integer | No | Order for sequential signing |

---

Send Document

Send a document to recipients for signature.

Endpoint: POST /documents/{id}/send

Request Body:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | message | string | No | Email message to recipients | | subject | string | No | Email subject line | | silent | boolean | No | If true, disables email notifications | | sender | object | No | Sender email or membership_id |

Important Notes:

• Document must be in document.draft status
• After creation, documents remain in document.uploaded status for 3-5 seconds
• Use Document Status endpoint or Webhooks to check when ready

---

Download Document

Download a document as PDF.

Endpoint: GET /documents/{id}/download

---

Download Completed Document

Download the completed (signed) version.

Endpoint: GET /documents/{id}/download-completed

---

Delete Document

Delete a document.

Endpoint: DELETE /documents/{id}

---

Update Document

Update document properties.

Endpoint: PATCH /documents/{id}

---

Templates

List Templates

Retrieve all templates.

Endpoint: GET /templates

---

Create Template from File Upload

Create a new template from a PDF or DOCX file.

Endpoint: POST /templates

---

Get Template Details

Retrieve template information.

Endpoint: GET /templates/{id}

---

Delete Template

Delete a template.

Endpoint: DELETE /templates/{id}

---

Webhooks

List Webhook Subscriptions

Retrieve all webhook subscriptions.

Endpoint: GET /webhook-subscriptions

---

Create Webhook Subscription

Subscribe to document events.

Endpoint: POST /webhook-subscriptions

Request Body:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | Yes | Webhook endpoint URL | | events | array | Yes | Array of event types to subscribe to | | shared_key | string | No | Secret key for webhook signature verification |

Available Events:

| Event | Description | |-------|-------------| | document_created | Document created | | document_state_changed | Document status changed | | document_deleted | Document deleted | | document_updated | Document updated | | document_creation_failed | Document creation failed | | recipient_completed | Recipient completed signing | | document_completed_pdf_ready | Completed PDF available | | quote_updated | Quote updated | | template_created | Template created | | template_updated | Template updated | | template_deleted | Template deleted |

---

Webhook Payload Structure

Headers:

Content-Type: application/json
X-PandaDoc-Signature: sha256=...
X-PandaDoc-Timestamp: 2024-01-15T10:30:00Z

---

Verify Webhook Authenticity

Node.js Example:

const crypto = require('crypto');

function verifyWebhook(payload, signature, sharedKey) {
  const expectedSignature = 'sha256=' + 
    crypto
      .createHmac('sha256', sharedKey)
      .update(JSON.stringify(payload))
      .digest('hex');
  
  return signature === expectedSignature;
}

---

Embedded Signing

Create Document Session for Embedded Sign

Create an embedded signing session for in-app signing.

Endpoint: POST /documents/{id}/session/embedded-sign

Request Body:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | recipient | string | Yes | Recipient email or ID | | redirect_url | string | No | URL to redirect after signing |

---

Document Recipients

Add Document Recipient

Add a recipient to a document.

Endpoint: POST /documents/{id}/recipients

---

Update Document Recipient

Update recipient information.

Endpoint: PATCH /documents/{id}/recipients/{recipient_id}

---

Delete Document Recipient

Remove a recipient from a document.

Endpoint: DELETE /documents/{id}/recipients/{recipient_id}

---

Folders

List Document Folders

Endpoint: GET /documents/folders

---

Create Document Folder

Endpoint: POST /documents/folders

---

Contacts

List Contacts

Endpoint: GET /contacts

---

Create Contact

Endpoint: POST /contacts

---

Step-by-Step Workflows

Workflow 1: Create and Send Document for E-Signature

1. List available templates: GET /templates
2. Create document from template: POST /documents
3. Wait for document to be ready (poll status or use webhook)
4. Send document for signature: POST /documents/{id}/send
5. Monitor via webhook for completion event
6. Download completed document: GET /documents/{id}/download-completed

Workflow 2: Embedded Signing Integration

1. Create document from template: POST /documents
2. Send document silently: POST /documents/{id}/send with silent: true
3. Create embedded signing session: POST /documents/{id}/session/embedded-sign
4. Embed the returned embed_url in an iframe
5. Handle redirect to completion URL
6. Download completed document via API

Workflow 3: Webhook Integration

1. Create webhook subscription: POST /webhook-subscriptions
2. Create server endpoint to receive webhooks
3. Verify webhook signature using shared_key
4. Process webhook payload based on event type

---

Error Handling

Common HTTP Status Codes

| Code | Description | |------|-------------| | 200 | Success | | 201 | Created | | 400 | Bad Request - Invalid parameters | | 401 | Authentication error - Invalid API key | | 403 | Permission error - Insufficient permissions | | 404 | Not found - Resource doesn't exist | | 409 | Conflict - Resource state conflict | | 429 | Too Many Requests - Rate limit exceeded |

---

Best Practices

Performance

1. Use date_created ordering for consistent pagination results
2. Include date ranges when filtering large datasets
3. Limit count to 100 or less per request
4. Use webhooks instead of polling for status changes
5. Cache template IDs to avoid repeated template listing

Document Creation

1. Wait 3-5 seconds after creation before sending
2. Use Document Status endpoint or webhooks to check readiness
3. Pre-fill fields using the fields parameter for better UX
4. Set signing order for sequential signature workflows

Webhooks

1. Always verify signatures using the shared_key
2. Return 200 status quickly - process webhooks asynchronously
3. Handle duplicate events - webhooks may be delivered multiple times
4. Use idempotent processing for reliability

Security

1. Store API keys securely - never expose in client-side code
2. Use OAuth 2.0 for multi-tenant applications
3. Use sandbox keys for development/testing
4. Rotate API keys periodically

---

SDKs and Libraries

Official SDKs

• Python: pip install pandadoc-api-client
• Node.js: npm install @pandadoc/node-client
• Ruby: gem install pandadoc_api

Postman Collection

Import the official PandaDoc Postman collection from the Developer Portal.

---

Support

• Documentation: https://developers.pandadoc.com/
• API Reference: https://developers.pandadoc.com/reference/about
• Support: Contact via Developer Portal
• Changelog: https://developers.pandadoc.com/changelog

---

Parameters

• action: The action to perform (create_document, list_documents, send_document, create_webhook, list_templates, get_document, download_document, create_template, list_contacts, etc.)
• params: JSON string of parameters specific to the action (document_id, template_uuid, recipients, fields, webhook_url, events, etc.)

Returns

• JSON response from PandaDoc API with document IDs, status, download URLs, webhook subscription confirmation, or error messages with details.

Usage Examples

Create Document from Template

action: create_document
params: {
  "template_uuid": "iMymdDd9XFD3HyxP5VD67Q",
  "name": "NDA - Client",
  "recipients": [{"email": "[email protected]", "role": "Signer"}]
}

Send Document

action: send_document
params: {
  "document_id": "xyz789abc",
  "subject": "Please sign",
  "message": "Review and sign the attached document."
}

Create Webhook

action: create_webhook
params: {
  "url": "https://your-server.com/webhooks/pandadoc",
  "events": ["document_state_changed", "recipient_completed"]
}