Vault API Reference

API Reference (v12.0)

We recommend using a newer version of the API.

For general information on Vault, refer to Vault Help.

General API Information

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

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

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

HTTP Methods

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

Response Formats

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

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

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

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

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

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

Retrieve Available API Resources

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

Example Request

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

Example Response

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

Response Details

Field Name Description Comments
metadata/objects/documents/types Retrieve Document Types Endpoint to retrieve a list of all document types configured in your vault.
metadata/objects/users Retrieve User Metadata Endpoint to retrieve a list of all user metadata configured in your vault.
metadata/objects/groups Retrieve Group Metadata Endpoint to retrieve a list of all group metadata configured in your vault.
metadata/objects/securitypolicies Retrieve Security Policies Endpoint to retrieve all security policies configured in your vault.
metadata/vobjects Retrieve Object Collection Endpoint to retrieve all Vault Objects (products, countries, studies, etc.) configured in your vault.

Retrieve Available API Versions

Send a GET request to the /api endpoint.

Example Request

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

Example Response

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

About Vault API Versions

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

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

Retrieve Vaults in Your Domain

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

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

Example Request

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

Example Response

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

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

Response Details

Field Name Description Comments
domain_name__v Domain Name A unique name assigned to the domain.
domain_type__v Domain Type The domain type: Production, Demo, Sandbox, other.
vaults__v [n] Vaults List of all vaults in the domain.
id Vault ID System-managed numerical ID assigned to each vault in the domain.
vault_name__v Vault Name Descriptive name given to each vault in the domain.
vault_status__v Vault Status Status of each vault in the domain: Active or Inactive.
vault_application__v Vault Application Vault Application Type: Platform, PromoMats, eTMF, Submissions, MedComms, or QualityDocs.

Authentication

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

Vault supports the following authentication methods:

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

Example Request (Username & Password Authentication)

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

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

Example Response

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

The example above shows two vaults in the company domain:

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

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

Field Name Description Comments
sessionId Session ID Vault Authorization Token for the specified vaultId to use for all subsequent API requests in this vault.
userId User ID Vault User ID of the user authenticating with Vault.
vaultIds Vault IDs List of all vaults in the domain to which you have been given access.
id Vault ID The ID of each vault in the domain.
name Vault Name The name of each vault in the domain.
url Vault URL The URL to access each vault in the domain.
vaultId Authenticated Vault ID The specific vault ID for which the current sessionId has been issued.

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

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

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

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

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

Possible Errors

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

Error Type Error Message/Description
USERNAME_OR_PASSWORD_INCORRECT Invalid login credentials provided.
INVALID_SESSION_ID Invalid or expired session ID. You must retrieve a new sessionId. Your authentication automatically expires after a certain period of time. Contact your Vault Administrator to determine the session duration for your vault.
USER_LOCKED_OUT Account locked out due to repeated failed login requests. Contact your Vault Administrator to recover your password.

Version History

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



Documents

Retrieve Document Fields

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

Example Request

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

Example Response (abridged)

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

Retrieve Shared Document Fields

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

Document Field Description
usedIn: key When the document field shared is true, this field lists the names of the document types using the shared field.
usedIn: type When the document field shared is true, this field indicates whether the shared document field is used by a document "type", "subtype", or "classification".

Possible Errors

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

Version History

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

Find Common Document Fields

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

Request Parameters

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

Example Request

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

Example Response (abridged)

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

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

Possible Errors

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

Version History

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

Retrieve All Document Types

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

Example Request

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

Example Response (abridged)

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

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

Possible Errors

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

Version History

Since: v1.0 - Retrieve all document types.

Retrieve Document Type

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

Example Request

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

Example Response (abridged)

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

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

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

Possible Errors

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

Version History

Since: v1.0 - Retrieve document type.

Retrieve Document Subtype

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

Example Request

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

Example Response (abridged)

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

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

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

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

Possible Errors

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

Version History

Since: v1.0 - Retrieve document subtype.

Retrieve Document Classification

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

Example Request

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

Example Response (abridged)

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

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

Possible Errors

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

Version History

Since: v1.0 - Retrieve document classification.

Create Document

The API supports the following create document actions:

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

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

About Required & Editable Fields

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

To retrieve document fields in your vault:

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

About Default Field Values

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

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

For example:

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

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

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

About Document Templates

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

Create Document from Uploaded File

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

Method & Endpoint

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

Request Headers

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

Upload the Source File

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

Required Standard Fields

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

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

Additional Required & Editable Fields

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

Example Request

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

This example includes:

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

Example JSON Response

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

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

Possible Errors

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

Version History

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

Create Document from Template

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

Method & Endpoint

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

Request Headers

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

Select the Document Template

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

Required Standard Fields

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

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

Additional Required & Editable Fields

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

Example Request

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

This example includes:

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

Example JSON Response

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

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

Possible Errors

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

Version History

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

Create Content Placeholder Document

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

Method & Endpoint

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

Request Headers

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

Required Standard Fields

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

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

Additional Required & Editable Fields

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

Example Request

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

This example includes:

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

Example JSON Response

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

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

Possible Errors

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

Version History

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

Create Unclassified Document

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

Method & Endpoint

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

Request Headers

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

Upload the Source File

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

Required Standard Fields

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

Field Name Description
type__v Set the document type to "Undefined".
lifecycle__v Set the document lifecycle to "Unclassified".

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

  • product__v
  • study__v
  • study_country__v
  • site__v

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

Example (All vaults)

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

Example (eTMF vaults)

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

Response

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

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

Possible Errors

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

Version History

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

Create CrossLink Document

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

Method & Endpoint

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

Request Headers

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

Required Standard Fields

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

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

Optional Standard Fields

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

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

Additional Required & Editable Fields

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

Example Request

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

This example includes:

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

Example JSON Response

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

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

Possible Errors

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

Version History

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

Create Multiple Documents

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

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

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

Headers

Name Description
Content-Type text/csv
Accept application/json (default) or text/csv

Body Parameters

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

Request

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

Response

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

Retrieve Documents

The following rules govern document retrieval:

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

Retrieve All Documents

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

Example Request

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

Example Response (abridged)

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

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

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

Limit, Sort, Paginate, and Search Results

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Possible Errors

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

Version History

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

Retrieve Document

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

Example Request

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

Example Response

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

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

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

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

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

Possible Errors

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

Version History

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

Retrieve All Document Versions

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

Example Request

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

Example Response

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

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

Possible Errors

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

Version History

Since: v1.0 - Retrieve all document versions.

Retrieve Document Version

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

Example Request

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

Example Response (abridged)

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

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

Possible Errors

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

Version History

Since: v1.0 - Retrieve document version.

Retrieve Document File

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

Example Request

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

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

Example Request

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

Example Response

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

Example Response Header

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

Possible Errors

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

Version History

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

Retrieve Document Version File

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

Example Request

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

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

Example Request

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

Example Response

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

Example Response Header

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

Possible Errors

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

Version History

Since: v1.0 - Retrieve document version file.

Retrieve Document Version Thumbnail File

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

Example Request

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

Example Response

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

Possible Errors

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

Version History

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

Update Documents

Update Document

Method & Endpoint

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

Request Headers

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

Request Parameters

  • {ID} - The document id field value.

Example Request

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

Example Response

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

Version History

Available in API v2.0 or later.

Update Multiple Documents

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

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

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

Headers

Name Description
Content-Type text/csv or application/x-www-form-urlencoded
Accept application/json (default) or text/csv

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.

Name Description
id ID of the document to update

Download Input File

Example Request

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

Example Response

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


Reclassify Document

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

Learn more about:

About this Request

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

Method & Endpoint

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

Request Headers

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

Request Parameters

  • {ID} - The document id field value.

Input Requirements

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

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

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

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

Example Request

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

Example Response

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

Version History

Available in API v8.0 or later.


Update Document Version

Method & Endpoint

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

Request Headers

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

Request Parameters

  • {ID} - The document id field value.
  • {MAJOR_VERSION} - The document major_version_number__v field value.
  • {MINOR_VERSION} - The document minor_version_number__v field value.

Example Request

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

Example Response

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

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

Version History

Available in API v2.0 or later.

Create New Document Draft Version

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

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

Request Parameters

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

Example Response

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

Possible Errors

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

Version History

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

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

Create Multiple Document Versions

Create or add document versions in bulk.

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

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

Headers

Name Description
Content-Type text/csv
Accept application/json (default) or text/csv

Body Parameters

Name Description
file The filepath of your source file. If the current version of the document includes a source file, you must include a source file for any past versions. The maximum allowed file size is 4GB.
id The system-assigned document ID of the document to delete.
external_id__v Optional: Instead of id, you can use this user-defined document external ID.
name__v Enter a name for the new document. This may be the same name as the existing document/version or a different name.
type__v Enter the name of the document type to assign to the new document.
subtype__v Enter the name of the document subtype (if one exists on the document type).
classification__v Enter the name of the document classification (if one exists on the document subtype).
lifecycle__v Enter the name of the document lifecycle to assign to the new document. This may be the same lifecycle as the existing document/version or a different lifecycle.
major_version_number__v Enter the major version number to assign to the new document version. This must be a version that does not yet exist on the document being updated.
minor_version_number__v Enter the minor version number to assign to the new document. This must be a version that does not yet exist on the document being updated.
status__v Enter a status for the new document, e.g., Draft, In Review, Approved, etc.
product__v Example: This is an example object reference field. To assign value for this field type, include either the document field name product__v or the document field name plus the name field on the object product__v.name__v.

Query String Parameters

Name Description
idParam If you're identifying documents in your input by their external ID, add idParam=external_id__v to the request endpoint.

Download Input File

Request

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

Response

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

Delete Documents

Delete Document

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

Example Request

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

Example Response

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

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

Possible Errors

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

Version History

Since: v1.0 - Delete document.

Delete Document Version

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

Example Request

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

Example Response

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

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

Possible Errors

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

Version History

Since: v1.0 - Delete document version.

Document Locks (Check-Out)

Retrieve Document Lock Metadata

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

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

Example Request

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

Example Response

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

Response Details

Field Description
name The "name" of the field used in the API. These include locked_by__v, locked_date__v, etc.
label The "label" of the field used in the UI. These include "Locked By", "Locked Date", etc.
type The "type" of field. These include "ObjectReference", "DateTime", etc.
scope The "scope" of the field. This value is "Lock" for all fields.
required Indicates if the field is required.
systemAttribute Boolean (true/false) field which indicates if the field is a standard (system-managed) field, i.e., not editable by the user.
editable Boolean (true/false) field which indicates if the field can be set or changed by the user, i.e., not system-managed.
setOnCreateOnly Boolean (true/false) field which indicates if the field can only be set during creation of a new document.
objectType When the field type is "ObjectReference", this field indicates the object which is being referenced.
hidden Boolean (true/false) field which indicates if the field is "hidden" (not available).

Possible Errors

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

Version History

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

Create Document Lock

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

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

Example Request

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

Example Response

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

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

Possible Errors

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

Version History

Since: v1.0 - Create document lock.

Retrieve Document Lock

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

Example Request

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

Example Response

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

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

Response Details

Field Description
locked_by__v User ID of the user who locked (checked out) the document.
locked_date__v Timestamp when the document was locked (checked out).

Possible Errors

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

Version History

Since: v1.0 - Retrieve document lock.

Delete Document Lock (Undo Check-Out)

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

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

Example Request

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

Example Response

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

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

Possible Errors

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

Version History

Since: v1.0 - Delete document lock.

Document Renditions

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

Learn more about Document Renditions in Vault Help.

Retrieve Document Renditions

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

Example Request

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

Where "534" is the document id.

Example Response

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

Response Details

Fields Description
renditionTypes[n] List of all rendition types configured for the specified document.
renditions[n] List of renditions available for the specified document and the endpoint URL to retrieve them.

Possible Errors

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

Version History

Since: v1.0 - List document renditions.

Retrieve Document Version Renditions

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

Example Request

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

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

Example Response

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

Possible Errors

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

Version History

Since: v7.0 - List document version renditions.

Retrieve Document Rendition File

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

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

Example Request

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

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Version History

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

Retrieve Document Version Rendition File

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

Example Request

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

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Version History

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

Upload Document Rendition

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

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

Example Request

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

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Version History

Since: v1.0 - Upload document rendition.

Upload Multiple Document Renditions

Add document renditions in bulk.

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

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

Headers

Name Description
Content-Type text/csv
Accept application/json (default) or text/csv

Body Parameters

Name Description
file The file path of your source files.
id The system-assigned document ID of the document to delete.
external_id__v Optional: Instead of id, you can use this user-defined document external ID.
rendition_type__v Document rendition type to assign to the new rendition. Only one rendition of each type may exist on each document.
major_version_number__v Major version number to assign to the new document rendition.
minor_version_number__v Minor version number to assign to the new document rendition.

Query String Parameters

Name Description
idParam If you're identifying documents in your input by their external ID, add idParam=external_id__v to the request endpoint.

Download Input File

Request

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

Response

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

Upload Document Version Rendition

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

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

Example Request

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

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Version History

Since: v7.0 - Upload document version rendition.

Replace Document Rendition

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

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

Example Request

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

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Version History

Since: v7.0 - Replace document rendition.

Replace Document Version Rendition

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

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

Example Request

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

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Version History

Since: v7.0 - Replace document version rendition.

Delete Document Rendition

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

Example Request

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

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Version History

Since: v7.0 - Delete document rendition.

Delete Document Version Rendition

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

Example Request

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

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Version History

Since: v7.0 - Delete document version rendition.

Document Attachments

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

Learn more about Document Attachments in Vault Help.

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

Determine if a Document has Attachments

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

Example Request

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

Example Response (abridged)

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

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to retrieve a document {ID} which does not exist.

Version History

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

List Document Attachments

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

Example Request

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

Example Response

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

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to retrieve attachments from a document {ID} which does not exist.

Version History

Since: v12.0 - List document attachments.

Retrieve Document Attachment Metadata

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

Example Request

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

Example Response

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

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

Vault Document Attachments include the following fields (metadata):

Field Description
id ID of the attachment. This is set by the system.
version__v Version of the attachment. 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.
filename__v File name of the attachment.
description__v Optional description added to the attachment. You can add descriptions up to 1000 characters in length.
format__v File format of the attachment. You can add any type of file as an attachment.
size__v File size of the attachment. You can add up to 50 attachments to a document; each must be under 2GB.
md5checksum__v MD5 checksum value calculated for the attachment. To avoid creating identical versions, Vault assigns each a checksum value. When you add an attachment with the same file name and checksum value, Vault ignores the new file and does not version the existing attachment.
created_by__v User ID of the person who created the attachment.
created_date__v Date the attachment was created.
versions[n] List of links to earlier versions of the attachment.

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to retrieve attachments from a document {ID} which does not exist.
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to retrieve metadata from an attachment {ID} which does not exist on the specified document.

Version History

Since: v12.0 - Retrieve document attachment metadata.

List Document Attachment Versions

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

Example Request

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

Example Response

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

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to retrieve attachments from a document {ID} which does not exist.
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to retrieve metadata from an attachment {ID} which does not exist on the specified document.
MALFORMED_URL The resource [{ID}/version/{VERSION}] does not exist. The user is attempting to retrieve metadata from a specific version {VERSION} of an attachment {ID} which does not exist on the specified document. The attachment {ID} exists but the version number {VERSION} does not.

Version History

Since: v12.0 - List document attachment versions.

Retrieve Document Attachment Version Metadata

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

Example Request

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

Example Response

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to retrieve attachments from a document {ID} which does not exist.
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to retrieve metadata from an attachment {ID} which does not exist on the specified document.
MALFORMED_URL The resource [{ID}/version/{VERSION}] does not exist. The user is attempting to retrieve metadata from a specific version {VERSION} of an attachment {ID} which does not exist on the specified document. The attachment {ID} exists but the version number {VERSION} does not.

Version History

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

Retrieve Document Attachment File

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

Example Request

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

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

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

Example Response Header

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to retrieve an attachment from a document {ID} which does not exist.
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to retrieve an attachment {ID} which does not exist on the specified document.
MALFORMED_URL The resource does not contain attachments. The user is attempting to retrieve an attachment from a document which does not have any attachments.

Version History

Since: v12.0 - Retrieve document attachment file.

Retrieve Document Attachment Version File

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

Example Request

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

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

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

Example Response Header

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to retrieve an attachment from a document {ID} which does not exist.
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to retrieve an attachment {ID} which does not exist on the specified document.
MALFORMED_URL The resource [{ID}/version/{VERSION}] does not exist. The user is attempting to retrieve a specific version {VERSION} of an attachment {ID} which does not exist on the specified document. The attachment {ID} exists but the version number {VERSION} does not.
MALFORMED_URL The resource does not contain attachments. The user is attempting to retrieve an attachment from a document which does not have any attachments.

Version History

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

Retrieve All Document Attachment Files

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

Example Request

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

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

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

Example Response Header

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to retrieve an attachment from a document {ID} which does not exist.
MALFORMED_URL The resource does not contain attachments. The user is attempting to retrieve attachments from a document which does not have any attachments.

Version History

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

Delete Document Attachment

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS"
}

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to delete an attachment from a document {ID} which does not exist.
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to delete an attachment {ID} which does not exist on the specified document.

Version History

Since: v12.0 - Delete document attachment.

Delete Document Attachment Version

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS"
}

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to delete an attachment from a document {ID} which does not exist.
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to delete an attachment {ID} which does not exist on the specified document.

Version History

Since: v12.0 - Delete document attachment version.

Add Document Attachment

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

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

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

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

  • filename__v
  • format__v
  • size__v

Example Request

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

Example Response

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

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to add an attachment from a document {ID} which does not exist.
MALFORMED_URL The resource is not enabled for attachments. The user is attempting to add an attachment to a document for which attachments have not been enabled.
OPERATION_NOT_ALLOWED Cannot add an attachment : number of allowed attachments exceeds max [50]. The user is attempting to add an attachment to a document which already has the maximum number of allowed attachments (50).
OPERATION_NOT_ALLOWED Cannot add an attachment : maximum attachment file size exceeds max [{n}]. The user is attempting to add an attachment to a document which exceeds the maximum file size allowed for an attachment (2GB).

Version History

Since: v12.0 - Add document attachment.

Restore Document Attachment Version

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

Example Request

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

The parameter restore must be set to true

Example Response

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

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

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to restore an attachment to a document {ID} which does not exist.
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to restore an attachment {ID} which does not exist on the specified document.
MALFORMED_URL The resource [{ID}/version/{VERSION}] does not exist. The user is attempting to restore a specific version {VERSION} of an attachment {ID} to make it the latest version, but the attachment or version do not exist.
PARAMETER_REQUIRED Missing required parameter [restore]. The user is attempting to restore a specific version of an attachment but did not include the "restore" parameter.
MALFORMED_URL The resource is not enabled for attachments. The user is attempting to restore an attachment to a document for which attachments have not been enabled.

Version History

Since: v12.0 - Restore document attachment version.

Update Document Attachment Description

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

Request Parameters

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Error Type Error Message/Description
INVALID_DOCUMENT Document not found {ID}. The user is attempting to update an attachment on a document {ID} which does not exist.
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to update an attachment {ID} which does not exist on the specified document.
MALFORMED_URL The resource is not enabled for attachments. The user is attempting to add or restore an attachment to a document for which attachments have not been enabled.
INVALID_DATA Invalid value [{value}] specified for parameter [description__v] : string exceeds max length [1000]. The user is attempting to update the attachment description when the description exceeds the maximum character length (1000)

Version History

Since: v12.0 - Update document attachment description.

Document Annotations

Learn about Document Annotations in Vault Help.

Retrieve Document Annotations

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

Example Request

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

Example 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.

Possible Errors

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

Version History

Since: v12.0 - Retrieve document annotations.

Retrieve Document Version Annotations

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

Example Request

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

Example 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.

Possible Errors

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

Version History

Since: v12.0 - Retrieve document version annotations.

Upload Document Annotations

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

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "OK",
    "replies": 0,
    "failures": 0,
    "new": 0
}

On success, Vault uploads the file and its annotations.

Possible Errors

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

Error Type Error Message/Description
OPERATION_NOT_ALLOWED Cannot import annotations : no annotations previously exported for document.

Version History

Since: v12.0 - Upload document annotations.

Upload Document Version Annotations

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

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

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-F file=@my_document.pdf \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/548/versions/2/1/annotations

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "OK",
    "replies": 0,
    "failures": 0,
    "new": 0
}

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

Possible Errors

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

Error Type Error Message/Description
OPERATION_NOT_ALLOWED Cannot import annotations : no annotations previously exported for document.

Version History

Since: v12.0 - Upload document version annotations.

Document Relationships

Document relationships create a connection between two documents. For example, you could create relationships on a promotional piece to connect documents like drug study results. In that example, the relationship type might be called "Supporting Studies". Vault includes standard relationship types, but does not currently support custom relationship types.

Note that, unlike document link annotations, relationships do not have a specific location in either the source document or the targeted document. They may or may not be specific to a single version of the source or target document.

Depending on your vault's configuration, you may have several standard, system-managed relationship types.

Learn more about Document Relationships in Vault Help.

Retrieve Document Relationships

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

Example Request

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

Example Response (abridged)

{
    "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": "crosslink_document_latest__v",
            "label": "CrossLink Latest Bindings",
            "sourceDocVersionSpecific": true,
            "targetDocVersionSpecific": false,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Template Fragment",
                    "value": "template_fragment__v"
                },
                ...
            ]
        },
        {
            "value": "references__vs",
            "label": "Linked Documents",
            "sourceDocVersionSpecific": true,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                ...
                {
                    "label": "Resource",
                    "value": "resources__c"
                },
                {
                    "label": "Master Email Fragment",
                    "value": "master_email_fragment__v"
                },
                ...
            ]
        },
        {
            "value": "crosslink_document_latest_steady_state__v",
            "label": "CrossLink Latest Steady State Bindings",
            "sourceDocVersionSpecific": true,
            "targetDocVersionSpecific": false,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                ...
                {
                    "label": "Promotional Piece",
                    "value": "promotional_piece__vs"
                },
                {
                    "label": "Email Fragment",
                    "value": "email_fragment__v"
                },
                ...
            ]
        },
        {
            "value": "basedon__vs",
            "label": "Based on",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                ...
                {
                    "label": "Presentation",
                    "value": "engage_presentation__v"
                },
                {
                    "label": "Email Template",
                    "value": "email_template__v"
                },
                ...
        {
            "value": "related_claims__vs",
            "label": "Related Claims",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": false,
            "system": false,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Claim",
                    "value": "claim__vs"
                }
            ]
        },
        {
            "value": "supporting_documents__vs",
            "label": "Supporting Documents",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": false,
            "system": false,
            "singleUse": false,
            "targetDocumentTypes": [
                ...
                {
                    "label": "Reference Document",
                    "value": "reference_document__vs"
                },
                {
                    "label": "Multichannel Slide",
                    "value": "slide__v"
                },
                ...
            ]
        },
        {
            "value": "crosslink_document_static__v",
            "label": "CrossLink Static Bindings",
            "sourceDocVersionSpecific": true,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                ...
                {
                    "label": "Compliance Package",
                    "value": "compliance_package__v"
                },
                {
                    "label": "Undefined",
                    "value": "undefined__v"
                }
            ]
        },
        {
            "value": "related_pieces__vs",
            "label": "Related Pieces",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": false,
            "system": false,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Promotional Piece",
                    "value": "promotional_piece__vs"
                }
            ]
        }
    ]
}

