Annotations API

The Annotations API makes it easy to add, read, and delete annotations on documents in Aprimo. You just provide the required properties in JSON, and Aprimo will generate and store the correct Annotation format automatically.

This makes it simpler and faster to integrate annotations into your applications.

Supported Annotation Types

The first release supports these annotation tools:

Rectangle
Highlight
Strikeout

Future updates may include additional tools, replies, and the ability to edit existing annotations.

How It Works

When you create an annotation, you’ll provide a JSON payload describing:

Type – The tool you’re using (rectangle, highlight, strikeout).
Page – Which page of the document the annotation belongs to.
Author – The user who created the annotation.
Geometry – The bounding box (and, if needed, quads for text highlights/strikeouts).
Style – Visual options like color, width, or opacity.
Content – The annotation comment, optional quoted text, or labels.
Reference Link – Optional link to another Aprimo asset.

Aprimo then converts this request into an annotation string behind the scenes and saves it.

Annotation Configuration

The Annotations API supports three tools: Rectangle, Highlight, and Strikeout.
Each tool requires a different combination of geometry, style, and content properties.

Common Fields (All Annotation Types)

Every annotation request requires these fields:

Property	Type	Required	Notes
`type`	string	✅	Must be one of: `rectangle`, `highlight`, `strikeout`
`page`	integer	✅	Page number (0-indexed)
`authorId`	integer	✅	Aprimo user ID of the creator. If this is an application user, they can modify the annotation in the UI
`geometry`	object	✅	Defines the position of the `annotation` (bounding box and/or quads)
`style`	object	✅	Defines visual style such as color, width, or opacity
`content`	object	✅	The text/comment content of the `annotation`
`referenceLink`	object	❌	Optional link to a reference document in the DAM

Rectangle Annotation Fields

Use a rectangle to mark areas on a page.

Required Fields:

geometry.boundingBox – the Rectangle’s position
style.color – Hex color string
style.width – Line Thickness (1–20)

Optional Fields:

content.comment – Max of 3700 characters
content.fixedLabel – Max of 120 characters. Fixed data, not editable in the UI
referenceLink – Optional link to a reference document in the DAM

Highlight Annotation Fields

Use a highlight to mark text passages.

Required Fields:

geometry.boundingBox – Bounding area around the highlight
geometry.quads – Array of coordinates for each text segment
style.color – Hex color string
style.opacity – Transparency Level (0.0–1.0)

Optional Fields:

content.comment – Max of 3700 characters
content.quotedText – Max of 3700 characters. Fixed data, not editable in the UI
content.fixedLabel – Max of 120 characters. Fixed data, not editable in the UI
referenceLink – Optional link to a reference document in the DAM

Strikeout Annotation Fields

Use strikeout to mark text that should be removed or ignored.

Required Fields:

geometry.boundingBox – Bounding area around the strikeout
geometry.quads – Array of coordinates for each text segment
style.color – Hex color string

Optional Fields:

content.comment – Max of 3700 characters
content.quotedText – Max of 3700 characters. Fixed data, not editable in the UI
content.fixedLabel – Max of 120 characters. Fixed data, not editable in the UI
referenceLink – Optional link to a reference document in the DAM

Geometry Details

Bounding Box

Property	Type	Notes
`left`	float	Lower-left X
`bottom`	float	Lower-left Y
`right`	float	Upper-right X
`top`	float	Upper-right Y

Quads Each quad describes a four-point polygon around a text segment.

Property	Type	Notes
`x1,y1`	double	Top-left corner
`x2,y2`	double	Top-right corner
`x3,y3`	double	Bottom-right corner
`x4,y4`	double	Bottom-left corner

Style

Property	Type	Notes
color	string	Hex color string
width	integer	1 - 20
opacity	double	0.00 - 1.00

Content

Property	Type	Notes
comment	string	Supports linebreak characters
quotedText	string	Max of 3700 characters. Fixed data, not editable in the UI
fixedLabel	string	Max of 120 characters. Fixed data, not editable in the UI

Reference Link

Property	Type	Notes
documentUuid	string	Record ID of a DAM Asset

Response Payload

When you create or fetch an annotation, the API returns:

Property	Type	Notes
`annotationId`	integer	Unique ID for the `annotation`
`authorId`	integer	User ID of the creator
`associatedNumber`	integer	`annotation` number on the document
`createdDate`	datetime	When the `annotation` was created
`modifiedDate`	datetime	When the `annotation` was last modified
`type`	string	`rectangle`, `highlight`, or `strikeout`
`page`	integer	Page number (0-indexed)
`geometry`	object	Geometry details
`style`	object	Style details
`content`	object	`annotation` content
`referenceLink`	object	Linked DAM Asset (if any)
`replyCount`	integer	Number of replies (including status changes)

