API Reference (v12.0)

We recommend using a newer version of the API.

For general information on Vault, refer to Vault Help.

General API Information

Vault limits the number of API calls that can be made every 5 minutes and every 24 hours. When either of these limits are reached, the API returns an API_LIMIT_EXCEEDED error message and no further calls will be processed until the next 5 minute or 24 hour period begins.

• The default limit every 5 minutes is 2,000 calls.
• The default limit every 24 hours is 100,000 calls.

The limits are configured on each individual vault in a domain.

HTTP Methods

Vault API uses the POST, GET, PUT, and DELETE HTTP methods. These correspond to Create, Retrieve (Read), Update, and Delete (or CRUD) operations, respectively.

Response Formats

• The API supports JSON and XML response formats. If no particular format is requested, the response is JSON by default.
• All responses include a responseStatus with a SUCCESS, FAILURE, or EXCEPTION value.
• For a responseStatus other than SUCCESS, an errors key/value array is returned, providing additional details for the type of error.
• If there are no errors, the errors value is empty or omitted.

To request a response in a particular format, use the Accept HTTP header with a value of application/json or application/xml. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
-H "Accept: application/xml" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents

Alternatively, you can include the format request parameter with a value of json or xml to indicate the desired format of the response. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents?format=xml

The format request parameter (if present) will overwrite the Accept HTTP Header value.

Retrieve Available API Resources

Send a GET request to the /api/{VERSION}/metadata/objects endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/metadata/objects

Example Response

{
    "responseStatus": "SUCCESS",
    "values": {
        "documents": "https://myvault.veevavault.com/api/v12.0/metadata/objects/documents/types",
        "users": "https://myvault.veevavault.com/api/v12.0/metadata/objects/users",
        "groups": "https://myvault.veevavault.com/api/v12.0/metadata/objects/groups",
        "securitypolicies": "https://myvault.veevavault.com/api/v12.0/metadata/objects/securitypolicies",
        "vobjects": "https://myvault.veevavault.com/api/v12.0/metadata/vobjects"
    }
}

Response Details

Retrieve Available API Versions

Send a GET request to the /api endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com.veevavault.com/api/

Example Response

{
    "responseStatus": "SUCCESS",
    "values": {
        "v2.0": "https://myvault.veevavault.com/api/v2.0",
        "v3.0": "https://myvault.veevavault.com/api/v3.0",
        "v4.0": "https://myvault.veevavault.com/api/v4.0",
        "v5.0": "https://myvault.veevavault.com/api/v5.0",
        "v6.0": "https://myvault.veevavault.com/api/v6.0",
        "v7.0": "https://myvault.veevavault.com/api/v7.0",
        "v8.0": "https://myvault.veevavault.com/api/v8.0",
        "v9.0": "https://myvault.veevavault.com/api/v9.0",
        "v10.0": "https://myvault.veevavault.com/api/v10.0",
        "v11.0": "https://myvault.veevavault.com/api/v11.0",
        "v12.0": "https://myvault.veevavault.com/api/v12.0"
    }
}

About Vault API Versions

You may use any API version to retrieve the same information from your vaults. However, make sure you refer to the corresponding API Reference (this document) to determine the appropriate request parameters as these vary considerably between versions.

The response above shows all versions of the API which are currently available and supported by Veeva. The last version listed is typically the Beta version. The second-to-last version listed is typically the latest GA version.

Retrieve Vaults in Your Domain

Send a GET request to the /api/{VERSION}/objects/domain endpoint.

Note: Only Domain Admins may retrieve the list of vaults in your domain.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/domain

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "domain__v": {
        "domain_name__v": "veevapharma",
        "domain_type__v": "devtestvaults",
        "vaults__v": [
            {
                "id": "3369",
                "vault_name__v": "VeevaPharma MedComms",
                "vault_status__v": "Active",
                "vault_application__v": "MedComms"
            },
            {
                "id": "7026",
                "vault_name__v": "VeevaPharma Submissions",
                "vault_status__v": "Active",
                "vault_application__v": "Submissions"
            },
            {
                "id": "3005",
                "vault_name__v": "VeevaPharma eTMF",
                "vault_status__v": "Active",
                "vault_application__v": "eTMF"
            },
            {
                "id": "5980",
                "vault_name__v": "VeevaPharma Platform",
                "vault_status__v": "Active",
                "vault_application__v": "Base"
            },
            {
                "id": "3003",
                "vault_name__v": "VeevaPharma PromoMats",
                "vault_status__v": "Active",
                "vault_application__v": "PromoMats"
            },
            {
                "id": "5547",
                "vault_name__v": "VeevaPharma QualityDocs",
                "vault_status__v": "Active",
                "vault_application__v": "QualityDocs"
            }
        ]
    }
}

The response contains a list of all vaults in the customer domain which are available to the logged-in API user.

Response Details

Authentication

Authentication calls are how you gain access to Vault through the API. Vault's authentication response contains the sessionId and a list of all vaults to which you have been given access.

Vault supports the following authentication methods:

• Username & Password Authentication
• SAML Single Sign-on (SSO) Authentication
• Salesforce Delegated Authentication

Example Request (Username & Password Authentication)

To use your Vault login credentials to authenticate with your company domain mypromomatsvault.veevavault.com, send a POST request to the /api/v12.0/auth endpoint and include your username and password as request parameters.

$ curl -X POST https://mypromomatsvault.veevavault.com/api/v12.0/auth \
-d "username=quinntaylor@mypromomatsvault.com" \
-d "password=Abcd1234" \

Example Response

{
    "responseStatus": "SUCCESS",
    "sessionId": "F722BDCECDFE1B2E82234ABB82AAF2505676FE22DC380752E1D80150D909C86D5E1BE5DFBC762A24D55A0B9AE8781FA8",
    "userId": 65432,
    "vaultIds": [
        {
            "id": 3123,
            "name": "PromoMats",
            "url": "https://mypromomatsvault.veevavault.com/api"
        },
        {
            "id": 3456,
            "name": "eTMF",
            "url": "https://myetmfvault.veevavault.com/api"
        }
    ],
    "vaultId": 3123
}

The example above shows two vaults in the company domain:

• Vault id "3123" at https://mypromomatsvault.veevavault.com is a "PromoMats" Vault.
  
• Vault id "3456" at https://myetmfvault.veevavault.com is an "eTMF" Vault.
  

The user (username) quinntaylor@mypromomatsvault.com with password Abcd1234 and Vault userId = 65432 has successfully authenticated with the PromoMats Vault as shown by the vaultId = 3123. This is the vault for which the Authorization Token sessionId has been issued. If this user wanted to access the eTMF Vault, he would have to make another authentication call to that URL and receive a new token.

Once authenticated, all subsequent API requests must include the Authorization HTTP header containing the sessionId authentication token. For example:

$ curl -X GET -H "Authorization: F722BDCECDFE1B2E82234ABB82AAF2505676FE22DC380752E1D80150D909C86D5E1BE5DFBC762A24D55A0B9AE8781FA8" 
https://myvault.veevavault.com/api/v12.0/objects/documents

Alternatively, you can include the sessionId authentication token on the URL in the auth request parameter. For example:

$ curl -X GET
https://myvault.veevavault.com/api/v12.0/objects/documents?auth=F722BDCECDFE1B2E82234ABB82AAF2505676FE22DC380752E1D80150D909C86D5E1BE5DFBC762A24D55A0B9AE8781FA8

The auth request parameter (if present) will overwrite the Authorization HTTP Header value.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Username & Password Authentication.
v5.0 - Added support for Salesforce Delegated Authentication.
v12.0 - Added support for SAML Single Sign-On (SSO) Authentication.

Documents

Retrieve Document Fields

Send a GET request to the /api/{VERSION}/metadata/objects/documents/properties endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/metadata/objects/documents/properties

