Add to PDF

The file parameter allows you to select a local PDF file to be uploaded to pdfRest's processing server. Use file to upload a PDF that you would like to add content to.

You can use an existing PDF as the input document, or use a blank PDF generated by Create Blank PDF as the starting point for a PDF Generation workflow.

The id parameter allows you to submit a resource ID generated by one of our API Tools. Each of our API Tools assigns a unique resource ID to your output file(s), allowing you to chain requests together without having to download intermediate files between requests.

For example, you can submit the output ID you receive from Create Blank PDF to add text, images, shapes, or tables to a new blank PDF.

Compatible with the /pdf-with-added-image endpoint.

The image_file parameter allows you to select a local image to be uploaded to pdfRest's processing server and inserted into the input PDF.

The following file formats are accepted:

• .gif
• .jpg/.jpeg
• .png
• .tif/.tiff

Compatible with the /pdf-with-added-image endpoint.

The image_id parameter allows you to submit a resource ID generated by one of our API Tools. Each of our API Tools assigns a unique resource ID to your file(s), allowing you to chain requests together without having to download intermediate files between requests.

For example, you can submit the output ID you receive from the /jpg endpoint of our PDF to Images tool to insert the generated image into an input PDF file.

The following file formats are accepted:

• .gif
• .jpg/.jpeg
• .png
• .tif/.tiff

The output parameter lets you set a filename (without extension) for your resulting PDF.

The x parameter lets you set the horizontal position of an inserted image in PDF units (1 PDF unit = 1/72 inch).

By default, the origin of the PDF coordinate system is in the lower-left corner of the document, so the x parameter indicates the position relative to the left edge of the page. If the PDF has an offset origin, this can affect the position at which the image will be inserted.

The y parameter lets you set the vertical position of an inserted image in PDF units (1 PDF unit = 1/72 inch).

By default, the origin of the PDF coordinate system is in the lower-left corner of the document, so the y parameter indicates the position relative to the bottom edge of the page. If the PDF has an offset origin, this can affect the position at which the image will be inserted.

The page parameter lets you set the page of the input PDF into which the image will be inserted. Specify a page number within the number of pages in the input PDF.

Compatible with the /pdf-with-added-image endpoint.

The width parameter lets you set the displayed width of an inserted image in PDF units (1 PDF unit = 1/72 inch).

This parameter is optional. If width and height are not provided, the image is inserted using its default dimensions.

Compatible with the /pdf-with-added-image endpoint.

The height parameter lets you set the displayed height of an inserted image in PDF units (1 PDF unit = 1/72 inch).

This parameter is optional. If width and height are not provided, the image is inserted using its default dimensions.

Compatible with the /pdf-with-added-attachment endpoint.

The file_to_attach parameter lets you upload a file to pdfRest's processing server to attach to an input PDF. Select any kind of file to add to PDF.

Compatible with the /pdf-with-added-attachment endpoint.

The id_to_attach parameter allows you to submit a resource ID generated by one of our API Tools. Each of our API Tools assigns a unique resource ID to your output file(s), allowing you to chain requests together without having to download intermediate files between requests.

id_to_attach also lets you attach a file that was uploaded previously to an input PDF document.

Text Objects

text_objects is a JSON-formatted string consisting of an array of one or more objects containing options to add and format text.

Text Object options:

• font: (string) specify the font of the given string. See available fonts here: pdfRest Documentation | Fonts
• max_width: (string) the maximum width of the text column in PDF Units (72 PDF Units = 1 inch). The text will wrap to conform to this width.
• opacity: (string) text opacity (0.0 - 1.0)
• page: (string) page number on which to add text. You can provide a page number, or you can use "all" to add the text to every page at the same X/Y position.
• rotation: (string) rotation in degrees of the text block
• text: (string) the string of text to add
• text_color_cmyk or text_color_rgb: (string) comma-delineated string of color values (RGB example: "53,5,102", CMYK example: "0,100,100,0"). Use one of these to set the text color.
• text_size: (string) font size of the text (5 - 100)
• x: (string) horizontal starting position of the text in PDF Units (72 PDF Units = 1 inch)
• y: (string) vertical starting position of the text in PDF Units (72 PDF Units = 1 inch)
• is_rtl: (string) set to "true" to insert right-to-left (RTL) language text
• tag_actual_text: (string) optional replacement text for tagged content. Requires tag_enabled=true.
• tag_is_artifact: (boolean) set to true to mark the inserted text as an artifact instead of regular structure content. Requires tag_enabled=true.
• tag_structure_type: (string) optional PDF structure type for the inserted text. Requires tag_enabled=true.

