Organize Annotations in PDF Document API

Apr 29, 2025
7 minutes to read

The PDF Document API supports the following annotation types:

Link AnnotationsA hypertext link to a URI or a destination (a reference to a page with specific view parameters).Markup Annotations

Annotations used to mark up document content. The following markups are available:

Text Markup (text highlight, underline, strikeout)
Sticky Note
Caret
Rubber Stamp
Shape (circle, square)
File Attachment
Free Text (text box, callout, typewriter)
Ink
Path (line, polyline, polygon)

Redaction AnnotationsTools used to remove sensitive or confidential information from a document. These annotations allow users to mark areas of text, images, or other content for redaction.

You can create, delete, and flatten annotations, edit their content, and add related comments and reviews.

The PdfPageFacade.Annotations property retrieves all page annotation properties. Use the PdfDocumentFacade.Pages property to obtain the PdfPageFacade instance.

This topic describes the following features common to all annotation types:

Edit annotations
Add comments to annotations
Add reviews to annotations
Flatten annotations
Remove annotations

Refer to the corresponding topic from the table below for more detailed information on the required annotation type.

Annotation Type	Base Class	More Information
Link Annotation	PdfLinkAnnotationFacade	Links in PDF Documents
File Attachment Annotations	PdfFileAttachmentAnnotationFacade	Attach Files to a PDF
Markup Annotations	PdfMarkupAnnotationFacade	Manage Markup Annotations
Redaction Annotations	PdfRedactAnnotationFacade	Manage Redaction

Edit Annotations

The PdfPageFacade.Annotations property returns all page annotation properties. You can filter annotation properties, cast them to the corresponding class, and use class properties to modify annotation parameters.

The code sample below changes annotations created in the previous example, so they appear as follows:

C#
VB.NET

csharp

using DevExpress.Pdf;
using System.Linq;

using (PdfDocumentProcessor processor = new PdfDocumentProcessor())
{
    // Load a document
    processor.LoadDocument("..\\..\\Result.pdf");

    // Access the first page properties
    PdfPageFacade pageFacade = processor.DocumentFacade.Pages[0];

    // Obtain all free text annotations
    var freeTextAnnotations = pageFacade.Annotations.Where
        (annotation => annotation.Type == PdfAnnotationType.FreeText);
    foreach (PdfFreeTextAnnotationFacade freeText in freeTextAnnotations) 
    { 
        // Change border parameters and text justification
        freeText.InteriorColor = new PdfRGBColor(0.36, 0.54, 0.66);
        freeText.BorderWidth = 0.5;
        freeText.TextJustification = PdfTextJustification.Centered;
    }

    // Retrieve all circle annotations
    var circleAnnotations = pageFacade.Annotations.Where
        (annotation => annotation.Type == PdfAnnotationType.Circle);
    foreach (PdfCircleAnnotationFacade pdfCircle in circleAnnotations)
    { 
        // Change border style and color
        pdfCircle.BorderStyle = PdfBorderStyle.Dash; 
        pdfCircle.Color = new PdfRGBColor(0.52, 0.87, 0.01);
    }

    // Get all rubber stamps 
    var rubberStampAnnotations = pageFacade.Annotations.Where
        (annotation => annotation.Type == PdfAnnotationType.RubberStamp);
    foreach (PdfRubberStampAnnotationFacade pdfRubberStamp in rubberStampAnnotations)
    {
        // Generate a stamp from another document’s page
        pdfRubberStamp.SetCustomIcon("..\\..\\Demo.pdf", 4);
    }

    // Obtain all file attachments
    var fileAttachments = pageFacade.Annotations.Where
        (annotation => annotation.Type == PdfAnnotationType.FileAttachment);
    foreach (PdfFileAttachmentAnnotationFacade fileAttachment in fileAttachments) 
    {
        // Change the icon and its color
        fileAttachment.Color = new PdfRGBColor(0.83, 0.13, 0.18);
        fileAttachment.IconName = PdfFileAttachmentAnnotationIconName.Tag;
    }
        // Save the result
        processor.SaveDocument("..\\..\\Result_1.pdf");
}

Imports DevExpress.Pdf
Imports System.Linq

