Adding stamp annotations to a PDF document

Use stamp annotations to mark document state in PDF workflows.

Common use cases include:

  • Approval and rejection workflows
  • Draft and final document marking
  • Confidentiality labeling
  • Quality control and review tracking

In this guide, you’ll add:

  • Default and custom stamp styles
  • Color-customized stamps
  • Multiple status stamps on one page
Download sample

How Nutrient helps

Nutrient Python SDK handles stamp annotation structures and appearance generation.

The SDK handles:

  • Stamp annotation dictionaries and icon rendering
  • Stamp appearance streams and text positioning
  • Stamp style resources and icon loading
  • Appearance state and color transformations

Complete implementation

This example adds several stamp annotations to a PDF file:

from nutrient_sdk import Document
from nutrient_sdk import PdfEditor
from nutrient_sdk import Color
from nutrient_sdk import PdfRubberStampIcon
from nutrient_sdk import NutrientException

Working with stamp annotations

Open the document in a context manager(opens in a new tab) so resources are cleaned up after processing.

Then:

  • Create a PDF editor.
  • Get the page collection.
  • Add a letter-size page (612 × 792) if the document is empty.
  • Get the annotation collection from the first page.
def main():
    try:
        with Document.open("input.pdf") as document:
            editor = PdfEditor.edit(document)
            pages = editor.get_page_collection()


            if pages.get_count() == 0:
                pages.add(612.0, 792.0)


            page = pages.get_first()
            annotations = page.get_annotation_collection()

Adding a basic stamp

Add a stamp with add_stamp(x, y, width, height, author, content).

In this sample:

  • The position is (400, 700).
  • The size is 150 × 50.
  • The default style is DRAFT.
  • The default color is red (ARGB 255, 255, 0, 0).
            draft_stamp = annotations.add_stamp(
                400.0, 700.0, 150.0, 50.0,  # x, y, width, height
                "Author",
                "Work in progress"
            )

Adding an approved stamp

Add a second stamp and customize its style.

This sample:

  • Adds a stamp at (400, 600).
  • Sets stamp_style to PdfRubberStampIcon.APPROVED.
  • Sets the color to green with Color.from_argb(255, 0, 128, 0).
            approved_stamp = annotations.add_stamp(
                400.0, 600.0, 150.0, 50.0,  # x, y, width, height
                "Approver Name",
                "Document approved on review"
            )
            # Customize the stamp appearance
            approved_stamp.stamp_style = PdfRubberStampIcon.APPROVED
            approved_stamp.color = Color.from_argb(255, 0, 128, 0)

Adding a confidential stamp

Add a confidentiality stamp and set its icon style.

This sample sets:

  • The position to (400, 500).
  • stamp_style to PdfRubberStampIcon.CONFIDENTIAL.

The stamp keeps the default red color unless you set a different color:

            confidential_stamp = annotations.add_stamp(
                400.0, 500.0, 150.0, 50.0,  # x, y, width, height
                "Security Officer",
                "Contains sensitive information"
            )
            # Customize the stamp appearance
            confidential_stamp.stamp_style = PdfRubberStampIcon.CONFIDENTIAL

Other available stamp types

Use other PdfRubberStampIcon values to represent more states.

This sample adds:

  • A NOT_APPROVED stamp at (50, 700).
  • A FINAL stamp at (50, 600) with the color blue (ARGB 255, 0, 0, 255).
            # Not Approved stamp
            not_approved_stamp = annotations.add_stamp(
                50.0, 700.0, 150.0, 50.0,  # x, y, width, height
                "Reviewer",
                "Rejected"
            )
            not_approved_stamp.stamp_style = PdfRubberStampIcon.NOT_APPROVED


            # Final stamp
            final_stamp = annotations.add_stamp(
                50.0, 600.0, 150.0, 50.0,  # x, y, width, height
                "Legal",
                "Final version"
            )
            final_stamp.stamp_style = PdfRubberStampIcon.FINAL
            final_stamp.color = Color.from_argb(255, 0, 0, 255)

Saving the document

Save the output PDF and close the editor.

The except block catches NutrientException if processing fails:

            editor.save_as("output.pdf")
            editor.close()
    except NutrientException as e:
        print(f"Error: {e}")




if __name__ == "__main__":
    main()

Conclusion

Use this workflow to add stamp annotations:

  1. Open the document using a context manager(opens in a new tab) for automatic resource cleanup.
  2. Create an editor and access the page collection.
  3. Ensure at least one page exists by adding a letter-size page if needed.
  4. Retrieve the annotation collection for the target page.
  5. Add basic stamp annotations with the default DRAFT style and red color.
  6. Customize stamp styles using the stamp_style property with PdfRubberStampIcon enumeration values.
  7. Customize stamp colors using the color property with ARGB color values.
  8. Add APPROVED stamps with green color for approval workflows.
  9. Add CONFIDENTIAL stamps for marking sensitive documents.
  10. Add NOT_APPROVED stamps for rejection indicators.
  11. Add FINAL stamps to mark completed documents.
  12. Save and close the editor.

For related annotation workflows, refer to the Python SDK annotation guides.