API Reference (v11.0)

We recommend using a newer version of the API.

For general information on Vault, refer to Vault Help.

General

API calls are REST calls made to a specific endpoint. The general pattern is that collections are accessed via a URL ending in a plural noun such as /documents, and to target an individual resource, append its ID or a name (e.g. /documents/42).

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

To tell the API whether you are viewing, updating, or deleting the resource, make use of the HTTP verbs GET, PUT, and DELETE (respectively). To create a new resource, send a POST request to the collection's URL (e.g. /documents). The API will respond with a JSON (default) or XML document reflecting your changes. All responses will include a responseStatus with a SUCCESS, FAILURE or EXCEPTION value. For a responseStatus other than SUCCESS, an errors key/value array returned will provide additional details for the type of errors. If there are no errors the errors value will be empty or omitted. Error handling is covered in depth in the Errors section.

Supported Response Formats

Veeva Vault API supports JSON and XML response formats. To request response in a particular format use the Accept HTTP header with a value of application/json (for JSON response) or application/xml (for XML response). If Accept HTTP header is not specified the response is in JSON by default.

Alternatively query string parameter format can be included on the URL to indicate the desired format of the response. The possible values are json for response formatted as JSON and xml for response formatted as XML. The format value passed on the query string will overwrite the value in the Accept HTTP header. As with HTTP headers, JSON is the default format.

Below is the detailed information for each Veeva Vault API method, note that the string with curly braces in the endpoint URL denotes a variable value. For example, {version} in the endpoint URLs is a value returned from the Retrieve Available API Versions API call.

Authentication

Authentication calls are how the user gains access to their Vault through the API. Every Vault API endpoint requires an authorization token called session ID. Vault's authentication response contains the session ID and a list of all vaults to which the user has been given access.

Once a user authenticates with Vault, all subsequent API requests must contain Authorization HTTP header containing the session ID received as part of the authentication. Alternatively, the query string parameter auth can be used instead of HTTP header Authorization. The value passed in the auth parameter will overwrite any value in the HTTP header Authorization.

Vault supports the following authentication methods:

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

API Metadata

Retrieve Available API Versions

You can retrieve the list of supported API versions by sending a GET request to the /api endpoint.

For example:

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

Response

The response contains a list of all available API versions.

Example:

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Retrieve Available API Resources

You can retrieve the available API resources by sending a GET request to the /api/{version}/metadata/objects endpoint.

For example:

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

Response

The response contains a list of the available API resources.

Example:

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Domain Information

Allows the Domain Admin user to retrieve all active Vault instances in the domain they manage.

See also: About Veeva Vault Domains & Domain Settings in Vault Help.

Retrieve Domain Information

You can retrieve the Vault domain information by sending a GET request to the /api/{version}/objects/domain endpoint.

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

For example:

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

Response

The response contains a list of Vaults accessible to the user in the Domain.

Example:

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "domain__v": {
        "domain_name__v": "customer.com",
        "domain_type__v": "Sandbox",
        "vaults__v": [
            {
                "id": "4621",
                "vault_name__v": "Customer Promos",
                "vault_status__v": "Active",
                "vault_application__v": "PromoMats"
            },
            {
                "id": "5091",
                "vault_name__v": "Customer eTMF",
                "vault_status__v": "Active",
                "vault_application__v": "eTMF"
            }
        ]
    }
}

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v7.0

Document Metadata

Vault is a very configurable system designed to reflect the business model of documents. Each Vault can have different document types, document fields, etc. The Document Metadata APIs allow you to interrogate the Vault to understand what document-based metadata is available to use.

Retrieve All Document Types

You can retrieve all document types configured in Vault by sending a GET request to the /api/{version}/metadata/objects/documents or /api/{version}/metadata/objects/documents/types endpoint.

For example:

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

Response

The response contains a list of document types configured in Vault.

Example:

{
    "responseStatus": "SUCCESS",
    "types": [
        {
            "label": "Base Document",
            "value": "https://{CUSTOMER}.veevavault.com/api/v11.0/metadata/objects/documents/types/base_document__v"
        },
        {
            "label": "Claim",
            "value": "https://{CUSTOMER}.veevavault.com/api/v11.0/metadata/objects/documents/types/claim__vs"
        }
        {
            "label": "Promotional Piece",
            "value": "https://{CUSTOMER}.veevavault.com/api/v11.0/metadata/objects/documents/types/promotional_piece__vs"
        },
        {
            "label": "Reference Document",
            "value": "https://{CUSTOMER}.veevavault.com/api/v11.0/metadata/objects/documents/types/reference_document__vs"
        }
    ],
    "lock": "https://{CUSTOMER}.veevavault.com/api/v11.0/metadata/objects/documents/lock"
}

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Retrieve Document Type

