Creating Annotations with Vault API

Within the Vault UI, users can mark up and comment on documents with a wide variety of annotation types. Learn more about annotating documents in Vault Help.

If your organization needs to create multiple annotations across documents, such as for a migration, we recommend using Vault API. If you are new to Vault API, check out the Vault API Getting Started Guide.

This guide walks through how to retrieve annotation metadata, create annotations by sending requests to Vault API, and troubleshoot errors.

Retrieving Annotation Type Metadata

Before creating annotations, you must send a request to the Retrieve Annotation Type Metadata endpoint to retrieve the available metadata for a specific annotation type. Provide the {annotation_type} URI path parameter to indicate which annotation type you'd like to retrieve metadata for.

When the request is successful, the response includes a list of metadata for the specified annotation type. The fields returned in each response may vary depending on type. Annotation properties that are system-managed (system_managed=true) must be excluded when creating annotations. The following subsections elaborate on this metadata, which can help you create multiple annotations effectively with Vault API.

Replies Allowed

You can only reply, or add reply (reply__sys) type annotations, to specific annotation types. When retrieving annotation type metadata, the allows_replies attribute in the response indicates whether this annotation type allows replies. If true, this annotation type accepts replies. When creating replies with Vault API, attempting to do so for an annotation type that does not allow replies will result in an error.

Allowed Placemark Types

All annotation types require placemarks, which indicate where and how an annotation appears on a document. Each annotation type only accepts specific placemark types. When retrieving annotation type metadata, the allowed_placemark_types array in the response indicates which placemark types are allowed for that annotation type. The example below shows a list of allowed placemark types for anchor (anchor__sys) annotations.

"allowed_placemark_types": [
            "page_level__sys",
            "rectangle__sys",
            "sticky__sys",
            "text__sys"
    ]

When creating annotations with Vault API, providing a value other than the allowed placemark types will result in an error. Learn more about each placemark type in About Annotations.

Allowed Reference Types

The following annotation types allow references:

Document link (document_link__sys)
Permalink (permalink_link__sys)
External link (external_link__sys)

When retrieving annotation type metadata, the allowed_reference_types array in the response indicates which reference types this annotation type allows, if any. The example below shows the singular reference type, document__sys, allowed for document link (document_link__sys) annotations.

"allowed_reference_types": [
            "document__sys"
        ]

When creating annotations with references, providing a value other than the allowed reference types will result in an error. Learn more about each reference type in About Annotations.

Field Value Sets

Some fields listed in the response have a non-empty value_set array, listing acceptable values for that field. The example below shows the color__sys field and its acceptable colors for the note (note__sys) annotation type.

{
    "name": "color__sys",
    "type": "String",
    "system_managed": false,
    "value_set": [
        "yellow_light__sys",
        "green_dark__sys",
        "green_light__sys",
        "orange_dark__sys",
        "orange_light__sys",
        "pink_dark__sys",
        "pink_light__sys",
        "purple_dark__sys",
        "purple_light__sys",
        "red_dark__sys",
        "red_light__sys",
        "yellow_dark__sys"
    ]
}

Creating Annotations

You can use the Create Multiple Annotations endpoint to create up to 500 annotations in a single request.

This endpoint accepts a JSON-formatted comma-separated list of annotation objects, each containing a list of annotation properties and their values. These properties can be retrieved by retrieving annotation type metadata. Annotation properties that are system-managed (system_managed=true) must be excluded when creating annotations. Alternatively, see the API Reference to learn more about the body parameters required for each annotation type. The example below shows the JSON object for a document link (document_link__sys) annotation.

{
    "type__sys": "document_link__sys",
    "document_version_id__sys": "12_1_0",
    "placemark": {
        "type__sys": "text__sys",
        "page_number__sys": 1,
        "text_start_index__sys": 10,
        "text_end_index__sys": 15
    },
    "references": [
        {
            "type__sys": "document__sys",
            "document_version_id__sys": "11_1_0",
            "annotation__sys": "46"
        }
    ]
}

When the request is successful, the response lists each annotation object provided in the request body, indicating whether the annotation was successfully created. Each successfully created annotation returns document metadata in addition to the new annotation's ID. To verify annotation creation, we recommend using Read Annotations by Document Version and Type to review its metadata or to verify its existence in the Vault UI document viewer.

The following sections reference the example above to explain how to generate placemarks and references for annotations.

Creating Placemarks

All annotations require a placemark indicating its location and appearance. The allowed placemark types for a specific annotation type are returned in the response when retrieving annotation type metadata.