The abridged response above shows the metadata for the relationship type configured for the specified document promotional_piece__vs.

Response Details

Relationship Field Description
properties [n] List of relationship fields that apply to all relationship types.
name The "name" of the field. This is the primary method of identifying the relationship field in the API.
type The "type" of field. Relationship field types include "id", "String", "Integer", "DateTime", "ObjectReference", etc.
length Indicates the maximum character length of the field.
editable Boolean (true/false) field which indicates if the field can be set or changed by the user, i.e., not system-managed.
queryable Boolean (true/false) field which indicates if the field can be searched.
required Boolean (true/false) field which indicates if the field is required when creating a new relationship.
multivalue Boolean (true/false) field which indicates if the field can include multiple values. This is analogous to repeating document fields.
OnCreateEditable Boolean (true/false) field which indicates if the field can only be set during creation of a new relationship.
relationshipTypes [n] List of relationship types available for the specified document type. These include all available target document types for each relationship type.
value The "value" of the relationship type used in the API. These include references__vs, supporting_documents__vs, related_pieces__vs, etc.
label The "label" of the relationship type used in the UI. These include "References", "Supporting Documents", "Related Pieces", etc.
sourceDocVersionSpecific Boolean (true/false) field which indicates if the "source document" in the relationship is version specific.
sourceDocVersionSpecific Boolean (true/false) field which indicates if the "target document" in the relationship is version specific.
system Boolean (true/false) field which indicates if the relationship type is a standard (system-managed).
singleUse Boolean (true/false) field wich indicates if the relationship type can only be used once for each document.
targetDocumentTypes [n] List of document types which are valid as target documents for the relationship type. Targets can also include document attachments attachment__v.
targetDocumentTypes: label The "label" of the document type used in the UI. For example: "Promotional Piece", "Reference Document", etc.
targetDocumentTypes: name The "name" of the document type used in the API. For example: promotional_piece__vs, reference_document__vs, etc.

Possible Errors

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

Version History

Since: v3.0 - Retrieve document relationships.

List Document Relationships

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": null,
    "errorCodes": null,
    "relationships": [
        {
            "relationship": {
                "id": 200,
                "source_doc_id__v": 534,
                "relationship_type__v": "supporting_documents__vs",
                "created_by__v": 46916,
                "created_date__v": "2015-03-20T20:44:56.000Z",
                "target_doc_id__v": 548
            }
        },
        {
            "relationship": {
                "id": 201,
                "source_doc_id__v": 534,
                "relationship_type__v": "supporting_documents__vs",
                "created_by__v": 46916,
                "created_date__v": "2015-03-20T21:01:53.000Z",
                "target_doc_id__v": 562
            }
        }
    ],
    "errorType": null
}

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

Response Details

Field Description
id Relationship ID
source_doc_id__v Source Document ID.
relationship_type__v Relationship Type.
target_doc_id__v Target Document ID.
target_major_version__v Target Document Major Version. A null value indicates that the relationship applies to all major versions of the target document.
target_minor_version__v Target Document Minor Version. A null value indicates that the relationship applies to all minor versions of the target document.
created_by__v Created By. The Vault User ID of the person who created the relationship.
created_date__v Created Date. The date and time when the relationship was created.

Possible Errors

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

Version History

Since: v3.0 - List document relationships.


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

Error Type Error Message/Description
INVALID_DATA Relationship already exists.
PARAMETER_REQUIRED Missing required parameter {PARAMETER}.
INVALID_DATA Document version major {MAJOR_VERSION_NUMBER}, minor {MINOR_NUMBER} not found for document {ID}.

Version History

Available in API v3.0 or later.

Retrieve Document Relationship

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": null,
    "errorCodes": null,
    "relationships": [
        {
            "relationship": {
                "id": 200,
                "source_doc_id__v": 534,
                "relationship_type__v": "supporting_documents__vs",
                "created_by__v": 46916,
                "created_date__v": "2015-03-20T20:44:56.000Z",
                "target_doc_id__v": 548
            }
        }
    ],
    "errorType": null
}

On success, Vault returns fields for the specified relationship.

Response Details

Field Description
id ID of the relationship.
source_doc_id__v ID of the source document.
relationship_type__v the name of relationship type.
target_doc_id__v Relationship target document ID.
target_major_version__v Major version of the target document. A null value indicates that the relationship applies to all major versions of the target document.
target_minor_version__v Minor version of the target document. A null value indicates that the relationship applies to all minor versions of the target document.
created_by__v ID of the user who created the relationship.
created_date__v Timestamp when the relationship was created.

Possible Errors

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

Version History

Since: v3.0 - Retrieve document relationship.

Delete Document Relationship

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

Example Request

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

Example Response

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

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

Possible Errors

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

Version History

Since: v3.0 - Delete document relationship.

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. These require separate application integrations are not available in all vaults.

Retrieve Document Event Types and Subtypes

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

Example Request

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

Example Response

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

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. The response above shows one document event distribution__v configured in our vault. This "Distribution Event" is configured with six document event "subtypes".

Possible Errors

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

Version History

Since: v6.0 - Retrieve document event types and subtypes.

Retrieve Document Event SubType Metadata

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "name": "approved_email__v",
    "label": "Approved Email",
    "properties": [
        {
            "name": "event_date__v",
            "label": "Event Date",
            "type": "DateTime",
            "queryable": true,
            "systemAttribute": true
        },
        {
            "name": "document_id__v",
            "label": "Document ID",
            "type": "ObjectReference",
            "objectType": "Documents",
            "queryable": true
        },
        {
            "name": "major_version_number__v",
            "label": "Document Major Version Number",
            "type": "Number",
            "queryable": true
        },
        {
            "name": "minor_version_number__v",
            "label": "Document Minor Version Number",
            "type": "Number",
            "queryable": true
        },
        {
            "name": "triggered_by__v",
            "label": "User ID",
            "type": "ObjectReference",
            "objectType": "Users",
            "queryable": true,
            "systemAttribute": true
        },
        {
            "name": "event_type__v",
            "label": "Event Type",
            "type": "String",
            "required": true,
            "queryable": true
        },
        {
            "name": "event_subtype__v",
            "label": "Event Subtype",
            "type": "String",
            "required": true,
            "queryable": true
        },
        {
            "name": "classification__v",
            "label": "Event Classification",
            "type": "String",
            "values": [
                {
                    "name": "distribute__v",
                    "label": "Distribute"
                },
                {
                    "name": "view__v",
                    "label": "View"
                },
                {
                    "name": "download__v",
                    "label": "Download"
                }
            ],
            "required": true,
            "queryable": true
        },
        {
            "name": "external_id__v",
            "label": "External ID",
            "type": "String",
            "required": true,
            "queryable": true
        },
        {
            "name": "user_email__v",
            "label": "User Email",
            "type": "String",
            "required": true,
            "queryable": true
        },
        {
            "name": "document_title__v",
            "label": "Document Title",
            "type": "String",
            "queryable": true,
            "systemAttribute": true
        },
        {
            "name": "document_number__v",
            "label": "Document Number",
            "type": "String",
            "queryable": true,
            "systemAttribute": true
        },
        {
            "name": "document_name__v",
            "label": "Document Name",
            "type": "String",
            "queryable": true,
            "systemAttribute": true
        }
    ]
}

On success, Vault returns all metadata for the specified event subtype.

Possible Errors

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

Version History

Since: v6.0 - Retrieve document event subtype metadata.

Create Document Event

Send a POST request to the /objects/documents/{ID}/versions/{MAJOR}/{MINOR}/events endpoint.

Request Parameters

Provide the name-value pairs consisting of all required fields and the values for the event subtype specified. The required fields are obtained from the event subtype metadata (described above). You can use either field value names or labels for the event_type__v, event_subtype__v and classification__v field values in the request. The Approved Email event subtype metadata shows the five event fields below as required.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-F "event_type__v=distribution__v" \
-F "event_subtype__v=approved_email__v" \
-F "classification__v=download__v" \
-F "external_id__v=1234"
-F "quinntaylor@myemail.com"
https://myvault.veevavault.com/api/v12.0/objects/documents/534/versions/2/0/events

Example Response

{
    "responseStatus": "SUCCESS"
}

On success, Vault logs the document event.

Possible Errors

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

Error Type Error Message/Description
INSUFFICIENT_ACCESS You do not have permission to log an event of specified type.
INVALID_DATA The value specified for the parameter is invalid (i.e. validation error). As part of the error, a list of all fields which have an error will be returned.
PARAMETER_REQUIRED A required parameter is not provided. As part of the error, a list of all missing parameters will be returned.
METHOD_NOT_SUPPORTED The URL is constructed with an invalid event type. This also includes other endpoint related errors.

Version History

Since: v6.0 - Create document event.

Retrieve Document Events

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

You can include one or more queryable event fields and associated values in the request parameters to filter the response. For example, specifying event_type__v=Distribution will return only distribution events; specifying event_type__v=Distribution&event_subtype__v=Approved Email will return only distribution events generated for/by Approved Email.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "name": "download__v",
            "label": "Approved Email Download",
            "properties": {
                "event_date__v": "2015-03-20T22:06:40.000Z",
                "document_id__v": 534,
                "major_version_number__v": 2,
                "minor_version_number__v": 0,
                "triggered_by__v": 46916,
                "event_type__v": "Distribution Event",
                "event_subtype__v": "Approved Email",
                "classification__v": "Download",
                "external_id__v": "1234",
                "user_email__v": "quinntaylor@myemail.com",
                "event_modified_by__v": 46916,
                "event_modified_date__v": "2015-03-20T22:06:40.000Z",
                "document_number__v": "REF-0059",
                "document_name__v": "Wonderdrug Information"
            }
        }
    ]
}

On success, Vault returns the list of event objects, each containing the fields as defined by the metadata for its event type. Null and/or false valued fields are omitted from the response.

Possible Errors

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

Version History

Since: v6.0 - Retrieve document events.

Document Tokens

The Vault Document Tokens API allows you to generates document access tokens needed by the external viewer to view documents outside of Vault.

Request

Send POST to /api/{version}/objects/documents/tokens

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Document IDs:

Required - Include the docIds request parameter with a comma-separated string of document id values. This will generate tokens for each document. For example: docIds=101,102,103,104

Token Expiration Date:

Optional - Include the expiryDateOffset request parameter set to the number of days after which the tokens will expire and the documents will no longer be available in the viewer. If not specified, the tokens will expire after 10 years by default.

Download Option:

Optional - Include the downloadOption request parameter set to PDF, source, both, or none. These allow users viewing the document to be able to download a PDF version or source version (Word, PPT, etc.) of the document. If not specified, the download options default to those set on each document.

Distribution Channel:

Optional - Include the channel request parameter set to the website object record id value that corresponds to the distribution channel where the document is being made available.

Token Groups:

Optional - Include the tokenGroup request parameter. This only required if you want to group together generated tokens for multiple documents in order to display the documents being referenced in the same viewer. This value accepts strings of alphanumeric characters (a-z, A-Z, 0-9, and single consecutive underscores) up to 255 characters in length.

The token that is passed as a URL parameter to the External Viewer is the primary token and the document it references will be displayed normally. However, any additional documents that have tokens generated with the same case-sensitive tokenGroup string will be displayed in a sidebar of the viewer.

The order of documents in the sidebar depends on the order in which the tokens are generated. If multiple tokens are generated with one request, the documents will be ordered top-to-bottom based on the order they are passed to the docIds parameter.

For example: If passing the parameters docIds=101,102,103,104 and tokenGroup=group_1 with the request, the top-to-bottom order in the sidebar will be documents 101, 102, 103, 104. If a new request is then made with the parameters docIds=105 and tokenGroup=group_1, document 105 will be added below document 104 in the previous list.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIds=101,102,103,104" \
-d "expiryDateOffset=90" \
-d "downloadOption=PDF" \
-d "channel=00W000000000301" \
https://myvault.veevavault.com/api/v12.0/objects/documents/tokens

Response

{
    "responseStatus": "SUCCESS",
    "tokens": [
        {
            "document_id__v": 101,
            "token__v": "3003-cb6e5c3b-4df9-411c-abc2-6e7ae120ede7"
        }
        {
            "document_id__v": 102,
            "token__v": "3003-1174154c-ac8e-4eb9-b453-2855de273bec"
        },
        {
            "document_id__v": 103,
            "token__v": "3003-51ca652c-36d9-425f-894f-fc2f42601fa9"
        },        
        {
            "document_id__v": 104,
            "errorType": "OPERATION_NOT_ALLOWED",
            "errors": [
                {
                    "type": "INVALID_DOCUMENT",
                    "message": "Document not found [104]."
                }
            ]
        }
    ]
}

Details

In the example above, tokens are generated for the first three documents. The fourth document could not be found. This indicates either an incorrect document id or that the specified document is a binder.

History

Since v12

Binders

Retrieve Binders

Retrieve All Binders

Send a GET request to the /api/{VERSION}/objects/documents endpoint and finding documents with the field binder__v set to true.

Use the document pseudo-field binder__v to determine whether a returned document is a "regular" document or a binder. A value of true means the document is a binder. A value of false or absense of the binder__v field means the document is a document. If it is a binder, the binder node structure is not listed as part of the response and must be determined through the Retrieve Binder API call below.

