Vault API Reference

API Reference (v11.0)

This is the documentation for the Vault API v11.0. The documentation for the previous version v10.0 is here.

Refer to the latest API Release Notes for the new features introduced in this version of the API.

Refer to Vault Help for detailed Vault user and administrator information.

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. Applications can easily acquire a session ID for Vault users by following the steps described in the Authentication article. 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

Refer to the Authentication article for detailed information about each of these methods.

API Metadata

Retrieve Available API Versions

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

For example:

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

Response

The response contains a list of all available API versions.

Example:

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

Errors

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

Version History

Since: v1.0

Retrieve Available API Resources

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

For example:

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

Response

The response contains a list of the available API resources.

Example:

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

Errors

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

Version History

Since: v1.0


Domain Information

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

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

Retrieve Domain Information

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

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

For example:

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

Response

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

Field Description
domain_type__v Type of domain
id Vault instance ID
vault_name__v Vault name
vault_status__v Vault status
vault_application__v Vault application type

Example:

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

Errors

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

Version History

Since: v7.0


Document Metadata

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

Retrieve All Document Types

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

For example:

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

Response

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

Field Description
types[n] List of document types available in Vault
label Label of the document type
value Url for the metadata of the document type; use this url to get the subtypes for this type
lock Url for the lock metadata

Example:

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

Errors

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

Version History

Since: v1.0

Retrieve Document Type

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

For example:

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

Response

The response contains the metadata for the document type.

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

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

Field Description
name Name of the specified document type
label UI-friendly label for the specified document type
properties[n] List of document fields that apply to the specified type
renditions[n] List of rendition types that apply to the specified document type
relationshipTypes[n] List of relationship types valid for the specified document type
processes[n] List of valid processes
defaultWorkflows[n] List of valid default Workflows valid for the specified document type
availableLifecycles[n] List of available Lifecycles valid for the specified document type
templates[n] List of of templates valid for the specified document type
subtypes[n] List of document subtypes configured for the specified document type

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

Errors

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

Version History

Since: v1.0

Retrieve Document Subtype

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

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

For example:

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

Response

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

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

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

Field Description
name Name of the specified document subtype
label UI-friendly label for the specified document subtype
properties[n] List of document fields that apply to the specified subtype
relationshipTypes[n] List of relationship types valid for the specified document subtype
processes[n] List of valid processes
defaultWorkflows[n] List of valid default Workflows valid for the specified document subtype
availableLifecycles[n] List of available Lifecycles valid for the specified document subtype
templates[n] List of of templates valid for the specified document subtype
classifications[n] List of document classifications configured for the specified document subtype

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

Errors

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

Version History

Since: v1.0

Retrieve Document Classification

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

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

For example:

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

Response

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

Field Description
name Name of the specified document classification
label UI-friendly label for the specified document classification
properties[n] List of document fields that apply to the specified classification
relationshipTypes[n] List of relationship types valid for the specified document classification
processes[n] List of valid processes
defaultWorkflows[n] List of valid default Workflows valid for the specified document classification
availableLifecycles[n] List of available Lifecycles valid for the specified document classification
templates[n] List of of templates valid for the specified document classification

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

Errors

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

Version History

Since: v1.0

Retrieve Document Fields

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

For example:

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

Response

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

Field Description
name Document Field Name
label Document Field Label - Example: "Title", "Format", "Size", etc.
type Document Field Type - Values: "String", "Number", "Date", "Boolean", "Picklist", "ObjectReference", etc.
objectType When "type": "ObjectReference", this indicates the object being referenced. Values: "User", "Group", "product__v", etc.
scope Document field scope - Values: "Document", "DocumentVersion"
required Indicates if the field is required - Values: "true", "false"
repeating Indicates if the field is repeating - Values: "true", "false"
editable Indicates if the field is editable - Values: "true", "false"
queryable Indicates if the field is exposed in query - Values: "true", "false"
shared Indicates if the field is shared - Values: "true", "false"
hidden Indicates if the field is hidden - Values: "true", "false"
disabled Indicates if the field is disabled - Values: "true", "false"
systemAttribute Indicates if the field is standard (system-managed) - Values: "true", "false"
setOnCreateOnly Indicates if the field can only be set on document creation - Values: "true", "false"
definedInType Indicates if the field is defined in a document "type", "subtype", or "classification"
definedIn Document type/subtype/classification where the field is defined. Example: "base_document__v"
usedIn When "shared": true, lists in the key and type fields (below) the other document types/subtypes/classifications where the field is used
usedIn: key When "shared": true, lists the names of the document types using the shared field. Example: "country_master_file__v"
usedIn: type When "shared": true, indicates whether the shared field is used by a document "type", "subtype", or "classification"
section Section in field layout where field appears. Example: "generalProperties"
sectionPosition Field's numeric position within the section
entryLabels When "type": "Picklist", lists the picklist value labels. Example: "Latest version", Latest Steady State version, etc.
minValue When "type": "Number", indicates the field's minimum value
maxValue When "type": "Number", indicates the field's maximum value
maxLength When "type": "String" or "id", indicates field's maximum character length
scale When "type": "Number", indicates the number of decimal places
helpContent Displays optional help text for the field

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

Errors

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

Version History

Since: v4.0

Retrieve Document Relationships

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

For example:

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

Response

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

Field Description
- properties[n] List of relationship fields that apply to all relationship types
------ name Relationship Field Name
------ type Relationship Field Type - Values: "id", "Integer", String", DateTime", "ObjectReference", etc.
------ length Indicates the maximum character length of the field; some field types will always have "0" as the length
------ editable Indicates if the field is editable - Values: "true", "false"
------ queryable Indicates if the field is exposed in query - Values: "true", "false"
------ required Indicates if the field is required - Values: "true", "false"
------ multivalue Indicates if the field is multi-valued - Values: "true", "false"
------ onCreateEditable Indicates if the field can be set only on document creation - Values: "true", "false"
- relationshipTypes[n] List of relationships available for the specified document type, with each array item giving details for each relationship type
------ value Relationship Type Value - Values: "supporting_documents_vs", "references_vs", etc.
------ label Relationship Type Label - Values: "Supporting Documents", Linked Documents, etc.
------ sourceDocVersionSpecific Indicates if the source document in the relationship is version-specific - Values: "true", "false"
------ targetDocVersionSpecific Indicates if the target document in the relationship is version-specific - Values: "true", "false"
------ system Indicates if the relationship type is standard (system-managed) - Values: "true", "false"
------ singleUse Indicates if the relationship type can only be used once for each document - Values: "true", "false"
------ targetDocumentTypes List of document types which are valid as target documents for the relationship
------ targetDocumentTypes: label Document type label - Example: "Regulatory"
------ targetDocumentTypes: value Document type name - Example: "regulatory__vs"

Example:

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

Errors

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

Version History

Since: v3.0

Retrieve Document Lock Metadata

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

For example:

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

Response

The response contains the document lock metadata.

Field Description
name Field Name
label Field label
type Field type
scope Field scope; this value is "Lock" for all fields
required Indicates if the field is required
systemAttribute Indicates if the field is system managed/standard
editable Indicates if the field is editable
setOnCreateOnly ndicates if the field can only be set on document creation
disabled Indicates if the field is disabled
objectType Object type if field: type is set to ObjectReference
hidden Indicates if the field is hidden

Example:

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

Errors

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

Version History

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

Find Common Document Fields

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

For example:

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

Response

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

Errors

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

Version History

Since: v9.0

Create Document

The API supports the following create document actions:

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

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

About Required & Editable Fields

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

To retrieve document fields in your vault:

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

About Default Field Values

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

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

For example:

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

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

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

About Document Templates

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

Create Document from Uploaded File

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

Method & Endpoint

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

Request Headers

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

Upload the Source File

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

Required Standard Fields

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

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

Additional Required & Editable Fields

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

Example Request

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

This example includes:

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

Example JSON Response

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

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

Possible Errors

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

Version History

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

Create Document from Template

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

Method & Endpoint

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

Request Headers

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

Select the Document Template

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

Required Standard Fields

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

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

Additional Required & Editable Fields

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

Example Request

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

This example includes:

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

Example JSON Response

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

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

Possible Errors

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

Version History

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

Create Content Placeholder Document

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

Method & Endpoint

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

Request Headers

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

Required Standard Fields

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

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

Additional Required & Editable Fields

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

Example Request

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

This example includes:

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

Example JSON Response

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

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

Possible Errors

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

Version History

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

Create Unclassified Document

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

Method & Endpoint

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

Request Headers

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

Upload the Source File

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

Required Standard Fields

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

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

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

  • product__v
  • study__v
  • study_country__v
  • site__v

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

Example (All vaults)

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

Example (eTMF vaults)

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

Response

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

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

Possible Errors

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

Version History

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

Create CrossLink Document

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

Method & Endpoint

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

Request Headers

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

Required Standard Fields

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

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

Optional Standard Fields

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

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

Additional Required & Editable Fields

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

Example Request

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

This example includes:

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

Example JSON Response

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

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

Possible Errors

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

Version History

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

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

Field Description
named_filter one of My Documents (get my documents), Recent Documents (get recent documents) or Favorites (get my favorite documents)
search used to do keyword search across all document properties; only one of named_filter or search can be used, using both is an error
scope used in conjunction with search to indicate whether the search is against all searchable properties (scope = properties) or against searchable properties and document content (scope = all). The default is properties and is assumed if not set.
start [optional, default: 0] number indicating the row offset in the result
limit [optional, default and absolute maximum: 200] number indicating the maximum number of documents to return
sort [optional] sort field followed by sort order, e.g. name__v desc

For example:

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

Response

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

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

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

Errors

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

Version History

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

Retrieve Document

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

For example:

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

Response

On success, Vault returns the fields and values for the document. The fields present in the response will vary based on the definition of the document type of the returned document.

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

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

Errors

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

Version History

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

Retrieve Document Versions

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

For example:

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

Response

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

Field Description
versions contains a list of document version
- number the version number; first value is the major version, second is the minor version
- value the API URL for the specific version
renditions the list of API URLs for of the document's renditions

Example:

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

Errors

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

Version History

Since: v1.0

Retrieve Document Version

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

For example:

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

Response

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

Errors

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

Version History

Since: v1.0

Update Document

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

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

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

Response

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

Example:

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

Errors

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

Version History

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

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

Field Description
locked_by__v ID of the user who locked the document
locked_date__v Timestamp when the document was locked

Example:

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

Errors

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

Version History

Since: v1.0

Delete Document Lock

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

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v1.0

Update Document File / Create Draft

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

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

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

Request Parameters

  • description__v - To set the description for the minor version update, include this parameter in the requested set to the description string.
  • createDraft - optional [latestContent|uploadedContent]

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

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

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

Response

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

Errors

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

Version History

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

List Document Renditions

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

For example:

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

Response

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

Errors

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

Version History

Since: v1.0

List Document Version Renditions

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Retrieve Document Rendition

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

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

For example:

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

Response

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

Errors

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

Version History

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

Retrieve Document Version Rendition

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Retrieve Document Annotations

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

For example:

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

Response

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

Errors

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

Version History

Since: v11.0

Retrieve Document Version Annotations

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

For example:

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

Response

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

Errors

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

Version History

Since: v11.0

Upload Document Rendition

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

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

For example:

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

Response

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

Errors

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

Version History

Since: v1.0

Upload Document Version Rendition

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

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Upload Document Annotations

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

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

For example:

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

Response

On success, Vault uploads the file and its annotations.

Errors

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

Version History

Since: v11.0

Upload Document Version Annotations

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

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

For example:

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

Response

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

Errors

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

Version History

Since: v11.0

Delete Latest Document Rendition

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Delete Document Version Rendition

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Replace Document Rendition

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

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

Replace Document Version Rendition

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

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

For example:

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

Response

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

Errors

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

Version History

Since: v7.0

List Document Relationships

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

For example:

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

Response

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

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

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

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

Version History

Available in API v3.0 or later.

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

Bulk Documents API

Bulk Documents API Method API Endpoint Input Output Batch Size Available in API
Create Documents POST /api/{VERSION}/objects/documents/batch CSV CSV, JSON 1-500 v9.0 or later
Update Documents PUT /api/{VERSION}/objects/documents/batch CSV, Form Data CSV, JSON 1-1000 v9.0 or later
Delete Documents DELETE /api/{VERSION}/objects/documents/batch CSV, JSON CSV, JSON 1-500 v13.0 or later
Add Document Versions POST /api/{VERSION}/objects/documents/versions/batch CSV CSV, JSON 1-500 v10.0 or later
Delete Document Versions DELETE /api/{VERSION}/objects/documents/versions/batch CSV, JSON CSV, JSON 1-500 v13.0 or later
Add Document Renditions POST /api/{VERSION}/objects/documents/renditions/batch CSV CSV, JSON 1-500 v10.0 or later
Delete Document Renditions DELETE /api/{VERSION}/objects/documents/renditions/batch CSV, JSON CSV, JSON 1-500 v13.0 or later

Create Documents in Bulk

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

Available in API v9.0 or later.

Update Documents in Bulk

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

Available in API v9.0 or later.

Add Document Versions in Bulk

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

Available in API v10.0 or later.

Add Document Renditions in Bulk

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

Available in API v10.0 or later.

Document Events

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

Document Events Metadata

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

Retrieve Available Document Event Types

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

For example:

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

Response

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

Example:

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

Errors

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

Version History

Since: v6.0

Retrieve Event Type Metadata & Defined Subtypes

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

For example:

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

Response

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

Errors

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

Version History

Since: v6.0