Example Response (abridged)

        ...
        {
            "name": "name__v",
            "scope": "DocumentVersion",
            "type": "String",
            "required": true,
            "maxLength": 100,
            "repeating": false,
            "systemAttribute": true,
            "editable": true,
            "setOnCreateOnly": false,
            "disabled": false,
            "label": "Name",
            "section": "generalProperties",
            "sectionPosition": 0,
            "hidden": false,
            "queryable": true,
            "shared": false,
            "definedInType": "type",
            "definedIn": "base_document__v"
        },
        {
            "name": "product__v",
            "scope": "DocumentVersion",
            "type": "ObjectReference",
            "required": true,
            "repeating": true,
            "systemAttribute": true,
            "editable": true,
            "setOnCreateOnly": false,
            "disabled": false,
            "objectType": "product__v",
            "label": "Product",
            "section": "productInformation",
            "sectionPosition": 1,
            "hidden": false,
            "queryable": true,
            "shared": false,
            "definedInType": "type",
            "definedIn": "base_document__v",
            "relationshipType": "reference",
            "relationshipName": "document_product__vr"
        },
        {
            "name": "version_creation_date__v",
            "scope": "DocumentVersion",
            "type": "DateTime",
            "required": true,
            "repeating": false,
            "systemAttribute": true,
            "editable": false,
            "setOnCreateOnly": false,
            "disabled": false,
            "label": "Version Creation Date",
            "section": "generalProperties",
            "sectionPosition": 17,
            "hidden": false,
            "queryable": true,
            "shared": false,
            "definedInType": "type",
            "definedIn": "base_document__v"
        },
        ...

Retrieve Shared Document Fields

Vault allows you to reuse fields across multiple document types by creating shared fields, which exist outside the context of a document type. You can create shared fields or convert existing fields into shared fields in the Vault Admin application. If a shared field is only used in one document type, you can also convert it to a non-shared field. All document fields include the Boolean shared document field. A value of true indicates which the field is shared and the following additional fields are included:

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v4.0 - Retrieve document metadata.
Since: v9.0 - Find common document fields.

Find Common Document Fields

Send a POST request to the /metadata/objects/documents/properties/find_common endpoint.

Request Parameters

• Set the HTTP Request Header Content-Type to application/x-www-form-urlencoded (name-value pair input).
• To find fields common to a set of documents, include the docIds parameter with a list of document IDs as shown below.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-d "docIds=34,52" \
https://myvault.veevavault.com/api/v12.0/metadata/objects/documents/properties/find_common

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "properties": [
        {
            "name": "product__v",
            "scope": "DocumentVersion",
            "type": "ObjectReference",
            "required": true,
            "repeating": true,
            "systemAttribute": true,
            "editable": true,
            "setOnCreateOnly": false,
            "disabled": false,
            "objectType": "product__v",
            "label": "Product",
            "section": "productInformation",
            "sectionPosition": 1,
            "hidden": false,
            "queryable": true,
            "shared": false,
            "definedInType": "type",
            "definedIn": "base_document__v",
            "relationshipType": "reference",
            "relationshipName": "document_product__vr"
        },
        {
            "name": "country__v",
            "scope": "DocumentVersion",
            "type": "ObjectReference",
            "required": false,
            "repeating": true,
            "systemAttribute": true,
            "editable": true,
            "setOnCreateOnly": false,
            "disabled": false,
            "objectType": "country__v",
            "label": "Country",
            "section": "generalProperties",
            "sectionPosition": 20,
            "hidden": false,
            "queryable": true,
            "shared": false,
            "definedInType": "type",
            "definedIn": "base_document__v",
            "relationshipType": "reference",
            "relationshipName": "document_country__vr"
        },
        ...

The response contains the list of document fields common across the documents indicated in the request.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v4.0 - Retrieve document metadata.
Since: v9.0 - Find common document fields.

Retrieve All Document Types

Send a GET request to the /api/{VERSION}/metadata/objects/documents/types endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/metadata/objects/documents

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "types": [
        {
            "label": "Base Document",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/base_document__v"
        },
        {
            "label": "Claim",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/claim__vs"
        },
        {
            "label": "Compliance Package",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/compliance_package__v"
        },
        {
            "label": "Promotional Piece",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs"
        },
        ...
    ],
    "lock": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/lock"
}

The example response shows a few of the many standard and custom document types configured in this vault. Some of these document types also have subtypes and classifications. Use the URL in the value field to retrieve information about a specific document type.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve all document types.

Retrieve Document Type

Send a GET request to the /api/{VERSION}/metadata/objects/documents/types/{TYPE} endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "name": "promotional_piece__vs",
    "label": "Promotional Piece",
    "renditions": [
        "distribution_package__vs",
        "production_proof__vs",
        "viewable_rendition__v",
        "imported_rendition__vs"
    ],
    "relationshipTypes": [
        {
            "label": "Supporting Documents",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
        },
        {
            "label": "Linked Documents",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
        },
        {
            "label": "CrossLink Static Bindings",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
        },
        ...
    ],
    "availableLifecycles": [
        {
            "name": "promotional_piece__vs",
            "label": "Promotional Piece"
        },
        ...
    ],
    "subtypes": [
        {
            "label": "Convention Item",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/convention_item__vs"
        },
        {
            "label": "Direct Mail",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/direct_mail__vs"
        },
        {
            "label": "Advertisement",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs"
        },
        ...
    ]
}

The example response shows metadata for the promotional_piece__vs document type. If the document type includes subtypes (as in the example above), the URLs in the subtype value fields provide a link to each subtype.

Note: If the document type did not have any subtypes, the response would include the list of all document fields configured for the document type.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve document type.

Retrieve Document Subtype

Send a GET request to the /api/{VERSION}/metadata/objects/documents/types/{TYPE}/subtypes/{SUBTYPE} endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "name": "advertisement__vs",
    "label": "Advertisement",
    "properties": [
        {
            "name": "id",
            "type": "id",
            "required": true,
            "maxLength": 20,
            "minValue": 0,
            "maxValue": 9223372036854776000,
            "repeating": false,
            "systemAttribute": true,
            "editable": false,
            "setOnCreateOnly": true,
            "disabled": false,
            "hidden": true,
            "queryable": true
        },
        ...
    ],
    "classifications": [
        {
            "label": "Print",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs/classifications/print__vs"
        },
        {
            "label": "Web",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs/classifications/web__vs"
        },
        ...
    ],
    "relationshipTypes": [
        {
            "label": "Linked Documents",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
        },
        {
            "label": "Supporting Documents",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
        },
        {
            "label": "CrossLink Static Bindings",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
        },

    ],
    "availableLifecycles": [
        {
            "name": "promotional_piece__vs",
            "label": "Promotional Piece"
        },
        ...
    ]
}

The example response shows metadata for the advertisement__vs document subtype of the promotional_piece__vs document type. The response includes a list of all document fields configured for the document subtype. If the document subtype includes classifications (as in the example above), the URLs in the classification value fields provide a link to each classification.

Note: If the document subtype did not have any classifications, the response would include the list of all document fields configured for the document subtype.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve document subtype.

Retrieve Document Classification

Send a GET request to the /api/{VERSION}/metadata/objects/documents/types/{TYPE}/subtypes/{SUBTYPE}/classifications/{CLASSIFICATION} endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs/classifications/web__vs

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "name": "web__vs",
    "label": "Web",
    "properties": [
        {
            "name": "id",
            "type": "id",
            "required": true,
            "maxLength": 20,
            "minValue": 0,
            "maxValue": 9223372036854776000,
            "repeating": false,
            "systemAttribute": true,
            "editable": false,
            "setOnCreateOnly": true,
            "disabled": false,
            "hidden": true,
            "queryable": true
        },
        ...
    ],
    "relationshipTypes": [
        {
            "label": "Linked Documents",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
        },
        {
            "label": "Supporting Documents",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
        },
        {
            "label": "CrossLink Static Bindings",
            "value": "https://myvault.vaultdev.com/api/v12.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
        },
        ...
    ],
    "templates": [
        {
            "label": "Web Advertisement Template",
            "name": "web_advertisement_template__c",
            "kind": "document",
            "definedIn": "web__vs",
            "definedInType": "classification"
        }
    ],
    "availableLifecycles": [
        {
            "name": "promotional_piece__vs",
            "label": "Promotional Piece"
        }
    ]
}

