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

# Create or send a template PDF document

Create / send a template PDF document for signing (also supports form templates).

This is the public route for creating a signing request from a template. Set `signingType` to `PDF_TEMPLATE` to send a PDF template, or `FORM_TEMPLATE` to send a form template. Supply receivers, optional custom variables, and optional `mailData`.

For `PDF_TEMPLATE`, each receiver `roleTitle` must exactly match a role on the template in the BoloSign dashboard. The `createdDocumentId` in the PDF response is the Mongo ObjectId to pass as `responseId` to `/void-document` and `/send-reminder` when `documentType=PDF_TEMPLATE`.

# 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": {
    "/pdf-template-lambda": {
      "post": {
        "tags": [
          "Templates"
        ],
        "operationId": "sendTemplateForSigning",
        "summary": "Create or send a template PDF document",
        "description": "Create / send a template PDF document for signing (also supports form templates).\n\nThis is the public route for creating a signing request from a template. Set `signingType` to `PDF_TEMPLATE` to send a PDF template, or `FORM_TEMPLATE` to send a form template. Supply receivers, optional custom variables, and optional `mailData`.\n\nFor `PDF_TEMPLATE`, each receiver `roleTitle` must exactly match a role on the template in the BoloSign dashboard. The `createdDocumentId` in the PDF response is the Mongo ObjectId to pass as `responseId` to `/void-document` and `/send-reminder` when `documentType=PDF_TEMPLATE`.",
        "requestBody": {
          "$ref": "#/components/requestBodies/TemplateSigningRequest"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/TemplateSigningSuccess"
          },
          "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"
      }
    },
    "requestBodies": {
      "TemplateSigningRequest": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/PDFTemplateSigningRequest"
                },
                {
                  "$ref": "#/components/schemas/FormTemplateSigningRequest"
                }
              ],
              "discriminator": {
                "propertyName": "signingType",
                "mapping": {
                  "PDF_TEMPLATE": "#/components/schemas/PDFTemplateSigningRequest",
                  "FORM_TEMPLATE": "#/components/schemas/FormTemplateSigningRequest"
                }
              }
            },
            "examples": {
              "pdfTemplate": {
                "summary": "PDF template",
                "value": {
                  "signingType": "PDF_TEMPLATE",
                  "documentId": "550e8400-e29b-41d4-a716-446655440000",
                  "receiversList": [
                    {
                      "name": "Jane Doe",
                      "email": "jane.doe@example.com",
                      "roleTitle": "Employee",
                      "subject": "Please sign the NDA",
                      "message": "Hi Jane, please review and sign."
                    },
                    {
                      "name": "John Smith",
                      "email": "john.smith@example.com",
                      "roleTitle": "Manager"
                    }
                  ],
                  "customVariables": [
                    {
                      "varName": "[name]",
                      "varValue": "Jane Doe"
                    },
                    {
                      "varName": "[company]",
                      "varValue": "Acme Corp"
                    }
                  ],
                  "mailData": {
                    "subject": "Document ready for signature",
                    "message": "Please sign the attached document."
                  }
                }
              },
              "formTemplate": {
                "summary": "Form template",
                "value": {
                  "signingType": "FORM_TEMPLATE",
                  "documentId": "form_550e8400e29b41d4a7164466",
                  "receiversList": [
                    {
                      "name": "Jane Doe",
                      "email": "jane.doe@example.com",
                      "subject": "Please complete this form",
                      "message": "Hi Jane, fill and sign when you can."
                    }
                  ],
                  "mailData": {
                    "subject": "Form ready for you",
                    "message": "Please complete the form."
                  }
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "TemplateSigningSuccess": {
        "description": "Successfully created / sent the template PDF (or form) for signing",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/PDFSigningResponse"
                },
                {
                  "$ref": "#/components/schemas/FormSigningResponse"
                }
              ]
            },
            "examples": {
              "pdf": {
                "summary": "PDF template sent",
                "value": {
                  "message": "Document sent for signature successfully",
                  "templateId": "550e8400-e29b-41d4-a716-446655440000",
                  "createdDocumentId": "64f0a1b2c3d4e5f678901234",
                  "createdDocumentStatus": "SENT",
                  "signers": [
                    {
                      "signerId": "s_01HZX",
                      "email": "jane.doe@example.com",
                      "name": "Jane Doe",
                      "status": "SENT",
                      "roleTitle": "Employee",
                      "sentUrl": "https://signature.boloforms.com/sign/abc123"
                    }
                  ]
                }
              },
              "form": {
                "summary": "Form template shared",
                "value": {
                  "message": "Form shared successfully"
                }
              }
            }
          }
        }
      },
      "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": {
      "BaseReceiver": {
        "type": "object",
        "required": [
          "name",
          "email"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the person",
            "minLength": 1,
            "maxLength": 256,
            "example": "Jane Doe",
            "pattern": "^[\\s\\S]{1,256}$"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email of the person, it will send an email to the customer for signing",
            "minLength": 3,
            "maxLength": 320,
            "example": "jane.doe@example.com",
            "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
          },
          "message": {
            "type": "string",
            "description": "Optional: Custom message for this receiver. If empty, uses message from mailData",
            "maxLength": 5000,
            "example": "Hi Jane, please review and sign.",
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,5000}$"
          },
          "subject": {
            "type": "string",
            "description": "Optional: Custom subject for this receiver. If empty, uses subject from mailData",
            "maxLength": 200,
            "example": "Please sign the NDA",
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,200}$"
          }
        },
        "additionalProperties": false
      },
      "PDFTemplateReceiver": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseReceiver"
          },
          {
            "type": "object",
            "required": [
              "roleTitle"
            ],
            "properties": {
              "roleTitle": {
                "type": "string",
                "description": "Must exactly match the role added while uploading PDF template in BoloSign dashboard",
                "minLength": 1,
                "maxLength": 128,
                "example": "Employee",
                "pattern": "^[\\s\\S]{1,128}$"
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "FormTemplateReceiver": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseReceiver"
          }
        ]
      },
      "CustomVariable": {
        "type": "object",
        "required": [
          "varName",
          "varValue"
        ],
        "properties": {
          "varName": {
            "type": "string",
            "description": "Variable name in square brackets, must match template exactly",
            "pattern": "^\\[[\\s\\S]{1,126}\\]$",
            "minLength": 3,
            "example": "[name]",
            "maxLength": 128
          },
          "varValue": {
            "type": "string",
            "description": "Value to be assigned to the variable",
            "example": "Jane Doe",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          }
        },
        "additionalProperties": false
      },
      "MailData": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string",
            "description": "Global subject used when receiver-specific subject is not provided",
            "maxLength": 200,
            "example": "Document ready for signature",
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,200}$"
          },
          "message": {
            "type": "string",
            "description": "Global message used when receiver-specific message is not provided",
            "maxLength": 5000,
            "example": "Please sign the attached document.",
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,5000}$"
          }
        },
        "additionalProperties": false
      },
      "BaseTemplateSigningRequest": {
        "type": "object",
        "required": [
          "documentId"
        ],
        "properties": {
          "customVariables": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomVariable"
            },
            "description": "Optional: Custom variables to be replaced in the template",
            "maxItems": 1000
          },
          "mailData": {
            "$ref": "#/components/schemas/MailData"
          },
          "documentId": {
            "type": "string",
            "description": "ID of the document template",
            "minLength": 1,
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]{1,128}$"
          }
        },
        "additionalProperties": false
      },
      "PDFTemplateSigningRequest": {
        "title": "Sending a PDF template for signing",
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseTemplateSigningRequest"
          },
          {
            "type": "object",
            "required": [
              "signingType",
              "receiversList"
            ],
            "properties": {
              "signingType": {
                "type": "string",
                "enum": [
                  "PDF_TEMPLATE"
                ],
                "description": "Must be PDF_TEMPLATE",
                "maxLength": 12,
                "minLength": 12,
                "pattern": "^(PDF_TEMPLATE)$"
              },
              "receiversList": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "$ref": "#/components/schemas/PDFTemplateReceiver"
                },
                "description": "List of receivers who need to sign the document. `roleTitle` values must be unique.",
                "maxItems": 100
              },
              "pdfData": {
                "type": "string",
                "description": "Base64-encoded PDF data. You can send a different PDF while maintaining the template's field mappings. For example, if your template has 50 pages with signature fields, you can send a 30-page PDF that follows the same format. The system will automatically map fields to correct locations based on the original template, saving time by reusing the existing field configuration.",
                "pattern": "^data:application\\/pdf;base64,[A-Za-z0-9+/=\\s]+$",
                "example": "data:application/pdf;base64,JVBERi0xLjQK...",
                "maxLength": 20971520,
                "minLength": 28
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "FormTemplateSigningRequest": {
        "title": "Sending a form template for signing",
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseTemplateSigningRequest"
          },
          {
            "type": "object",
            "required": [
              "signingType",
              "receiversList"
            ],
            "properties": {
              "signingType": {
                "type": "string",
                "enum": [
                  "FORM_TEMPLATE"
                ],
                "description": "Must be FORM_TEMPLATE",
                "maxLength": 13,
                "minLength": 13,
                "pattern": "^(FORM_TEMPLATE)$"
              },
              "receiversList": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "$ref": "#/components/schemas/FormTemplateReceiver"
                },
                "description": "List of receivers who need to sign the document",
                "maxItems": 100
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "SignerInfo": {
        "type": "object",
        "properties": {
          "signerId": {
            "type": "string",
            "example": "s_01HZX",
            "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@]+$"
          },
          "name": {
            "type": "string",
            "example": "Jane Doe",
            "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?:\\/\\/.+$"
          }
        },
        "additionalProperties": false
      },
      "PDFSigningResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Document sent for signature successfully",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "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"
          },
          "createdDocumentId": {
            "type": "string",
            "description": "Mongo ObjectId of the created template PDF document. Pass this as `responseId` to `/void-document` and `/send-reminder` when `documentType=PDF_TEMPLATE`.",
            "example": "64f0a1b2c3d4e5f678901234",
            "maxLength": 24,
            "minLength": 24,
            "pattern": "^[a-fA-F0-9]{24}$"
          },
          "createdDocumentStatus": {
            "type": "string",
            "example": "SENT",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          },
          "signers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignerInfo"
            },
            "maxItems": 1000
          }
        },
        "additionalProperties": false
      },
      "FormSigningResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Form shared successfully",
            "maxLength": 1024,
            "minLength": 0,
            "pattern": "^[\\s\\S]{0,1024}$"
          }
        },
        "additionalProperties": false
      },
      "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
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```