v1

latestOpenAPI 3.0.3MIT2026-07-24122271451.2 KB

Documents

[Beta] List 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.

get/public/beta/documents/search

Query parameters

qstring required

Natural-language search query. Supports filtering by status, owner, dates, and folder. Also supports keyword content search across document titles and body text.

Response

Search completed successfully

countinteger required

Total number of matching documents.

messagestring required

Human-friendly summary of the search outcome.

Example response

{
  "results": [
    {
      "document_id": "msFYActMfJHqNTKH9ig2DF",
      "name": "Service Agreement - Acme Corp",
      "status": "document.draft",
      "date_created": "2026-03-15T10:30:00Z",
      "owner": {
        "id": "9FeAY2NB3C9qDdtQRb4tTL",
        "name": "Jane Doe",
        "email": "jane.doe@example.com"
      },
      "folder": {
        "id": "Uf7yNEwkELsazbKHDMDAeV",
        "name": "Active Contracts"
      },
      "extra_fields": {
        "title": "Service Agreement - Acme Corp",
        "date_modified": "2026-03-18T11:05:00Z",
        "date_of_last_action": "2026-03-20T14:22:00Z",
        "date_sent": "2026-03-16T09:00:00Z",
        "date_first_signed": "2026-03-19T10:15:00Z",
        "date_last_signed": "2026-03-20T14:22:00Z",
        "date_first_viewed": "2026-03-16T11:30:00Z",
        "date_last_viewed": "2026-03-20T14:20:00Z",
        "date_completed": "2026-03-20T14:22:00Z",
        "date_expired": "2026-04-15T00:00:00Z",
        "date_expiration": "2026-06-15T00:00:00Z",
        "type": "regular document",
        "parent": {
          "id": "7Xfnrk7dTaWJ78wNUrg3rr",
          "name": "Master Sales Contract"
        },
        "path": [
          {
            "id": "Uf7yNEwkELsazbKHDMDAeV",
            "name": "Sales"
          }
        ],
        "recipients": [
          {
            "id": "bQySP2djjJkNKxyVbQ8pu4",
            "email": "john.smith@example.com",
            "phone": "+1-555-0123",
            "first_name": "John",
            "last_name": "Smith",
            "role_name": "Client",
            "date_signed": "2026-03-20T14:22:00Z",
            "date_first_viewed": "2026-03-17T08:45:00Z",
            "date_last_viewed": "2026-03-20T14:20:00Z",
            "viewed_count": 3,
            "type": "signer",
            "group": "Legal Team",
            "user_id": "9FeAY2NB3C9qDdtQRb4tTL",
            "contact_id": "DrNfkrquTcXH83cgF5ZGrr",
            "company": "Acme Corp",
            "title": "VP of Sales",
            "location": "San Francisco, CA",
            "country": "US",
            "postal_code": "94105",
            "state": "CA",
            "city": "San Francisco",
            "street": "123 Market St",
            "avatar": "https://www.gravatar.com/avatar/abc123",
            "is_done": true
          }
        ],
        "recipient_count": 1,
        "viewed_total_count": 5,
        "viewed_count": 2,
        "signed_count": 1,
        "completion_rate": 1,
        "time_to_completion_hours": 120.5,
        "total": {
          "amount": 15000,
          "currency": "USD"
        },
        "tags": [
          "legal",
          "Q1-2026"
        ],
        "document_type": {
          "id": "pXwnAhg8bk9SoBEGGdNu3d",
          "type": "Non-Disclosure Agreement",
          "general_type": "Agreement"
        },
        "clm_metadata": [
          {
            "key": "department",
            "value": "Engineering"
          }
        ]
      }
    }
  ],
  "count": 12,
  "suggestions": [
    {
      "text": "Show only completed contracts"
    }
  ],
  "message": "Found 12 documents matching your query.",
  "intent": [
    {
      "field": "status",
      "value": "document.completed"
    }
  ]
}