API Reference (v9.0)

We recommend using a newer version of the API

For general information on Vault, refer to Vault Help.

General

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

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

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

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

HTTP Methods

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

Supported Response Formats

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

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

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

Authentication

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

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

Vault supports the following authentication methods:

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

API Metadata

Retrieve Available API Versions

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

For example:

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

Response

The response contains a list of all available API versions.

Example:

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

Errors

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

Version History

Since: v1.0

Retrieve Available API Resources

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

For example:

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

Response

The response contains a list of the available API resources.

Example:

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

Errors

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

Version History

Since: v1.0

Domain Information

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

Retrieve Domain Information

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

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

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v7.0

Document Metadata

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

Retrieve All Document Types

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

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v1.0

Retrieve Document Type

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

For example:

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

Response

The response contains the metadata for the document type.

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

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

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

Errors

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

Version History

Since: v1.0

Retrieve Document Subtype

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

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

For example:

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

Response

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

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

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

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

Errors

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

Version History

Since: v1.0

Retrieve Document Classification

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

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

For example:

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

Response

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

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

Errors

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

Version History

Since: v1.0

Retrieve Document Properties

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

For example:

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

Response

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

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

Errors

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

Version History

Since: v4.0

Retrieve Document Relationships

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

For example:

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

Response

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

Example:

{
    "responseStatus": "SUCCESS",
    "properties": [
        {
            "name": "id",
            "type": "id",
            "length": 20,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "source_doc_id__v",
            "type": "id",
            "length": 20,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "source_major_version__v",
            "type": "Integer",
            "length": 10,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "source_minor_version__v",
            "type": "Integer",
            "length": 10,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "target_doc_id__v",
            "type": "id",
            "length": 20,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "target_major_version__v",
            "type": "Integer",
            "length": 10,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "target_minor_version__v",
            "type": "Integer",
            "length": 10,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "relationship_type__v",
            "type": "String",
            "length": 255,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "created_date__v",
            "type": "DateTime",
            "length": 0,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "created_by__v",
            "type": "ObjectReference",
            "length": 10,
            "object": "users",
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": false
        }
    ],
    "relationshipTypes": [
        {
            "value": "references__vs",
            "label": "References",
            "sourceDocVersionSpecific": true,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Trial Management",
                    "value": "trial_management__vs"
                },
                {
                    "label": "Statistics",
                    "value": "statistics__vs"
                },
                {
                    "label": "Third parties",
                    "value": "third_parties__vs"
                }
            ]
        },
        {
            "value": "supporting_documents__vs",
            "label": "Supporting Documents",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": false,
            "system": false,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Trial Management",
                    "value": "trial_management__vs"
                },
                {
                    "label": "Statistics",
                    "value": "statistics__vs"
                },
                {
                    "label": "Third parties",
                    "value": "third_parties__vs"
                }
            ]
        },
        {
            "value": "basedon__vs",
            "label": "Based on",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Trial Management",
                    "value": "trial_management__vs"
                },
                {
                    "label": "Statistics",
                    "value": "statistics__vs"
                },
                {
                    "label": "Third parties",
                    "value": "third_parties__vs"
                }
            ]
        }
    ]
}

Errors

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

Version History

Since: v3.0

Retrieve Document Lock Metadata

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

For example:

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

Response

The response contains the document lock metadata.

Example:

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

Errors

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

Version History

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

Find Common Document Fields

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

For example:

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

Response

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

Errors

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

Version History

Since: v9.0

Documents

The heart of Veeva Vault is the documents object. The API lets you create, update, retrieve and delete documents. The properties available and/or required for the document depend on the type/subtype/classification of the document. You can get the list of document properties from the Document Metadata API calls.

Note that as of v5.0 you cannot create or manipulate binder documents through the documents API, you must use the binders API, below.

Create Document

You can create a document by sending a POST request to the /api/{version}/objects/documents endpoint.

• The maximum file size allowed is 4GB.
  
• The HTTP Request Header Content-Type must be set to multipart/form-data.
• Refer to output from the Document Metadata APIs to determine the request parameters. To determine the required properties, look for the properties with the following metadata: required=true and setOnCreateOnly=false
• To upload a file, use multi-part attachment with the file component named file. If no file is attached, the document will be created as a content placeholder.
• To create a document from a template, include a query parameter fromTemplate and specify the name of the template as returned from the document {type}/{subtype}/{classification} Document Metadata API. Only templates of type document are allowed and the document type of the document being created must match the metadata API path.