Document Events Data

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

Retrieve Document Event Data

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

Request Parameters

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

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

  • Use startDate and endDate parameters to filter by date range

    • the date can be specified in UTC including the time part, although the time part is optional. If time part is not included a midnight on the specified date is assumed.
  • Use limit and start parameters for paginating over the result set

Response

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

Errors

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

Version History

Since: v6.0

Log a Document Event

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

Request Parameters

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

Response

On success, Vault logs the document event.

Errors

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

Error Type Description
INSUFFICIENT_ACCESS This error occurs if the user does not have permission to log an event of specified type
INVALID_DATA This error occurs if the value specified for the parameter is invalid (i.e. validation error). As part of the error a list of all properties which have an error will be returned
PARAMETER_REQUIRED This error occurs if the required parameter is not provided. As part of the error a list of all missing parameters will be returned.
METHOD_NOT_SUPPORTED This error occurs if the URL is constructed with an invalid event type, or any other endpoint related issues occur.

Version History

Since: v6.0


Attachments

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

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

Attachment Fields

Attachments have the following metadata:

Field Name Description
id ID of the attachment
version__v Version of the attachment (1, 2, 3...)
filename__v File name of the attachment
description__v Optional description added to the attachment
format__v File format of the attachment
size__v File size of the attachment
md5checksum__v MD5 checksum value calculated for the attachment
created_by__v User ID of the person who created the attachment
created_date__v Date the attachment was created
versions[n] List of links to earlier versions of the attachment

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

Attachments on Documents

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

Determine if a Document has Attachments

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

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

Response (abridged)

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

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

List Attachments

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

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

Response

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

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Retrieve Attachment Metadata

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

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

Response

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

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

List Attachment Versions

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

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

Response:

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Retrieve Attachment Version Metadata

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

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

Response

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Download Attachment

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

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

Response

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

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Download Attachment Version

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

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

Response

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

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Download All Attachments

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

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

Response

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

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Delete Attachment

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

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

Response

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

{
    "responseStatus": "SUCCESS"
}

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Delete Attachment Version

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

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

Response

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

{
    "responseStatus": "SUCCESS"
}

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Add Attachment

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

  • The maximum file size allowed is 4GB.
  • The HTTP Request Header Content-Type must be set to multipart/form-data
  • The file component of the multipart request must be specified as file
  • If an attachment is added which has the same filename as an existing attachment on a given document, the new attachment is added as a new version of the existing attachment.
  • If an attachment is added which is exactly the same (same MD5 checksum value) as an existing attachment on a given document or object record, the new attachment is not added.

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

  • filename__v
  • format__v
  • size__v

Response

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

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Restore Attachment Version

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

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

The parameter restore must be set to true

Response

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

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Update Attachment Description

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

Required Parameters

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Attachments on Object Records

Determine if Attachments are Enabled

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

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

Response (abridged)

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

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

Version History

Since: v11.0

List Attachments

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

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

Where "1357752909483" is the site__v object record id.

Response

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

Shown above, the site__v object record has three versions of attachment id 558 and one version of attachment id 571. Attachment versioning uses integer numbers beginning with 1 and incrementing sequentially (1, 2, 3,...). There is no concept of major or minor version numbers with attachments.

Errors

On failure, the response will contain an error response.

Error Type Message Description
MALFORMED_URL The resource [{resource}] does not exist. The user is attempting to retrieve metadata from an object record {id} which does not exist.

Version History

Since: v11.0

Retrieve Attachment Metadata

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

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

Where "1357752909483" is the site__v object record id.

Response

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

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

Errors

On failure, the response will contain an error response.

Error Type Message Description
MALFORMED_URL The resource [{id}] does not exist. The user is attempting to retrieve metadata from an attachment {id} which does not exist on the specified object record.

Version History

Since: v11.0

List Attachment Versions

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

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

Where "1357752909483" is the site__v object record id.

Response

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

Errors

On failure, the response will contain an error response.

Error Type Message Description
MALFORMED_URL The resource [{id}] does not exist. The user is attempting to retrieve metadata from an attachment {id} which does not exist on the specified object record.
MALFORMED_URL The resource [{id}/version/{version}] does not exist. The user is attempting to retrieve metadata from a specific version {version} of an attachment {id} which does not exist on the specified object record. The attachment {id} exists but the version number {version} does not.

Version History

Since: v11.0

Retrieve Attachment Version Metadata

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

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

Where "1357752909483" is the site__v object record id.

Response

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

Errors

On failure, the response will contain an error response.

Error Type Message Description
MALFORMED_URL The resource [{id}] does not exist. The user is attempting to retrieve metadata from an attachment {id} which does not exist on the specified object record.
MALFORMED_URL The resource [{id}/version/{version}] does not exist. The user is attempting to retrieve metadata from a specific version {version} of an attachment {id} which does not exist on the specified object record. The attachment {id} exists but the version number {version} does not.

Version History

Since: v11.0

Download Attachment

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

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

Where "1357752909483" is the site__v object record id.

Response

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

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

Errors

On failure, the response will contain an error response.

Error Type Message Description
MALFORMED_URL The resource [{id}] does not exist. The user is attempting to download an attachment {id} which does not exist on the specified object record.
MALFORMED_URL The resource does not contain attachments The user is attempting to download an attachment from an object record which does not have any attachments.

Version History

Since: v11.0

Download Attachment Version

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

Example:

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

Where "1357752909483" is the site__v object record id.

Response

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

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

Errors

On failure, the response will contain an error response.

Error Type Message Description
MALFORMED_URL The resource [{id}] does not exist. The user is attempting to download an attachment {id} which does not exist on the specified object record.
MALFORMED_URL The resource [{id}/version/{version}] does not exist. The user is attempting to download a specific version {version} of an attachment {id} which does not exist on the specified object record. The attachment {id} exists but the version number {version} does not.
MALFORMED_URL The resource does not contain attachments The user is attempting to download an attachment from an object record which does not have any attachments.

Version History

Since: v11.0

Download All Attachments

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

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

Response

On success, Vault retrieves the latest version of all attachments from the object record. The downloaded attachments are packaged in a ZIP file with the file name: {object type label} {object record name} - attachments.zip.

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

Errors

On failure, the response will contain an error response.

Error Type Message Description
MALFORMED_URL The resource does not contain attachments The user is attempting to download attachments from an object record which does not have any attachments.

Version History

Since: v11.0

Delete Attachment

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

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

Response

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

{
    "responseStatus": "SUCCESS"
}

Errors

On failure, the response will contain an error response.

Error Type Message Description
MALFORMED_URL The resource [{id}] does not exist. The user is attempting to delete an attachment {id} which does not exist on the specified object record.

Version History

Since: v11.0

Delete Attachment Version

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

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

Response

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

{
    "responseStatus": "SUCCESS"
}

Errors

On failure, the response will contain an error response.

Error Type Message Description
MALFORMED_URL The resource [{id}] does not exist. The user is attempting to delete an attachment {id} which does not exist on the specified object record.
MALFORMED_URL The resource [{id}/version/{version}] does not exist. The user is attempting to delete a specific version {version} of an attachment {id} which does not exist on the specified object record. The attachment {id} exists but the version number {version} does not.

Version History

Since: v11.0

Add Attachment

You can add an attachment to an object record in Vault by sending a POST request to the /vobjects/{name}/{id}/attachments endpoint.

  • The maximum file size allowed is 4GB.
  • The HTTP Request Header Content-Type must be set to multipart/form-data
  • The file component of the multipart request must be specified as file
  • If an attachment is added which has the same filename as an existing attachment on a given object record, the new attachment is added as a new version of the existing attachment.
  • If an attachment is added which is exactly the same (same MD5 checksum value) as an existing attachment on a given object record, the new attachment is not added.

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

  • filename__v
  • format__v
  • size__v

Response

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

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

Errors

On failure, the response will contain an error response.

Error Type Message Description
MALFORMED_URL The resource is not enabled for attachments The user is attempting to add an attachment to an object record for which attachments have not been enabled.
OPERATION_NOT_ALLOWED Cannot add an attachment : number of allowed attachments exceeds max [50] The user is attempting to add an attachment to an object record which already has the maximum number of allowed attachments (50).
OPERATION_NOT_ALLOWED Cannot add an attachment : maximum attachment file size exceeds max [{n}] The user is attempting to add an attachment to an object record which exceeds the maximum file size allowed for an attachment (2GB).

Version History

Since: v11.0

Restore Attachment Version

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

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v11.0/vobjects/site__v/1357752909483/attachments/571/versions/2?restore=true

The parameter restore must be set to true

Response

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

{
    "responseStatus": "SUCCESS",
    "data":
    {
        "id": "571",
        "version__v": 2
    }
}

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.0

Update Attachment Description

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

Required Parameters

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

Errors

On failure, the response will contain an error response.

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

Version History

Since: v11.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:

Property Description
name The entry requirement name (used in the API). This value must be specified when starting the lifecycle action.
description The entry requirement name (used in the UI).
type The entry requirement data type. This value can be one of String, Number, Date, Boolean, Picklist, or ObjectReference.
objectTypeReferenced When type is ObjectReference, this is the object being reference. For example: User, Product, Country, etc.
required Boolean value indicating whether or not the entry requirement must be specified when initiating a lifecycle action.
editable Boolean value indicating whether or not the value can be edited by the user.
repeating Boolean value indicating whether or not the entry requirement can have multiple values.
minValue Indicates the minimum character length for the value.
maxValue Indicates the maximum character length for the value.
values When type is Picklist, this provides a list of possible values that can be used.
currentSetting When a value has already been set, this shows the value.
scope Indicates where the property is defined. This can be one of Document, Binder, WorkflowActivation, EmailFragment, ControlledCopy, or CreatePresentation.

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

Field Description
depth [string] number of levels to return of the binder structure. Default is "1" and will return top level sections in the binder. Valid values are "1" and "all" where "all" returns the entire binder structure. An example would be .../objects/binders/1255?depth=all to return the entire binder structure.

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 type
  • 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 Document type
  • 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 Document type
  • 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.

Type Description
INVALID_BINDER ID passed is not for a binder

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.

Type Description
INVALID_BINDER ID passed is not for a binder

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.

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

Version History

Since: 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

Field Description
target_doc_id__v [required] relationship target document id
relationship_type__v [required] is the value of property value of one of the desired relationshipTypes from the "Documents Relationships Metadata" call
target_major_version__v [optional] if applicable to the type of relationship being created, this is the major version of the target document
target_minor_version__v [optional] if applicable to the type of relationship being created, this is the minor version of the target document

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:

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

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 does 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

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

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.

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

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

Field Description
name__v [retuired] Section name
section_number__v [optional] Section number
parent_id__v [optional] Node ID of the parent section; if blank, the new section will be a top-level section.
order__v [order] Order within the parent section or (if top-level) within the binder; "0" is the first position. Blank means add it as the last element in the binder or parent section.

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.

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

Version History

Since: v5.0

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 type * 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 Document type * 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 Document type * 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.

Error Type Description
INVALID_BINDER ID passed is not for a binder
INVALID_SECTION Parent section ID is not a valid section

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 type * 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 Section * 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.

Error Type Description
INVALID_BINDER ID passed is not for a binder
INVALID_SECTION Parent section ID is not a valid section

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}/versions/{major}/{minor}/sections/{section_node_id} endpoint.

Request Parameters

Field Description
name__v [optional] Section name
section_number__v [optiona] Section number
parent_id__v [optional] ID of new parent section or of binder, if the section is top-level; specifying a parent ID will move the section within the hierarchy. If blank, the section stays in the same level within the hierarchy
order__v [optional] New location within the binder. If moving to a new section (as defined by new parent_id__v being specified), this is the position within the target section or binder. If new parent_id__v is blank, the sections will move within the current section. If new order__v is greater than the available positions, it will be placed in the last position.

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.

Error Type Description
INVALID_BINDER ID passed is not for a binder
INVALID_SECTION Section ID is not a valid section
INVALID_TARGET_SECTION Parent ID is not a valid section within the binder or the Binder ID itself

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

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

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

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.

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

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.

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

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

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

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.

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

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

Field Description
parent_id__v [optional] the node ID of the new parent section (or binder if moving it to the top level of the binder)
order__v [optional] the ordinal position within the target section or binder. If parent_id__v is blank, the the document will be moved within the current section. If order__v is greater than the available positions, it will be placed in the last position.

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.

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

Version History

Since: v5.0

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

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

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.

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

Version History

Since: v5.0

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.

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

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.

Bulk Document Roles API

Bulk Document Roles API Method API Endpoint Input Output Batch Size Available in API
Assign Users & Groups to Document Roles POST /api/{VERSION}/objects/documents/roles/batch CSV, Form Data CSV, JSON 1-1000 v9.0 or later
Remove Users & Groups from Document Roles DELETE /api/{VERSION}/objects/documents/roles/batch CSV, Form Data CSV, JSON 1-1000 v9.0 or later

Assign Users & Groups to Document Roles in Bulk

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

Available in API v9.0 or later.

Remove Users & Groups from Document Roles in Bulk

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

Available in API v9.0 or later.

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:

Fields Description
documentRoles[n] List of all active roles assigned to the selected document
-- name Role name (public key)
-- label Role label
-- assignedUsers List of the IDs for all users in the selected role assigned to the document
-- assignedGroups List of the IDs for all groups in the selected role assigned to the document
-- availableUsers List of the IDs for all users available in the selected role
-- availableGroups List of the IDs for all groups available in the selected role
-- defaultUsers List of the default user IDs for the selected role
-- defaultGroups List of the default group IDs for the selected role

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:

Fields Description
documentRoles[1] Contains the active roles assigned to the document for a specific role
-- name Role name (public key)
-- label Role label
-- assignedUsers List of the IDs for all users in the selected role assigned to the document
-- assignedGroups List of the IDs for all groups in the selected role assigned to the document
-- availableUsers List of the IDs for all users available in the selected role
-- availableGroups List of the IDs for all groups available in the selected role
-- defaultUsers List of the default user IDs for the selected role
-- defaultGroups List of the default group IDs for the selected role

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.

Error Type Description
ROLE_NOT_FOUND Role of name [name] was not found

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
Fields Description
{role_name}.users [optional] Name (public key) of the role to which you're adding a user with ".users" appended to indicate that the ID is for a user
{role_name}.groups [optional] Name (public key) of the role to which you're adding a group with ".groups" appended to indicate that the ID is for a group

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

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.

Error Type Description
ROLE_NOT_FOUND Role of name [role_name] was not found
USER_OR_GROUP_NOT_FOUND User or group of ID [user/group ID] was not assigned to role [role_name]

Version History

Since: v5.0



Users

The Vault users object includes a fixed set of metadata. You cannot add or remove fields, nor can you change the field names or labels.

About Domain-Level User Management

Vault user accounts exist at the domain level, so in multi-vault domains, user details are shared across vaults.

Users in the Vault Owner and System Admin roles have access to all users in the vaults where they are assigned administrative access. Users with the Domain Admin setting enabled in their user profile and assigned the Admin: Users: Create, Edit permission in every domain vault, have access to all users across all vaults in your domain. Learn about Permission Sets in Vault Help.

To support domain-level user management, the API includes the following input options and request parameters:

  • domain=true - When creating a user, this can be (optionally) included in the input to add the user to the domain but not assign them to any vaults in the domain. When disabling a user, this is added to the request endpoint.
  • domain_active__v - When updating a user, this can be (optionally) included in the input and set to either true or false to enable or disable the user at the domain-level. Disabling a user at the domain-level will disable the user in every vault in your domain. Re-enabling a user enables them in the domain but does not re-activate them in their vaults. After re-enabling a user, you must update their vault membership to make them active in the individual vaults.
  • is_domain_admin__v - When creating or updating a user, this can be (optionally) included in the input and set to true to make a user a Domain Admin. When updating a user, this can be set to false to remove them from the Domain Admin role. Note that only another Domain Admin can do this. There must always be at least one Domain Admin.

Domain-level user management is available in API v7.0 or later.

Vault User Metadata

Required Fields: With the exception of the Vault User ID, the fields listed below are required when adding new users to a vault.

Field Name Field Label Field Type Description Required Editable Queryable
id ID id Unique user identifier (primary). Numeric value. System-Managed False True
user_name__v User Name String Unique user identifier. This is the user's vault login credential. True True True
user_email__v Email String The user's email address. Vault notifications are sent to this address. True True True
user_first_name__v First Name String The user's first name. True True True
user_last_name__v Last Name String The user's last name. True True True
user_language__v Language String The user's preferred language. Available values displayed in metadata response. True True True
user_timezone__v Timezone String The user's time zone. Available values displayed in metadata response. True True True
user_locale__v Locale String The user's location. Available values displayed in metadata response. True True True
security_policy_id__v Security Policy ObjectReference The user's security policy. Learn more. True True True
vault_id__v Vault ID ObjectReference The ID of the vault to which the user is assigned. Learn more. True ** vault_membership False True
security_profile__v Security Profile * ObjectReference The user's security profile. Available values displayed in metadata response. True ** vault_membership True True
license_type__v License Type * Picklist The user's license type. Learn more. True ** vault_membership True True
active__v Active Boolean Whether or not the user is active in the current Vault application. True ** vault_membership True True

* The security_profile__v and license_type__v fields are available in API v10.0 or later.
** The vault_membership fields are not required to add users to the domain. They are required to assign users to vaults. See Create User and Update Vault Membership below.

Optional Fields: The fields listed below are either optional, editable user fields or system-managed user fields.

Field Name Field Label Field Type Description Required Editable Queryable
company__v Company String The user's company. False True True
user_title__v Title String The user's title. False True True
alias__v Alias String Nickname. Used to differentiate users with the same first and last name. False True False
site__v Site String The user's location, such as a city. In user profiles (UI), this is labeled "Location". False True True
office_phone__v Office Phone Number String The user's office phone number. False True True
mobile_phone__v Mobile Phone Number String The user's mobile phone number. False True True
fax__v Fax Phone Number String The user's fax number. False True True
user_needs_to_change_password__v Change Password Boolean The user is required to change their password on next login. False True True
domain_active__v Domain Active Boolean Whether or not the user is active in the domain. False True True
is_domain_admin__v Is Domain Admin Boolean The user is a Domain Administrator. False True True
domain_id__v Domain ID ObjectReference The ID of the domain to which the user is assigned. System-Managed False True
federated_id__v Federated ID String The user's federated ID if using SAML Single Sign-on Authentication. False True True
salesforce_user_name__v Salesforce Username String The user's Salesforce.com username if using Salesforce Delegated Authentication. False True True
medidata_uuid__v Medidata UUID String The user's Medidata email if using Medidata Delegated Authentication. False True True
group_id__v Group ID ObjectReference The IDs of the groups to which the user is assigned. False False False
created_date__v Created Date Calendar The date and time when the user account was created. System-Managed False True
created_by__v Created By ObjectReference The user ID of the person who created the user account. System-Managed False True
modified_date__v Modified Date Calendar The date and time when the user account was last modified. System-Managed False True
modified_by__v Modified By ObjectReference The user ID of the person who last modified the user account. System-Managed False True
last_login__v Last Login Calendar The date the user last logged into the vault. System-Managed False True

Field Properties: The information listed below may be included with each field.

Field Property Description
name Field name.
type Field type: ID, String, Boolean, Picklist, Calendar, or ObjectReference.
object When the field type is "ObjectReference", this shows the name of the object being referenced.
multivalue Whether or not the field can have multiple values.
queryable Whether or not the field can be used in API queries.
length When the field type is "String", this shows the maximum character length allowed.
required Whether or not the field is required when creating a new user.
onCreateEditable Whether or not the field can be set when creating a new user.
editable Whether or not the field is editable.
values Lists allowed values for the user_locale__v, user_language__v, user_timezone__v, and security_profile__v fields.

Retrieve User Metadata

