How to Filter and Search Documents

Problem

You need to efficiently find specific documents in your PandaDoc workspace using various filtering criteria instead of manually browsing through all documents.

Prerequisites

Access to PandaDoc API
Valid API authentication credentials
Basic familiarity with REST API calls

Solution

Step 1: Choose Your Filtering Criteria

Determine what criteria you want to use to filter documents:

By template or form: Use template_id or form_id parameters
By owner: Use membership_id parameter
By recipient/approver: Use contact_id parameter
By status: Use status parameter (or status__ne to exclude)
By folder: Use folder_uuid parameter
By tags: Use tag parameter (e.g., tag=tag_1)
By metadata: Use metadata_{key}={value} format (e.g., metadata_opportunity_id=2181432)
By name or reference: Use q parameter
By specific ID: Use id parameter

Step 2: Set Date Range Filters

If you want to limit results by date ranges:

By completion date: Use completed_from and/or completed_to
By creation date: Use created_from and/or created_to
By modification date: Use modified_from and/or modified_to

Step 3: Configure Result Ordering

For best performance and consistent results:

Order by creation date (recommended): order_by=date_created
Set date range: Always include created_from and created_to when ordering
Use pagination: Set count (max 100) and page parameters

Step 4: Make the API Call

Example request to find documents by template in August 2023:

GET /public/v1/documents?template_id=ABC123&order_by=date_created&created_from=2023-08-01T00:00:00Z&created_to=2023-09-01T00:00:00Z&count=100

Example with metadata filtering:

GET /public/v1/documents?metadata_opportunity_id=2181432&order_by=date_created&count=50

Example excluding specific status (exclude drafts):

GET /public/v1/documents?status__ne=0&order_by=date_created&count=50

Example filtering by completed status:

GET /public/v1/documents?status=2&order_by=date_created&count=50

Step 5: Handle Large Result Sets

For workspaces with many documents, use batching:

First batch: Set initial date range (e.g., one month)
Process pages: Increment page parameter until empty response
Next batch: Move to next date range
Continue: Repeat until all desired periods are covered

Example batching sequence:

# August 2023 - Page 1
GET /public/v1/documents?order_by=date_created&created_from=2023-08-01T00:00:00Z&created_to=2023-09-01T00:00:00Z&count=100&page=1

# August 2023 - Page 2
GET /public/v1/documents?order_by=date_created&created_from=2023-08-01T00:00:00Z&created_to=2023-09-01T00:00:00Z&count=100&page=2

# September 2023 - Page 1
GET /public/v1/documents?order_by=date_created&created_from=2023-09-01T00:00:00Z&created_to=2023-10-01T00:00:00Z&count=100&page=1

Verification

Confirm your filtering worked by checking:

Result count: Verify you received the expected number of documents
Content match: Spot-check that returned documents match your criteria
Date ranges: Ensure documents fall within specified date ranges
Pagination: Verify page and count parameters work as expected

Troubleshooting

Empty results: Check if your filter criteria are too restrictive or date ranges are incorrect.

Slow performance: Always use date_created ordering with date range filters for large workspaces.

Inconsistent ordering: Avoid ordering by date_status_changed for large result sets; use date_created instead.

Missing documents: Check if you need to include deleted documents with deleted=true.