You can retrieve the metadata for the document type by sending a GET request to the /api/{version}/metadata/objects/documents/types/{type} endpoint.

For example:

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

Response

The response contains the metadata for the document type.

If the type contains subtypes in the document type hierarchy, the list of subtypes and the URLs pointing to their metadata will be included in the response.

If no subtypes exist in the document type hierarchy, the list of document fields defined for the specified type will be included in the response.

Shared Fields:
Shared fields are indicated by shared: true metadata field. In addition, usedIn metadata field specifies the document {type}:{subtype}:{classification} where the field is currently used.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Retrieve Document Subtype

You can retrieve the metadata for the document subtype by sending a GET request to the /api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype} endpoint.

By default the fields and templates from higher in the document type hierarchy are included. To exclude, set query parameter includeInheritedFields to false.

For example:

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

Response

The response contains the metadata for the document subtype defined for the specified type.

If the subtype contains classifications in the document type hierarchy, the list of classifications and the URLs pointing to their metadata will be included in the response.

If no classifications exist in the document type hierarchy under specified subtype, the list of document fields defined for the specified subtype will be included in the response.

Shared Fields:
Shared fields are indicated by shared: true metadata field. In addition, usedIn metadata field specifies the document {type}:{subtype}:{classification} where the field is currently used.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Retrieve Document Classification

You can retrieve the metadata for the document classification by sending a GET request to the /api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype}/classifications/{classification} endpoint.

By default the fields and templates from higher in the document type hierarchy are included. To exclude, set query parameter includeInheritedFields to false.

For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype}/classifications/{classification}

Response

The response contains the list of document fields for the document classification defined for the specified classification.

Shared Fields:
Shared fields are indicated by shared: true metadata field. In addition, usedIn metadata field specifies the document {type}:{subtype}:{classification} where the field is currently used.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Retrieve Document Fields

You can retrieve the metadata of all document fields by sending a GET request to the /api/{version}/metadata/objects/documents/properties endpoint.

For example:

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

Response

The response contains the list of document fields configured across entire document type hierarchy. Formula fields are currently not returned.

Shared Fields:
Shared fields are indicated by shared: true metadata field. In addition, usedIn metadata field specifies the document {type}:{subtype}:{classification} where the field is currently used.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v4.0

Retrieve Document Relationships

You can retrieve the document relationships metadata by sending a GET request to the /api/{version}/metadata/objects/documents/types/{type}/relationships endpoint.

For example:

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

Response

The response contains the information on relationship types available for the specified document type and generic relationship fields, such as Target Document and Source Document IDs.

Example:

{
    "responseStatus": "SUCCESS",
    "properties": [
        {
            "name": "id",
            "type": "id",
            "length": 20,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "source_doc_id__v",
            "type": "id",
            "length": 20,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "source_major_version__v",
            "type": "Integer",
            "length": 10,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "source_minor_version__v",
            "type": "Integer",
            "length": 10,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "target_doc_id__v",
            "type": "id",
            "length": 20,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "target_major_version__v",
            "type": "Integer",
            "length": 10,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "target_minor_version__v",
            "type": "Integer",
            "length": 10,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "relationship_type__v",
            "type": "String",
            "length": 255,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "created_date__v",
            "type": "DateTime",
            "length": 0,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "created_by__v",
            "type": "ObjectReference",
            "length": 10,
            "object": "users",
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "source_vault_id__v",
            "type": "id",
            "length": 20,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": false
        }
    ],
    "relationshipTypes": [
        {
            "value": "supporting_documents__vs",
            "label": "Supporting Documents",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": false,
            "system": false,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Trial Management",
                    "value": "trial_management__vs"
                },
                {
                    "label": "Country Master File",
                    "value": "country_master_file__v"
                },
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Regulatory",
                    "value": "regulatory__vs"
                },,
                {
                    "label": "Site Master File",
                    "value": "site_master_file__v"
                }
            ]
        },
        {
            "value": "references__vs",
            "label": "Linked Documents",
            "sourceDocVersionSpecific": true,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Trial Management",
                    "value": "trial_management__vs"
                },
                {
                    "label": "Country Master File",
                    "value": "country_master_file__v"
                },
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Regulatory",
                    "value": "regulatory__vs"
                },
                {
                    "label": "Site Master File",
                    "value": "site_master_file__v"
                }
            ]
        },
        {
            "value": "crosslink_document_static__v",
            "label": "CrossLink Static Bindings",
            "sourceDocVersionSpecific": true,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Trial Management",
                    "value": "trial_management__vs"
                },
                {
                    "label": "Country Master File",
                    "value": "country_master_file__v"
                },
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Regulatory",
                    "value": "regulatory__vs"
                },
                {
                    "label": "Site Master File",
                    "value": "site_master_file__v"
                }
            ]
        },
        {
            "value": "crosslink_document_latest__v",
            "label": "CrossLink Latest Bindings",
            "sourceDocVersionSpecific": true,
            "targetDocVersionSpecific": false,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Trial Management",
                    "value": "trial_management__vs"
                },
                {
                    "label": "Country Master File",
                    "value": "country_master_file__v"
                },
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Regulatory",
                    "value": "regulatory__vs"
                },
                {
                    "label": "Site Master File",
                    "value": "site_master_file__v"
                }
            ]
        },
        {
            "value": "basedon__vs",
            "label": "Based on",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Trial Management",
                    "value": "trial_management__vs"
                },
                {
                    "label": "Country Master File",
                    "value": "country_master_file__v"
                },
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Regulatory",
                    "value": "regulatory__vs"
                },
                {
                    "label": "Site Master File",
                    "value": "site_master_file__v"
                }
            ]
        },
        {
            "value": "crosslink_document_latest_steady_state__v",
            "label": "CrossLink Latest Steady State Bindings",
            "sourceDocVersionSpecific": true,
            "targetDocVersionSpecific": false,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Trial Management",
                    "value": "trial_management__vs"
                },
                {
                    "label": "Country Master File",
                    "value": "country_master_file__v"
                },
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Regulatory",
                    "value": "regulatory__vs"
                },
                {
                    "label": "Site Master File",
                    "value": "site_master_file__v"
                }
            ]
        }
    ]
}

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v3.0

Retrieve Document Lock Metadata

You can retrieve the document lock metadata by sending a GET request to the /api/{version}/metadata/objects/documents/lock endpoint.

For example:

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

Response

The response contains the document lock metadata.

Example:

{
    "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
        }
    ]
}

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0
v6.0: updated field names

Find Common Document Fields

In order to help determine which document fields can be updated on documents in bulk, it is helpful to find the common document fields among a list of documents. You can determine the common document fieds by sending a list of document IDs docIds in a POST request to /metadata/objects/documents/properties/find_common endpoint.

For example:

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

Response

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v9.0

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.

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.
• 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/v11.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/v11.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/v11.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/v11.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

You can retrieve the documents from a specific Library view or documents matching a keyword search by sending a GET request to the /api/{version}/objects/documents endpoint.

The Retrieve Documents API mimics the behavior of the pre-canned document filters available through the Vault UI: My Documents (documents I have created or updated), Recent Documents (documents I have recently viewed), Favorites (documents I have tagged as Favorites). Just as with the UI, the lists return both documents and binders.

Request Parameters

For example:

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

Response

On success, Vault retrieves the list of documents and binders matching the request criteria, with their metadata. 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 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.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0
v4.0: the scope parameter is supported
v4.0: the response now includes term highlighting hints
v5.0: the response now distinguishes between documents and binders
v10.0: CrossLink documents are supported

Retrieve Document

You can retrieve the document properties and property values for the specified document by sending a GET request to the /api/{version}/objects/documents/{id} endpoint.

For example:

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

Response

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.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0
v10.0: CrossLink documents are supported

Retrieve Document Versions

You can retrieve the available versions of the document by sending a GET request to the /api/{version}/objects/documents/{id}/versions endpoint.

For example:

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

Response

On success, Vault returns a list of the available versions for the specified document.

Example:

{
    "responseStatus": "SUCCESS",
    "versions": [
        {
            "number": "1.1",
            "value": "https://customer.veevavault.com/api/v11.0/objects/documents/208/versions/1/1"
        },
        {
            "number": "2.1",
            "value": "https://customer.veevavault.com/api/v11.0/objects/documents/208/versions/2/1"
        },
        {
            "number": "1.2",
            "value": "https://customer.veevavault.com/api/v11.0/objects/documents/208/versions/1/2"
        },
        {
            "number": "2.0",
            "value": "https://customer.veevavault.com/api/v11.0/objects/documents/208/versions/2/0"
        },
        {
            "number": "1.0",
            "value": "https://customer.veevavault.com/api/v11.0/objects/documents/208/versions/1/0"
        }
    ],
    "renditions": {
        "veeva_distribution_package__vs": "https://customer.veevavault.com/api/v11.0/objects/documents/208/renditions/veeva_distribution_package__vs",
        "viewable_rendition__v": "https://customer.veevavault.com/api/v11.0/objects/documents/208/renditions/viewable_rendition__v"
    }
}

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Retrieve Document Version