Use this request to retrieve all user fields and field properties.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Example Request

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

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "properties": [
        {
            "name": "user_name__v",
            "type": "String",
            "length": 255,
            "editable": true,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "user_first_name__v",
            "type": "String",
            "length": 100,
            "editable": true,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        ...

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Retrieve All Users

Use this request to retrieve all users and user metadata.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Optional Request Parameters

Using the endpoint alone with no optional parameters will retrieve users assigned only to the vault in which the request is made.

For customers with multiple vaults in their domain, users with Domain Admin, System Admin, and Vault Owner privileges can access user information across different vaults in the domain by including the optional parameter vaults set to one of the following values:

  • vaults=all - Retrieve all users assigned to all vaults in your domain.
  • vaults=-1 - Retrieve all users assigned to all vaults in your domain except for the vault in which the request is made.
  • vaults={Vault IDs} - Use a comma-separated list of Vault IDs to retrieve users assigned only to the specified vaults.

System Admins and Vault Owners must have administrative access to Vault applications referenced in the vaults parameter to be able to access users from those vault. Learn about domain-level user management above.

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

Field Description
limit [optional, default is 200] the size of the result set in the page
start [optional, default is 0] the starting record number
sort [optional, default is "id asc"] the sort order for the result set (asc - ascending, desc - descending) (e.g. user_name__v asc)

Example Request

This request will retrieve all users assigned to the vault in which the request is made.

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

Example Request

This request will retrieve all users assigned to all vaults in the domain. This is available only to Admin users with administrative access to the vaults.

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/users?vaults=all

Example Request

This request will retrieve all users assigned to all vaults in the domain except the vault in which the request is made. This is available only to Admin users with administrative access to the vaults.

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/users?vaults=-1

Example Request

This request will retrieve all users assigned to vault ID 3003, vault ID 4004, and vault ID 5005. This is available only to Admin users with administrative access to the vaults.

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/users?vaults=3003,4004,5005

Example Response (abridged)

{
    "responseStatus": "SUCCESS",
    "size": 200,
    "start": 0,
    "limit": 200,
    "sort": "id asc",
    "users": [
        {
            "user": {
                "id": 25501,
                "user_name__v": "ewoodhouse@veevapharm.com",
                "user_first_name__v": "Elaine",
                "user_last_name__v": "Woodhouse",
                ...
        },
        {
            "user": {
                "id": 25502,
                "user_name__v": "bashton@veevapharm.com",
                "user_first_name__v": "Bruce",
                "user_last_name__v": "Ashton",
                ...
        },                
        {
            "user": {
                "id": 25503,
                "user_name__v": "tchung@veevapharm.com",
                "user_first_name__v": "Thomas",
                "user_last_name__v": "Chung",
                ...
        },                
        ...

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Retrieve User

Use this request to retrieve the user metadata for a specific user.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

  • {ID} - The system-managed numerical ID assigned to each user. See Retrieve All Users above.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "users": [
        {
            "user": {
                "user_name__v": "ewoodhouse@veevapharm.com",
                "user_first_name__v": "Elaine",
                "user_last_name__v": "Woodhouse",
                "user_email__v": "ewoodhouse@veevapharm.com",
                "user_timezone__v": "America/New_York",
                "user_locale__v": "en_US",
                "user_title__v": "Research Associate",
                "office_phone__v": "5559876543",
                "fax__v": "5556789123",
                "mobile_phone__v": "5551234567",
                "site__v": "Manhattan",
                "is_domain_admin__v": false,
                "active__v": true,
                "domain_active__v": true,
                "security_policy_id__v": 821,
                "user_needs_to_change_password__v": false,
                "id": 25496,
                "created_date__v": "2013-01-08T15:55:27.000Z",
                "created_by__v": 25001,
                "modified_date__v": "2015-02-12T18:22:18.000Z",
                "modified_by__v": 25001,
                "domain_id__v": 3003,
                "vault_id__v": [
                    3003,
                    4004
                ],
                "federated_id__v": "",
                "salesforce_user_name__v": "",
                "last_login__v": "2015-01-20T23:58:02.000Z",
                "medidata_uuid__v": "",
                "user_language__v": "en",
                "company__v": "VeevaPharm",
                "group_id__v": [
                    2555089996,
                    2111844470
                ],
                "security_profile__v": "document_user__v",
                "license_type__v": "full__v",
                "vault_membership": [
                    {
                        "id": 3003,
                        "active__v": true,
                        "security_profile__v": "document_user__v",
                        "license_type__v": "full__v"
                    },
                    {
                        "id": 4004,
                        "active__v": true,
                        "security_profile__v": "document_user__v",
                        "license_type__v": "full__v"
                    }
                ]
            }
        }
    ]
}

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Create User

Use this request to add one new user to your domain or to a vault.

Method & Endpoint

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

Request Headers

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

Input Requirements

When creating new users, the following fields are required in all vaults:

  • user_name__v
  • user_first_name__v
  • user_last_name__v
  • user_email__v
  • user_timezone__v
  • user_locale__v
  • user_language__v
  • security_policy_id__v

Adding User Profile Pictures

Optional - You may add a user profile picture. To do so, include the file parameter in the input with the path/location of the image to be uploaded. For example:

-F "file=images/elaine.jpg" \

Uploaded profile pictures must be JPG, PNG, or GIF files, and less than 10MB in size. Vault automatically resizes images to 64 x 64 pixels, and removes the animations for animated GIFs. Images of approximately square aspect ratio will work best as profile pictures.

Example Request: Add User to Domain

This request will add one new user to your domain. It will not assign them to individual vaults in your domain. See also: Update Vault Membership.

  • This request includes all required fields to create a new user.
  • By including domain=true, the user will not be assigned to a vault.
$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "user_name__v=ewoodhouse@veevapharm.com" \
-F "user_email__v=ewoodhouse@veevapharm.com" \
-F "user_first_name__v=Elaine" \
-F "user_last_name__v=Woodhouse" \
-F "user_language__v=en" \
-F "user_timezone__v=America/Denver" \
-F "user_locale__v=en_US" \
-F "security_policy_id__v=821" \
-F "domain=true" \
https://myvault.veevavault.com/api/v14.0/objects/users

On SUCCESS, the user account will be created and set to active. The new user will not be assigned a license type or security profile, nor will they have access to any vaults in your domain.

Example Request: Add User to Current Vault

This request will add one new user to your domain. It will also assign them to the vault in which the request is made. See also: Update Vault Membership.

  • This request includes all required fields to create a new user.
  • This request includes the security profile and license type fields. This is optional. If not included in the request, this user would be assigned the document_user__v security profile and full__v license type by default.
$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "user_name__v=ewoodhouse@veevapharm.com" \
-F "user_email__v=ewoodhouse@veevapharm.com" \
-F "user_first_name__v=Elaine" \
-F "user_last_name__v=Woodhouse" \
-F "user_language__v=en" \
-F "user_timezone__v=America/Denver" \
-F "user_locale__v=en_US" \
-F "security_policy_id__v=821" \
-F "security_profile__v=business_admin__v" \
-F "license_type__v=full__v" \
https://myvault.veevavault.com/api/v14.0/objects/users

On SUCCESS, the user account will be created and set to active. The new user will be a member of the vault instance in which the request was made and assigned the Business Admin security profile and Full User license type. They will receive a welcome email with instructions for logging into the vault. They will not have access to any other vaults in your domain. To give them access to other vaults, see Update Vault Membership below.

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
As of API v8.0, the domain_active__v field cannot be set when creating a user.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Update User

Use this request to update the user profile information for an existing user in your domain.

Permissions

  • System Admins and Vault Owners can update users in the vaults where they have administrative access.
  • System Admins who are also Domain Admins have an unrestricted access to users across all vaults in the domain.

Method & Endpoint

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

Request Headers

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

Request Parameters

  • {ID} - The system-managed numerical ID assigned to each user. See Retrieve All Users above.

Example Request: Update User Profile Information

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "user_timezone__v=America/Los Angeles" \
-d "company__v=VeevaPharm" \
-d "user_title__v=Product Manager" \
-d "alias__v=Skipper" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001

Example Request: Disable User at Domain-Level

Only Domain Admins may use this request.

This request will set the user (ID: 25001) profile to inactive in all vaults in your domain. The user will still be a member in the vaults and retain their license types and security profiles, but their user profile will be inactive and they will no longer have access to any vaults in your domain.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "domain_active__v=false" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001

Example Request: Re-Enable User at Domain-Level

Only Domain Admins may use this request.

This request will set the (previously inactive) user (ID: 25001) profile to active in your vault domain. However, they will still be inactive in and unable to access your domain vaults. Use the Update Vault Membership request below to set their status to active in the individual vaults in your domain.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "domain_active__v=false" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001

Example Request: Promote a User to Domain Admin

Only Domain Admins may use this request.

This request will promote a user to Domain Admin. To remove a user from the Domain Admin role, set the is_domain_admin__v field to false. Each domain must have at least one user in the Domain Admin role.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "is_domain_admin__v=true" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001

Example Response

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

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Disable User

Use this request to disable a user in a specific vault or disable a user in all vaults in your domain.

Permissions

  • System Admins and Vault Owners can update users in the vaults where they have administrative access.
  • System Admins who are also Domain Admins have an unrestricted access to users across all vaults in the domain.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

  • {ID} - The system-managed numerical ID assigned to each user. See Retrieve All Users above.
  • domain=true [Optional] - To disable the user in all vaults in your domain, add this to the request endpoint.

Example Request: Disable User in a Vault

This request will set the user (ID: 25001) profile to inactive in the vault in which the request is made. The user will still be a member in the vault and retain their license type and security profile, but their user profile will be inactive and they will no longer have access to the vault.

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001

Example Request: Disable User in All Domain Vaults

This request will set the user (ID: 25001) profile to inactive in all vaults in your domain. The user will still be a member in the vaults and retain their license types and security profiles, but their user profile will be inactive and they will no longer have access to any vaults in your domain.

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001?domain=true

Example Response

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

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

Change User Password

Use this request to change the password of an existing user in your vault or domain.

Method & Endpoint

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

Permissions

  • System Admins and Vault Owners can update users in the vaults where they have administrative access.
  • System Admins who are also Domain Admins have an unrestricted access to users across all vaults in the domain.

Request Headers

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

Request Parameters

  • {ID} - The system-managed numerical ID assigned to each user. See Retrieve All Users above.
  • password__v - Enter the current password.
  • new_password__v - Enter the new password.

Note: The new password must meet the minimum password requirements. Learn about Configuring Password Security Policies in Vault Help.

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "password__v=CurrentPassword" \
-d "new_password__v=NewPassword" \
https://myvault.veevavault.com/api/v14.0/objects/users/25496/password

Example Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, the password will be changed and the user will receive an email notification with instructions.

Version History

Available in API v7.0 or later.

Update Vault Membership

Use this request to:

  • Assign an existing user to a vault in your domain.
  • Remove (disable) an existing user from a vault in your domain.
  • Update the security profile and license type of an existing user.

You cannot use this request to:

Additional information:

Permissions

  • System Admins and Vault Owners can update users in the vaults where they have administrative access.
  • System Admins who are also Domain Admins have an unrestricted access to users across all vaults in the domain.

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/users/{ID}/vault_membership/{VAULT_ID} endpoint.

Request Headers

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

Request Parameters

  • {ID} - The system-managed numerical ID assigned to each user. See Retrieve All Users above.
  • {VAULT_ID} - The system-managed numerical ID assigned to each vault in the domain. See Retrieve Domain Vaults above.

Optional Input Values

The following fields and values may be (optionally) submitted with the request:

  • active__v=true - Assigns the user to the vault sets their status to active.
  • active__v=false - Sets the user status to inactive in the vault.
  • security_profile__v={SECURITY_PROFILE} - Assigns the user a specific security profile in the vault.
  • license_type__v={LICENSE_TYPE} - Assigns the user a specific license type in the vault.

See the example requests below for additional information about using these input values.

Example Request: Add User to a Vault

This request will assign the user (ID: 25001) to the vault (ID: 3003). There are a few default settings that will be applied here:

  • The user's status will be set to active in the vault. This is the default setting; the "active__v=true" parameter can omitted and produce the same results.
  • We've not included the optional security_profile__v and license_type__v in the input. Therefore, the user will be assigned a full__v license type and document_user__v security profile by default.
$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "active__v=true" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001/vault_membership/3003

Example Request: Disable User in a Vault

This request will set the user (ID: 25001) profile to inactive in the vault (ID: 3003). They will still be a member in the vault and retain their license type and security profile, but their user profile will be inactive and they will no longer have access to the vault.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "active__v=false" \
https://myvault.veevavault.com/api/v14.0/objects/users/25001/vault_membership/3003

Example Request: Set Security Profile & License Type

This request will set the user (ID: 25001) security profile and license type to specific values in the vault (ID: 3003). If the user is already a member of the vault, this will change their security profile and license type. If the user is not a member of the vault, this will assign them to the vault, set their status to active, and their security profile and license type to the specified values.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "security_profile__v=business_admin__v" \
-d "license_type__v=full__v"
https://myvault.veevavault.com/api/v14.0/objects/users/25001/vault_membership/3003

Version History

Available in API v2.0 or later.
Domain-level user management is available in API v7.0 or later. Learn more.
The security_profile__v and license_type__v fields are available in API v10.0 or later.

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:

Field Description
id Group ID
name__v Group name
label__v Group label
group_description__v Group description
members__v List of user IDs of users who are members of this group
implied_members__v List of user IDs of users who were added to the group through a security profile assignment.
security_profiles__v List of security profiles assigned to the group.
active__v Indicates if this group is active
system_group__v Indicates if this group is a system managed group
created_date__v Timestamp when the group was created
created_by__v User ID of the user who created the group
modified_date__v Timestamp when the group was last modified
modified_by__v User ID of the user who last modified the group

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:

Field Description
name Name of the property
type Data type of property (id,ObjectReference, String, Calendar, Boolean)
object The object type when type is set to ObjectReference
multivalue Indicates if the property is multi-valued
queryable Indicates if the property is exposed in query
length Maximum number of characters for the property value
required Indicates if the property is required
onCreateEditable Indicates if the property can only be set on group creation
editable Indicates if the property is editable

Example:

{
    "responseStatus": "SUCCESS",
    "properties": [
        {
            "name": "id",
            "type": "id",
            "length": 20,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "label__v",
            "type": "String",
            "length": 255,
            "editable": true,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": true
        },
        {
            "name": "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": "implied_members__v",
            "type": "ObjectReference",
            "length": 20,
            "object": "users",
            "editable": false,
            "queryable": false,
            "required": false,
            "multivalue": true,
            "onCreateEditable": false
        },
        {
            "name": "security_profiles__v",
            "type": "ObjectReference",
            "length": 40,
            "object": "Securityprofile",
            "editable": true,
            "queryable": false,
            "required": false,
            "multivalue": true,
            "onCreateEditable": true
        },
        {
            "name": "active__v",
            "type": "Boolean",
            "length": 1,
            "editable": true,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        },
        {
            "name": "name__v",
            "type": "String",
            "length": 40,
            "editable": false,
            "queryable": true,
            "required": true,
            "multivalue": false,
            "onCreateEditable": false
        }
    ]
}

Errors

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

Version History

Since: v1.0 Since: v11.0 security_profile__v and implied_members__v added to group metadata.

Create Group

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

For example:

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-d "label__v=Clinical Reviewers&members__v=25515,26180" \
https://{CUSTOMER}.veevavault.com/api/{version}/objects/groups

Request Parameters

Refer to the output of the "Retrieve Group Metadata" API for request parameters. Only those properties that are marked as "onCreateEditable": true are valid for group creation, only those that are marked as "required": true must be set.

Response

On success, Vault returns the ID of the newly created group

Example:

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Group successfully created.",
  "id": 1367526751338
}

Errors

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

Version History

Since: v1.0
v10.0: The groups object field includes name__v. The groups object field group_name__v is now label__v.

Retrieve Groups

You can retrieve a collection of all groups by sending a GET request to the /api/{version}/objects/groups endpoint.

For example:

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

Response

On success, Vault returns the list of groups and their properties.

Example:

{
    "responseStatus": "SUCCESS",
    "groups": [
        {
            "group": {
                "id": 1,
                "active__v": true,
                "members__v": [
                    25496,
                    25516,
                    25517,
                    25518,
                    25520,
                    46916
                ],
                "created_by__v": 1,
                "group_description__v": "All Internal Vault Users (System managed group)",
                "modified_date__v": "2014-11-12T23:42:01.000Z",
                "modified_by__v": 46916,
                "security_profiles__v": [
                    "business_admin__v",
                    "document_user__v",
                    "system_admin__v",
                    "vault_owner__v"
                ],
                "name__v": "all_internal_users__v",
                "label__v": "All Internal Users",
                "system_group__v": true,
                "created_date__v": "2013-01-08T16:33:50.000Z"
            }
        },
        {
            "group": {
                "id": 4,
                "active__v": true,
                "members__v": [
                    25516,
                    25527
                ],
                "created_by__v": 1,
                "group_description__v": "All Business Administrators (System managed group)",
                "modified_date__v": "2013-01-23T22:07:53.000Z",
                "modified_by__v": 25496,
                "security_profiles__v": [
                    "business_admin__v"
                ],
                "name__v": "business_administrators__v",
                "label__v": "Business Administrators",
                "system_group__v": true,
                "created_date__v": "2013-01-08T16:33:50.000Z"
            }
        },
        {
            "group": {
                "id": 6,
                "active__v": true,
                "members__v": [
                    25496,
                    25524,
                    46916
                ],
                "created_by__v": 1,
                "group_description__v": "All Vault Owners (System managed group)",
                "modified_date__v": "2014-11-12T22:33:14.000Z",
                "modified_by__v": 46916,
                "security_profiles__v": [
                    "vault_owner__v"
                ],
                "name__v": "vault_owners__v",
                "label__v": "Vault Owners",
                "system_group__v": true,
                "created_date__v": "2013-01-08T16:33:50.000Z"
            }
        }
    ]
}

Errors

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

Version History

Since: v1.0 Since: v11.0 security_profile__v and implied_members__v added to group metadata.

Retrieve Group

You can retrieve the specified group and its properties by sending the GET request to the /api/{version}/objects/groups/{id} endpoint.

For example:

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

Response

On success, Vault returns the properties of the specified group.

Example:

{
    "responseStatus": "SUCCESS",
    "groups": [
        {
            "group": {
                "id": 6,
                "active__v": true,
                "members__v": [
                    25496,
                    25524,
                    46916
                ],
                "created_by__v": 1,
                "group_description__v": "All Vault Owners (System managed group)",
                "modified_date__v": "2014-11-12T22:33:14.000Z",
                "modified_by__v": 46916,
                "security_profiles__v": [
                    "vault_owner__v"
                ],
                "name__v": "vault_owners__v",
                "label__v": "Vault Owners",
                "system_group__v": true,
                "created_date__v": "2013-01-08T16:33:50.000Z"
            }
        }
    ]
}

Errors

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

Version History

Since: v1.0 Since: v11.0 security_profile__v and implied_members__v added to group metadata.

Update Group

You can update the properties of the specified group by sending a PUT request to the /api/{version}/objects/groups/{id} endpoint.

For example:

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-d "label__v=Reviewers" \
https://{CUSTOMER}.veevavault.com/api/{version}/objects/groups/{id}

Request Parameters

Refer to the output of the "Retrieve Group Metadata" API for the request parameters. Only properties marked as "editable=true are valid for the group update.

Response

On success, Vault returns the ID of the updated group.

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Group successfully updated.",
  "id": 27
}

Errors

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

Version History

Since: v1.0
v10.0: The groups object field includes name__v. The groups object field group_name__v is now label__v.

Delete Group

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

For example:

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

Response

On success, Vault returns the ID of the deleted group

Errors

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

Version History

Since: v3.0

Vault Objects

This API provides access to Vault Objects and the object data records.

NOTE: The Vault Objects API replaces the deprecated Catalogs API in Vault v8.

Object Metadata

The object consists of the following metadata:

Field Description
- name Unique object identifier
- label UI-friendly object label
- label_plural Plural version of the UI-friendly object label
- prefix Prefix used in object record IDs
- description Description of the object
- created_by ID of the user who created the object
- created_date Object creation timestamp in UTC format
- modified_by ID of the user who last modified the object
- modified_date Object last modified timestamp in UTC format
- status Status of the object: active__v, inactive__v
- urls Hypermedia URLs to use to access details of the object and object records
------ field URL to use to access and manage object field(s)
------ record URL to use to access and manage a single object record(s)
------ list URL to use to access the collection of object records
------ metadata URL to use to access the object metadata
- source Source of object creation: standard, sample, custom
- in_menu Whether the object is listed in Vault menu
- order Order in which the object is listed
- auditable Whether the audit events are created when object records are manupulated
- help_content Short help message describing the object
- allow_attachments Whether file attachments are enabled for this object
- role_overrides Whether the security overrides are enabled on the object record
- relationships Relationships defined by this object (only returned if relationships defined)
------ field Name of the field in the related object that holds the reference
------ object Name of the related object
------------ url URL to use to access the object metadata
------------ name Unique object identifier
------------ prefix Prefix used in object record IDs
------------ label UI-friendly object label
------------ label_plural Plural version of the UI-friendly object label
------ relationship_type Type of the relationship: child,reference_inbound
------ relationship_label Plural version of the UI-friendly related object label
------ relationship_name Relationship name
------ relationship_deletion Relationship deletion strategy
- fields Fields defined by this object
------ name Unique field identifier
------ label UI-friendly field label
------ type Type of data that can be stored by the field
------ created_by ID of the user who created the field
------ created_date Field creation timestamp in UTC format
------ modified_by ID of the user who last modified the field
------ modified_date Field last modified timestamp in UTC format
------ status Status of the field: active__v, inactive__v
------ object Summary of the related object details (only returned if field type is Object)
------------ url URL to use to access the object metadata
------------ name Unique object identifier
------------ prefix Prefix used in object record IDs
------------ label UI-friendly object label
------------ label_plural Plural version of the UI-friendly object label
------ source Source of field creation: standard, sample, custom
------ list_column Whether the field is listed in Vault UI tables
------ order Order in which the field is listed in the Vault UI forms
------ editable Whether it is allowed to update the data in the object record
------ help_content Short help message describing the field
------ picklist For field of type Picklist, the name of the Picklist containing the possible values
------ unique Whether the record value stored in this field is unique
------ required Whether it is required to provide the data in the object record
------ min_value Minimum float value that can be set into the field (max of 9 decimal places)
------ max_value Maximum float value that can be set into the field (max of 9 decimal places)
------ max_length Maximum length of the String (for String fields)
------ multi_value For fields of type Picklist, whether multiple values can be selected for field in the object record
------ relationship_type Relationship type specified by the field: parent, reference (only returned if field type is Object)
------ relationship_inbound_name Inbound relationship name
------ relationship_inbound_label Inbound relationship label
------ relationship_outbound_name Outbound relationship name
------ relationship_deletion Relationship deletion strategy

Retrieve Object Collection

You can retrieve the collection of objects by sending a GET request to the /api/{VERSION}/metadata/vobjects endpoint. For example:

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

The response body is a collection containing summaries of all objects exposed by the VOF. Each summary in the collection consists of:

Field Description
- url Hypermedia URLs to use to access details of the object and object records
- name Unique object identifier
- label UI-friendly object label
- label_plural Plural version of the UI-friendly object label
- prefix Prefix used in object record IDs
- status Status of the object: active__v, inactive__v
- source Source of object creation: standard, sample, custom
- in_menu Whether the object is listed in Vault menu
- order Order in which the object is listed
- allow_attachments Whether file attachments are enabled for this object

For example:

{
    "responseStatus": "SUCCESS",
    "objects": [
        {
            "url": "/api/v11.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            "prefix": "00P",
            "order": 2,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Products",
            "in_menu": true,
            "allow_attachments": false
        },
        {
            "url": "/api/v11.0/metadata/vobjects/country__v",
            "label": "Country",
            "name": "country__v",
            "prefix": "00C",
            "order": 4,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Countries",
            "in_menu": true,
            "allow_attachments": false
        },
        {
            "url": "/api/v11.0/metadata/vobjects/study__v",
            "label": "Study",
            "name": "study__v",
            "prefix": "0ST",
            "order": 1,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Studies",
            "in_menu": true,
            "allow_attachments": true
        },
        {
            "url": "/api/v11.0/metadata/vobjects/location__v",
            "label": "Location",
            "name": "location__v",
            "prefix": "00L",
            "order": 3,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Locations",
            "in_menu": true,
            "allow_attachments": false
        },
        {
            "url": "/api/v11.0/metadata/vobjects/site__v",
            "label": "Study Site",
            "name": "site__v",
            "prefix": "0SI",
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Study Sites",
            "in_menu": true,
            "allow_attachments": true
        },
        {
            "url": "/api/v11.0/metadata/vobjects/study_country__v",
            "label": "Study Country",
            "name": "study_country__v",
            "prefix": "0SC",
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Study Countries",
            "in_menu": false,
            "allow_attachments": false
        },
        {
            "url": "/api/v11.0/metadata/vobjects/milestone__v",
            "label": "Milestone",
            "name": "milestone__v",
            "prefix": "0MI",
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Milestones",
            "in_menu": true,
            "allow_attachments": false
        }
    ]
}

Localized Data

You can retrieve the localized strings for the following metadata fields: label, label_plural. To request the localized data include the loc query string parameter set to true on the endpoint URL. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{VERSION}/metadata/vobjects?loc=true

When the localized data is requested, the response will contain additional field localized_data containing the the map with localized strings for each of the localized fields. This data is available only if localized string are configured.

{
    "responseStatus": "SUCCESS",
    "objects": [
        {
            "url": "/api/v11.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            "prefix": "00P",
            "order": 2,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Products",
            "in_menu": true,
            "allow_attachments": false,
            "localized_data": {
                "label_plural": {
                    "de": "Produkte",
                    "pt_PT": "Produtos",
                    "zh": "产品",
                    "it": "Prodotti",
                    "pt_BR": "Produtos",
                    "fr": "Produits",
                    "en": "Products",
                    "ru": "Продукты",
                    "es": "Productos",
                    "ja": "製品"
                },
                "label": {
                    "de": "Produkt",
                    "pt_PT": "Produto",
                    "zh": "产品",
                    "it": "Prodotto",
                    "pt_BR": "Produto",
                    "fr": "Produit",
                    "en": "Product",
                    "ru": "Продукт",
                    "es": "Producto",
                    "ja": "製品"
                }
            }
        },

Retrieve Object

You can retrieve the object metadata by sending the GET request to the /api/{VERSION}/metadata/vobjects/{NAME} endpoint. For example:

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

The response body consists of the detailed metadata.

For example:

{
    "responseStatus": "SUCCESS",
    "object": {
        "created_date": "2014-02-03T20:12:19.000Z",
        "created_by": 1,
        "allow_attachments": false,
        "auditable": true,
        "modified_date": "2014-02-03T20:12:19.000Z",
        "status": [
            "active__v"
        ],
        "urls": {
            "field": "/api/v11.0/metadata/vobjects/study__v/fields/{name}",
            "record": "/api/v11.0/vobjects/study__v/{id}",
            "list": "/api/v11.0/vobjects/study__v",
            "metadata": "/api/v11.0/metadata/vobjects/study__v"
        },
        "label_plural": "Studies",
        "role_overrides": false,
        "label": "Study",
        "in_menu": true,
        "help_content": null,
        "source": "standard",
        "order": 1,
        "modified_by": 1,
        "description": null,
        "name": "study__v",
        "prefix": "0ST",
        "relationships": [
            {
                "field": "study_number__v",
                "relationship_deletion": "block",
                "object": {
                    "url": "/api/v11.0/metadata/vobjects/study_country__v",
                    "label": "Study Country",
                    "name": "study_country__v",
                    "prefix": "0SC",
                    "label_plural": "Study Countries"
                },
                "relationship_label": "Study Countries",
                "relationship_type": "child",
                "relationship_name": "study_countries__vr"
            },
            {
                "field": "study_number__v",
                "relationship_deletion": "block",
                "object": {
                    "url": "/api/v11.0/metadata/vobjects/site__v",
                    "label": "Study Site",
                    "name": "site__v",
                    "prefix": "0SI",
                    "label_plural": "Study Sites"
                },
                "relationship_label": "Sites",
                "relationship_type": "reference_inbound",
                "relationship_name": "sites__vr"
            },
            {
                "field": "study__v",
                "relationship_deletion": "block",
                "object": {
                    "url": "/api/v11.0/metadata/vobjects/milestone__v",
                    "label": "Milestone",
                    "name": "milestone__v",
                    "prefix": "0MI",
                    "label_plural": "Milestones"
                },
                "relationship_label": "Milestones",
                "relationship_type": "reference_inbound",
                "relationship_name": "milestones__vr"
            },
            {
                "field": "product__v",
                "relationship_deletion": "block",
                "object": {
                    "url": "/api/v11.0/metadata/vobjects/product__v",
                    "label": "Product",
                    "name": "product__v",
                    "prefix": "00P",
                    "label_plural": "Products"
                },
                "relationship_label": "Product",
                "relationship_type": "reference_outbound",
                "relationship_name": "product__vr"
            }
        ],
        "fields": [
            {
                "created_by": 1,
                "created_date": "2014-02-03T20:12:20.000Z",
                "list_column": false,
                "modified_date": "2014-02-03T20:12:20.000Z",
                "status": [
                    "active__v"
                ],
                "label": "ID",
                "type": "ID",
                "editable": false,
                "help_content": null,
                "order": 0,
                "source": "standard",
                "modified_by": 1,
                "name": "id",
                "required": false
            },
            {
                "created_date": "2014-02-03T20:12:20.000Z",
                "created_by": 1,
                "max_length": 128,
                "list_column": true,
                "unique": true,
                "modified_date": "2014-02-03T20:12:20.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Study Number",
                "type": "String",
                "editable": true,
                "help_content": null,
                "order": 1,
                "source": "standard",
                "modified_by": 1,
                "name": "name__v",
                "required": true
            },
            {
                "created_date": "2014-02-03T20:12:20.000Z",
                "created_by": 1,
                "list_column": false,
                "modified_date": "2014-02-03T20:12:20.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Status",
                "type": "Picklist",
                "editable": true,
                "help_content": null,
                "order": 2,
                "source": "standard",
                "modified_by": 1,
                "name": "status__v",
                "multi_value": false,
                "required": true,
                "picklist": "study_record_status__v"
            },
            {
                "created_date": "2014-02-03T20:12:20.000Z",
                "created_by": 1,
                "max_length": 60,
                "list_column": false,
                "unique": false,
                "modified_date": "2014-02-03T20:12:20.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Alternate Study Number",
                "type": "String",
                "editable": true,
                "help_content": null,
                "order": 3,
                "source": "sample",
                "modified_by": 1,
                "name": "alternate_study_number__vs",
                "required": false
            },
            {
                "created_date": "2014-02-03T20:12:20.000Z",
                "created_by": 1,
                "relationship_deletion": "block",
                "list_column": true,
                "modified_date": "2014-04-29T02:06:36.000Z",
                "status": [
                    "active__v"
                ],
                "relationship_outbound_name": "product__vr",
                "label": "Product",
                "object": {
                    "url": "/api/v11.0/metadata/vobjects/product__v",
                    "label": "Product",
                    "name": "product__v",
                    "prefix": "00P",
                    "label_plural": "Products"
                },
                "type": "Object",
                "editable": true,
                "relationship_inbound_name": "studies__vr",
                "help_content": null,
                "source": "standard",
                "order": 4,
                "modified_by": 1,
                "name": "product__v",
                "relationship_inbound_label": "Studies",
                "required": false,
                "relationship_type": "reference"
            },
            {
                "created_date": "2014-02-03T20:12:20.000Z",
                "created_by": 1,
                "max_length": 500,
                "list_column": false,
                "unique": false,
                "modified_date": "2014-02-03T20:12:20.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Study Name",
                "type": "String",
                "editable": true,
                "help_content": null,
                "order": 5,
                "source": "sample",
                "modified_by": 1,
                "name": "study_name__vs",
                "required": false
            },
            {
                "created_date": "2014-02-03T20:12:20.000Z",
                "created_by": 1,
                "list_column": false,
                "modified_date": "2014-02-03T20:12:20.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Indication",
                "type": "Picklist",
                "editable": true,
                "help_content": null,
                "order": 6,
                "source": "standard",
                "modified_by": 1,
                "name": "indication__v",
                "multi_value": false,
                "required": false,
                "picklist": "indication__vs"
            },
            {
                "created_date": "2014-02-03T20:12:20.000Z",
                "created_by": 1,
                "list_column": false,
                "modified_date": "2014-02-03T20:12:20.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Route of Administration",
                "type": "Picklist",
                "editable": true,
                "help_content": null,
                "order": 7,
                "source": "sample",
                "modified_by": 1,
                "name": "route_of_administration__vs",
                "multi_value": false,
                "required": true,
                "picklist": "route_of_administration__vs"
            },
            {
                "created_date": "2014-02-03T20:12:21.000Z",
                "created_by": 1,
                "list_column": true,
                "modified_date": "2014-02-03T20:12:21.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Study Phase",
                "type": "Picklist",
                "editable": true,
                "help_content": null,
                "order": 8,
                "source": "standard",
                "modified_by": 1,
                "name": "study_phase__v",
                "multi_value": false,
                "required": true,
                "picklist": "study_phase__vs"
            },
            {
                "created_date": "2014-02-03T20:12:21.000Z",
                "created_by": 1,
                "list_column": true,
                "modified_date": "2014-02-03T20:12:21.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Study Type",
                "type": "Picklist",
                "editable": true,
                "help_content": null,
                "order": 9,
                "source": "standard",
                "modified_by": 1,
                "name": "study_type__v",
                "multi_value": false,
                "required": true,
                "picklist": "study_type__vs"
            },
            {
                "created_date": "2014-02-03T20:12:21.000Z",
                "created_by": 1,
                "list_column": false,
                "modified_date": "2014-02-03T20:12:21.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Control",
                "type": "Picklist",
                "editable": true,
                "help_content": null,
                "order": 10,
                "source": "standard",
                "modified_by": 1,
                "name": "control__v",
                "multi_value": false,
                "required": true,
                "picklist": "control__vs"
            },
            {
                "created_date": "2014-02-03T20:12:21.000Z",
                "created_by": 1,
                "list_column": false,
                "modified_date": "2014-02-03T20:12:21.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Masking",
                "type": "Picklist",
                "editable": true,
                "help_content": null,
                "order": 11,
                "source": "sample",
                "modified_by": 1,
                "name": "masking__vs",
                "multi_value": false,
                "required": false,
                "picklist": "masking__vs"
            },
            {
                "created_date": "2014-02-03T20:12:21.000Z",
                "created_by": 1,
                "scale": 0,
                "list_column": false,
                "modified_date": "2014-02-03T20:12:21.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Enrollment",
                "type": "Number",
                "editable": true,
                "help_content": null,
                "source": "sample",
                "order": 12,
                "modified_by": 1,
                "name": "enrollment__vs",
                "max_value": 100000,
                "required": false,
                "min_value": 0
            },
            {
                "created_by": 1,
                "created_date": "2014-02-03T20:12:21.000Z",
                "list_column": false,
                "modified_date": "2014-02-03T20:12:21.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Study Start Date",
                "type": "Date",
                "editable": true,
                "help_content": null,
                "order": 13,
                "source": "sample",
                "modified_by": 1,
                "name": "study_start_date__vs",
                "required": false
            },
            {
                "created_by": 1,
                "created_date": "2014-02-03T20:12:22.000Z",
                "list_column": false,
                "modified_date": "2014-02-03T20:12:22.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Planned Study End Date",
                "type": "Date",
                "editable": true,
                "help_content": null,
                "order": 14,
                "source": "sample",
                "modified_by": 1,
                "name": "planned_study_end_date__vs",
                "required": false
            },
            {
                "created_date": "2014-02-03T20:12:22.000Z",
                "created_by": 1,
                "list_column": false,
                "modified_date": "2014-02-03T20:12:22.000Z",
                "status": [
                    "active__v"
                ],
                "label": "CRO",
                "type": "Picklist",
                "editable": true,
                "help_content": null,
                "order": 15,
                "source": "sample",
                "modified_by": 1,
                "name": "cro__vs",
                "multi_value": false,
                "required": false,
                "picklist": "cro__vs"
            },
            {
                "created_date": "2014-02-03T20:12:22.000Z",
                "created_by": 1,
                "list_column": true,
                "modified_date": "2014-02-03T20:12:22.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Study Status",
                "type": "Picklist",
                "editable": true,
                "help_content": null,
                "order": 16,
                "source": "standard",
                "modified_by": 1,
                "name": "study_status__v",
                "multi_value": false,
                "required": true,
                "picklist": "study_status__vs"
            },
            {
                "created_date": "2014-02-03T20:12:22.000Z",
                "created_by": 1,
                "max_length": 50,
                "list_column": false,
                "unique": true,
                "modified_date": "2014-02-03T20:12:22.000Z",
                "status": [
                    "active__v"
                ],
                "label": "External ID",
                "type": "String",
                "editable": true,
                "help_content": null,
                "order": 17,
                "source": "standard",
                "modified_by": 1,
                "name": "external_id__v",
                "required": false
            },
            {
                "created_date": "2014-02-03T20:12:23.000Z",
                "created_by": 1,
                "list_column": false,
                "modified_date": "2014-02-03T20:12:23.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Created By",
                "object": {
                    "name": "users"
                },
                "type": "Object",
                "editable": false,
                "help_content": null,
                "order": 18,
                "source": "standard",
                "modified_by": 1,
                "name": "created_by__v",
                "required": false,
                "relationship_type": "reference"
            },
            {
                "created_by": 1,
                "created_date": "2014-02-03T20:12:23.000Z",
                "list_column": false,
                "modified_date": "2014-02-03T20:12:23.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Created Date",
                "type": "DateTime",
                "editable": false,
                "help_content": null,
                "order": 19,
                "source": "standard",
                "modified_by": 1,
                "name": "created_date__v",
                "required": false
            },
            {
                "created_date": "2014-02-03T20:12:23.000Z",
                "created_by": 1,
                "list_column": false,
                "modified_date": "2014-02-03T20:12:23.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Last Modified By",
                "object": {
                    "name": "users"
                },
                "type": "Object",
                "editable": false,
                "help_content": null,
                "order": 20,
                "source": "standard",
                "modified_by": 1,
                "name": "modified_by__v",
                "required": false,
                "relationship_type": "reference"
            },
            {
                "created_by": 1,
                "created_date": "2014-02-03T20:12:23.000Z",
                "list_column": false,
                "modified_date": "2014-02-03T20:12:23.000Z",
                "status": [
                    "active__v"
                ],
                "label": "Last Modified Date",
                "type": "DateTime",
                "editable": false,
                "help_content": null,
                "order": 21,
                "source": "standard",
                "modified_by": 1,
                "name": "modified_date__v",
                "required": false
            }
        ]
    }
}

Localized Data

You can retrieve the localized strings for the following metadata fields: label, label_plural and help_content. To request the localized data include the loc query string parameter set to true on the endpoint URL. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{VERSION}/metadata/vobjects/{NAME}?loc=true

When the localized data is requested, the response will contain additional field localized_data containing the the map with localized strings for each of the localized fields. This data is Available at the object and/or the field level, and only if localized string are configured.

{
    "responseStatus": "SUCCESS",
    "object": {
        "created_date": "2014-02-03T20:12:16.000Z",
        "created_by": 1,
        "allow_attachments": false,
        "localized_data": {
            "label_plural": {
                "de": "Länder",
                "pt_PT": "Países",
                "zh": "国家/地区",
                "it": "Paesi",
                "pt_BR": "Países",
                "fr": "Pays",
                "en": "Countries",
                "ru": "Страны",
                "es": "Países",
                "ja": "国"
            },
            "label": {
                "de": "Land",
                "pt_PT": "País",
                "zh": "国家/地区",
                "it": "Paese",
                "pt_BR": "País",
                "fr": "Pays",
                "en": "Country",
                "ru": "Страна",
                "es": "País",
                "ja": "国"
            }
        },

Errors

On failure, the response will contain an error response.

Type Message Condition
MALFORMED_URL The resource [RESOURCE] does not exist User is requesting a non-existent resource
METHOD_NOT_SUPPORTED Request method [METHOD] not supported User is requesting a resource with an unsupported HTTP method

Object Field Metadata

The object field consist of the following metadata:

Field Field Type Field Description
- name System Managed Unique field identifier
- label System Managed UI-friendly field label
- type Required Enum Type of data that can be stored by the field: ID String Number Boolean Picklist Object Date DateTime
- created_by System Managed ID of the user who created the field
- created_date System Managed Field creation timestamp in UTC format
- modified_by System Managed ID of the user who last modified the field
- modified_date System Managed Field last modified timestamp in UTC format
- status Optional Picklist Status of the field: active__v, inactive__v. Default: active__v
- object System Managed Summary of the related object details (only returned if field type is Object)
------ url System Managed URL to use to access the object metadata
------ name System Managed Unique object identifier
------ prefix System Managed Prefix used in object record IDs
------ label System Managed UI-friendly object label
------ label_plural System Managed Plural version of the UI-friendly object label
- source System Managed Source of field creation: standard, sample, custom
- list_column Optional Boolean Whether the field is listed in Vault UI tables. Default: false
- order Optional Number Order in which the field is listed in the Vault UI forms. Default: Insert in last position
- editable Optional Boolean Whether it is allowed to update the data in the object record. Default: true
- help_content Optional String Short help message describing the field. 255 character max
- picklist System Managed For field of type Picklist, the name of the Picklist containing the possible values.
- unique Optional Boolean Whether the record value stored in this field is unique. Default: false
- required Optional Boolean Whether it is required to provide the data in the object record. Default: false
- min_value Required Number Minimum float value that can be set into the field (max of 9 decimal places). Data type: Number
- max_value Required Number Maximum float value that can be set into the field (max of 9 decimal places). Data type: Number
- max_length Required Number Maximum length of the String (for String fields). Default: 20, Max: 1500. Data type: String
- multi_value Optional Boolean For fields of type Picklist, whether multiple values can be selected for field in the object record. Default: false
- relationship_type System Managed Relationship type specified by the field: parent, child, reference. Only returned if field type is Object
- relationship_inbound_name System Managed Inbound relationship name
- relationship_inbound_label System Managed Inbound relationship label
- relationship_outbound_name System Managed Outbound relationship name
- relationship_deletion System Managed Relationship deletion strategy

Retrieve Object Field

You can retrieve the object field metadata by sending the GET request to the /api/{VERSION}/metadata/vobjects/{NAME}/fields/{FIELD} endpoint.

For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{VERSION}/metadata/vobjects/{NAME}/fields/{FIELD}

Response

The response contains the metadata for a specified object field.

{
    "responseStatus": "SUCCESS",
    "field": {
        "created_date": "2014-04-25T01:13:03.000Z",
        "created_by": 1,
        "relationship_deletion": "block",
        "list_column": false,
        "modified_date": "2014-04-25T01:13:03.000Z",
        "status": [
            "active__v"
        ],
        "relationship_outbound_name": "study_number__vr",
        "label": "Study Number",
        "object": {
            "url": "/api/v10.0/metadata/vobjects/study__v",
            "label": "Study",
            "name": "study__v",
            "prefix": "0ST",
            "label_plural": "Studies"
        },
        "type": "Object",
        "editable": true,
        "relationship_inbound_name": "sites__vr",
        "help_content": null,
        "source": "standard",
        "order": 0,
        "modified_by": 1,
        "name": "study_number__v",
        "relationship_inbound_label": "Sites",
        "required": true,
        "relationship_type": "parent"
    }
}

Localized Data

You can retrieve the localized strings for the following metadata fields: label, label_plural and help_content. To request the localized data include the loc query string parameter set to true on the endpoint URL.

For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{VERSION}/metadata/vobjects/{NAME}/fields/{FIELD}?loc=true

Example response with localize data:

{
    "responseStatus": "SUCCESS",
    "field": {
        "created_date": "2013-12-30T21:05:15.000Z",
        "created_by": 25507,
        "max_length": 20,
        "list_column": false,
        "localized_data": {
            "label": {
                "de": "Produkt",
                "zh": "产品",
                "it": "Prodotto",
                "fr": "Produit",
                "en": "Product",
                "ru": "Продукт",
                "ja": "製品"
            }
        },
        "unique": false,
        "modified_date": "2013-12-30T21:05:15.000Z",
        "status": [
            "active__v"
        ],
        "label": "Product",
        "type": "String",
        "editable": true,
        "help_content": null,
        "order": 13,
        "source": "custom",
        "modified_by": 25507,
        "name": "product1__c",
        "required": false
    }
}

Object Records

The Object Records API allows you to create, retrieve, update and delete one or more object records at a time.

Retrieve Object Record Collection

You can retrieve a collection of records of specific type by sending the GET request to the /api/{VERSION}/vobjects/{NAME} endpoint.

For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}/api/{VERSION}/vobjects/{NAME}

Limits & Pagination

You may limit the number of records returned in the collection by specifying an alternative limit value. A maximum of 200 object records is returned per call by default. To override this limit, limit query string parameter can be set to the alternative limit. Limits over 200 are ignored and reset back to 200.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{VERSION}/vobjects/{NAME}?limit=100


To paginate over the collection of results, offset query string parameter is used. offset values equaling to a number larger than the total number of records in the collection will not return any records in the collection.

limit and offset must be positive integers

To facilitate implementing the pagination over the collection of records, the result contains previous_page and next_page fields in the resultDetails of the response. These fiels are included only when there are previous or next pages of the result set.

Examples

To limit the number of records in the collection to 20 starting with the 20th record of the total result set:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com.veevavault.com/api/{VERSION}/vobjects/{NAME}?limit=20&offset=20

To start the collection of records from the 200th record of the total result set. By default 200 records will be returned since alternate limit is not specified:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com.veevavault.com/api/{VERSION}/vobjects/{NAME}?offset=200

Fields

You may request particular fields to be returned for each object record. For this, fields query string parameter can be set to a comma-delimited list of object field names.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{VERSION}/vobjects/{NAME}?fields={FIELD},{FIELD}

If the fields parameter is present on the query string but contains no value, it's presence is ignored and only the default set of fields is returned.

If the fields parameter contains an invalid field (or set of fields), an INVALID_DATA error is returned.

Sorting

You may request the collection of results to be sorted. For this, sort query string parameter can be set to the field name by which the collection of results shall be sorted. Sorting requires the sort direction to be specifed: asc for ascending (default), desc for descending.

Example

To sort the collection of results by name__v in ascending order:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://{CUSTOMER}.veevavault.com/api/{VERSION}/vobjects/{NAME}?sort=name__v asc

Response

The response will contain a collection of object record summaries.

Example Response:

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 4,
        "limit": 200,
        "object": {
            "url": "/api/v11.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            "prefix": "00P",
            "order": 2,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Products",
            "in_menu": true,
            "allow_attachments": false
        },
        "offset": 0,
        "url": "/api/v11.0/vobjects/product__v"
    },
    "data": [
        {
            "id": "1357663087386",
            "name__v": "CholeCap"
        },
        {
            "id": "1357663087433",
            "name__v": "VeevaProm"
        },
        {
            "id": "1357663087491",
            "name__v": "VeevaProm XR"
        },
        {
            "id": "1357663087538",
            "name__v": "WonderDrug"
        }
    ]
}

Errors

On failure, the response will contain an error response.

Type Message Condition
INVALID_DATA Invalid sort field [{field}] Attempting to sort by an invalid/non-existent field
INVALID_DATA Invalid value [{value}[,{value}]] specified for parameter [fields] Attempting to provide a list of fields on the query string but one or more fields are invalid
MALFORMED_URL The resource [{NAME}] does not exist Attempting to request a non-existent object record collection
METHOD_NOT_SUPPORTED Request method '{METHOD}' not supported Attempting to request a resource with an unsupported HTTP Method

Retrieve Object Record

You can retrieve a specific object record by sending the GET request to the /api/{VERSION}/vobjects/{NAME}/{ID} endpoint.

For example:

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

Response

The response contains a complete set of object fields as defined by the object's metadata.

Example Response:

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "object": {
            "url": "/api/v11.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            "prefix": "00P",
            "label_plural": "Products"
        },
        "url": "/api/v11.0/vobjects/product__v/1357663087386"
    },
    "data": {
        "external_id__v": null,
        "internal_name__vs": null,
        "therapeutic_area__vs": null,
        "abbreviation__vs": "CC",
        "created_date__v": "2013-01-08T16:38:07.000Z",
        "id": "1357663087386",
        "inn__vs": null,
        "status__v": [
            "active__v"
        ],
        "created_by__v": 1,
        "modified_date__v": "2013-01-08T16:38:07.000Z",
        "modified_by__v": 1,
        "compound_id__vs": null,
        "product_family__vs": null,
        "name__v": "CholeCap",
        "generic_name__vs": null
    }
}

Errors

On failure, the response will contain an error response.

Type Message Condition
MALFORMED_URL The resource [{NAME}] does not exist Attempting to request a non-existent object record
METHOD_NOT_SUPPORTED Request method {METHOD} not supported Attempting to request a resource with an unsupported HTTP Method


Create Object Record

See Bulk Object Records API.


Update Object Record

See Bulk Object Records API.


Delete Object Record

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

  • {NAME} - The name__v field value of the object.
  • {ID} - The id field value of the object record to be deleted.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS"
}

Possible Errors

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

Version History

Available in API v8.0 or later.


Bulk Object Records API

Bulk Object Records API Method API Endpoint Input Output Batch Size Available in API
Create Object Records POST /api/{VERSION}/vobjects/{NAME} CSV, JSON CSV, JSON 1-500 v8.0 or later
Update Object Records PUT /api/{VERSION}/vobjects/{NAME} CSV, JSON CSV, JSON 1-500 v8.0 or later

Create Object Records in Bulk

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

Available in API v8.0 or later.

Update Object Records in Bulk

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

Available in API v8.0 or later.


Picklists

The Picklists API allows you to manage the values that appear in your vault's picklist fields. The API does not support creating or updating the picklists themselves, this must be done in the Admin UI. Learn about managing picklists.

Retrieve All Picklists

Use this request to retrieve a list of all standard and custom picklists in your vault.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Example Request

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

Example Response (abridged)

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "errorCodes": null,
  "picklists": [
    {
      "name": "audience__vs",
      "label": "Audience",
      "kind": "document",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "audience__vs"
        }
      ]
    },
    {
      "name": "claim_category__vs",
      "label": "Claim Category",
      "kind": "document",
      "usedIn": [
        {
          "documentTypeName": "claim__vs",
          "propertyName": "claim_category__vs"
        }
      ]
    },
    {
      "name": "language__v",
      "label": "Language",
      "kind": "document",
      "system": true,
      "usedIn": [
        {
          "documentTypeName": "base_document__v",
          "propertyName": "language__v"
        }
      ]
    },
    {
      "name": "product_family__vs",
      "label": "Product Family",
      "kind": "object",
      "usedIn": [
        {
          "objectName": "product__v",
          "propertyName": "product_family__vs"
        }
      ]
    },
    {
      "name": "regions__c",
      "label": "Regions",
      "kind": "object",
      "usedIn": [
        {
          "objectName": "product__v",
          "propertyName": "regions__c"
        }
      ]
    },
    {
      "name": "therapeutic_area__vs",
      "label": "Therapeutic Area",
      "kind": "object",
      "usedIn": [
        {
          "objectName": "product__v",
          "propertyName": "therapeutic_area__vs"
        }
      ]
    },
    {
      "name": "license_type__v",
      "label": "License Type",
      "kind": "user",
      "system": true
    }
  ],
  "errorType": null
}

