---
title: "[Beta] List Documents Search"
method: GET
path: "/public/beta/documents/search"
tags: ["Documents"]
---

# [Beta] List Documents Search

`GET /public/beta/documents/search`

Find documents from a natural-language query. PandaDoc AI interprets
the query and returns the matching documents.

PandaDoc offers two document search tools: this AI-powered search
and the structured <a href="#/operations/listDocuments">List Documents</a>
endpoint.

<details><summary><strong>Document Search Tools Guide</strong> — click to expand</summary>

#### When to use AI Search (this endpoint)

- The query is in natural language (e.g., "show me all completed documents from Q2 2026")
- The query mentions people by name (e.g., "contracts shared with John Smith")
- The query uses relative date expressions (e.g., "last week", "this quarter")
- You want the system to automatically determine the best filtering strategy
- You want follow-up suggestions to help refine the search

#### When to use List Documents

- You already have exact, structured filter parameters (specific status codes, precise ISO-8601 date ranges)
- You need to paginate through a large result set (explicit page/count control)
- You need faster, more predictable response times
- You need deterministic, repeatable queries for automation workflows

#### Comparison

| Feature                  | AI Search                                           | List Documents                                   |
| ------------------------ | --------------------------------------------------- | ------------------------------------------------ |
| **Input**                | Single natural-language query                       | Search query + optional structured filters       |
| **Date handling**        | Understands relative dates ("last week", "Q2 2026") | Requires explicit ISO-8601 date range            |
| **Status filtering**     | Interprets from query ("completed", "sent")         | Requires numeric status codes                    |
| **Contact/owner search** | Resolves people by name                             | Not supported                                    |
| **Pagination**           | Returns top 100 results                             | Supports explicit page and page size (up to 100) |
| **Suggestions**          | Returns follow-up suggestions for refinement        | No suggestions                                   |
| **Best for**             | Conversational, exploratory search                  | Precise, structured, repeatable queries          |

</details>

The response may return fewer items than the total matches. The
search caps the returned list based on query complexity: `count`
shows the number of items returned in `results`. When the query
matches more documents than returned, use one of the returned
`suggestions` as a stricter follow-up query to narrow the results.

> 🚧 **Beta**
>
> This endpoint is currently in beta and may change without notice.

## Query parameters

- `q` string, required

## Response `200`

Search completed successfully