The response shown below is from a GET api/{VERSION}/objects/documents request. The first document is a binder. The second document is a document.

    {
        "document": {
            "id": 510,
            "binder__v": true,
            ...

        "document": {
            "id": 520,
            "binder__v": false,
            ...

Alternatively, you can use the Query API to find just binders. Learn more in the Vault Query API Overview article.

Possible Errors

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

Version History

Since: v1.0 - Retrieve all documents.
v5.0 - Response distinguishes between documents and binders.

Retrieve Binder

You can retrieve all fields for a specific binder, including the first level node "tree" structure by sending a GET request to the /api/{VERSION}/objects/binders/{ID} endpoint.

Example Request (Retrieve First Binder Level (Nodes))

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "document": {
        "id": 566,
        "binder__v": true,
        ...
        "major_version_number__v": 0,
        "minor_version_number__v": 3,       
        "status__v": "Draft",
        "product__v": [
            "1357662840210",
            "1357662840255"
        ],   
        "name__v": "VeevaProm Patient Education Packet",
        "lifecycle__v": "Binder Lifecycle",        
        "type__v": "Promotional Piece",
        "subtype__v": "Healthcare Practitioner Resources",
        ...
    },
    "versions": [
        {
            "number": "0.1",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/1"
        },
        {
            "number": "0.2",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/2"
        },
        {
            "number": "0.3",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/3"
        }
    ],
    "binder": {
        "nodes": [
            {
                "properties": {
                    "document_id__v": 567,
                    "name__v": "Introducing VeevaProm and VeevaProm XR",
                    "order__v": 1,
                    "type__v": "document",
                    "id": "1427232743506:-827816211",
                    "parent_id__v": "rootNode"
                }
            },
            {
                "properties": {
                    "section_number__v": "1",
                    "name__v": "Level A VeevaProm",
                    "order__v": 2,
                    "type__v": "section",
                    "id": "1427232809771:1381853041",
                    "parent_id__v": "rootNode"
                }
            },
            {
                "properties": {
                    "section_number__v": "2",
                    "name__v": "Level A VeevaProm XR",
                    "order__v": 3,
                    "type__v": "section",
                    "id": "1427232821091:-101693304",
                    "parent_id__v": "rootNode"
                }
            }
        ]
    }
}

The response above shows many of the fields and field values for the binder id 566. Included in the response are all versions of the binder and the first level of "nodes". In this first level there is one document "document_id__v": 567 and two sections "section_number__v": "1" and "section_number__v": "2".

By default, the response includes only the first level of the binder section node structure. To retrieve all levels of the binder, include the depth parameter set to all. For example:

Example Request (Retrieve All Binder Levels (Nodes))

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566?depth=all

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "document": {
        "id": 566,
        "binder__v": true,
        ...
        "major_version_number__v": 0,
        "minor_version_number__v": 3,       
        "status__v": "Draft",
        "product__v": [
            "1357662840210",
            "1357662840255"
        ],   
        "name__v": "VeevaProm Patient Education Packet",
        "lifecycle__v": "Binder Lifecycle",        
        "type__v": "Promotional Piece",
        "subtype__v": "Healthcare Practitioner Resources",
        ...
    },
    "versions": [
        {
            "number": "0.1",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/1"
        },
        {
            "number": "0.2",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/2"
        },
        {
            "number": "0.3",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/3"
        }
    ],
    "binder": {
        "nodes": [
            {
                "properties": {
                    "document_id__v": 567,
                    "name__v": "Introducing VeevaProm and VeevaProm XR",
                    "order__v": 1,
                    "type__v": "document",
                    "id": "1427232743506:-827816211",
                    "parent_id__v": "rootNode"
                }
            },
            {
                "properties": {
                    "section_number__v": "1",
                    "name__v": "Level A VeevaProm",
                    "order__v": 2,
                    "type__v": "section",
                    "id": "1427232809771:1381853041",
                    "parent_id__v": "rootNode"
                },
                "nodes": [
                    {
                        "properties": {
                            "document_id__v": 568,
                            "name__v": "VeevaProm Presentation",
                            "order__v": 1,
                            "type__v": "document",
                            "id": "1427232745973:-39541070",
                            "parent_id__v": "1427232809771:1381853041"
                        }
                    },
                    {
                        "properties": {
                            "section_number__v": "1.1",
                            "name__v": "Level B VeevaProm Provider Info",
                            "order__v": 2,
                            "type__v": "section",
                            "id": "1427233015334:109650943",
                            "parent_id__v": "1427232809771:1381853041"
                        },
                        "nodes": [
                            {
                                "properties": {
                                    "document_id__v": 572,
                                    "name__v": "VeevaProm Indications",
                                    "order__v": 1,
                                    "type__v": "document",
                                    "id": "1427233653738:-1176103302",
                                    "parent_id__v": "1427233015334:109650943"
                                }
                            },
                            {
                                "properties": {
                                    "document_id__v": 573,
                                    "name__v": "VeevaProm Prescribing",
                                    "order__v": 2,
                                    "type__v": "document",
                                    "id": "1427233655331:-387828161",
                                    "parent_id__v": "1427233015334:109650943"
                                }
                            }
                        ]
                    },
                    {
                        "properties": {
                            "section_number__v": "1.2",
                            "name__v": "Level B VeevaProm Patient Info",
                            "order__v": 3,
                            "type__v": "section",
                            "id": "1427233029752:1294369759",
                            "parent_id__v": "1427232809771:1381853041"
                        },
                        "nodes": [
                            {
                                "properties": {
                                    "document_id__v": 570,
                                    "name__v": "VeevaProm Brochure",
                                    "order__v": 1,
                                    "type__v": "document",
                                    "id": "1427233644267:1540191912",
                                    "parent_id__v": "1427233029752:1294369759"
                                }
                            },
                            {
                                "properties": {
                                    "document_id__v": 571,
                                    "name__v": "VeevaProm FAQ",
                                    "order__v": 2,
                                    "type__v": "document",
                                    "id": "1427233648204:-1966500243",
                                    "parent_id__v": "1427233029752:1294369759"
                                }
                            }
                        ]
                    }
                ]
            },
            {
                "properties": {
                    "section_number__v": "2",
                    "name__v": "Level A VeevaProm XR",
                    "order__v": 3,
                    "type__v": "section",
                    "id": "1427232821091:-101693304",
                    "parent_id__v": "rootNode"
                },
                "nodes": [
                    {
                        "properties": {
                            "document_id__v": 569,
                            "name__v": "VeevaProm XR Presentation",
                            "order__v": 1,
                            "type__v": "document",
                            "id": "1427232741608:745551371",
                            "parent_id__v": "1427232821091:-101693304"
                        }
                    },
                    {
                        "properties": {
                            "section_number__v": "2.1",
                            "name__v": "Level B VeevaProm XR Provider Info",
                            "order__v": 2,
                            "type__v": "section",
                            "id": "1427233110708:1749668778",
                            "parent_id__v": "1427232821091:-101693304"
                        },
                        "nodes": [
                            {
                                "properties": {
                                    "document_id__v": 576,
                                    "name__v": "VeevaProm XR Indications",
                                    "order__v": 1,
                                    "type__v": "document",
                                    "id": "1427233651952:-586944478",
                                    "parent_id__v": "1427233110708:1749668778"
                                }
                            },
                            {
                                "properties": {
                                    "document_id__v": 577,
                                    "name__v": "VeevaProm XR Prescribing",
                                    "order__v": 2,
                                    "type__v": "document",
                                    "id": "1427233650400:199208863",
                                    "parent_id__v": "1427233110708:1749668778"
                                }
                            }
                        ]
                    },
                    {
                        "properties": {
                            "section_number__v": "2.2",
                            "name__v": "Level B VeevaProm XR Patient Info",
                            "order__v": 3,
                            "type__v": "section",
                            "id": "1427233138010:-1403853102",
                            "parent_id__v": "1427232821091:-101693304"
                        },
                        "nodes": [
                            {
                                "properties": {
                                    "document_id__v": 574,
                                    "name__v": "VeevaProm XR Brochure",
                                    "order__v": 1,
                                    "type__v": "document",
                                    "id": "1427233642988:2129350736",
                                    "parent_id__v": "1427233138010:-1403853102"
                                }
                            },
                            {
                                "properties": {
                                    "document_id__v": 575,
                                    "name__v": "VeevaProm XR FAQ",
                                    "order__v": 2,
                                    "type__v": "document",
                                    "id": "1427233641730:-1379463219",
                                    "parent_id__v": "1427233138010:-1403853102"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

On success, Vault retrieves the fields of a binder (in exactly the same format as the "Retrieve Document" API) and retrieves the components of the binder in a hierarchical structure clearly showing the parent-child relationships for each item and maintaining the specific order of the objects in each level.

Response Details

For each node in a binder, the API returns the following fields:

Field Description
nodes [n] List of all nodes (documents and sections) at each level in the binder.
properties [n] List of all properties associated with each document or section node.
order__v Order of the document or section within the binder or within another section of the binder.
section_number__v Optional number which can be added to each section.
type Type of node (document or section).
document_id__v The document ID of the document in the binder. This is the same as the document's actual document id
id The document ID or section ID specific to the binder. For documents, this is different from the document's actual document id.
parent_id__v Section ID of the parent node, e.g., "rootNode".
name__v Name of the document or section. For sections, this is the name of the "subfolder" seen in the binder hierarchy in the UI.
major_version_number__v If the document binding rule is "specific", this is major version number of the document.
minor_version_number__v If the document binding rule is "specific", this is minor version number of the document.

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder. Verify that you have entered the correct binder id and not a document id.

Version History

Since: v5.0

Retrieve All Binder Versions

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "versions": [
        {
            "number": "0.1",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/1"
        },
        {
            "number": "0.2",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/2"
        },        
        {
            "number": "0.3",
            "value": "https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/3"
        }
    ]
}

Binders have versions just like regular documents. On success, Vault returns a list of the available versions for the specified binder.

Possible Errors

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

Version History

Since: v5.0

Retrieve Binder Version

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

Example Request

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "document": {
        "id": 566,
        "binder__v": true,
        ...

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder. Verify that you have entered the correct binder id and not a document id.

Version History

Since: v5.0


Create Binders

Create Binder

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

Request Parameters

  • Set the HTTP Request Header Content-Type to application/x-www-form-urlencoded.
  • All required binder (document) fields must be included in the request.
  • When creating a binder, no file is included in the request.
  • Refer to the next section to create a binder from a template.

Optional: When creating a binder, the binder metadata is indexed synchronously by default. To process the indexing asynchronously, include a query parameter async set to true (objects/binders?async=true). This helps speed up the response time from Vault when processing large amounts of data.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-d "name__v=Wonderdrug Compliance Package" \
-d "type__v=Compliance Package" \
-d "subtype__v=Professional" \
-d "lifecycle__v=Binder Lifecycle" \
-d "product__v=1357662840293" \
-d "major_version_number__v=0" \
-d "minor_version_number__v=1" \
https://myvault.veevavault.com/api/v12.0/objects/binders

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Successfully created binder.",
    "id": 563
}

Possible Errors

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

Error Type Error Message/Description
PARAMETER_REQUIRED Missing required parameter {field_name}. A required field or field value was not included in the request.
INVALID_DATA Invalid values {field_value} specified for parameter {field_name}. The value entered for a specified document field does not match with available values.

Version History

Since: v1.0 - Create binder.
v7.0 - Asynchronous indexing supported.

Create Binder from Template

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

Request Parameters

  • Set the HTTP Request Header Content-Type to application/x-www-form-urlencoded.
  • All required binder (document) fields must be included in the request. See below.
  • When creating a binder, no file is included in the request.
  • Include the parameter fromTemplate and specify the name of the template as returned from the document metadata as shown below. Only templates of "kind": binder are allowed.

Example Request & Abridged Response (Find Available Binder Templates)

Since we're creating a new binder with the document type "Compliance Package" and subtype "Professional", we need to find the available templates in the type/subtype metadata:

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

Example Response (abridged)

    ...
    "templates": [
        {
            "label": "Compliance Package Template",
            "name": "compliance_package__v",
            "kind": "binder",
            "definedIn": "compliance_package__v",
            "definedInType": "type"
        },
        {
            "label": "eCTD Compliance Package",
            "name": "ectd_compliance_package_template__v",
            "kind": "binder",
            "definedIn": "compliance_package__v",
            "definedInType": "type"
        }
        ...

The abridged response above shows the "templates" section of the type/subtype response. There are two available templates we can use to create this binder (each template has the "kind": binder). Both are defined on the compliance_package__v document type. We'll use the binder template ectd_compliance_package_template__v to create our new binder as shown below.

Example Request (Create Binder from Template)

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-d "fromTemplate=ectd_compliance_package_template__v" \
-d "name__v=Cholecap eCTD Compliance Package" \
-d "type__v=Compliance Package" \
-d "subtype__v=Professional" \
-d "lifecycle__v=Binder Lifecycle" \
-d "product__v=1357662840171" \
-d "major_version_number__v=0" \
-d "minor_version_number__v=1" \
https://myvault.veevavault.com/api/v12.0/objects/binders

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Successfully created binder.",
    "id": 565
}

Possible Errors

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

Error Type Error Message/Description
PARAMETER_REQUIRED Missing required parameter {field_name}. A required document field or field value was not included in the request.
INVALID_DATA Invalid values {field_value} specified for parameter {field_name}. The value entered for a specified document field does not match with available values.

Version History

Since: v1.0 - Create binder.
v5.0 - Create binder from template.
v7.0 - Asynchronous indexing supported.


Update Binders

Update Binder

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

Request Parameters

  • Set the HTTP Request Header Content-Type to application/x-www-form-urlencoded.
  • Only editable binder (document) fields may be included in the request.
  • Refer to the next section to reclassify a binder.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-d "audience__vs=Healthcare Provider" \
-d "country__v=1357662840400" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566

Example Response

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

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder. Verify that you have entered the correct binder id and not a document id.

Version History

Since: v5.0

Reclassify Binder

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

Learn more about:

About this Request

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

Method & Endpoint

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

API Request Headers

  • Set the HTTP Request Header Content-Type to application/x-www-form-urlencoded (Form Data input).
  • JSON is the default response format. To request a CSV response, set the HTTP Request Header Accept to text/csv.

Request Parameters

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

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

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

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

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-d "reclassify=true" \
-d "type__v=Claim" \
-d "lifecycle__v=Binder Lifecycle" \
https://myvault.veevavault.com/api/v12.0/objects/binders/776

Example Response

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

Possible Errors

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

Version History

Available in API v8.0 or later.

Update Binder Version

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

Request Parameters

  • Set the HTTP Request Header Content-Type to application/x-www-form-urlencoded.
  • Only editable binder (document) fields may be included in the request.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-F "audience__vs=Healthcare Provider" \
-F "country__v=1357662840400" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/0/1

Example Response

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

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder. Verify that you have entered the correct binder id and not a document id.

Version History

Since: v5.0

Create New Binder Draft Version

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "New draft successfully created",
    "major_version_number__v": 0,
    "minor_version_number__v": 4
}

Possible Errors

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

Error Type Error Message/Description
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. This error condition occurs when the user does not have permissions to create a draft.
INVALID_BINDER Binder not found {ID}. The error condition occurs when the user specifies a binder {ID} that does not exist.

Version History

Since: v5.0 - Update binder fields.
v7.0 - Create a new binder draft supported.


Delete Binders

Delete Binder

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

Example Request

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

Example Response

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

Possible Errors

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

Error Type Error Message/Description
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. This error condition occurs when the user does not have permissions to delete a binder.
INVALID_BINDER Binder not found {ID}. The error condition occurs when the user specifies a binder {ID} that does not exist.

Version History

Since: v5.0


Delete Binder Version

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

Note: If a binder has only one version, you cannot delete it.

Example Request

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

Example Response

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

Possible Errors

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

Error Type Error Message/Description
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. This error condition occurs when the user does not have permissions to delete a binder.
INVALID_BINDER Binder not found {ID}. The error condition occurs when the user specifies a binder {ID} that does not exist.

Version History

Since: v5.0


Binder Relationships

Retrieve Binder Relationship

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

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/3/relationships/202

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": null,
    "errorCodes": null,
    "relationships": [
        {
            "relationship": {
                "source_doc_id__v": 566,
                "relationship_type__v": "supporting_documents__vs",
                "created_date__v": "2015-03-24T22:37:20.000Z",
                "id": 202,
                "target_doc_id__v": 254,
                "created_by__v": 46916
            }
        }
    ],
    "errorType": null
}

Response Details

Field Description
id Relationship ID.
source_doc_id Document ID of the source document.
relationship_type__v Relationship type
created_by__v User ID of user who created the relationship
created_date__v Timestamp when the relationship was created
target_doc_id__v Document ID for target document
target_major_version__v Major version of the target document; null values indicate that the relationship applies to all major versions
target_minor_version__v Minor version of the target document; null values indicate that the relationship applies to all minor versions

Possible Errors

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

Version History

Since: v5.0 - Retrieve binder relationship.
v6.0 - The response no longer includes the target_major_version__v field for relationships that are not version specific.
v6.0 - The response now includes the created_by__v, created_date__v, and source_doc_id__v fields.

Create Binder Relationship

Send a POST request to the /api/{VERSION}/objects/binders/{ID}/versions/{MAJOR}/{MINOR}/relationships endpoint.

Request Parameters

  • Set the HTTP Request Header Content-Type to application/x-www-form-urlencoded.
  • Set the target_doc_id__v to the document id of the "target document" to which a relationship will be established with the binder.
  • Set the relationship_type__v to the field value of one of the desired relationshipTypes from the "Documents Relationships Metadata" call. See below.
  • [Optional] - If you're creating a relationship with a specific version of the target document, set the target_major_version__v to the major version number of the target document.
  • [Optional] - If you're creating a relationship with a specific version of the target document, set the target_minor_version__v to the minor version number of the target document.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-d "target_doc_id__v=13" \
-d "relationship_type__v=supporting_documents__vs" \
-d "target_major_version__v=0" \
-d "target_minor_version__v=1" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/3/relationships

Example Response

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

On success, Vault returns the relationship id of the newly created binder relationship.

Possible Errors

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

Version History

Since: v5.0

Delete Binder Relationship

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

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/4/relationships/202

Example Response

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

On success, Vault deletes the requested relationship and returns the relationship id of the deleted relationship.

Possible Errors

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

Version History

Since: v5.0


Binder Sections

Retrieve Binder Sections

Send a GET request to the /api/{VERSION}/objects/binders/{ID}/sections/{NODE_ID} endpoint.

If the {NODE_ID} is left blank in the endpoint, the sections directly linked to the top-level binder will be returned instead.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/sections/1427486900128:1467568099

The section Node ID is from the new section we created in the previous example.

Example Response

{
    "responseStatus": "SUCCESS",
    "node": {
        "properties": {
            "section_number__v": "1.3",
            "name__v": "VeevaProm Additional Information",
            "order__v": 4,
            "type__v": "section",
            "id": "1427486900128:1467568099",
            "parent_id__v": "1427232809771:1381853041"
        },
        "nodes": []
    }
}

On success, Vault returns the specified section including a list of all subsections and documents contained within the specified section Node ID. Since this Node ID was just created in the previous example, it has no subsections or documents. Compare this response to the Retrieve Binder (All Binder Level Nodes) Response above - This new node fits within parent node "Level A VeevaProm" at the root level and just below it's subsections "1.1" and "1.2". We've placed it in the third position (order). This is also shown in the example response below.

Response Details

For each node in a binder, the API returns the following fields:

Field Description
nodes [n] List of all nodes (documents and sections) at each level in the binder.
properties [n] List of all properties associated with each document or section node.
order__v Order of the document or section within the binder or within another section of the binder.
section_number__v Optional number which can be added to each section.
type Type of node (document or section).
document_id__v The document ID of the document in the binder. This is the same as the document's actual document id
id The document ID or section ID specific to the binder. For documents, this is different from the document's actual document id.
parent_id__v Section ID of the parent node, e.g., "rootNode".
name__v Name of the document or section. For sections, this is the name of the "subfolder" seen in the binder hierarchy in the UI.
major_version_number__v If the document binding rule is "specific", this is major version number of the document.
minor_version_number__v If the document binding rule is "specific", this is minor version number of the document.

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder. Verify that you have entered the correct binder id and not a document id.

Version History

Since: v5.0

Retrieve Binder Version Section

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

If the {NODE_ID} is left blank in the endpoint, the sections directly linked to the top-level binder will be returned instead.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/2/sections/1427232809771:1381853041

Example Response

{
    "responseStatus": "SUCCESS",
    "node": {
        "properties": {
            "section_number__v": "1",
            "name__v": "Level A VeevaProm",
            "order__v": 2,
            "type__v": "section",
            "id": "1427232809771:1381853041",
            "parent_id__v": "rootNode"
        },
        "nodes": [
            {
                "properties": {
                    "document_id__v": 568,
                    "name__v": "VeevaProm Presentation",
                    "order__v": 1,
                    "type__v": "document",
                    "id": "1427232745973:-39541070",
                    "parent_id__v": "1427232809771:1381853041"
                }
            },
            {
                "properties": {
                    "section_number__v": "1.1",
                    "name__v": "Level B VeevaProm Provider Info",
                    "order__v": 2,
                    "type__v": "section",
                    "id": "1427233015334:109650943",
                    "parent_id__v": "1427232809771:1381853041"
                }
            },
            {
                "properties": {
                    "section_number__v": "1.2",
                    "name__v": "Level B VeevaProm Patient Info",
                    "order__v": 3,
                    "type__v": "section",
                    "id": "1427233029752:1294369759",
                    "parent_id__v": "1427232809771:1381853041"
                }
            },
            {
                "properties": {
                    "section_number__v": "1.3",
                    "name__v": "VeevaProm Additional Information",
                    "order__v": 4,
                    "type__v": "section",
                    "id": "1427486900128:1467568099",
                    "parent_id__v": "1427232809771:1381853041"
                }
            }
        ]
    }
}

On success, Vault returns the specified section including a list of all subsections and documents contained within the specified section Node ID. Compare this response to the Retrieve Binder (All Binder Level Nodes) Response above.

Response Details

For each node in a binder, the API returns the following fields:

Field Description
nodes [n] List of all nodes (documents and sections) at each level in the binder.
properties [n] List of all properties associated with each document or section node.
order__v Order of the document or section within the binder or within another section of the binder.
section_number__v Optional number which can be added to each section.
type Type of node (document or section).
document_id__v The document ID of the document in the binder. This is the same as the document's actual document id
id The document ID or section ID specific to the binder. For documents, this is different from the document's actual document id.
parent_id__v Section ID of the parent node, e.g., "rootNode".
name__v Name of the document or section. For sections, this is the name of the "subfolder" seen in the binder hierarchy in the UI.
major_version_number__v If the document binding rule is "specific", this is major version number of the document.
minor_version_number__v If the document binding rule is "specific", this is minor version number of the document.

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder. Verify that you have entered the correct binder id and not a document id.

Version History

Since: v5.0

Create Binder Section

Send a POST request to the /api/{VERSION}/objects/binders/{ID}/sections endpoint.

Request Parameters

  • Set the HTTP Request Header Content-Type to application/x-www-form-urlencoded.
  • name__v - [required] You must specify a name for the new section.
  • section_number__v - [optional] You may enter a numerical value for the new section.
  • parent_id__v - [optional] If the new section is going to be a subsection, enter the Node ID of the parent section. If left blank, the new section will become a top-level section in the binder.
  • order__v - [optional] Enter the new section order arrangement within the parent section or within the binder (if the new section is a top-level section). An order__v=0 means the new section will be arranged in the first position. IF left blank, the new section will be arranged in the last position (bottom of the list).

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-d "name__v=VeevaProm Additional Information" \
-d "section_number__v=1.3" \
-d "parent_id__v=1427232809771:1381853041" \
-d "order__v=4" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/sections

Example Response

{
    "responseStatus": "SUCCESS",
    "id": "1427486900128:1467568099"
}

On success, Vault returns the Node ID of the newly created section. This is unique within the binder, regardless of level.

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder.
REQUIRED_FIELD_NOT_PRESENT Section name not present.
INVALID_SECTION Parent section ID is not a valid section.

Version History

Since: v5.0

Update Binder Section

Update a section in a binder.

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/binders/{ID}/sections/{NODE_ID} endpoint.

Request Headers

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

Parameters

  • {ID} - The binder id field value.
  • {NODE_ID} - The binder node id of the section.

Inputs

Configure one or more of the following fields with values. These are all optional.

  • name__v - Change the name of the binder section.
  • section_number__v - Update the section number value.
  • order__v - The ordinal position (1, 2, 3, etc.) where the section will be moved. For example, if the section's current order is 1 (first section in the binder or subsection) and you want to move it down one, set order__v=2. If the order is greater than the available positions, the section will be moved to the last position. When using only order__v (without parent_id__v), the section will be moved within the same higher level section.
  • parent_id__v - To move the section to a different section in the binder, include the value of the parent node where it will be moved.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name__v=VeevaProm Additional Information" \
-d "section_number__v=3" \
-d "parent_id__v=rootNode" \
-d "order__v=4" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/versions/0/3/sections/1427232809771:1381853041

Example Response

{
    "responseStatus": "SUCCESS",
    "id": "1427486900128:1467568099"
}

On success, Vault returns the Node ID of the newly created section. This is unique within the binder, regardless of level.

Possible Errors

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder.
REQUIRED_FIELD_NOT_PRESENT Section name not present.
INVALID_SECTION Parent section ID is not a valid section.

Version History

Available in API v5.0 or later.

Delete Binder Section

Send a DELETE request to the /api/{VERSION}/objects/binders/{ID}/sections/{NODE_ID} endpoint.

By deleting the section, it will be removed from its parent binder and all documents will be unlinked from the binder. If there are sub-sections and documents under the current section, they will be deleted (for sections) and unlinked (for documents) as well.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/sections/1427486900128:1467568099

Example Response

{
    "responseStatus": "SUCCESS",
    "id": "1427486900128:1467568099"
}

On success, Vault returns the Node ID of the deleted section.

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder
INVALID_SECTION Section ID is not a valid section

Refer to the API Errors section below for additional information.

Version History

Since: v5.0


Binder Documents

Add Document to Binder

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

Request Parameters

Set the HTTP Request Header Content-Type to application/x-www-form-urlencoded.

Field Description
document_id__v [required] ID of the document being added to the binder
parent_id__v [required] Section ID of the parent section, if the document will be in a section rather than top-level. Note: the section ID is unique no matter where it is in the binder hierarchy. Blank means adding the document at the top-level binder.
order__v [optional] Order within the parent section or binder ("1" is the first position). Blank means add it as the last element in the binder or parent section.
binding_rule__v [optional] binding rule indicating which version of the document will be linked to the binder and the ongoing behavior. Options are:
  • default - latest available (assumed if binding_rule is blank)
  • steady-state - latest version in steady-state state
  • current - bind to current version
  • specific - specific version
major_version_number__v if binding_rule is specific, then required and indicates the major version of the document to be linked, otherwise ignored
minor_version_number__v if binding_rule is specific, then required and indicates the minor version of the document to be linked. Otherwise ignored

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-d "document_id__v=585" \
-d "parent_id__v=1427232809771:1381853041" \
-d "section_id__v=1" \
-d "binding_rule__v=steady-state" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/documents

Example Response

{
    "responseStatus": "SUCCESS",
    "id": "1427491342404:-1828014479"
}

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder
INVALID_DOCUMENT Document ID is not present
INVALID_SECTION Parent section ID is not a valid section
MISSING_MAJOR Document major version was not specified and binding rule was specific
MISSING_MINOR Document minor version was not specified and binding rule was specific

Version History

Since: v5.0

Move Document in Binder

Move a document to a different position within a binder.

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

Request Headers

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

Request Parameters

  • {ID} - The binder id field value.
  • {NODE_ID} - The binder node id of the document in its current section and position.

Inputs

  • order__v - The ordinal position (1, 2, 3, etc.) where the document will be moved. For example, if the document's current order is 1 (first document in the section) and you want to move it down one, set order__v=2. If the order is greater than the available positions, the document will be moved to the last position in the section. When using only order__v (without parent_id__v), the document will be moved within the same section.
  • parent_id__v - To move the document to a different section in the binder, include the value of the parent node where it will be moved.

Note: There is a known issue which prevents users from moving documents into the first position within a section with only one API call. This occurs when an existing document has an order__v=0 (first position). Setting the document to be moved to an order__v=0 may not move it above the existing first document. Setting the order__v=-1 has no effect. To accomplish this type of move, you must move the existing document with an order__v=0 down to a lower order.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "parent_id__v=1427491342404:-1828014479" \
-d "order__v=2" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/documents/1427491342404:-1828014479

Example Response

{
    "responseStatus": "SUCCESS",
    "id": "1427491342404:-1828014479"
}

Possible Errors

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder
INVALID_DOCUMENT Document ID is not a valid document or the document is not linked to the selected binder
INVALID_TARGET_SECTION Parent ID is not a valid section within the binder or the Binder ID itself

Version History

Since v5.0

Remove Document from Binder

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

By unlinking the document, you remove it from the specified location within the binder, this does not actually delete the document from Vault.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "id": "1427491342404:-1828014479"
}

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

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder
INVALID_DOCUMENT Document ID is not present

Version History

Since: v5.0


Update Binding Rules

Update Binder Binding Rule

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

Request Parameters

binding_rule__v - [required] Indicates which binding rule to apply (which document versions to link to the section); options are default, steady-state, and current binding_rule_override__v - [required] Indicates if the specified rule should override documents or sections which already have binding rules set; options are true, and false

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-d "binding_rule__v=steady-state" \
-d "binding_rule_override__v=true" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/binding_rule

Example Response

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

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder
INVALID_BINDING_RULE Binder rule not recognized

Version History

Since: v5.0 - Update binder binding rules.

Update Binder Section Binding Rule

Send a PUT request to the /api/{VERSION}/objects/binders/{ID}/sections/{NODE_ID}/binding_rule endpoint.

Binding rule setting applies to the current section and all sub-sections.

Request Parameters

Field Description
binding_rule__v [required] which binding rule indicating which versions of documents will be linked to the section and the ongoing behavior; options are default, steady-state, and current
binding_rule_override__v [required] if set to true then binding rule is applied to all documents and sections within the current section. If blank or false then binding rule is applied only to documents and sections within the current section that do not have a binding rule specified; options are true, and false

Binding Rules:

  • default Latest available (assumed if binding_rule is blank)
  • steady-state Latest version in steady-state state
  • current Version currently in use

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-d "binding_rule__v=steady-state" \
-d "binding_rule_override__v=true" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/sections/1427232809771:1381853041/binding_rule

Example Response

{
    "responseStatus": "SUCCESS",
    "id": "1427491342404:-1828014479"
}

On success, Vault returns the Node ID of the updated section.

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder
INVALID_SECTION Section ID is not a valid section

Version History

Since: v5.0

Update Binder Document Binding Rule

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

Request Parameters

Field Description
binding_rule__v [optional] Binding rule indicating which versions of documents will be linked to the section and the ongoing behavior. Options are:
  • default - latest available (assumed if binding_rule is blank)
  • steady-state - latest version in steady-state state
  • current - bind to current version
  • specific - specific version
major_version_number__v if binding_rule is specific, then required and indicates the major version of the document to be linked, otherwise ignored
minor_version_number__v if binding_rule is specific, then required and indicates the minor version of the document to be linked. Otherwise ignored

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-d "binding_rule__v=specific" \
-d "major_version_number__v=1" \
-d "minor_version_number__v=0" \
https://myvault.veevavault.com/api/v12.0/objects/binders/566/documents/1427491342404:-1828014479/binding_rule

Example Response

{
  "responseStatus": "SUCCESS",
  "id": "1427491342404:-1828014479"
}

On success, Vault returns the Node ID of the updated document node within the binder

Possible Errors

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

Error Type Error Message/Description
INVALID_BINDER ID passed is not for a binder
INVALID_DOCUMENT Document ID is not a valid document or the document is not linked to the selected binder

Version History

Since: v5.0



Vault Objects

Retrieve All Vault Objects

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

Example Request

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "objects": [
        {
            "url": "/api/v12.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            "prefix": "00P",
            "order": 2,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Products",
            "in_menu": true,
            "allow_attachments": false
        },
        {
            "url": "/api/v12.0/metadata/vobjects/country__v",
            "label": "Country",
            "name": "country__v",
            ...
        },
        {
            "url": "/api/v12.0/metadata/vobjects/study__v",
            "label": "Study",
            "name": "study__v",
            ...
        },
        {
            "url": "/api/v12.0/metadata/vobjects/location__v",
            "label": "Location",
            "name": "location__v",
            ...
        },
        {
            "url": "/api/v12.0/metadata/vobjects/site__v",
            "label": "Study Site",
            "name": "site__v",
            ...
        },
        {
            "url": "/api/v12.0/metadata/vobjects/study_country__v",
            "label": "Study Country",
            "name": "study_country__v",
            ...
        },
        {
            "url": "/api/v12.0/metadata/vobjects/milestone__v",
            "label": "Milestone",
            "name": "milestone__v",
            ...
        }
    ]
}

The response includes a summary of key information (url, label, name, prefix, status, etc.) for all standard and custom Vault Objects configured in your vault.

Retrieve Localized Strings

When available, you can retrieve localized (translated) strings for the label and label_plural object fields by adding loc=true to request. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/metadata/vobjects?loc=true
{
    "responseStatus": "SUCCESS",
    "objects": [
        {
            "url": "/api/v12.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            "prefix": "00P",
            "order": 1,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Products",
            "in_menu": true,
            "localized_data": {
                "label_plural": {
                    "de": "Produkte",
                    "pt_PT": "Produtos",
                    "zh": "产品",
                    "it": "Prodotti",
                    "pt_BR": "Produtos",
                    "fr": "Produits",
                    "en": "Products",
                    "ru": "Продукты",
                    "es": "Productos",
                    "ja": "製品"
                },
                ...

When localized data is requested, the response includes an additional localized_data field containing translated fields and field values on each object field for which localized strings have been configured. This data is only available at the object and field level and only if localized strings have been configured.

Possible Errors

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

Version History

Since: v8.0

Retrieve All Object Metadata

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

Example Request

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "object": {
        "label_plural": "Products",
        "help_content": null,
        "prefix": "00P",
        "in_menu": true,
        "description": null,
        "label": "Product",
        "source": "standard",
        "modified_date": "2015-04-29T16:50:08.000Z",
        "created_by": 1,
        "allow_attachments": true,
        "dynamic_security": true,
        "relationships": [
            {
                "field": "product__v",
                "relationship_name": "studies__vr",
                "relationship_label": "Studies",
                "relationship_type": "reference_inbound",
                "relationship_deletion": "block",
                "object": {
                    "url": "/api/v12.0/metadata/vobjects/study__v",
                    "label": "Study",
                    "name": "study__v",
                    "label_plural": "Studies",
                    "prefix": "0ST"
                }
            }
        ],
        "urls": {
            "field": "/api/v12.0/metadata/vobjects/product__v/fields/{name}",
            "record": "/api/v12.0/vobjects/product__v/{id}",
            "attachments": "/api/v12.0/vobjects/product__v/{id}/attachments",
            "list": "/api/v12.0/vobjects/product__v",
            "metadata": "/api/v12.0/metadata/vobjects/product__v"
        },
        "role_overrides": false,
        "auditable": true,
        "name": "product__v",
        "modified_by": 1,
        "created_date": "2014-02-03T20:12:12.000Z",
        "fields": [
            {
                "help_content": null,
                "editable": false,
                "label": "ID",
                "source": "standard",
                "type": "ID",
                "modified_date": "2014-02-03T20:12:13.000Z",
                "created_by": 1,
                "required": false,
                "name": "id",
                "list_column": false,
                "modified_by": 1,
                "created_date": "2014-02-03T20:12:13.000Z",
                "status": [
                    "active__v"
                ],
                "order": 0
            },
            {
                "help_content": null,
                "editable": true,
                "label": "Product Name",
                "source": "standard",
                "type": "String",
                "modified_date": "2014-02-03T20:12:13.000Z",
                "created_by": 1,
                "required": true,
                "unique": true,
                "name": "name__v",
                "list_column": true,
                "modified_by": 1,
                "created_date": "2014-02-03T20:12:13.000Z",
                "status": [
                    "active__v"
                ],
                "max_length": 128,
                "order": 1
            },
            {
            ...
            }
        ],
        "status": [
            "active__v"
        ],
        "order": 2
    }
}

The response includes all metadata configured on the specific Vault Object.

Retrieve Localized Strings

When available, you can retrieve localized (translated) strings for the label, label_plural, and help_content object fields by adding loc=true to request. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/metadata/vobjects/product__v?loc=true
{
    "responseStatus": "SUCCESS",

    "object": 
            {
                ...
                "localized_data": {
                    "label_plural": {
                        "de": "Produkte",
                        "pt_PT": "Produtos",
                        ...
                    },
                    "label": {
                        "de": "Produkt",
                        "pt_PT": "Produto",
                        ...

    "fields":
            {
                ...
                "localized_data": {
                    "label": {
                        "de": "ID",
                        "pt_PT": "ID",
                        ...
                },
                "label": "ID",
                "name": "id"
            },
                ...
                "localized_data": {
                    "label": {
                        "de": "Produktbezeichnung",
                        "pt_PT": "Nome do produto",
                        ...
                },
                "label": "Product Name",
                "name": "name__v"
            },
                ...
                "localized_data": {
                    "label": {
                        "de": "Status",
                        "pt_PT": "Estado",
                        ...
            ...        

When localized data is requested, the response includes an additional localized_data field containing translated fields and field values on each object field for which localized strings have been configured. This data is only available at the object and field level and only if localized strings have been configured.

Possible Errors

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

Version History

Since: v8.0

Retrieve Object Field Metadata

Send a GET request to the /api/{VERSION}/metadata/vobjects/{NAME}/fields/{FIELD} endpoint.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "field": {
        "created_date": "2014-01-27T15:31:50.000Z",
        "created_by": 1,
        "max_length": 128,
        "list_column": true,
        "unique": true,
        "modified_date": "2014-01-27T15:31:50.000Z",
        "status": [
            "active__v"
        ],
        "label": "Product Name",
        "type": "String",
        "editable": true,
        "help_content": null,
        "order": 1,
        "source": "standard",
        "modified_by": 1,
        "name": "name__v",
        "required": true
    }
}

The response includes all metadata configured on the specific Vault Object field.

Retrieve Localized Strings

When available, you can retrieve localized (translated) strings for the label and help_content object fields by adding loc=true to request. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/metadata/vobjects/product__v/fields/name__v?loc=true
{
    "responseStatus": "SUCCESS",
    "field": {
        "created_date": "2014-01-27T15:31:50.000Z",
        "created_by": 1,
        "max_length": 128,
        "list_column": true,
        "localized_data": {
            "label": {
                "de": "Produktbezeichnung",
                "pt_PT": "Nome do produto",
                "zh": "产品名称",
                "it": "Nome prodotto",
                "pt_BR": "Nome do produto",
                "fr": "Nom de produit",
                "en": "Product Name",
                "ru": "Название продукта",
                "es": "Nombre de producto",
                "ja": "製品名"
            }
        },
        ...
    }
}

When localized data is requested, the response includes an additional localized_data field containing translated fields and field values on each object field for which localized strings have been configured. This data is only available at the object and field level and only if localized strings have been configured.

Possible Errors

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

Version History

Since: v8.0

Retrieve All Object Records

Send a GET request to the /api/{VERSION}/vobjects/{NAME} endpoint.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 3,
        "limit": 200,
        "offset": 0,
        "url": "/api/v12.0/vobjects/product__v",
        "object": {
            "url": "/api/v12.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            "prefix": "00P",
            "order": 1,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Products",
            "in_menu": true
    },
    "data": [
        {
            "id": "00P7662840171",
            "name__v": "CholeCap"
        },
        {
            "id": "00P7662840210",
            "name__v": "VeevaProm"
        },
        {
            "id": "00P7662840293",
            "name__v": "Nyaxa"
        }
    ]
}

The response includes the object metadata for the specified object and the id and name__v of all object records configured on the object.

Retrieve Specific Object Record Fields

You can augment the request to retrieve fields other than the default object record id and name__v by using the fields parameter and a comma-delimited list of object field names. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/vobjects/product__v?fields=id,name__v,external_id__v,generic_name__vs
{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 3,
        "limit": 200,
        "object": {
            "url": "/api/v12.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            ...
        "url": "/api/v12.0/vobjects/product__v?fields=id,name__v,external_id__v,generic_name__vs"
    },
    "data": [
        {
            "id": "00P7662840171",
            "name__v": "CholeCap",
            "external_id__v": "454-Chole",
            "generic_name__vs": "cholepriol phosphate"
        },
        {
            "id": "00P7662840210",
            "name__v": "VeevaProm",
            "external_id__v": "2258-VeevaP-2014",
            "generic_name__vs": "veniladrine"
        },
        {
            "id": "00P7662840293",
            "name__v": "Nyaxa",
            "external_id__v": "775-Nyaxa-A15",
            "generic_name__vs": "nitroprinaline oxalate"
        }
    ]
}

Limit, Sort, and Paginate Results

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

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

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

By default, Vault sorts the list by the object record id in ascending order. You can change this to sort in descending desc or ascending asc order based on an object field. For example, to sort by the name of each product in descending order:

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

With a maximum of 200 records returned per page, you must submit a new request to see the "next page" of results (when more than 200 object records exist). Vault provides two methods to accomplish pagination: the offset operator and the next_page/previous_page URLs.

The offset operator is used in request in the same way as the limit operator above. For example, if you're viewing the first page of 200 results (default maximum per page) out of 1000 total results found and want to see the next 200 results, enter offset=201.

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

The offset operator must be a positive integer. Values equaling to a number larger than the total number of records in the collection will not return any results.

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

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

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

Alternatively, you can use the next_page/previous_page URLs in the response to paginate results. Consider the following abridged response for an object record request:

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 1000,
        "limit": 200,
        "offset": 601,
        "previous_page": "/api/v12.0/vobjects/study__v?limit=200&offset=401",
        "next_page": "/api/v12.0/vobjects/study__v?limit=200&offset=801",
        "object": {
        ...

There are a total of 1000 object records found. We used the default maximum of 200 records per page and offset the results to 601, meaning this response is displaying results 601-800 (page 3). Notice the next_page URL shows a limit of 200 and offset of 401 (to view page 4) and the previous_page URL shows a limit of 200 and offset of 801 (to view page 4.).

The pagination URLs are automatically provided in the response when the number of records exceeds the maximum number of results per page. These strings can be used to basically "copy and paste" your next query to paginate the entire result set. The numbers at the end of the string (?limit=200&offset=801") can also be modified with different limits and offsets before using the string to change the pagination.

Note that the next_page and previous_page strings only remain active for about 15 minutes following the query.

Possible Errors

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

Version History

Since: v8.0

Retrieve Object Record

Send a GET request to the /api/{VERSION}/vobjects/{NAME}/{ID} endpoint.

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/vobjects/product__v/00P7662840171

Example Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "object": {
            "url": "/api/v12.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            "prefix": "00P",
            "label_plural": "Products"
        },
        "url": "/api/v12.0/vobjects/product__v/00P7662840171"
    },
    "data": {
        "external_id__v": "454-Chole",
        "internal_name__vs": "CholeCap",
        "therapeutic_area__vs": [
            "cardiology__vs"
        ],
        "abbreviation__vs": "CC",
        "created_date__v": "2013-01-08T16:34:00.000Z",
        "id": "1357662840171",
        "status__v": [
            "active__v"
        ],
        "created_by__v": 25500,
        "modified_date__v": "2014-04-16T00:00:55.000Z",
        "modified_by__v": 25524,
        "compound_id__vs": "39RBO",
        "product_family__vs": "Cholepriol",
        "name__v": "CholeCap",
        "manufacturer_name__v": "VeevaLabs",
        "generic_name__vs": "cholepriol phosphate"
    }
}

The response includes all object fields and field values for the specified object record. Object record fields vary significantly from object to object.

Possible Errors

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

Version History

Since: v8.0

Create Object Records

Create Object Records in bulk.

  • The maximum 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}/vobjects/{object_name}

Headers

Name Description
Content-Type text/csv or application/json
Accept application/json (default) or text/csv

URI Path Parameters

Name Description
{object_name} The name of the object, for example, product__v.

Body Parameters

Upload parameters as a JSON or CSV file.

Name Description
name__v This field is required unless it is set to system-managed. To find out if an object uses system-managed naming, retrieve its name__v field and look for the system_managed_name property set to true or false. Learn more about system-managed naming in Vault Help.
source_record_id Optional: To copy an existing object record, add this field with the id of the existing object record. Any values specified for other fields will override the copied values. If you want to make a deep copy of a record, see the Deep Copy endpoint.

Admin may set other standard or custom object fields to required. Use the Object Metadata API to retrieve all fields configured on objects. You can add any object field with editable: true.

Download Input File

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Object Records\create_object_records.csv" \
https://myvault.veevavault.com/api/v8.0/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "0PR0771",
                "url": "api/v8.0/vobjects/product__v/0PR0771"
            }
        },
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "0PR0772",
                "url": "api/v8.0/vobjects/product__v/0PR0772"
            }
        },
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "0PR0773",
                "url": "api/v8.0/vobjects/product__v/0PR0773"
            }
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not created."
                }
            ]
        }
    ]
}

Update Object Records

Update Object Records in bulk.

  • The maximum 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.

PUT /api/{version}/vobjects/{object_name}

Headers

Name Description
Content-Type text/csv or application/json
Accept application/json (default) or text/csv

URI Path Parameters

Name Description
{object_name} The name of the object, for example, product__v.

Body Parameters

Upload parameters as a JSON or CSV file.

Name Description
id The object record ID.

Admin may set other standard or custom object fields to required. Use the Object Metadata API to retrieve all fields configured on objects. You can update any object field with editable: true.

Note that if an object is a parent in a parent-child relationship with another object, you cannot update its status__v field in bulk.

If Dynamic Security (Custom Sharing Rules) is configured on an object, you can add or remove users and groups on manually assigned roles. For example, editor__v.users. This will overwrite any users currently in the role.

Download Input File

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Object Records\update_object_records.csv" \
https://myvault.veevavault.com/api/v8.0/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        },
        {
            "responseStatus": "SUCCESS"
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not updated."
                }
            ]
        }
    ]
}

