Veeva Vault Developer Portal - Previous Versions
Vault API Reference

API Reference (v1.0) & (v2.0)

We recommend using a newer version of the API.

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 item, append its numerical id (/documents/42).

Creating, Retrieving, Updating, Deleting

To tell the API whether you are viewing, updating, or deleting the item, make use of the HTTP verbs,  GET, PUT, and DELETE (respectively). To create a new item, send a POST request to the collection’s URL (/documents). The API will respond with a JSON (default) or XML document reflecting your changes. All responses will include a responseStatus with a “SUCCESS” or “FAILURE” value. For a responseStatus other than SUCCESS, an “errors” key/value array returned with the response gives 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.

Below is the detailed information for each Veeva Vault API method, note that the string with curly braces in the End Point URL denotes a “variable” value. {version} in the End Point 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. The user will make a POST call with a username and password and receive a session id in return.

The session id should be passed as the value to the “Authorization” http header for all subsequent api requests.
Use the url value in the vaultIds key to make further calls against the api.

End Point URL: https://{yourVaultDNS}/auth/api
Where:
yourVaultDNS – your vault DNS
HTTP Method: POST
Since Version: v1.0
Request Parameters:
username - The vault username.
password - The password for that username
Response: The session id and the vault specific url to use
sessionId - The session id for subsequent api calls. The session id should be set with an “Authorization” header.
vaultIds - The object with the url to use in subsequent api calls.
Error Conditions: Refer to Errors section.

API Metadata

Retrieve Available API Versions

End Point URL: /api
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: An array of all available api versions.
Error Conditions: Refer to Errors section.

Retrieve Available API Resources (objects)

End Point URL: /api/{version}/metadata/objects
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: An array of all available resources for the given version.
Error Conditions: Refer to Errors section.

Documents

The heart of Veeva Vault is the document object. The API lets you create, update, retrieve and delete documents. The parameters of any object call are the properties of that corresponding object. You can get the list of properties from the metadata api call.

Documents Types Metadata

End Point URL: /api/{version}/metadata/objects/documents/types
HTTP Method: GET
Since Version: v1.0
Request Parameters: none
Response: A list of types available in the vault, each type is described with this information:
label- The label of the type
value – The url for the metadata of the type, use this url to get the subtypes for this type
The value of the url for the lock metadata.
Error Conditions: Refer to Errors section.

Documents Type/Subtype/Classification Metadata

End Point URL: /api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype}/classification/{classification}
Where:
{type} –  is one of the values of property types returned from the /api/{version}/metadata/objects/documents/types call
{subtype} – is one of the values of property subtypes returned from the /api/{version}/metadata/objects/documents/types/{type} call
{classification} - is one of the values of property classifications returned from the /api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype} call
HTTP Method: GET
Since Version: v1.0
Request Parameters: none
Response: A list of of child subtypes or classifications or values for the particular document hierarchy
label – The label of the type
name – The name of the type
renditions – an array of available rendition types
relationshipTypes – an array of label and values for supported relationships
properties – An array of the properties for the type. Each property contains the values:
name — name of the property
label — property label
type — the type of the property
required — if the property is required
maxValue — maximum value of the property
minValue — minimum value of the property
repeating — if the property is multi-valued
systemAttribute — if the property is a system property
editable — if the property can be edited
setOnCreateOnly — if the property can be set on create only
disabled — if the property is disabled
hidden — if the property is hidden
queryable — if the property is exposed in query
categoryType — where the property is defined in, is one of type, subtype or classification
categoryKey — the name of type, subtype or the classification that the property is defined in
Error Conditions: Refer to Errors section.

Documents Lock Metadata

End Point URL: /api/{version}/metadata/objects/documents/lock
HTTP Method: GET
Since Version: v1.0
Request Parameters: none
Response: A list of properties available for the lock. Each property has the following:
name — name of the property
label — the label of the property
type — the type of the property
required — if the property is required
systemAttribute – if the property is a system property
editable – if the property can be edited
setOnCreateOnly – if the property can be set on create only
disabled – if the property is disabled
hidden – if the property is hidden
scope — property scope (the value is “Lock” for all properties)
Error Conditions: Refer to Errors section.