You can retrieve the document properties and property values for the specified document version by sending a GET request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor} endpoint.

For example:

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

Response

On success, Vault returns the properties and property values for the specified version of the document. Response properties will vary based on properties defined for the document type of the specified document.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Update Document

You can update a document by sending a PUT request to the /api/{version}/objects/documents/{id} endpoint.

Refer to the output of the Document Metadata APIs, only those properties that are marked as "editable": true are valid.

To reclassify the document, set the reclassify request parameter to true (set to false by default). While reclassifying you are able to set the lifecycle/type/subType/classifications for the document together with the properties required for the specified classification.

Response

On success, the response will contain the ID of the updated document.

Example:

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0
v8.0: reclassify support added

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"
        }
    ]
}

Update Document Version

You can update a document version by sending a PUT request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor} endpoint.

Refer to the output of the Document Metadata APIs, only those properties that are marked as "editable": true are valid.

Response:

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

Example:

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

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 Document

You can delete the document by sending a DELETE request to the /api/{version}/objects/documents/{id} endpoint.

For example:

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

Response

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Delete Document Version

You can delete the specific version of the document by sending a DELETE request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor} endpoint.

For example:

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/versions/{major}/{minor}

Response

On success, Vault deletes the version specified, including the viewable rendition, property values, etc., and returns the ID of the deleted document.

Example:

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Retrieve Document File

You can retrieve the source file from the document by sending a GET request to the /api/{version}/objects/documents/{id}/file endpoint.

You can check-out the document before the retrieval by setting lockDocument request parameter to true (false by default).

For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/file?lockDocument=true > file

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.

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0
v6.0: check-out prior to retrieval is supported

Retrieve Document Version File

You can retrieve the source file from the specified version of the document by sending a GET request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/file endpoint.

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.

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Retrieve Document Version Thumbnail

You can retrieve the document thumbnail image for the specified version of the document by sending a GET request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/thumbnail endpoint.

For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/versions/{major}/{minor}/thumbnail > thumbnail.png

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.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v6.0

Create Document Lock (Check-out)

You can create the document lock by sending 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 API.

For example:

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

Response

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

Example:

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Retrieve Document Lock

You can check if the document is locked (checked-out) by sending a GET request to the /api/{version}/objects/documents/{id}/lock endpoint.

For example:

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

Response

On success, Vault retrieves the lock object (if any) for a document. If the document is not currently checked out, no lock properties will be returned.

Example:

{
    "responseStatus": "SUCCESS",
    "lock": {
        "locked_by__v": 25496,
        "locked_date__v": "2013-04-09T18:01:09.000Z"
    }
}

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Delete Document Lock

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.

For example:

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

Response

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

Example:

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Update Document File / Create Draft

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.

The HTTP Request Header Content-Type must be set to multipart/form-data. To upload a file, use multi-part attachment with the file component named file.

Request Parameters

• 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

Response

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0
v7.0: Create Draft feature is supported
v8.0: suppressing generation of viewable rendition is supported

List Document Renditions

You can retrieve the list of rendition types available for the document by sending a GET request to the /api/{version}/objects/documents/{id}/renditions endpoint.

For example:

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

Response

On success, Vault returns the list of rendition types for the document.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

List Document Version Renditions

You can retrieve the list of rendition types available for the specified document version by sending a GET request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions endpoint.

For example:

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

Response

On success, Vault returns the list of rendition types for the specified document version.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v7.0

Retrieve Document Rendition

You can retrieve the file associated with the given rendition type for the document by sending a GET request to the /api/{version}/objects/documents/{id}/renditions/{renditionType} endpoint.

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

For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/renditions/{renditionType}?steadyState=true > file

Response

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.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0
v6.0: steadyState request parameter supported

Retrieve Document Version Rendition

You can retrieve the file associated with the given rendition type for the specified document version by sending a GET request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType} endpoint.

For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType} > file

Response

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.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v7.0

Retrieve Document Annotations

