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

# Get template respondents

Retrieve respondents for a specific template with pagination, or get a specific respondent.

Provide `templateId`, `respondentDocumentId`, or both. `respondentDocumentId` is the Mongo ObjectId returned as `createdDocumentId` from `POST /pdf-template-lambda` and `templateRespondents` array in the response of `GET /get-documents`.

# 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": "Templates",
      "description": "Send PDF/form templates and fetch template respondents"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/get-template-respondent": {
      "get": {
        "tags": [
          "Templates"
        ],
        "operationId": "getTemplateRespondents",
        "summary": "Get template respondents",
        "description": "Retrieve respondents for a specific template with pagination, or get a specific respondent.\n\nProvide `templateId`, `respondentDocumentId`, or both. `respondentDocumentId` is the Mongo ObjectId returned as `createdDocumentId` from `POST /pdf-template-lambda` and `templateRespondents` array in the response of `GET /get-documents`.",
        "parameters": [
          {
            "name": "templateId",
            "in": "query",
            "description": "Template ID to retrieve respondents for",
            "schema": {
              "$ref": "#/components/schemas/PublicDocumentId"
            },
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          {
            "name": "respondentDocumentId",
            "in": "query",
            "description": "Specific respondent ID to retrieve",
            "schema": {
              "$ref": "#/components/schemas/MongoObjectId"
            },
            "example": "64f0a1b2c3d4e5f678901234"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved respondents",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/RespondentsPaginatedResponse"
                    },
                    {
                      "$ref": "#/components/schemas/RespondentDocument"
                    }
                  ]
                },
                "examples": {
                  "paginated": {
                    "summary": "List respondents for a template",
                    "value": {
                      "respondents": [
                        {
                          "respondentDocumentId": "64f0a1b2c3d4e5f678901234",
                          "templateId": "550e8400-e29b-41d4-a716-446655440000",
                          "ownerId": "64f0a1b2c3d4e5f678900001",
                          "status": "SENT",
                          "signers": [
                            {
                              "name": "Jane Doe",
                              "email": "jane.doe@example.com",
                              "signerId": "s_01HZX",
                              "status": "SENT",
                              "roleTitle": "Employee",
                              "sentUrl": "https://signature.boloforms.com/sign/abc123",
                              "hasDeclined": false
                            }
                          ],
                          "history": [
                            {
                              "action": "SENT",
                              "activity": "Document sent for signature",
                              "status": "SENT",
                              "createdAt": "2026-08-01T10:15:30.000Z"
                            }
                          ],
                          "pdfLink": "https://files.example.com/template.pdf",
                          "finishedPdfUrl": "",
                          "createdAt": "2026-08-01T10:15:30.000Z"
                        }
                      ],
                      "pagination": {
                        "currentPage": 1,
                        "totalPages": 1,
                        "totalDocuments": 1,
                        "hasNextPage": false,
                        "hasPreviousPage": false
                      }
                    }
                  },
                  "single": {
                    "summary": "Single respondent",
                    "value": {
                      "respondentDocumentId": "64f0a1b2c3d4e5f678901234",
                      "templateId": "550e8400-e29b-41d4-a716-446655440000",
                      "ownerId": "64f0a1b2c3d4e5f678900001",
                      "status": "SENT",
                      "signers": [
                        {
                          "name": "Jane Doe",
                          "email": "jane.doe@example.com",
                          "signerId": "s_01HZX",
                          "status": "SENT",
                          "roleTitle": "Employee",
                          "sentUrl": "https://signature.boloforms.com/sign/abc123",
                          "hasDeclined": false
                        }
                      ],
                      "history": [],
                      "pdfLink": "https://files.example.com/template.pdf",
                      "finishedPdfUrl": "",
                      "createdAt": "2026-08-01T10:15:30.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "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": {
      "PageQuery": {
        "name": "page",
        "in": "query",
        "description": "Page number for pagination",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1,
          "format": "int32",
          "maximum": 10000
        },
        "example": 1
      },
      "LimitQuery": {
        "name": "limit",
        "in": "query",
        "description": "Number of items per page",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 10,
          "format": "int32",
          "maximum": 100
        },
        "example": 10
      }
    },
    "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"
            }
          }
        }
      },
      "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": {
      "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}$"
      },
      "MongoObjectId": {
        "type": "string",
        "description": "MongoDB ObjectId (24 hex characters). Returned as `createdDocumentId` from `POST /pdf-template-lambda`.",
        "pattern": "^[a-fA-F0-9]{24}$",
        "minLength": 24,
        "maxLength": 24,
        "example": "64f0a1b2c3d4e5f678901234"
      },
      "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
      },
      "RespondentSigner": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Jane Doe",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "jane.doe@example.com",
            "minLength": 3,
            "maxLength": 320,
            "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
          },
          "signerId": {
            "type": "string",
            "example": "s_01HZX",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "status": {
            "type": "string",
            "example": "SENT",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "roleTitle": {
            "type": "string",
            "example": "Employee",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "sentUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://signature.boloforms.com/sign/abc123",
            "minLength": 8,
            "maxLength": 2048,
            "pattern": "^https?:\\/\\/.+$"
          },
          "hasDeclined": {
            "type": "boolean",
            "example": false
          }
        },
        "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
      },
      "RespondentDocument": {
        "type": "object",
        "properties": {
          "respondentDocumentId": {
            "type": "string",
            "example": "64f0a1b2c3d4e5f678901234",
            "maxLength": 24,
            "minLength": 24,
            "pattern": "^[a-fA-F0-9]{24}$"
          },
          "templateId": {
            "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"
          },
          "ownerId": {
            "type": "string",
            "example": "64f0a1b2c3d4e5f678900001",
            "maxLength": 24,
            "minLength": 24,
            "pattern": "^[a-fA-F0-9]{24}$"
          },
          "status": {
            "type": "string",
            "example": "SENT",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "signers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RespondentSigner"
            },
            "maxItems": 1000
          },
          "history": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HistoryItem"
            },
            "maxItems": 1000
          },
          "pdfLink": {
            "type": "string",
            "maxLength": 2048,
            "minLength": 0,
            "pattern": "^(https?:\\/\\/\\S{0,2040})?$"
          },
          "finishedPdfUrl": {
            "type": "string",
            "description": "Presigned URL of the completed PDF when available",
            "maxLength": 2048,
            "minLength": 0,
            "pattern": "^(https?:\\/\\/\\S{0,2040})?$"
          },
          "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})$"
          }
        },
        "additionalProperties": false
      },
      "RespondentsPaginatedResponse": {
        "type": "object",
        "properties": {
          "respondents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RespondentDocument"
            },
            "maxItems": 1000
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```