Add to PDF

Compatible with all Add to PDF endpoints.

The file parameter allows you to select a local PDF file to be uploaded to pdfRest's processing server. The uploaded PDF becomes the input document to which text, images, shapes, tables, or file attachments are added.

You can also use a blank PDF generated by Create Blank PDF as the starting point for a PDF Generation workflow.

Accepted file type:

• application/pdf

Compatible with all Add to PDF endpoints.

The id parameter allows you to submit a resource ID generated by one of our API Tools instead of uploading the PDF again. Each API Tool assigns a unique resource ID to its output file(s), allowing you to chain requests together without downloading intermediate files between requests.

For example, you can submit the output ID received 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 one local image to be uploaded to pdfRest's processing server and inserted into the input PDF during a single image insertion. The image is placed using the request-level x, y, and page parameters.

For multiple image insertion, use the image_objects parameter. Each image object can specify its own image source, page selection, position, displayed width, displayed height, and optional tagging metadata.

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 during a single image insertion. Each API Tool assigns a unique resource ID to its output file(s), allowing you to chain requests together without downloading intermediate files between requests.

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

For multiple image insertion, use the image_objects parameter. Each image object can reference an existing image resource and specify its own page, position, displayed dimensions, and optional tagging metadata. The same image resource can be reused in multiple placements without uploading it again.

The following file formats are accepted:

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

Compatible with all Add to PDF endpoints.

The output parameter lets you set the filename of the resulting PDF without specifying a file extension.

Compatible with the /pdf-with-added-image endpoint for single image insertion.

The x parameter sets the horizontal position of an inserted image's lower-left corner in PDF units, where 72 PDF units equal 1 inch.

By default, the origin of the PDF coordinate system is in the lower-left corner of the document. The x parameter therefore indicates the position relative to the left edge of the page. If the PDF has an offset origin, that can affect the final image placement.

For multiple image insertion, specify x inside each image_objects entry.

Compatible with the /pdf-with-added-image endpoint for single image insertion.

The y parameter sets the vertical position of an inserted image's lower-left corner in PDF units, where 72 PDF units equal 1 inch.

By default, the origin of the PDF coordinate system is in the lower-left corner of the document. The y parameter therefore indicates the position relative to the bottom edge of the page. If the PDF has an offset origin, that can affect the final image placement.

For multiple image insertion, specify y inside each image_objects entry.

Compatible with the /pdf-with-added-image endpoint for single image insertion.

The page parameter specifies the page of the input PDF into which the image will be inserted. For single image insertion, provide a page number within the input PDF.

For multiple image insertion, page selection is specified inside each image_objects entry. An image object can target a page number, all, last, comma-separated page numbers, numeric ranges, or combinations of these values.

Examples include:

• 1
• all
• last
• 1,4,8
• 3-10
• 2-last
• 1-4,6-last

Each image object uses the same coordinates and dimensions on every selected page. To place the same image at different coordinates or sizes, use separate image objects.

Text, shape, and table objects have their own page behavior, which is described in their respective JSON object sections.

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

The width parameter sets the displayed width of an inserted image in PDF units, where 72 PDF units equal 1 inch.

For single image insertion, provide width as a request-level parameter. For multiple image insertion, provide width inside each image_objects entry.

This parameter is optional. If width and height are not provided, the image is inserted using its default dimensions. If only width is provided, the height is calculated to preserve the image's aspect ratio. If both width and height are provided, both displayed dimensions are used.

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

The height parameter sets the displayed height of an inserted image in PDF units, where 72 PDF units equal 1 inch.

For single image insertion, provide height as a request-level parameter. For multiple image insertion, provide height inside each image_objects entry.

This parameter is optional. If width and height are not provided, the image is inserted using its default dimensions. If only height is provided, the width is calculated to preserve the image's aspect ratio. If both width and height are provided, both displayed dimensions are used.

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

The file_to_attach parameter lets you upload a file to pdfRest's processing server and attach it to the input PDF.