Delete Object Record

Delete Object Records in bulk.

  • The maximum 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.

DELETE /api/{version}/vobjects/{object_name}

Headers

Name Description
Content-Type text/csv or application/json
Accept application/json (default) or text/csv

URI Path Parameters

Name Description
{object_name} The name of the object, for example, product__v.

Body Parameters

Upload parameters as a JSON or CSV file.

Name Description
id The system-assigned object record ID to delete.
external_id__v Optional: Instead of id, you can use this user-defined document external ID.

Query String Parameters

Name Description
idParam If you're identifying documents in your input by their external ID, add idParam=external_id__v to the request endpoint.

Admin may set other standard or custom object fields to required. Use the Object Metadata API to retrieve all fields configured on objects. You can update any object field with editable: true.

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Object Records\delete_object_records.csv" \
https://myvault.veevavault.com/api/v14.0/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        },
        {
            "responseStatus": "SUCCESS"
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not deleted."
                }
            ]
        }
    ]
}

Vault Object Record Attachments

Determine if Attachments are Enabled on an Object

Send GET request to the /api/{VERSION}/metadata/vobjects/{OBJECT} endpoint.

Example Request

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

Example 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/v12.0/metadata/vobjects/site__v/fields/{NAME}",
            "record": "/api/v12.0/vobjects/site__v/{ID}",
            "attachments": "/api/v12.0/vobjects/site__v/{ID}/attachments",
            "list": "/api/v12.0/vobjects/site__v",
            "metadata": "/api/v12.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, "allow_attachments" is set to true for this object and "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 can have attachments.

Possible Errors

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

Version History

Since: v12.0

Retrieve Object Record Attachments

Send a GET request to the /api/{VERSION}/vobjects/{NAME}/{ID}/attachments endpoint.

Example Request

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

Example 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/v12.0/vobjects/site__v/1357752909483/attachments/558/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v12.0/vobjects/site__v/1357752909483/attachments/558/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.vaultdev.com/api/v12.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/v12.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.

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource [{resource}] does not exist. The user is attempting to retrieve metadata from an object record {ID} which does not exist.

Version History

Since: v12.0

Retrieve Object Record Attachment Metadata

Send a GET request to the /api/{VERSION}/vobjects/{NAME}/{ID}/attachments/{ID} endpoint.

Example Request

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

Example 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/v12.0/vobjects/site__v/1357752909483/attachments/558/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v12.0/vobjects/site__v/1357752909483/attachments/558/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.vaultdev.com/api/v12.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.

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to retrieve metadata from an attachment {ID} which does not exist on the specified object record.

Version History

Since: v12.0

Retrieve Object Record Attachment Versions

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

Example Request

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

Example Response

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

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to retrieve metadata from an attachment {ID} which does not exist on the specified object record.
MALFORMED_URL The resource [{ID}/version/{VERSION}] does not exist. The user is attempting to retrieve metadata from a specific version {VERSION} of an attachment {ID} which does not exist on the specified object record. The attachment {ID} exists but the version number {VERSION} does not.

Version History

Since: v12.0

Retrieve Object Record Attachment Version Metadata

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

Example Request

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

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

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to retrieve metadata from an attachment {ID} which does not exist on the specified object record.
MALFORMED_URL The resource [{ID}/version/{VERSION}] does not exist. The user is attempting to retrieve metadata from a specific version {VERSION} of an attachment {ID} which does not exist on the specified object record. The attachment {ID} exists but the version number {VERSION} does not.

Version History

Since: v12.0

Retrieve Object Record Attachment File

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

Example Request

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

Response Details

  • 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 attachments (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Example Response Header

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

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to retrieve an attachment {ID} which does not exist on the specified object record.
MALFORMED_URL The resource does not contain attachments. The user is attempting to retrieve an attachment from an object record which does not have any attachments.

Version History

Since: v12.0

Retrieve Object Record Attachment Version File

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

Example Request

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

Reponse Details

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

  • The HTTP Response Header Content-Type is set to application/octet-stream.
  • The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. This can be changed.
  • When 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 attachments (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Example Response Header

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

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to retrieve an attachment {ID} which does not exist on the specified object record.
MALFORMED_URL The resource [{ID}/version/{VERSION}] does not exist. The user is attempting to retrieve a specific version {VERSION} of an attachment {ID} which does not exist on the specified object record. The attachment {ID} exists but the version number {VERSION} does not.
MALFORMED_URL The resource does not contain attachments. The user is attempting to retrieve an attachment from an object record which does not have any attachments.

Version History

Since: v12.0

Retrieve All Object Record Attachment Files

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

Example Request

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

Response Details

On success, Vault retrieves the latest version of all attachments from the object record. The attachments are packaged in a ZIP file with the file name: {object type label} {object record name} - attachments.zip.

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

Example Response Header

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="Product Cholecap - attachments.zip"

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource does not contain attachments. The user is attempting to retrieve attachments from an object record which does not have any attachments.

Version History

Since: v12.0

Create Object Record Attachment

Send POST request to the /api/{VERSION}/vobjects/{NAME}/{ID}/attachments endpoint.

Request Parameters

  • Set the HTTP Request Header Content-Type to multipart/form-data.
  • To upload the file, use the multi-part attachment with the file component named file.
  • If an attachment is added which has the same filename as an existing attachment on a given object record, 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 object record, the new attachment is not added.

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

  • filename__v
  • format__v
  • size__v

Example Request

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

Example Response

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

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource is not enabled for attachments. The user is attempting to add an attachment to an object record for which attachments have not been enabled.
OPERATION_NOT_ALLOWED Cannot add an attachment : number of allowed attachments exceeds max [50]. The user is attempting to add an attachment to an object record which already has the maximum number of allowed attachments (50).
OPERATION_NOT_ALLOWED Cannot add an attachment : maximum attachment file size exceeds max [{n}]. The user is attempting to add an attachment to an object record which exceeds the maximum file size allowed for an attachment (2GB).

Version History

Since: v12.0

Restore Object Record Attachment Version

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

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v12.0/vobjects/site__v/1357752909483/attachments/571/versions/2?restore=true

Example Response

{
    "responseStatus": "SUCCESS",
    "data":
    {
        "id": "571",
        "version__v": 2
    }
}

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to restore an attachment {ID} which does not exist on the specified object record.
MALFORMED_URL The resource [{ID}/version/{VERSION}] does not exist. The user is attempting to restore a specific version {VERSION} of an attachment {ID} to make it the latest version, but the attachment or version do not exist.
PARAMETER_REQUIRED Missing required parameter [restore]. The user is attempting to restore a specific version of an attachment but did not include the "restore" parameter.
MALFORMED_URL The resource is not enabled for attachments. The user is attempting to restore an attachment to a object record for which attachments have not been enabled.

Version History

Since: v12.0

Update Object Record Attachment Description

Send a PUT request to the /api/{VERSION}/vobjects/{NAME}/{ID}/attachments/{ID} endpoint.

Request Parameters

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to update an attachment {ID} which does not exist on the specified object record.
MALFORMED_URL The resource is not enabled for attachments. The user is attempting to add or restore an attachment to an object record for which attachments have not been enabled.
INVALID_DATA Invalid value [{value}] specified for parameter [description__v] : string exceeds max length [1000]. The user is attempting to update the attachment description when the description exceeds the maximum character length (1000)

Version History

Since: v12.0

Delete Object Record Attachment

Send a DELETE request to the /api/{VERSION}/vobjects/{NAME}/{ID}/attachments/{ID} endpoint.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to delete an attachment {ID} which does not exist on the specified object record.

Version History

Since: v12.0

Delete Object Record Attachment Version

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Error Type Error Message/Description
MALFORMED_URL The resource [{ID}] does not exist. The user is attempting to delete an attachment {ID} which does not exist on the specified object record.
MALFORMED_URL The resource [{ID}/version/{VERSION}] does not exist. The user is attempting to delete a specific version {VERSION} of an attachment {ID} which does not exist on the specified object record. The attachment {ID} exists but the version number {VERSION} does not.

Version History

Since: v12.0



Roles

  • Documents have different roles available to them depending on their document type and lifecycle.
  • Users and groups are automatically assigned to roles when the document is created and when the document changes workflows.
  • Vault includes the following set of default document roles: Owner, Coordinator, Editor, Approver, Reviewer, Viewer, and Consumer.
  • You can create custom document roles that are unique to a particular document type and lifecycle.
  • Regardless of how a role is assigned, they have specific permissions on a document based on a lifecycle state.

Retrieve All Document Roles

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

Example Request

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document roles retrieved",
    "errorCodes": null,
    "documentRoles": [
        {
            "name": "reviewer__v",
            "label": "Reviewer",
            "assignedUsers": [
                25496,
                26231
            ],
            "assignedGroups": [
                1,
                2
            ],
            "availableUsers": [
                25530,
                26328,
                28874
            ],
            "availableGroups": [
                1,
                2,
                3
            ],
            "defaultUsers": [
                25496,
                26231
            ],
            "defaultGroups": [
                1,
                2
            ]
        },
        {
            "name": "viewer__v",
            "label": "Viewer",
            ...
        },
        {
            "name": "consumer__v",
            "label": "Consumer",
            ...
        },
        {
            "name": "approver__v",
            "label": "Approver",
            ...
        },
        {
            "name": "owner__v",
            "label": "Owner",
            ...
        },
        {
            "name": "editor__v",
            "label": "Editor",
            ...
        },
        {
            "name": "coordinator__v",
            "label": "Coordinator",
            ...
        }
    ],
    "errorType": null
}

In the abrided response above, document ID 245 is configured with several roles. Two users (25496 & 26231) and two groups (1 & 2) are assigned to the reviewer__v role.

Possible Errors

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

Version History

Since: v5.0

Retrieve Users & Groups Assigned to Role

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

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document role retrieved",
    "errorCodes": null,
    "documentRoles": [
        {
            "name": "reviewer__v",
            "label": "Reviewer",
            "assignedUsers": [
                25496,
                26231
            ],
            "assignedGroups": [
                1,
                2
            ],
            "availableUsers": [
                25530,
                26328,
                28874
            ],
            "availableGroups": [
                1,
                2,
                3
            ],
            "defaultUsers": [
                25496,
                26231
            ],
            "defaultGroups": [
                1,
                2
            ]
        }
    ],
    "errorType": null
}