Response Details

The response lists the names and labels of all picklists configured in your vault. These include the following picklist properties:

Picklist Property Description Comments
name Picklist Name The name of the picklist, e.g., study_status__vs.
label Picklist Label The label of the picklist as seen in the UI, e.g., "Study Status".
system System (true/false) Indicates if the picklist is system-managed.
kind Picklist Kind - document picklists are used in document fields.
- object picklists are used in object fields.
- global picklists are used in milestone_type__v fields (eTMF Vaults).
- user picklists are used in user fields.
usedIn Used In For document picklists, this indicates:
- the document type in which the picklist is defined (see documentTypeName).
- the related field name (see propertyName).
For object picklists, this indicates:
- the object in which the picklist is defined (see objectName).
- the related field name (see propertyName).
For global picklists, this indicates:
- both the document type and the object in which the picklist is defined.
- the related field names for each (see propertyName).
documentTypeName Document Type Name For document and global picklists, this the document type name in which the picklist is defined.
objectName Object Name For object picklists, this is the object name in which the picklist is defined.
For global picklists, the object is milestone__v (eTMF vaults).
propertyName Property Name For document picklists, this is the document field name using the picklist.
For object picklists, this is the object field name using the picklist.
For global picklists, this is the milestone_type__v picklist (eTMF vaults).