The example response shows metadata for the web__vs document classification of the advertisement__vs document subtype. The response includes a list of all document fields configured for the document classification.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve document classification.

Create Document

The API supports the following create document actions:

• Create Document from Uploaded File - See below.
• Create Document from Template - See below.
• Create Content Placeholder Document - See below.
• Create Unclassified Document - See below.
• Create CrossLink Document - See below.

These all involve creating one document at a time. Many of these actions are also available in the Bulk Documents API.

About Required & Editable Fields

• When creating a new document, certain standard document fields are required in all vaults. These are listed below with each request.
• Your Vault Admin may set additional standard or custom document fields to required in your vault.
• If a required field is not included in the request, Vault returns a PARAMETER_REQUIRED error with the name of the missing field.

To retrieve document fields in your vault:

• Use the Document Metadata API to retrieve all fields configured on documents. In the field specifications: Required fields: required:true / Editable fields: editable:true.
• Use the Vault Loader Document Extract to retrieve fields and values configured on specific documents.
• Go to Admin > Configuration > Document Fields and find all fields marked "Required" and those which are editable. Learn more.

About Default Field Values

• Some document fields allow default values to be specified by Admin.
• When a field includes default values and the field is omitted from the request, the field is automatically populated with the value during document creation.
• When the field is included in the request, the field values specified in the input override the default values.

You can find out which field has a default by analyzing the defaultValue metadata field on the document field.

For example:

{
    "name": "region__c",
    "type": "Picklist",
    "required": false,
    "editable": true,
    "defaultValue": [
        "North America"
    ],
    "label": "Region",
    "entryLabels": [
        "North America",
        "South America"
    ],...
}

Shown above are select portions of the region__c document field metadata.

• The field is not required when creating a new document.
• The field is editable, meaning you can add or remove its values.
• The field has a default value. When a document is created, this field is automatically assigned the value "North America".
• The field can be assigned the alternate value "South America" by including it in the input when creating the document.

About Document Templates

• Retrieve the name of the document template that will be used to create the new document. Document templates are shown in Admin > Business Admin > Documents & Binders. Since document templates are associated with a specific document type, you can retrieve them via the API through the retrieve document type, subtype, and classification endpoints described above.
• To specify the template in the request, include the fromTemplate parameter with a valid Vault document template name.

Create Document from Uploaded File

• Most documents in your vault are created from uploaded source files, e.g., "mydocument.docx". Learn about supported file formats.
• Once uploaded with values assigned to document fields, Vault gererates the viewable rendition, e.g., "mydocument.docx.pdf". Learn about viewable renditions.

Method & Endpoint

Send a POST request to the /api/{VERSION}/objects/documents endpoint.

Request Headers

• Set the HTTP Request Header Content-Type to multipart/form-data (name-value pair input).
• JSON is the default response format. To request an XML response, set the HTTP Request Header Accept to application/xml.

Upload the Source File

• To upload the source file, use multi-part attachment with the file component named file. The maximum allowed file size is 4GB.

Required Standard Fields

When creating a new document, the following standard fields are required in all vaults:

• name__v - Name of the new document.
• type__v - Name of the document type to assign to the new document.
• subtype__v - Name of the document subtype (if one exists on the document type).
• classification__v - Name of the document classification (if one exists on the document subtype).
• lifecycle__v - Name of the document lifecycle to assign to the new document.
• major_version_number__v - Major version number to assign to the new document.
• minor_version_number__v - Minor version number to assign to the new document.

Additional Required & Editable Fields

• Admin may set other standard or custom document fields to required in your vault. Learn about required document fields above.
• If a required field is not included, Vault returns a PARAMETER_REQUIRED error with the name of the missing field.
• You may include name-value pairs for other optional, editable document fields and values. Learn about editable document fields above.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "file=gludacta-document-01.docx" \
-F "name__v=Gludacta Document" \
-F "type__v=Promotional Piece" \
-F "subtype__v=Advertisement" \
-F "classification__v=Web" \
-F "lifecycle__v=Promotional Piece" \
-F "major_version_number__v=0" \
-F "minor_version_number__v=1" \
-F "product__v=0PR0303" \
-F "external_id__v=GLU-DOC-0773" \
https://myvault.veevavault.com/api/v12.0/objects/documents

This example includes:

• The file parameter with the name of the source file being used to create the new document.
• All required fields (in our vault) to create a new document of the specified document type.
• The specified major and minor document version numbers will create this document as version 0.1.
• The optional (in our vault) product__v document field name with the product object record ID to assign to the new document.
• The optional (in our vault) external_id__v document field with a document external ID to assign to the new document.

Example JSON Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 773
}

On success, the document is created and assigned a system-managed document id field value.

Possible Errors

On failure, the response displays an error type and message describing the error.

Version History

• Create document from uploaded file is available in API v2.0 or later.

Create Document from Template

• Vault document templates allow quick creation of new documents from preconfigured templates in your vault.
• When you create the new document, Vault copies the template file and uses that copy as the source file for the new document.
• This process bypasses the content upload process and allows for more consistent document creation.
• Document templates are associated with a specific document type, like documents themselves. Learn about document templates.

Method & Endpoint

Send a POST request to the /api/{VERSION}/objects/documents endpoint.

Request Headers

• Set the HTTP Request Header Content-Type to multipart/form-data (name-value pair input).
• JSON is the default response format. To request an XML response, set the HTTP Request Header Accept to application/xml.

Select the Document Template

• To specify the template, use multi-part attachment with the parameter fromTemplate.

Required Standard Fields

When creating a new document, the following standard fields are required in all vaults:

• name__v - Name of the new document.
• type__v - Name of the document type to assign to the new document.
• subtype__v - Name of the document subtype (if one exists on the document type).
• classification__v - Name of the document classification (if one exists on the document subtype).
• lifecycle__v - Name of the document lifecycle to assign to the new document.
• major_version_number__v - Major version number to assign to the new document.
• minor_version_number__v - Minor version number to assign to the new document.

Additional Required & Editable Fields

• Admin may set other standard or custom document fields to required in your vault. Learn about required document fields above.
• If a required field is not included, Vault returns a PARAMETER_REQUIRED error with the name of the missing field.
• You may include name-value pairs for other optional, editable document fields and values. Learn about editable document fields above.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "fromTemplate=promo_doc_template__c" \
-F "name__v=Gludacta Document" \
-F "type__v=Promotional Piece" \
-F "subtype__v=Advertisement" \
-F "classification__v=Web" \
-F "lifecycle__v=Promotional Piece" \
-F "major_version_number__v=0" \
-F "minor_version_number__v=2" \
-F "product__v=0PR0303" \
-F "external_id__v=GLU-DOC-0774" \
https://myvault.veevavault.com/api/v12.0/objects/documents

This example includes:

• The fromTemplate parameter with the name of the template being used to create the new document.
• All required fields (in our vault) to create a new document of the specified document type.
• The specified major and minor document version numbers will create this document as version 0.2.
• The optional (in our vault) product__v document field name with the product object record ID to assign to the new document.
• The optional (in our vault) external_id__v document field with a document external ID to assign to the new document.

Example JSON Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 774
}

On success, the document is created and assigned a system-managed document id field value.

Possible Errors

On failure, the response displays an error type and message describing the error.

Version History

• Create document from template is available in API v5.0 or later.

Create Content Placeholder Document

• You can create a content placeholder document when the associated source file is not yet available and then, add the source file at a later date.
• Creating a content placeholder document is just like creating a document from an uploaded file, but the file parameter is not included in the request.
• Learn about content placeholders.

Method & Endpoint

Send a POST request to the /api/{VERSION}/objects/documents endpoint.

Request Headers

• Set the HTTP Request Header Content-Type to multipart/form-data (name-value pair input).
• JSON is the default response format. To request an XML response, set the HTTP Request Header Accept to application/xml.

Required Standard Fields