The response includes the Vault User IDs and Group IDs of all users and groups assigned to the specific role on the document.

Possible Errors

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

Version History

Since: v5.0

Assign Users & Groups to Roles on a Single Document

Assign users and groups to roles on a single document or binder.

POST /api/{version}/objects/documents/{id}/roles

Headers

Name Description
Content-Type application/x-www-form-urlencoded
Accept application/json (default) or application/xml

URI Path Parameters

Name Description
{id} The document or binder id field value.

Body Parameters

Include name-value pairs of all users or groups with their corresponding roles in the form {Role_name}.{USERS or GROUPS}=ID1,ID2,ID3. For example, reviewer__v.users = "3003, 4005".

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "consumer__v.users=35565,35571" \
-d "approver__v.users-45585,45594" \
https://myvault.veevavault.com/api/v15.0/objects/documents/245/roles

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Document roles updated",
  "updatedRoles": {
    "consumer__v": {
      "users": [
        19376,18234,19456
      ]
    },
    "legal__c": {
      "groups": [
        19365,18923
      ]
    }
  }
}

Response Details

The response includes ROLE:ID pairs for the users and groups successfully assigned to roles on the document or binder.

Assign Users & Groups to Roles on Multiple Documents

Assign users and groups to roles on a document or binder in bulk.

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

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

Assigning users and groups to document roles is additive. For example, if groups 1, 2, and 3 are currently assigned to a particular role and you assign groups 3, 4, and 5 to the same role, the final list of groups assigned to the role will be 1, 2, 3, 4, and 5. Users and groups (IDs) in the input that are either invalid (not recognized) or cannot be assigned to a role due to permissions are ignored and not processed.

Headers

Name Description
Content-Type text/csv or application/x-www-form-urlencoded
Accept application/json (default) or application/xml

Body Parameters

You can add parameters in the request body, or upload them as a CSV file.

Name Description
id The document ID.
role__v.users A string of user id values for the new role.
role__v.groups A string of user id values for the new group.

For example,

id reviewer__v.users reviewer__v.groups approver__v.users approver__v.groups
771 "12021,12022" "3311303,3311404" 22124 4411606

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.groups": [
                3311303,
                4411606
            ],
            "reviewer__v.users": [
                12021,
                12022,
                12023,
                12124
            ]           
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.groups": [
                3311303,
                4411606
            ],
            "reviewer__v.users": [
                12021,
                12022,
                12023,
                12124
            ]           
        },        
        {
           "responseStatus":"FAILURE",
           "id":"773",
           "errors":[
              {
                 "type":"INVALID_DATA",
                 "message":"Error message describing why the users and groups were not assigned to roles on this document.."
              }
           ]
        }
    ]
}

Response Details

The response includes role:id pairs for the users and groups successfully assigned to roles.

Remove Users & Groups from Roles on a Single Document

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/documents/1234/roles/consumer__v.user/19376

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "User/group deleted from document role",
  "updatedRoles": {
    "consumer__v": {
      "users": [
        19376
      ]
    }
  }
}

Remove users and groups from roles on a single document or binder.

DELETE /api/{version}/objects/documents/{doc_id}/roles/{role_name}.{user_or_group}/{id}

Headers

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

URI Path Parameters

Name Description
{doc_id} The id value of the document or binder from which to remove roles.
{role_name} The name of the role to remove the users or groups from.
{user_or_group} Choose to remove a user or a group from a role. Possible values for this parameter are either user or group.
{id} The id value of the user or group to remove from the role.

Remove Users and Groups from Roles on Multiple Documents

Remove users and groups to roles on a document or binder in bulk.

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

DELETE /api/{version}/objects/documents/roles/batch

Headers

Name Description
Content-Type text/csv or application/x-www-form-urlencoded
Accept application/json (default) or application/xml

Body Parameters

You can add parameters in the request body, or upload them as a CSV file.

Name Description
id The document ID.
role__v.users A string of user id values to delete.
role__v.groups A string of user id values to delete.

For example,

id reviewer__v.users reviewer__v.groups approver__v.users approver__v.groups
771 "12021,12022" "3311303,3311404" 22124 4411606

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.groups": [
                4411606
            ],
            "reviewer__v.users": [
                12124
            ]           
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.groups": [
                4411606
            ],
            "reviewer__v.users": [
                12124
            ]           
        },        
        {
           "responseStatus":"FAILURE",
           "id":"773",
           "errors":[
              {
                 "type":"INVALID_DATA",
                 "message":"Error message describing why the users and groups were not removed from roles on this document."
              }
           ]
        }
    ]
}



Users

The Vault users object includes a fixed set of metadata. You cannot add or remove fields, nor can you change the field names or labels.

About Domain-Level User Management

Vault user accounts exist at the domain level, so in multi-vault domains, user details are shared across vaults.

Users in the Vault Owner and System Admin roles have access to all users in the vaults where they are assigned administrative access. Users with the Domain Admin setting enabled in their user profile and assigned the Admin: Users: Create, Edit permission in every domain vault, have access to all users across all vaults in your domain. Learn about Permission Sets in Vault Help.

To support domain-level user management, the API includes the following input options and request parameters:

  • domain=true - When creating a user, this can be (optionally) included in the input to add the user to the domain but not assign them to any vaults in the domain. When disabling a user, this is added to the request endpoint.
  • domain_active__v - When updating a user, this can be (optionally) included in the input and set to either true or false to enable or disable the user at the domain-level. Disabling a user at the domain-level will disable the user in every vault in your domain. Re-enabling a user enables them in the domain but does not re-activate them in their vaults. After re-enabling a user, you must update their vault membership to make them active in the individual vaults.
  • is_domain_admin__v - When creating or updating a user, this can be (optionally) included in the input and set to true to make a user a Domain Admin. When updating a user, this can be set to false to remove them from the Domain Admin role. Note that only another Domain Admin can do this. There must always be at least one Domain Admin.

Domain-level user management is available in API v7.0 or later.

Vault User Metadata

Required Fields: With the exception of the Vault User ID, the fields listed below are required when adding new users to a vault.

Field Name Field Label Field Type Description Required Editable Queryable
id ID id Unique user identifier (primary). Numeric value. System-Managed False True
user_name__v User Name String Unique user identifier. This is the user's vault login credential. True True True
user_email__v Email String The user's email address. Vault notifications are sent to this address. True True True
user_first_name__v First Name String The user's first name. True True True
user_last_name__v Last Name String The user's last name. True True True
user_language__v Language String The user's preferred language. Available values displayed in metadata response. True True True
user_timezone__v Timezone String The user's time zone. Available values displayed in metadata response. True True True
user_locale__v Locale String The user's location. Available values displayed in metadata response. True True True
security_policy_id__v Security Policy ObjectReference The user's security policy. Learn more. True True True
vault_id__v Vault ID ObjectReference The ID of the vault to which the user is assigned. Learn more. True ** vault_membership False True
security_profile__v Security Profile * ObjectReference The user's security profile. Available values displayed in metadata response. True ** vault_membership True True
license_type__v License Type * Picklist The user's license type. Learn more. True ** vault_membership True True
active__v Active Boolean Whether or not the user is active in the current Vault application. True ** vault_membership True True

* The security_profile__v and license_type__v fields are available in API v10.0 or later.
** The vault_membership fields are not required to add users to the domain. They are required to assign users to vaults. See Create User and Update Vault Membership below.

Optional Fields: The fields listed below are either optional, editable user fields or system-managed user fields.

Field Name Field Label Field Type Description Required Editable Queryable
company__v Company String The user's company. False True True
user_title__v Title String The user's title. False True True
alias__v Alias String Nickname. Used to differentiate users with the same first and last name. False True False
site__v Site String The user's location, such as a city. In user profiles (UI), this is labeled "Location". False True True
office_phone__v Office Phone Number String The user's office phone number. False True True
mobile_phone__v Mobile Phone Number String The user's mobile phone number. False True True
fax__v Fax Phone Number String The user's fax number. False True True
user_needs_to_change_password__v Change Password Boolean The user is required to change their password on next login. False True True
domain_active__v Domain Active Boolean Whether or not the user is active in the domain. False True True
is_domain_admin__v Is Domain Admin Boolean The user is a Domain Administrator. False True True
domain_id__v Domain ID ObjectReference The ID of the domain to which the user is assigned. System-Managed False True
federated_id__v Federated ID String The user's federated ID if using SAML Single Sign-on Authentication. False True True
salesforce_user_name__v Salesforce Username String The user's Salesforce.com username if using Salesforce Delegated Authentication. False True True
medidata_uuid__v Medidata UUID String The user's Medidata email if using Medidata Delegated Authentication. False True True
group_id__v Group ID ObjectReference The IDs of the groups to which the user is assigned. False False False
created_date__v Created Date Calendar The date and time when the user account was created. System-Managed False True
created_by__v Created By ObjectReference The user ID of the person who created the user account. System-Managed False True
modified_date__v Modified Date Calendar The date and time when the user account was last modified. System-Managed False True
modified_by__v Modified By ObjectReference The user ID of the person who last modified the user account. System-Managed False True
last_login__v Last Login Calendar The date the user last logged into the vault. System-Managed False True

Field Properties: The information listed below may be included with each field.

Field Property Description
name Field name.
type Field type: ID, String, Boolean, Picklist, Calendar, or ObjectReference.
object When the field type is "ObjectReference", this shows the name of the object being referenced.
multivalue Whether or not the field can have multiple values.
queryable Whether or not the field can be used in API queries.
length When the field type is "String", this shows the maximum character length allowed.
required Whether or not the field is required when creating a new user.
onCreateEditable Whether or not the field can be set when creating a new user.
editable Whether or not the field is editable.
values Lists allowed values for the user_locale__v, user_language__v, user_timezone__v, and security_profile__v fields.

Retrieve User Metadata

Use this request to retrieve all user fields and field properties.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Example Request

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "properties": [
        {
            "name": "user_name__v",
            "type": "String",
            "length": 255,
            "editable": true,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "user_first_name__v",
            "type": "String",
            "length": 100,
            "editable": true,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        ...

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Retrieve All Users

Use this request to retrieve all users and user metadata.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Optional Request Parameters

Using the endpoint alone with no optional parameters will retrieve users assigned only to the vault in which the request is made.

For customers with multiple vaults in their domain, users with Domain Admin, System Admin, and Vault Owner privileges can access user information across different vaults in the domain by including the optional parameter vaults set to one of the following values:

  • vaults=all - Retrieve all users assigned to all vaults in your domain.
  • vaults=-1 - Retrieve all users assigned to all vaults in your domain except for the vault in which the request is made.
  • vaults={Vault IDs} - Use a comma-separated list of Vault IDs to retrieve users assigned only to the specified vaults.

System Admins and Vault Owners must have administrative access to Vault applications referenced in the vaults parameter to be able to access users from those vault. Learn about domain-level user management above.

The response supports pagination. By default the page limit is set to 200 records. The pagination parameters are:

Field Description
limit [optional, default is 200] the size of the result set in the page
start [optional, default is 0] the starting record number
sort [optional, default is "id asc"] the sort order for the result set (asc - ascending, desc - descending) (e.g. user_name__v asc)

Example Request

This request will retrieve all users assigned to the vault in which the request is made.

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

Example Request

This request will retrieve all users assigned to all vaults in the domain. This is available only to Admin users with administrative access to the vaults.

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/users?vaults=all

Example Request

This request will retrieve all users assigned to all vaults in the domain except the vault in which the request is made. This is available only to Admin users with administrative access to the vaults.

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/users?vaults=-1

Example Request

This request will retrieve all users assigned to vault ID 3003, vault ID 4004, and vault ID 5005. This is available only to Admin users with administrative access to the vaults.

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/users?vaults=3003,4004,5005

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "size": 200,
    "start": 0,
    "limit": 200,
    "sort": "id asc",
    "users": [
        {
            "user": {
                "id": 25501,
                "user_name__v": "ewoodhouse@veevapharm.com",
                "user_first_name__v": "Elaine",
                "user_last_name__v": "Woodhouse",
                ...
        },
        {
            "user": {
                "id": 25502,
                "user_name__v": "bashton@veevapharm.com",
                "user_first_name__v": "Bruce",
                "user_last_name__v": "Ashton",
                ...
        },                
        {
            "user": {
                "id": 25503,
                "user_name__v": "tchung@veevapharm.com",
                "user_first_name__v": "Thomas",
                "user_last_name__v": "Chung",
                ...
        },                
        ...

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Retrieve User

Use this request to retrieve the user metadata for a specific user.

Method & Endpoint

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

Request Headers

  • 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 system-managed numerical ID assigned to each user. See Retrieve All Users above.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "users": [
        {
            "user": {
                "user_name__v": "ewoodhouse@veevapharm.com",
                "user_first_name__v": "Elaine",
                "user_last_name__v": "Woodhouse",
                "user_email__v": "ewoodhouse@veevapharm.com",
                "user_timezone__v": "America/New_York",
                "user_locale__v": "en_US",
                "user_title__v": "Research Associate",
                "office_phone__v": "5559876543",
                "fax__v": "5556789123",
                "mobile_phone__v": "5551234567",
                "site__v": "Manhattan",
                "is_domain_admin__v": false,
                "active__v": true,
                "domain_active__v": true,
                "security_policy_id__v": 821,
                "user_needs_to_change_password__v": false,
                "id": 25496,
                "created_date__v": "2013-01-08T15:55:27.000Z",
                "created_by__v": 25001,
                "modified_date__v": "2015-02-12T18:22:18.000Z",
                "modified_by__v": 25001,
                "domain_id__v": 3003,
                "vault_id__v": [
                    3003,
                    4004
                ],
                "federated_id__v": "",
                "salesforce_user_name__v": "",
                "last_login__v": "2015-01-20T23:58:02.000Z",
                "medidata_uuid__v": "",
                "user_language__v": "en",
                "company__v": "VeevaPharm",
                "group_id__v": [
                    2555089996,
                    2111844470
                ],
                "security_profile__v": "document_user__v",
                "license_type__v": "full__v",
                "vault_membership": [
                    {
                        "id": 3003,
                        "active__v": true,
                        "security_profile__v": "document_user__v",
                        "license_type__v": "full__v"
                    },
                    {
                        "id": 4004,
                        "active__v": true,
                        "security_profile__v": "document_user__v",
                        "license_type__v": "full__v"
                    }
                ]
            }
        }
    ]
}

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Create User

Use this request to add one new user to your domain or to a vault.

Method & Endpoint

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

Request Headers

  • To specify the input format, set the HTTP Request Header Content-Type to multipart/form-data (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.

Input Requirements

When creating new users, the following fields are required in all vaults:

  • user_name__v
  • user_first_name__v
  • user_last_name__v
  • user_email__v
  • user_timezone__v
  • user_locale__v
  • user_language__v
  • security_policy_id__v

Adding User Profile Pictures

Optional - You may add a user profile picture. To do so, include the file parameter in the input with the path/location of the image to be uploaded. For example:

-F "file=images/elaine.jpg" \

Uploaded profile pictures must be JPG, PNG, or GIF files, and less than 10MB in size. Vault automatically resizes images to 64 x 64 pixels, and removes the animations for animated GIFs. Images of approximately square aspect ratio will work best as profile pictures.

Example Request: Add User to Domain

This request will add one new user to your domain. It will not assign them to individual vaults in your domain. See also: Update Vault Membership.

  • This request includes all required fields to create a new user.
  • By including domain=true, the user will not be assigned to a vault.
$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "user_name__v=ewoodhouse@veevapharm.com" \
-F "user_email__v=ewoodhouse@veevapharm.com" \
-F "user_first_name__v=Elaine" \
-F "user_last_name__v=Woodhouse" \
-F "user_language__v=en" \
-F "user_timezone__v=America/Denver" \
-F "user_locale__v=en_US" \
-F "security_policy_id__v=821" \
-F "domain=true" \
https://myvault.veevavault.com/api/v14.0/objects/users

On SUCCESS, the user account will be created and set to active. The new user will not be assigned a license type or security profile, nor will they have access to any vaults in your domain.

Example Request: Add User to Current Vault

This request will add one new user to your domain. It will also assign them to the vault in which the request is made. See also: Update Vault Membership.

  • This request includes all required fields to create a new user.
  • This request includes the security profile and license type fields. This is optional. If not included in the request, this user would be assigned the document_user__v security profile and full__v license type by default.
$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "user_name__v=ewoodhouse@veevapharm.com" \
-F "user_email__v=ewoodhouse@veevapharm.com" \
-F "user_first_name__v=Elaine" \
-F "user_last_name__v=Woodhouse" \
-F "user_language__v=en" \
-F "user_timezone__v=America/Denver" \
-F "user_locale__v=en_US" \
-F "security_policy_id__v=821" \
-F "security_profile__v=business_admin__v" \
-F "license_type__v=full__v" \
https://myvault.veevavault.com/api/v14.0/objects/users

On SUCCESS, the user account will be created and set to active. The new user will be a member of the vault instance in which the request was made and assigned the Business Admin security profile and Full User license type. They will receive a welcome email with instructions for logging into the vault. They will not have access to any other vaults in your domain. To give them access to other vaults, see Update Vault Membership below.

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
As of API v8.0, the domain_active__v field cannot be set when creating a user.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Create Multiple Users

Create new users and assign them to vaults in bulk.

  • The maximum 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.
  • If you want to add profile pictures, you must upload these to the FTP staging server.

Headers

Name Description
Content-Type application/json or text//csv
Accept application/json (default) or text//csv

Body Parameters

Prepare a JSON or CSV input file.

Name Description
user_name__v The user’s vault username (login credential). For example, ewoodhouse@veepharm.com
user_first_name__v The user's first name.
user_last_name__v The user's last name.
user_email__v The user's email address.
user_timezone__v The user's time zone. Retrieve values from Retrieve User Metadata.
user_locale__v The user's location. Retrieve values from Retrieve User Metadata.
security_policy_id__v The user's security policy. Retrieve values from Retrieve All Security Policies.
user_language__v The user's preferred language. Retrieve values from Retrieve User Metadata.
file Optional: The file path of a profile picture from the FTP. Must be JPG, PNG, or GIF, and less than 10MB in size. Vault automatically resizes images to 64 x 64 pixels and removes the animations from GIFs.
domain Optional: If you set this to true, the user will not be assigned to a vault.
security_profile__v Optional: The user’s security profile. If omitted, default value is document_user__v.
license_type__v Optional: The user’s license type. If omitted, default value is full__v.
vault_membership Optional: Use this field to assign a user to individual vaults within your domain. See below for how to configure.
Vault Membership

To assign user permissions across vaults, you must include the vault_membership field and configured with the following fields:

Name Description
id The vault ID to assign the user to.
active__v Optional: Set the user to active (true) or inactive (false). If not specified, default value is true.
security_profile__v Optional: Set the user's security profile, for example, read_only_user__v. If not specified, this value defaults to document_user__v.
license_type__v Optional: Set the user's license type, for example, read_only__v. If not specified, this value defaults to full__v.

For example, to add an active user to vault ID 3003 with the system_admin__vsecurity profile and the full__v license type:

vault_membership
3003:true:system_admin__v:full__v

Query String Parameters: Upsert Users

Upsert is a combination of create and update. Use one input file to create new users and update existing users at the same time. If a matching user record is found in your vault, it is updated with the field values specified in the input. If no matching user record is found, a new user is created using values in the input.

Name Description
operation To upsert users, you must include operation=upsert
idParam To upsert users, you must include either idParam=id or idParam=user_name__v to the request endpoint.

Download Input File

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Users\create_users.csv" \
https://myvault.veevavault.com/api/v12.0/objects/users

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "id":"12021"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12022"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12023"
      },      
      {
         "responseStatus":"FAILURE",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not created."
            }
         ]
      }
   ]
}

Response Details:

On SUCCESS, Vault responds will list the id of each user. The order results are displayed in the response is the same as the order of records in the input.

Download Input File

Update User

Use this request to update the user profile information for an existing user in your domain.

Permissions

  • System Admins and Vault Owners can update users in the vaults where they have administrative access.
  • System Admins who are also Domain Admins have an unrestricted access to users across all vaults in the domain.

Method & Endpoint

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

Request Headers

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

Request Parameters

  • {ID} - The system-managed numerical ID assigned to each user. See Retrieve All Users above.

Example Request: Update User Profile Information

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "user_timezone__v=America/Los Angeles" \
-d "company__v=VeevaPharm" \
-d "user_title__v=Product Manager" \
-d "alias__v=Skipper" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001

Example Request: Disable User at Domain-Level

Only Domain Admins may use this request.

This request will set the user (ID: 25001) profile to inactive in all vaults in your domain. The user will still be a member in the vaults and retain their license types and security profiles, but their user profile will be inactive and they will no longer have access to any vaults in your domain.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "domain_active__v=false" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001

Example Request: Re-Enable User at Domain-Level

Only Domain Admins may use this request.

This request will set the (previously inactive) user (ID: 25001) profile to active in your vault domain. However, they will still be inactive in and unable to access your domain vaults. Use the Update Vault Membership request below to set their status to active in the individual vaults in your domain.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "domain_active__v=false" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001

Example Request: Promote a User to Domain Admin

Only Domain Admins may use this request.

This request will promote a user to Domain Admin. To remove a user from the Domain Admin role, set the is_domain_admin__v field to false. Each domain must have at least one user in the Domain Admin role.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "is_domain_admin__v=true" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001

Example Response

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

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Update Multiple Users

Update information for multiple users at once.

  • The maximum 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.
  • If you want to update profile pictures, you must upload these to the FTP staging server.

PUT /api/{version}/objects/users

Headers

Name Description
Content-Type application/json or text/csv
Accept application/json (default) or text/csv

Body Parameters

Prepare a JSON or CSV input file. The following are the only required fields. You can include any editable user field and value in the input.

Name Description
id The ID of the user to update.

Download Input File

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Users\update_users.csv" \
https://myvault.veevavault.com/api/v12.0/objects/users

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "id":"12021"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12022"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12023"
      },      
      {
         "responseStatus":"FAILURE",
         "id":"22124",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not updated."
            }
         ]
      }
   ]
}