Example:

[ { "font":"Arial", "max_width":"240", "opacity":"1", "page":"1", "rotation":"0", "text":"Invoice #INV-1042", "text_color_rgb":"26,72,112", "text_size":"18", "x":"72", "y":"720", "tag_structure_type":"H1", "tag_actual_text":"Invoice number INV-1042" }, { "font":"Arial", "max_width":"360", "opacity":"1", "page":"1", "rotation":"0", "text":"Payment due within 30 days.", "text_color_rgb":"55,65,81", "text_size":"11", "x":"72", "y":"690", "tag_structure_type":"P" } ]

Shape Objects

Compatible with the /pdf-with-added-shapes endpoint.

shape_objects is a JSON-formatted object or array of objects that define lines and rectangles to add to a PDF.

Shape Object options:

• type: (string) required. Use line or rectangle.
• page: (string or number) required. Use a page number, or use all to place the same shape on every page.

Line options:

• x1: (number) required. Horizontal starting position of the line in PDF units.
• y1: (number) required. Vertical starting position of the line in PDF units.
• x2: (number) required. Horizontal ending position of the line in PDF units.
• y2: (number) required. Vertical ending position of the line in PDF units.
• stroke_color_rgb: (string) optional RGB stroke color, such as "26,72,112".
• stroke_color_cmyk: (string) optional CMYK stroke color, such as "100,64,0,56".
• stroke_width: (number) optional line thickness in PDF units.
• opacity: (number) optional opacity from 0.0 to 1.0.

Rectangle options:

• x: (number) required. Horizontal position of the rectangle in PDF units.
• y: (number) required. Vertical position of the rectangle in PDF units.
• width: (number) required. Rectangle width in PDF units.
• height: (number) required. Rectangle height in PDF units.
• fill_color_rgb: (string) optional RGB fill color, such as "245,247,250".
• fill_color_cmyk: (string) optional CMYK fill color, such as "0,0,0,4".
• stroke_color_rgb: (string) optional RGB border color.
• stroke_color_cmyk: (string) optional CMYK border color.
• stroke_width: (number) optional border thickness in PDF units.
• opacity: (number) optional opacity from 0.0 to 1.0.

Tag options:

• tag_actual_text: (string) optional replacement text for tagged content. Requires tag_enabled=true.
• tag_is_artifact: (boolean) set to true to mark the shape as an artifact. Requires tag_enabled=true.
• tag_structure_type: (string) optional PDF structure type for the inserted shape. Requires tag_enabled=true.

Example:

[ { "type":"rectangle", "page":1, "x":54, "y":540, "width":504, "height":108, "fill_color_rgb":"245,247,250", "stroke_color_rgb":"26,72,112", "stroke_width":1, "tag_is_artifact":true }, { "type":"line", "page":1, "x1":72, "y1":576, "x2":540, "y2":576, "stroke_color_rgb":"26,72,112", "stroke_width":1.5, "tag_actual_text":"Review section divider", "tag_structure_type":"Figure" } ]

Table Objects

Compatible with the /pdf-with-added-tables endpoint.

table_objects is a JSON-formatted object or array of objects that define one or more tables to add to a PDF.

Table Object options:

• page: (number) required. Page number where the table starts.
• x: (number) required. Horizontal starting position of the table in PDF units.
• y: (number) required. Vertical starting position of the table in PDF units.
• width: (number) optional. Total table width in PDF units.
• width_percentage: (number) optional. Table width as a percentage of the available page width.
• columns: (array) required. Defines the table columns and their widths.
• rows: (array) required. Defines the table body rows.
• header_rows: (array) optional. Defines header rows.
• footer_rows: (array) optional. Defines footer rows.
• repeat_header_on_overflow: (boolean) optional. Repeats header rows on continuation pages. Default is false.
• repeat_footer_on_overflow: (boolean) optional. Repeats footer rows on continuation pages. Default is false.
• style: (object) optional. Defines default table styling.
• tag_structure_type: (string) optional PDF structure type for the table. Requires tag_enabled=true.