You can retrieve the latest version of a document and its annotations by sending a GET request to the /api/{version}/objects/documents/{id}/annotations endpoint.

For example:

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

Response

On success, Vault retrieves the document rendition and its associated annotations. The HTTP Response Header Content-Type is set to application/pdf.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v11.0

Retrieve Document Version Annotations

You can retrieve a specific version of a document and its annotations by sending a GET request to the /api/{version}/objects/documents/{id}/versions/{maj}/{min}/annotations endpoint.

For example:

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

Response

On success, Vault retrieves the specified version document rendition and its associated annotations. The HTTP Response Header Content-Type is set to application/pdf. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v11.0

Upload Document Rendition

You can upload the file to be associated with the given rendition type for the document by sending a POST request to the /api/{version}/objects/documents/{id}/renditions/{renditionType} endpoint.

The HTTP Request Header Content-Type must be set to multipart/form-data. Include the file component in the multi-part attachment named file.

For example:

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-F file=@file.pdf \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/renditions/{renditionType}

Response

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v1.0

Add 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

You can upload the file to be associated with the given rendition type for the the document with the specified version number by sending a POST request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType} endpoint.

The HTTP Request Header Content-Type must be set to multipart/form-data. Include the file component in the multi-part attachment named file.

For example:

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-F file=@file.pdf \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType}

Response

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v7.0

Upload Document Annotations

You can upload the file to be associated with the given document rendition along with its associated annotations by sending a POST request to the /api/{version}/objects/documents/{id}/annotations endpoint.

The HTTP Request Header Content-Type must be set to multipart/form-data. Include the file component in the multi-part attachment named file.

For example:

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-F file=@file.pdf \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/annotations

Response

On success, Vault uploads the file and its annotations.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v11.0

Upload Document Version Annotations

You can upload a specific version of a file to be associated with the given document rendition along with its associated annotations by sending a POST request to the /api/{version}/objects/documents/{id}/versions/{maj}/{min}/annotations endpoint.

The HTTP Request Header Content-Type must be set to multipart/form-data. Include the file component in the multi-part attachment named file.

For example:

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-F file=@file.pdf \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/versions/{maj}/{min}/annotations

Response

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v11.0

Delete Latest Document Rendition

You can delete the rendition of specified type from the latest document version by sending a DELETE request to the /api/{version}/objects/documents/{id}/renditions/{renditionType} endpoint.

For example:

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

Response

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v7.0

Delete Document Version Rendition

You can delete the rendition of the given type from the specified version of the document by sending a DELETE request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType} endpoint.

For example:

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType} 

Response

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v7.0

Replace Document Rendition

You can replace the rendition of the given type from the latest version of the document by sending a PUT request to the /api/{version}/objects/documents/{id}/renditions/{renditionType} endpoint.

The HTTP Request Header Content-Type must be set to multipart/form-data. Include the file component in the multi-part attachment named file.

For example:

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-F file=@file.pdf \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/renditions/{renditionType

Response

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v7.0

Replace Document Version Rendition

You can replace the rendition of the given type from the specified version of the document by sending a PUT request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType} endpoint.

The HTTP Request Header Content-Type must be set to multipart/form-data. Include the file component in the multi-part attachment named file.

For example:

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-F file=@file.pdf \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType}

Response

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

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v7.0

List Document Relationships

You can retrieve the list of document relationships by sending a GET request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships endpoint.

For example:

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

Response

On success, Vault returns a list of relationships where the specified document is the source document.

Example:

{
  "responseStatus": "SUCCESS",
  "relationships": [
    {
      "relationship": {
        "id": 31,
        "source_doc_id__v": 24,
        "relationship_type__v": "related_claims__vs",
        "created_by__v": 25496,
        "created_date__v": "2013-03-12T16:59:39.000Z",
        "target_doc_id__v": 22
      }
    }
  ]
}

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v3.0

Create Document Relationship

Method & Endpoint

Send a POST request to the /api/{VERSION}/objects/documents/{ID}/versions/{MAJOR_VERSION}/{MINOR_VERSION}/relationships 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.

Input Parameters

• target_doc_id__v - [Required] The target document id field value.
• relationship_type__v - [Required] The relationship type retrieved from the Document Relationships Metadata call.
• target_major_version__v - [Optional] The major version number of the target document.
• target_minor_version__v - [Optional] The minor version number of the target document.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "target_doc_id__v=548"
-d "relationship_type__v=supporting_documents__vs"
-d "target_major_version_v=0"
-d "target_minor_version_v=1"
https://myvault.veevavault.com/api/v14.0/objects/documents/548/versions/0/1/relationships

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document relationship successfully created.",
    "id": 200
}