Disable User

Use this request to disable a user in a specific vault or disable a user in all vaults in your domain.

Permissions

  • System Admins and Vault Owners can update users in the vaults where they have administrative access.
  • System Admins who are also Domain Admins have an unrestricted access to users across all vaults in the domain.

Method & Endpoint

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

Request Headers

  • 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 system-managed numerical ID assigned to each user. See Retrieve All Users above.
  • domain=true [Optional] - To disable the user in all vaults in your domain, add this to the request endpoint.

Example Request: Disable User in a Vault

This request will set the user (ID: 25001) profile to inactive in the vault in which the request is made. The user will still be a member in the vault and retain their license type and security profile, but their user profile will be inactive and they will no longer have access to the vault.

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001

Example Request: Disable User in All Domain Vaults

This request will set the user (ID: 25001) profile to inactive in all vaults in your domain. The user will still be a member in the vaults and retain their license types and security profiles, but their user profile will be inactive and they will no longer have access to any vaults in your domain.

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001?domain=true

Example Response

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

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Change User Password

Use this request to change the password of an existing user in your vault or domain.

Method & Endpoint

Send a POST request to the /api/{VERSION}/objects/users/{ID}/password endpoint.

Permissions

  • System Admins and Vault Owners can update users in the vaults where they have administrative access.
  • System Admins who are also Domain Admins have an unrestricted access to users across all vaults in the domain.

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 system-managed numerical ID assigned to each user. See Retrieve All Users above.
  • password__v - Enter the current password.
  • new_password__v - Enter the new password.

Note: The new password must meet the minimum password requirements. Learn about Configuring Password Security Policies in Vault Help.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "password__v=CurrentPassword" \
-d "new_password__v=NewPassword" \
https://myvault.veevavault.com/api/v14.0/objects/users/25496/password

Example Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, the password will be changed and the user will receive an email notification with instructions.

Version History

Available in API v7.0 or later.

Update Vault Membership

Use this request to:

  • Assign an existing user to a vault in your domain.
  • Remove (disable) an existing user from a vault in your domain.
  • Update the security profile and license type of an existing user.

You cannot use this request to:

Additional information:

Permissions

  • System Admins and Vault Owners can update users in the vaults where they have administrative access.
  • System Admins who are also Domain Admins have an unrestricted access to users across all vaults in the domain.

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/users/{ID}/vault_membership/{VAULT_ID} endpoint.

Request Headers

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

Request Parameters

  • {ID} - The system-managed numerical ID assigned to each user. See Retrieve All Users above.
  • {VAULT_ID} - The system-managed numerical ID assigned to each vault in the domain. See Retrieve Domain Vaults above.

Optional Input Values

The following fields and values may be (optionally) submitted with the request:

  • active__v=true - Assigns the user to the vault sets their status to active.
  • active__v=false - Sets the user status to inactive in the vault.
  • security_profile__v={SECURITY_PROFILE} - Assigns the user a specific security profile in the vault.
  • license_type__v={LICENSE_TYPE} - Assigns the user a specific license type in the vault.

See the example requests below for additional information about using these input values.

Example Request: Add User to a Vault

This request will assign the user (ID: 25001) to the vault (ID: 3003). There are a few default settings that will be applied here:

  • The user's status will be set to active in the vault. This is the default setting; the "active__v=true" parameter can omitted and produce the same results.
  • We've not included the optional security_profile__v and license_type__v in the input. Therefore, the user will be assigned a full__v license type and document_user__v security profile by default.
$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "active__v=true" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001/vault_membership/3003

Example Request: Disable User in a Vault

This request will set the user (ID: 25001) profile to inactive in the vault (ID: 3003). They will still be a member in the vault and retain their license type and security profile, but their user profile will be inactive and they will no longer have access to the vault.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "active__v=false" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001/vault_membership/3003

Example Request: Set Security Profile & License Type

This request will set the user (ID: 25001) security profile and license type to specific values in the vault (ID: 3003). If the user is already a member of the vault, this will change their security profile and license type. If the user is not a member of the vault, this will assign them to the vault, set their status to active, and their security profile and license type to the specified values.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "security_profile__v=business_admin__v" \
-d "license_type__v=full__v"
https://myvault.veevavault.com/api/v14.0/objects/users/25001/vault_membership/3003

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Retrieve Your Information

As the logged-in API user, you can use this request to retrieve your own user profile information.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Example Request

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "users": [
        {
            "user": {
                "user_name__v": "quinn.taylor@veevapharm.com",
                "user_first_name__v": "Quinn",
                "user_last_name__v": "Taylor",
                "alias__v": "Vault Admin",
                "user_email__v": "quinn.taylor@veevapharm.com",
                "user_timezone__v": "America/Los_Angeles",
                "user_locale__v": "en_US",
                ...

Version History

Available in API v12.0 or later.

Update Your Information

As the logged-in API user, you can use this request to update your own user profile information.

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/users/me 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.

Optional Input Values

  • You may add or remove values on any editable user field.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "alias__v=API Admin" \
-d "user_timezone__v=America/Denver" \
https://myvault.veevavault.com/api/v14.0/objects/users/me

Example Response

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

Version History

Available in API v12.0 or later.

Change Your Password

As the logged-in API user, you can use this request to change your own password.

Method & Endpoint

Send a POST request to the /api/{VERSION}/objects/users/me/password 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

  • password__v - Enter your current password.
  • new_password__v - Enter your new password.

Note: The new password must meet the minimum password requirements. Learn about Configuring Password Security Policies in Vault Help.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "password__v=MyCurrentPassword \
-d new_password__v=MyNewPassword" \
https://myvault.veevavault.com/api/v14.0/objects/users/me/password

Example Response

{
    "responseStatus": "SUCCESS"
}

Version History

Available in API v12.0 or later.



Groups

Learn about users and groups in Vault Help.


Vault Groups Metadata

The Vault groups object includes the following fields:

Field Name Field Label Field Type Description Required Editable Queryable
id ID id Unique group identifier (primary). Numeric value. System-Managed False True
name__v Name String Unique group identifier. Alphanumeric value. False False True
label__v Label String Unique group identifier. Alphanumeric value. True True True
group_description__v Description String Group description. False True True
members__v Members ObjectReference Users assigned individually (not implied users added via security profile). False True False
implied_members__v Implied Members ObjectReference Users assigned automatically by adding a security profile. False False False
security_profiles__v Security Profiles ObjectReference Security profile to automatically add implied members. False True False
active__v Active Boolean Whether or not the group is active. False True True
type__v Type String User Managed Group or System Provided Group. System-Managed False True
editable__v Editable Boolean Indicates whether or not the group is editable. System-Managed False True
system_group__v System Group Boolean Whether or not the group was automatically created by the system. System-Managed False True
created_date__v Created Date ObjectReference Date and time when the group was created. System-Managed False False
created_by__v Created By ObjectReference Vault User ID of the person who created the group. System-Managed False False
modified_date__v Modified Date ObjectReference Date and time when the group was last modified. System-Managed False False
modified_by__v Modified By ObjectReference Vault User ID of the person who last modified the group. System-Managed False False

The following information may be included with each field:

Field Name Description Comments
name Field Name The name of the group field (id, label__v, members__v, etc.
type Field Type The type of group field. These include "id", "String", "Boolean", or "ObjectReference".
object Object When the group type is ObjectReference, this indicates the name of the object being referenced by the field.
multivalue Multi-Value Indicates if the field can have multiple values.
queryable Queryable Indicates if the field can be used as a keyword search parameter to search for groups.
length Length When the field type is "String", this field indicates the maximum character length which can be used.
required Required Indicates if the field is required when creating a group.
onCreateEditable On Create Editable Indicates if the field can be set during creation of a new group.
editable Editable Indicates if the field can be set or changed by the user, i.e., not system-managed.


Retrieve Group Metadata

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Example Request

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "properties": [
        {
            "name": "id",
            "type": "id",
            "length": 20,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "label__v",
            "type": "String",
            "length": 255,
            "editable": true,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "name__v",
            ...
        },        
        {
            "name": "group_description__v",
            ...
        },
        {
            "name": "system_group__v",
            ...
        },
        {
            "name": "created_date__v",
            ...
        },
        {
            "name": "created_by__v",
            ...
        },
        {
            "name": "modified_date__v",
            ...
        },
        {
            "name": "modified_by__v",
            ...
        },
        {
            "name": "members__v",
            ...
        },
        {
            "name": "implied_members__v",
            ...
        },
        {
            "name": "security_profiles__v",
            ...
        },
        {
            "name": "active__v",
            ...
        }, 
        {
            "name": "editable__v",
            ...
        },
        {
            "name": "type__v",
            ...
        }                     
    ]
}

Version History

Retrieve group metadata is available in API v2.0 or later.
The security_profile__v and implied_members__v fields are available in API v12.0 or later.


Retrieve All Groups

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

includeImplied=true - Optional parameter used to shown which group members are "implied members". See the Retrieve Group request below for details.

Example Request

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

Example Response (abridged)

{
  "responseStatus": "SUCCESS",
  "groups": [
     {
      "group": {
        "members__v": [
          25516,
          25527
        ],
        "active__v": true,
        "security_profiles__v": [
          "business_admin__v"
        ],
        "name__v": "business_administrators__v",
        "modified_by__v": 25496,
        "editable__v": true,
        "modified_date__v": "2013-01-23T22:07:53.000Z",
        "group_description__v": "All Business Administrators (System Provided Group)",
        "system_group__v": true,
        "label__v": "Business Administrators",
        "created_date__v": "2013-01-08T16:33:50.000Z",
        "type__v": "System Provided Group",
        "id": 4,
        "created_by__v": 1
      }
    },
    {
      "group": {
        "members__v": [
          25518,
          25519,
          25520,
          25522,
          25524,
          25525,
          25526,          
        ],
        "active__v": true,
        "security_profiles__v": [],
        "name__v": "cholecap_editors_group__c",
        "modified_by__v": 46916,
        "editable__v": true,
        "modified_date__v": "2015-06-24T20:11:17.000Z",
        "group_description__v": "Document Editors on the Cholecap Team",
        "system_group__v": false,
        "label__v": "Cholecap Editors Group",
        "created_date__v": "2015-06-24T20:11:17.000Z",
        "type__v": "User Managed Group",
        "id": 1435176677013,
        "created_by__v": 46916
      }
    },

Version History

Retrieve groups is available in API v2.0 or later.
The security_profile__v and implied_members__v fields are available in API v12.0 or later.


Retrieve Group

Method & Endpoint

Send aGET request to the /api/{VERSION}/objects/groups/{ID} endpoint.

Request Headers

  • 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 group id field value.
  • includeImplied=true - Optional parameter used to shown which group members are "implied members". See alternate request below.

Example Request

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

Example Response

{
  "responseStatus": "SUCCESS",
  "groups": [
     {
      "group": {
        "members__v": [
          45501,
          45502,
          61748,
          61749,
          61750
        ],
        "active__v": true,
        "security_profiles__v": [
          "document_user__v"
        ],
        "name__v": "cholecap_us_compliance_group__c",
        "modified_by__v": 46916,
        "editable__v": true,
        "modified_date__v": "2015-11-13T21:12:56.000Z",
        "group_description__v": "Cholecap Team US Compliance",
        "system_group__v": false,
        "label__v": "Cholecap US Compliance Group",
        "created_date__v": "2015-11-13T21:12:56.000Z",
        "type__v": "User Managed Group",
        "id": 1358979070034,
        "created_by__v": 46916
      }
    }
  ]
}

Request Details

The example request above lists all members and other metadata configured for this group.

  • The group has 5 members. Some of these are "implied members" and others were manually added (see the alternate request below).
  • The group has been configured with a security profile. All users with the document_user__v security profile are automatically members of this group. These are the "implied members".

Alternate Request (Show Implied Members)

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/groups/1358979070034?includeImplied=true

Example Response

{
  "responseStatus": "SUCCESS",
  "groups": [
     {
      "group": {
        "members__v": [
          45501,
          45502,
          61748,
          61749,
          61750
        ],
        "implied_members__v": [
          {
            "id": 61748,
            "source_type": "security_profile",
            "source_name": "document_user__v"
          },
          {
            "id": 61749,
            "source_type": "security_profile",
            "source_name": "document_user__v"
          },
          {
            "id": 61750,
            "source_type": "security_profile",
            "source_name": "document_user__v"
          }
        ],
        "active__v": true,
        "security_profiles__v": [
          "document_user__v"
        ],
        "name__v": "cholecap_team_us__c",
        "modified_by__v": 46916,
        "editable__v": true,
        "modified_date__v": "2015-11-13T21:10:05.000Z",
        "group_description__v": "Cholecap Team US Compliance",
        "system_group__v": false,
        "label__v": "Cholecap Team US",
        "created_date__v": "2013-01-23T22:11:10.000Z",
        "type__v": "User Managed Group",
        "id": 1358979070034,
        "created_by__v": 25496
      }
    }
  ]
}

Response Details

The alternate request above uses the optional includeImplied=true parameter.

  • All users with the security profile document_user__v are automatically members of this group. These are the "implied members".
  • The other two users shown (45501 & 45502) were manually added to this group.

Version History

Retrieve group is available in API v2.0 or later.
The security_profile__v and implied_members__v fields are available in API v12.0 or later.


Create Group

Method & Endpoint

Send a POST request to the /api/{VERSION}/objects/groups 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.

Input Requirements

When creating new groups, label__v is the only required field. The following group fields are optional:

  • security_profiles__v - Add one or more security profiles. All users with the security profile will automatically be added as implied members of the group.
  • members__v - Include the IDs of all users who will be members of the group. These are separate from and/or in addition to implied members added via a security profile.
  • group_description__v - Add a description of the group.
  • active__v - By default, the new group will be created as active. To set the group to inactive, set this value to false.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "label__v=Cholecap Team US Compliance" \
-d "members__v=45501,45002" \
-d "security_profiles__v=document_user__v"
https://myvault.veevavault.com/api/v14.0/objects/groups

Example Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Group successfully created.",
  "id": 1358979070034
}

Version History

Create group is available in API v2.0 or later.
The security_profile__v and implied_members__v fields are available in API v12.0 or later.


Update Group

Method & Endpoint

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

Request Headers

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

Request Parameters

{ID} - The group id field value.

Update Fields

You may change the values of any editable group field.

  • Changing the security_profiles__v will automatically replace all previous implied users assigned via the previous security profile.
  • All user IDs included in members__v will replace all previous users who were manually assigned. This action is not additive.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "label__v=Cholecap Team" \
-d "members__v=45501,45502,45503,45004" \
https://myvault.veevavault.com/api/v14.0/objects/groups/1358979070034

Example Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Group successfully updated.",
  "id": 1358979070034
}

Version History

Update group is available in API v2.0 or later.
The security_profile__v and implied_members__v fields are available in API v12.0 or later.


Delete Group

Method & Endpoint

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

Request Headers

  • 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 group id field value.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/groups/1358979070034

Example Response

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

Version History

Available in API v2.0 or later.



Picklists

The Picklists API allows you to manage the values that appear in your vault's picklist fields. The API does not support creating or updating the picklists themselves, this must be done in the Admin UI. Learn about managing picklists.

Retrieve All Picklists

Use this request to retrieve a list of all standard and custom picklists in your vault.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Example Request

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

Example Response (abridged)

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "errorCodes": null,
  "picklists": [
    {
      "name": "audience__vs",
      "label": "Audience",
      "kind": "document",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "audience__vs"
        }
      ]
    },
    {
      "name": "claim_category__vs",
      "label": "Claim Category",
      "kind": "document",
      "usedIn": [
        {
          "documentTypeName": "claim__vs",
          "propertyName": "claim_category__vs"
        }
      ]
    },
    {
      "name": "language__v",
      "label": "Language",
      "kind": "document",
      "system": true,
      "usedIn": [
        {
          "documentTypeName": "base_document__v",
          "propertyName": "language__v"
        }
      ]
    },
    {
      "name": "product_family__vs",
      "label": "Product Family",
      "kind": "object",
      "usedIn": [
        {
          "objectName": "product__v",
          "propertyName": "product_family__vs"
        }
      ]
    },
    {
      "name": "regions__c",
      "label": "Regions",
      "kind": "object",
      "usedIn": [
        {
          "objectName": "product__v",
          "propertyName": "regions__c"
        }
      ]
    },
    {
      "name": "therapeutic_area__vs",
      "label": "Therapeutic Area",
      "kind": "object",
      "usedIn": [
        {
          "objectName": "product__v",
          "propertyName": "therapeutic_area__vs"
        }
      ]
    },
    {
      "name": "license_type__v",
      "label": "License Type",
      "kind": "user",
      "system": true
    }
  ],
  "errorType": null
}

Response Details

The response lists the names and labels of all picklists configured in your vault. These include the following picklist properties:

Picklist Property Description Comments
name Picklist Name The name of the picklist, e.g., study_status__vs.
label Picklist Label The label of the picklist as seen in the UI, e.g., "Study Status".
system System (true/false) Indicates if the picklist is system-managed.
kind Picklist Kind - document picklists are used in document fields.
- object picklists are used in object fields.
- global picklists are used in milestone_type__v fields (eTMF Vaults).
- user picklists are used in user fields.
usedIn Used In For document picklists, this indicates:
- the document type in which the picklist is defined (see documentTypeName).
- the related field name (see propertyName).
For object picklists, this indicates:
- the object in which the picklist is defined (see objectName).
- the related field name (see propertyName).
For global picklists, this indicates:
- both the document type and the object in which the picklist is defined.
- the related field names for each (see propertyName).
documentTypeName Document Type Name For document and global picklists, this the document type name in which the picklist is defined.
objectName Object Name For object picklists, this is the object name in which the picklist is defined.
For global picklists, the object is milestone__v (eTMF vaults).
propertyName Property Name For document picklists, this is the document field name using the picklist.
For object picklists, this is the object field name using the picklist.
For global picklists, this is the milestone_type__v picklist (eTMF vaults).

Possible Errors

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

Version History

Available in API v4.0 or later.
As of v12.0, the new picklist type global was added to all vaults.
As of v12.0, the new standard picklist milestone_type__v was added to eTMF vaults.

Retrieve Picklist Values

Use this request to retrieve all values (names and labels) currently configured on an existing picklist in your vault.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

  • {NAME} - The name of the existing picklist to which you're adding new values (language__v, therapeutic_area__vs, regions__c, etc.).
  • To see all picklists configured in your vault, use the "Retrieve All Picklists" endpoint above.

Example Request

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

Example Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "picklistValues": [
    {
      "name": "europe__c",
      "label": "Europe"
    },
    {
      "name": "asia_pacific__c",
      "label": "Asia Pacific"
    },
    {
      "name": "australasia__c",
      "label": "Australasia"
    },
    {
      "name": "middle_east__c",
      "label": "Middle East"
    }
  ]
}

Possible Errors

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

Version History

Available in API v4.0 or later.
As of v12.0, the new picklist type global was added to all vaults.
As of v12.0, the new standard picklist milestone_type__v was added to eTMF vaults.

Create Picklist Values

Use this request to add new values to an existing picklist. You can add up to 1024 values to any picklist.

Method & Endpoint

Send a POST request to the /api/{VERSION}/objects/picklists/{NAME} 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

  • {NAME} - The name of the existing picklist to which you're adding new values (language__v, therapeutic_area__vs, regions__c, etc.).
  • To see all picklists configured in your vault, use the "Retrieve All Picklists" endpoint above.
  • To see all names and labels currently configured on an existing picklist, use the "Retrieve Picklist Values" endpoint above.

Name-Value Pair Input Requirements

  • To add new values, use the picklist property name (value_1=, value_2=, value_3=, etc.).
  • Enter new picklist value labels as they will be displayed in the UI. Example: "value_1=North America" (surrounded by double-quotes).

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "value_1=North America" \
-d "value_2=Central America" \
-d "value_3=South America" \
https://myvault.veevavault.com/api/v13.0/objects/picklists/regions__c

Example Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Created picklist value(s).",
  "picklistValues": [
    {
      "name": "north_america__c",
      "label": "North America"
    },
    {
      "name": "central_america__c",
      "label": "Central America"
    },
    {
      "name": "south_america__c",
      "label": "South America"
    }
  ]
}

Possible Errors

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

Version History

Available in API v4.0 or later.
As of v12.0, the new picklist type global was added to all vaults.
As of v12.0, the new standard picklist milestone_type__v was added to eTMF vaults.

Update Picklist Value Label

Use this request to update the labels (only) for existing picklist values in your vault. To update picklist value names, refer to the section below.

CAUTION: This may break existing integrations that access picklist values via the API. Use caution when editing picklist labels or names. When these attributes are changed, they affect all existing document and object metadata that refer to the picklist. For users in the UI who are accustomed to seeing a particular selection (picklist label), the changes may also cause confusion.

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/picklists/{NAME} 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

  • {NAME} - The name of the existing picklist to which you're updating labels (language__v, therapeutic_area__vs, regions__c, etc.).
  • To see all picklists configured in your vault, use the "Retrieve All Picklists" endpoint above.
  • To see all names and labels currently configured on an existing picklist, use the "Retrieve Picklist Values" endpoint above.