For example, to create a document in eTMF Vault:

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-F "lifecycle__v=eTMF Lifecycle" \
-F "type__v=Trial Management" \
-F "subtype__v=Trial Oversight" \
-F "classification__v=Trial Master File Plan" \
-F "process_name__v=Secure Resources / People" \
-F "name__v=Test Document" \
-F "major_version_number__v=0" \
-F "minor_version_number__v=1" \
-F "file=@TestDocument.docx" \
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents

By default the document metadata is indexed synchronously. To process the indexing asynchronously, include a query parameter async set to true. This also improves the performance of rendering the viewable PDF renditions by routing the rendering requests to bulk renditions queue.

By default the viewable rendition is generated at the time of document creation. To supporess generation of the viewable rendition, include a query parameter suppressRendition set to true.

Response

On success, the response will contain the ID of the newly created document.

Example:

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

Errors

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

Version History

Since: v1.0
v5.0: create from template supported
v7.0: asynchronous metadata indexing supported
v8.0: suppressing generation of viewable rendition is supported

Create Multiple Documents

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

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

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

Headers

Body Parameters

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

Request

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

Response

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

Retrieve Documents

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

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

Request Parameters

For example:

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

Response

On success, Vault retrieves the list of documents and binders matching the request criteria, with their metadata. The document metadata returned will vary based on your vault configuration.

A document pseudo-property 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 the pseudo-property 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.

Errors

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

Version History

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

Retrieve Document

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

For example:

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

Response

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

Errors

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

Version History

Since: v1.0

Retrieve Document Versions

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

For example:

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

Response

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

Example:

{
    "responseStatus": "SUCCESS",
    "versions": [
        {
            "number": "0.1",
            "value": "https://devtmf.vaultdev.com/api/v8.0/objects/documents/23/versions/0/1"
        }
    ],
    "renditions": {
        "viewable_rendition__v": "https://devtmf.vaultdev.com/api/v8.0/objects/documents/23/renditions/viewable_rendition__v"
    }
}

Errors

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

Version History

Since: v1.0

Retrieve Document Version

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

For example:

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

Response

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

Errors

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

Version History

Since: v1.0

Update Document

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

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

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

Response

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

Example:

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

Errors

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

Version History

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

Update Multiple Documents

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

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

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

Headers

Body Parameters

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

Example Request

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

Example Response

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

Update Document Version

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

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

Response:

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

Example:

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

Errors

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

Version History

Since: v1.0

Delete Document

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

For example:

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

Response

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

Errors

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

Version History

Since: v1.0

Delete Document Version

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

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v1.0

Retrieve Document File

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

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

For example:

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

Response

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

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

Errors

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

Version History

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

Retrieve Document Version File

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

Response

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

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

Errors

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

Version History

Since: v1.0

Retrieve Document Version Thumbnail

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

For example:

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

Response

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

Errors

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

Version History

Since: v6.0

Create Document Lock (Check-out)

You can create the document lock by sending a POST request to the /api/{version}/objects/documents/{id}/lock endpoint.

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

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v1.0

Retrieve Document Lock

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

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v1.0

Delete Document Lock

You can delete the document lock by sending a DELETE request to the /api/{version}/objects/documents/{id}/lock endpoint. Deleting a document lock is analogous to undoing check out of a document.

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v1.0

Update Document File / Create Draft

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

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

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

Request Parameters

• description__v - To set the description for the minor version update, include this parameter in the requested set to the description string.

• createDraft - optional [latestContent|uploadedContent]

  • if not set or not included in the request, the functionality of this API call is to Upload New Document
  • if set to latestContent, the functionality of this API is to create a new draft version from the latest content
  • if set to uploadedContent, the functionality of this API is to create a new draft version from the content uploaded in file parameter

• file - contains the binary file attachment

  • optional when a new draft needed to be created from existing content
  • required when a new draft needed to be created for new content
  • required when the existing document file needs to be updated

• suppressRendition - optional - boolean

  • if set to true suppresseses generation of viewable rendition when the document file is updated

Response

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

Errors

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

Version History

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

List Document Renditions

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

For example:

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

Response

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

Errors

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

Version History

Since: v1.0

List Document Version Renditions

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Retrieve Document Rendition

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

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

For example:

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

Response

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

Errors

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

Version History

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

Retrieve Document Version Rendition

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Upload Document Rendition

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

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

For example:

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

Response

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

Errors

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

Version History

Since: v1.0

Upload Document Version Rendition

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

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Delete Latest Document Rendition

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Delete Document Version Rendition

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Replace Document Rendition

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

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Replace Document Version Rendition

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

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

List Document Relationships

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

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v3.0

Create Document Relationship

Method & Endpoint

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

