---
updatedAt: 2026-08-18T12:36:39.000Z
agentTools:
  projectIndex: https://bolosign-developer-docs.readme.io/llms.txt
---

# Get documents list

Retrieve documents for a workspace, with optional filtering and pagination.

A document is either a **single signature PDF** (`documentType=PDF`) or a **PDF template** (`documentType=PDF_TEMPLATE`). Both types are supported; set `documentType` to choose which list to return. Default is `PDF`.

Results are always sorted by `createdAt`. Use `sortOrder` for ascending or descending (default: newest first).

Supported filters: `documentType`, `status` (PDF only), `documentId`, `dateFrom` / `dateTo` (`createdAt` range), and `archive`. Maximum `limit` is 100.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "BoloForms Signature API",
    "description": "Public OpenAPI for the BoloForms Signature product.\n\nAuthenticate every request with `x-api-key`. Workspace-scoped list endpoints also require `workspaceid`.\n\nIn this API, a **document** is either a single signature PDF (`documentType=PDF`) or a PDF template (`documentType=PDF_TEMPLATE`). `GET /get-documents`, `POST /void-document`, and `POST /send-reminder` all support both.\n\n`POST /pdf-template-lambda` creates / sends a template PDF (or form template) for signing.",
    "version": "2026-08-18",
    "contact": {
      "name": "BoloForms Support",
      "url": "https://www.boloforms.com",
      "email": "support@boloforms.com"
    }
  },
  "servers": [
    {
      "url": "https://sapi.boloforms.com/signature",
      "description": "Production Signature API"
    }
  ],
  "tags": [
    {
      "name": "Documents",
      "description": "List, void, and remind on documents. A document is a single signature PDF (`PDF`) or a PDF template (`PDF_TEMPLATE`)."
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/get-documents": {
      "get": {
        "tags": [
          "Documents"
        ],
        "operationId": "getDocuments",
        "summary": "Get documents list",
        "description": "Retrieve documents for a workspace, with optional filtering and pagination.\n\nA document is either a **single signature PDF** (`documentType=PDF`) or a **PDF template** (`documentType=PDF_TEMPLATE`). Both types are supported; set `documentType` to choose which list to return. Default is `PDF`.\n\nResults are always sorted by `createdAt`. Use `sortOrder` for ascending or descending (default: newest first).\n\nSupported filters: `documentType`, `status` (PDF only), `documentId`, `dateFrom` / `dateTo` (`createdAt` range), and `archive`. Maximum `limit` is 100.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "name": "documentType",
            "in": "query",
            "description": "Which documents to list. `PDF` = single signature PDFs. `PDF_TEMPLATE` = PDF templates. Both are supported.",
            "schema": {
              "$ref": "#/components/schemas/DocumentType"
            },
            "example": "PDF"
          },
          {
            "name": "status",
            "in": "query",
            "description": "Document status filter. Only supported for `documentType=PDF`. Use `ALL` to skip status filtering. Encode `SENT VIA LINK` as `SENT%20VIA%20LINK`.",
            "schema": {
              "$ref": "#/components/schemas/DocumentStatus"
            },
            "example": "SENT"
          },
          {
            "name": "sortOrder",
            "in": "query",
            "description": "Sort direction for `createdAt` (`asc` or `desc`). Sort field is always `createdAt`. Defaults to newest first (`desc`).",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc",
              "maxLength": 4,
              "minLength": 3,
              "pattern": "^(asc|desc)$"
            },
            "example": "desc"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of documents per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10,
              "format": "int32"
            },
            "example": 20
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number for pagination",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "format": "int32",
              "maximum": 10000
            },
            "example": 1
          },
          {
            "name": "documentId",
            "in": "query",
            "description": "Specific document ID to retrieve. Works for both a single signature PDF UUID and a PDF template UUID (pair with `documentType`).",
            "schema": {
              "$ref": "#/components/schemas/PublicDocumentId"
            },
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          {
            "name": "dateFrom",
            "in": "query",
            "description": "Inclusive start of the `createdAt` range. Format: `YYYY-MM-DD`.",
            "schema": {
              "type": "string",
              "format": "date",
              "minLength": 10,
              "maxLength": 10,
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "example": "2024-01-01"
          },
          {
            "name": "dateTo",
            "in": "query",
            "description": "Inclusive end of the `createdAt` range. Format: `YYYY-MM-DD`.",
            "schema": {
              "type": "string",
              "format": "date",
              "minLength": 10,
              "maxLength": 10,
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "example": "2024-12-31"
          },
          {
            "name": "archive",
            "in": "query",
            "description": "Archived files flag. `true` returns archived documents only; `false` (default) excludes them.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false",
              "maxLength": 5,
              "minLength": 4,
              "pattern": "^(true|false)$"
            },
            "example": "false"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved documents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentsResponse"
                },
                "example": {
                  "message": "Fetched documents",
                  "documents": [
                    {
                      "_id": "64f0a1b2c3d4e5f678901234",
                      "documentId": "550e8400-e29b-41d4-a716-446655440000",
                      "documentName": "NDA - Acme Corp",
                      "status": "SENT",
                      "signType": "PDF",
                      "authorEmail": "owner@example.com",
                      "createdAt": "2026-08-01T10:15:30.000Z",
                      "updatedAt": "2026-08-02T09:00:00.000Z",
                      "totalRespondents": 2,
                      "totalSignedRespondents": 1,
                      "isAllSigned": false,
                      "isArchived": false
                    }
                  ],
                  "documentsCount": 1,
                  "pagination": {
                    "currentPage": 1,
                    "totalPages": 1,
                    "totalDocuments": 1,
                    "hasNextPage": false,
                    "hasPreviousPage": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key issued from the BoloForms dashboard"
      }
    },
    "parameters": {
      "WorkspaceIdHeader": {
        "name": "workspaceid",
        "in": "header",
        "required": true,
        "description": "Workspace ID for filtering documents. Header name is case-insensitive (`workspaceid` or `workspaceId`).",
        "schema": {
          "type": "string",
          "format": "uuid",
          "minLength": 36,
          "maxLength": 36,
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        },
        "example": "550e8400-e29b-41d4-a716-446655440000"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized - API key is missing",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "message": "API key is required"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Bad Request - Invalid parameters, workspace access, or document state",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "message": "Invalid receiver data: email is required",
              "error": "email is required"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden - Workspace is not associated with this API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "message": "Document does not belong to any of the eligible workspaces",
              "error": "workspaceId is not associated with this API key"
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "message": "No document found with the specified documentId",
              "error": "Document not found"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "message": "Something went wrong",
              "error": "Unexpected error"
            }
          }
        }
      }
    },
    "schemas": {
      "DocumentType": {
        "type": "string",
        "description": "Document kind. `PDF` is a single signature PDF; `PDF_TEMPLATE` is a PDF template. Both are documents in `/get-documents`, `/void-document`, and `/send-reminder`. For void/reminder on a template, pair `PDF_TEMPLATE` with `responseId`.",
        "enum": [
          "PDF",
          "PDF_TEMPLATE"
        ],
        "example": "PDF",
        "maxLength": 12,
        "minLength": 3,
        "pattern": "^(PDF|PDF_TEMPLATE)$"
      },
      "DocumentStatus": {
        "type": "string",
        "description": "Document lifecycle status",
        "enum": [
          "ALL",
          "DRAFT",
          "SENT",
          "SIGNED",
          "COMPLETED",
          "DECLINED",
          "EXPIRED",
          "CANCELLED",
          "VOID",
          "TEMPLATE",
          "DELETED",
          "UNPAID",
          "PAID",
          "SENT VIA LINK"
        ],
        "example": "SENT",
        "maxLength": 13,
        "minLength": 3,
        "pattern": "^(ALL|DRAFT|SENT|SIGNED|COMPLETED|DECLINED|EXPIRED|CANCELLED|VOID|TEMPLATE|DELETED|UNPAID|PAID|SENT VIA LINK)$"
      },
      "PublicDocumentId": {
        "type": "string",
        "description": "Public UUID of a document: a single signature PDF or a PDF template",
        "format": "uuid",
        "minLength": 36,
        "example": "550e8400-e29b-41d4-a716-446655440000",
        "maxLength": 36,
        "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Invalid receiver data: email is required",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "error": {
            "type": "string",
            "description": "Detailed error information",
            "example": "email is required",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          }
        },
        "additionalProperties": false
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "currentPage": {
            "type": "integer",
            "minimum": 1,
            "example": 1,
            "format": "int32",
            "maximum": 2147483647
          },
          "totalPages": {
            "type": "integer",
            "minimum": 0,
            "example": 3,
            "format": "int32",
            "maximum": 2147483647
          },
          "totalDocuments": {
            "type": "integer",
            "minimum": 0,
            "example": 42,
            "format": "int32",
            "maximum": 2147483647
          },
          "hasNextPage": {
            "type": "boolean",
            "example": true
          },
          "hasPreviousPage": {
            "type": "boolean",
            "example": false
          }
        },
        "additionalProperties": false
      },
      "DocumentListItem": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "example": "64f0a1b2c3d4e5f678901234",
            "maxLength": 24,
            "minLength": 24,
            "pattern": "^[a-fA-F0-9]{24}$"
          },
          "documentId": {
            "type": "string",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "maxLength": 36,
            "minLength": 36,
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
            "format": "uuid"
          },
          "documentName": {
            "type": "string",
            "example": "NDA - Acme Corp",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "documentUrl": {
            "type": "string",
            "maxLength": 2048,
            "minLength": 0,
            "pattern": "^(https?:\\/\\/\\S{0,2040})?$"
          },
          "status": {
            "type": "string",
            "example": "SENT",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "signType": {
            "type": "string",
            "example": "PDF",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "authorEmail": {
            "type": "string",
            "format": "email",
            "example": "owner@example.com",
            "minLength": 3,
            "maxLength": 320,
            "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "minLength": 20,
            "maxLength": 40,
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "minLength": 20,
            "maxLength": 40,
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
          },
          "respondentsOfDoc": {
            "type": "array",
            "description": "Signers on the document (`respondents` for PDF [signer object], `templateRespondents` for PDF_TEMPLATE [template response unique id - can be used as `respondentDocumentId` later to request for particular responses of the template ]).",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "maxItems": 1000
          },
          "history": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HistoryItem"
            },
            "maxItems": 1000
          },
          "totalRespondents": {
            "type": "integer",
            "minimum": 0,
            "format": "int32",
            "maximum": 2147483647
          },
          "totalSignedRespondents": {
            "type": "integer",
            "minimum": 0,
            "format": "int32",
            "maximum": 2147483647
          },
          "isAllSigned": {
            "type": "boolean"
          },
          "metafields": {
            "type": "object",
            "additionalProperties": true
          },
          "schemaFieldsCount": {
            "type": "integer",
            "minimum": 0,
            "format": "int32",
            "maximum": 2147483647
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "maxItems": 1000
          },
          "pagesCount": {
            "type": "integer",
            "minimum": 0,
            "format": "int32",
            "maximum": 2147483647
          },
          "finishedPdfUrl": {
            "type": "string",
            "maxLength": 2048,
            "minLength": 0,
            "pattern": "^(https?:\\/\\/\\S{0,2040})?$"
          },
          "finishedPdfHistoryUrl": {
            "type": "string",
            "maxLength": 2048,
            "minLength": 0,
            "pattern": "^(https?:\\/\\/\\S{0,2040})?$"
          },
          "isSigningOrderData": {
            "type": "boolean"
          },
          "eTemplateId": {
            "type": "string",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "settings": {
            "type": "object",
            "additionalProperties": true
          },
          "sentViaSMS": {
            "type": "boolean"
          },
          "createdBy": {
            "type": "object",
            "description": "Owner who created the document. Populated with `_id`, `email`, `name`, and `profilePic`.",
            "properties": {
              "_id": {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{24}$",
                "minLength": 24,
                "maxLength": 24
              },
              "email": {
                "type": "string",
                "format": "email",
                "minLength": 3,
                "maxLength": 320,
                "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
              },
              "name": {
                "type": "string",
                "maxLength": 1024,
                "minLength": 0,
                "pattern": "^[\\s\\S]{0,1024}$"
              },
              "profilePic": {
                "type": "string",
                "maxLength": 2048,
                "minLength": 0,
                "pattern": "^[\\s\\S]{0,2048}$"
              }
            },
            "additionalProperties": true
          },
          "isArchived": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "DocumentsResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Fetched documents",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentListItem"
            },
            "maxItems": 1000
          },
          "documentsCount": {
            "type": "integer",
            "minimum": 0,
            "example": 42,
            "format": "int32",
            "maximum": 2147483647
          },
          "pagination": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Pagination"
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "HistoryItem": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "example": "SENT",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "activity": {
            "type": "string",
            "example": "Document sent for signature",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "status": {
            "type": "string",
            "example": "SENT",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-08-01T10:15:30.000Z",
            "minLength": 20,
            "maxLength": 40,
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
          },
          "userId": {
            "type": "string",
            "description": "Present on document history entries. Omitted from transformed template-respondent history."
          },
          "ip": {
            "type": "string",
            "description": "Present on document history entries. Omitted from transformed template-respondent history."
          }
        },
        "additionalProperties": true
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```