Create Document

End Point URL: /api/{version}/objects/documents
HTTP Method: POST
Since Version: v1.0
Request Parameters: The POST should be a multi-part request. Refer to the output of the metadata for request parameters, only those properties that are marked as onCreateEditable=true are valid. To upload a file use multi-part attachment with the file component named “file”. If there is no file attached, the document will be a placeholder document.
Response: On success the id of the newly created document will be returned.
Error Conditions: Refer to Errors section.

Update Document

End Point URL: /api/{version}/objects/documents/{id}
Where:
{id} - is a valid document id
HTTP Method: PUT
Since Version: v1.0
Request Parameters: Refer to the output of the metadata, only those properties that are marked as editable=true are valid.
Response: On success the id of the updated document will be returned.
Error Conditions: Refer to Errors section.

Retrieve Document

End Point URL: /api/{version}/objects/documents/{id}
Where:
{id} - is a valid document id
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: Retrieves the properties of the document
Error Conditions: Refer to Errors section.

Delete Document

End Point URL: /api/{version}/objects/documents/{id}
Where:
{id} - is a valid document id
HTTP Method: DELETE
Since Version: v1.0
Request Parameters: None
Response: On success the id of the deleted document will be returned.
Error Conditions: Refer to Errors section.

Retrieve Document File

End Point URL: /api/{version}/objects/documents/{id}/file
Where:
{id} - is a valid document id
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: Retrieves the latest version of the file of the document with the response content type set to “application/octet-stream”.
Error Conditions: Refer to Errors section.

Create Document Lock

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.
End Point URL: /api/{version}/objects/documents/{id}/lock
Where:
{id} - is a valid document id
HTTP Method: POST
Since Version: v1.0
Request Parameters: None
Response: On success the document is locked and other users are not allowed to lock the document. To get the file use the Retrieve Document File api.
Error Conditions: Refer to Errors section.

Retrieve Document Lock

End Point URL: /api/{version}/objects/documents/{id}/lock
Where:
{id} - is a valid document id
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: Retrieves the lock object (if any) for a document
The lock object contains two parameters:
lockedBy — the id of the user who locked the document
lockedDate — the date the document was locked.
Error Conditions: Refer to Errors section.

Update Document File

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.
End Point URL: /api/{version}/objects/documents/{id}
Where:
{id} - is a valid document id
HTTP Method: POST
Since Version: v1.0
Request Parameters: The POST should be a multi-part request, use multi-part attachment with the file component named “file”.  Optionally a parameter description__v can be passed with the description for the minor version update.
Response: On success the document file is successfully updated.
Error Conditions: Refer to Errors section.

Delete Document Lock

Deleting document lock is analogous to undoing check out of a document.
End Point URL: /api/{version}/objects/documents/{id}/lock
Where:
{id} - is a valid document id
HTTP Method: DELETE
Since Version: v1.0
Request Parameters: None
Response: On success the document is successfully unlocked, allowing other users to checkout.
Error Conditions: Refer to Errors section.

List Document Renditions

End Point URL: /api/{version}/objects/documents/{id}/renditions
Where:
{id} - is a valid document id
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: An array of rendition types for the document.
Error Conditions: Refer to Errors section.

Retrieve Document Rendition

End Point URL: /api/{version}/objects/documents/{id}/renditions/{renditionType}
Where:
{id} - is a valid document id
{renditionType} - is one of the values of property renditions returned from the /api/{version}/metadata/objects/documents/types/{type} call
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: Retrieves the file associated with the given rendition type of the document with the response content type set to “application/octet-stream”.
Error Conditions: Refer to Errors section.

Upload Document Rendition

