Complete reference for all parameters available in the List Documents API endpoint
List Documents API Parameters
Endpoint
GET /public/v1/documents
Filter Parameters
Document Identification
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
User and Contact Filters
Parameter
Type
Required
Description
membership_id
string
No
Filter by document owner's membership ID
contact_id
string
No
Filter by recipient or approver contact ID
Status Filters
Parameter
Type
Required
Description
status
integer
No
Filter by document status (see status values below)
status__ne
integer
No
Exclude documents with specified status (see status values below)
Organization Filters
Parameter
Type
Required
Description
folder_uuid
string
No
Filter by folder UUID
tag
string
No
Filter by document tag
metadata
array
No
Filter by metadata key-value pairs (format: metadata_{key}={value})
Date Range Filters
Parameter
Type
Required
Description
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
Special Filters
Parameter
Type
Required
Description
deleted
boolean
No
Include only deleted documents when true
Pagination Parameters
Parameter
Type
Required
Default
Description
count
integer
No
50
Number of results per page (max: 100)
page
integer
No
1
Page number (starts from 1)
Ordering Parameters
Parameter
Type
Required
Default
Description
order_by
string
No
date_status_changed
Field to order results by
Available Order Fields
date_created (recommended for performance)
date_status_changed (default)
date_modified
name
Data Types
DateTime Format
All datetime parameters must use ISO 8601 format:
Format: YYYY-MM-DDTHH:MM:SSZ
Example: 2023-08-01T00:00:00Z
Document Status Values
Status values are numeric integers:
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
Performance Considerations
Recommended Practices
Use order_by=date_created for consistent results
Include created_from and created_to when ordering for best performance
Limit count to 100 or less
Use date range filters for large workspaces
Performance Impact
Ordering by date_created with date ranges: High performance
Ordering by date_status_changed without date ranges: Lower performance for large datasets
Complex metadata filters: May impact response time
Response Format
The API returns a JSON object with:
results: Array of document objects
count: Total number of documents matching criteria
next: URL for next page (if available)
previous: URL for previous page (if available)
Usage Examples
Filter by Status
# Get all completed documents
GET /public/v1/documents?status=2
# Exclude draft documents
GET /public/v1/documents?status__ne=0
Filter by Metadata
# Filter by opportunity ID
GET /public/v1/documents?metadata_opportunity_id=2181432
# Filter by multiple metadata fields
GET /public/v1/documents?metadata_opportunity_id=2181432&metadata_custom_key=custom_value
Ordering with Date Range
# Order by creation date with date range
GET /public/v1/documents?order_by=date_created&created_from=2023-08-01T00:00:00Z&created_to=2023-09-01T00:00:00Z&count=100