Name-Value Pair Input Requirements

  • To change existing values, use the existing picklist name (north_america__c=, central_america__c=, etc.) and enter new labels as they will be displayed in the UI.
  • For example, to change the label of the existing "north_america__c=North America", enter "north_america__c=North America/United States".

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "north_america__c=North America/United States" \
https://myvault.veevavault.com/api/v13.0/objects/picklists/regions__c

Example Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Updated picklist value(s).",
  "picklistValues": [
    {
      "name": "north_america__c",
      "label": "North America/United States"
    }
  ]
}

As shown above, only the picklist value label has been changed. The picklist value name remains the same. All documents and objects that refer to the specified picklist value will be updated as well.

Possible Errors

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

Version History

Available in API v4.0 or later.
As of v12.0, the new picklist type global was added to all vaults.
As of v12.0, the new standard picklist milestone_type__v was added to eTMF vaults.

Update Picklist Value Name

Use this request to update the name (only) of an existing picklist value in your vault. To update picklist value labels, refer to the section above.

CAUTION: This may break existing integrations that access picklist value via the API. Use caution when editing picklist labels or names. When these attributes are changed, they affect all existing document and object metadata that refer to the picklist. For users in the UI who are accustomed to seeing a particular selection (picklist label), the changes may also cause confusion.

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/picklists/{NAME}/{PICKLIST_VALUE_NAME} 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

  • {NAME} - The name of the existing picklist to which you're updating names (language__v, therapeutic_area__vs, regions__c, etc.).
  • {PICKLIST_VALUE_NAME} - The existing picklist value name which you are changing (north_america__c=, central_america__c=, etc.).
  • To see all picklists configured in your vault, use the "Retrieve All Picklists" endpoint above.
  • To see all names and labels currently configured on an existing picklist, use the "Retrieve Picklist Values" endpoint above.

Name-Value Pair Input Requirements

  • To change an existing name, use the picklist property name (name=) set to the new name.
  • For example, to change the existing north_america__c pickist value name, enter "name=north_america_united_states".
  • Do not include the __c suffix with the new name. Vault will automatically add this after updating.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name=north_america_united_states" \
https://myvault.veevavault.com/api/v13.0/objects/picklists/regions__c/north_america__c

Example Response

{
  "responseStatus": "SUCCESS"
}

Only the picklist value name has been changed. The picklist value label remains the same. All documents and objects that refer to the specified picklist value will be updated as well.

Possible Errors

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

Version History

Available in API v10.0 or later.
As of v12.0, the new picklist type global was added to all vaults.
As of v12.0, the new standard picklist milestone_type__v was added to eTMF vaults.

Delete Picklist Value

Use this request to delete a value from an existing picklist in your vault.

CAUTION: This may break existing integrations that access picklist value via the API. When these attributes are changed, they affect all existing document and object metadata that refer to the picklist. For users in the UI who are accustomed to seeing a particular selection (picklist label), the changes may also cause confusion.

Method & Endpoint

Send a DELETE request to the /api/{VERSION}/objects/picklists/{NAME}/{PICKLIST_VALUE_NAME} endpoint.

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

  • {NAME} - The name of the existing picklist to which you're updating names (language__v, therapeutic_area__vs, regions__c, etc.).
  • {PICKLIST_VALUE_NAME} - The existing picklist value name which you are deleting (north_america__c=, central_america__c=, etc.).
  • To see all picklists configured in your vault, use the "Retrieve All Picklists" endpoint above.
  • To see all names and labels currently configured on an existing picklist, use the "Retrieve Picklist Values" endpoint above.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v13.0/objects/picklists/regions__c/north_america_united_states__c

Example Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Deleted picklist value.",
  "name": "north_america_united_states__c"
}

Possible Errors

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

Version History

Available in API v4.0 or later.
As of v12.0, the new picklist type global was added to all vaults.
As of v12.0, the new standard picklist milestone_type__v was added to eTMF vaults.



Lifecycles

Document lifecycles are the sequences of states (Draft, In Review, etc.) a document goes through during its life. A lifecycle can be simple (two states requiring users to manually move between states) or very complex (multiple states with different security and workflows that automatically move the document to another state). In Vault, lifecycles simplify the implementation of business logic that traditionally required custom coding or time-consuming manual setup.

Lifecycle states are the ordered states within a lifecycle represent the stages a document transitions through as users create, review, approve and eventually archive or replace it. A set of business rules applies to each state and defines what happens to the document in that state. Admins define these rules for each lifecycle state and Vault automatically applies them to every document that enters the state.

Business Rules: Each state has the following configuration options:

  • User Actions: Actions that end users can perform on a document.
  • Security Settings: Permissions that users in each role have for a document.
  • Entry Criteria: Conditions that a document must meet before transitioning into this state.
  • Entry Actions: Actions that Vault performs automatically when a document enters this state.

Learn about Lifecycles & Workflows in Vault Help.

Document & Binder Lifecycle Actions

The API supports initiating lifecycle actions on documents and binders.

Supported Lifecycle Actions

  • Change the State of a Document or Binder
  • Start a Workflow
  • Obtain a Controlled Copy
  • Create Presentation

Entry Requirements

Before users can initiate a lifecycle action, the document or binder must satisfy certain entry requirements. Entry requirements are dynamic and depend on the lifecycle configuration, entry criteria defined for the lifecycle state, and/or the workflow activation requirements defined in the Start Step of the workflow.

Property Scope

The API specifies the scope for the each requirement:

  • Document scope means that the property is document-level and must be updated on the document before initiating the lifecycle action.
  • Binder scope means that the property is binder-level and must be updated on the binder before initiating the lifecycle action.
  • Workflow scope means that the property is workflow-level and must be specified at the time of action initiation.
  • Controlled Copy scope means that the property is controlled copy specific and must be specified at the time of action initiation.

Typical Implementation

In a typical implementation, the client requests the available lifecycle actions using the Get Lifecycle Actions endpoint. The response to this call lists lifecycle actions that the current user can initiate on a document or a binder specified by its ID and version.

Overview of Steps

Step 1: Retrieve Lifecycle Actions

  • Retrieve a list of available lifecycle actions ("User Actions" in the UI) that can be initiated on a specific version of a document or binder.
  • The response includes the name of each lifecycle action used to initiate the action and the endpoint to retrieve the entry requirements.

Step 2: Retrieve Entry Requirements

  • Before initiating a lifecycle action, you need to ensure that the document or binder meets certain conditions (required fields are populated, etc.).
  • For example, you don't need to assign a user to the "Approver" role when the document is first uploaded, but you do need to when initiating the "Start Approval" workflow.
  • Not all lifecycle actions have entry requirements. In these cases, you can simply proceed with initiation of the lifecycle action.
  • When the entry requirement "scope": "WorkflowActivation", the values can be specified as name-value pairs with the lifecycle initiation request.
  • When the entry requirement "scope": "Document" or "scope": "Binder" the values must first be updated on the document or binder before initiating the request.

Step 3: Initiate Lifecycle Action

  • Once you've determined the entry requirements and completed those which must be configured separately, you can initiate the lifecycle action.
  • Vault will evaluate whether all the entry requirements have been met and, if so, will initiate the lifecycle action on the specified version of the document or binder.

Retrieve Lifecycle Actions

Retrieve all available lifecycle actions that can be initiated on a specific version of a document or binder.

Request

Documents: Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions
Binders: Send GET to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

document_id - The document id field value from which to retrieve available lifecycle actions.
binder_id - The binder id field value from which to retrieve available lifecycle actions.
major_version_number__v - The major version number of the document or binder.
minor_version_number__v - The minor version number of the document or binder.

Example

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "lifecycle_actions__v": [
    {
      "name__v": "startApproval",
      "label__v": "Start Approval",
      "lifecycle_action_type__v": "workflow",
      "entry_requirements__v": "https://myvault.veevavault.com/api/v13.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval/entry_requirements"
    },
    {
      "name__v": "approve",
      "label__v": "Approve",
      "lifecycle_action_type__v": "stateChange",
      "entry_requirements__v": "https://myvault.veevavault.com/api/v13.0/objects/documents/222/versions/0/1/lifecycle_actions/approve/entry_requirements"
    }
  ]
}

Details

The response lists all available lifecycle actions (lifecycle_actions__v) that can be initiated on the specified version of the document or binder.

  • name__v - The lifecycle action name (consumed by the API). These vary from vault to vault and may be text, numeric, or alphanumeric values.
  • label__v - The lifecycle action label. This is the "User Action" label seen in the UI.
  • lifecycle_action_type__v - The workflow and stateChange types are the most commonly used and are available in all vaults. Others may exist.
  • entry_requirements__v - The endpoint to retrieve the entry requirements for each lifecycle action. If no entry requirements exist, this will be excluded from the response.

Note that lifecycle actions are not returned for documents or binders which are currently in an active workflow.

History

Since v6

Retrieve Entry Requirements

Once you've retrieved the available lifecycle actions, you can retrieve the entry requirements for a specific lifecycle action.

Request

Documents: Send GET to /api/{version}/objects/documents/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{name__v}/entry_requirements
Binders: Send GET to /api/{version}/objects/binders/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{name__v}/entry_requirements

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

document_id - The document id field value from which to retrieve available lifecycle actions.
binder_id - The binder id field value from which to retrieve available lifecycle actions.
major_version_number__v - The major version number of the document or binder.
minor_version_number__v - The minor version number of the document or binder.
name__v - The lifecycle name__v field value from which to retrieve entry requirements. This is retrieved from the Retrieve Lifecycle Action request above.

Example

In this request, we'll retrieve the entry requirements for the "Start Approval" workflow.

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval/entry_requirements

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "properties": [
    {
      "name": "dueDate",
      "description": "Approval Due Date",
      "type": [
        "Date"
      ],
      "required": true,
      "editable": true,
      "scope": "WorkflowActivation"
    },
    {
      "name": "Approver",
      "description": "Approver",
      "type": [
        "ObjectReference"
      ],
      "objectTypeReferenced": {
        "name": "User",
        "label": "User"
      },
      "required": true,
      "editable": true,
      "repeating": true,
      "scope": "WorkflowActivation"
    }
  ]
}

Details

The response above shows two entry requirements to start the approval workflow on this document: dueDate and Approver.

  • You must assign an Approval Due Date and users/groups to the Approver role on the document when initiating the lifecycle action.
  • Unlike the response from the next example, the Scope for these fields is set to WorkflowActivation ("scope": "WorkflowActivation").
  • This scope means that you can initiate the lifecycle action by including these entry requirements as name-value pairs with the request.

See the Initiate Lifecycle Action section below for more information.

Example

In this request, we'll retrieve the entry requirements to change the state of a document from "Draft" to "Approved".

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/objects/documents/222/versions/0/1/lifecycle_actions/approve/entry_requirements

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "properties": [
    {
      "name": "country__v",
      "description": "Country",
      "type": [
        "ObjectReference"
      ],
      "objectTypeReferenced": {
        "name": "country__v",
        "label": "Country",
        "url": "/api/v14.0/metadata/vobjects/country__v",
        "label_plural": "Countries"
      },
      "editable": true,
      "repeating": true,
      "scope": "Document",
      "records": "/api/v14.0/vobjects/country__v"
    }
  ]
}

Details

The response above shows one entry requirement to change the state of this document from "Draft" to "Approved": country__v.

  • You must assign a value to the Country document field before initiating the lifecycle action.
  • Unlike the response from the previous example, the Scope for this field is set to Document ("scope": "Document").
  • This scope means that you must first update this field on the document before initiating the lifecycle action.

See the Initiate Lifecycle Action section below for more information.

The response may include the following metadata elements describing the properties for which values need to be specified:

Property Description
name The entry requirement name (used in the API). This value must be specified when starting the lifecycle action.
description The entry requirement name (used in the UI).
type The entry requirement data type. This value can be one of String, Number, Date, Boolean, Picklist, or ObjectReference.
objectTypeReferenced When type is ObjectReference, this is the object being reference. For example: User, Product, Country, etc.
required Boolean value indicating whether or not the entry requirement must be specified when initiating a lifecycle action.
editable Boolean value indicating whether or not the value can be edited by the user.
repeating Boolean value indicating whether or not the entry requirement can have multiple values.
minValue Indicates the minimum character length for the value.
maxValue Indicates the maximum character length for the value.
values When type is Picklist, this provides a list of possible values that can be used.
currentSetting When a value has already been set, this shows the value.
scope Indicates where the property is defined. This value can be one of Document, Binder, WorkflowActivation, EmailFragment, ControlledCopy, or CreatePresentation.

History

Since v6

Initiate Lifecycle Action

Once you've identified the entry requirements, you can initiate the lifecycle action.

Request

Documents: Send PUT to /api/{version}/objects/documents/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{LIFECYCLE_ACTION}
Binders: Send PUT to /api/{version}/objects/binders/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{LIFECYCLE_ACTION}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

document_id - The document id field value from which to retrieve available lifecycle actions.
binder_id - The binder id field value from which to retrieve available lifecycle actions.
major_version_number__v - The major version number of the document or binder.
minor_version_number__v - The minor version number of the document or binder.
name__v - The lifecycle name__v field value from which to retrieve entry requirements. This is retrieved from the Retrieve Lifecycle Action request above.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "dueDate=2015-12-25" \
-d "Approver=user:12021,user:12022,group:10030003" \
https://myvault.veevavault.com/api/v14.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval

This request is initiating a workflow activation lifecycle action on the document. We're initiating the "Start Approval" workflow.

  • Recall from the discussion in the previous section that the two entry requirements are to assign a values to the dueDate and Approver fields.
  • The entry requirement Scope is set to WorkflowActivation ("scope": "WorkflowActivation"), meaning the values can be included as a name-value pairs with the request.
  • Format the dueDate value as shown above. To assign users and/or groups to the Approver role, include a comma-separated list of user and group id field values.

On submitting this request, Vault will evaluate whether all the entry requirements have been met and, if so, initiate the lifecycle action.

Response

{
  "responseStatus": "SUCCESS",
  "id": 222,
  "workflow_id__v": "115"
}

Details

On SUCCESS, Vault returns the document id field value of the document on which the lifecycle action has been initiated and the workflow workflow_id__v field value of the workflow. This document ("id": 222) is now in the "Start Approval" workflow ("workflow_id__v": "115"). On FAILURE, Vault returns an error type and message describing the reason for the error. The lifecycle action will not be initiated until all errors have been corrected.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/objects/documents/222/versions/0/1/lifecycle_actions/approve

This request is initiating a state change lifecycle action on the document. We're changing the state from "Draft" to "Approved".

  • Recall from the discussion in the previous section that the only entry requirement is to assign a value to the document's country__v field.
  • The entry requirement Scope is set to Document ("scope": "Document"), meaning the country field value cannot be included as a name-value pair with the request.
  • Instead, before submitting this request, we used a separate Update Document request to update the country field on the document. This fulfilled the entry requirement.
  • Therefore, we do not need to specify the input format (there is no input requirement) and the request can be submitted as shown in this example.

Response

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

Details

On SUCCESS, Vault returns the document id field value of the document on which the lifecycle action has been initiated. This document ("id": 222) was previously version 0.1 (Draft State). It is now version 1.0 (Approved/Steady State). On FAILURE, Vault returns an error type and message describing the reason for the error. The lifecycle action will not be initiated until all errors have been corrected.

History

Since v6

Bulk Document State Change

Currently, you can only begin a Read & Understood workflow using this functionality. For each bulk action, you may only select a single workflow that Vault will start for all selected and valid documents.

Request

Documents: Send PUT to /api/{version}/objects/documents/lifecycle_actions/{lifecycle_action_name}
Binders: Send PUT to /api/{version}/objects/binders/lifecycle_actions/{lifecycle_action_name}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{lifecycle_action_name} - The lifecycle action name__v field value.

Input

Field Name Description
docIDs Include a comma-separated list of document or binder IDs, major and minor version numbers, as shown below.
lifecycle Include the name of the document or binder lifecycle.
state Include the name of the state to which the documents or binders will be changed.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIDs=222:0:1,223:0:1,224:0:1,225:0:1" \
-d "lifecycle=general_lifecycle__vs" \
-d "state=approved__vs" \
https://myvault.veevavault.com/api/v15.0/objects/documents/lifecycle_actions/approve__c

In this example:

  • The input file format is set to accept name-value inputs.
  • The documents and versions are specified. We're changing the state of version 0.1 of document IDs 222, 223, 224, and 225.
  • The lifecycle is specified. These documents are assigned to the general_lifecycle__vs.
  • The state is specified. We're changing the state of all four documents to approved.

Response

{
  "responseStatus": "SUCCESS"
}

History

Since v12

Lifecycle Role Assignment Rules

For both standard and custom roles, you can define a subset of users who are allowed in the role and define users that Vault automatically assigns to the role at document creation or when a workflow starts. You can also override the allowed users and default users settings based on standard object-type document fields like Country, Product, Study, etc.

Vault Help Resources

Learn about Lifecycles & Workflows
Learn about Defining Allowed & Default Users for Roles
Learn about Users & Groups
Learn about Fields & Objects

Note the following limitations:

  • The API can only be used with active lifecycles and roles.
  • The maximum number of roles that can be created or updated per request is 50,000.
  • The lifecycle role default rule cannot be set when creating override rules.
  • A role cannot be assigned more users or groups to default roles than allowed on the role.
  • The default owner__v role cannot be edited.

Retrieve Lifecycle Role Assignment Rules (Default & Override)

Request

Send GET to api/{version}/configuration/role_assignment_rule

Headers

Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Parameters

This endpoint alone will retrieve a list of all lifecycle role assignment rules (default & override) from all roles in all lifecycles in your vault.

To filter the results by lifecycle or role, add one or both of the following parameters to the request endpoint:

  • lifecycle__v={lifecycle_name} - Include the name of the lifecycle from which to retrieve information. For example: lifecycle__v=general_lifecycle__vs
  • role__v={role_name} - Include the name of the role from which to retrieve information. For example: role__v=editor__c

For example, to retrieve the lifecycle role assignment rules (default & override) from:

  • All roles in a specific lifecycle, use api/{version}/configuration/role_assignment_rule?lifecycle__v={lifecycle_name}
  • A specific role in all lifecycles, use api/{version}/configuration/role_assignment_rule?role__v={role_name}
  • A specific role in a specific lifecycle, use api/{version}/configuration/role_assignment_rule?lifecycle__v={lifecycle_name}&role__v={role_name}

The response will include:

  • The default role assignments.
  • The override role assignments when an override condition (when configured on the role) is met.
  • The override conditions (when configured on the role).

You can also filter the results by one or more override conditions. This can be included with the filters above or used on its own to retrieve the information from all roles in all lifecycles in which the conditions have been configured.

For example, to retrieve lifecycle role override rules when the product "CholeCap" and country "United States" are assigned to a document:

  • Use the system-managed object record id field values: api/{version}/configuration/role_assignment_rule?product__v=0PR0011001&country__v=0CR0022002
  • Or, use the object record name__v field values (via object__v.name__v lookup): api/{version}/configuration/role_assignment_rule?product__v.name__v=CholeCap&country__v.name__v=United States

The response will exclude the default role assignments and only return the override conditions and role assignments when the override condition is met.

Example

Retrieve lifecycle role assignment rules from a specific role (editor__c) in a specific lifecycle (general_lifecycle__vs):

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__vs&role__v=editor__c

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "lifecycle__v": "general_lifecycle__vs",
            "role__v": "editor__c",
            "allowed_users__v": [
                "ally@veevapharm.com",
                "beth@veevapharm.com",
                "cruz@veevapharm.com",
                "dave@veevapharm.com"
            ],
            "allowed_groups__v": [
                "global_products_team__c",
                "vault_products_team__c",
                "vault_doc_management__c"
            ],
            "allowed_default_users__v": [
                "ally@veevapharm.com"
            ],
            "allowed_default_groups__v": [
                "global_products_team__c"
            ]
        },
        {
            "lifecycle__v": "general_lifecycle__vs",
            "role__v": "editor__c",
            "product__v.name__v": "CholeCap",
            "country__v.name__v": "United States",
            "product__v": "0PR0011001",
            "country__v": "0CR0022002",
            "allowed_users__v": [
                "etta@veevapharm.com",
                "finn@veevapharm.com",
                "greg@veevapharm.com",
                "hope@veevapharm.com"                
            ],
            "allowed_groups__v": [
                "cholecap_us_docs_group__c",
                "cholecap_us_research_group__c",
                "cholecap_us_compliance_group__c",
                "cholecap_us_product_management_group__c"
            ],
            "allowed_default_users__v": [
                "etta@veevapharm.com"
            ],
            "allowed_default_groups__v": [
                "cholecap_us_docs_group__c"
            ]
        }
    ]
}

Details

In the example response above, the editor__c role in the general_lifecycle__vs lifecycle is configured with the following role assignment rules:

Default Rule

When a document is assigned this lifecycle, the following users and groups are automatically assigned to the editor__c role:

  • allowed_default_users__v - The user ally@veevapharm.com is automatically assigned to the role.
  • allowed_users__v - The users beth@veevapharm.com, cruz@veevapharm.com, and dave@veevapharm.com can be (optionally) assigned to the role at any time during the lifecycle.
  • allowed_default_groups__v - The group global_products_team__c is automatically assigned to the role.
  • allowed_groups__v - The groups vault_products_team__c and vault_doc_management__c can be (optionally) assigned to the role at any time during the lifecycle.

Override Conditions

This lifecycle role has been configured with two override conditions which state: If both the product "CholeCap" and country "United States" are assigned to a document, do not apply the default rule, but instead apply the override rule.

The API returns both the system-managed object record id and the user-defined object record name__v (via the object__v.name__v lookup) field values which define the override conditions:

  • "product__v.name__v": "CholeCap" - The product object record name.
  • "country__v.name__v": "United States" - The country object record name.
  • "product__v": "0PR0011001" - The product object record ID.
  • "country__v": "0CR0022002" - The country object record ID.

Override Rule

When both the product "CholeCap" and country "United States" are assigned (at any time) to a document in this lifecycle, the following (alternate) users and groups are automatically assigned to the editor__c role:

  • allowed_default_users__v - The user etta@veevapharm.com is automatically assigned to the role.
  • allowed_users__v - The users finn@veevapharm.com, greg@veevapharm.com, and hope@veevapharm.com can be (optionally) assigned to the role during its lifecycle.
  • allowed_default_groups__v - The group cholecap_us_docs_group__c is automatically assigned to the role.
  • allowed_groups__v - The groups cholecap_us_research_group__c, cholecap_us_compliance_group__c, and cholecap_us_product_management_group__c can be (optionally) assigned to the role during its lifecycle.