When creating a new document, the following standard fields are required in all vaults:

• name__v - Name of the new document.
• type__v - Name of the document type to assign to the new document.
• subtype__v - Name of the document subtype (if one exists on the document type).
• classification__v - Name of the document classification (if one exists on the document subtype).
• lifecycle__v - Name of the document lifecycle to assign to the new document.
• major_version_number__v - Major version number to assign to the new document.
• minor_version_number__v - Minor version number to assign to the new document.

Additional Required & Editable Fields

• Admin may set other standard or custom document fields to required in your vault. Learn about required document fields above.
• If a required field is not included, Vault returns a PARAMETER_REQUIRED error with the name of the missing field.
• You may include name-value pairs for other optional, editable document fields and values. Learn about editable document fields above.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "name__v=Gludacta Document" \
-F "type__v=Promotional Piece" \
-F "subtype__v=Advertisement" \
-F "classification__v=Web" \
-F "lifecycle__v=Promotional Piece" \
-F "major_version_number__v=0" \
-F "minor_version_number__v=2" \
-F "product__v=0PR0303" \
-F "external_id__v=GLU-DOC-0775" \
https://myvault.veevavault.com/api/v12.0/objects/documents

This example includes:

• All required fields (in our vault) to create a new document of the specified document type.
• The specified major and minor document version numbers will create this document as version 0.2.
• The optional (in our vault) product__v document field name with the product object record ID to assign to the new document.
• The optional (in our vault) external_id__v document field with a document external ID to assign to the new document.

Example JSON Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 775
}

On success, the document is created and assigned a system-managed document id field value.

Possible Errors

On failure, the response displays an error type and message describing the error.

Version History

• Create content placeholder document is available in API v2.0 or later.

Create Unclassified Document

• Unclassified documents are documents which have a source file, but no document type.
• Bypassing the steps to classify the document and populate document properties allows you to upload source files and create documents more quickly.
• Learn about unclassified documents.

Method & Endpoint

Send a POST request to the /api/{VERSION}/objects/documents endpoint.

Request Headers

• Set the HTTP Request Header Content-Type to multipart/form-data (name-value pair input).
• JSON is the default response format. To request an XML response, set the HTTP Request Header Accept to application/xml.

Upload the Source File

• To upload the source file, use multi-part attachment with the file component named file. The maximum allowed file size is 4GB.

Required Standard Fields

When creating an unclassified document, the following standard fields are required in all vaults:

In eTMF vaults, you can also (optionally) set the following fields:

• product__v
• study__v
• study_country__v
• site__v

Any other fields included in the input will be ignored. The document name (name__v) will default to the name of the uploaded file.

Example (All vaults)

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "file=CholeCap Information.docx" \
-F "type__v=Undefined" \
-F "lifecycle__v=Unclassified" \
https://myvault.veevavault.com/api/v15.0/objects/documents

Example (eTMF vaults)

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "file=CholeCap Information.docx" \
-F "type__v=Undefined" \
-F "lifecycle__v=Unclassified" \
-F "product__v=00P000000000101" \
-F "study__v=0ST000000000501" \
-F "study_country__v=0SC000000000401" \
-F "site__v=0SI000000000301" \
https://myvault.veevavault.com/api/v15.0/objects/documents

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 776
}

On SUCCESS, the new unclassified document is created and assigned a document id.

Possible Errors

On failure, the response displays an error type and message describing the error.

Version History

• Create unclassified document is available in API v2.0 or later.

Create CrossLink Document

• CrossLink documents enable content from one vault to be used in another vault within the same domain.
• A CrossLink document in your vault uses the viewable rendition from a source document in another [source] vault, with different fields, lifecycle, and workflows.
• When creating a CrossLink document, you must include all document fields that are required for the specified document type/subtype/classification and no file is uploaded.
• You must also specify the vault ID and document ID for the source document which will be bound to the new CrossLink document.
• Learn about CrossLink documents.

Method & Endpoint

Send a POST request to the /api/{VERSION}/objects/documents endpoint.

Request Headers

• Set the HTTP Request Header Content-Type to multipart/form-data (name-value pair input).
• JSON is the default response format. To request an XML response, set the HTTP Request Header Accept to application/xml.

Required Standard Fields

When creating a new CrossLink document, the following standard fields are required in all vaults:

• name__v - Name of the new CrossLink document.
• type__v - Name of the document type to assign to the new CrossLink document.
• subtype__v - Name of the document subtype (if one exists on the document type).
• classification__v - Name of the document classification (if one exists on the document subtype).
• lifecycle__v - Name of the document lifecycle to assign to the new CrossLink document.
• major_version_number__v - Major version number to assign to the new CrossLink document.
• minor_version_number__v - Minor version number to assign to the new CrossLink document.
• source_vault_id__v - ID of the source vault containing the source document that will be bound to the new CrossLink document.
• source_document_id__v - ID of the source document that will be bound to the new CrossLink document.

Optional Standard Fields

When creating a new CrossLink document, the following standard fields referencing the source document are optional:

• source_binding_rule__v - Possible values: Latest version, Latest Steady State version, or Specific Document version. These define which version of the source document will be bound to the CrossLink document. If not specified, this defaults to the Latest Steady State version.
• bound_source_major_version__v - When the source_binding_rule__v is set to Specific Document version, you must specify the major version number of the source document to bind to the CrossLink document.
• bound_source_minor_version__v - When the source_binding_rule__v is set to Specific Document version, you must specify the minor version number of the source document to bind to the CrossLink document.

Additional Required & Editable Fields

• Admin may set other standard or custom document fields to required in your vault. Learn about required document fields above.
• If a required field is not included, Vault returns a PARAMETER_REQUIRED error with the name of the missing field.
• You may include name-value pairs for other optional, editable document fields and values. Learn about editable document fields above.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "name__v=Gludacta Document" \
-F "type__v=Promotional Piece" \
-F "subtype__v=Advertisement" \
-F "classification__v=Web" \
-F "lifecycle__v=Promotional Piece" \
-F "major_version_number__v=0" \
-F "minor_version_number__v=`" \
-F "source_vault_id__v=2112" \
-F "source_document_id__v=101" \
-F "source_binding_rule__v=Specific Document version" \
-F "bound_source_major_version__v=1" \
-F "bound_source_major_version__v=3" \
-F "product__v=0PR0303" \
-F "external_id__v=GLU-DOC-0777" \
https://myvault.veevavault.com/api/v12.0/objects/documents

This example includes:

• All required fields (in our vault) to create a new document of the specified document type.
• The specified major and minor document version numbers will create this CrossLink document as version 0.1.
• The ID of the source vault and source document which will be bound to the CrossLink document in our vault.
• The binding rule specifying that the new CrossLink document will be statically bound to version 1.3 of the source document.
• The optional (in our vault) product__v document field name with the product object record ID to assign to the new CrossLink document.
• The optional (in our vault) external_id__v document field with a document external ID to assign to the new CrossLink document.

Example JSON Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 775
}

On success, the document is created and assigned a system-managed document id field value.

Possible Errors

On failure, the response displays an error type and message describing the error.

Version History

• Create CrossLink document is available in API v10.0 or later.

Create Multiple Documents

This endpoint allows you to create multiple documents at once with a CSV input file.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard format.
• The maximum batch size is 500.

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

Headers

Body Parameters

Prepare a CSV input file. There are multiple ways to create documents in bulk. The following shows the required standard fields needed to create documents, but an Admin may set other standard or custom document fields as required in your vault. To find which fields are required, Retrieve Document Fields. You can also optionally include any editable document field.

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\create_documents.csv" \
https://myvault.veevavault.com/api/v9.0/objects/documents/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773"
        },        
        {
            "responseStatus": "FAILURE"
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this document was not created."
                }
            ]
        }
    ]
}

Retrieve Documents

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. See Limit, Sort, Paginate, and Search Results below.

Retrieve All Documents

Send a GET request to the /api/{VERSION}/objects/documents endpoint.

