Import Document 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 latest version of the same document through either the Export Annotations action in the Vault UI or the Export Document Annotations as PDF endpoint and edited in a supported PDF editor
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.
/api/{version}/objects/documents/{doc_id}/annotations/fileHeaders
Section link for HeadersInclude the following request headers.
| Name | Description |
|---|---|
Content-Type | multipart/form-data |
Accept | application/json (default) or application/xml |
File Upload
Section link for File UploadTo 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
URI Path Parameters
Section link for URI Path Parameters| Name | Description |
|---|---|
{doc_id} | The document id field value. |
Importing Redaction Annotations
Section link for Importing Redaction AnnotationsWhen importing a PDF that contains redaction annotations, Vault reconciles the 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 state.
Rendition type resolution: Vault maps each imported redaction annotation to a redaction type using the following resolution order:
- The annotation's overlay text, matched against active redaction type names, exact match, case- and whitespace-normalized.
- Other: If no match is found, the annotation resolves to the
other__systype. This fallback is reported in the response inredaction_fallbacks.
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 (untraceable displacement), Vault converts it to a page-level annotation and blocks the Generate Redacted Copy action on the associated redaction record until the annotation is corrected or removed. Redaction type fallbacks to other__sys are reported alongside placement issues.
Request
Section link for Requestcurl -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/annotations/fileResponse
Section link for Response{
"responseStatus": "SUCCESS",
"responseMessage": "OK",
"replies": 0,
"failures": 0,
"new": 0
}Response Details
Section link for Response DetailsOn SUCCESS, Vault uploads the file and its annotations.
For redaction (redaction__sys) annotations, the response includes additional fields:
| Field | Description |
|---|---|
redaction_fallbacks | The number of redaction annotations that resolved to the other__sys type because no Redaction Type match was found. Each fallback requires review before finalizing the redaction. |
redaction_page_level | The number of redaction annotations converted to page-level placement due to untraceable displacement. These annotations block the Generate Redacted Copy action until corrected or removed. |