Accessing Documents

The API allows you to access the documents in your vault in various ways. This article covers the basic document access use cases. If you need further help, head over to the Vault Developer Community or check out the latest API Reference.

The Documents API contains the endpoints and information needed to work with documents.

Article Contents

Getting Started
Retrieving All Documents

Getting Started

The Following Rules Govern Document Retrieval

  • Vault only returns documents to which the logged in user has been given access (even if more documents exist).
  • Unless version operators are used, Vault only returns the latest version of each document. Learn about [Searching Document Versions below]
  • Vault returns a maximum of 200 documents per page. This can be changed (lowered) using the limit operator.

Documents API vs Query API Syntax

There are a few key differences in syntax which may cause confusion for users switching between the Documents API and Query API. All syntax is defined in their corresponding API articles. Using the wrong syntax results in an error response.

  • Paginating Results uses start in the Documents API and offset in the Query API.
  • Keyword Search uses search in the Documents API and find in the Query API.
  • Searching Across All Versions uses versionscope=all in the Documents API and allversions in the Query API.

Top

Retrieving All Documents

You can retrieve a list of documents in your vault by sending a GET request to the /api/{version}/objects/documents endpoint. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents

The results list all documents, their document fields and field values. The partial (json) response below indicates a total size of 1000 documents in the vault. The start value of 0 (default) and limit of 200 (default) indicate that you're viewing the first of five pages of available results (1000/200) with each page listing 200 documents. One document is shown below (id 475) with a few of its many (40 +/-) document fields and field values.

{
    "responseStatus": "SUCCESS",
    "size": 1000,
    "start": 0,
    "limit": 200,
    "documents": [
        {
            "document": {
                "id": 475,
                "name__v": "Cholecap Information",
                "major_version_number__v": 1,
                "minor_version_number__v": 3,
                ...

Top

Sorting Results

The default sort order when using the Documents API is not based on any document field. However, you can change the sort parameters by including the sort operator and setting the "sort by" field name and "sort direction" as desc (descending) or asc (ascending). For example, you could sort all documents in descending order by their id, name__v, type__v, product__v, etc.

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents?sort=name__v desc
{
    "responseStatus": "SUCCESS",
    "size": 1000,
    "start": 0,
    "limit": 200,
    "documents": [
        {
            "document": {
                "id": 120,
                "name__v": "Zosteril Brochure",
                ...

Top

Paginating Results

The examples above list the first of five pages of results (results 1-200). To get to the next page (results 201-400), you must use the start operator set to 201. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents?sort=name__v desc&start=201
{
    "responseStatus": "SUCCESS",
    "size": 1000,
    "start": 201,
    "limit": 200,
    "documents": [
        {
            "document": {
                "id": 320,
                "name__v": "Nyaxa Ad",
                ...

To change the default of 200 results displayed per page, you can use the limit operator (with or without sort and start). The example below limits the results to 10 per page starting at result 500:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents?sort=name__v desc&start=500&limit=10
{
    "responseStatus": "SUCCESS",
    "size": 10,
    "start": 500,
    "limit": 10,
    "documents": [
        {
            "document": {
                "id": 680,
                "name__v": "Ludenerol Study Data",
                ...

Top

Using Named Filters

The API provides a set of pre-defined filters that allow you to reduce the number of documents in the result set: My Documents, Recent Documents and Favorites. These must be entered exactly as shown (initial caps).

  • My Documents - documents created by the user
  • Recent Documents - documents recently accessed by the user
  • Favorites - documents marked as favorite by the user

These filters are passed to the API endpoint in the request parameter called named_filter. Only one named filter may be used in each query. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents?named_filter=My Documents
{
    "responseStatus": "SUCCESS",
    "size": 5,
    "start": 0,
    "limit": 200,
    "documents": [
        {
            "document": {
                "id": 829,
                ...

Top

Performing Keyword Searches

You can search for documents based on keywords in searchable document fields by using the search operator. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents?search=oncology

You can search for documents based on keywords in searchable document fields and/or document content by including the scope operator.

  • When the scope operator is not included, search is performed only within searchable document fields.
  • When scope=contents is included, search is performed only within document content.
  • When scope=all is included, search is performed within both searchable document fields and document content.

Only one type of scope operator can be used in the entire expression, e.g., scope=contents or scope=all. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents?search=oncology&scope=contents
$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents?search=oncology&scope=all

Refer to the Query Syntax & Structure article for more information about keyword searches in the Query API.

Top

Searching Across All Versions

By default, all documents returned in the search are the latest versions to which the user has been given access. However, you can request that the search be performed across all versions of the documents. Version scope is passed to the API endpoint in the request parameter versionscope and is set to either latest (default) or all.

For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents?search=oncology&scope=contents&versionscope=all

When the API finds the match in multiple document versions, the version information as well as the string where the match was found is included in the term_highlights section of the result set. This section may look like the following:

            },
            "term_highlights": [
                {
                    "name": "content",
                    "highlight": [
                        " <em>The Oncology Lab found the following results in this study:</em>\n\n\n\n\n \n"
                    ],
                    "major_version_number__v": 2,
                    "minor_version_number__v": 1
                }
            ]...

Top

Best Practices

The Documents API is great for simple document retrieval use cases. For much more granular search options, consider using the Query API which allows you to execute fine-tuned queries.

Top