Column options:

• width: (number) required. Column width in PDF units.
• style: (object) optional. Defines default styling for cells in the column.

Row options:

• cells: (array) required. Defines the cells in the row.
• style: (object) optional. Defines default styling for cells in the row.
• min_height: (number) optional. Minimum row height in PDF units.
• fixed_height: (number) optional. Fixed row height in PDF units.

Cell options:

• text: (string) optional. Text to place in the cell.
• image: (object) optional. Image to place in the cell.
• col_span: (number) optional. Number of columns the cell spans.
• row_span: (number) optional. Number of rows the cell spans.
• style: (object) optional. Defines styling for this cell.
• tag_actual_text: (string) optional replacement text for tagged content. Requires tag_enabled=true.
• tag_is_artifact: (boolean) set to true to mark the cell as an artifact. Requires tag_enabled=true.
• tag_structure_type: (string) optional PDF structure type for the cell, such as TH or TD. Requires tag_enabled=true.

Image cell options:

• image_index: (number) required. Zero-based index selecting an uploaded file from image_files.
• width: (number) optional. Displayed image width in PDF units.
• height: (number) optional. Displayed image height in PDF units.
• tag_alt_text: (string) optional alternate text for the image. Requires tag_enabled=true.
• tag_structure_type: (string) optional PDF structure type for the image. Requires tag_enabled=true.

Style options:

• background_color_rgb: (array) optional RGB background color, such as [245,247,250].
• text_color_rgb: (array) optional RGB text color, such as [26,72,112].
• border_color_rgb: (array) optional RGB border color.
• border_width: (number) optional border thickness in PDF units.
• font: (string) optional font name.
• text_size: (number) optional font size.
• padding: (object) optional cell padding.
• opacity: (number) optional opacity from 0.0 to 1.0.

Padding options:

• top: (number) optional top padding in PDF units.
• right: (number) optional right padding in PDF units.
• bottom: (number) optional bottom padding in PDF units.
• left: (number) optional left padding in PDF units.

This example includes an image cell. To run it, upload any supported image as the first image_files multipart field and set tag_enabled=true. Its image_index value of 0 selects that first upload.

Example:

[ { "page":1, "x":54, "y":540, "width":504, "repeat_header_on_overflow":true, "columns":[ {"width":210}, {"width":144}, {"width":150} ], "tag_structure_type":"Table", "style":{ "padding":{"top":6,"right":8,"bottom":6,"left":8}, "text_size":10 }, "header_rows":[ { "cells":[ {"text":"Milestone","tag_structure_type":"TH"}, {"text":"Owner","tag_structure_type":"TH"}, {"text":"Status","tag_structure_type":"TH"} ] } ], "rows":[ { "cells":[ {"text":"Requirements review","tag_structure_type":"TD"}, {"text":"Maya Chen","tag_structure_type":"TD"}, { "image":{ "image_index":0, "width":18, "height":18, "tag_alt_text":"Complete status icon", "tag_structure_type":"Figure" }, "tag_actual_text":"Complete", "tag_structure_type":"TD", "style":{"background_color_rgb":[220,252,231]} } ] } ], "footer_rows":[ { "cells":[ { "text":"Next review: Friday, 10:00 AM", "col_span":3, "tag_structure_type":"TD" } ] } ] } ]

Compatible with the /pdf-with-added-tables endpoint.

The image_files parameter allows you to upload one or more local image files for use inside table cells.

Use the same multipart field name, image_files, for each uploaded image file. Table image cells select these uploads with image_index, starting at 0 for the first uploaded image, 1 for the second uploaded image, and so on.

The following file formats are accepted:

• .gif
• .jpg/.jpeg
• .png
• .tif/.tiff

Example:

image_files=@complete-status-icon.png

image_files=@warning-status-icon.png

Compatible with the /pdf-with-added-text, /pdf-with-added-image, /pdf-with-added-shapes, and /pdf-with-added-tables endpoints.

The tag_enabled parameter lets you add optional structure tags for newly inserted content.

Accepts:

• true
• false

Default:

• false

When set to true, Add to PDF can tag newly inserted text, images, shapes, and table content. This can help identify added content in the PDF structure for downstream processing and accessibility-oriented workflows. It does not automatically tag pre-existing untagged content already present in the input PDF.