Guide

PDF operations

PDF/A, booklets, rotate, split, protect, page layout and OCR.

Beyond plain format conversion, the API offers a set of PDF-specific operations: rotating pages, splitting, controlling page layout, encryption, PDF/A compliance, booklet imposition, and OCR for searchable PDFs. Most of these run through the document category with the target pdf; a few are dedicated operations. All examples authenticate with the x-oc-api-key header.

Merge multiple files into one PDF

Add two or more inputs to a single job with the target pdf and they are combined into one document, in the order the inputs are added. This works across PDFs, images (JPG, PNG) and office documents (DOCX, XLSX): each input is converted to PDF and then concatenated. There is no separate "merge" option — merging happens automatically whenever a job has more than one input and a single output target.

{
  "input": [
    { "type": "remote", "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg" },
    { "type": "remote", "source": "https://example-files.online-convert.com/document/docx/example.docx" }
  ],
  "conversion": [{ "category": "document", "target": "pdf" }]
}
The output order is the input order. To change the page order after the inputs are added, PATCH each input's position — see Reorder inputs.

Rotate pages

Rotate pages by passing a list of { "pages", "angle" } entries. pages accepts ranges like "1-3", single pages, or the keywords first/last/even/odd; angle is 90, 180 or 270 degrees clockwise.

{
  "conversion": [{
    "category": "document",
    "target": "pdf",
    "options": { "rotate": [{ "pages": "1-3", "angle": 90 }] }
  }],
  "input": [{ "type": "remote", "source": "https://example-files.online-convert.com/document/pdf/example.pdf" }]
}

Split into one file per page

Set one_file_per_page to split a multi-page PDF so each page becomes its own output file.

{
  "conversion": [{
    "category": "document",
    "target": "pdf",
    "options": { "one_file_per_page": true }
  }]
}

Page layout

Control the output geometry with page_size (e.g. a4, letter), orientation (portrait or landscape), and per-side borders. Border values use the unit given in border_unit.

{
  "conversion": [{
    "category": "document",
    "target": "pdf",
    "options": {
      "page_size": "a4",
      "orientation": "portrait",
      "border_top": 10,
      "border_bottom": 10,
      "border_left": 15,
      "border_right": 15,
      "border_unit": "mm"
    }
  }]
}

Protect and encrypt

Encrypt the PDF and set permissions. new_user_password is required to open the file; new_owner_password guards permission changes; the allow_* flags restrict printing, copying, and modification.

{
  "conversion": [{
    "category": "document",
    "target": "pdf",
    "options": {
      "new_user_password": "open-me",
      "new_owner_password": "owner",
      "allow_printing": false,
      "allow_copying": false,
      "allow_modification": false
    }
  }]
}

PDF/A compliance

Use the convert-pdfa operation to convert to an archival PDF/A profile, and validate-pdfa to check an existing file for compliance without converting it. Pick the conformance level with validation_profile; strict_mode tightens conversion checks.

{
  "conversion": [{
    "category": "operation",
    "target": "convert-pdfa",
    "options": { "validation_profile": "pdfa2b", "strict_mode": true }
  }]
}
{
  "conversion": [{
    "category": "operation",
    "target": "validate-pdfa",
    "options": { "validation_profile": "pdfa2b" }
  }]
}

Booklet

The pdf-booklet operation imposes pages for booklet printing. Configure the reading direction, the paper_size, how many pages_per_sheet, how blank pages are filled (blank_page_fill), and whether to add crop_marks.

{
  "conversion": [{
    "category": "operation",
    "target": "pdf-booklet",
    "options": {
      "direction": "ltr",
      "paper_size": "a4",
      "pages_per_sheet": 2,
      "blank_page_fill": "last",
      "crop_marks": true
    }
  }]
}

OCR and searchable PDFs

When converting a scanned document to PDF, enable ocr to produce a searchable text layer. Set the recognition language (ISO 639-2, e.g. eng), and optionally ocr_page_structure and ocr_filter to tune layout detection. This is the public OCR option and is distinct from any internal AI OCR target.

{
  "conversion": [{
    "category": "document",
    "target": "pdf",
    "options": {
      "ocr": true,
      "language": "eng"
    }
  }]
}
Stamping a watermark onto pages is covered in Add watermark. To see every supported target and its options, use the format explorer.

Live options

Pick a PDF target or operation to see its current option schema:

Loading options…