--- updatedAt: 2026-08-18T12:36:39.000Z agentTools: projectIndex: https://bolosign-developer-docs.readme.io/llms.txt --- # Get form responses Retrieve form responses. Provide `formId`, `responseId`, or both. `responseId` may be a Mongo ObjectId or a UUID v4 (`formResponseId`). Pagination (`page`, `limit`) applies when listing by `formId` only. # 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": "Forms", "description": "Retrieve submitted form responses" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/get-form-responses": { "get": { "tags": [ "Forms" ], "operationId": "getFormResponses", "summary": "Get form responses", "description": "Retrieve form responses.\n\nProvide `formId`, `responseId`, or both. `responseId` may be a Mongo ObjectId or a UUID v4 (`formResponseId`). Pagination (`page`, `limit`) applies when listing by `formId` only.", "parameters": [ { "name": "formId", "in": "query", "description": "ID of the form to retrieve responses for", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "example": "form_550e8400e29b41d4a7164466" }, { "name": "responseId", "in": "query", "description": "Specific response ID to retrieve. Accepts a Mongo ObjectId or UUID v4.", "schema": { "type": "string", "minLength": 24, "maxLength": 36, "pattern": "^([a-fA-F0-9]{24}|[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": "64f0a1b2c3d4e5f678901234" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/LimitQuery" } ], "responses": { "200": { "description": "Successfully retrieved form responses", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FormResponsesPaginatedResponse" }, { "$ref": "#/components/schemas/SingleFormResponse" } ] }, "examples": { "paginated": { "summary": "Paginated form responses", "value": { "responses": [ { "responseId": "64f0a1b2c3d4e5f678901234", "formId": "form_550e8400e29b41d4a7164466", "answers": { "Full Name": "Jane Doe", "Email": "jane.doe@example.com" }, "submittedAt": "2026-08-01T10:15:30.000Z" } ], "pagination": { "currentPage": 1, "totalPages": 1, "totalResponses": 1, "hasNextPage": false, "hasPreviousPage": false } } }, "single": { "summary": "Single form response", "value": { "responseId": "64f0a1b2c3d4e5f678901234", "formId": "form_550e8400e29b41d4a7164466", "answers": { "Full Name": "Jane Doe", "Email": "jane.doe@example.com" }, "submittedAt": "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": { "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 }, "SingleFormResponse": { "type": "object", "properties": { "responseId": { "type": "string", "example": "64f0a1b2c3d4e5f678901234", "maxLength": 24, "minLength": 24, "pattern": "^[a-fA-F0-9]{24}$" }, "formId": { "type": "string", "example": "form_550e8400e29b41d4a7164466", "maxLength": 1024, "minLength": 0, "pattern": "^[\\s\\S]{0,1024}$" }, "answers": { "type": "object", "description": "Form response data. Keys are question labels; shape varies per form.", "additionalProperties": true, "example": { "Full Name": "Jane Doe", "Email": "jane.doe@example.com" } }, "submittedAt": { "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})$" } }, "additionalProperties": false }, "FormResponsesPaginatedResponse": { "type": "object", "properties": { "responses": { "type": "array", "items": { "$ref": "#/components/schemas/SingleFormResponse" }, "maxItems": 1000 }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "example": 1, "format": "int32", "maximum": 2147483647 }, "totalPages": { "type": "integer", "minimum": 0, "example": 1, "format": "int32", "maximum": 2147483647 }, "totalResponses": { "type": "integer", "minimum": 0, "example": 12, "format": "int32", "maximum": 2147483647 }, "hasNextPage": { "type": "boolean", "example": false }, "hasPreviousPage": { "type": "boolean", "example": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```