Request Headers

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

Request Parameters

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

Input Parameters

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

Example Request

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

Example Response

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

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

Possible Errors

Version History

Available in API v3.0 or later.

Delete a Document Relationship

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

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v3.0

Document Events

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

Document Events Metadata

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

Retrieve Available Document Event Types

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

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v6.0

Retrieve Event Type Metadata & Defined Subtypes

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

For example:

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

Response

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

Errors

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

Version History

Since: v6.0

Document Events Data

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

Retrieve Document Event Data

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

Request Parameters

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

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

• Use startDate and endDate parameters to filter by date range

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

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

Response

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

Errors

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

Version History

Since: v6.0

Log a Document Event

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

Request Parameters

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

Response

On success, Vault logs the document event.

Errors

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

Version History

Since: v6.0

Lifecycles

The API supports lifecycle actions such as workflows and state changes on documents and binders in your vault. This allows you to request a list of lifecycle actions available to users on a document or binder, retrieve the properties which are required to be provided before the lifecycle action can be initiated (entry requirements), and then initiate the lifecycle action.

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.
• Some have requirements that can be specified as name-value pairs with the lifecycle initiation request (when the entry requirement "scope": "WorkflowActivation").
• Others must first be updated on the document or binder before initiating the request (when the entry requirement "scope": "Document" or "scope": "Binder").

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

Use this request to retrieve all available lifecycle actions that can be initiated on a specific version of a document or binder.

Method & Endpoint

Documents: Send a GET request to the /api/{VERSION}/objects/documents/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions endpoint.
Binders: Send a GET request to the /api/{VERSION}/objects/binders/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions 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 id field value of the document from which to retrieve available lifecycle actions.
• major_version_number__v - Major version number of the document.
• minor_version_number__v - Minor version number of the document.

Example Request

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

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

Response 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. These values
• lifecycle_action_type__v - The workflow and stateChange types are the most commonly used and are available in all vaults.
• 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.

Version History

Available in API v6.0 or later.

Retrieve Entry Requirements

Once you've retrieved the available lifecycle actions, use this request to retrieve the entry requirements from a specific lifecycle action.

Method & Endpoint

Documents: Send a GET request to the /api/{VERSION}/objects/documents/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{LIFECYCLE_ACTION}/entry_requirements endpoint.
Binders: Send a GET request to the /api/{VERSION}/objects/binders/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{LIFECYCLE_ACTION}/entry_requirements 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 id field value of the document from which to retrieve lifecycle action entry requirements.
• major_version_number__v - Major version number of the document.
• minor_version_number__v - Minor version number of the document.
• LIFECYCLE_ACTION - The name__v value of the lifecycle action from which to retrieve entry requirements.

Example Request 1

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

Example Response 1

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

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 intiating the lifecycle action.
• Unlike the response from the next request, 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.

Refer to the example request "Initiate Start Approval Workflow" in the "Initiate Lifecycle Action" section below for more information.

Example Request 2

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

Example Response 2

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

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

Refer to the example request "Change State to Approved" in the "Initiate Lifecycle Action" section below for more information.

Entry Requirement Field Properties

The response may include the following metadata elements describing the properties for which values need to be specified:

Version History

Available in API v6.0 or later.

Initiate Lifecycle Action

Once you've identified the entry requirements, use this request to initiate the lifecycle action on a specific version of a document or binder.

Method & Endpoint

Documents: Send a PUT request to the /api/{VERSION}/objects/documents/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{LIFECYCLE_ACTION} endpoint.
Binders: Send a PUT request to the /api/{VERSION}/objects/binders/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{LIFECYCLE_ACTION} 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 id field value of the document on which to initiate a lifecycle action.
• major_version_number__v - Major version number of the document.
• minor_version_number__v - Minor version number of the document.
• LIFECYCLE_ACTION - The name__v value of the lifecycle action to be initiated. This is retrieved from the first request above.

Example Request 1

In this request, we'll initiate the "Start Approval" workflow.

$ 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

Request Details

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

On submitting this request, Vault will evaluate whether all the entry requirements have been met and, if so, initiate the lifecycle action.

Example Response

{
  "responseStatus": "SUCCESS",
  "id": 222,
  "workflow_id__v": "115"
}

Response Details

• On SUCCESS, Vault returns the id value of the document on which the lifecycle action has been initiated and the workflow_id__v value of the workflow.
• This document ("id": 222) was 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.

Version History

Available in API v6.0 or later.

Example Request 2

In this request, we'll change the state of a document from "Draft" to "Approved".

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/objects/documents/222/versions/0/1/lifecycle_actions/approve