On success, Vault returns the ID of the newly created document relationship.

Possible Errors

Version History

Available in API v3.0 or later.

Delete a Document Relationship

You can delete the document relationship by sending a DELETE request to the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships/{relationshipId} endpoint.

For example:

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships/{relationshipId}

Response

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

Example:

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Document relationship successfully deleted.",
  "id": 35
}

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v3.0

Document Events

The Document Events are used to track the document and binder distribution events across sub-systems such as iRep, Controlled Copy, Approved Email and Engage.

Document Events Metadata

Through the Document Event Metadata APIs you can retrieve the current configuration of the Document Events in your Vault including the available event types and subtypes, and the event data each of the types/sybtypes manage.

Retrieve Available Document Event Types

You can retrieve the document event types by sending a GET request to the /api/{version}/metadata/objects/documents/events endpoint.

For example:

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

Response

On success, Vault returns the list of events, and event types per each event (if applicable). If the user is not permitted to access the event data, the event type is omitted from the response.

Example:

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "name": "distribution__v",
            "label": "Distribution Event",
            "subtypes": [
                {
                    "name": "approved_email__v",
                    "label": "Approved Email",
                    "value": "https://customer.veevavault.com/api/v11.0/metadata/objects/documents/events/distribution__v/types/approved_email__v"
                },
                {
                    "name": "controlled_copy__v",
                    "label": "Controlled Copy",
                    "value": "https://customer.veevavault.com/api/v11.0/metadata/objects/documents/events/distribution__v/types/controlled_copy__v"
                },
                {
                    "name": "irep__v",
                    "label": "CRM",
                    "value": "https://customer.veevavault.com/api/v11.0/metadata/objects/documents/events/distribution__v/types/irep__v"
                },
                {
                    "name": "engage__v",
                    "label": "Engage",
                    "value": "https://customer.veevavault.com/api/v11.0/metadata/objects/documents/events/distribution__v/types/engage__v"
                },
                {
                    "name": "published_content__v",
                    "label": "Published Content",
                    "value": "https://customer.veevavault.com/api/v11.0/metadata/objects/documents/events/distribution__v/types/published_content__v"
                },
                {
                    "name": "clm__v",
                    "label": "CLM",
                    "value": "https://customer.veevavault.com/api/v11.0/metadata/objects/documents/events/distribution__v/types/clm__v"
                }
            ]
        }
    ]
}

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v6.0

Retrieve Event Type Metadata & Defined Subtypes

You can retrieve the document event type metadata by sending a GET request to the /api/{version}/metadata/objects/documents/events/{event_type} endpoint.

For example:

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

Response

On success, Vault returns all metadata for the specified event type. If event subtypes are defined for the event type, the subtypes will also be included

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v6.0

Document Events Data

Through the Document Event Data APIs you can log and retrieve the document distribution event data in your Vault.

Retrieve Document Event Data

You can retrieve the document event type metadata by sending a GET request to the /objects/documents/{id}/events endpoint.

Request Parameters

You can include one or more queryable event properties and associated values in the request parameters to filter the response.

Example: specifying event_type__v=Distribution will return only distribution events, event_type__v=Distribution&event_subtype__v=Approved Email will return only distribution events generated for/by Approved Email

• Use startDate and endDate parameters to filter by date range

  • the date can be specified in UTC including the time part, although the time part is optional. If time part is not included a midnight on the specified date is assumed.

• Use limit and start parameters for paginating over the result set

Response

On success, Vault returns the list of event objects, each containing the properties as defined by the metadata for its event type. Null and/or false valued properties are omitted from the response. By default 200 records is returned, however this can be overwritten by specifying an alternative value in the limit parameter.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v6.0

Log a Document Event

You can log a document event of specific type, subtype, and classificationt by sending a POST request to the /objects/documents/{id}/versions/{maj}/{min}/events endpoint.

Request Parameters

Provide the name-value pairs consisting of all required properties and the values for the event type/subtype specified. The required properties are obtained from the "Event Type Metadata" API for the event type/subtype. Either Labels or keys can be used for event_type__v, event_subtype__v and classification__v properties.

Response

On success, Vault logs the document event.

Errors

On failure, the response will contain an error response. Refer to Errors section below for details.

Version History

Since: v6.0

Attachments

As of V11.0 of the API, files can now be added as attachments to documents and object records.

