Export Bulk Annotations

Export all annotations created or modified within a specified date range across documents to your Vault's file staging. Only includes annotations where the authenticated user has the View Content permission, others are silently excluded from the export. You must have permission to access file staging to use this endpoint.

Retrieve your bulk annotation export in three steps:

Call this endpoint to request the bulk annotation export, which starts an asynchronous job and returns a job ID.
With the job ID, poll the job with Retrieve Job Status, which returns the URL to file staging.
With the file staging URL from retrieving the job status, call Download Item Content to download the file from file staging.

POST/api/{version}/objects/documents/annotations/batch/actions

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`

Query Parameters

Name	Description
`start_date` required	Start of the date range, inclusive. Matches annotations whose modified date falls on or after this value. If the modified date is `null`, uses the created date. Accepts datetime `YYYY-MM-DDTHH:mm:ssZ` or date-only `YYYY-MM-DD`.
`end_date`	End of the date range, inclusive. If omitted, defaults to the current date and time. Cannot be a future date. The range between `start_date` and `end_date` cannot exceed one year.
`include_placemark`	When `true`, includes each annotation's placemark data in the export. Defaults to `false` to improve performance.

Request

curl -X POST -H "Authorization: {AUTH_VALUE}" \
"https://myvault.veevavault.com/api/v26.3/objects/documents/annotations/batch/actions?start_date=2025-01-01&end_date=2025-12-31&include_placemark=true"

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "jobId": "1276601",
        "url": "/api/v26.3/services/jobs/1276601"
    }
}

Response Details

On SUCCESS, Vault schedules the export job and returns a jobId and url to Retrieve the Job Status.

When the job reaches a SUCCESS status, the Retrieve Job Status response includes links to entries that point directly to the exported file in file staging. No separate results endpoint is required. Download the file from file staging with Download Item Content using the content href. For example:

"links": [
    {
        "rel": "file",
        "href": "/api/v26.3/services/file_staging/items/u{userId}/{jobId}/{start_date}-{end_date}-annotations_export-vault{vaultId}.zip",
        "method": "GET"
    },
    {
        "rel": "content",
        "href": "/api/v26.3/services/file_staging/items/content/u{userId}/{jobId}/{start_date}-{end_date}-annotations_export-vault{vaultId}.zip",
        "method": "GET"
    }
]

Output File

The output is a ZIP archive containing a single JSON file. Both use the naming convention {start_date}-{end_date}-annotations_export-vault{vaultId}.zip. For example, 2025-01-01T00:00:00Z-2025-12-31T23:59:59Z-annotations_export-vault19523.zip.

The JSON file contains an array of annotation records. Each annotation object may include different fields depending on the annotation type. Fields that do not apply to a given record are omitted or null. For the complete, type-specific schema, including references and placemark shapes, see Read Annotations by Document Version and Type and the annotation placemark and reference type-metadata endpoints.

For example:

{
    "id__sys": "3",
    "type__sys": "note__sys",
    "document_version_id__sys": "65_0_1",
    "state__sys": "open__sys",
    "color__sys": "yellow_light__sys",
    "title__sys": "00:51",
    "comment__sys": "Shadow on cursor",
    "reply_count__sys": 1,
    "created_by_user__sys": "61579",
    "created_date_time__sys": "2018-08-20T16:50:16.000Z",
    "modified_by_user__sys": "61579",
    "modified_date_time__sys": "2018-08-20T16:50:16.000Z",
    "persistent_id__sys": "19523_3",
    "prevent_bring_forward__sys": false,
    "references": [],
    "placemark": {
        "type__sys": "video_rectangle__sys",
        "style__sys": "rectangle_solid__sys",
        "video_time_signature__sys": 51.211743,
        "video_x_coordinate__sys": 143,
        "video_y_coordinate__sys": 256,
        "video_width__sys": 27,
        "video_height__sys": 30
    }
}

Replies

Replies are included as their own records with a type__sys of reply__sys, rather than nested inside the parent annotation. A reply links to its parent through its placemark: reply_parent__sys holds the parent annotation's id__sys, and reply_position_index__sys gives its order in the thread.

Placemarks

The placemark shape varies by annotation type. Every placemark includes a type__sys, and the remaining fields depend on that type.

For example, the following snippet shows examples of different placemark types:

"placemark": {
    "type__sys": "line__sys",
    "style__sys": "line_weight_two__sys",
    "page_number__sys": 1,
    "x_coordinate__sys": 80.47,
    "y_coordinate__sys": 134.25,
    "width__sys": 7,
    "height__sys": 16.81,
    "coordinates__sys": [80.47, 134.25, 87.47, 134.25, 80.47, 117.44, 87.47, 117.44]
}

"placemark": {
    "type__sys": "page_level__sys",
    "page_number__sys": 1
}

"placemark": {
    "type__sys": "reply__sys",
    "reply_parent__sys": "3",
    "reply_position_index__sys": 1
}