Request Details

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.

Example Response

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

Response Details

• On SUCCESS, Vault returns the id 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.

Version History

Available in API v6.0 or later.

Binders

Binders organize documents and sections and other binders into a hierarchical structure that is useful for packaging related documents together for easier management or eventual publishing. Binders are a kind of document and many of the Document API calls, such as metadata, retrieving and setting properties, security, etc. can be used directly on a binder and will not be replicated here. All API calls related to files and renditions will not work on a binder object. Binders do have unique APIs that allow for interrogating and manipulating the binder structure.

Create Binder

You can create a binder by sending a POST request to the /api/{version}/objects/binders endpoint.

• Refer to output from the Document Metadata APIs to determine the request parameters.
• Only properties marked as "onCreateEditable": true are valid and properties vary based on your Vault configuration.
• No file can be uploaded as part of a binder creation
• To create a document from a template, include a query parameter fromTemplate and specify the name of the template as returned from the "Document Type/Subtype/Classification Metadata" API. Only templates of type binder are allowed and the document type of the document being created must match the metadata API path.

By default the binder metadata is indexed synchronously. To process the indexing asynchronously, include an optional request parameter async set to true.

Response

On success, Vault create a binder returns the ID of the newly created binder

Example:

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

Errors

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

Version History

Since: v5.0
v7.0: asynchronous metadata indexing supported

Retrieve Binder

You can retrieve the binder properties and it's node tree structure by sending a GET request to the /api/{version}/objects/binders/{id} endpoint.

Request Parameters

Response

On success, Vault retrieves the properties 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.

For each binder, the API will return: * order__v Order within the section or binder * type__v = Document * id Node ID of the document, unique within the binder * document_id__v ID of the document * name__v Name of the document * major_version_number__v Major version (if binding rule = specific) * minor_version_number__v Minor version (if binding rule = specific)

For each section, the API will return:
* order__v Order within the section or binder * type__v Section * id ID of the section, unique within the binder * name__v Name of the section * section_number__v Section number (optional)

For each binder, the API will return: * order__v Order within the section or binder * type__v = Binder * id ID of the binder * name__v Name of the binder

NOTE: When a contained binder is listed here, no children of that binder are listed. It will require a separate "Retrieve Binder" API call in that binder to get its structure.

Errors

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

Version History

Since: v5.0

Retrieve Binder Versions

Binders have versions just like regular documents.

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

For example:

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

Response

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

Errors

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

Version History

Since: v5.0

Retrieve Binder Version

You can retrieve the binder properties and values for the specific binder version by sending a GET request to the /api/{version}/objects/binders/{id}/versions/{major}/{minor} endpoint.

For example:

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

Response

On success, Vault returns the properties and property values for the specified version of the binder. Response properties will vary based on properties defined for the document type classification of the specified binder. The shaper and the contents of the response is similar to the response of the "Retrieve Binder" API

Errors

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

Version History

Since: v5.0

Update Binder Properties

You can update the binder properties by sending a PUT request to the /api/{version}/objects/binders/{id} endpoint.

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

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

Response

On success, Vault returns the ID of the updated binder.
v8.0 Notes: reclassify supported

Example:

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

Errors

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

Version History

Since: v5.0
v8.0: reclassify supported

Update Binder Version Properties

You can update the binder properties of the specific binder version by sending a PUT request to the /api/{version}/objects/binders/{id}/versions/{major}/{minor} endpoint.

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

Response

On success, Vault updates the specified version of the binder and returns the id of the updated binder.

Errors

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

Version History

Since: v5.0

Create Draft

You can create a new draft version for a binder by sending a POST request to the /api/{version}/objects/binders/{id} endpoint.

For example:

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

Response

On success, the response contains the major and minor versions of the newly created binder draft.

Errors

On failure, the response contains an error message.

Version History

Since: v7.0

Delete Binder

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

For example:

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

Response

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

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

Errors

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

Version History

Since: v5.0

Delete Binder Version

You can delete the specific binder version by sending 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.

For example:

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

Response

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

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

Errors

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

Version History

Since: v5.0

Create a Binder Relationship

You can create a binder relationship by sending a POST request to the /api/{version}/objects/binders/{id}/versions/{major}/{minor}/relationships endpoint.

For example:

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-d "target_doc_id__v=13&relationship_type__v=supporting_documents__vs&target_major_version__v=0&target_minor_version__v=1" \
https://{CUSTOMER}.veevavault.com/api/{version}/objects/binders/{id}/versions/{major}/{minor}/relationships

Request Parameters

Response

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

Errors

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

Version History