Note: An Admin must first enable attachments on the document type, subtype, classification, or object. Learn more about Attachments in Vault Help.

Attachment Fields

Attachments have the following metadata:

Note: 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.

Attachments on Documents

Attachments are automatically be added to the latest version of a document. When the document is versioned, the latest version of all attachments can be brought forward with the new document version. All previous versions of attachments remain attached to the earlier versions of the document and exist in a read-only state.

Determine if a Document has Attachments

You can determine if a document contains attachments by sending a GET request to the /objects/documents/{id} endpoint. Learn more about retrieving documents. For example:

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

Response (abridged)

{
    "attachments": [
        {
            "id": 566,
            "url": "https://myvault.vaultdev.com/api/v11.0/objects/documents/565/attachments/566"
        },
        {
            "id": 567,
            "url": "https://myvault.vaultdev.com/api/v11.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).

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

List Attachments

You can retrieve a list of all available attachments and versions of each attachment on a document by sending a GET request to the /objects/documents/{id}/attachments endpoint. For example:

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

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/v11.0/objects/documents/565/attachments/566/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v11.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/v11.0/objects/documents/565/attachments/567/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v11.0/objects/documents/565/attachments/567/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.vaultdev.com/api/v11.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.

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Retrieve Attachment Metadata

You can retrieve the metadata from a specific attachment by sending a GET request to the /objects/documents/{id}/attachments/{id} endpoint. For example:

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

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://sharpers.vaultdev.com/api/v11.0/objects/documents/565/attachments/566/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://sharpers.vaultdev.com/api/v11.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 or object record, the new attachment is not added.

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

List Attachment Versions

You can retrieve a list of all available versions of a specific attachment by sending a GET request to the /objects/documents/{id}/attachments/{id}/versions endpoint. For example:

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

Response:

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

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Retrieve Attachment Version Metadata

You can retrieve the metadata from a specific version of an attachment by sending a GET request to the /objects/documents/{id}/attachments/{id}/versions/{version} endpoint. For example:

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

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"
        }
    ]
}

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Download Attachment

You can download the latest version of a specific attachment by sending a GET request to the /objects/documents/{id}/attachments/{id}/file endpoint. For example:

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

Response

On success, Vault retrieves the latest version of the attachment from the document. The downloaded 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 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.

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

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Download Attachment Version

You can download a specific version of an attachment by sending a GET request to the /objects/documents/{id}/attachments/{id}/version/{version}/file endpoint. For example:

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

Response

On success, Vault retrieves the specified version of the attachment from the document. The downloaded 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.

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Download All Attachments

You can download the latest versions of all attachments by sending a GET request to the /objects/documents/{id}/attachments/file endpoint. For example:

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

Response

On success, Vault retrieves the latest version of all attachments from the document. The downloaded 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.

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

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Delete Attachment

You can delete a specific attachment (including all versions of the attachment) by sending a DELETE request to the /objects/documents/{id}/attachments/{id} endpoint. For example:

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

Response

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

{
    "responseStatus": "SUCCESS"
}

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Delete Attachment Version

You can delete a specific version of an attachment by sending a DELETE request to the /objects/documents/{id}/attachments/{id}/versions/{version} endpoint. For example:

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

Response

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

{
    "responseStatus": "SUCCESS"
}

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Add Attachment

You can add an attachment to a document record in Vault by sending a POST request to the /objects/documents/{id}/attachments endpoint.

• The maximum file size allowed is 4GB.
  
• The HTTP Request Header Content-Type must be set to multipart/form-data
• The file component of the multipart request must be specified as 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 or object record, the new attachment is not added.

No POST parameters are required to create an attachment. The following attribute values are determined based on the file in the request:

• filename__v
• format__v
• size__v

Response

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

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

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Restore Attachment Version

You can restore a specific version of an attachment to make it the latest version by sending a POST request to the /objects/documents/{id}/attachments/{id}/versions/{version} endpoint. For example:

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

The parameter restore must be set to true

Response

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

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

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Update Attachment Description

You can update the description of the latest version of an attachment by sending a PUT request to the /objects/documents/{id}/attachments/{id} endpoint.

Required Parameters

• The HTTP Request Header Content-Type must be set 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

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Attachments on Object Records

Determine if Attachments are Enabled

You can determine if attachments have been enabled for a specific object by sending a GET request to the /api/{version}/metadata/vobjects/{object} endpoint. For example:

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

Response (abridged)