The fields that can be provided for a specific placemark type can be obtained by sending a request to Retrieve Annotation Placemark Type Metadata. Some fields may be read-only, while other fields cannot be populated alongside others. Review the considerations for placemark types prior to creating placemarks.

The example below shows the placemark metadata provided to create a document link (document_link__sys) annotation. This annotation has a text (text__sys) placemark type, which specifies a text selection on the document tied to the annotation. The remaining metadata indicates the location of the text selection, existing on the 10th-15th word on the first page of the document.

"placemark": {
        "type__sys": "text__sys",
        "page_number__sys": 1,
        "text_start_index__sys": 10,
        "text_end_index__sys": 15
    }

Placemark locations can be indicated using coordinates, width-height, or text indices. If allowed for the specified placemark type, use coordinates__sys when possible. Learn more about placemark fields in About Annotations.

Creating Annotations with References

Only document link (document_link__sys), permalink (permalink_link__sys), and external link (external_link__sys) annotations require references. This can be a document, an anchor annotation on a document, an external URL, or a permalink. The allowed reference types for a specific annotation type are returned in the response when retrieving annotation type metadata. The fields that can be provided for a specific reference type can be obtained by sending a request to Retrieve Annotation Reference Type Metadata.

The example below shows the reference metadata provided to create a document link (document_link__sys) annotation. This annotation type only accepts a document (document__sys) reference type, which requires the ID and version number of the referenced document. For document references, you can optionally provide the ID of the referenced anchor annotation. Otherwise, you can omit it to reference an entire document.

"references": [
    {
        "type__sys": "document__sys",
        "document_version_id__sys": "11_1_0",
        "annotation__sys": "46"
    }
]

Likewise, permalink and external link annotations require different fields to reference their respective entities. Learn more about annotation references in About Annotations.

Creating Annotation Replies

You must use the Add Annotation Replies endpoint to create up to 500 annotation replies in a single request. Parent annotations must exist in your Vault before creating replies.

This endpoint accepts a JSON-formatted comma-separated list of annotation reply objects, each containing a list of properties and their values. These properties can be retrieved by retrieving annotation type metadata for the reply (reply__sys) annotation type. Reply annotations must also have the same required fields as other annotation types. Annotation properties that are system-managed (system_managed=true) must be excluded when creating annotation replies.

The example below shows the JSON object for a reply annotation. Replies require a placemark, whose type must always be reply (reply__sys). Within the placemark JSON array, indicate the ID of the parent annotation (reply_parent__sys), which must already exist in your Vault.

{
    "document_version_id__sys": "1_0_1",
    "type__sys": "reply__sys",
    "comment__sys": "first reply from the api",
    "placemark": {
        "type__sys": "reply__sys",
        "reply_parent__sys": "54"
    }
}

When the request is successful, the response lists each reply annotation object provided in the request body, indicating whether the reply was successfully created. Each successfully created annotation returns document metadata in addition to the new reply's ID. To verify reply annotation creation, we recommend using Read Annotations by Document Version and Type to review its metadata or to verify its existence in the Vault UI document viewer.

Troubleshooting Tips

The table below offers solutions to common issues that may arise while creating annotations with Vault API.

Category	Error Message	Solution
Placemarks	`Value for fields, [text_start_index__sys,text_end_index__sys], must be valid index for text on page [X] in document version [X_X_X].`	Create coordinate-based text annotations instead. In the case where the `coordinates__sys` value is not populated and you run into this error, then you should create the annotation using the `page_level__sys` placemark type.
Placemarks	`Value for placemark fields, [x_coordinate__sys,y_coordinate__sys], must be valid location on page [X] in document version [X_X_X].`	Create the annotation at the same page, but using the `page_level__sys` placemark type.
Placemarks	`Sum of values for fields [width__sys] and [x_coordinate__sys] must be a valid location in the document's page.`	Create the annotation at the same page, but using the `page_level__sys` placemark type.
Placemarks	`Value for placemark fields, [x_coordinate__sys,y_coordinate__sys], cannot be negative.`	Coordinates cannot be negative values. Create the annotation at the same page, but using the `page_level__sys` placemark type.
References	`Annotation reference field [XXX] does not resolve to an existing anchor annotation.`	The referenced annotation must already exist in your Vault. Check for previous failures in the batch.
References	`Value for [comment__sys] annotation field contains one or more invalid Vault user mentions.`	Make sure the user mentioned exists and is active in your Vault. They must also have View Content permission for the document.