Since: v5.0

Retrieve a Binder Relationship

You can retrieve a binder relationship by sending a GET request to the /api/{version}/objects/binders/{id}/versions/{major}/{minor}/relationships/{relationshipId} endpoint.

For example:

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

Response

On success, Vault return the requested relationship. The relationship has the following properties:

Example:

{
  "responseStatus": "SUCCESS",
  "relationships": [
    {
      "relationship": {
        "id": 41,
        "source_doc_id__v": 32,
        "relationship_type__v": "supporting_documents__vs",
        "created_by__v": 25496,
        "created_date__v": "2013-04-11T19:46:59.000Z",
        "target_doc_id__v": 14
      }
    }
  ]
}

Errors

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

Version History

Since: v5.0
v6.0: The response no longer includes the target_major_version__v property 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 properties.

Delete a Binder Relationship

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

For example:

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

Response

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

Errors

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

Version History

Since: v5.0

Update Binder Binding Rule

You can update document version binding rules for the binder, either for all documents and sections within the binder that do not already have binding rules set or for all documents and sections regardless of previous binding rules.

You can update the binding rules by sending a PUT request to the /api/{version}/objects/binders/{id}/binding_rule endpoint.

For example:

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-d "binding_rule__v=steady-state&binding_rule_override__v=true" \
https://{CUSTOMER}.veevavault.com/api/{version}/objects/binders/{id}/binding_rule

Request Parameters

Binding Rules: * default Latest available (assumed if binding_rule is blank) * steady-state Latest version in steady-state state * current Version currently in use

Response

On success, Vault returns the ID of updated binder.

Errors

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

Version History

Since: v5.0

Create Section

You can create a binder section by sending a POST request to the /api/{version}/objects/binders/{id}/sections endpoint.

Request Parameters

Response

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

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

Errors

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

Version History

Since: v5.0

Retrieve Section(s)

You can retrieve a binder section by sending a GET request to the /api/{version}/objects/binders/{id}/sections/{section_node_id} endpoint. If {section_node_id} blank in the endpoint, sections directly linked to the top-level binder will be returned.

For example:

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

Response

On success, Vault returns the list of all sections, documents and binders within the top-level binder (if {section_node_id} is blank on the endpoint) or retrieves a list of all sections, documents, and binders within the specified section (if {section_node_id} is a valid section within the binder}.

For each document, the API will return: * order__v Order within the section * type__v Document * document_id__v ID of the document * name__v Name of the section * id Unique ID of the node within the binder * major_version_number__v Major version (if binding rule = specific) * minor_version_number__v Minor version (if binding rule = specific)

For each section, the API will return: * order__v Order within the section * type__v Section * id ID of the section, unique within the binder * name__v Name of the section * section_number__v Section number (optional)

For each binder, the API will return: * order__v Order within the section * type__v Binder * binder_id ID of the binder * name__v Name of the binder

Note that the section node ID passed in may be at any level within the binder hierarchy as section node IDs are unique within the binder.

Errors

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

Version History

Since: v5.0

Retrieve Binder Version Section

You can retrieve a binder section for in a specific binder version by sending a GET request to the /api/{version}/objects/binders/{id}/versions/{major}/{minor}/sections/{section_node_id} endpoint. If {section_node_id} blank in the endpoint, sections directly linked to the top-level binder will be returned.

For example:

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

Response

On success, Vault returns the list of all sections, documents and binders within the top-level binder (if {section_node_id} is blank on the endpoint) or retrieves a list of all sections, documents, and binders within the specified section (if {section_node_id} is a valid section within the binder}.

For each document, the API will return: * order__v Order within the section * type__v Document * document_id__v ID of the document * name__v Name of the section * id Unique ID of the node within the binder * major_version_number__v Major version (if binding rule = specific) * minor_version_number__v Minor version (if binding rule = specific)

For each section, the API will return: * order__v Order within the section * type__v Section * id ID of the section, unique within the binder * name__v Name of the section * section_number__v Section number (optional)

For each binder, the API will return: * order__v Order within the section * type__v Binder * binder_id ID of the binder * name__v Name of the binder

Note that the section node ID passed in may be at any level within the binder hierarchy as section node IDs are unique within the binder.

Errors

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

Version History

Since: v5.0

Update Section

You can update the section name or the number of an existing section and/or move the section to a different location within the binder by sending a PUT request to the /api/{version}/objects/binders/{id}/sections/{section_node_id} endpoint.

Request Parameters

All other items in the section or binder will move down one position. If order__v is blank and new parent_id__v is entered, the section will move to the last position in the new parent.

Response

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

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

