# PDF coded automation APIs (preview)

> Coded automation APIs for the PDF activities package, covering reading, merging, converting, and manipulating PDF and XPS files.

`UiPath.PDF.Activities`

Coded workflow API for reading, merging, converting, and manipulating PDF and XPS files. These APIs are available when designing coded automations. For an introduction to coded automations and how to design them using APIs, see [Coded Automations](https://docs.uipath.com/studio/standalone/2023.10/user-guide/coded-automations-introduction).

- **Service accessor:** `pdf` (type `IPdfService`)
- **Required package:** `"UiPath.PDF.Activities": "*"` in the `project.json` dependencies.

## Auto-imported namespaces

The following namespaces are automatically available in coded workflows when the PDF package is installed:

* `UiPath.PDF.Activities.Api`
* `UiPath.PDF`
* `UiPath.PDF.Activities.PDF.Enums`
* `UiPath.Platform.ResourceHandling`
* `System.Net.Mail`

## Service overview

The `pdf` service exposes each operation as a direct method call. There is no connection or scope to open. Most operations provide two forms: one that takes a file path as a `string`, and one that takes an `IResource` (for example, the output of the **Path Exists** or **Get Local File or Folder** activity). Call methods on the service accessor directly:

```csharp
string text = pdf.ReadPdfText(@"C:\docs\report.pdf");
```

Methods that create or transform a file return an `ILocalResource` pointing to the output. When `outputFileName` is `null`, the service generates a name automatically. Password-protected files are opened by passing the `password` parameter. The `range` parameter accepts `"All"` or explicit ranges such as `"1-3,5"`.

## Reading text

### `string ReadPdfText(string fileName, string password = null, string range = "All", bool preserveFormatting = false)`

Reads the text from a PDF file. Set `preserveFormatting` to `true` to keep the text layout. An overload accepting an `IResource` is also available.

### `string ReadPdfWithOcr(string fileName, IOCRActivity ocrEngine, string range = "All", int degreeOfParallelism = 1, string password = null, ImageDpi imageDpi = ImageDpi.Medium)`

Reads the text from a scanned PDF using the supplied OCR engine. Obtain an OCR engine from the OCR service (for example, `IOcrService.GetUiPathDocumentOcr`). `degreeOfParallelism` sets how many pages are processed at once. **Windows only.**

### `string ReadXpsText(string fileName, string range = "All")`

Reads the text from an XPS file. An overload accepting an `IResource` is also available. **Windows only.**

### `string ReadXpsWithOcr(string fileName, IOCRActivity ocrEngine, string range = "All", int degreeOfParallelism = 1, string password = null)`

Reads the text from an XPS file using the supplied OCR engine. **Windows only.**

## Page and document operations

### `int GetPdfPageCount(string fileName, string password = null)`

Returns the number of pages in a PDF file. An overload accepting an `IResource` is also available.

### `ILocalResource JoinPdf(string[] fileList, string outputFileName = null)`

Merges multiple PDF files into a single PDF, in the order given. An overload accepting an `IResource[]` is also available.

### `ILocalResource ExtractPdfPageRange(string fileName, string range, string password = null, string outputFileName = null)`

Extracts a range of pages (for example, `"1-3,5"`) from a PDF into a new PDF. An overload accepting an `IResource` is also available.

### `ILocalResource ExportPdfPageAsImage(string fileName, int pageNumber, string outputFileName, string password = null, ImageDpi imageDpi = ImageDpi.Medium)`

Exports a single page (1-based `pageNumber`) as an image. The image format is inferred from the `outputFileName` extension. An overload accepting an `IResource` is also available.

## Creating and converting

### `ILocalResource CreatePdfFromImages(string[] fileList, string outputFileName = null)`

Creates a PDF from a list of image files, one image per page. Supported input formats: PNG, JPG, JPEG, TIF, TIFF, BMP. An overload accepting an `IResource[]` is also available.

### `ILocalResource ConvertHtmlToPdf(string html, string outputFileName = null, bool keepBackground = true, ConvertToPdfOptions options = null)`

Converts HTML content to a PDF. Set `keepBackground` to `true` to preserve background colors and graphics.

### `ILocalResource ConvertEmailToPdf(MailMessage email, string outputFileName = null, bool keepBackground = true, ConvertToPdfOptions options = null)`

Converts an email message to a PDF.

### `ILocalResource ConvertTextToPdf(string text, string outputFileName = null, int fontSize = 12, TextAlignment textAlignment = TextAlignment.Justify, ConvertToPdfOptions options = null)`

Converts plain text to a PDF, with a configurable font size and text alignment.

## Extracting images and attachments

### `IEnumerable<ILocalResource> ExtractImagesFromPdf(string fileName, string password = null, ImageExtension imageExtension = ImageExtension.PNG, string outputFolderName = null)`

Extracts all images from a PDF and saves them in the chosen format. An overload accepting an `IResource` is also available.

### `IEnumerable<ILocalResource> ExtractAttachmentsFromPdf(string fileName, string password = null, string[] filter = null, string outputFolderName = null)`

Extracts the files embedded in a PDF. Set `filter` to limit to specific extensions (for example, `new[] { ".docx", ".xlsx" }`). An overload accepting an `IResource` is also available.

## Managing passwords

### `ILocalResource ManagePdfPassword(string fileName, string oldUserPassword, string newUserPassword, string oldOwnerPassword, string newOwnerPassword, string outputFileName = null)`

Sets or removes the user and owner passwords on a PDF. Pass `null` or an empty string as a new password to remove it. An overload accepting an `IResource` is also available.

## Options

### `ConvertToPdfOptions`

Shared layout and content options for the conversion methods.

* `HeaderHtml` `String` - HTML snippet used as the page header. Defaults to `null` (no header).
* `FooterHtml` `String` - HTML snippet used as the page footer. Defaults to `null` (no footer).
* `PaperSize` `PaperSize` - Paper size for the output PDF. Defaults to `A4`.
* `Margin` `Int` - Page margin in points. Defaults to `0`.
* `Scale` `Double` - Page rendering scale, between `0.1` and `2` inclusive. Defaults to `1.0`.

## Enum reference

### `ImageExtension`

Used by `ExtractImagesFromPdf`.

* `PNG` - PNG image format.
* `JPEG` - JPEG image format.
* `TIFF` - TIFF image format.
* `BMP` - BMP image format.

### `ImageDpi`

Used by `ReadPdfWithOcr` and `ExportPdfPageAsImage`.

* `Low` - 96 DPI.
* `Medium` - 150 DPI. Default.
* `High` - 270 DPI.

### `TextAlignment`

Used by `ConvertTextToPdf`.

* `Justify` - Justified alignment. Default.
* `Left` - Left alignment.
* `Right` - Right alignment.
* `Center` - Center alignment.

### `PaperSize`

Used by `ConvertToPdfOptions`.

* `A4` (default), `A3`, `A5`, `A2`, `A6` - ISO A-series sizes.
* `Letter`, `Legal`, `Tabloid`, `Ledger`, `Executive`, `Statement` - North American sizes.
* `B4`, `B5` - ISO B-series sizes.
* `Number10Envelope`, `DLEnvelope`, `C5Envelope`, `C4Envelope` - Envelope sizes.

## Relationship to the activities

The coded API and the PDF XAML activities run on the same runtime, so a coded workflow reaches the same reading, conversion, and manipulation behavior as the activities in the [PDF activity package](https://docs.uipath.com/activities/other/latest/document-understanding/about-the-pdf-activities-pack). The difference is the call shape: the service takes plain file paths or `IResource` inputs and returns `string`, `int`, or `ILocalResource` results directly, and you use ordinary `try`/`catch` instead of the activity **Continue On Error** option.

## Common patterns

### Read the text of a PDF

This pattern reads the text of a page range from a PDF file. `ReadPdfText` returns the extracted text as a `string`.

```csharp
[Workflow]
public void Execute()
{
    string text = pdf.ReadPdfText(@"C:\docs\report.pdf", range: "1-3");
    Log(text);
}
```

### Merge PDFs and extract a page range

This pattern merges two PDF files into one and then extracts a page range from the merged result. Each step returns an `ILocalResource` pointing to the output file.

```csharp
[Workflow]
public void Execute()
{
    var merged = pdf.JoinPdf(new[] { @"C:\docs\a.pdf", @"C:\docs\b.pdf" }, @"C:\docs\merged.pdf");
    var firstTwoPages = pdf.ExtractPdfPageRange(merged.LocalPath, "1-2", outputFileName: @"C:\docs\excerpt.pdf");
}
```

### Convert HTML to a Letter-size PDF with a margin

This pattern converts an HTML string to a PDF, using `ConvertToPdfOptions` to set a Letter paper size and a page margin. `ConvertHtmlToPdf` returns an `ILocalResource` pointing to the created PDF.

```csharp
[Workflow]
public void Execute()
{
    var options = new ConvertToPdfOptions { PaperSize = PaperSize.Letter, Margin = 20 };
    var pdfFile = pdf.ConvertHtmlToPdf("ReportGenerated by a coded workflow.", @"C:\docs\report.pdf", options: options);
}
```