Using processor As New PdfDocumentProcessor()
  ' Load a document
  processor.LoadDocument("..\..\Result.pdf")

  ' Access the first page properties
  Dim pageFacade As PdfPageFacade = processor.DocumentFacade.Pages(0)

  ' Obtain all free text annotations
  Dim freeTextAnnotations = pageFacade.Annotations.Where
      (Function(annotation) annotation.Type = PdfAnnotationType.FreeText)
  For Each freeText As PdfFreeTextAnnotationFacade In freeTextAnnotations

    ' Change border parameters and text justification
    freeText.InteriorColor = New PdfRGBColor(0.36, 0.54, 0.66)
    freeText.BorderWidth = 0.5
    freeText.TextJustification = PdfTextJustification.Centered
  Next freeText

  ' Retrieve all circle annotations
  Dim circleAnnotations = pageFacade.Annotations.Where
      (Function(annotation) annotation.Type = PdfAnnotationType.Circle)
  For Each pdfCircle As PdfCircleAnnotationFacade In circleAnnotations

    ' Change border style and color
    pdfCircle.BorderStyle = PdfBorderStyle.Dash
    pdfCircle.Color = New PdfRGBColor(0.52, 0.87, 0.01)
  Next pdfCircle

  ' Get all rubber stamps 
  Dim rubberStampAnnotations = pageFacade.Annotations.Where
      (Function(annotation) annotation.Type = PdfAnnotationType.RubberStamp)
  For Each pdfRubberStamp As PdfRubberStampAnnotationFacade In rubberStampAnnotations

    ' Generate a stamp from another document’s page
    pdfRubberStamp.SetCustomIcon("..\..\Demo.pdf", 4)
  Next pdfRubberStamp

  ' Obtain all file attachments
  Dim fileAttachments = pageFacade.Annotations.Where
      (Function(annotation) annotation.Type = PdfAnnotationType.FileAttachment)
  For Each fileAttachment As PdfFileAttachmentAnnotationFacade In fileAttachments

    ' Change the icon and its color
    fileAttachment.Color = New PdfRGBColor(0.83, 0.13, 0.18)
    fileAttachment.IconName = PdfFileAttachmentAnnotationIconName.Tag
  Next fileAttachment

    ' Save the result
    processor.SaveDocument("..\..\Result_1.pdf")
End Using

Add Comments to Annotations

Use API from the table below to add comments to markup annotations:

API	Description
PdfMarkupAnnotationFacade.AddReply	Adds a comment to the annotation. This method returns the PdfMarkupAnnotationComment object. Use this class’ members to change the reply’s author, subject and text.
PdfMarkupAnnotationFacade.Replies	Obtains all annotation comments.
PdfMarkupAnnotationComment.AddReply	Creates a nested comment.
PdfMarkupAnnotationComment.Replies	Gets all nested comments added to the comment.
PdfMarkupAnnotationComment.AddReview	Adds a review to the comment. Use the PdfMarkupAnnotationFacade.Reviews property to get all reviews.

The code sample below adds two nested comments to all sticky notes (the document in opened in WinForms PDF Viewer):

C#
VB.NET

csharp

using (PdfDocumentProcessor processor = new PdfDocumentProcessor())
{
    // Load a document
    processor.LoadDocument("..\\..\\Document.pdf");

    // Access the first page properties
    PdfPageFacade pageFacade = processor.DocumentFacade.Pages[0];

    // Retrieve all text annotations
    var stickyNotes = pageFacade.Annotations.Where
            (annotation => annotation.Type == PdfAnnotationType.Text);
    foreach (PdfTextAnnotationFacade stickyNote in stickyNotes)
    {
        // Add comments
        AddAnnotationComments(stickyNote);
    }

    // Save the result
    processor.SaveDocument("..\\..\\Result.pdf");
}

private static void AddAnnotationComments(PdfMarkupAnnotationFacade annotation)
{
    PdfMarkupAnnotationComment comment =
       annotation.AddReply("Reviewer", "Done");
    comment.Subject = "Proofread";

    PdfMarkupAnnotationComment nestedComment =
       comment.AddReply(annotation.Author, "Thanks");
    nestedComment.Subject = "Reviewed";
}

Using processor As New PdfDocumentProcessor()
  ' Load a document
  processor.LoadDocument("..\..\Document.pdf")

  ' Access the first page properties
  Dim pageFacade As PdfPageFacade = processor.DocumentFacade.Pages(0)

  ' Retrieve all text annotations
  Dim stickyNotes = pageFacade.Annotations.Where
    (Function(annotation) annotation.Type = PdfAnnotationType.Text)
  For Each stickyNote As PdfTextAnnotationFacade In stickyNotes
    ' Add comments
    AddAnnotationComments(stickyNote)
  Next stickyNote

  ' Save the result
  processor.SaveDocument("..\..\Result.pdf")
End Using

private static void AddAnnotationComments(PdfMarkupAnnotationFacade annotation)
  Dim comment As PdfMarkupAnnotationComment = annotation.AddReply("Reviewer", "Done")
  comment.Subject = "Proofread"

  Dim nestedComment As PdfMarkupAnnotationComment = comment.AddReply(annotation.Author, "Thanks")
  nestedComment.Subject = "Reviewed"

Add Reviews to Annotations

Call the PdfMarkupAnnotationFacade.AddReview method to add a review to the markup annotation. The PdfMarkupAnnotationFacade.Reviews property obtains all annotation reviews.

To remove all reviews, call the PdfMarkupAnnotationFacade.ClearReviews() method.