Errors

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

Version History

Since: v5.0

Update Section Binding Rule

You can update the section binding rule by sending a PUT request to the /api/{version}/objects/binders/{id}/sections/{section_node_id}/binding_rule endpoint.

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

Request Parameters

Binding Rules: * default Latest available (assumed if binding_rule is blank) * steady-state Latest version in steady-state state * current Version currently in use

Response

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

Errors

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

Version History

Since: v5.0

Delete Section

You can delete a binder section by sending a DELETE request to the /api/{version}/objects/binders/{id}/sections/{section_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.

For example:

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

Response

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

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

Errors

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

Version History

Since: v5.0

Add Document to Binder

You can link an existing document to a location within a binder (either at the top level or within a section in the binder) by sending a POST request to the /api/{version}/objects/binders/{binder ID}/documents endpoint.

Request Parameters

Response

On success, Vault returns the node id of the newly linked document

Errors

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

Version History

Since: v5.0

Move Document Within Binder

You can move the document to a different location within the binder by sending a PUT request to the /api/{version}/objects/binders/{id}/documents/{node_id} endpoint.

The {node_id} must be a valid ID representing a document node currently linked to the binder

For example:

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-d "parent_id__v=1365789543654&order__v=3" \
https://{CUSTOMER}.veevavault.com/api/{version}/objects/binders/{id}/documents/{node_id}

Request Parameters

Response

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

Example:

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

Errors

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

Version History

Since: v5.0

Update Document Binding Rules

You can update the binding rules for the document within a specified binder by sending a PUT request to the /api/{version}/objects/binders/{id}/documents/{node_id}/binding_rule endpoint.

For example:

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-d "binding_rule__v=specific&major_version_number__v=1&minor_version_number__v=0" \
https://{CUSTOMER}.veevavault.com/api/{version}/objects/binders/{id}/documents/{node_id}/binding_rule

Request Parameters

Response

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

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

Errors

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

Version History

Since: v5.0

Remove Document from Binder

You can unlink an existing document from a location within a binder (either at the top level or within a section in the binder) by sending 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.

For example:

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

Response

On success, Vault returns the node ID of the removed document node

Example:

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

Errors

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

Version History

Since: v5.0

Roles

Documents can have different roles available to them depending on their document type and lifecycles. Roles are important in that users and groups get assigned to document roles both at document creation time as well as during document workflows. There are a set of default roles that ship with Vault: Owner, Coordinator, Editor, Approver, Reviewer, Viewer, and Consumer. In addition there can be custom roles defined per lifecycle that reflect business roles that are particular to a document type. Regardless of how a role was assigned, they have specific permissions on a document based on a lifecycle state. Through the Roles APIs, you can retrieve available roles for a document, determine who can be assigned to the role, default users that get assigned automatically within the Vault UI, and who is currently assigned to the role. You can also add additional users and groups to a role and remove users and groups as needed. Note that all user and group information is returned as IDs and you need to use the "Retrieve User" or "Retrieve Group" API to determine the name, etc.

Retrieve Document Roles

You can retrieve the active available roles for a document, available users and groups for the role, and any defaulted users or groups by sending a GET request to the /api/{version}/objects/documents/{id}/roles endpoint.

This information varies on a per document basis based on the document's lifecycle and associated properties that can alter the available users and groups that can be put in a role.

For example:

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

Response

On success, Vault returns the list of all active roles assigned to the specified document:

Example:

{
    "responseStatus": "SUCCESS",
    "documentRoles": [
. . .
        {
            "name": "reviewer__v",
            "label": "Reviewer",
            "assignedUsers": [],
            "assignedGroups": [],
            "availableUsers": [
                31662,
                34525,
                25507,
                31615,
                31810
            ],
            "availableGroups": [
                1
            ],
            "defaultUsers": [],
            "defaultGroups": []
        },
        {
            "name": "archivist__c",
            "label": "Archivist",
            "assignedUsers": [],
            "assignedGroups": [],
            "availableUsers": [
                31662,
                34525,
                25507,
                31615,
                31810
            ],
            "availableGroups": [
                1
            ],
            "defaultUsers": [],
            "defaultGroups": []
        }
. . .
    ]
}

Errors

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

Version History

Since: v5.0

Retrieve Document Role Assignments

You can retrieve the users and groups assigned to a particular role on a document by sending a GET request to the /api/{version}/objects/documents/{id}/roles/{name} endpoint.

For example:

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

Response

On success, Vault returns the users and groups assigned to a particular role on a specified document:

Exmaple:

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document role retrieved",
    "documentRoles": [
        {
            "name": "reviewer__v",
            "label": "Reviewer",
            "assignedUsers": [],
            "assignedGroups": [],
            "availableUsers": [
                31662,
                34525,
                25507,
                31615,
                31810
            ],
            "availableGroups": [
                1
            ],
            "defaultUsers": [],
            "defaultGroups": []
        }
    ]
}

