tippyentertainment/panda-doc-upload-docs

PandaDoc Skill

You use this skill whenever the user wants to generate or manage documents, proposals, quotes, contracts, or e‑signatures using PandaDoc workspaces, templates, or PDFs via the PandaDoc Public API.

Your goals:

• Create documents from PandaDoc templates or uploaded files.
• Send documents for e‑signature and check their status.
• Retrieve links, audit trails, and recipient info the user can act on.
• Help the user wire this into their own automations and webhooks.

The user will usually be a developer or power user, comfortable with JSON and APIs.

---

1. Configuration and assumptions

Before using this skill, assume the following configuration is already set up by the platform, not by you:

• A PandaDoc API key (sandbox or production) has been generated in the Developer Dashboard and securely stored as PANDADOC_API_KEY.
• The key has access to the correct workspace and templates.
• For server‑side flows, the platform can make HTTPS requests with arbitrary headers and JSON.
• Optional: a public HTTPS endpoint exists for receiving PandaDoc webhooks.

You never print or request the raw API key.
You only describe:

• Which HTTP method and URL to call.
• Which headers and JSON body to send.
• How to parse the response.

Default base URL:
https://api.pandadoc.com/public/v1

All requests must include (platform responsibility):

• Header Authorization: Bearer {PANDADOC_API_KEY}.
• Header Content-Type: application/json for JSON requests.

If the user mentions OAuth2, you may refer them to PandaDoc OAuth docs, but prefer API key for server‑to‑server integrations.

---

2. When to use this skill

Use this skill when the user asks for things like:

• "Create a proposal from a PandaDoc template and send it for signature."
• "Generate a contract as PDF for a specific customer and return a link."
• "List my recent PandaDoc documents and their statuses."
• "Hook [REDACTED] into PandaDoc so I know when a document is completed."
• "Fill a PandaDoc template with variables from my CRM data."

Do not use this skill when:

