> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luminpdf.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload Document
> Create and save a document in the Workspace using file upload or a PDF template.
This endpoint supports two methods, selected by the `method` field:
* **`file-upload`** - import an existing file from a URL or multipart upload
* **`template`** - generate a PDF from a Lumin PDF template and optionally prefill fields
Copy examples from the dropdown to quickly get the sample request body for each method.
The response returns a `document_id` in the `id` field. Use that ID with PDF operation endpoints such as [Merge Documents](/tabs/api-reference/api/documents/merge-documents) or [Compress Document](/tabs/api-reference/api/documents/compress-document).
Upload from file
Set `method` to `file-upload` and provide the file via `document_data.file_url` or a multipart `document_data.file` upload.
### Supported file formats
PDF, DOCX, XLSX, PPTX, DOC, XLS, PNG, JPEG/JPG
### File size limits
| Plan | Max size |
| ---- | -------- |
| Free | 20 MB |
| Paid | 200 MB |
Create from template
Set `method` to `template`, provide a `pdf_` template ID, and optionally prefill form fields.
1. List templates with [List Templates](/tabs/api-reference/api/templates/list-templates) and find a template whose ID starts with `pdf_`.
2. Optionally inspect fields with [Get Template Details](/tabs/api-reference/api/templates/get-template-details).
Only PDF templates (`pdf_` prefix) are supported for document creation.
| Field | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
| `document_data.template_id` | PDF template ID (must start with `pdf_`). |
| `document_data.fields` | Optional key–value pairs for form fields defined in the template. Supports text and checkbox fields. |
This endpoint requires the following scope:
`pdf:files`
## OpenAPI
````yaml tabs/api-reference/lumin-openapi.yaml POST /documents
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
security: []
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:
/documents:
post:
tags:
- Documents
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
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'
security:
- ApiKey: []
- BearerAuth:
- pdf:files
components:
schemas:
DocumentCreateRequest:
oneOf:
- $ref: '#/components/schemas/DocumentCreateFileUploadRequest'
- $ref: '#/components/schemas/DocumentCreateTemplateRequest'
discriminator:
propertyName: method
mapping:
file-upload:
$ref: '#/components/schemas/DocumentCreateFileUploadRequest'
template:
$ref: '#/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.
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.
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'
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**.
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.
````