Errors

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

Version History

Since: v5.0

Assign Users/Groups to Role

You can add a user or group to a document by assigning them to an available role for the document by sending a POST request to the /api/{version}/objects/documents/{id}/roles endpoint.

For example:

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-d "consumer__v.users=19376,18234,19456&legal__c.groups=19365,18923"
https://{CUSTOMER}.veevavault.com/api/{version}/objects/documents/{id}/roles/{name}

Request Parameters

Provide lists of users or groups and their corresponding roles in the form of {role_name}.{"users"|"groups"}=ID1,ID2 for example:

• consumer__v.users=19376,18234,19456
• legal__c.groups=19365,18923
  

Note that if the role is not available for the document or the user/group is not allowed for the role, the API will skip assigning that user/group but will attempt other users/groups in the request. You will need to confirm the list of role:ID pairs returned in the results with the requested roles to ensure all users and groups were successfully added.

Response

On success, Vault returns a list of role:ID pairs for each of the successfully added users or groups.

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Document roles updated",
  "updatedRoles": {
    "consumer__v": {
      "users": [
        19376,18234,19456
      ]
    },
    "legal__c": {
      "groups": [
        19365,18923
      ]
    }
  }
}

Errors

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

Version History

Since: v5.0

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

Body Parameters

You can add parameters in the request body, or upload them as a CSV file.

For example,

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.

Delete User/Group from Role

You can delete a selected user or group from a document's role by sending a DELETE request to the /api/{version}/objects/documents/{id}/roles/{role_name}.{"user"|"group"}/{user ID | group ID} endpoint.

For example:

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

Response

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

Example:

{
  "responseStatus": "SUCCESS",
  "responseMessage": "User/group deleted from document role",
  "updatedRoles": {
    "consumer__v": {
      "users": [
        19376
      ]
    }
  }
}

Errors

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

Version History

Since: v5.0

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

Body Parameters

You can add parameters in the request body, or upload them as a CSV file.

For example,

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 users object represents the actual users of Veeva Vault. This API lets you create, retrieve, update and delete users in the Vault domain as well as manage the users in the specific Vault application.

User Metadata

The users object consists of the following fields:

Retrieve User Metadata

You can retrieve the user metadata by sending the GET request to the /api/{version}/metadata/objects/users endpoint.

For example:

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

Response

On success, Vault returns the list of user properties, each property is described with this metadata field information:

Errors

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

Version History

Since: v1.0

Create User

You can creates a new user in the Vault domain and/or the current Vault application by sending POST request to /api/{version}/objects/users endpoint.

• The HTTP Request Header Content-Type must be set to multipart/form-data.
• Refer to the output of the "User Metadata" API for the request parameters. Only properties marked as "onCreateEditable": true are valid for the user creation, only those that are marked as "required": true must be set.
• To upload a profile picture file, use multi-part attachment with the file component named file.

Domain Level User Management

The Domain Administrators are able to create users in the Vault domain without adding them to a Vault application by including additional request parameter domain set to true. When creating users in the domain only, active__v and user_type_id__v properties are not required.

Response

On success, Vault returns the ID of the newly created user.

Errors

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

Version History

Since: v1.0
v7.0: domain-level properties supported
v8.0: domain_active__v property cannot be set during User creation

Retrieve Users

You can retrieve the users in the Vault domain and/or the current Vault application by sending a GET request to the /api/{version}/objects/users endpoint.

For example:

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

The Administrators are allowed to access user's profile information across the Vault domain. The Domain Administrators are additionally allowed to access user's Vault membership information across the Vault domain.

Request Parameters

The Administrators (System Administrator, Vault Owner) are able to access user information across the domain by including optional query string parameter vaults set as following:

• all Return users across entire domain
• -1 Return users across entire domain excluding current Vault instance
• comma-delimited Vault application IDs. Return users from Vault instances included in the list

The Administrator must have administrative access to Vault application referenced in the vaults parameter to be able to access users from that Vault. Domain Administrator have unrestricted access to all users in the Domain domain.

Response

On success, Vault returns the properties of the users

The response supports pagination. By default the page limit is set to 200 records. The pagination parameters are:

Administrators (System Administrator, Vault Owner) can access user's Vault membership from vault_membership field in each of the user records. The Domain Administrators additionally can access user's user_type__v and active__v status in each of the Vault instances.

