openapi: 3.1.0 info: version: 1.0.0 title: Lumin API Reference description: | The Lumin API Reference provides a comprehensive set of tools to integrate document workflows — including editing, eSignatures, and automation — into your applications. Useful links: - [Document Repository](https://github.com/luminpdf/luminsign-docs) - [API Definition](https://github.com/luminpdf/luminsign-docs/blob/main/openapi.yaml) - [Authentication Guide](/tabs/guides/authentication/overview) termsOfService: https://www.luminpdf.com/terms-of-use/ contact: name: API Support email: integration@luminpdf.com url: https://help.luminpdf.com servers: - url: https://api.luminpdf.com/v1 description: Production server tags: - name: Signature Requests description: Everything about Signature Requests - name: Users description: Everything about Users - name: Templates description: Everything about Templates - name: Documents description: Everything about Documents - name: Workspaces description: Everything about Workspaces - name: Agreements description: Everything about Agreements paths: /signature_request/{signature_request_id}: get: summary: Get Signature Request description: Returns the information of the signature request. security: - ApiKey: [] - BearerAuth: - "sign:requests.read" - BearerAuth: - "sign:requests" tags: - Signature Requests parameters: - in: path name: signature_request_id schema: type: string required: true description: ID of the signature request. responses: "200": description: Returns the information of the signature request. content: application/json: schema: type: object required: - signature_request properties: signature_request: description: Contains information about a signature request. $ref: "#/components/schemas/SignatureRequest" "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" patch: summary: Update Signature Request description: | Update the due date of an existing signature request. Update the **due date** (`expires_at`) of an existing signature request **only when**: - The request **status** is `NEED_TO_SIGN` or `WAITING_FOR_OTHERS`, and - The caller is the **creator** of the signature request. Requests in any **terminal or final status** (e.g., `APPROVED`, `REJECTED`, `FAILED`, `CANCELLED`, `WAITING_FOR_PROCESSING`) **cannot** be updated. security: - ApiKey: [] - BearerAuth: - "sign:requests" tags: - Signature Requests parameters: - in: path name: signature_request_id schema: type: string required: true description: ID of the signature request. requestBody: content: application/json: schema: $ref: "#/components/schemas/SignatureRequestUpdateRequest" example: expires_at: 1927510980000 responses: "200": description: Returns the updated signature request. content: application/json: schema: type: object properties: signature_request: description: Signature request details with the updated data. $ref: "#/components/schemas/SignatureRequest" example: signature_request: signature_request_id: "1234567890" title: Title Here created_at: 1756887739247 expires_at: 1927510980000 status: WAITING_FOR_OTHERS "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /signature_request/send: post: summary: Send Signature Request description: Creates and sends a new signature request with the submitted documents. security: - ApiKey: [] - BearerAuth: - "sign:requests" tags: - Signature Requests requestBody: content: application/json: schema: $ref: "#/components/schemas/SignatureRequestDTO" responses: "201": description: Returns the information of the created signature request. content: application/json: schema: $ref: "#/components/schemas/SignatureRequestCreateResponse" "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /signature_request/send-from-template: post: summary: Send Signature Request from Template description: Creates and sends a new signature request from a template with the submitted template data. security: - ApiKey: [] - BearerAuth: - "sign:requests" - templates tags: - Signature Requests requestBody: content: application/json: schema: $ref: "#/components/schemas/SignatureRequestFromTemplateDTO" responses: "201": description: Returns the information of the created signature request. content: application/json: schema: $ref: "#/components/schemas/SignatureRequestCreateResponse" "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /signature_request/{signature_request_id}/signing-link: post: operationId: get-signing-link summary: Get Signing Link description: | Returns a signing link for an existing signature request. This enables presenting signing links within your own applications (mobile apps, web portals, etc.) instead of relying solely on email-based signing flows. security: - ApiKey: [] - BearerAuth: - "sign:requests" tags: - Signature Requests parameters: - in: path name: signature_request_id schema: type: string required: true description: ID of the signature request. requestBody: content: application/json: schema: type: object required: - signer_email properties: signer_email: type: string format: email description: Email address of the signer whose signing link should be generated. example: signer_email: tenant@example.com responses: "200": description: Signing link generated successfully. content: application/json: schema: type: object required: - view_url - signer_email - status properties: view_url: type: string description: The signing URL that the signer can use to view and sign the document. signer_email: type: string description: Email address of the signer. status: type: string description: Current signing status of the signer. enum: - NEED_TO_SIGN - APPROVED - WAITING_FOR_OTHERS - REJECTED - FAILED - WAITING_FOR_PROCESSING example: view_url: "https://sign.luminpdf.com/auth?mode=view-contract&token=8647b08b..." signer_email: tenant@example.com status: NEED_TO_SIGN "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /signature_request/{signature_request_id}/signing-session: post: operationId: create-signing-session summary: Create Signing Session description: | Returns a short-lived embedded-signing session URL (`sign_url`) for a single recipient on an existing signature request. Load this URL into the [`@luminpdf/lumin-embed-signing-sdk`](https://www.npmjs.com/package/@luminpdf/lumin-embed-signing-sdk?activeTab=readme) iframe to render the signing experience inline. Each session is scoped to one `signature_request_id` + `signer_email` pair. The signature request must have been created via the public API (`/signature_request/send` or `/signature_request/send-from-template`). For redirect or hosted signing flows, use [Get Signing Link](/tabs/api-reference/api/signature-requests/get-signing-link) instead. See the [Embedded Signing walkthrough](/tabs/guides/walkthroughs/embedded-signing) for integration steps and domain verification requirements. security: - ApiKey: [] - BearerAuth: - "sign:requests" tags: - Signature Requests parameters: - in: path name: signature_request_id schema: type: string required: true description: ID of an existing signature request that was created via the public API (`/signature_request/send` or `/signature_request/send-from-template`). requestBody: required: true content: application/json: schema: type: object required: - signer_email properties: signer_email: type: string description: Email address of the recipient this session is being issued for. Must be a recipient (signer/viewer) already attached to the signature request. expiry: type: integer description: | How long the returned `sign_url` remains valid, in milliseconds from issue time. **Default:** `900000` (15 minutes) **Accepted range:** `300000` – `3600000` (5 minutes – 1 hour, inclusive). Shorter values are intended for security-sensitive host apps. default: 900000 minimum: 300000 maximum: 3600000 example: signer_email: signer1@example.com expiry: 900000 responses: "200": description: Embedded-signing session created successfully. content: application/json: schema: type: object required: - sign_url - signer_email - expires_at - status properties: sign_url: type: string description: Short-lived URL the Embed Signing SDK loads into its iframe. Includes a single-use session token bound to `signature_request_id` and `signer_email`. signer_email: type: string description: Echoes the recipient this session was issued for. expires_at: type: integer description: Absolute expiry of `sign_url`. After this time the SDK will receive an `expire` event and the URL must be re-issued. status: type: string description: Current signing status of the recipient at issue time. enum: - NEED_TO_SIGN - WAITING_FOR_OTHERS example: sign_url: "https://sign.luminpdf.com/embed?session=8647b08b..." signer_email: signer1@example.com expires_at: 1927510980694 status: NEED_TO_SIGN "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /signature_request/cancel/{signature_request_id}: put: summary: Cancel Signature Request description: Cancel a signature request. security: - ApiKey: [] - BearerAuth: - "sign:requests" tags: - Signature Requests parameters: - in: path name: signature_request_id schema: type: string required: true description: ID of the signature request. responses: "200": description: Returns the information of the cancelled signature request. content: application/json: schema: type: object properties: signature_request_id: type: string description: The unique identifier for the signature request. status: type: string description: The status of the signature request. enum: - CANCELLED "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /signature_request/remind/{signature_request_id}: post: operationId: send-reminder-emails summary: Send Reminder Emails description: | Send reminder emails to selected signers under a signature request whose signer status is `NEED_TO_SIGN`. **Notes:** - Reminders sent to signers who already signed will be ignored (no email sent). - You can send reminders to up to 10 reminders per signer per day. security: - ApiKey: [] - BearerAuth: - "sign:requests" tags: - Signature Requests parameters: - in: path name: signature_request_id schema: type: string required: true description: ID of the signature request requestBody: content: application/json: schema: $ref: "#/components/schemas/SignatureRequestRemindRequest" example: emails: - john@example.com - jane@example.com responses: "200": description: Returns signature request details and per-email reminder results. content: application/json: schema: type: object required: - signature_request - reminders properties: signature_request: description: Contains information about a signature request. $ref: "#/components/schemas/SignatureRequest" reminders: type: array description: List of reminder email results for requested signer emails. items: $ref: "#/components/schemas/ReminderResult" example: signature_request: signature_request_id: "696d007913f3b8..." title: Signature request created_at: 1768751225657 expires_at: 1927510980694 status: WAITING_FOR_OTHERS signers: - name: John Doe email_address: john@example.com status: WAITING_FOR_OTHERS is_approved: true group: 1 - name: Jane Doe email_address: jane@example.com status: NEED_TO_SIGN is_approved: false group: 2 updated_at: 1768751357064 details_url: "https://sign.luminpdf.com/auth?mode=view-contract&token=8647b08b..." signing_type: ORDER reminders: - email: john@example.com signer_status: WAITING_FOR_OTHERS email_status: BOUNCE - email: jane@example.com signer_status: NEED_TO_SIGN email_status: SENT "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /signature_request/{signature_request_id}/file: get: summary: Get Signature Request File description: | Obtain the file of the Signature Request by id. This endpoint supports returning different types of files: - The **agreement** itself - The **Certificate of Completion (CoC)** - A **merged PDF** which combines both the agreement and the CoC **Preconditions by file type:** - For `agreement` file type: None - For `coc` file type: Requires the status to be **APPROVED** and a certificate must exist for that request - For `merged` file type: Requires the status to be **APPROVED** and both artifacts must exist. Lazy-generation is not performed for legacy requests, and developers should see errors in such cases. security: - ApiKey: [] - BearerAuth: - "sign:requests.read" - BearerAuth: - "sign:requests" tags: - Signature Requests parameters: - in: path name: signature_request_id schema: type: string required: true description: ID of the Signature Request. - in: query name: type schema: type: string enum: [agreement, coc, merged] default: agreement required: false description: | Which artifact to return: - `agreement`: The completed/signed agreement PDF - `coc`: The Certificate of Completion PDF - `merged`: A single PDF with agreement **followed by** the CoC responses: "200": description: Returns the downloadable file of the Signature Request. content: application/json: schema: type: object properties: signed_url: type: string description: Signed HTTPS URL to the requested artifact. Expires in 30 minutes. expires_at: type: integer format: unix-epoch description: Unix epoch timestamp (in seconds) indicating when `signed_url` will no longer work. example: signed_url: "https://files.luminpdf.com/download/nda-acmecorp-abc123.pdf?expires=20..." expires_at: 1766726700 application/pdf: schema: type: string format: binary "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /user/info: get: summary: Get User Information description: Get information of current user security: - ApiKey: [] - BearerAuth: - profile.read tags: - Users responses: "200": description: Returns the information of the current user. content: application/json: schema: type: object required: - user properties: user: description: Information of current user. $ref: "#/components/schemas/User" "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /templates: get: summary: List Templates description: | Returns a paginated list of templates in a Lumin Workspace, including AgreementGen, Sign and PDF templates. security: - ApiKey: [] - BearerAuth: - templates tags: - Templates parameters: - name: page in: query description: Specify which page of the dataset to return (min = 1). required: true example: 1 schema: type: integer minimum: 1 - name: limit in: query description: "Specify how many templates to return: one of 10, 25, 50." required: true example: 25 schema: type: integer enum: [10, 25, 50] - name: X-Lumin-API-Version in: header description: API version header schema: type: string default: "1.1" required: true responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/TemplateListResponse" example: page: 1 limit: 25 total_count: 3 data: - template_id: sign_123456 type: pdf name: Mutual NDA created_at: 1748456885430 updated_at: 1748456885430 - template_id: ag_456789 type: lumin name: Lease Agreement created_at: 1748456885430 updated_at: 1748456885430 - template_id: pdf_456789 type: pdf name: Onboarding Form created_at: 1748456885430 updated_at: 1748456885430 "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /templates/{template_id}: get: summary: Get Template Details description: | Returns essential template details for a specific template. security: - ApiKey: [] - BearerAuth: - templates tags: - Templates parameters: - in: path name: template_id schema: type: string required: true description: ID of the template. responses: "200": description: Returns the template details. content: application/json: schema: $ref: "#/components/schemas/TemplateDetail" examples: sign-template: summary: Sign template value: template_id: sign_123456 type: pdf name: Mutual NDA signing_type: ORDER signer_roles: - name: Tenant group: 1 - name: Client group: 2 tags: - name: owner.name type: merge_tag is_required: true fields: - name: hasCompleted type: checkbox is_required: true assigned_role: Tenant variables: [] collections: [] created_at: 1748456885430 updated_at: 1748456885430 ag-template: summary: AgreementGen template with collections value: template_id: ag_456789 type: lumin name: Sales Proposal signing_type: SAME_TIME signer_roles: - name: Client group: 1 tags: [] fields: - name: clientName type: text is_required: false assigned_role: Client variables: - name: Client.Name - name: Company.Address collections: - name: Opportunity.LineItems type: table_row_repeat variables: - Product.Name - Product.Quantity - Product.UnitPrice - Product.Total created_at: 1748456885430 updated_at: 1748456885430 "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /templates/{template_id}/generate-document: post: summary: Generate Document from Template description: | Creates a downloadable PDF document from an existing Lumin template. If a template contains **required tags or fields**, you must include these tags and fields in the request payload along with their corresponding values to generate the PDF document. security: - ApiKey: [] - BearerAuth: - templates tags: - Templates parameters: - in: path name: template_id schema: type: string required: true description: ID of the template to generate document from. requestBody: content: application/json: schema: type: object properties: tags: type: object description: | Key–value pairs for **Merge Tags** defined in the Sign template. Keys must match tag names. Values replace the corresponding tags and are rendered as plain text in the generated document. fields: type: object description: | Key–value pairs for **Form Fields** defined in the template. Keys must match field names. Values prefill the corresponding fields in the generated document. variables: type: object description: | Key–value pairs for **Variables** defined in the AgreementGen template. Keys must match variable names. Values prefill the corresponding variables and are rendered as plain text in the generated document. collections: type: object description: | Map of **collection name → array of record objects** used to expand table-scoped row-loop markers in the template. - Each key must match a collection name returned by [Get Template Details](/tabs/api-reference/api/templates/get-template-details) under `collections[].name`. - Each value is an ordered array of flat record objects; each record is a key–value map where keys match the collection's variable names and values are strings. - Records are rendered in array order. - Maximum 100 items per collection, and up to 50 collections per request. Applies to AgreementGen templates only. Ignored silently when the template `type` is not `lumin`. additionalProperties: type: array items: type: object additionalProperties: type: string document_name: type: string description: Optional name for the generated document. If omitted, the document name defaults to the template's name. example: tags: Client.Name: Acme Corp Effective.Date: "2025-08-01" fields: CustomerName: John Doe AgreeToTerms: true variables: Company.Name: ACME Corp Document.Name: NDA Document collections: Opportunity.LineItems: - Product.Name: Annual enterprise license Product.Quantity: "1" Product.UnitPrice: "$1,000.00" Product.Total: "$1,000.00" - Product.Name: Premium support package Product.Quantity: "1" Product.UnitPrice: "$500.00" Product.Total: "$500.00" document_name: My Contract responses: "200": description: Returns the generated document. content: application/json: schema: $ref: "#/components/schemas/DocumentGenerateResponse" example: document_name: NDA_AcmeCorp signed_url: https://files.luminpdf.com/download/nda-acmecorp-abc123.pdf?expires=2025-08-24T10:45:00Z expires_at: 1766726700 application/pdf: schema: type: string format: binary "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /documents: post: summary: Create Document description: | Create and save a PDF file in the user's Workspace. The document can be created using one of two methods: - **file-upload** — Import from a file (PDF or other supported formats). - **template** — Create from a PDF template (only templates with `pdf_` prefix are supported). The document can be saved to: - The Workspace's shared document list, optionally inside a folder - A specific Space's shared document list, optionally inside a folder - The user's Personal document list **Supported file formats (for file-upload):** PDF, DOCX, XLSX, PPTX, DOC, XLS, PNG, JPEG/JPG **File size limits:** - Free plans: 20 MB - Paid plans: 200 MB security: - ApiKey: [] - BearerAuth: - "pdf:files" tags: - Documents requestBody: content: application/json: schema: $ref: "#/components/schemas/DocumentCreateRequest" examples: upload-workspace: summary: File upload to Workspace value: method: file-upload document_name: Patient Form location: type: workspace folder_id: "123456" document_data: file_url: https://files.luminpdf.com/download/nda-acmecorp-abc123.pdf upload-space: summary: File upload to Space value: method: file-upload document_name: Q4 Sales Report location: type: space space_id: "69d74983d0cbaa0977be7997" folder_id: "789012" document_data: file_url: https://my-bucket.s3.amazonaws.com/docs/q4-report.pdf upload-personal: summary: File upload to Personal value: method: file-upload document_name: My Notes location: type: personal document_data: file_url: https://files.luminpdf.com/download/notes-abc123.pdf template-workspace: summary: PDF template to Workspace value: method: template document_name: Patient Information Form location: type: workspace folder_id: "123456" document_data: template_id: pdf_12312321 fields: Client.Name: Acme Corp Document.EffectiveDate: "2025-08-01" template-space: summary: PDF template to Space value: method: template document_name: Onboarding Packet location: type: space space_id: "69d74983d0cbaa0977be7997" document_data: template_id: pdf_98765432 fields: Employee.Name: Jane Doe Employee.StartDate: "2026-01-15" template-personal: summary: PDF template to Personal value: method: template document_name: Tax Worksheet location: type: personal document_data: template_id: pdf_55555555 fields: TaxYear: "2025" Filer.Name: John Smith multipart/form-data: schema: $ref: "#/components/schemas/DocumentCreateRequest" examples: upload-workspace: summary: File upload to Workspace value: method: file-upload document_name: Patient Form location: type: workspace folder_id: "123456" document_data: file_url: https://files.luminpdf.com/download/nda-acmecorp-abc123.pdf upload-space: summary: File upload to Space value: method: file-upload document_name: Q4 Sales Report location: type: space space_id: "69d74983d0cbaa0977be7997" folder_id: "789012" document_data: file_url: https://my-bucket.s3.amazonaws.com/docs/q4-report.pdf upload-personal: summary: File upload to Personal value: method: file-upload document_name: My Notes location: type: personal document_data: file_url: https://files.luminpdf.com/download/notes-abc123.pdf template-workspace: summary: PDF template to Workspace value: method: template document_name: Patient Information Form location: type: workspace folder_id: "123456" document_data: template_id: pdf_12312321 fields: Client.Name: Acme Corp Document.EffectiveDate: "2025-08-01" template-space: summary: PDF template to Space value: method: template document_name: Onboarding Packet location: type: space space_id: "69d74983d0cbaa0977be7997" document_data: template_id: pdf_98765432 fields: Employee.Name: Jane Doe Employee.StartDate: "2026-01-15" template-personal: summary: PDF template to Personal value: method: template document_name: Tax Worksheet location: type: personal document_data: template_id: pdf_55555555 fields: TaxYear: "2025" Filer.Name: John Smith responses: "201": description: Returns the summary of the created document. content: application/json: schema: $ref: "#/components/schemas/DocumentSummary" example: id: "doc_abc123def456" name: Patient Form created_at: 1748456885430 updated_at: 1748456885430 location: type: workspace workspace_id: "123456" folder_id: "789" size: 245678 mime_type: application/pdf preview_url: "https://app.luminpdf.com/viewer/doc_abc123def456" "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /documents/merge: post: summary: Merge Documents description: | Merge multiple documents into a single PDF file and return a temporary download URL. Documents can be specified by Lumin document IDs (must already exist in the current Workspace) or by publicly accessible file URLs. The merge order follows the order of items provided in the request. The merged file is **temporary** — the `signed_url` expires after 30 minutes. To persist the result, download the file and re-upload it via [Create Document](/tabs/api-reference/api/documents/create-document). **Supported source file types:** PDF, JPG, JPEG, PNG. **Limits:** Minimum 2 documents, maximum 20 documents per request. Combined total file size must not exceed 200 MB. Password-protected documents cannot be merged. **File URL restrictions:** Only URLs from allowed domains are accepted (`api.luminpdf.com`, `*.s3.amazonaws.com`, `*.s3.*.amazonaws.com`). Redirecting URLs are not supported. **Input priority:** If both `document_ids` and `file_urls` are provided, `document_ids` takes priority and `file_urls` is ignored. security: - ApiKey: [] - BearerAuth: - "pdf:files" tags: - Documents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DocumentMergeRequest" examples: document-ids: summary: Merge using document IDs value: document_ids: - "695dd6880d951f4de70a7c5d" - "683566387023be1b8285b64c" - "6915b2a24912dd85e2225da4" document_name: Combined Patient Forms file-urls: summary: Merge using file URLs value: file_urls: - https://files.luminpdf.com/download/abc123?token=xyz - https://my-bucket.s3.amazonaws.com/docs/form-2.pdf document_name: Combined Patient Forms responses: "200": description: Returns a temporary download URL for the merged PDF. content: application/json: schema: $ref: "#/components/schemas/DocumentOperationResponse" example: document_name: Combined Patient Forms_merged signed_url: https://files.luminpdf.com/download/merged-abc123?token=xyz789 expires_at: 1755526530000 application/pdf: schema: type: string format: binary "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /documents/compress: post: summary: Compress Document description: | Compress a PDF document to reduce its file size and return a temporary download URL. The document can be specified by a Lumin document ID or by a publicly accessible file URL. The compressed file is **temporary** — the `signed_url` expires after 30 minutes. To persist the result, download the file and re-upload it via [Create Document](/tabs/api-reference/api/documents/create-document). **Supported file type:** PDF only. **Plan restrictions:** - **Pro / Business** plans: compress files up to 500 MB; access to both `standard` and `maximum` compression levels. - **Other plans:** compress files up to 20 MB; `standard` compression level only. **Absolute file size limit:** 500 MB regardless of plan. Password-protected documents cannot be compressed. **File URL restrictions:** Only URLs from allowed domains are accepted (`api.luminpdf.com`, `*.s3.amazonaws.com`, `*.s3.*.amazonaws.com`). Redirecting URLs are not supported. **Input priority:** If both `document_id` and `file_url` are provided, `document_id` takes priority and `file_url` is ignored. security: - ApiKey: [] - BearerAuth: - "pdf:files" tags: - Documents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DocumentCompressRequest" examples: standard: summary: Standard compression value: document_id: "695dd6880d951f4de70a7c5d" compression_level: standard maximum: summary: Maximum compression with options value: document_id: "695dd6880d951f4de70a7c5d" compression_level: maximum document_name: NDA Compressed options: image_dpi: 72 embed_fonts: true subset_fonts: true remove_annotations: true remove_metadata: false responses: "200": description: Returns a temporary download URL for the compressed PDF. content: application/json: schema: $ref: "#/components/schemas/DocumentOperationResponse" example: document_name: NDA Compressed_compressed signed_url: https://files.luminpdf.com/download/compressed-abc123?token=xyz789 expires_at: 1755526530000 application/pdf: schema: type: string format: binary "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /documents/split: post: summary: Split Document description: | Split or extract pages from a PDF document into one or more output files and return a temporary download URL. The document can be specified by a Lumin document ID or by a publicly accessible file URL. Two split methods are supported: - `ranges` — Extract specific page ranges into separate output files (e.g., pages 1–3 as one file, pages 7–9 as another). - `fixed_size` — Split the document into equal-sized parts of N pages each. The output file is **temporary** — the `signed_url` expires after 30 minutes. To persist the result, download and re-upload via [Create Document](/tabs/api-reference/api/documents/create-document). **Output packaging:** - Single output file → the `signed_url` points directly to a PDF. - Multiple output files → the `signed_url` points to a ZIP archive containing all PDFs. Password-protected documents cannot be split. **File URL restrictions:** Only URLs from allowed domains are accepted (`api.luminpdf.com`, `*.s3.amazonaws.com`, `*.s3.*.amazonaws.com`). Redirecting URLs are not supported. **Input priority:** If both `document_id` and `file_url` are provided, `document_id` takes priority and `file_url` is ignored. security: - ApiKey: [] - BearerAuth: - "pdf:files" tags: - Documents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DocumentSplitRequest" examples: ranges: summary: Split by page ranges value: document_id: "695dd6880d951f4de70a7c5d" method: ranges ranges: - "1-3,5" - "7-9" - "12" fixed-size: summary: Split by fixed page count value: document_id: "695dd6880d951f4de70a7c5d" method: fixed_size pages_per_file: 5 document_name: Quarterly Report responses: "200": description: Returns a temporary download URL for the split result (PDF or ZIP). content: application/json: schema: $ref: "#/components/schemas/DocumentSplitResponse" example: signed_url: https://files.luminpdf.com/download/split-abc123?token=xyz789 expires_at: 1755526530000 "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /documents/add-password: post: summary: Add Password description: | Add or change password protection on a PDF document and return the encrypted file as a temporary download URL. The document can be specified by a Lumin document ID or by a publicly accessible file URL. - If the document has **no password**, it will be encrypted with the provided `password`. - If the document **already has a password**, provide `current_password` to authorize the change, and `password` for the new one. The output file is **temporary** — the `signed_url` expires after 30 minutes. To persist the result, download and re-upload via [Create Document](/tabs/api-reference/api/documents/create-document). **Supported file type:** PDF only. **Plan restrictions:** Available on **Business** plans only. **Password requirements:** 4–32 characters. **File URL restrictions:** Only URLs from allowed domains are accepted (`api.luminpdf.com`, `*.s3.amazonaws.com`, `*.s3.*.amazonaws.com`). Redirecting URLs are not supported. **Input priority:** If both `document_id` and `file_url` are provided, `document_id` takes priority and `file_url` is ignored. security: - ApiKey: [] - BearerAuth: - "pdf:files" tags: - Documents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DocumentAddPasswordRequest" examples: add-password: summary: Add password to unprotected document value: document_id: "695dd6880d951f4de70a7c5d" password: "YOUR_PDF_PASSWORD" change-password: summary: Change existing password value: document_id: "695dd6880d951f4de70a7c5d" password: "YOUR_NEW_PDF_PASSWORD" current_password: "YOUR_CURRENT_PDF_PASSWORD" responses: "200": description: Returns a temporary download URL for the password-protected PDF. content: application/json: schema: $ref: "#/components/schemas/DocumentOperationResponse" example: document_name: protected_Patient Information Form.pdf signed_url: https://files.luminpdf.com/download/pw-abc123?token=xyz789 expires_at: 1755526530000 application/pdf: schema: type: string format: binary "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /documents/remove-password: post: summary: Remove Password description: | Remove password protection from a PDF document and return the unprotected file as a temporary download URL. The document can be specified by a Lumin document ID or by a publicly accessible file URL. The document must currently be password-protected. The output file is **temporary** — the `signed_url` expires after 30 minutes. To persist the result, download and re-upload via [Create Document](/tabs/api-reference/api/documents/create-document). **Supported file type:** PDF only. **File URL restrictions:** Only URLs from allowed domains are accepted (`api.luminpdf.com`, `*.s3.amazonaws.com`, `*.s3.*.amazonaws.com`). Redirecting URLs are not supported. **Input priority:** If both `document_id` and `file_url` are provided, `document_id` takes priority and `file_url` is ignored. security: - ApiKey: [] - BearerAuth: - "pdf:files" tags: - Documents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DocumentRemovePasswordRequest" example: document_id: "695dd6880d951f4de70a7c5d" current_password: "YOUR_CURRENT_PDF_PASSWORD" responses: "200": description: Returns a temporary download URL for the unprotected PDF. content: application/json: schema: $ref: "#/components/schemas/DocumentOperationResponse" example: document_name: unprotected_Patient Information Form.pdf signed_url: https://files.luminpdf.com/download/pw-def456?token=abc123 expires_at: 1755526530000 application/pdf: schema: type: string format: binary "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /documents/summarize: post: summary: Summarize Document description: | Generate a concise AI-powered summary of a PDF document's text content. The document can be specified by a Lumin document ID or by a publicly accessible file URL. **Supported file type:** PDF only. **Supported languages:** English, Spanish, French, Vietnamese, Portuguese. **Content requirements:** - The document must contain extractable text (not scanned images). - Minimum content: 50 words. - Maximum content: 48,000 characters (including spaces). **Rate limits:** - Pro, Business, Old Enterprise plans: 200 requests/day/user. - Other plans: 100 requests/lifetime. **Caching:** Summaries are cached on the server. If the document has not been modified since the last summarization, the cached summary is returned without consuming a rate-limit token. Use `regenerate: true` to bypass the cache and produce a fresh summary. Password-protected documents cannot be summarized. **File URL restrictions:** Only URLs from allowed domains are accepted (`api.luminpdf.com`, `*.s3.amazonaws.com`, `*.s3.*.amazonaws.com`). Redirecting URLs are not supported. **Input priority:** If both `document_id` and `file_url` are provided, `document_id` takes priority and `file_url` is ignored. security: - ApiKey: [] - BearerAuth: - "pdf:files" tags: - Documents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DocumentSummarizeRequest" examples: summarize: summary: Summarize a document value: document_id: "695dd6880d951f4de70a7c5d" regenerate: summary: Force regeneration value: document_id: "695dd6880d951f4de70a7c5d" regenerate: true responses: "200": description: Returns the AI-generated summary. content: application/json: schema: $ref: "#/components/schemas/DocumentSummarizeResponse" example: document_id: "695dd6880d951f4de70a7c5d" document_name: Patient Information Form.pdf summary: This document is a patient information form for a prescription medication. It collects personal details including name, date of birth, address, and insurance information. language: en character_count: 12480 cached: false remaining_requests: 7 "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /documents/translate: post: summary: Translate Document description: | Translate a PDF document into a target language while preserving the original formatting, layout, and images. The API auto-detects the source language, translates the text content, and returns a temporary download URL for the translated file. The document can be specified by a Lumin document ID or by a publicly accessible file URL. **Supported file type:** PDF only. **Page limit:** Maximum 40 pages per translation request. Optionally specify a page range to translate a subset. **Rate limit:** 20 translation requests per user per day. **Concurrency:** One document at a time per user. If a translation is already in progress, subsequent requests are rejected. **Output formats:** `pdf` (default), `html`. **Security note:** When `output_format` is `html`, the returned content must be sanitized before injecting into a DOM. Use a trusted HTML sanitizer (e.g. [DOMPurify](https://github.com/cure53/DOMPurify)) to prevent XSS. Password-protected documents cannot be translated. **File URL restrictions:** Only URLs from allowed domains are accepted (`api.luminpdf.com`, `*.s3.amazonaws.com`, `*.s3.*.amazonaws.com`). Redirecting URLs are not supported. **Input priority:** If both `document_id` and `file_url` are provided, `document_id` takes priority and `file_url` is ignored. security: - ApiKey: [] - BearerAuth: - "pdf:files" tags: - Documents requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DocumentTranslateRequest" examples: full-document: summary: Translate entire document value: document_id: "695dd6880d951f4de70a7c5d" target_language: vi page-range: summary: Translate specific pages to HTML value: document_id: "695dd6880d951f4de70a7c5d" target_language: ja pages: "1-5,8,12-15" output_format: html document_name: Contract_Japanese responses: "200": description: Returns a temporary download URL for the translated file. content: application/json: schema: $ref: "#/components/schemas/DocumentTranslateResponse" example: signed_url: https://files.luminpdf.com/download/translate-abc123?token=xyz789 expires_at: 1755526530000 output_format: pdf detected_language: en target_language: vi document_name: vi_rental_agreement.pdf page_count: 12 remaining_requests: 17 "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /workspaces/info: get: summary: Get Workspace Information description: Return information of the authorized Workspace. security: - ApiKey: [] - BearerAuth: - workspaces.read - BearerAuth: - workspaces tags: - Workspaces responses: "200": description: Returns the information of the authorized Workspace. content: application/json: schema: $ref: "#/components/schemas/WorkspaceInfo" "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /workspaces/members: get: summary: Get Workspace Members description: Return a paginated list of members in a Workspace. security: - ApiKey: [] - BearerAuth: - workspaces.read - BearerAuth: - workspaces tags: - Workspaces parameters: - name: page in: query description: Specify which page of the dataset to return (min = 1). required: true example: 1 schema: type: integer minimum: 1 - name: limit in: query description: "Specify how many records to return: one of 10, 25, 50." required: true example: 25 schema: type: integer enum: [10, 25, 50] responses: "200": description: Returns the list of members in the Workspace. content: application/json: schema: $ref: "#/components/schemas/WorkspaceMembersResponse" example: page: 1 limit: 25 total_count: "123" data: - user_id: "655f..." email: alice@example.com name: Alice role: owner joined_at: 1748456885430 last_active_at: 1748456885430 - user_id: "655f..." email: bob@example.com name: Bob role: admin joined_at: 1748456885430 last_active_at: 1748456885430 - user_id: "655f..." email: carol@example.com name: Carol role: member joined_at: 1748456885430 last_active_at: 1748456885430 "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /workspaces/spaces: get: summary: List Spaces description: Return a paginated list of Spaces within the authorized Workspace. security: - ApiKey: [] - BearerAuth: - workspaces.read - BearerAuth: - workspaces tags: - Workspaces parameters: - name: page in: query description: Specify which page of the dataset to return (min = 1). schema: type: integer minimum: 1 default: 1 required: false - name: limit in: query description: "Specify how many records to return per page: one of 10, 25, 50." schema: type: integer enum: [10, 25, 50] default: 25 required: false responses: "200": description: Returns the list of Spaces in the Workspace. content: application/json: schema: $ref: "#/components/schemas/SpacesListResponse" example: page: 1 limit: 25 total_count: 3 data: - space_id: "69d74983d0cbaa0977be7997" name: Sales Team role_of_user: admin total_members: 12 created_at: "2026-04-09T06:38:59.381Z" - space_id: "68595b53e8013297be427871" name: Engineering role_of_user: member total_members: 8 created_at: "2025-12-01T10:15:30.000Z" - space_id: "668b6900aa86960c33b24147" name: Partner Program role_of_user: member total_members: 5 created_at: "2025-07-08T03:54:17.521Z" "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" post: summary: Create Space description: | Create a new Space within the authorized Workspace. **Partial success (member invites):** The Space is created when Space-level checks pass. - Each object in `members` is evaluated independently. - Entries that cannot be invited (for example, the user is not an active Workspace member or the account is ineligible) are **skipped** rather than failing the whole request. - If any entry was skipped, an optional aggregate `member_invite_notice` is included in the response. **Member payload:** - Invitees are identified by `user_id` only (plus `role`). - Valid `user_id` values are the same users returned by [Get Workspace Members](/tabs/api-reference/api/workspaces/get-workspace-members) for this Workspace. - Any other unknown property on a `members[]` object is silently ignored. **Space creation cap:** A Workspace's overall Space allowance is 2 on Free plans and up to 200 on paid plans. security: - ApiKey: [] - BearerAuth: - workspaces tags: - Workspaces requestBody: content: application/json: schema: $ref: "#/components/schemas/SpaceCreateRequest" example: name: Sales Team members: - user_id: "5eafc19053615900182f85c6" role: member responses: "200": description: Returns the newly created Space. content: application/json: schema: $ref: "#/components/schemas/SpaceCreateResponse" example: space: id: "69d74983d0cbaa0977be7997" name: Sales Team created_at: "2026-04-09T06:38:59.381Z" workspace_id: "60ab55f099ce3f001250857b" role_of_user: admin total_members: 2 owner: user_id: "655f01fadb5d4b9916422581" name: Jane Smith email: jane@example.com member_invite_notice: "Some members couldn't be added as they're not in this Workspace or aren't eligible." "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /agreements: post: summary: Create Agreement description: | Create a new AgreementGen document from a AgreementGen template. security: - ApiKey: [] - BearerAuth: - agreements tags: - Agreements requestBody: content: application/json: schema: $ref: "#/components/schemas/AgreementCreateRequest" example: method: template agreement_name: NDA Agreement agreement_data: template_id: ag_12312321 fields: Client.Name: Acme Corp Document.EffectiveDate: "2025-08-01" variables: Client.Name: Acme Corp Document.EffectiveDate: "2025-08-01" collections: Opportunity.LineItems: - Product.Name: Annual enterprise license Product.Quantity: "1" Product.UnitPrice: "$1,000.00" Product.Total: "$1,000.00" - Product.Name: Premium support package Product.Quantity: "1" Product.UnitPrice: "$500.00" Product.Total: "$500.00" linked_objects: - integration: salesforce entity_type: opportunity record_id: "0065g00000Vh123ABC" reference_url: "https://your-crm-instance.example.com/record/001XXXXXXXXX" signer_roles: - name: Tenant preassigned_signer: name: Alice Nguyen email_address: alice.nguyen@example.com - name: Landlord preassigned_signer: name: Brian Tran email_address: brian.tran@example.com responses: "201": description: Returns the Agreement summary object data content: application/json: schema: $ref: "#/components/schemas/AgreementSummary" "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /agreements/{agreement_id}/file: get: summary: Get Agreement File description: | Obtain a downloadable file or binary PDF data from an AgreementGen document. security: - ApiKey: [] - BearerAuth: - agreements tags: - Agreements parameters: - in: path name: agreement_id schema: type: string required: true description: ID of the AgreementGen document. responses: "200": description: Returns the downloadable file or binary PDF data of the AgreementGen document. content: application/json: schema: type: object properties: signed_url: type: string format: uri description: Signed HTTPS URL to download the agreement file. Expires in 30 minutes. expires_at: type: integer format: unix-epoch description: Unix epoch timestamp (in seconds) indicating when `signed_url` will no longer work. example: signed_url: "https://files.luminpdf.com/download/agreement-abc123.pdf?expires=2025-08-24T10:45:00Z" expires_at: 1766726700000 application/pdf: schema: type: string format: binary "4XX": description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" components: securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key description: > Provide your API key in the `X-API-Key` header, e.g., `X-API-Key: YOUR_API_KEY`. BearerAuth: type: oauth2 flows: authorizationCode: authorizationUrl: https://auth.luminpdf.com/oauth2/auth tokenUrl: https://auth.luminpdf.com/oauth2/token scopes: openid: Retrieve basic identity details (username, email, profile picture). offline_access: Request a refresh token for long-lived access. Private apps only. profile.read: View basic user profile information. workspaces: View and manage Workspaces and Spaces. workspaces.read: View information about the authenticated user's Workspace. templates: View and manage templates in a Workspace. "pdf:files": Create, edit, and delete PDF files in a Workspace. "pdf:files.read": Retrieve PDF documents stored in a Workspace. "sign:requests": Create, update, or view signature requests. "sign:requests.read": Retrieve signature requests. agreements: Create, update, or delete AgreementGen documents. description: > OAuth 2.0 authorization code flow. Provide your access token in the `Authorization` header, e.g., `Authorization: Bearer `. See the [OAuth 2.0 guide](/tabs/guides/authentication/oauth2) for details. schemas: Signer: type: object required: - email_address - name properties: email_address: type: string description: Email address of the signer. name: type: string description: Name of the signer. group: type: string description: | The signing order of signer for signature request with `signing_type` is ORDER. Required if `signing_type` is ORDER. Group starts at 1. Only signers in first group will receive email/notification, signers in subsequent groups will receive email/notification when all signers in previous group has signed. verification: type: object description: | Defines the identity verification method for a signer before they can complete the signing process. This allows stronger assurance of signer authenticity. **Requires a Digital Trust license** enabled at the Workspace level. If your Workspace is not licensed, including this field will return a `403 verification_not_licensed` error. Contact your Lumin account manager to enable Digital Trust. properties: method: type: string enum: [vc] description: | The verification method used. Required when the `verification` object is present. Possible values: `vc` – Verifiable Credential (via mDocs) payload: type: object description: | Payload parameters required by the verification method. Required when the `verification` object is present. properties: doc_type: type: string enum: [driver_license, photo_id, nz_business_passport] description: | The type of credential requested from the signer. - If **defined** → VC verification is **required** for this signer. - If **omitted** → VC verification is **optional** for this signer. Must be in the Workspace's `enabled_doc_types` list. claims: type: array description: | The specific attributes requested from the credential. Required when the `verification` object is present. **Required claims (always):** - `given_name` – Signer's given name, validated against the verified credential - `family_name` – Signer's family name, validated against the verified credential **Optional claims:** - `issuing_country` – Country where the credential was issued - `issuing_authority` – The issuing authority tied to the root certificate - `document_number` – The ID/number of the credential The provided list must be a subset of the Workspace's `required_claims`. items: type: string enum: [ given_name, family_name, issuing_country, issuing_authority, document_number, ] SignerWithRole: type: object required: - email_address - name properties: email_address: type: string description: Email address of the signer. name: type: string description: Name of the signer. signer_role: type: string description: | The name of the signer role defined in the template. Must match a signer role in the template. Required when the template has defined signer roles. verification: type: object description: | Defines the identity verification method for a signer before they can complete the signing process. This allows stronger assurance of signer authenticity. **Requires a Digital Trust license** enabled at the Workspace level. If your Workspace is not licensed, including this field will return a `403 verification_not_licensed` error. Contact your Lumin account manager to enable Digital Trust. properties: method: type: string enum: [vc] description: | The verification method used. Required when the `verification` object is present. Possible values: `vc` – Verifiable Credential (via mDocs) payload: type: object description: | Payload parameters required by the verification method. Required when the `verification` object is present. properties: doc_type: type: string enum: [driver_license, photo_id, nz_business_passport] description: | The type of credential requested from the signer. - If **defined** → VC verification is **required** for this signer. - If **omitted** → VC verification is **optional** for this signer. Must be in the Workspace's `enabled_doc_types` list. claims: type: array description: | The specific attributes requested from the credential. Required when the `verification` object is present. **Required claims (always):** - `given_name` – Signer's given name, validated against the verified credential - `family_name` – Signer's family name, validated against the verified credential **Optional claims:** - `issuing_country` – Country where the credential was issued - `issuing_authority` – The issuing authority tied to the root certificate - `document_number` – The ID/number of the credential The provided list must be a subset of the Workspace's `required_claims`. items: type: string enum: [ given_name, family_name, issuing_country, issuing_authority, document_number, ] Viewer: type: object required: - email_address - name properties: email_address: type: string description: Email address of the viewer. name: type: string description: Name of the viewer. SignatureRequest: type: object required: - signature_request_id - title - created_at - expires_at - details_url - status - signers - signing_type properties: signature_request_id: type: string description: The unique identifier for the signature request. title: type: string description: The title of the signature request. created_at: type: string description: The time the signature request was created. updated_at: type: string description: The time the signature request was last updated. expires_at: type: string description: The time the signature request will expire. details_url: type: string description: The url to view the signature request in the browser. status: type: string description: The status of the signature request. enum: - NEED_TO_SIGN - WAITING_FOR_OTHERS - APPROVED - REJECTED - WAITING_FOR_PROCESSING - FAILED - CANCELLED reason: type: string description: The reason for the status FAILED or REJECTED of the signature request. signing_type: type: string description: Recipient signing flow. enum: - SAME_TIME - ORDER signers: type: array items: properties: email_address: type: string description: Email address of the signer. name: type: string description: Name of the signer. group: type: number description: | The signing order of signer for the signature request with `signing_type` is `ORDER`. Required if `signing_type` is `ORDER`. Only signers in `1st Signers` group will receive email/notification, signers in subsequent groups will receive email/notification when all signers in previous group has signed. Group starts incrementing at 1. The default value for group always is 1 if `signing_type` is `SAME_TIME.` is_approved: type: boolean description: Whether the signer has approved the signature request. status: type: string description: The status of the Signer. enum: - NEED_TO_SIGN - APPROVED - WAITING_FOR_OTHERS - REJECTED - FAILED - WAITING_FOR_PROCESSING # - $ref: '#/components/schemas/Signer' # - type: object # properties: # is_approved: # type: boolean # description: Whether the Signer has approved the signature request. # status: # type: string # description: The status of the Signer. # enum: # - NEED_TO_SIGN # - APPROVED # - REJECTED # - WAITING_FOR_OTHERS description: The signers of the signature request. User: type: object required: - email - id - name properties: id: type: string description: The unique identifier for the user. email: type: string description: The email address of the user. name: type: string description: The name of the user. SignatureRequestDTO: type: object required: - signers - title - expires_at properties: file_url: type: string description: The URL of a single file to be downloaded and signed. This field is mutually exclusive with `file`, `files`, and `file_urls`. Only one of these fields should be provided in the request. file: type: string format: binary description: A single uploaded file to be sent for signature. This field is mutually exclusive with `file_url`, `files`, and `file_urls`. Only one of these fields should be provided in the request. file_urls: type: array description: An array of URLs of files to be downloaded and signed. This field is mutually exclusive with `file`, `files`, and `file_url`. Only one of these fields should be provided in the request. items: type: string files: type: array description: An array of uploaded files to be sent for signature. This field is mutually exclusive with `file`, `file_url`, and `file_urls`. Only one of these fields should be provided in the request. items: type: binary signers: type: array items: $ref: "#/components/schemas/Signer" description: Signers of the signature request. viewers: type: array items: $ref: "#/components/schemas/Viewer" description: Viewers of the signature request. title: type: string minLength: 1 maxLength: 255 description: The title of the signature request. expires_at: type: integer format: unix-epoch description: When the signature request will expire. This is a unix epoch timestamp (miliseconds). Should be later than today. use_text_tags: type: boolean description: Set to `true` to enable Text Tag parsing in your document. Your Text Tags will be converted into UI components for the user to interact with. Defaults to `false`. signing_type: type: string description: The signing order for the signature request. Defaults to `SAME_TIME`. enum: - SAME_TIME - ORDER custom_email: type: object description: Custom email content for the email sent to signers. properties: sender_email: type: string description: The email address of the sender. subject_name: type: string description: The subject of the email. title: type: string description: The title of the email. example: file_url: https://example.com/path/to/document.pdf title: Financial Year-End Report Authorization signers: - email_address: john.doe@example.com name: John Doe group: 1 verification: method: vc payload: doc_type: driver_license claims: - given_name - family_name - email_address: jane.doe@example.com name: Jane Doe group: 2 viewers: - email_address: jane.doe@example.com name: Jane Doe expires_at: 1927510980694 use_text_tags: false signing_type: ORDER SignatureRequestFromTemplateDTO: type: object required: - template_id - signers - title - expires_at properties: template_id: type: string description: ID of the template. ID needs to include the prefix returned by the template list endpoint. title: type: string minLength: 1 maxLength: 255 description: The title of the signature request. tags: type: object description: | Key–value pairs for **Merge Tags** defined in the Sign template. Keys must match tag names. Values replace the corresponding tags and are rendered as **plain text** in the sent agreement. fields: type: object description: | Key–value pairs for **Form Fields** defined in the template. Keys must match field names. Values prefill the corresponding fields in the sent agreement. variables: type: object description: | Key–value pairs for **Variables** defined in the AgreementGen template. Keys must match variable names. Values prefill the corresponding variables and are rendered as **plain text** in the sent agreement. collections: type: object description: | Map of **collection name → array of record objects** used to expand table-scoped row-loop markers in the template. - Each key must match a collection name returned by [Get Template Details](/tabs/api-reference/api/templates/get-template-details) under `collections[].name`. - Each value is an ordered array of flat record objects; each record is a key–value map where keys match the collection's variable names and values are strings. - Records are rendered in array order. - Maximum 100 items per collection, and up to 50 collections per request. Applies to AgreementGen templates only. Ignored silently when the resolved template `type` is not `lumin`. additionalProperties: type: array items: type: object additionalProperties: type: string signers: type: array items: $ref: "#/components/schemas/SignerWithRole" description: Signers of the signature request. viewers: type: array items: $ref: "#/components/schemas/Viewer" description: Viewers of the signature request. custom_email: type: object description: Custom email content for the email sent to signers. properties: sender_email: type: string description: The email address of the sender. subject_name: type: string description: The subject of the email. title: type: string description: The title of the email. expires_at: type: integer format: unix-epoch description: When the signature request will expire. This is a unix epoch timestamp (miliseconds). Should be later than today. example: template_id: sign_123 title: Mutual NDA Agreement tags: ClientName: ACME Corp EffectiveDate: "2026-01-01" ContractValue: "$50,000" fields: CustomerName: John Doe AgreeToTerms: true ContractDuration: 12 signers: - signer_role: Tenant email_address: tenant@acmecorp.com name: Jane Smith verification: method: vc payload: doc_type: driver_license claims: - given_name - family_name - issuing_country - issuing_authority - document_number - signer_role: Customer email_address: customer@example.com name: John Doe viewers: - email_address: legal@acmecorp.com name: Legal Team expires_at: 1927510980694 custom_email: sender_email: tenant@acmecorp.com subject_name: Mutual NDA Agreement from ACME Corp title: Mutual NDA Agreement from ACME Corp TemplateDTO: type: object required: - template_id properties: tags: type: object description: | Key–value pairs for **Merge Tags** defined in the template. Keys must match tag names. Values replace the corresponding tags and are rendered as plain text in the generated document. fields: type: object additionalProperties: oneOf: - type: string - type: boolean description: | Key–value pairs for **Form Fields** defined in the template. Keys must match field names. Values prefill the corresponding fields in the generated document. document_name: type: string description: Optional custom name for the generated document. Defaults to the template's name if omitted. description: | At least one of `tags` or `fields` may be required when the template defines required tags/fields. Template: type: object required: - template_id - name - tags - fields - created_at - updated_at properties: template_id: type: string description: The unique identifier for the template. name: type: string description: The name of the template. signing_type: allOf: - $ref: "#/components/schemas/SignatureRequest/properties/signing_type" - description: Recipient signing flow. signer_roles: type: array description: Signer roles defined in the template. items: type: object properties: name: type: string description: The name of the signer role. group: type: integer description: The signing order of signer for the signature request with `signing_type` is `ORDER`. tags: type: array description: Merge Tags embedded in the template. items: type: object properties: name: type: string description: The name/label of the tag. type: type: string description: The type of the text tag. enum: [merge_tag] is_required: type: boolean description: Whether the tag must be filled before completing the document. fields: type: array description: Form fields defined in the template. items: type: object properties: name: type: string description: The name/label of the form field. type: type: string description: The type of the form field. enum: [text, checkbox] is_required: type: boolean description: Whether the form field must be filled before completing the document. created_at: type: string description: The time the template was created. updated_at: type: string description: The time the template was last updated. TemplateListItem: type: object properties: template_id: type: string description: Unique identifier for the template type: type: string description: "Template file type. One of: pdf, lumin" enum: [pdf, lumin] name: type: string description: Name of the template created_at: type: integer format: unix-epoch description: The Unix timestamp when the template was first created. updated_at: type: integer format: unix-epoch description: The Unix timestamp of the last update to the template. TemplateDetail: type: object properties: template_id: type: string description: Unique identifier for the template type: type: string description: "Template file type. One of: pdf, lumin" enum: [pdf, lumin] name: type: string description: Name of the template signing_type: type: string description: | Defines how recipients are expected to sign: - ORDER: Signers sign in a specific sequence. - SAME_TIME: All signers can sign in parallel. AgreementGen and PDF templates currently only supports signing_type as SAME_TIME. enum: [ORDER, SAME_TIME] signer_roles: type: array description: Describes the signer roles defined in the template. items: type: object properties: name: type: string description: A label for the role (e.g., "Tenant", "Manager"). group: type: integer description: Indicates signing order group (e.g., 1 = sign first, 2 = sign second). tags: type: array description: | Merge tags embedded in the Sign template. items: type: object properties: name: type: string description: The label or identifier of the tag. type: type: string description: "Type of tag, one of: merge_tag" enum: [merge_tag] is_required: type: boolean description: Indicates whether the merge tag needs to be prefilled before the signature request can be completed. fields: type: array description: The form fields that appear in the template. items: type: object properties: name: type: string description: The label or identifier of the form field. type: type: string description: "Type of field, one of: text, checkbox" enum: [text, checkbox] is_required: type: boolean description: Indicates whether the assigned signer must complete the field before the signature request can be completed. assigned_role: type: string description: The role (as defined in the template) to which this field is assigned. If not set, the field may not be linked to a specific role and will be dismissed during signature request creation. variables: type: object description: | The variables defined in the AgreementGen template. properties: name: type: string description: The label or identifier of the variable. collections: type: array description: | Table-scoped collections referenced by row-loop markers in the template. Empty array (`[]`) when the template has no markers. Applies to AgreementGen templates only — returned as `[]` for Sign and PDF templates. items: $ref: "#/components/schemas/TemplateCollection" created_at: type: integer format: unix-epoch description: The Unix timestamp when the template was first created. updated_at: type: integer format: unix-epoch description: The Unix timestamp of the last update to the template. TemplateCollection: type: object properties: name: type: string description: | Collection identifier as declared in the template marker (e.g., `Opportunity.LineItems`). Use this value as the key in the `collections` object of the [Create Agreement](/tabs/api-reference/api/agreements/create-agreement), [Generate Document from Template](/tabs/api-reference/api/templates/generate-document-from-template), or [Send Signature Request from Template](/tabs/api-reference/api/signature-requests/send-signature-request-from-template) payloads. type: type: string description: | Marker scope the collection drives. - `table_row_repeat` — duplicates one or more body rows per item (`<>` / `<>`). enum: [table_row_repeat] variables: type: array description: | Variable names referenced inside the loop body (e.g., `Product.Name`, `Product.Quantity`). Callers should include these keys in each item object of the `collections.` array at generation time. Missing collection variables render as empty strings. items: type: string TemplateListResponse: type: object properties: page: type: integer description: The current page of results being returned. limit: type: integer description: The maximum number of template records shown per page (e.g., 10, 25, or 50). total_count: type: integer description: The total number of template records returned. data: type: array description: The list of templates returned. Each object contains full details about one template. items: $ref: "#/components/schemas/TemplateListItem" DocumentLocation: type: object required: - type properties: type: type: string description: "Location type." enum: [personal, space, workspace] space_id: type: string description: ID of a specific Space in the Workspace. Required if `type` = `space`. folder_id: type: string description: ID of a specific folder within the chosen location. DocumentDataFileUpload: type: object description: Payload for file-upload method. properties: file: type: string format: binary description: Upload binary file. Required if `file_url` not provided. file_url: type: string format: uri description: HTTPS URL to download the source file. Required if `file` not provided. DocumentDataTemplate: type: object description: Payload for template method. Only PDF templates (template_id with `pdf_` prefix) are supported. required: - template_id properties: template_id: type: string description: | Unique identifier of the PDF template. Obtainable from the Template list API. Only PDF templates (IDs starting with `pdf_` prefix) are supported for document creation. fields: type: object description: | Key–value pairs for **Form Fields** defined in the template. Keys must match field names. Values prefill the corresponding form fields in the generated document. Currently supports: **checkbox, text field**. DocumentCreateFileUploadRequest: type: object title: file-upload required: - method - document_name - location - document_data properties: method: type: string enum: [file-upload] description: Import from a file (PDF or other supported formats). document_name: type: string minLength: 1 maxLength: 255 description: Human-friendly title of the document (1–255 characters). location: $ref: "#/components/schemas/DocumentLocation" document_data: $ref: "#/components/schemas/DocumentDataFileUpload" DocumentCreateTemplateRequest: type: object title: template required: - method - document_name - location - document_data properties: method: type: string enum: [template] description: Create from a PDF template (only templates with `pdf_` prefix are supported). document_name: type: string minLength: 1 maxLength: 255 description: Human-friendly title of the document (1–255 characters). location: $ref: "#/components/schemas/DocumentLocation" document_data: $ref: "#/components/schemas/DocumentDataTemplate" DocumentCreateRequest: oneOf: - $ref: "#/components/schemas/DocumentCreateFileUploadRequest" - $ref: "#/components/schemas/DocumentCreateTemplateRequest" discriminator: propertyName: method mapping: file-upload: "#/components/schemas/DocumentCreateFileUploadRequest" template: "#/components/schemas/DocumentCreateTemplateRequest" DocumentSummary: type: object required: - id - name - created_at - updated_at - location - size - mime_type - preview_url properties: id: type: string description: Unique identifier of the document in Lumin. name: type: string description: Human-friendly name of the document. created_at: type: integer format: unix-epoch description: Unix timestamp (milliseconds) when the document was created. updated_at: type: integer format: unix-epoch description: Unix timestamp (milliseconds) when the document was last updated. location: type: object description: Where the document is stored. properties: type: type: string description: | One of: - `workspace` — Workspace's shared document list - `space` — Space's shared document list - `personal` — Personal document list enum: [workspace, space, personal] workspace_id: type: string description: ID of the Workspace that owns this document (derived from the auth token). space_id: type: string description: ID of the Space that contains the document if `location.type` is `space`. Blank otherwise. folder_id: type: string description: ID of the folder that contains the document, if any. Blank otherwise. size: type: integer description: Size of the PDF file in bytes. mime_type: type: string description: MIME type of the file (e.g. `application/pdf`). preview_url: type: string format: uri description: URL to open the document in Lumin's viewer. SignatureRequestUpdateRequest: type: object required: - expires_at properties: expires_at: type: integer format: unix-epoch description: The expiration time of the signature request, expressed as a Unix epoch timestamp in milliseconds. This value must represent a future point in time. SignatureRequestSummary: type: object required: - signature_request_id - created_at - status properties: signature_request_id: type: string description: The unique identifier for the signature request. created_at: type: string description: The time the signature request was created. status: type: string description: The status of the signature request. enum: - WAITING_FOR_PROCESSING - FAILED SignatureRequestCreateResponse: type: object required: - signature_request properties: signature_request: description: Contains information about a signature request. $ref: "#/components/schemas/SignatureRequestSummary" SignatureRequestRemindRequest: type: object required: - emails properties: emails: type: array description: List of emails to send reminder. items: type: string format: email ReminderResult: type: object required: - email - signer_status - email_status properties: email: type: string format: email description: The signer email that the reminder request targets. signer_status: type: string description: "The signer status at the time of sending the reminder. One of: NEED_TO_SIGN, APPROVED, REJECTED, WAITING_FOR_OTHERS" enum: [NEED_TO_SIGN, APPROVED, REJECTED, WAITING_FOR_OTHERS] email_status: type: string description: | Result of reminder email delivery attempt. - `SENT` – Sent an email successfully - `EXCEED_DAILY_LIMIT` – Email not sent due to daily limit (**10 emails/signer/day**) - `BOUNCE` – Email not sent because the signer already signed or is not in turn to sign enum: - SENT - EXCEED_DAILY_LIMIT - BOUNCE WorkspaceMember: type: object properties: user_id: type: string description: The unique identifier for the user. email: type: string description: The email address of the user. name: type: string description: The name of the user. role: type: string description: "Role of the member." enum: [owner, admin, member] joined_at: type: integer format: unix-epoch description: The time the user joined the Workspace. last_active_at: type: integer format: unix-epoch description: The time the user was last active in Lumin. WorkspaceInfo: type: object properties: id: type: string description: The unique identifier of the Workspace. name: type: string description: The name of the Workspace. owner: type: string description: The email address of the Workspace owner. created_at: type: integer format: unix-epoch description: The time the Workspace was created. user_role: type: string description: The role of the current user in the Workspace. enum: [owner, admin, member] total_members: type: integer description: The number of Workspace members. total_spaces: type: integer description: The number of Spaces in the Workspace. WorkspaceMembersResponse: type: object properties: page: type: integer description: The current page of results being returned. limit: type: integer description: The maximum number of records shown per page (e.g., 10, 25, or 50). total_count: type: string description: The total number of records returned for the request. data: type: array description: List of Workspace members returned for the requested page. items: $ref: "#/components/schemas/WorkspaceMember" Space: type: object properties: space_id: type: string description: The unique identifier of the Space. name: type: string description: The name of the Space. role_of_user: type: string description: The role of the authenticated user in this Space. enum: [admin, member] total_members: type: integer description: The total number of members in the Space. created_at: type: string format: date-time description: The timestamp when the Space was created (ISO 8601). SpacesListResponse: type: object properties: page: type: integer description: The current page of results being returned. limit: type: integer description: The maximum number of records shown per page (e.g., 10, 25, or 50). total_count: type: integer description: The total number of Spaces in the Workspace. data: type: array description: List of Spaces returned for the requested page. items: $ref: "#/components/schemas/Space" SpaceMemberInvite: type: object required: - user_id - role properties: user_id: type: string description: | Lumin user ID of the member to invite. Must correspond to a user returned by [Get Workspace Members](/tabs/api-reference/api/workspaces/get-workspace-members) for this Workspace. If the user is not an active Workspace member or fails other invite checks, this entry is skipped; the Space is still created and an aggregate `member_invite_notice` may be returned. role: type: string description: Role assigned to this member in the new Space. enum: [admin, member] SpaceCreateRequest: type: object required: - name properties: name: type: string minLength: 1 maxLength: 100 description: The name of the Space to create. members: type: array description: | Initial members to invite into the Space. If omitted, the Space is created with only the requesting user as owner. Ineligible entries are skipped; see `member_invite_notice` on the response. items: $ref: "#/components/schemas/SpaceMemberInvite" SpaceOwner: type: object properties: user_id: type: string description: The unique identifier of the Space owner. name: type: string description: The name of the Space owner. email: type: string description: The email address of the Space owner. SpaceDetail: type: object properties: id: type: string description: The unique identifier of the newly created Space. name: type: string description: The name of the Space. created_at: type: string format: date-time description: The timestamp when the Space was created (ISO 8601). workspace_id: type: string description: The ID of the parent Workspace this Space belongs to. role_of_user: type: string description: The role of the requesting user in the newly created Space (typically `admin`). enum: [admin, member] total_members: type: integer description: | Total members in the Space after this request (owner plus every `members` entry that was successfully invited). Skipped invitees are not counted. owner: $ref: "#/components/schemas/SpaceOwner" member_invite_notice: type: string description: | Optional. Omitted when every requested `members` entry was successfully invited. When present, at least one invitee was skipped (the Space was still created). SpaceCreateResponse: type: object required: - space properties: space: $ref: "#/components/schemas/SpaceDetail" DocumentGenerateResponse: type: object required: - document_name - signed_url - expires_at properties: document_name: type: string description: Name of the generated document (from input or default). signed_url: type: string format: uri description: Signed HTTPS URL to download the generated document. Expires in 30 minutes. expires_at: type: integer format: unix-epoch description: Unix epoch timestamp (in seconds) indicating when signed_url will no longer work. DocumentMergeRequest: type: object properties: document_ids: type: array description: | Ordered list of Lumin document IDs to merge. The order of IDs determines the page order in the output PDF. Required when `file_urls` is not provided. Provide 2–20 document IDs. To obtain document IDs, upload files to Lumin first using [Upload Document](/tabs/api-reference/api/documents/create-document). items: type: string file_urls: type: array description: | Ordered list of publicly accessible file URLs to merge. Only URLs from allowed domains are accepted. Required when `document_ids` is not provided. Ignored if `document_ids` is also provided. Provide 2–20 URLs. items: type: string format: uri document_name: type: string minLength: 1 maxLength: 255 description: Name of the merged output file. Defaults to `merged_{first document name}`. DocumentCompressRequest: type: object required: - compression_level properties: document_id: type: string description: | Lumin document ID of the PDF to compress. Required when `file_url` is not provided. Takes priority if both are provided. To obtain a document ID, upload the file to Lumin first using [Upload Document](/tabs/api-reference/api/documents/create-document). file_url: type: string format: uri description: | Publicly accessible URL of the PDF file to compress. Required when `document_id` is not provided. Ignored if `document_id` is also provided. compression_level: type: string enum: [standard, maximum] description: | Compression level. - `standard` — ~150 dpi images, removes non-essential bookmarks and unused metadata. Targets ≥ 30% file size reduction. - `maximum` — ~72–96 dpi images, strips all non-essential content. Targets ≥ 60% file size reduction. Requires Pro / Business plan. document_name: type: string minLength: 1 maxLength: 255 description: Name of the compressed output file. Defaults to `compressed_{original document name}`. options: $ref: "#/components/schemas/DocumentCompressOptions" DocumentCompressOptions: type: object description: Advanced compression settings. Only applicable when `compression_level` is `maximum`. properties: image_dpi: type: integer minimum: 72 maximum: 300 default: 96 description: Target resolution for downsampled color images. Lower values produce smaller files. embed_fonts: type: boolean default: true description: Keep fonts embedded in the file so it renders consistently. subset_fonts: type: boolean default: true description: Only include characters actually used in the document. Only applies when `embed_fonts` is `true`. remove_annotations: type: boolean default: false description: Remove all annotations (comments, highlights, etc.) from the file. remove_metadata: type: boolean default: false description: Remove outlines, bookmarks, and document info metadata. DocumentSplitRequest: type: object required: - method properties: document_id: type: string description: | Lumin document ID of the PDF to split. Required when `file_url` is not provided. Takes priority if both are provided. To obtain a document ID, upload the file to Lumin first using [Upload Document](/tabs/api-reference/api/documents/create-document). file_url: type: string format: uri description: | Publicly accessible URL of the PDF file to split. Required when `document_id` is not provided. Ignored if `document_id` is also provided. method: type: string enum: [ranges, fixed_size] description: | Split method. - `ranges` — Extract specific page ranges into separate files. - `fixed_size` — Split into parts of a fixed number of pages. ranges: type: array description: | List of page range expressions. Each entry produces one output file. Required when `method` is `ranges`. items: type: string pages_per_file: type: integer minimum: 1 description: | Number of pages per output file. Required when `method` is `fixed_size`. Must not produce more than 10,000 output files. document_name: type: string minLength: 1 maxLength: 255 description: Base name for the output files. Defaults to `extracted_{original document name}`. DocumentAddPasswordRequest: type: object required: - password properties: document_id: type: string description: | Lumin document ID of the PDF. Required when `file_url` is not provided. Takes priority if both are provided. To obtain a document ID, upload the file to Lumin first using [Upload Document](/tabs/api-reference/api/documents/create-document). file_url: type: string format: uri description: | Publicly accessible URL of the PDF file. Required when `document_id` is not provided. Ignored if `document_id` is also provided. document_name: type: string minLength: 1 maxLength: 255 description: Name of the output file. Defaults to `protected_{original document name}`. password: type: string minLength: 4 maxLength: 32 description: The new password to apply to the document. current_password: type: string description: The document's existing password. Required if the document is already password-protected. DocumentRemovePasswordRequest: type: object required: - current_password properties: document_id: type: string description: | Lumin document ID of the PDF. Required when `file_url` is not provided. Takes priority if both are provided. To obtain a document ID, upload the file to Lumin first using [Upload Document](/tabs/api-reference/api/documents/create-document). file_url: type: string format: uri description: | Publicly accessible URL of the PDF file. Required when `document_id` is not provided. Ignored if `document_id` is also provided. document_name: type: string minLength: 1 maxLength: 255 description: Name of the output file. Defaults to `unprotected_{original document name}`. current_password: type: string description: The document's current password. Required to authorize removal. DocumentSummarizeRequest: type: object properties: document_id: type: string description: | Lumin document ID of the PDF to summarize. Required when `file_url` is not provided. Takes priority if both are provided. To obtain a document ID, upload the file to Lumin first using [Upload Document](/tabs/api-reference/api/documents/create-document). file_url: type: string format: uri description: | Publicly accessible URL of the PDF file to summarize. Required when `document_id` is not provided. Ignored if `document_id` is also provided. regenerate: type: boolean default: false description: If `true`, bypass the cached summary and generate a fresh one. This counts against the rate limit. DocumentTranslateRequest: type: object required: - target_language properties: document_id: type: string description: | Lumin document ID of the PDF to translate. Required when `file_url` is not provided. Takes priority if both are provided. To obtain a document ID, upload the file to Lumin first using [Upload Document](/tabs/api-reference/api/documents/create-document). file_url: type: string format: uri description: | Publicly accessible URL of the PDF file to translate. Required when `document_id` is not provided. Ignored if `document_id` is also provided. target_language: type: string description: | ISO language code for the target language (e.g., `vi`, `fr`, `ja`, `zh-hans`). Supported codes: `ar`, `bn`, `bg`, `ca`, `zh-hans`, `zh-hant`, `hr`, `cs`, `da`, `nl`, `en`, `et`, `fa`, `fi`, `fr`, `de`, `el`, `gu`, `he`, `hi`, `hu`, `id`, `it`, `ja`, `kn`, `ko`, `lv`, `lt`, `ms`, `ml`, `mr`, `no`, `pl`, `pt`, `ro`, `ru`, `sr`, `sk`, `sl`, `es`, `sw`, `sv`, `ta`, `te`, `th`, `tr`, `uk`, `ur`, `vi`. pages: type: string description: | Page range to translate. Accepts comma-separated pages and ranges (e.g., `1-10`, `1,3,5-8`). If omitted, all pages are translated (up to the 40-page limit). output_format: type: string enum: [pdf, html] default: pdf description: Output file format. document_name: type: string description: Custom name for the translated file (without extension). Default is `{target_language}_{original_name}`. DocumentOperationResponse: type: object required: - document_name - signed_url - expires_at properties: document_name: type: string description: Name of the output document. signed_url: type: string format: uri description: Temporary HTTPS URL to download the output file. Expires after 30 minutes. expires_at: type: integer format: unix-epoch description: Unix epoch timestamp (in milliseconds) when `signed_url` becomes invalid. DocumentSplitResponse: type: object required: - signed_url - expires_at properties: signed_url: type: string format: uri description: Temporary HTTPS URL to download the result. Points to a PDF (single file) or ZIP archive (multiple files). Expires after 30 minutes. expires_at: type: integer format: unix-epoch description: Unix epoch timestamp (in milliseconds) when `signed_url` becomes invalid. DocumentSummarizeResponse: type: object required: - document_id - document_name - summary - language - character_count - cached - remaining_requests properties: document_id: type: string description: ID of the document that was summarized. document_name: type: string description: Name of the document. summary: type: string description: The AI-generated summary text. language: type: string enum: [en, es, fr, vi, pt] description: Detected language of the document content. character_count: type: integer description: Total number of characters in the source document (including spaces). cached: type: boolean description: "`true` if the response was served from cache; `false` if a fresh summary was generated." remaining_requests: type: integer description: Number of summarize requests the user has remaining for today. DocumentTranslateResponse: type: object required: - signed_url - expires_at - output_format - detected_language - target_language - document_name - page_count - remaining_requests properties: signed_url: type: string format: uri description: Temporary URL to download the translated file. expires_at: type: integer format: unix-epoch description: Unix epoch timestamp (in milliseconds) when the `signed_url` expires. output_format: type: string enum: [pdf, html] description: Format of the output file. detected_language: type: string description: ISO language code of the auto-detected source language. target_language: type: string description: ISO language code of the target language. document_name: type: string description: Name of the translated output file (with extension). page_count: type: integer description: Number of pages that were translated. remaining_requests: type: integer description: Number of translation requests the user has remaining for today. LinkedObject: type: object properties: integration: type: string description: | The external system or integration where the linked object lives. Example: salesforce, hubspot. entity_type: type: string description: | The type of the linked object in that provider's data model. Example: opportunity, contact, deal. record_id: type: string description: | The unique identifier of the linked object in the provider system. Example: 0065g00000Vh123ABC (Salesforce record ID). reference_url: type: string format: uri description: The reference URL of the linked object in the provider system. AgreementTemplateData: type: object required: - template_id properties: template_id: type: string description: Unique identifier of the AG template. Obtainable from the template list API. variables: type: object description: | Key-value map of Variables in the template. Pass values for the variables to render them into the created document or leave values blank to make them available for insertion later. fields: type: object description: | Key-value pairs for Form Fields defined in the template. Keys must match field names. Values prefill the corresponding form fields in the generated document. Currently supports: `text` and `checkbox` fields. collections: type: object description: | Map of **collection name → array of record objects** used to expand table-scoped row-loop markers in the template. - Each key must match a collection name returned by [Get Template Details](/tabs/api-reference/api/templates/get-template-details) under `collections[].name`. - Each value is an ordered array of flat record objects; each record is a key–value map where keys match the collection's variable names and values are strings. - Records are rendered in array order. - Maximum 100 items per collection, and up to 50 collections per request. Applies to AgreementGen templates only. Ignored silently when the resolved template `type` is not `lumin`. additionalProperties: type: array items: type: object additionalProperties: type: string linked_objects: type: array description: CRM or external objects linked to the Agreement. items: $ref: "#/components/schemas/LinkedObject" signer_roles: type: array description: | Describes the signer roles defined in the template. Role name must match the values defined in the template. These values are prefilled when sending the agreement for signature from the AgreementGen editor. items: type: object properties: name: type: string description: A label for the role (e.g., "Tenant", "Manager"). Must match a role defined in the template. preassigned_signer: type: object description: Signer preassigned to this role. These values are prefilled when sending the agreement for signature. properties: name: type: string description: Name of the preassigned signer. email_address: type: string format: email description: Email address of the preassigned signer. AgreementCreateRequest: type: object required: - method - agreement_data properties: method: type: string enum: [template] description: Must be set to `template`. agreement_name: type: string minLength: 1 maxLength: 255 description: | Human-friendly title of the agreement (1-255 chars). Defaults to input name or "New document" if not provided in the request body. agreement_data: $ref: "#/components/schemas/AgreementTemplateData" AgreementSummary: type: object required: - id - name - created_at properties: id: type: string description: The unique identifier for the agreement. name: type: string description: The name of the agreement. preview_url: type: string format: uri description: The URL to preview the agreement in the browser. created_at: type: integer format: unix-epoch description: The time the agreement was created (Unix timestamp in milliseconds). linked_objects: type: array description: CRM or external objects linked to the agreement. items: $ref: "#/components/schemas/LinkedObject" Error: type: object required: - error_code - error_message properties: error_code: type: string description: The system error code. error_message: type: string description: The human-readable error message.