End Point URL: /api/{version}/objects/documents/{id}/renditions/{renditionType}
Where:
{id} - is a valid document id
{renditionType} - is one of the values of property renditions returned from the /api/{version}/metadata/objects/documents/types/{type} call
HTTP Method: POST
Since Version: v1.0
Request Parameters: The POST should be a multi-part request, use multi-part attachment with the file component named “file”.
Response: On success the file is successfully associated with the given rendition type of the document.
Error Conditions: Refer to Errors section.

Retrieve Document Versions

End Point URL: /api/{version}/objects/documents/{id}/versions
Where:
{id} - is a valid document id
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response:On success a list of the available versions is returned.
Error Conditions: Refer to Errors section.

Retrieve Document Version

Retrieve a specific version of the document.
End Point URL: /api/{version}/objects/documents/{id}/versions/{major}/{minor}
Where:
{id} - is a valid document id
{major} and {minor} - are one of the numbers of property versions returned from the /api/{version}/objects/documents/{id}/versions call
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: On success a list of the properties for the version is returned. The response is similiar to the response returned from the current version of the document.
Error Conditions: Refer to Errors section.

Update Document Version

Update a specific version of the document.
End Point URL:/api/{version}/objects/documents/{id}/versions/{major}/{minor}
Where:
{id} - is a valid document id
{major} and {minor} - are one of the numbers of property versions returned from the /api/{version}/objects/documents/{id}/versions call
HTTP Method: PUT
Since Version: v1.0
Request Parameters: Refer to the output of the metadata, only those properties that are marked as editable=true are valid.
Response: On success the specified version of the document is updated and id of the updated document is returned.
Error Conditions: Refer to Errors section.

Delete Document Version

Delete a specific version of the document.
End Point URL:/api/{version}/objects/documents/{id}/versions/{major}/{minor}
Where:
{id} - is a valid document id
{major} and {minor} - are one of the numbers of property versions returned from the /api/{version}/objects/documents/{id}/versions call
HTTP Method: DELETE
Since Version: v1.0
Request Parameters: None
Response: On success the specified version of the document is deleted.
Error Conditions: Refer to Errors section.

Retrieve Document Version File

Get a specific version of the document file.
End Point URL:/api/{version}/objects/documents/{id}/versions/{major}/{minor}/file
Where:
{id} - is a valid document id
{major} and {minor} - are one of the numbers of property versions returned from the /api/{version}/objects/documents/{id}/versions call
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: Retrieves the specified version of the file of the document with the response content type set to “application/octet-stream”.
Error Conditions: Refer to Errors section.

Retrieve Documents

End Point URL:/api/{version}/objects/documents
HTTP Method: GET
Since Version: v1.0
Request Parameters:
named_filter – is 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.
start – number indicating the row offset in the result; optional, the default is 0
limit – number indicating the maximum number to return; optional, the default is 5000
sort – sort field followed by sort order, e.g. name__v desc; optional
Response: Retrieves documents matching the retrieve request.
Error Conditions: Refer to Errors section.

Users

Users are the actual users of Veeva Vault.

User Metadata

End Point URL: /api/{version}/metadata/objects/users
HTTP Method: GET
Since Version: v1.0
Request Parameters: none
Response: is a list of properties, each property is described with this information:
name – name of the property, to be used with create, update or query
type – property type
multivalue – if the property can hold multiple values
queryable – if the property is queryable
length – maximum length of the value for the property
required – if the property is required
onCreateEditable – if the property can be set on create only
editable – if the property can be edited
Error Conditions: Refer to Errors section.

Create User

End Point URL: /api/{version}/objects/users
HTTP Method: POST
Since Version: v1.0
Request Parameters:  The POST should be a multi-part request. Refer to the output of the user metadata for request parameters, only those properties that are marked as onCreateEditable=true are valid. To upload a profile picture file use multi-part attachment with the file component named “file”.
user_email__v - should include the domain; ex. apiuser@veevavault.com
user_locale__v – valid values included in the metadata
security_policy_id__v – use the Security Policy Retrieval api for valid values
user_type_id__v – valid values included in the metadata
user_timezone__v – valid values included in the metadata
Response: on success the id of the newly created user will be returned
Error Conditions: Refer to Errors section.