Example Request

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "size": 1000,
    "start": 0,
    "limit": 200,
    "documents": [
        {
            "document": {
                "id": 267,
                "binder__v": false,
                "allow_download_embedded_viewer__v": true,
                "reviewer__v": {
                    "users": [
                        25529,
                        25516
                    ],
                    "groups": [
                        1358979070034
                    ]
                },
                "viewer__v": {
                    "users": [
                        25496,
                        25529,
                        ...

On success, Vault retrieves the list of all documents and binders along with their fields and field values. The document metadata returned will vary based on your vault configuration.

A document pseudo-field binder__v indicates whether the returned document is a regular document or a binder. The value of true means it is a binder, false or absense of this field means it is a document. If it is a binder, the binder node structure is not listed as part of the response and must be determined through the appropriate Binder API call. A document pseudo-field crosslink__v indicates whether the returned document is a regular document or a CrossLink document. The value of true means it is a CrossLink.

Limit, Sort, Paginate, and Search Results

By default, Vault returns a maximum of 200 documents per page. You can change (lower) this using the limit operator. For example, to limit the number of documents to 20 per page:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents?limit=20

The limit operator must be a positive integer. Values over 200 are ignored.

The default sort order is not based on any document field. You can change the sort parameters by including the sort operator with a field and indicating descending desc or ascending asc. For example, to sort by the name of each document in descending order:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents?sort=name__v desc

With a maximum of 200 records returned per page, you must submit a new request to see the "next page" of results (when more than 200 documents exist). Use the start operator in the same way as the limit operator above. For example, if you're viewing the first page of 200 results out of 1000 total results found and want to see the next 200 results, enter start=201.

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents?start=201

The start operator must be a positive integer. Values equaling to a number larger than the total number of documents will not return any results.

To use limit, start, and sort together, structure the string in the following manner:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents?limit=10&start=51&sort=name__v desc

The request shown above will return 10 results per page, staring with page 5 (results 51-60), and sort the results by the document name in descending order.

The logged-in API user can pass a named_filter operator to limit the documents returned to My Documents (documents created by the user), Recent Documents (documents recently accessed by the user), or Favorites (documents marked as favorites by the user). For example:

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

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

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
        }
    },
    ...

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve all documents.
v4.0 - Scope parameter supported in search.
v4.0 - Response includes term highlight hints.
v5.0 - Response distinguishes between documents and binders.
v10.0 - CrossLink documents supported.

Retrieve Document

Send a GET request to the /api/{VERSION}/objects/documents/{ID} endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/450

Example Response

{
    "responseStatus": "SUCCESS",
    "document": {
        "id": 450,
        "binder__v": false,
        "allow_download_embedded_viewer__v": true,
        "reviewer__v": {
            "users": [
                25519,
                25516
            ],
            "groups": [
                1358979070034                    
            ]
        },
        "viewer__v": {
            "users": [
                25519,
                25516,
                25597
            ],
            "groups": [
                1358979070034                    
            ]
        },
        "distribution_contacts__v": {
            "users": [],
            "groups": []
        },
        "consumer__v": {
            "users": [],
            "groups": []
        },
        "approver__v": {
            "users": [
                25516
            ],
            "groups": []
        },
        "editor__v": {
            "users": [
                25519,
                25516
            ],
            "groups": []
        },
        "owner__v": {
            "users": [
                46916
            ],
            "groups": []
        },
        "coordinator__v": {
            "users": [],
            "groups": []
        },
        "crosslink__v": false,
        "lifecycle__v": "General Lifecycle",
        "version_created_by__v": 46916,
        "language__v": [
            "English"
        ],
        "minor_version_number__v": 1,
        "created_by__v": 46916,
        "annotations_lines__v": 0,
        "version_creation_date__v": "2015-03-12T16:24:33.539Z",
        "country__v": [],
        "md5checksum__v": "94e18bdbcf695c905a5968429e0c5204",
        "restrict_fragments_by_product__v": true,
        "annotations_notes__v": 0,
        "version_modified_date__v": "2015-03-12T16:24:54.000Z",
        "pages__v": 1,
        "major_version_number__v": 1,
        "annotations_anchors__v": 0,
        "product__v": [
            "1357662840293"
        ],
        "export_filename__v": "451Chole",
        "annotations_resolved__v": 0,
        "type__v": "Reference Document",
        "size__v": 11599,
        "description__v": "This is my document.",
        "status__v": "Draft",
        "annotations_unresolved__v": 0,
        "document_creation_date__v": "2015-02-25T01:26:55.845Z",
        "locked__v": false,
        "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "annotations_links__v": 0,
        "document_number__v": "REF-0201",
        "annotations_all__v": 0,
        "last_modified_by__v": 46916,
        "name__v": "Cholecap Information",
        "subtype__v": "Prescribing Information",
    },
    "renditions": 
        {
        "viewable_rendition__v": "https://myvault.vaultdev.com/api/v12.0/objects/documents/450/renditions/viewable_rendition__v"
        "veeva_distribution_package__vs": "https://myvault.vaultdev.com/api/v12.0/objects/documents/450/renditions/veeva_distribution_package__vs",
    },
    "versions": [
        {
            "number": "0.1",
            "value": "https://myvault.vaultdev.com/api/v12.0/objects/documents/450/versions/0/1"
        },
        {
            "number": "1.0",
            "value": "https://myvault.vaultdev.com/api/v12.0/objects/documents/450/versions/1/0"
        },
        {
            "number": "1.1",
            "value": "https://myvault.vaultdev.com/api/v12.0/objects/documents/450/versions/1/1"
        }
    ],
    "attachments": [
        {
            "id": 547,
            "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/450/attachments/547"
        }
    ]
}

On success, Vault returns the fields and values for the document.

The fields present in the response will vary based on the definition of the document type of the returned document.

A document pseudo-field binder__v indicates whether the returned document is a regular document or a binder. The value of true means it is a binder, false or absense of this field means it is a document. If binder, the binder node structure is not listed as part of the response and must be determined through the appropriate Binder API call.

A document pseudo-field crosslink__v indicates whether the returned document is a regular document or a CrossLink document. The value of true means it is a CrossLink.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve a document.
v10.0 - CrossLink documents supported.

Retrieve All Document Versions

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/versions endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions

Example Response

{
    "responseStatus": "SUCCESS",
    "versions": [
        {
            "number": "0.1",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/0/1"
        },
        {
            "number": "0.2",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/0/2"
        },        
        {
            "number": "1.0",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/1/0"
        },        
        {
            "number": "1.1",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/1/1"
        },
        {
            "number": "2.0",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/0"
        },
        {
            "number": "2.1",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/1"
        },
        {
            "number": "2.2",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/2"
        },
        {
            "number": "2.3",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/3"
        }
    ],
    "renditions":
        {
        "viewable_rendition__v": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions/viewable_rendition__v",   
        "veeva_distribution_package__vs": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions/veeva_distribution_package__vs"
    }
}

On success, Vault returns a list of all available versions of the specified document. In the response above, document id "534" has 8 different versions. Version 2.3 is the latest version. There are also two different renditions available for this document: the "standard" viewable_rendition__v and a veeva_distribution_package__vs rendition used for integrations with a separate (optional) application.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve all document versions.

Retrieve Document Version

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR}/{MINOR} endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/3

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "document": {
        "id": 534,
        "allow_download_embedded_viewer__v": true,
        "reviewer__v": {
            "users": [
                46916,
                45589
            ],
            "groups": [
                1359484520721
            ]
            ...
        },    
        "crosslink__v": false,
        "lifecycle__v": "General Lifecycle",
        "version_created_by__v": 46916,
        "language__v": [
            "English"
        ],
        "minor_version_number__v": 3,
        "created_by__v": 46916,
        "annotations_lines__v": 0,
        "version_creation_date__v": "2015-03-13T16:24:33.539Z",
        "country__v": [],
        "md5checksum__v": "94e18bdbcf695c905a5989629e0c5204",
        "restrict_fragments_by_product__v": true,
        "annotations_notes__v": 0,
        "version_modified_date__v": "2015-03-13T16:24:54.000Z",
        "pages__v": 1,
        "major_version_number__v": 2,
        "annotations_anchors__v": 0,
        "product__v": [
            "1357662840293"
        ],
        "export_filename__v": "WD",
        "annotations_resolved__v": 0,
        "type__v": "Reference Document",
        "size__v": 11518,
        "description__v": "",
        "status__v": "Draft",
        "annotations_unresolved__v": 0,
        "document_creation_date__v": "2015-02-25T01:26:55.845Z",
        "locked__v": false,
        "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "annotations_links__v": 0,
        "document_number__v": "REF-0059",
        "annotations_all__v": 0,
        "last_modified_by__v": 46916,
        "name__v": "Wonderdrug Information",
        "binder__v": false,
        "subtype__v": "Prescribing Information"
    },
    "renditions": [
        {
        "viewable_rendition__v": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions/viewable_rendition__v",   
        "veeva_distribution_package__vs": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions/veeva_distribution_package__vs"
        }
    ],
    "versions": [
        {
            "number": "2.3",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/3"
        }
    ],
    "attachments": [
        {
            "id": 547,
            "url": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/attachments/547"
        },
        {
            "id": 561,
            "url": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/attachments/561"
        }
    ]
}

On success, Vault returns the fields and field values for the specified version of the document. Note that the document fields retrieved vary significantly by document types and Vault configuration.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve document version.

Retrieve Document File

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/file endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/file > file

You can also "check out" the document before the retrieval by setting lockDocument request parameter to true (this is set to false by default).

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/file?lockDocument=true > file

Example Response

On success, Vault retrieves the latest version of the source file from the document. The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file.

Example Response Header

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="VaultFile.pptx"

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve document file.
v6.0 - Added support for document lock (check-out) prior to retrieval of a document file.

Retrieve Document Version File

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR}/{MINOR}/file endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/file > file