Possible Errors

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

Version History

Available in API v4.0 or later.

Retrieve Picklist Values

Use this request to retrieve all values (names and labels) currently configured on an existing picklist in your vault.

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

  • {NAME} - The name of the existing picklist to which you're adding new values (language__v, therapeutic_area__vs, regions__c, etc.).
  • To see all picklists configured in your vault, use the "Retrieve All Picklists" endpoint above.

Example Request

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

Example Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "picklistValues": [
    {
      "name": "europe__c",
      "label": "Europe"
    },
    {
      "name": "asia_pacific__c",
      "label": "Asia Pacific"
    },
    {
      "name": "australasia__c",
      "label": "Australasia"
    },
    {
      "name": "middle_east__c",
      "label": "Middle East"
    }
  ]
}

Possible Errors

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

Version History

Available in API v4.0 or later.

Create Picklist Values

Use this request to add new values to an existing picklist. You can add up to 1024 values to any picklist.

Method & Endpoint

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

Request Headers

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

Request Parameters

  • {NAME} - The name of the existing picklist to which you're adding new values (language__v, therapeutic_area__vs, regions__c, etc.).
  • To see all picklists configured in your vault, use the "Retrieve All Picklists" endpoint above.
  • To see all names and labels currently configured on an existing picklist, use the "Retrieve Picklist Values" endpoint above.

