Add watermarks to PDFs

Watermarking is the process of embedding visual elements into a document’s pages, typically to indicate ownership, add disclaimers, or discourage redistribution. While these watermarks may be transparent, opaque, or even invisible, they can ultimately be flattened into the page content and become a permanent part of the document.

Document Engine enables you to watermark documents using the watermark action.

Requirements

Ensure Document Engine is up and running.
Send a multipart POST request with instructions to Document Engine’s /api/build endpoint.

For more information, refer to the API reference to learn about the /api/build endpoint and all the actions you can perform on PDFs with Document Engine.

For an overview of multipart requests, refer to the brief tour of multipart requests blog post.

Add a watermark

Set up the watermark action with the required options, which define the appearance and position of the watermark. These options support both text and image watermarks and abstract away the lower-level annotation details.

The watermark action automatically handles the creation and flattening of watermark annotations, so you don’t need to manage annotations manually.

Alternatively, if you need more control, you can manually create annotations for each page using the PDF Annotations API and then flatten them using the Flatten PDF API.

Watermarking a file on disk

To add a TOP SECRET text watermark to a document, send a request to the /api/build endpoint, include the document file as an attachment, and provide watermark instructions in the instructions JSON payload, as demonstrated in the code snippet below:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F document=@/path/to/example-document.pdf \
  -F instructions='{
  "parts": [
    {
      "file": "document",
      "actions": [
        {
          "type": "watermark",
          "text": "TOP SECRET",
          "width": 100,
          "height": 200
        },
        {
          "type": "flatten"
        }
      ]
    }
  ]
}' \
  -o result.pdf

POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

--customboundary
Content-Disposition: form-data; name="document"; filename="example-document.pdf"
Content-Type: application/pdf

<PDF data>
--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": "document",
      "actions": [
        {
          "type": "watermark",
          "text": "TOP SECRET",
          "width": 100,
          "height": 200
        },
        {
          "type": "flatten"
        }
      ]
    }
  ]
}
--customboundary--

The following example adds an image watermark to the first page of a four-page document and a text annotation to the last page of the same document before flattening the annotations on the final output PDF so that the watermark can’t be erased:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F document=@/path/to/example-document.pdf \
  -F image-local=@/path/to/image-watermark.png \
  -F instructions='{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": 0
      },
      "actions": {
        "type": "watermark",
        "image": "image-local",
        "width": 100
      }
    },
    {
      "file": "document",
      "pages": {
        "start": 1,
        "end": 2
      }
    },
    {
      "file": "document",
      "pages": {
        "start": 3,
        "end": 3
      },
      "actions": {
        "type": "watermark",
        "text": "TOP SECRET",
        "width": 100,
        "height": 200
      }
    }
  ],
  "actions": [
    {
      "type": "flatten"
    }
  ]
}' \
  -o result.pdf

POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

--customboundary
Content-Disposition: form-data; name="document"; filename="example-document.pdf"
Content-Type: application/pdf

<PDF data>
--customboundary
Content-Disposition: form-data; name="image-local"; filename="image-watermark.png"
Content-Type: application/pdf

<PDF data>
--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": 0
      },
      "actions": {
        "type": "watermark",
        "image": "image-local",
        "width": 100
      }
    },
    {
      "file": "document",
      "pages": {
        "start": 1,
        "end": 2
      }
    },
    {
      "file": "document",
      "pages": {
        "start": 3,
        "end": 3
      },
      "actions": {
        "type": "watermark",
        "text": "TOP SECRET",
        "width": 100,
        "height": 200
      }
    }
  ],
  "actions": [
    {
      "type": "flatten"
    }
  ]
}
--customboundary--

Watermarking a file from URL

Instead of paths to local files, you can use URLs to specify both the documents to be watermarked in the file parts and the images to use for image watermarks.

The following example adds an image annotation to all pages of a document and flattens them so that the watermark can’t be erased. This request to the /api/build endpoint attaches two URLs, which point to the input file and the image, respectively:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F instructions='{
  "parts": [
    {
      "file": {
        "url": "https://pspdfkit.com/downloads/examples/paper.pdf"
      },
      "pages": {
        "start": 0,
        "end": 0
      },
      "actions": {
        "type": "watermark",
        "image": {
          "url": "https://image-url.com/path-to-image-on-internet.png"
        },
        "width": 100
      }
    }
  ],
  "actions": [
    {
      "type": "flatten"
    }
  ]
}' \
  -o result.pdf

POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": {
        "url": "https://pspdfkit.com/downloads/examples/paper.pdf"
      },
      "pages": {
        "start": 0,
        "end": 0
      },
      "actions": {
        "type": "watermark",
        "image": {
          "url": "https://image-url.com/path-to-image-on-internet.png"
        },
        "width": 100
      }
    }
  ],
  "actions": [
    {
      "type": "flatten"
    }
  ]
}
--customboundary--

When using a URL to specify the path for an image annotation, the MIME type of the image needs to be a part of the image’s URL. In the example above, the MIME type of the image is png.

Exporting watermarks added to a PDF document

You can export the current annotations (including watermarks) of a PDF document as an Instant JSON file through a GET request to Document Engine’s /api/documents/:document_id/document.json endpoint. For more information, refer to the import and export Instant JSON PDF annotation data guide.