You can also "check out" the document version before the retrieval by setting lockDocument request parameter to true (this is set to false by default).

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/file?lockDocument=true > file

Example Response

On success, Vault retrieves the specified version of the source file from the document. The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file.

Example Response Header

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="VaultFile.pptx"

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve document version file.

Retrieve Document Version Thumbnail File

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR}/{MINOR}/thumbnail endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/3/thumbnail > thumbnail.png

Example Response

On success, Vault returns the thumbnail image for the specified version of the document. The HTTP Response Header Content-Type is set to image/png.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v6.0 - Retrieve document version thumbnail file.

Update Documents

Update Document

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/documents/{ID} endpoint.

Request Headers

• To specify the input format, set the HTTP Request Header Content-Type to application/x-www-form-urlencoded (name-value pair input).
• JSON is the default response format (application/json).
• To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

• {ID} - The document id field value.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "language__v=English" \
-d "product__v=1357662840171" \
-d "audience__vs=consumer__vs" \
https://myvault.veevavault.com/api/v14.0/objects/documents/534

Example Response

{
    "responseStatus": "SUCCESS",
    "id": 534
}

Version History

Available in API v2.0 or later.

Update Multiple Documents

Bulk update editable field values on multiple documents. You can only update the latest version of each document. To update past document versions, see Update Document Version.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard format.
• The maximum batch size is 1,000.

PUT /api/{version}/objects/documents/batch

Headers

Body Parameters

You can use Name-Value pairs in the body of your request or you can upload a CSV. id is the only required field, and you can update values of any editable document field. To find these fields, retrieve fields configured on documents. Editable fields will have editable:true. To remove existing field values, include the field name and set its value to null.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\update_documents.csv" \
https://myvault.veevavault.com/api/v9.0/objects/documents/batch

Example Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773"
        }
    ]
}

Reclassify Document

Reclassify allows you to change the document type of an existing document or assign a document type to an existing unclassified document. A document "type" is the combination of the type__v, subtype__v, and classification__v fields on a document. When you reclassify, Vault may add or remove certain fields on the document.

Learn more about:

• Vault Help: Reclassifying Documents.
• API: Retrieve Documents
• API: Retrieve Document Fields
• API: Retrieve Document Types, Subtypes, and Classifications
• API: Create Unclassified Documents

About this Request

• You can only reclassify the latest version of a specified document.
• You can only reclassify one document at a time. Bulk reclassify is not currently supported.

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/documents/{ID} endpoint.

Request Headers

• To specify the input format, set the HTTP Request Header Content-Type to application/x-www-form-urlencoded (name-value pair input).
• JSON is the default response format (application/json).
• To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

• {ID} - The document id field value.

Input Requirements

• reclassify : To reclassify the document, set the reclassify parameter value to true. Without this, a standard document update action is performed.
• type__v : Name of the Vault document type.
• subtype__v : Name of the Vault document subtype (if one exists on the type).
• classification__v : Name of the Vault document classification (if one exists on the subtype).
• lifecycle__v : Name of the Vault document lifecycle.

You can also add or remove values for any other editable document field.

Note that additional fields may be required depending on the document type, subtype, and classification being assigned to the document.

Use the Document Metadata API to retrieve required and editable fields in your vault.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "reclassify=true" \
-d "type__v=Promotional Piece" \
-d "subtype=Advertisement" \
-d "classification__v=Web" \
-d "lifecycle__v=Promotional Piece" \
https://myvault.veevavault.com/api/v14.0/objects/documents/775

Example Response

{
    "responseStatus": "SUCCESS",
    "id": 775
}

Version History

Available in API v8.0 or later.

Update Document Version

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR_VERSION}/{MINOR_VERSION} endpoint.

Request Headers

• To specify the input format, set the HTTP Request Header Content-Type to application/x-www-form-urlencoded (name-value pair input).
• JSON is the default response format (application/json).
• To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

• {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.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "language__v=English" \
-d "product__v=1357662840171" \
-d "audience__vs=consumer__vs" \
https://myvault.veevavault.com/api/v14.0/objects/documents/534/versions/2/0

Example Response

{
    "responseStatus": "SUCCESS",
    "id": 534
}

On success, Vault updates field values for the specified version of the document and returns the ID of the updated document.

Version History

Available in API v2.0 or later.

Create New Document Draft Version

You can replace the document file or create a draft document version by sending a a POST request to the /api/{VERSION}/objects/documents/{ID} endpoint.

• Updating the document file is the act of replacing the existing file. This will increase the document by a minor version. A document lock may be required before a file can be updated.
  
• Creating a new document draft is the action of creating a new document version in Draft state from either the existing document content or by uploading a new document file.

Request Parameters

• Set the HTTP Request Header Content-Type to multipart/form-data.
• To upload the file, use the multi-part attachment with the file component named file.
  
• description__v - To set the description for the minor version update, include this parameter in the requested set to the description string.
  
• createDraft - optional [latestContent|uploadedContent]
  
  • if not set or not included in the request, the functionality of this API call is to Upload New Document.
    
  • if set to latestContent, the functionality of this API is to create a new draft version from the latest content.
    
  • if set to uploadedContent, the functionality of this API is to create a new draft version from the content uploaded in file parameter.
    
• file - contains the binary file attachment
  
  • optional when a new draft needed to be created from existing content.
    
  • required when a new draft needed to be created for new content.
    
  • required when the existing document file needs to be updated.
    
• suppressRendition - optional - boolean.
  
  • if set to true suppresseses generation of viewable rendition when the document file is updated

Example Response

On success, Vault updates the document source file or creates a new document draft.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Update document.
v7.0 - Create new document draft version supported.

v8.0 - Suppress generation of the viewable rendition supported.

Create Multiple Document Versions

Create or add document versions in bulk.

• Your vault must be in Migration Mode.
• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard format.
• The maximum batch size is 500.

POST /api/{version}/objects/documents/versions/batch

Headers

Body Parameters

Query String Parameters

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\add_document_versions.csv" \
https://myvault.veevavault.com/api/v10.0/objects/documents/versions/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771",
            "major_version_number__v": 0,
            "minor_version_number__v": 2
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772",
            "major_version_number__v": 0,
            "minor_version_number__v": 2
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773",
            "major_version_number__v": 1,
            "minor_version_number__v": 0
        },        
        {
            "responseStatus": "FAILURE"
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this document version was not added."
                }
            ]
        }
    ]
}