{
    "responseStatus": "SUCCESS",
    "object": {
        "created_date": "2014-02-03T20:12:29.000Z",
        "created_by": 1,
        "allow_attachments": true,
        "auditable": true,
        "modified_date": "2015-01-06T22:34:15.000Z",
        "status": [
            "active__v"
        ],
        "urls": {
            "field": "/api/v11.0/metadata/vobjects/site__v/fields/{name}",
            "record": "/api/v11.0/vobjects/site__v/{id}",
            "attachments": "/api/v11.0/vobjects/site__v/{id}/attachments",
            "list": "/api/v11.0/vobjects/site__v",
            "metadata": "/api/v11.0/metadata/vobjects/site__v"
        },
        "label_plural": "Study Sites",
        "role_overrides": false,
        "label": "Study Site",
        "in_menu": true,
        "help_content": null,
        "source": "standard",
        "order": null,
        "modified_by": 46916,
        "description": null,
        "name": "site__v",
}

Shown above, "attachments" is included in the list of urls, indicating that attachments are enabled on the site__v object. This means that any of the object records may have attachments.

Version History

Since: v11.0

List Attachments

You can retrieve a list of all available attachments and versions of each attachment on a specific object record by sending a GET request to the /api/{version}/vobjects/{name}/{id}/attachments endpoint. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v11.0/metadata/vobjects/site__v/1357752909483/attachments

Where "1357752909483" is the site__v object record id.

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 558,
            "filename__v": "Site Contact List.docx",
            "description__v": "Facilities information and contacts",
            "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "size__v": 11450,
            "md5checksum__v": "9c6f61847207898ca98431d3e9ad176d",
            "version__v": 3,
            "created_by__v": 46916,
            "created_date__v": "2015-01-07T21:42:47.772Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v11.0/vobjects/site__v/1357752909483/attachments/558/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v11.0/vobjects/site__v/1357752909483/attachments/558/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.vaultdev.com/api/v11.0/vobjects/site__v/1357752909483/attachments/558/versions/3"
                }
            ]
        },
        {
            "id": 571,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 1,
            "created_by__v": 46916,
            "created_date__v": "2015-01-16T22:28:44.039Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v11.0/vobjects/site__v/1357752909483/attachments/571/versions/1"
                }
            ]
        }
    ]
}

Shown above, the site__v object record has three versions of attachment id 558 and one version of attachment id 571. 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.

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Retrieve Attachment Metadata

You can retrieve the metadata from a specific attachment by sending a GET request to the /vobjects/{name}/{id}/attachments/{id} endpoint. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v11.0/vobjects/site__v/1357752909483/attachments/558

Where "1357752909483" is the site__v object record id.

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 558,
            "filename__v": "Site Contact List.docx",
            "description__v": "Facilities information and contacts",
            "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "size__v": 11450,
            "md5checksum__v": "9c6f61847207898ca98431d3e9ad176d",
            "version__v": 3,
            "created_by__v": 46916,
            "created_date__v": "2015-01-07T21:42:47.772Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v11.0/vobjects/site__v/1357752909483/attachments/558/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v11.0/vobjects/site__v/1357752909483/attachments/558/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.vaultdev.com/api/v11.0/vobjects/site__v/1357752909483/attachments/558/versions/3"
                }
            ]
        }
    ]
}

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 object record, the new attachment is not added.

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

List Attachment Versions

You can retrieve a list of all available versions of a specific attachment by sending a GET request to the /vobjects/{name}/{id}/attachments/{id}/versions endpoint. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v11.0/vobjects/site__v/1357752909483/attachments/571/versions

Where "1357752909483" is the site__v object record id.

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "version__v": 1,
            "url": "https://myvault.vaultdev.com/api/v11.0/vobjects/site__v/1357752909483/attachments/571/versions/1"
        }
    ]
}

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Retrieve Attachment Version Metadata

You can retrieve the metadata from a specific version of an attachment by sending a GET request to the /vobjects/{name}/{id}/attachments/{id}/versions/{version} endpoint. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v11.0/vobjects/site__v/1357752909483/attachments/571/versions/1

Where "1357752909483" is the site__v object record id.

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 571,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 1,
            "created_by__v": 46916,
            "created_date__v": "2015-01-16T22:28:44.039Z"
        }
    ]
}

Errors

On failure, the response will contain an error response.

Version History

Since: v11.0

Download Attachment

You can download the latest version of a specific attachment by sending a GET request to the /vobjects/{name}/{id}/attachments/{id}/file endpoint. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v11.0/vobjects/site__v/1357752909483/attachments/571/file