Note: If the lifecycle role has not been configured with an override rule, the response will only display the default rule.

Errors

On failure, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Create Override Rules

Request

Send POST to api/{version}/configuration/role_assignment_rule

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Input

Before submitting this request, prepare a JSON or CSV input file with the following information:

  • The name__v field values of the lifecycle and role to which the override rule is being added.
  • The id or name__v field values of the object records which define the override condition.
  • The user_name__v field values of the allowed and default users who will be assigned to the role when the override condition is met.
  • The name__v field values of the allowed and default groups who will be assigned to the role when the override condition is met.

Note the following scope and limitations:

  • This request can only be used to specify the override rules (conditions, users, and groups). It cannot be used to configure the default rules.
  • The input may include override rules for multiple lifecycles and roles.
  • Each role may be configured with multiple override rules.

Example CSV & JSON Input Files

Create an override rule on the editor__c role of the general_lifecycle__vs with the following override conditions, users, and groups:

lifecycle__v role__v product__v.name__v country__v.name__v allowed_users__v allowed_groups__v allowed_default_users__v allowed_default_groups__v
general_lifecycle__vs editor__c CholeCap United States "etta@veevapharm.com,finn@veevapharm.com,greg@veevapharm.com,hope@veevapharm.com" "cholecap_us_docs_group__c,cholecap_us_research_group__c,cholecap_us_compliance_group__c,cholecap_us_product_management_group__c" etta@veevapharm.com cholecap_us_docs_group__c
[
{
    "lifecycle__v": "general_lifecycle__vs",
    "role__v": "editor__c",
    "product__v.name__v": "CholeCap",
    "country__v.name__v": "United States",
    "allowed_users__v": [
        "etta@veevapharm.com",
        "finn@veevapharm.com",
        "greg@veevapharm.com",
        "hope@veevapharm.com"                
    ],
    "allowed_groups__v": [
        "cholecap_us_docs_group__c",
        "cholecap_us_research_group__c",
        "cholecap_us_compliance_group__c",
        "cholecap_us_product_management_group__c"
    ],
    "allowed_default_users__v": [
        "etta@veevapharm.com"
    ],
    "allowed_default_groups__v": [
        "cholecap_us_docs_group__c"
    ]
}
]    

To understand how and where these users and groups are being assigned, refer to the Details section of the previous request.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
--data-binary @"C:\Vault\Override Rules\create-lifecycle-role-override-rules.json" \
https://myvault.veevavault.com/api/v12.0/configuration/role_assignment_rule

In this example:

  • The input file format is set to JSON.
  • The response format is not set and will default to JSON.
  • The path/name of the JSON input file is specified.

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        }
    ]
}

Details

For each override rule specified in the input, the response includes a SUCCESS or FAILURE message.

Errors

On failure, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Update Override Rules

Request

Send PUT to api/{version}/configuration/role_assignment_rule

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Input

Before submitting this request, prepare a JSON or CSV input file. See the Create Override Rules request above for details.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Override Rules\update-lifecycle-role-override-rules.csv" \
https://myvault.veevavault.com/api/v12.0/configuration/role_assignment_rule

Details

For each override rule specified in the input, the response includes a SUCCESS or FAILURE message.

Errors

On failure, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Delete Override Rules

Request

Send DELETE to api/{version}/configuration/role_assignment_rule

Headers

Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Parameters

This endpoint alone will retrieve a list of all lifecycle role assignment rules (default & override) from all roles in all lifecycles in your vault.

Parameters

You must add the following parameters to the request endpoint:

  • lifecycle__v={lifecycle_name} - Include the name of the lifecycle from which to delete override rules. For example: lifecycle__v=general_lifecycle__vs
  • role__v={role_name} - Include the name of the role from which to delete override rules. For example: role__v=editor__c

This will delete ALL override rules configured on the specified lifecycle role.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__vs&role__v=editor__c

Response

{
  "responseStatus": "SUCCESS",
  "data": {
    "rules_deleted": 2
  }
}

Details

The response above shows that two separate override rules were deleted from the lifecycle role.

If you'd rather delete only one of the override rules, you can include an additional parameter to define the specific override rule to be deleted. This is described in the next example:

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__vs&role__v=editor__c&product__v.name__v=CholeCap

For this request, assume the following:

  • There are two separate override rules configured on the editor__c role in the general_lifecycle__vs lifecycle.
  • The first override rule defines the users and groups assigned to the role when the product "CholeCap" is assigned to the document.
  • The second override rule defines the users and groups assigned to the role when the product "Nyaxa" is assigned to the document.
  • We only want to delete the first override rule.

When specifying the object records that define the override condition, you can use either the object record id value (e.g., product__v=0PR0011001) or name__v value (e.g., product__v.name__v=CholeCap via object__v.name__v lookup).

Response

{
  "responseStatus": "SUCCESS",
  "data": {
    "rules_deleted": 1
  }
}

Details

The response above shows that one override rule was deleted from the lifecycle role.

Errors

On failure, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Lifecycle Role Assignment Rule Errors

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

Error Type Error Message Comments
INSUFFICIENT_ACCESS Insufficient privileges to perform the action : permission [{PERMISSION}] is expected. The logged-in API user does not have sufficient privileges to create the configuration data. The error message includes the name of the required permission.
METHOD_NOT_SUPPORTED Requested method [{METHOD}] not supported. Use the appropriate HTTP method: GET, POST, PUT, DELETE.
OPERATION_NOT_ALLOWED Cannot create rule for role [{LIFECYCLE}.{ROLE}] : max rules exceeds [50000]. There is a maximum of 50,000 rules that can be created per role with this request.
OPERATION_NOT_ALLOWED Multiple default users: can only define one default user for role [{LIFECYCLE}.{ROLE}]. If you specify multiple user IDs in the input for a default user role on a lifecycle which does not allow multiple users, this error is returned. The error message includes the lifecycle and role generating the error. Only one user ID may be assigned to the role.
OPERATION_NOT_ALLOWED Cannot set group to default : default groups not allowed for role [{LIFECYCLE}.{ROLE}]. If you specify a group ID in the input for a default group role which does not allow default groups, this error is returned. The error message includes the lifecycle and role generating the error. You cannot assign a group ID to the default role on this lifecycle.
OPERATION_NOT_ALLOWED Role is not modifiable : cannot modify override rules for role [{LIFECYCLE}.{ROLE}]. If you specify a role in the input which cannot be edited, this error is returned. The error message includes the lifecycle and role generating the error. You cannot create override rules for this role on this lifecycle.
INVALID_DATA Duplicate rule: rule [{FIELD_1}={VALUE_1},{FIELD_2}={VALUE_2}], etc.] exists in the input more than once. If the input contains duplicate field values, only the first instance is processed. The remaining duplicate fields are ignored.
INVALID_DATA Duplicate rule: rule [{FIELD_1}={VALUE_1},{FIELD_2}={VALUE_2}], etc.] already exists in the database. If the input contains a rule which is already configured on the specified lifecycle in Vault, this error is returned.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : no value expected since parent [{PARENT_OBJECT}] is not specified. Child objects are allowed to be in a condition only when the parent object is already in a condition.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : child record of [{PARENT_OBJECT}.{ID}] is expected. The child object record must be validated as an actual child of the selected parent. If validation fails, this error is returned.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : value does not resolve to a valid lifecycle or role. Vault performs a check of all lifecycle and role values included in the input. If a value does not resolve to a valid lifecycle or role, this error is returned. The error message includes the name of the lifecycle or role and the invalid value entered in the input. When creating override rules for a specific lifecycle and/or specific role, make sure the lifecycle value (e.g., general_lifecycle__vs and/or role value (e.g., editor__c) exists in your vault and is entered correctly in the input.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : object record ID does not resolve to a valid object [{OBJECT_RECORD}]. Vault performs a check of all object record IDs included as a condition in the input (e.g., product__v=00P2889114). If a value does not resolve to a valid object record ID, this error is returned. The error message includes the name of object record and invalid value entered in the input. When creating override rules for documents assigned a specific object record (e.g., product, country, study, etc.), you must enter the value of the object record ID (not the object record name). Make sure the object record value exists in your vault and is entered correctly in the input. Note that the object record does not need to be active.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : object record ID does not resolve to a unique valid object [{OBJECT_RECORD}]. If the condition is used with a lookup (e.g., "product__v.name__v": "CholeCap") and there are multiple object records in the input with the same object record ID, this error is returned. The exception to this rule is that as long as the name is unique within its parent, there can be duplicate records.
INVALID_DATA Invalid values [{VALUE_1},{VALUE_2}] specified for parameter [user_list] : values do not resolve to a valid active [user]. User values in the input are validated. Each username must resolve to a valid active user in the current vault application. Duplicate users in the input are ignored. The error message includes a comma-delimited list of all users who were identified as invalid.
INVALID_DATA Invalid values [{VALUE_1},{VALUE_2}] specified for parameter [group_list] : values do not resolve to a valid active [group]. Group values in the input are validated. Each group must resolve to a valid active group in the current vault application. Duplicate groups in the input are ignored. The error message includes a comma-delimited list of all groups which were identified as invalid.


Workflows

A workflow is a series of steps configured in Vault to align with specific business processes. The different types of steps offer a flexible way to organize a wide variety of processes for a document, including assigning tasks to users, sending notifications and changing document status. User task steps in workflows also serve various purposes. User tasks can allow users to enter comments, choose verdicts (approve, deny, etc.), update required fields or provide electronic signatures.

Workflows are specific to a lifecycle, meaning that a single workflow cannot apply to multiple lifecycles. A single document can only be in one workflow at a time.

Learn more about Lifecycles & Workflows in Vault Help.

Workflow Metadata

The Vault workflows object includes the following fields:

Field Name Description Comments
workflow_id__v Workflow ID The ID of the workflow instance.
workflow_name__v Workflow Name The name of the workflow (Review, Submit for MLR, Approval, etc.).
This is a picklist field.
workflow_type__v Workflow Type The type of workflow (Standard, Read and Understood, etc.).
This is a picklist field.
workflow_status__v Workflow Status The status of the workflow (Active, Completed, Cancelled, etc.).
This is a picklist field.
workflow_document_id__v Workflow Document ID The id of the document associated with the workflow.
workflow_document_major_version_number__v Document Major Version The major version number of the document associated with the workflow.
workflow_document_minor_version_number__v Document Minor Version The minor version number of the document associated with the workflow.
workflow_initiator__v Initiator Vault User ID of the person who initiated the workflow.
workflow_initiatorName__v Initiator Name The name of the person who initiated the workflow.
workflow_startDate__v Start Date The date and time when the workflow was started.
workflow_dueDate__v Due Date The date when the workflow is due.
workflow_completionDate__v Completion Date If completed, the date when the workflow was completed.
workflow_cancelationDate__v Cancellation Date If cancelled, the date when the workflow was cancelled.
workflow_duration__v Duration The number of days the workflow was active before it was completed or cancelled (including partial days).
workflow_process_instance_group__v Instance Group
task_id__v Task ID The ID of the task instance.
task_name__v Task Name The name of the task (Approve, Review and Provide Annotations, etc.).
This is a picklist field.
task_status__v Task Status The current status of the task (Available, Assigned, Completed, etc.).
This is a picklist field.
task_verdict__v Task Verdict The outcome or verdict of the task (Approved, Not Approved, etc.).
This is a picklist field.
task_capacity__v Task Capacity
task_assignee__v Assignee Vault User ID of the person who was assigned the task.
task_assignee_name__v Assignee Name The name of the person who was assigned the task.
task_delegate__v Delegate If the task was delegated to another user, the Vault User ID of the delegated user.
task_queueGroup__v Queue Group If the task was sent to a group, this is the group name (Reviewer, Approver, etc.).
This is a picklist field.
task_creationDate__v Creation Date The date and time when the task was created.
task_assignmentDate__v Assignment Date The date and time when the task was assigned.
task_dueDate__v Due Date The date when the task is due.
task_completionDate__v Completion Date If completed, the date and time when the task was completed.
task_cancelationDate__v Cancellation Date If cancelled, the date and time when the task was cancelled.
task_duration__v Duration The number of days the task was active before it was completed or cancelled (including partial days).

The following information may be included with each field:

Field Description Comments
name Field Name The name of the field (workflow_name__v, task_name__v, etc.
type Field Type The type of field. These include "id", "String", "Number", "Boolean", "ObjectReference", "Date", "DateTime", and "Picklist".
object Object When the type is ObjectReference, this indicates the name of the object being referenced by the field.
These include workflow_initiator__v, task_assigneee__v, and task_delegate__v.
multivalue Multi-Value Indicates if the field can have multiple values. This is analogous to repeating document fields.
length Length When the field type is "String", this field indicates the maximum character length which can be used.

Retrieve Workflow Metadata

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

Example Request

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "properties": [
        {
            "name": "workflow_document_id__v",
            "type": "id",
            "multivalue": false
        },
        {
            "name": "workflow_initiator_name__v",
            "type": "String",
            "length": 255,
            "multivalue": false
        },
        {
            "name": "workflow_id__v",
            "type": "id",
            "multivalue": false
        },
        {
            "name": "workflow_name__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Approval"
                },
                {
                    "label": "Approval without Review"
                },
                {
                    "label": "Distribute"
                },
                {
                    "label": "MLR Approval"
                },
                ...
            ]
        },
        {
            "name": "workflow_initiator__v",
            "type": "ObjectReference",
            "object": "User",
            "multivalue": false
        },
        {
            "name": "workflow_status__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Error"
                },
                {
                    "label": "Complete"
                },
                {
                    "label": "Cancelled"
                },
                {
                    "label": "Active"
                }
            ]
        },
        {
            "name": "workflow_startDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "workflow_completionDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "workflow_cancelationDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "workflow_duration__v",
            "type": "Number",
            "multivalue": false
        },
        {
            "name": "workflow_dueDate__v",
            "type": "Date",
            "multivalue": false
        },
        {
            "name": "workflow_type__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Standard"
                },
                {
                    "label": "Read and Understood"
                },
                {
                    "label": "Read and Understood"
                }
            ]
        },
        {
            "name": "workflow_document_major_version_number__v",
            "type": "Number",
            "multivalue": false
        },
        {
            "name": "workflow_document_minor_version_number__v",
            "type": "Number",
            "multivalue": false
        },
        {
            "name": "workflow_process_instance_group__v",
            "type": "String",
            "length": 255,
            "multivalue": false
        },
        {
            "name": "task_assignee_name__v",
            "type": "String",
            "length": 255,
            "multivalue": false
        },
        {
            "name": "task_id__v",
            "type": "id",
            "multivalue": false
        },
        {
            "name": "task_name__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Approve"
                },
                {
                    "label": "Assess outcome"
                },
                {
                    "label": "Approve Document"
                },
                ...
            ]
        },
        {
            "name": "task_assignee__v",
            "type": "ObjectReference",
            "object": "User",
            "multivalue": false
        },
        {
            "name": "task_delegate__v",
            "type": "ObjectReference",
            "object": "User",
            "multivalue": false
        },
        {
            "name": "task_queueGroup__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Approver"
                },
                {
                    "label": "Coordinator"
                },
                {
                    "label": "Reviewer"
                },
                ---
            ]
        },
        {
            "name": "task_status__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Assigned"
                },
                {
                    "label": "Available"
                },
                {
                    "label": "Completed"
                },
                ...
            ]
        },
        {
            "name": "task_verdict__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Approved"
                },
                {
                    "label": "Not approved"
                },
                {
                    "label": "Cancel any distribution requests that have not been acted upon."
                },
                {
                    "label": "Re-send tasks to any recipient that has not downloaded the distribution package."
                },
                ---
            ]
        },
        {
            "name": "task_capacity__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false
        },
        {
            "name": "task_creationDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "task_assignmentDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "task_completionDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        ...
    ]
}

Possible Errors

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

Version History

Since: v4.0



Security Policies

Learn about authentication and security in Vault Help.


Retrieve All Security Policies

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "security_policies__v": [
        {
            "name__v": "821",
            "label__v": "Basic",
            "value__v": "https://myvault.vaultdev.com/api/v14.0/objects/securitypolicies/821"
        },
        {
            "name__v": "958",
            "label__v": "Default",
            "value__v": "https://myvault.vaultdev.com/api/v14.0/objects/securitypolicies/958"
        },
        {
            "name__v": "957",
            "label__v": "High Security",
            "value__v": "https://myvault.vaultdev.com/api/v14.0/objects/securitypolicies/957"
        }
    ]
}

Response Details

On SUCCESS, the response includes the following information:

Field Name Description Comments
security_policies__v [n] All Security Policies List of all security policies configured in your vault.
name__v Security Policy ID System-managed number field automatically added to the security policy. Use the ID to retrieve a security policy.
label__v Security Policy Label User-defined string field for the security policy. The label is used to identify the security policy in the UI.
value__v Security Policy URL URL to access the security policy details.

Version History

Available in API v3.0 or later.


Retrieve Security Policy

Method & Endpoint

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

Request Headers

  • 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 security policy id field value. This is retrieved from the previous request.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "security_policy__v": {
        "policy_details__v": {
            "name__v": "1722",
            "label__v": "SFDC Users Policy",
            "description__v": "A sample security policy.",            
            "is_active__v": true
        },
        "policy_security_settings__v": {
            "authentication_type__v": {
                "name__v": "Password",
                "label__v": "Password"
            },
            "passwords_require_number__v": true,
            "passwords_require_uppercase_letter__v": true,
            "passwords_require_nonalpha_char__v": true,
            "min_password_length__v": 10,
            "password_expiration__v": 90,
            "password_history_reuse__v": 3,
            "require_question_on_password_reset__v": true,
            "allow_delegated_auth_sfdc__v": true,
            "sfdc_org_id__v": "00215SFDA9587456"
        }
    }
}

Response Details

On SUCCESS, the response includes some or all of the following security policy fields:

Note: Boolean fields are only returned when the value is set to true.

Field Name Description
policy_details__v Policy Details
name__v Security Policy ID
label__v Security Policy Label
description__v Security Policy Description
is_active__v Active (true/false)
policy_security_settings__v Policy Security Settings
authentication_type__v Authentication Type
name__v Authentication Type Name
label__v Authentication Type Label
passwords_require_number__v Passwords Require Number (true/false)
passwords_require_uppercase_letter__v Passwords Require Upper-Case Letter (true/false)
passwords_require_nonalpha_char__v Passwords Require Non-Alphanumeric Character (true/false)
min_password_length__v Minimum Password Length (7, 8, 10, or 12 characters)
password_expiration__v Password Expiration (90 days, 180 days, or no expiration)
password_history_reuse__v Password History Reuse (prevent reuse of the last 3 passwords, 5 passwords, or no limitations)
require_question_on_password_reset__v Require Security Question on Password Reset (true/false)
allow_delegated_auth_sfdc__v Allow Salesforce Delegated Authentication (true/false)
sfdc_org_id__v Salesforce Org ID

Version History

Available in API v3.0 or later.



Query API

Query API is used to construct simple but powerful queries to retrieve data from Vault. When a client application invokes the query call, it passes in a Vault Query Language (VQL) expression (a SQL-like query) that specifies the object to query, the fields to retrieve, and any conditions to qualify an object.

For detailed information, refer to the following articles which focus on querying informaiton in Vault:



API Errors

The Vault response to every API call includes a field called responseStatus. Possible values are:

  • SUCCESS - The API request has been successfully processed.
  • FAILURE - The API request could not be processed because of API user error.
  • EXCEPTION - The API request could not be processed because of API system error.

For a responseStatus other than SUCCESS, API users can inspect another field in the response called errors. Each error includes the following fields:

type

  • The specific type of error, e.g., INVALID_DATA, PARAMETER_REQUIRED, etc.
  • These values are not subject to change for a given version of the API, even when newer versions of the API are available.
  • API users need to use the error type value in combination with the responseStatus value for error handling.
  • In other words, the type and responseStatus values ARE contractual parts for error handling.

message

  • The message accompanying each error type, e.g., Missing required parameter [{FIELD_NAME}].
  • When available, the error message includes the specific reason, e.g., {FIELD_NAME} for the error.
  • Other error messages provide more general reasons for each error.
  • These values are subject to change, even for past versions. They ARE NOT contractual parts for error handling. Developers should consider error messages for debugging and troubleshooting purposes only and should not implement application logic which relies on specific error strings or formatting.

For a responseStatus of SUCCESS, the errors field is either omitted or has a null value.

Example: An unsuccessful authentication request due to password not provided:

{
    "responseStatus" : "FAILURE"**,
    "errors" : [
        {
            "type" : "NO_PASSWORD_PROVIDED",
            "message" : "No password was provided for the login call."
        }
    ],
    "errorType" : "AUTHENTICATION_FAILED"
}

Error Types

Error Type Error Message/Description
UNEXPECTED_ERROR General error catch-all when there is no specific error, or an unidentified error.
MALFORMED_URL The specified resource cannot be found.
METHOD_NOT_SUPPORTED The specified resource does not support the (POST, PUT, GET, DELETE) method. Or, the API request is not supported by this version of API.
INACTIVE_USER User is inactive or not found.
NO_PASSWORD_PROVIDED No password was provided for the login call.
USERNAME_OR_PASSWORD_INCORRECT Authentication failed because an invalid username or password was provided.
USER_LOCKED_OUT The user is locked out.
PASSWORD_CHANGE_REQUIRED Password change required.
INVALID_SESSION_ID Invalid session id provided.
PARAMETER_REQUIRED Missing required parameters in the API call.
INVALID_DATA Invalid data provided in the API call.
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action.
OPERATION_NOT_ALLOWED Certain rules that must be met to perform this operation have not been met.
ATTRIBUTE_NOT_SUPPORTED The specified resource does not recognize provided attributes.
INVALID_FILTER Provided a non-existent filter to Retrieve Documents.
INCORRECT_QUERY_SYNTAX_ERROR Query string used with Query API has an incorrect query syntax.
RACE_CONDITION A rare condition where the same record is being simultaneously updated by another API call
EXCEEDS_FILE_MAX_SIZE The size of file uploaded exceeds the maximum allowed
API_LIMIT_EXCEEDED 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, this error message is returned and no further calls will be processed until the next 5 minute or 24 hour period begins. The default limit every 5 minutes is 1000 or 2000 calls, depending on your vault. The default limit every 24 hours is 100,000 calls.
SDK_ERROR An error caused by the Vault Java SDK. This error may also include a custom subtype. For more information about this error, check the Debug Log. To inquire about Vault Java SDK Solutions, contact Veeva Services.

Backwards Compatibility

Although we do not change behavior in previous API versions, we may update and improve messages that accompany error responses. Error types will not change. Developers should consider error messages for debugging and troubleshooting purposes only and should not implement application logic which relies on specific error strings or formatting.




End of Veeva Vault v12.0 API Reference. Have a nice day.