You can attach XML data, spreadsheets, source documents, receipts, supporting records, or any other file accepted by the endpoint. Attachments are useful for supplementary information, e-invoicing, archival, compliance, collaboration, and preserving source data with a human-readable 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 and attach that file to the input PDF without uploading it again.

The resource ID can refer to a file generated by another API Tool or a file that was uploaded previously.

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

The text_objects parameter 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 in the pdfRest documentation.
• max_width: (string) Maximum width of the text column in PDF units, where 72 PDF units equal 1 inch. The text wraps to conform to this width.
• opacity: (string) Text opacity from 0.0 to 1.0.
• page: (string) Page number on which to add text. You can provide a page number or 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) Text to add.
• text_color_cmyk or text_color_rgb: (string) Comma-delimited color values. An RGB example is "53,5,102". A CMYK example is "0,100,100,0". Use one of these options to set the text color.
• text_size: (string) Font size of the text. Supported values range from 5 to 100.
• x: (string) Horizontal starting position of the text in PDF units.
• y: (string) Vertical starting position of the text in PDF units.
• is_rtl: (string) Set to true to insert right-to-left 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.

Set the request-level tag_enabled parameter to true for tag metadata to be applied. Tagging applies to newly inserted text and does not remediate existing untagged content.

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"
  }
]

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

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

Shape Object options:

• type: (string) Required. Use line or rectangle.
• page: (string or number) Required. Use a page number or 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.

To apply the tagging properties shown in this example, set the request-level tag_enabled parameter to 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"
  }
]

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

The table_objects parameter is a JSON-formatted object or array of objects that defines one or more structured tables to add to the input 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.
• width_mode: (string) Optional. Controls whether column widths are interpreted as fixed widths or relative proportions.
• horizontal_align: (string) Optional. Horizontal alignment of the table within its available width.
• is_rtl: (boolean) Optional. Enables right-to-left table layout.
• 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.
• show_header_on_first_page: (boolean) Optional. Controls whether header rows appear on the first page.
• show_footer_on_last_page: (boolean) Optional. Controls whether footer rows appear on the final page.
• keep_table_block_together: (boolean) Optional. Attempts to keep the table together when it fits on a page.
• spacing_before: (number) Optional. Space before the table in PDF units.
• spacing_after: (number) Optional. Space after the table in PDF units.
• continuation_page_top_margin: (number) Optional. Reserved top space on continuation pages.
• page_bottom_margin: (number) Optional. Reserved bottom space on pages containing continuing table content.
• final_page_bottom_margin: (number) Optional. Reserved bottom space on the final table page.
• overflow_behavior: (string) Optional. Controls whether rows move, split, or cause the operation to fail.
• row_split_behavior: (string) Optional. Controls whether rows split when needed or move to the next page.
• style: (object) Optional. Defines default table styling.
• tag_structure_type: (string) Optional PDF structure type for the table. Requires tag_enabled=true.
• tag_is_artifact: (boolean) Optional. Marks the table as an artifact. Requires tag_enabled=true.

Use either width or width_percentage, not both. Relative percentage widths require relative width mode.

Column options:

• width: (number) Required. Column width or relative column-width value.
• 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 the cell.
• no_wrap: (boolean) Optional. Prevents text from wrapping within the cell.
• is_rtl: (boolean) Optional. Enables right-to-left text in the cell.
• min_height: (number) Optional. Minimum cell height in PDF units.
• fixed_height: (number) Optional. Fixed cell height in PDF units.
• tag_actual_text: (string) Optional replacement text for tagged content. Requires tag_enabled=true.
• tag_alt_text: (string) Optional alternate text for an image cell. Requires tag_enabled=true.
• tag_is_artifact: (boolean) Optional. Marks 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 image from image_files or image_ids.
• 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.
• tag_is_artifact: (boolean) Optional. Marks the image as an artifact. Requires tag_enabled=true.

Style options:

• font: (string) Optional font name.
• text_size: (number) Optional font size.
• text_align: (string) Optional horizontal text alignment.
• vertical_align: (string) Optional vertical cell alignment.
• text_color_rgb or text_color_cmyk: Optional text color.
• background_color_rgb or background_color_cmyk: Optional background color.
• opacity: (number) Optional opacity from 0.0 to 1.0.
• padding: (object) Optional cell padding.
• border: (object) Optional per-side border settings.

Border settings can be specified independently for the top, right, bottom, and left sides. Each side can define its width, RGB or CMYK color, and opacity. Styles can be inherited at the table, column, row, and cell levels.

Image cells select an image using image_index. For multipart uploads, the index refers to the ordered image_files fields. For stored resources, the index refers to the ordered image_ids values. Both indexes start at zero.

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. The same table structure can reference an existing image resource by using the corresponding entry in image_ids.

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-image endpoint.

The image_objects parameter is a JSON-formatted array of objects for multiple image insertion. Each object defines one image placement and can specify its image source, page selection, position, displayed dimensions, and optional tagging metadata.

Image Object options:

• image_index: (number) Zero-based index selecting an image from the uploaded image_files fields.
• image_id: (string) Resource ID of an existing image.
• page: (string or number) Page number, all, last, or a supported page range.
• x: (number) Horizontal position of the image's lower-left corner in PDF units.
• y: (number) Vertical position of the image's lower-left corner in PDF units.
• 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 inserted image. Requires tag_enabled=true.
• tag_is_artifact: (boolean) Set to true to mark the image as an artifact. Requires tag_enabled=true.
• tag_structure_type: (string) Optional PDF structure type for the inserted image, such as Figure. Requires tag_enabled=true.

Use image_index when supplying images through repeated image_files multipart fields. Use image_id when referencing an existing image resource. The same image can be referenced by multiple objects without being uploaded again.

If only one image dimension is provided, the other dimension is calculated to preserve the image's aspect ratio. If both dimensions are provided, both displayed dimensions are used.

Example:

[
  {
    "image_index": 0,
    "page": "all",
    "x": 72,
    "y": 648,
    "width": 96,
    "height": 48,
    "tag_alt_text": "Northstar Sample Supply logo",
    "tag_structure_type": "Figure"
  },
  {
    "image_index": 0,
    "page": "2-last",
    "x": 432,
    "y": 72,
    "width": 48,
    "height": 48,
    "tag_alt_text": "Northstar Sample Supply mark",
    "tag_structure_type": "Figure"
  },
  {
    "image_id": "a1b2c3d4",
    "page": 3,
    "x": 72,
    "y": 540,
    "width": 120,
    "tag_alt_text": "Customer logo",
    "tag_structure_type": "Figure"
  }
]

Set the request-level tag_enabled parameter to true for the tagging properties in this example to be applied.

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 enables optional structure tags for newly inserted text, images, shapes, and table content.

Accepts:

• true
• false

Default:

• false

When set to true, object-level tagging properties can identify structure types, alternate text, actual text, artifact status, and table relationships where supported.

When used with an already tagged PDF, newly inserted tagged content can be appended while preserving the existing structure. The parameter does not automatically tag or remediate pre-existing untagged content.

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

For multiple image insertion, the image_files parameter accepts one or more local image files. Use the same multipart field name, image_files, for each uploaded image. Image objects select these uploads with the zero-based image_index property.

For table insertion, image_files supplies the local images that can be placed in table image cells. Table cells also select these uploads with image_index.

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-tables endpoint.

The image_ids parameter accepts an ordered array of existing image resource IDs for use in table image cells. A table cell's zero-based image_index selects an image from this array.

Use image_files when uploading local images with the request. Use image_ids when referencing images that were uploaded previously or created by another API Tool. The same image resource can be referenced by multiple cells without uploading it again.

Example:

[
  "a1b2c3d4",
  "e5f6g7h8"
]