Retrieve Users

End Point URL: /api/{version}/objects/users
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: Retrieves the properties of all the users
Error Conditions: Refer to Errors section.

Retrieve User

End Point URL: /api/{version}/objects/users/{id}
Where:
{id} - is a valid user id
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: Retrieves the properties of the specified user
Error Conditions: Refer to Errors section.

Update User

End Point URL: /api/{version}/objects/users/{id}
Where:
{id} - is a valid user id
HTTP Method: PUT
Since Version: v1.0
Request Parameters: Refer to the output of the user metadata, only those properties that are marked as editable=true are valid. The API currently does not support the update of profile pictures.
user_email__v - should include the domain; ex. apiuser@veevavault.com
user_locale__v - valid values included in the metadata
security_policy_id__v - use the Security Policy Retrieval api for valid values
user_type_id__v - valid values included in the metadata
user_timezone__v - valid values included in the metadata
Response: on success the id of the updated user will be returned
Error Conditions: Refer to Errors section.

Disable User

End Point URL: /api/{version}/objects/users/{id}
Where:
{id} - is a valid user id
HTTP Method: DELETE
Since Version: v1.0
Request Parameters: None
Response: on success the id of the disabled user will be returned
Error Conditions: Refer to Errors section.

Groups

User groups of the Veeva Vault.

Group Metadata

End Point URL: /api/{version}/metadata/objects/groups
HTTP Method: GET
Since Version: v1.0
Request Parameters: none
Response: is a list of properties, each property is described with this information:
name - name of the property, to be used with create, update or query
type - property type
multivalue - if the property can hold multiple values
queryable - if the property is queryable
length - maximum length of the value for the property
required - if the property is required
onCreateEditable - if the property can be set on create only
editable - if the property can be edited
Error Conditions: Refer to Errors section.

Create Group

End Point URL: /api/{version}/objects/groups
HTTP Method: POST
Since Version: v1.0
Request Parameters:  Refer to the output of the group metadata for request parameters, only those properties that are marked as onCreateEditable=true are valid.
group_name__v - user provided name for the group
group_description__v - user provided description for the group
members__v – comma separated list of user ids of the group
Response: on success the id of the newly created group will be returned
Error Conditions: Refer to Errors section.

Retrieve Groups

End Point URL: /api/{version}/objects/groups
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: Retrieves the properties of all the groups
Error Conditions: Refer to Errors section.

Retrieve Group

End Point URL: /api/{version}/objects/groups/{id}
Where:
{id} - is a valid group id
HTTP Method: GET
Since Version: v1.0
Request Parameters: None
Response: Retrieves the properties of the specified group
Error Conditions: Refer to Errors section.

Update Group

End Point URL: /api/{version}/objects/groups/{id}
Where:
{id} - is a valid group id
HTTP Method: PUT
Since Version: v1.0
Request Parameters: Refer to the output of the group metadata, only those properties that are marked as editable=true are valid.
group_name__v - user provided name for the group
group_description__v - user provided description for the group
members__v - comma separated list of user ids of the group
active__v – if the group is active
Response: on success the id of the updated user will be returned
Error Conditions: Refer to Errors section.

Query

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

End Point URL: /api/{version}/query
HTTP Method: GET
Since Version: v1.0
Request Parameters: q – the query string (see below for syntax details)
Response: A resultSet containing a list of values matching the query, each values object represents a row and contains values for fields requested.
Error Conditions: Refer to the errors section.

Query String Syntax

The query language is a SQL-like language designed to allow a user to:

  • Select the properties for the query
  • Select the object for the query
  • Filter the query
  • Sort the query
  • Limit and offset the query

Select Properties

Selecting properties to be returned will be similar to making a SQL select statement in the form of:

Select properties

where properties is a comma separated list of property values to be returned. For example:

Select id, name__v, title__v, description__v

From Object

The object is also similar to SQL, and is in the form of:

From Object

where Object is the name of the Object being queried. For instance:

From documents

Where Filter

Filtering will support a set of comparison operators that are in the form:

Where property operator literal  | logical_operator property operator literal

These operators will consist of =, !=, <, >, between, and like.
Logical operators will be AND and OR. AND will return true if the first and second expression is true, and OR will return true if either expression is true.
The operator literal will be a string (enclosed in quotes) or number.
Booleans can be compared using TRUE or FALSE in the operator literal.
The empty value can be tested using NULL as the operator literal.
Like uses the % wildcard to mean any number of characters, there should be atleast one character preceding the wildcard %
Dates are in UTC data format (yyyy-MM-dd or yyyy-MM-dd’T'HH:mm:ss.SSS’Z') When times or datetimes are returned through the API, they are always in UTC, not the users timezone.
Sample Where Filter:

Where (name__v='test document' AND type__v != 'Promotional Piece')
OR (name__v='test document' AND type__v = 'Claim')
AND document_creation_date__v > '2012-01-01T00:00:00.000Z'
AND title__v like 't%' AND submission_required__vs=true

Sorting and Limits

Sorting and limits will follow the where clause and will be in the form of:

Order By property asc|desc

Limits on queries will be in the form of:

Limit number

Pagination will be implemented using the Offset keyword. In the form:

Offset number

For instance, to return rows 11 – 20 of set of 20 and order by “id” desc, the query would be:

Select id from documents Order By id desc Limit 20 Offset 10

Find

After the FROM clause there can be a comparison operator that goes across multiple fields when unable to specify column to filter against. For that we will use “Find” in the form:

Find keywords

Find applies only when searching documents and will be equivalent to the search box in the UI. The keywords will be full word matches, but will also support the * wildcard for partial matches. It is strongly recommended not to use Find for mission critical integrations, it suits well for user interactive based applications.
To find the documents with “Eric Bezar”:

Select id, name__v, title__v, description__v
From documents Find 'Eric Bez*'

Find is also supported in single object queries with a where clause:

Select id, name__v, title__v, description__v
From documents Find 'Eric Bez*' where type__v='Claim'

Errors

Response to every API call includes a property called responseStatus, possible values for responseStatus are:
SUCCESS – API request has been successfully processed
FAILURE – API request couldn’t be processed because of API user error
EXCEPTION – API request couldn’t be processed because of API system error

For a responseStatus other than SUCCESS, API users can inspect another property called errors in the response to gather additional information about the errors, errors is a list of all errors when processing the request. For a responseStatus of SUCCESS the errors property is either omitted or has a null value. Each item of errors has the following properties:
type –  error type, see the table below for a list of error types; the values for error type are not subject to change for a given version of API even while there are newer versions of API. API users will need to use the value of type in combination with the value of responseStatus for error handling, in other words the values of responseStatus and type are contractual parts for error handling.
message – a detailed message for the error type, the message is subject to change and is not contractual for error handling.

A successful authentication request:

{
   "vaultId" : "3",
   "sessionId" : "1BDDF2B9DB53279C105B0D534B630FDAF68655D68EAA23B65C404FE96E607C44",
   "vaultIds" : [
      {
         "url" : "https://my.veevavault.com/api",
         "name" : "promovault",
         "id" : 3
      }
   ],
   "responseStatus" : "SUCCESS",
   "userId" : 2
}

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 – 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.
SDK_ERROR An error caused by the Vault Java SDK. This error may also include a custom subtype. For more information about this error, check the Debug Log. To inquire about Vault Java SDK Solutions, contact Veeva Services.

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.

Daily API Transaction Limit

For an individual vault, there is a daily limit on API transactions. The default limit is 100,000, but this value is configurable. To change the vault, contact Veeva Support.