Name-Value Pair Input Requirements

  • To add new values, use the picklist property name (value_1=, value_2=, value_3=, etc.).
  • Enter new picklist value labels as they will be displayed in the UI. Example: "value_1=North America" (surrounded by double-quotes).

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "value_1=North America" \
-d "value_2=Central America" \
-d "value_3=South America" \
https://myvault.veevavault.com/api/v13.0/objects/picklists/regions__c

Example Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Created picklist value(s).",
  "picklistValues": [
    {
      "name": "north_america__c",
      "label": "North America"
    },
    {
      "name": "central_america__c",
      "label": "Central America"
    },
    {
      "name": "south_america__c",
      "label": "South America"
    }
  ]
}

Possible Errors

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

Version History

Available in API v4.0 or later.

Update Picklist Value Label

Use this request to update the labels (only) for existing picklist values in your vault. To update picklist value names, refer to the section below.

CAUTION: This may break existing integrations that access picklist values via the API. Use caution when editing picklist labels or names. When these attributes are changed, they affect all existing document and object metadata that refer to the picklist. For users in the UI who are accustomed to seeing a particular selection (picklist label), the changes may also cause confusion.

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/picklists/{NAME} endpoint.

Request Headers

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

Request Parameters

  • {NAME} - The name of the existing picklist to which you're updating labels (language__v, therapeutic_area__vs, regions__c, etc.).
  • To see all picklists configured in your vault, use the "Retrieve All Picklists" endpoint above.
  • To see all names and labels currently configured on an existing picklist, use the "Retrieve Picklist Values" endpoint above.

Name-Value Pair Input Requirements

  • To change existing values, use the existing picklist name (north_america__c=, central_america__c=, etc.) and enter new labels as they will be displayed in the UI.
  • For example, to change the label of the existing "north_america__c=North America", enter "north_america__c=North America/United States".

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "north_america__c=North America/United States" \
https://myvault.veevavault.com/api/v13.0/objects/picklists/regions__c

Example Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Updated picklist value(s).",
  "picklistValues": [
    {
      "name": "north_america__c",
      "label": "North America/United States"
    }
  ]
}

As shown above, only the picklist value label has been changed. The picklist value name remains the same. All documents and objects that refer to the specified picklist value will be updated as well.

Possible Errors

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

Version History

Available in API v4.0 or later.

Update Picklist Value Name

Use this request to update the name (only) of an existing picklist value in your vault. To update picklist value labels, refer to the section above.

CAUTION: This may break existing integrations that access picklist value via the API. Use caution when editing picklist labels or names. When these attributes are changed, they affect all existing document and object metadata that refer to the picklist. For users in the UI who are accustomed to seeing a particular selection (picklist label), the changes may also cause confusion.

Method & Endpoint

Send a PUT request to the /api/{VERSION}/objects/picklists/{NAME}/{PICKLIST_VALUE_NAME} endpoint.

Request Headers

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

Request Parameters

  • {NAME} - The name of the existing picklist to which you're updating names (language__v, therapeutic_area__vs, regions__c, etc.).
  • {PICKLIST_VALUE_NAME} - The existing picklist value name which you are changing (north_america__c=, central_america__c=, etc.).
  • To see all picklists configured in your vault, use the "Retrieve All Picklists" endpoint above.
  • To see all names and labels currently configured on an existing picklist, use the "Retrieve Picklist Values" endpoint above.

Name-Value Pair Input Requirements

  • To change an existing name, use the picklist property name (name=) set to the new name.
  • For example, to change the existing north_america__c pickist value name, enter "name=north_america_united_states".
  • Do not include the __c suffix with the new name. Vault will automatically add this after updating.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name=north_america_united_states" \
https://myvault.veevavault.com/api/v13.0/objects/picklists/regions__c/north_america__c

Example Response

{
  "responseStatus": "SUCCESS"
}

Only the picklist value name has been changed. The picklist value label remains the same. All documents and objects that refer to the specified picklist value will be updated as well.

Possible Errors

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

Version History

Available in API v10.0 or later.

Delete Picklist Value

Use this request to delete a value from an existing picklist in your vault.

CAUTION: This may break existing integrations that access picklist value via the API. When these attributes are changed, they affect all existing document and object metadata that refer to the picklist. For users in the UI who are accustomed to seeing a particular selection (picklist label), the changes may also cause confusion.

Method & Endpoint

Send a DELETE request to the /api/{VERSION}/objects/picklists/{NAME}/{PICKLIST_VALUE_NAME} endpoint.

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

  • {NAME} - The name of the existing picklist to which you're updating names (language__v, therapeutic_area__vs, regions__c, etc.).
  • {PICKLIST_VALUE_NAME} - The existing picklist value name which you are deleting (north_america__c=, central_america__c=, etc.).
  • To see all picklists configured in your vault, use the "Retrieve All Picklists" endpoint above.
  • To see all names and labels currently configured on an existing picklist, use the "Retrieve Picklist Values" endpoint above.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v13.0/objects/picklists/regions__c/north_america_united_states__c

Example Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Deleted picklist value.",
  "name": "north_america_united_states__c"
}

Possible Errors

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

Version History

Available in API v4.0 or later.



Security Policies

Learn about authentication and security in Vault Help.


Retrieve All Security Policies

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "security_policies__v": [
        {
            "name__v": "821",
            "label__v": "Basic",
            "value__v": "https://myvault.vaultdev.com/api/v14.0/objects/securitypolicies/821"
        },
        {
            "name__v": "958",
            "label__v": "Default",
            "value__v": "https://myvault.vaultdev.com/api/v14.0/objects/securitypolicies/958"
        },
        {
            "name__v": "957",
            "label__v": "High Security",
            "value__v": "https://myvault.vaultdev.com/api/v14.0/objects/securitypolicies/957"
        }
    ]
}

Response Details

On SUCCESS, the response includes the following information:

Field Name Description Comments
security_policies__v [n] All Security Policies List of all security policies configured in your vault.
name__v Security Policy ID System-managed number field automatically added to the security policy. Use the ID to retrieve a security policy.
label__v Security Policy Label User-defined string field for the security policy. The label is used to identify the security policy in the UI.
value__v Security Policy URL URL to access the security policy details.

Version History

Available in API v3.0 or later.


Retrieve Security Policy

Method & Endpoint

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