- DocumentSearchResponse — Response containing matching documents and follow-up suggestions
  - `results` DocumentSearchResult[], required — Matching documents. Empty list when nothing matches.
    - `document_id` string, required — Document identifier.
    - `name` string, required — Document title or name.
    - `status` 'document.draft' | 'document.sent' | 'document.completed' | 'document.uploaded' | 'document.error' | 'document.viewed' | 'document.waiting_approval' | 'document.approved' | 'document.rejected' | 'document.waiting_pay' | 'document.paid' | 'document.voided' | 'document.declined' | 'document.external_review' | 'document.scheduled', required
    - `date_created` string, date-time, required — When the document was created (ISO 8601).
    - `owner` DocumentSearchResultOwner, required — Owner of the document
      - `id` string, required — Owner's user identifier.
      - `name` string, required — Owner's display name (first and last name combined).
      - `email` string, required — Owner's email address.
      - `avatar` string, nullable — Owner's avatar URL. null if not set.
    - `folder` DocumentSearchResultFolder, required — Folder containing the document
      - `id` string, required — Folder identifier.
      - `name` string, required — Folder display name.
    - `extra_fields` DocumentSearchExtraFields, required — Additional document fields dynamically selected by the AI based on the query. All properties are optional, only relevant will be included to the query. The object is empty when only the standard fields were requested.
      - `title` string, nullable — Document title (includes autonumbering).
      - `date_modified` string, date-time, nullable — When the document was last modified (ISO 8601).
      - `date_of_last_action` string, date-time, nullable — When the last action was performed on the document (ISO 8601).
      - `date_sent` string, date-time, nullable — When the document was sent (ISO 8601).
      - `date_first_signed` string, date-time, nullable — When the first recipient signed the document (ISO 8601).
      - `date_last_signed` string, date-time, nullable — When the last recipient signed the document (ISO 8601).
      - `date_first_viewed` string, date-time, nullable — When the document was first viewed (ISO 8601).
      - `date_last_viewed` string, date-time, nullable — When the document was last viewed (ISO 8601).
      - `date_completed` string, date-time, nullable — When the document was completed (ISO 8601).
      - `date_expired` string, date-time, nullable — When the document expired (ISO 8601).
      - `date_expiration` string, date-time, nullable — When the document will expire (ISO 8601).
      - `removed` boolean — Whether the document has been removed.
      - `type` 'regular document' | 'template' | 'content library item'
      - `parent` DocumentSearchParentTemplate, nullable — Template from which the document was created. null when the document was not created from a template.
        - `id` string, nullable — Template identifier.
        - `name` string, nullable — Template name.
      - `path` DocumentSearchPathEntry[], nullable — Ordered list of folders from root to the document's location.
        - `id` string, nullable — Folder identifier.
        - `name` string, nullable — Folder name.
      - `recipients` DocumentSearchRecipient[], nullable — List of document recipients.
        - `id` string, nullable — Recipient identifier.
        - `email` string, nullable — Email address.
        - `phone` string, nullable — Phone number.
        - `first_name` string, nullable — First name.
        - `last_name` string, nullable — Last name.
        - `role_name` string, nullable — User-defined role label assigned to this recipient on the document (e.g. "Client", "Sender", "Manager"). Free-form string set by the document creator.
        - `date_signed` string, date-time, nullable — When the recipient signed the document (ISO 8601).
        - `date_first_viewed` string, date-time, nullable — When the recipient first viewed the document (ISO 8601).
        - `date_last_viewed` string, date-time, nullable — When the recipient last viewed the document (ISO 8601).
        - `viewed_count` integer, nullable — Number of times the recipient viewed the document.
        - `can_pay` boolean — Whether the recipient can make payments.
        - `type` 'signer' | 'CC' | 'approver'
        - `group` string, nullable — Name of the recipient group this recipient belongs to. null for individual recipients.
        - `user_id` string, nullable — Associated user identifier.
        - `contact_id` string, nullable — Associated contact identifier.
        - `company` string, nullable — Company name.
        - `title` string, nullable — Contact title.
        - `internal` boolean, nullable — Whether the contact is internal.
        - `location` string, nullable — Contact location.
        - `country` string, nullable — Country.
        - `postal_code` string, nullable — Postal code.
        - `state` string, nullable — State or province.
        - `city` string, nullable — City.
        - `street` string, nullable — Street address.
        - `avatar` string, nullable — Avatar URL. null if no email is associated.
        - `is_done` boolean, nullable — Whether the recipient has completed their action.
      - `recipient_count` integer — Total number of recipients.
      - `viewed_total_count` integer — Total number of times the document was viewed.
      - `viewed_count` integer — Number of recipients who viewed the document.
      - `signed_count` integer — Number of recipients who signed the document.
      - `completion_rate` number, float, nullable — Completion rate of recipients (0.0 to 1.0).
      - `time_to_completion_hours` number, float, nullable — Time taken to complete the document, in hours.
      - `total` DocumentSearchGrandTotal, nullable — Document grand total.
        - `amount` number, float, required — Total amount.
        - `currency` string, required — Currency ISO code (e.g. USD, EUR).
      - `tags` string[] — List of document tags.
      - `document_type` DocumentSearchDocumentType, nullable — Document type classification. Each workspace can define custom specific types that belong to a general category.
        - `id` string, nullable — Document type identifier.
        - `type` string, nullable — Specific document type name. Can be a built-in system type or a workspace-defined custom type. Common system values include Non-Disclosure Agreement, Sales Agreement, Employment Agreement, Service Agreement, Contractor Agreement, Subscription Agreement, Partnership Agreement, Lease Agreement, Rental Agreement, License Agreement, Purchase Agreement, Statement of Work, Professional Services Agreement, Sales Proposal, Project Proposal, Business Letter, Financial Report, Inspection Report, Employment Termination Notice, and Employee Handbook.
        - `general_type` 'Agreement' | 'Proposal' | 'Invoice' | 'Quote' | 'Form' | 'Policy'
      - `effective_permissions` DocumentSearchEffectivePermissions — Effective permissions of the current user for the document.
        - `can_manage_collaborators` boolean, required — Whether the user can manage collaborators.
        - `can_revert_to_draft` boolean, required — Whether the user can revert the document to draft.
      - `clm_metadata` DocumentSearchClmMetadata[], nullable — List of CLM metadata key/value pairs.
        - `key` string, required — Metadata key.
        - `value` string, required — Metadata value, always serialized as a string regardless of the underlying typed value.
  - `count` integer, required — Total number of matching documents.
  - `suggestions` DocumentSearchSuggestion[], required — Follow-up suggestions to narrow or refine the search.
    - `text` string, required — Natural-language suggestion text. Designed to work as a valid query in the next call.
  - `message` string, required — Human-friendly summary of the search outcome.
  - `intent` DocumentSearchAppliedFilter[], required — Filters that were applied to resolve the query. Helps the caller understand how the query was interpreted.
    - `field` string, required — The field or dimension used for filtering.
    - `value` string, required — The resolved value applied for that field.

## Other responses

- `400` — Bad Request error
- `401` — Authentication error
- `403` — Permission error
- `429` — Too many requests error
- `500` — Internal server error
- `504` — The search did not complete within the allowed time. Retry the request or simplify the query.

---

[API](https://skmtc.net/pandadoc/apis/pandadoc-public-api.md) · [All operations](https://skmtc.net/pandadoc/apis/pandadoc-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pandadoc/pandadoc-public-api/versions/0c2b70be3fb0/schema)