# List Documents API Parameters

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`    | object | 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

```bash
# Get all completed documents
GET /public/v1/documents?status=2

# Exclude draft documents
GET /public/v1/documents?status__ne=0
```

### Filter by Metadata

```bash
# 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

```bash
# 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
```

## Related Endpoints

* [List Documents by Linked Object](https://developers.pandadoc.com/reference/list-documents-by-linked-object)
* [List Documents API Reference](https://developers.pandadoc.com/reference/list-documents)