Delete Documents

Delete Document

Send a DELETE request to the /api/{VERSION}/objects/documents/{ID} endpoint.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534

Example Response

{
    "responseStatus": "SUCCESS",
    "id": 534
}

On success, Vault returns the ID of the deleted document.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Delete document.

Delete Document Version

Send a DELETE request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR}/{MINOR} endpoint.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/0/2

Example Response

{
    "responseStatus": "SUCCESS",
    "id": 534
}

On success, Vault deletes the specific version of the document, including the viewable rendition, field values, etc. Vault returns the ID of the document.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Delete document version.

Document Locks (Check-Out)

Retrieve Document Lock Metadata

Send a GET request to the /api/{VERSION}/metadata/objects/documents/lock endpoint.

A document "lock" is analogous to "checking out a document" but without the file attached in the response for download. To check out and retrieve the document file, use the Retrieve Document File request described below.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/metadata/objects/documents/lock

Example Response

{
    "responseStatus": "SUCCESS",
    "name": "lock",
    "properties": [
        {
            "name": "locked_by__v",
            "scope": "Lock",
            "type": "ObjectReference",
            "required": true,
            "systemAttribute": true,
            "editable": false,
            "setOnCreateOnly": false,
            "disabled": false,
            "objectType": "User",
            "label": "Locked By",
            "hidden": false
        },
        {
            "name": "locked_date__v",
            "scope": "Lock",
            "type": "DateTime",
            "required": true,
            "systemAttribute": true,
            "editable": false,
            "setOnCreateOnly": false,
            "disabled": false,
            "objectType": "DateTime",
            "label": "Locked Date",
            "hidden": false
        }
    ]
}

Response Details

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve document lock metadata.
v6.0 - Updated document lock field names.

Create Document Lock

Send a POST request to the /api/{VERSION}/objects/documents/{ID}/lock endpoint.

A document lock is analogous to checking out a document but without the file attached in the response for download. To get the file, use the "Retrieve Document File" request above.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/lock

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document successfully checked out."
}

On success, Vault locks the document and other users are not allowed to lock the document.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Create document lock.

Retrieve Document Lock

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/lock endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/lock

Example Response

{
    "responseStatus": "SUCCESS",
    "lock": {
        "locked_by__v": 46916,
        "locked_date__v": "2015-03-20T23:47:11.000Z"
    }
}

If the document is locked, Vault retrieves user ID of the person who checked out the document and when it was locked. If the document is not currently checked out, no lock fields will be returned.

Response Details

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve document lock.

Delete Document Lock (Undo Check-Out)

You can delete the document lock by sending a DELETE request to the /api/{VERSION}/objects/documents/{ID}/lock endpoint.

Deleting a document lock is analogous to undoing check out of a document.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/lock

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Undo check out successful."
}

On success, Vault unlocks the document, allowing other users to lock/check out the document.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Delete document lock.

Document Renditions

When a user uploads a file to Vault as a new document or version, Vault automatically generates a PDF rendition (the "viewable rendition"). Viewable renditions display in the Vault UI and allow users to view the document and add annotations. Each version of a document has a unique viewable rendition to reflect any changes made during the editing process of the source file. Other rendition types can also be accessed and managed by these APIs.

Learn more about Document Renditions in Vault Help.

Retrieve Document Renditions

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/renditions endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions

Where "534" is the document id.

Example Response

{
    "responseStatus": "SUCCESS",
    "renditionTypes": [
        "viewable_rendition__v",
        "imported_rendition__vs",
        "veeva_distribution_package__vs"
    ],
    "renditions": {
        "viewable_rendition__v": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions/viewable_rendition__v",
        "veeva_distribution_package__vs": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions/veeva_distribution_package__vs"
    }
}

Response Details

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - List document renditions.

Retrieve Document Version Renditions

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR}/{MINOR}/renditions endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/0/renditions

Where "534" is the document id. Since we want to retrieve the rendition for the major document version 2.0, we've added versions/2/0/renditions to the request.

Example Response

{
    "responseStatus": "SUCCESS",
    "renditionTypes": [
        "viewable_rendition__v",
        "imported_rendition__vs",
        "veeva_distribution_package__vs"
    ],
    "renditions": {
        "viewable_rendition__v": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/0/renditions/viewable_rendition__v",
        "veeva_distribution_package__vs": "https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/0/renditions/veeva_distribution_package__vs"
    }
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v7.0 - List document version renditions.

Retrieve Document Rendition File

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/renditions/{RENDITION_TYPE} endpoint.

To retrieve the latest steady state version of the document rendition, set the optional steadyState request parameter to true (false by default)

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions/viewable_rendition__v?steadyState=true > file

On success, Vault retrieves the file associated with the given renditions type for the document. The HTTP Response Header Content-Type is set to application/octet-stream.

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Retrieve document rendition.
v6.0 - steadyState request parameter supported.

Retrieve Document Version Rendition File

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR}/{MINOR}/renditions/{RENDITION_TYPE} endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/0/renditions/viewable_rendition__v > file

On success, Vault retrieves the file associated with the given renditions type for the specified document version. The HTTP Response Header Content-Type is set to application/octet-stream.

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v7.0 - Retrieve document version rendition file.

Upload Document Rendition

Send a POST request to the /api/{VERSION}/objects/documents/{ID}/renditions/{RENDITION_TYPE} endpoint.

• Set the HTTP Request Header Content-Type to multipart/form-data.
• To upload the file, use the multi-part attachment with the file component named file.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-F file=@my_document_rendition.pdf \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions/imported_rendition__vs

On success, Vault associates the uploaded file with the given rendition type for the specified document.

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v1.0 - Upload document rendition.

Upload Multiple Document Renditions

Add document renditions in bulk.

• Your vault must be in Migration Mode.
• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard format.
• The maximum batch size is 500.

POST /api/{version}/objects/documents/renditions/batch

Headers

Body Parameters

Query String Parameters

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\add_document_renditions.csv" \
https://myvault.veevavault.com/api/v10.0/objects/documents/renditions/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771",
            "major_version_number__v": 0,
            "minor_version_number__v": 2,
            "rendition_type__c": "imported_rendition__c"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772",
            "major_version_number__v": 0,
            "minor_version_number__v": 2,
            "rendition_type__c": "imported_rendition__c"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773",
            "major_version_number__v": 1,
            "minor_version_number__v": 0,
            "rendition_type__c": "imported_rendition__c"
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this document rendition was not added."
                }
            ]
        }
    ]
}

Upload Document Version Rendition

Send a POST request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR}/{MINOR}/renditions/{RENDITION_TYPE} endpoint.

• Set the HTTP Request Header Content-Type to multipart/form-data.
• To upload the file, use the multi-part attachment with the file component named file.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-F file=@my_document_rendition.pdf \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/0/renditions/imported_rendition__vs

On success, Vault associates the uploaded file with the given rendition type for the document with the specified version number.

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v7.0 - Upload document version rendition.

Replace Document Rendition

Send a PUT request to the /api/{VERSION}/objects/documents/{ID}/renditions/{RENDITION_TYPE} endpoint.

• Set the HTTP Request Header Content-Type to multipart/form-data.
• To upload the file, use the multi-part attachment with the file component named file.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-F file=@another_document_rendition.pdf \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions/imported_rendition__vs

On success, Vault replaces the rendition of the given type from the latest version of the document.

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v7.0 - Replace document rendition.

Replace Document Version Rendition

Send a PUT request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR}/{MINOR}/renditions/{RENDITION_TYPE} endpoint.

• Set the HTTP Request Header Content-Type to multipart/form-data.
• To upload the file, use the multi-part attachment with the file component named file.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-F file=@another_document_rendition.pdf \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/0/renditions/imported_rendition__vs

On success, Vault replaces the rendition of the given type for the specified version of the document.

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v7.0 - Replace document version rendition.

