> ## 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.
# Merge Documents
> Merge multiple documents into a single PDF file and return a temporary download URL.
This endpoint requires the following scope:
`pdf:files`
## OpenAPI
````yaml tabs/api-reference/lumin-openapi.yaml POST /documents/merge
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/merge:
post:
tags:
- Documents
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.
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'
security:
- ApiKey: []
- BearerAuth:
- pdf:files
components:
schemas:
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}`.
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.
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.
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.
````