Request Headers

  • JSON is the default response format (application/json).
  • To request an XML response, set the HTTP Request Header Accept to application/xml.

Request Parameters

  • {ID} - The security policy id field value. This is retrieved from the previous request.

Example Request

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

Example Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "security_policy__v": {
        "policy_details__v": {
            "name__v": "1722",
            "label__v": "SFDC Users Policy",
            "description__v": "A sample security policy.",            
            "is_active__v": true
        },
        "policy_security_settings__v": {
            "authentication_type__v": {
                "name__v": "Password",
                "label__v": "Password"
            },
            "passwords_require_number__v": true,
            "passwords_require_uppercase_letter__v": true,
            "passwords_require_nonalpha_char__v": true,
            "min_password_length__v": 10,
            "password_expiration__v": 90,
            "password_history_reuse__v": 3,
            "require_question_on_password_reset__v": true,
            "allow_delegated_auth_sfdc__v": true,
            "sfdc_org_id__v": "00215SFDA9587456"
        }
    }
}

Response Details

On SUCCESS, the response includes some or all of the following security policy fields:

Note: Boolean fields are only returned when the value is set to true.

Field Name Description
policy_details__v Policy Details
name__v Security Policy ID
label__v Security Policy Label
description__v Security Policy Description
is_active__v Active (true/false)
policy_security_settings__v Policy Security Settings
authentication_type__v Authentication Type
name__v Authentication Type Name
label__v Authentication Type Label
passwords_require_number__v Passwords Require Number (true/false)
passwords_require_uppercase_letter__v Passwords Require Upper-Case Letter (true/false)
passwords_require_nonalpha_char__v Passwords Require Non-Alphanumeric Character (true/false)
min_password_length__v Minimum Password Length (7, 8, 10, or 12 characters)
password_expiration__v Password Expiration (90 days, 180 days, or no expiration)
password_history_reuse__v Password History Reuse (prevent reuse of the last 3 passwords, 5 passwords, or no limitations)
require_question_on_password_reset__v Require Security Question on Password Reset (true/false)
allow_delegated_auth_sfdc__v Allow Salesforce Delegated Authentication (true/false)
sfdc_org_id__v Salesforce Org ID

Refer to the Vault Authentication article on this site for more information about Username and Password Authentication, Single Sign-On with SAML Authentication, and Salesforce Delegated Authentication.

Version History

Available in API v3.0 or later.

Workflows

The workflows object represents the actively running workflows in Veeva Vault. This API lets you retrieve the metadata of the object so it can be queried using the Query API.

Workflow Metadata

The workflows object consists of the following fields:

Field Description Type Comments
workflow_id__v Workflow ID id the ID of the workflow instance
workflow_document_id__v Document ID id the ID of the document associated with the workflow
workflow_document_major_version_number__v Document Major Version Number
workflow_document_minor_version_number__v Document Minor Version Number
workflow_name__v Workflow Name String ``
workflow_initiator__v Workflow Initiator ID ObjectReference the user ID of the user who initiated the workflow
workflow_initiatorName__v Workflow Initiator Name String the name of the user
workflow_status__v Workflow Status String allowable values are active, completed, cancelled
workflow_startDate__v Workflow Start Date DateTime
workflow_cancelationDate__v Workflow Cancellation Date DateTime only populated if workflow has been cancelled
workflow_completionDate__v Workflow Completion Date DateTime only populated if workflow is completed
workflow_dueDate__v Workflow Due Date Date only populated if a due date has been defined
workflow_duration__v Workflow Duration Number number of days
task_id__v Task ID id the ID of the task instance
task_name__v Task Name String the name of the task
task_asignee__v Task Assignee ID ObjectReference the ID of the user assigned to the task
task_asigneeName__v Task Assignee Name String the name of the user assigned to the task
task_status__v Task Status String available, assigned, completed, cancelled
task_assignmentDate__v Task Assignment Date DateTime the date the task was assigned to a user
task_cancelationDate__v Task Cancellation Date DateTime only populated if task has been cancelled
task_completionDate__v Task Completion Date DateTime only populated if task has been completed
task_creationDate__v Task Creation Date DateTime the date the task was created
task_dueDate__v Task Due Date Date task due date (if defined by the workflow originator)
task_duration__v Task Duration Number the number of days a task was active before it was completed (with fractions)
task_queueGroup__v Task Queue Group String populated only if the task was sent to a group
task_verdict__v Task Verdict String user-driven, defined during workflow admin
task_comment__v Task Comments String if entered, task comment entered by workflow actor

In addition, the values property will be filled out for the following workflow properties:

label values
workflow_name__v list of available workflow names within the vault
workflow_status__v list of possible workflow statuses across all workflows
task_name__v list of available task names across all workflows
task_queueGroup__v list of all groups specified as task owners across all workflow tasks
task_status__v list of task statuses across all tasks. Example list would be Assigned, Available, Canceled, Completed
task_verdict__v list of all available verdicts across all workflow tasks

Retrieve Workflow Metadata

You can retrieve the list of available properties for querying on workflows object in Vault by sending the GET request to the /api/{version}/metadata/objects/workflows endpoint.

For example:

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

This will mirror the data retrieved via workflow reporting.

Response

On success, Vault returns the list of values that describes the workflows in the user's vault.

For example:

{
    "responseStatus": "SUCCESS",
    "properties": [
        {
            "name": "workflow_document_id__v",
            "type": "id",
            "multivalue": false
        },
        {
            "name": "workflow_initiator_name__v",
            "type": "String",
            "length": 255,
            "multivalue": false
        },
        {
            "name": "workflow_id__v",
            "type": "id",
            "multivalue": false
        },
        {
            "name": "workflow_name__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Approval"
                },
                {
                    "label": "Review"
                },
                {
                    "label": "Send for Training"
                },
                {
                    "label": "Test on Draft - Send for Training"
                },
                {
                    "label": "Upload New Draft"
                },
                {
                    "label": "Upload Source File"
                }
            ]
        },
        {
            "name": "workflow_initiator__v",
            "type": "ObjectReference",
            "object": "User",
            "multivalue": false
        },
        {
            "name": "workflow_status__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Error"
                },
                {
                    "label": "Complete"
                },
                {
                    "label": "Cancelled"
                },
                {
                    "label": "Active"
                }
            ]
        },
        {
            "name": "workflow_startDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "workflow_completionDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "workflow_cancelationDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "workflow_duration__v",
            "type": "Number",
            "multivalue": false
        },
        {
            "name": "workflow_dueDate__v",
            "type": "Date",
            "multivalue": false
        },
        {
            "name": "workflow_type__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Standard"
                },
                {
                    "label": "Read and Understood"
                },
                {
                    "label": "Read and Understood"
                }
            ]
        },
        {
            "name": "workflow_document_major_version_number__v",
            "type": "Number",
            "multivalue": false
        },
        {
            "name": "workflow_document_minor_version_number__v",
            "type": "Number",
            "multivalue": false
        },
        {
            "name": "workflow_process_instance_group__v",
            "type": "String",
            "length": 255,
            "multivalue": false
        },
        {
            "name": "task_assignee_name__v",
            "type": "String",
            "length": 255,
            "multivalue": false
        },
        {
            "name": "task_id__v",
            "type": "id",
            "multivalue": false
        },
        {
            "name": "task_name__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Approve"
                },
                {
                    "label": "Assess outcome"
                },
                {
                    "label": "Review and provide annotations"
                },
                {
                    "label": "RU User Task"
                },
                {
                    "label": "Read"
                },
                {
                    "label": "Upload file."
                },
                {
                    "label": "Step Name: Upload Source File"
                }
            ]
        },
        {
            "name": "task_assignee__v",
            "type": "ObjectReference",
            "object": "User",
            "multivalue": false
        },
        {
            "name": "task_delegate__v",
            "type": "ObjectReference",
            "object": "User",
            "multivalue": false
        },
        {
            "name": "task_queueGroup__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Approver"
                },
                {
                    "label": "Editor"
                },
                {
                    "label": "Reviewer"
                },
                {
                    "label": "Trainee"
                },
                {
                    "label": "originator"
                }
            ]
        },
        {
            "name": "task_status__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Created"
                },
                {
                    "label": "Cancelled"
                },
                {
                    "label": "Assigned"
                },
                {
                    "label": "Available"
                },
                {
                    "label": "Completed"
                }
            ]
        },
        {
            "name": "task_verdict__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false,
            "values": [
                {
                    "label": "Approved"
                },
                {
                    "label": "Not approved"
                },
                {
                    "label": "Changes required, return to originator"
                },
                {
                    "label": "No changes required, document is Ready for Approval"
                }
            ]
        },
        {
            "name": "task_capacity__v",
            "type": "Picklist",
            "length": 255,
            "multivalue": false
        },
        {
            "name": "task_creationDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "task_assignmentDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "task_completionDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "task_cancelationDate__v",
            "type": "DateTime",
            "multivalue": false
        },
        {
            "name": "task_duration__v",
            "type": "Number",
            "multivalue": false
        },
        {
            "name": "task_dueDate__v",
            "type": "Date",
            "multivalue": false
        },
        {
            "name": "task_comment__v",
            "type": "String",
            "length": 4000,
            "multivalue": false
        }
    ]
}

Each array row contains the following:

Field Description
name the name of the workflow property
type the data type of the property (e.g. id, Date, DateTime, String, Number, ObjectReference, Picklist)
length length of the value (if type = String)
multivalue true or false
values provides array of available values, in the form "label:value" in the vault's workflows

Errors

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

Version History

Since: v4.0

Query

Query API is used to construct simple but powerful queries to retrieve data from Vault. When a client application invokes the query call, it passes in a Vault Query Language (VQL) expression (a SQL-like query) that specifies the object to query, the fields to retrieve, and any conditions to qualify an object.

For detailed information, refer to the following articles which focus on querying informaiton in Vault:

Errors

The Vault response to every API call includes a field called responseStatus. Possible values are:

  • SUCCESS - The API request has been successfully processed.
  • FAILURE - The API request could not be processed because of API user error.
  • EXCEPTION - The API request could not be processed because of API system error.

For a responseStatus other than SUCCESS, API users can inspect another field in the response called errors. Each error includes the following fields:

type

  • The specific type of error, e.g., INVALID_DATA, PARAMETER_REQUIRED, etc.
  • These values are not subject to change for a given version of the API, even when newer versions of the API are available.
  • API users need to use the error type value in combination with the responseStatus value for error handling.
  • In other words, the type and responseStatus values ARE contractual parts for error handling.

message

  • The message accompanying each error type, e.g., Missing required parameter [{FIELD_NAME}].
  • When available, the error message includes the specific reason, e.g., {FIELD_NAME} for the error.
  • Other error messages provide more general reasons for each error.
  • These values are subject to change, even for past versions. They ARE NOT contractual parts for error handling. Developers should consider error messages for debugging and troubleshooting purposes only and should not implement application logic which relies on specific error strings or formatting.

For a responseStatus of SUCCESS, the errors field is either omitted or has a null value.

Example: An unsuccessful authentication request due to password not provided:

{
    "responseStatus" : "FAILURE"**,
    "errors" : [
        {
            "type" : "NO_PASSWORD_PROVIDED",
            "message" : "No password was provided for the login call."
        }
    ],
    "errorType" : "AUTHENTICATION_FAILED"
}

Error Types

Type Description
UNEXPECTED_ERROR General error catch-all when there is no specific error, or an unidentified error.
MALFORMED_URL The specified resource cannot be found.
METHOD_NOT_SUPPORTED The specified resource does not support the (POST, PUT, GET, DELETE) method. Or, the API request is not supported by this version of API.
INACTIVE_USER User is inactive or not found.
NO_PASSWORD_PROVIDED No password was provided for the login call.
USERNAME_OR_PASSWORD_INCORRECT Authentication failed because an invalid username or password was provided.
USER_LOCKED_OUT The user is locked out.
PASSWORD_CHANGE_REQUIRED Password change required.
INVALID_SESSION_ID Invalid session id provided.
PARAMETER_REQUIRED Missing required parameters in the API call.
INVALID_DATA Invalid data provided in the API call.
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action.
OPERATION_NOT_ALLOWED Certain rules that must be met to perform this operation have not been met.
ATTRIBUTE_NOT_SUPPORTED The specified resource does not recognize provided attributes.
INVALID_FILTER Provided a non-existent filter to Retrieve Documents.
INCORRECT_QUERY_SYNTAX_ERROR Query string used with Query API has an incorrect query syntax.
RACE_CONDITION A rare condition where the same record is being simultaneously updated by another API call
EXCEEDS_FILE_MAX_SIZE The size of file uploaded exceeds the maximum allowed
API_LIMIT_EXCEEDED Vault limits the number of API calls that can be made every 5 minutes and every 24 hours. When either of these limits are reached, this error message is returned and no further calls will be processed until the next 5 minute or 24 hour period begins. The default limit every 5 minutes is 1000 or 2000 calls, depending on your vault. The default limit every 24 hours is 100,000 calls.

Backwards Compatibility

Although we do not change behavior in previous API versions, we may update and improve messages that accompany error responses. Error types will not change. Developers should consider error messages for debugging and troubleshooting purposes only and should not implement application logic which relies on specific error strings or formatting.

Security

The Vault API respects the security and permissions of the user that is logged in.

  • The user will not be able to retrieve or query any document that they do not have access to through the API.
  • The user will not be able to modify, create, or delete any document that they do not have the permissions to through the security matrix.
  • The user will be shown metadata that is specific to the permissions set by property level security and the user's access. System administrators will be able to see properties that are hidden to them, but the metadata will reflect that with the hidden tag.