Skip to content

Import Document Version Annotations from PDF

Load annotations from a PDF to Vault. This is equivalent to the Import Annotations action in the Vault document viewer UI. The file must be a PDF created by exporting annotations for the specified version of the same document through either the Export Annotations action in the Vault UI or the Export Document Version Annotations as PDF endpoint.

To import annotations, you must have a role on the document that includes the Annotate permission. To import redaction (redaction__sys) annotations, you must have the Redact permission on the document's current lifecycle state.

POST/api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations/file

Include the following request headers.

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB. Vault truncates annotations that exceed the following character limits:

  • Note annotations: Subject (in Header) limited to 32,000 characters
  • Note, Line, and Reply annotations: Comment limited to 32,000 characters
NameDescription
Content-Typemultipart/form-data
Acceptapplication/json (default) or application/xml
NameDescription
{doc_id}The document id field value.
{major_version}The document major_version_number__v field value.
{minor_version}The document minor_version_number__v field value.

When importing a PDF that contains redaction annotations, Vault reconciles annotations against the current active redaction record for the document's current Steady State. If no active record exists, Vault creates one automatically in the redacting_source__sys state.

Redaction type resolution: Vault maps each imported redaction annotation to a redaction type using the following resolution order:

  1. The annotation's overlay text, matched against active redaction type names (exact match, case- and whitespace-normalized)
  2. Other: If no match is found, the annotation resolves to the other__sys redaction type. This fallback is reported in the response.

Upsert behavior: Re-importing a previously imported PDF does not create duplicate annotations. An annotation matching an existing one by page, geometry, and type is updated in place. An annotation absent from a prior import is added as new. Existing Vault annotations not present in the imported PDF are left in place and not removed.

Page-level data-leak prevention: If an imported annotation cannot be reliably placed at a specific location on the document (untraceable displacement), Vault converts it to a page-level annotation and blocks the Generate Redacted Copy action until the annotation is corrected or removed. Redaction type fallbacks to other__sys are reported in the same response surface as page-level displacement issues.

curl -X POST -H "Authorization: {AUTH_VALUE}" \
-H "Content-Type: multipart/form-data" \
-F "file=document2016.pdf" \
https://myvault.veevavault.com/api/v26.3/objects/documents/548/versions/2/1/annotations/file
{
    "responseStatus": "SUCCESS",
    "responseMessage": "OK",
    "replies": 0,
    "failures": 0,
    "new": 0
}

On SUCCESS, Vault uploads the file and its annotations.

FieldDescription
redaction_fallbacksThe number of redaction annotations that fell back to the other__sys type during import because no type match was found.
redaction_page_levelThe number of redaction annotations converted to page-level due to untraceable placement displacement. These block the Generate Redacted Copy action until corrected.