The code sample below adds a review to the annotations from a specific author (the document is opened in the WinForms PDF Viewer):

C#
VB.NET

csharp

using DevExpress.Pdf;

using (PdfDocumentProcessor processor = new PdfDocumentProcessor())
{
    // Load a document
    processor.LoadDocument("..\\..\\Document.pdf");

    // Access the first page properties
    PdfPageFacade pageFacade = processor.DocumentFacade.Pages[0];

    foreach(PdfMarkupAnnotationFacade markupAnnotation in pageFacade.Annotations)
    {

        // Check the annotation author
        if (markupAnnotation.Author == "Brian Zetc") 
        {

          // Add a review to the annotation
            markupAnnotation.AddReview("Cardle Anita W", PdfAnnotationReviewStatus.Accepted);
        }
    }
    // Save the result
    processor.SaveDocument("..\\..\\Result.pdf");
}

Imports DevExpress.Pdf

Using processor As New PdfDocumentProcessor()
  ' Load a document
  processor.LoadDocument("..\..\Document.pdf")

  ' Access the first page properties
  Dim pageFacade As PdfPageFacade = processor.DocumentFacade.Pages(0)

  For Each markupAnnotation As PdfMarkupAnnotationFacade In pageFacade.Annotations

    ' Check the annotation author
    If markupAnnotation.Author = "Brian Zetc" Then

      ' Add a review to the annotation
      markupAnnotation.AddReview("Cardle Anita W", PdfAnnotationReviewStatus.Accepted)
    End If
  Next markupAnnotation
  ' Save the result
  processor.SaveDocument("..\..\Result.pdf")
End Using

Flatten Annotations

Call one of the following methods to flatten an annotation:

Method	Description
PdfDocumentFacade.FlattenAnnotations	Flattens document annotations.
PdfPageFacade.FlattenAnnotations	Flattens annotations of a specific page.
PdfAnnotationFacade.Flatten()	Flattens a specific annotation.

Note

When you call one of the Flatten… methods for redaction annotations, their overlay parameters (text, fill color, and so on) are not applied and redacted content is not removed. Use one of the ApplyRedactAnnotations methods to apply these annotations.

The code sample below flattens all text annotations in the document:

C#
VB.NET

csharp

using (PdfDocumentProcessor processor = new PdfDocumentProcessor())
{
  // Load a document:
  processor.LoadDocument("..\\..\\Document.pdf");

  // Flatten all text annotations:
  PdfDocumentFacade documentFacade = processor.DocumentFacade;
  documentFacade.FlattenAnnotations(PdfAnnotationType.Text);

  // Save the result:
  processor.SaveDocument("..\\..\\Result.pdf");
}

Using processor As New PdfDocumentProcessor()
  ' Load a document:
  processor.LoadDocument("..\..\Document.pdf")

  ' Flatten all text annotations:
  Dim documentFacade As PdfDocumentFacade = processor.DocumentFacade
  documentFacade.FlattenAnnotations(PdfAnnotationType.Text)

  ' Save the result:
  processor.SaveDocument("..\..\Result.pdf")
End Using

Remove Annotations

Call the PdfAnnotationFacade.Remove() method to remove an annotation.

The code sample below removes all annotations from a specific author:

C#
VB.NET

csharp

using DevExpress.Pdf;
using System.Linq;

using (PdfDocumentProcessor processor = new PdfDocumentProcessor())
{
    // Load a document
    processor.LoadDocument("..\\..\\Document.pdf");

    // Access the first page properties
    PdfPageFacade pageFacade = processor.DocumentFacade.Pages[0];

    // Retrieve all markup annotations
    var markups = pageFacade.Annotations.Where
            (annotation => annotation.Type != PdfAnnotationType.Link).ToList();
    foreach(PdfMarkupAnnotationFacade markupAnnotation in markups)
    {
        // Check the annotation author
        if (markupAnnotation.Author == "Brian Zetc")
        {
            // Remove the annotation
            markupAnnotation.Remove();
        }
    }
    // Save the result
    processor.SaveDocument("..\\..\\Result.pdf");
}

Imports DevExpress.Pdf
Imports System.Linq

Using processor As New PdfDocumentProcessor()
  ' Load a document
  processor.LoadDocument("..\..\Document.pdf")

  ' Access the first page properties
  Dim pageFacade As PdfPageFacade = processor.DocumentFacade.Pages(0)

  ' Retrieve all markup annotations
  Dim markups = pageFacade.Annotations.Where
    (Function(annotation) annotation.Type <> PdfAnnotationType.Link).ToList()
  For Each markupAnnotation As PdfMarkupAnnotationFacade In markups

    ' Check the annotation author
    If markupAnnotation.Author = "Brian Zetc" Then

      ' Remove the annotation
      markupAnnotation.Remove()
    End If
  Next markupAnnotation

  ' Save the result
  processor.SaveDocument("..\..\Result.pdf")
End Using