Upload Document

curl --request POST \
  --url https://api.luminpdf.com/v1/documents \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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"
  }
}
'

{
  "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"
}

{
  "error_code": "<string>",
  "error_message": "<string>"
}

POST

documents

curl --request POST \
  --url https://api.luminpdf.com/v1/documents \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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"
  }
}
'

{
  "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"
}

{
  "error_code": "<string>",
  "error_message": "<string>"
}

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 or 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.

List templates with List Templates and find a template whose ID starts with pdf_.
Optionally inspect fields with 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.

Required scopes (OAuth 2.0)

This endpoint requires the following scope:pdf:files

Authorizations

X-API-Key

string

header

required

Provide your API key in the X-API-Key header, e.g., X-API-Key: YOUR_API_KEY.

Body

file-upload
template

method

enum<string>

required

Import from a file (PDF or other supported formats).

Available options:

file-upload

document_name

string

required

Human-friendly title of the document (1–255 characters).

Required string length: 1 - 255

location

object

required

Hide child attributes

location.type

enum<string>

required

Location type.

Available options:

personal,

space,

workspace

location.space_id

string

ID of a specific Space in the Workspace. Required if type = space.

location.folder_id

string

ID of a specific folder within the chosen location.

document_data

object

required

Payload for file-upload method.

Hide child attributes

document_data.file

file

Upload binary file. Required if file_url not provided.

document_data.file_url

string<uri>

HTTPS URL to download the source file. Required if file not provided.

Response

Returns the summary of the created document.

string

required

Unique identifier of the document in Lumin.

name

string

required

Human-friendly name of the document.

created_at

integer<unix-epoch>

required

Unix timestamp (milliseconds) when the document was created.

updated_at

integer<unix-epoch>

required

Unix timestamp (milliseconds) when the document was last updated.

location

object

required

Where the document is stored.

Hide child attributes

location.type

enum<string>

One of:

workspace — Workspace's shared document list
space — Space's shared document list
personal — Personal document list

Available options:

workspace,

space,

personal

location.workspace_id

string

ID of the Workspace that owns this document (derived from the auth token).

location.space_id

string

ID of the Space that contains the document if location.type is space. Blank otherwise.

location.folder_id

string

ID of the folder that contains the document, if any. Blank otherwise.

size

integer

required

Size of the PDF file in bytes.

mime_type

string

required

MIME type of the file (e.g. application/pdf).

preview_url

string<uri>

required

URL to open the document in Lumin's viewer.

Documents

Merge Documents

API Documentation

Lumin API reference

Upload from file

Supported file formats

File size limits

Create from template

Authorizations

Body

Response

​Upload from file

​Supported file formats

​File size limits

​Create from template

Authorizations

Body

Response

Upload from file

Supported file formats

File size limits

Create from template