PDF Page Insertion API

BASE URLhttps://api-server.compdf.com/server/

❖ Feature Description

Insert pages from another PDF or blank pages into a target PDF at a specified position.

❖ Request Mode

Synchronous Request (Sync) ✓

The API returns the result file directly after processing. Recommended for small files and real-time interactive scenarios that need immediate feedback.

Asynchronous Request (Async)

The API first returns task acceptance information, then you query progress and results with taskId. Suitable for large files and batch workloads.

Secure Request Mode

Upload and process files through secure mechanisms such as pre-signed URLs. Suitable for high-security and privacy compliance scenarios.

▎Call Flow

1Upload file

2Call API (sync)

3Get result URL

4Download file

▎Usage Limits

Download validity

24 hours

Sync /pdf/insert

POSThttps://api-server.compdf.com/server/v2/process/pdf/insert

❖ Request Parameters

x-api-key*

Authentication credential sent in the header: x-api-key

Body Parameters multipart/form-data

actionTypestring*FROM_PDFBLANK

Operation type. FROM_PDF: insert pages from another PDF (requires 2 files). BLANK: insert blank pages (requires 1 file with width/height).

fileFile[]

Choose Files

No file selected

Uploaded files. file[0] is the target PDF. file[1] is the source PDF whose pages will be inserted into the target PDF. FROM_PDF requires both files.

indexinteger*

Insert position, starting from 1. It indicates where pages from the second file will be inserted into the first file.

outputFileNamestring

Output file name

sourcePagesstring

Which pages to take from the second file, for example "1-3,6". Leave empty to insert all pages from the second file into the first file.

sourcePageRangesstring

Backward-compatible alias of sourcePages

targetPasswordstring

Target PDF password

insertPasswordstring

Source PDF password

passwordstring

Upload password for the main file

languageinteger

API error message language. 1 = English, 2 = Chinese.

❖ Response Properties

Field	Type	Description
actionType	String	Operation type. FROM_PDF: insert pages from another PDF (requires 2 files). BLANK: insert blank pages (requires 1 file with width/height).
code	String	Business status code
msg	String	Message
data	Object	Response data
data.actionType	String	Operation type. FROM_PDF: insert pages from another PDF (requires 2 files). BLANK: insert blank pages (requires 1 file with width/height).
data.fileKey	String	Unique key of the file in the storage system.
data.taskId	String	Task ID
data.fileName	String	Source file name. Required in presigned mode to generate the object storage upload URL.
data.downFileName	String	Output file name after conversion.
data.fileUrl	String	Source file storage URL or object storage key.
data.downloadUrl	String	File download URL
data.sourceType	String	Source file type
data.targetType	String	Target file type
data.fileSize	Integer	Source file size in bytes.
data.convertSize	Integer	Converted file size in bytes.
data.convertTime	Integer	Conversion time for a single file, typically in milliseconds.
data.status	String	File processing status. Common values: success, failed, processing, etc.
data.failureCode	String	Error code when file conversion fails.
data.failureReason	String	Error reason when file conversion fails.
data.fileParameter	String	Conversion parameter JSON string submitted when creating the task.

🔗Request Example

curl --request POST \
  --url https://api-server.compdf.com/server/v2/process/pdf/insert \
  --header 'x-api-key: YOUR API-KEY' \
  --form [email protected] \
  --form [email protected] \
  --form actionType=FROM_PDF

✓Response Example

200 OK

{
  "actionType": "<string>",
  "code": "200",
  "msg": "success",
  "data": {
    "actionType": "<string>",
    "fileKey": "<string>",
    "taskId": "<string>",
    "fileName": "<string>",
    "downFileName": "<string>",
    "fileUrl": "<string>",
    "downloadUrl": "<string>",
    "sourceType": "<string>",
    "targetType": "<string>",
    "fileSize": 0,
    "convertSize": 0,
    "convertTime": 0,
    "status": "<string>",
    "failureCode": "<string>",
    "failureReason": "<string>",
    "fileParameter": "<string>"
  }
}