• The user only wants high‑level product comparison or pricing.
• The user asks about editing template design UI inside PandaDoc (just describe, don't call APIs).

---

3. Core flows to implement

Below are the canonical workflows. Adapt IDs/fields to the user's context.

3.1 Create a document from a template

Use when the user has a PandaDoc template and wants to generate a document with variables (tokens), recipients, and send options.

Endpoint

• Method: POST
• URL: /documents

Required headers

• Authorization: Bearer {PANDADOC_API_KEY}
• Content-Type: application/json

Typical request body (template source)

{
  "name": "Sales Proposal for {{customer_name}}",
  "template_uuid": "TEMPLATE_UUID_HERE",
  "recipients": [
    {
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "role": "Client"
    }
  ],
  "tokens": [
    { "name": "customer_name", "value": "Acme Corp" },
    { "name": "proposal_amount", "value": "25000" }
  ],
  "metadata": {
    "external_id": "crm-opportunity-12345",
    "source": "taskingtech-bot"
  },
  "send": true
}

Response (201 Created)

{
  "id": "DOCUMENT_UUID",
  "name": "Sales Proposal for Acme Corp",
  "status": "document.draft",
  "recipients": [...],
  "tokens": [...],
  "date_created": "2025-01-15T10:30:00Z",
  "date_modified": "2025-01-15T10:30:00Z"
}

Key fields

• template_uuid: The UUID of the PandaDoc template to use.
• recipients: Array of signer objects with email, name, and role.
• tokens: Array of variable name/value pairs to fill template [REDACTED]s.
• metadata: Optional external tracking ID.
• send: If true, sends immediately after creation.

---

3.2 Upload a PDF and create a document

Use when the user has a PDF file (e.g., generated by [REDACTED]) and wants to upload it to PandaDoc for e‑signature.

Endpoint

• Method: POST
• URL: /documents

Required headers

• Authorization: Bearer {PANDADOC_API_KEY}
• Content-Type: multipart/form-data`

Request body (multipart form)

• file: The PDF file binary.
• name: Document name (optional, defaults to filename).
• recipients[]: JSON array of recipient objects.
• metadata: JSON object for external tracking.

Example using http_post

{
  "url": "https://api.pandadoc.com/public/v1/documents",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer {PANDADOC_API_KEY}"
  },
  "body": {
    "file": "[PDF_BINARY_DATA]",
    "name": "Contract for Acme Corp",
    "recipients": [
      {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Smith",
        "role": "Client"
      }
    ]
  }
}

Response (201 Created)

Same structure as template-based creation.

---

3.3 List documents

Use when the user wants to see all documents in their workspace.

Endpoint

• Method: GET
• URL: /documents

Query parameters (optional)

• status: Filter by status (e.g., document.draft, document.sent, document.completed).
• q: Search query (document name or ID).
• count: Number of results (default 50, max 100).
• page: Page number for pagination.

Example request

{
  "url": "https://api.pandadoc.com/public/v1/documents?status=document.sent&count=20",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer {PANDADOC_API_KEY}"
  }
}

Response (200 OK)

{
  "count": 20,
  "next": "https://api.pandadoc.com/public/v1/documents?page=2",
  "previous": null,
  "results": [
    {
      "id": "DOCUMENT_UUID",
      "name": "Sales Proposal for Acme Corp",
      "status": "document.sent",
      "date_created": "2025-01-15T10:30:00Z",
      "date_modified": "2025-01-15T10:35:00Z"
    },
    ...
  ]
}

---

3.4 Get document details

Use when the user wants full details of a specific document.

Endpoint

• Method: GET
• URL: /documents/{DOCUMENT_ID}

Response (200 OK)

{
  "id": "DOCUMENT_UUID",
  "name": "Sales Proposal for Acme Corp",
  "status": "document.completed",
  "recipients": [
    {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Smith",
      "role": "Client",
      "status": "completed",
      "date_completed": "2025-01-16T14:22:00Z"
    }
  ],
  "tokens": [...],
  "metadata": {...},
  "date_created": "2025-01-15T10:30:00Z",
  "date_modified": "2025-01-16T14:22:00Z"
}

---

3.5 Send a document for signature

Use when a document was created in draft mode and the user wants to send it now.

Endpoint

• Method: POST
• URL: /documents/{DOCUMENT_ID}/send

Request body

{
  "subject": "Please sign this proposal",
  "message": "Hi Jane,\n\nPlease review and sign the attached proposal.\n\nBest,\nRyan",
  "silent": false
}

Response (200 OK)

{
  "id": "DOCUMENT_UUID",
  "status": "document.sent",
  "message": "Document sent successfully"
}

---

3.6 Get document link (shareable URL)

Use when the user wants a direct link to view or download the document.

Endpoint

• Method: POST
• URL: /documents/{DOCUMENT_ID}/session

Request body

{
  "recipient": "[email protected]",
  "lifetime": 3600
}

Response (201 Created)

{
  "id": "SESSION_UUID",
  "document_id": "DOCUMENT_UUID",
  "url": "https://app.pandadoc.com/s/SESSION_UUID",
  "expires_at": "2025-01-15T11:30:00Z"
}

---

3.7 Download document as PDF

Use when the user wants the signed document as a PDF file.

Endpoint

• Method: GET
• URL: /documents/{DOCUMENT_ID}/download/pdf

Response

Binary PDF file with Content-Type: application/pdf.

---

3.8 Delete a document

Use when the user wants to remove a document from PandaDoc.

Endpoint

• Method: DELETE
• URL: /documents/{DOCUMENT_ID}

Response (204 No Content)

Empty body on success.

---

4. Webhooks

PandaDoc can send webhook events to a public HTTPS endpoint when document status changes.

4.1 Webhook events

| Event | Description | |-------|-------------| | document_completed | All recipients have signed | | document_viewed | A recipient opened the document | | document_sent | Document was sent for signature | | document_declined | A recipient declined to sign | | recipient_completed | A specific recipient signed |

4.2 Webhook payload structure

{
  "event": "document_completed",
  "data": {
    "id": "DOCUMENT_UUID",
    "name": "Sales Proposal for Acme Corp",
    "status": "document.completed",
    "date_created": "2025-01-15T10:30:00Z",
    "date_modified": "2025-01-16T14:22:00Z",
    "recipients": [...]
  },
  "timestamp": "2025-01-16T14:22:00Z"
}

4.3 Setting up webhooks

The user must:

1. Create a public HTTPS endpoint (e.g., https://yourserver.com/webhooks/pandadoc).
2. In PandaDoc Developer Dashboard, add the webhook URL.
3. Select which events to subscribe to.
4. Verify the endpoint receives POST requests with JSON body.

[REDACTED] can help by:

• Creating an endpoint handler in the user's automation.
• Using http_post to send data to other services when webhooks arrive.

---

5. Error handling

PandaDoc API returns standard HTTP status codes:

| Code | Meaning | |------|---------| | 200 | Success | | 201 | Created | | 204 | No Content (successful delete) | | 400 | Bad Request (invalid JSON, missing fields) | | 401 | Unauthorized (invalid or missing API key) | | 403 | Forbidden (insufficient permissions) | | 404 | Not Found (document or template doesn't exist) | | 429 | Rate Limited (too many requests) | | 500 | PandaDoc Server Error |

Error response body

{
  "detail": "Invalid template_uuid provided"
}

Always check the detail field for error messages.

---

6. Common patterns

6.1 Create and send in one call

Set send: true in the create request body to immediately send after creation.

6.2 Draft, review, then send

1. Create with send: false.
2. Review the document in PandaDoc UI.
3. Use /documents/{id}/send when ready.

6.3 Track external IDs

Use metadata.external_id to link PandaDoc documents to CRM records, deals, or tasks.

6.4 Polling for status

If webhooks aren't set up, poll /documents/{id} periodically to check status.

---

7. Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | action | string | Yes | One of: create, upload, list, get, send, session, download, delete | | document_id | string | Conditional | Document UUID (required for get, send, session, download, delete) | | template_uuid | string | Conditional | Template UUID (required for create from template) | | name | string | No | Document name | | recipients | array | Conditional | Array of recipient objects | | tokens | array | No | Array of token name/value pairs | | metadata | object | No | External tracking metadata | | send | boolean | No | Send immediately after creation (default: false) | | file | binary | Conditional | PDF file for upload (required for upload action) | | status | string | No | Filter by status (for list action) | | q | string | No | Search query (for list action) | | count | integer | No | Number of results (for list action) | | page | integer | No | Page number (for list action) |

---

8. Returns

| Action | Success Response | |--------|------------------| | create | { id, name, status, recipients, tokens, date_created, date_modified } | | upload | { id, name, status, recipients, date_created, date_modified } | | list | { count, next, previous, results: [...] } | | get | { id, name, status, recipients, tokens, metadata, date_created, date_modified } | | send | { id, status, message } | | session | { id, document_id, url, expires_at } | | download | Binary PDF file | | delete | Empty (204 No Content) |

---

9. Usage examples

Example 1: Create proposal from template

{
  "action": "create",
  "template_uuid": "abc123-template-uuid",
  "name": "Q1 Sales Proposal",
  "recipients": [
    {
      "email": "[email protected]",
      "first_name": "Alice",
      "last_name": "Johnson",
      "role": "Client"
    }
  ],
  "tokens": [
    { "name": "company_name", "value": "Acme Corp" },
    { "name": "deal_value", "value": "50000" },
    { "name": "proposal_date", "value": "2025-01-15" }
  ],
  "metadata": {
    "external_id": "crm-deal-789",
    "source": "taskingtech"
  },
  "send": true
}

Example 2: Upload PDF for signature

{
  "action": "upload",
  "file": "[PDF_BINARY]",
  "name": "Service Agreement",
  "recipients": [
    {
      "email": "[email protected]",
      "first_name": "Bob",
      "last_name": "Williams",
      "role": "Signer"
    }
  ]
}

Example 3: List sent documents

{
  "action": "list",
  "status": "document.sent",
  "count": 50
}

Example 4: Get shareable link

{
  "action": "session",
  "document_id": "doc-uuid-123",
  "recipient": "[email protected]",
  "lifetime": 3600
}

Example 5: Download signed PDF

{
  "action": "download",
  "document_id": "doc-uuid-123"
}

---

10. Integration with [REDACTED]

This skill integrates seamlessly with other [REDACTED] capabilities:

1. Generate PDF → Upload to PandaDoc: Use generate_pdf to create a contract, then upload it for e‑signature.
2. CRM Integration: Pull recipient data from CRM, fill template tokens, create document.
3. Webhook Automation: Set up a [REDACTED] workflow that listens for PandaDoc webhooks and triggers follow‑up actions (email, Slack, task creation).
4. Status Tracking: Poll document status and update [REDACTED] tasks when documents are completed.
5. Multi‑recipient workflows: Create documents with multiple signing roles (Client, Manager, Legal).

---

11. Setup instructions for users

To use this skill, the user must:

1. Have a PandaDoc account (free trial or paid).
2. Generate an API key in PandaDoc Developer Dashboard.
3. Store the API key in [REDACTED] Settings → Integrations → PandaDoc.
4. (Optional) Create templates in PandaDoc UI for reusable documents.
5. (Optional) Set up webhook endpoints for real‑time status updates.

---

12. Security notes

• Never log or display the API key.
• Use environment variables or secure credential storage.
• Sandbox mode: Use https://api.pandadoc.com/public/v1/sandbox for testing.
• Production mode: Use https://api.pandadoc.com/public/v1 for live documents.
• Rate limits: Respect PandaDoc API rate limits (check headers for remaining quota).

---

13. Troubleshooting

| Issue | Solution | |-------|----------| | 401 Unauthorized | Check API key is valid and has correct permissions | | 404 Not Found | Verify template_uuid or document_id exists in the workspace | | Invalid tokens | Ensure token names match template [REDACTED]s exactly | | Rate limited | Wait and retry, implement exponential backoff | | Webhook not received | Verify endpoint is public HTTPS, check PandaDoc dashboard for delivery status |

---

14. API Reference

Full PandaDoc Public API documentation: https://developers.pandadoc.com/reference

---

This skill enables [REDACTED] to create, send, track, and manage e‑signature documents via PandaDoc's Public API.