Delete Document Rendition

Send a DELETE request to the /api/{VERSION}/objects/documents/{ID}/renditions/{RENDITION_TYPE} endpoint.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/renditions/imported_rendition__vs

On success, Vault deletes the rendition of specified type from the latest document version.

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v7.0 - Delete document rendition.

Delete Document Version Rendition

Send a DELETE request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR}/{MINOR}/renditions/{RENDITION_TYPE} endpoint.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/0/renditions/imported_rendition__vs

On success, Vault deletes the rendition of the given type from the specified version of the document.

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v7.0 - Delete document version rendition.

Document Attachments

Attachments provide a simple way to upload and associate related files with existing documents without the overhead of Vault's full document management capabilities. Unlike "regular" documents in Vault, attachments don't have a document type, document fields, lifecycle, workflows, or annotations. Vault allows attachments on regular documents, content placeholders, binders, and CrossLinks. Document attachments are automatically bound to all versions of a document.

Learn more about Document Attachments in Vault Help.

Note: Before adding attachments, an Admin must first enable attachments at the base document level or individual document types, subtypes, or classifications.

Determine if a Document has Attachments

Send a GET request to the /api/{VERSION}/objects/documents/{ID} endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565

Example Response (abridged)

{
    ...
    "attachments": [
        {
            "id": 566,
            "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/566"
        },
        {
            "id": 567,
            "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/567"
        }
    ]
}

Shown above, document id 565 has two different attachments: id 566 and id 567. Note that this endpoint does not retrieve the number of versions of each attachment nor the attachment metadata. The "attachments" attribute is displayed in the response for documents in which attachments have been enabled on the document type (even if the document has no attachments).

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Determine if a document has attachments.

List Document Attachments

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/attachments endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments

Example Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 566,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 2,
            "created_by__v": 46916,
            "created_date__v": "2015-01-14T00:35:01.775Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/566/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/566/versions/2"
                }
            ]
        },
        {
            "id": 567,
            "filename__v": "Site Facilities Contacts.docx",
            "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "size__v": 11483,
            "md5checksum__v": "bddd2e18f40dd09ab4939ddd2acefeac",
            "version__v": 3,
            "created_by__v": 46916,
            "created_date__v": "2015-01-14T00:35:12.320Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/567/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/567/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/567/versions/3"
                }
            ]
        }
    ]
}

Shown above, document id 565 has two different attachments. Attachment id 566 is an image file with two versions. Attachment id 567 is a Word document with three versions. Unlike "regular" document versioning, attachment versioning uses integer numbers beginning with 1 and incrementing sequentially (1, 2, 3,...). There is no concept of major or minor version numbers with attachments.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - List document attachments.

Retrieve Document Attachment Metadata

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/attachments/{ID} endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments/566

Example Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 566,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 2,
            "created_by__v": 46916,
            "created_date__v": "2015-01-14T00:35:01.775Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/566/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/566/versions/2"
                }
            ]
        }
    ]
}

The md5checksum__v field is calculated on the latest version of the attachment. If an attachment is added which has the same MD5 checksum value as an existing attachment on a given document, the new attachment is not added.

Vault Document Attachments include the following fields (metadata):

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Retrieve document attachment metadata.

List Document Attachment Versions

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/attachments/{ID}/versions endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments/566/versions

Example Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "version__v": 1,
            "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/566/versions/1"
        },
        {
            "version__v": 2,
            "url": "https://myvault.vaultdev.com/api/v12.0/objects/documents/565/attachments/566/versions/2"
        }
    ]
}

Attachment versioning uses integer numbers beginning with 1 and incrementing sequentially (1, 2, 3,...). There is no concept of major or minor version numbers with attachments.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - List document attachment versions.

Retrieve Document Attachment Version Metadata

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/attachments/{ID}/versions/{VERSION} endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments/566/version/2

Example Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 566,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 2,
            "created_by__v": 46916,
            "created_date__v": "2015-01-14T00:35:01.775Z"
        }
    ]
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Retrieve document attachment version metadata.

Retrieve Document Attachment File

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/attachments/{ID}/file endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments/567/file

On success, Vault retrieves the latest version of the attachment from the document. The file name is the same as the attachment file name.

• The HTTP Response Header Content-Type is set to application/octet-stream
• The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. This can be changed.
• When retrieving attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachment downloads (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Example Response Header

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="file.pdf"

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Retrieve document attachment file.

Retrieve Document Attachment Version File

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/attachments/{ID}/version/{VERSION}/file endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments/567/versions/1/file

On success, Vault retrieves the specified version of the attachment from the document. The file name is the same as the attachment file name.

• The HTTP Response Header Content-Type is set to application/octet-stream
• The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file
• When downloading attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachment downloads (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Example Response Header

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="file.pdf"

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Retrieve document attachment version file.

Retrieve All Document Attachment Files

Send a GET request to the /api/{VERSION}/objects/documents/{ID}/attachments/file endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments/file

On success, Vault retrieves the latest version of all attachments from the document. The attachments are packaged in a ZIP file with the file name: Document {document number} (v. {major version}.{minor version}) - attachments.zip.

• The HTTP Response Header Content-Type is set to application/octet-stream
• The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. This can be changed.
• When downloading attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachment downloads (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Example Response Header

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="Document VV-02839 (v0.1) - attachments.zip"

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Retrieve all document attachment files.

Delete Document Attachment

Send a DELETE request to the /api/{VERSION}/objects/documents/{ID}/attachments/{ID} endpoint.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments/567

Example Response

{
    "responseStatus": "SUCCESS"
}

On success, Vault deletes the specific attachment and all its versions.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Delete document attachment.

Delete Document Attachment Version

Send a DELETE request to the /api/{VERSION}/objects/documents/{ID}/attachments/{ID}/versions/{VERSION} endpoint.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments/567/versions/3

Example Response

{
    "responseStatus": "SUCCESS"
}

On success, Vault deletes the specific version of the attachment.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Delete document attachment version.

Add Document Attachment

Send a POST request to the /api/{VERSION}/objects/documents/{ID}/attachments endpoint.

• Set the HTTP Request Header Content-Type to multipart/form-data.
• To upload the file, use the multi-part attachment with the file component named file.
• If an attachment is added which has the same filename as an existing attachment on a given document, the new attachment is added as a new version of the existing attachment.
• If an attachment is added which is exactly the same (same MD5 checksum value) as an existing attachment on a given document, the new attachment is not added.

Document attachments are automatically bound to all versions of a document.

The following attribute values are determined based on the file in the request:

• filename__v
• format__v
• size__v

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-F "file=my_attachment_file.png" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments

Example Response

{
    "responseStatus": "SUCCESS",
    "data":
    {
        "id": "567",
        "version__v": 3
    }
}

On success, the response will contain the attachment ID and version of the newly added attachment.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Add document attachment.

Restore Document Attachment Version

Send a POST request to the /api/{VERSION}/objects/documents/{ID}/attachments/{ID}/versions/{VERSION}?restore=true endpoint.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments/567/versions/2?restore=true

The parameter restore must be set to true

Example Response

{
    "responseStatus": "SUCCESS",
    "data":
    {
        "id": "567",
        "version__v": 3
    }
}

On success, Vault restores the specific version of an existing attachment to make it the latest version. The response will contain the attachment ID and version of the restored attachment.

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Restore document attachment version.

Update Document Attachment Description

Send a PUT request to the /api/{VERSION}/objects/documents/{ID}/attachments/{ID} endpoint.

Request Parameters

• Set the HTTP Request Header Content-Type to multipart/form-data or application/x-www-form-urlencoded.
• The only field available for editing is description__v
• The maximum character length for a description is 1000 characters

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-F "description__v=This is my description for this attachment." \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/565/attachments

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

On failure, the response displays an error type and message describing the error. Refer to the API Errors section below for additional information.

Version History

Since: v12.0 - Update document attachment description.

Document Annotations

Learn about Document Annotations in Vault Help.

Retrieve Document Annotations