Errors

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

Version History

Since: v1.0
v7.0: added support for accessing the user information across the domain for Administrators

Retrieve User

You can retrieve the user record by sending the GET request to the /api/{version}/objects/users/{id} endpoint.

For example:

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

Response

On success, Vault returns the properties of the specified user

Errors

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

Version History

Since: v1.0

Update User

You can updates the user record in the Domain and/or the current Vault application by sending a PUT request to the /api/{version}/objects/users/{id} endpoint.

Request Parameters

Refer to the output of the "User Metadata" API for the request parameters. Only properties marked as "editable=true are valid for the user update. The API currently does not support the update of profile pictures.

Domain Level User Management

Administrators (System Administrator, Vault Owner) are able to update users in the Vault applications where they have administrative access. Domain Administrators have an unrestricted access to users in the entire Domain.

To activate/deactivate the user at the Domain level, domain_active__v property can be set to respective boolean value. Disabling the user (i.e. setting domain_active__v to false) at the domain level will disable the user in every Vault in the domain. Re-enabling the user, on the other hand, will only re-enable them at the domain level. This property is only editable by the Domain Administrator users.

To promote the user to Domain Admin, is_domain_admin__v property can be set to true. Only a Domain Administrator user is capable of promoting another domain user to Domain Admin role. Similarly, to demote the user from Domain Admin, domain_admin__v property can be set to false. Only Domain Admin user can demote a user. The Domain Admin can demote it's own user record only if there is another active Domain Admin user in the domain.

Response

On success, Vault returns the id of the updated user.

Errors

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

Version History

Since: v1.0
v7.0: Domain-level user management is supported

Disable User

You can disables the user in the Domain or the current Vault application by sending a DELETE request to the /api/{version}/objects/users/{id} endpoint.

By default the user is disabled at Vault level. The Domain Administrator users can optionally disable the user at the domain level by setting domain request parameter to true, affecting the user's status in every Vault application in the domain.

For example:

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://{CUSTOMER}.veevavault.com/api/{version}/objects/users/{id}?domain=true

Response

On success, Vault returns the ID of the disabled user

Errors

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

Version History

Since: v1.0
v7.0: Domain-level user management is supported

Change Password

You can change your password by sending the POST request to the /api/{version}/objects/users/{id}/password endpoint.

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-d "password__v=CurrentPassword&new_password__v=NewPassword" \
https://{CUSTOMER}.veevavault.com/api/{version}/objects/users/{id}/password

Request Parameters

Response

On success, Vault changes the password and returns SUCCESS.

Errors

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

Version History

Since: v7.0

Update Vault Membership

You can manage the user's Vault membership in the domain by sending the PUT request to the /api/{version}/objects/users/{id}/vault_membership/{vaultId} endpoint.

NOTE: Accessible only to Administrator users

Through this API it is possible to:

• add a domain user to a Vault
• deactivate user's Vault membership in a specified Vault
• manage user's user type in a specified Vault

Request Parameters

Errors

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

Version History

Since: v7.0

Groups

The groups object represents the Groups in Veeva Vault. This API lets you create, retrieve, update and delete groups in Vault as well as manage the users in these groups.

Group Metadata

The groups object consists of the following fields:

Retrieve Group Metadata

You can retrieve the group metadata by sending the GET request to the /api/{version}/metadata/objects/groups endpoint.

For example:

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

Response

On success, Vault returns the list of group properties, each property is described with this metadata field information:

Example:

{
    "responseStatus": "SUCCESS",
    "properties": [
        {
            "name": "id",
            "type": "id",
            "length": 20,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "group_name__v",
            "type": "String",
            "length": 255,
            "editable": true,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "group_description__v",
            "type": "String",
            "length": 200,
            "editable": true,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "system_group__v",
            "type": "Boolean",
            "length": 1,
            "editable": false,
            "queryable": true,
            "required": false,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "created_date__v",
            "type": "Calendar",
            "length": 0,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "created_by__v",
            "type": "ObjectReference",
            "length": 20,
            "object": "users",
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "modified_date__v",
            "type": "Calendar",
            "length": 0,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "modified_by__v",
            "type": "ObjectReference",
            "length": 20,
            "object": "users",
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "members__v",
            "type": "ObjectReference",
            "length": 20,
            "object": "users",
            "editable": true,
            "queryable": false,
            "required": true,
            "multivalue": true,
            "onCreateEditable": true
        },
        {
            "name": "active__v",
            "type": "Boolean",
            "length": 1,
            "editable": true,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        }
    ]
}