Derived Annotation Values

These values are automatically generated by Aprimo when saving the annotation:

Property	Source	Notes
`name`	auto-generated GUID	Unique identifier
`subject`	type of `annotation`	Rectangle, Highlight, Strikeout
`creationdate`	current datetime	When `annotation` was created
`date`	current datetime	When `annotation` was created or edited
`flags`	`"print"`	Fixed value
`dashes`	`""`	Fixed value

Example Requests

Create a Rectangle

POST /api/assets/{id}/versions/{versionId}/annotations-data

{
  "type": "rectangle",
  "page": 3,
  "authorId": 57,
  "geometry": {
    "boundingBox": {
      "left": 27.44,
      "bottom": 220.16,
      "right": 358.12,
      "top": 456.98
    }
  },
  "style": {
    "color": "#C544CE",
    "width": 4
  },
  "content": {
    "comment": "This is the main text of the annotation",
    "fixedLabel": "Created by API"
  },
  "referenceLink": {
    "documentUuid": "25E4AF5A-6DB3-72DC-F5F1-E18F32627863"
  }
}

Create a Highlight

POST /api/assets/{id}/versions/{versionId}/annotations-data

{
  "type": "highlight",
  "page": 6,
  "authorId": 57,
  "geometry": {
    "boundingBox": {
      "left": 67.876,
      "bottom": 622.707,
      "right": 418.453,
      "top": 724.882
    },
    "quads": [{
      "x1": 67.87, "y1": 724.88,
      "x2": 263.80, "y2": 724.88,
      "x3": 67.87, "y3": 694.70,
      "x4": 263.80, "y4": 694.70
    }]
  },
  "style": {
    "color": "#C544CE",
    "opacity": 0.65
  },
  "content": {
    "comment": "This is the main comment of the annotation",
    "quotedText": "Poor UX: Slow Performance, Crashing, and Inaccurate Rendering",
    "fixedLabel": "Created by API"
  },
  "referenceLink": {
    "documentUuid": "16AB7575-D6D0-E2AC-34C6-32F79DF7CACE"
  }
}

API Endpoints

List Annotations

GET /api/assets/{id}/versions/{versionId}/annotations-data?offset=0&limit=20

Returns a paged list of annotations on the specified document. Replies are not included.

Create Annotation

POST /api/assets/{id}/versions/{versionId}/annotations-data

Create a new annotation. See examples

Delete Annotation

DELETE /api/assets/{id}/versions/{versionId}/annotations-data/{annotationId}

Deletes an annotation by ID

Response Examples

Successful responses include full annotation details. Example response from creating a rectangle annotation:

{
  "annotationId": 242,
  "authorId": 57,
  "associatedNumber": 3,
  "createdDate": "2025-05-13T04:07:12.273",
  "modifiedDate": "2025-05-13T04:07:12.273",
  "type": "rectangle",
  "page": 3,
  "geometry": {
    "boundingBox": {
      "left": 27.44,
      "bottom": 220.16,
      "right": 358.12,
      "top": 456.98
    }
  },
  "style": {
    "color": "#C544CE",
    "width": 4
  },
  "content": {
    "comment": "This is the main text of the annotation",
    "fixedLabel": "Created by API"
  },
  "referenceLink": {
    "documentUuid": "25E4AF5A-6DB3-72DC-F5F1-E18F32627863"
  },
  "replyCount": 0
}

Validation & Limitations

The API does not check if the page number is valid for the document.
It does not verify if bounding box or quad values are within document bounds.
Sending the same payload multiple times may create duplicate annotations.
Editing annotations and creating replies is not yet supported.
Attachments are not supported.

Next Steps

Try out the new endpoints in your environment.
Use the simplified JSON contract to create annotations.
Watch for future enhancements, including replies, editing, and more annotation tools.

Supported Annotation Types​

How It Works​

Annotation Configuration​

Common Fields (All Annotation Types)​

Rectangle Annotation Fields​

Highlight Annotation Fields​

Strikeout Annotation Fields​

Geometry Details​

Style​

Content​

Reference Link​

Response Payload​

Derived Annotation Values​

Example Requests​

Create a Rectangle​

Create a Highlight​

API Endpoints​

List Annotations​

Create Annotation​

Delete Annotation​

Response Examples​

Validation & Limitations​

Next Steps​

Supported Annotation Types

How It Works

Annotation Configuration

Common Fields (All Annotation Types)

Rectangle Annotation Fields

Highlight Annotation Fields

Strikeout Annotation Fields

Geometry Details

Style

Content

Reference Link

Response Payload

Derived Annotation Values

Example Requests

Create a Rectangle

Create a Highlight

API Endpoints

List Annotations

Create Annotation

Delete Annotation

Response Examples

Validation & Limitations

Next Steps