API Reference (v5.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).

HTTP Methods

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.

Authenticate

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}/api/auth
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.

Delegated Authentication via Salesforce

See details.

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.

Document Metadata

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

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 (template return values since v5.0)
Request Parameters:
includeInheritedFields – indicates whether properties and templates from higher in the document type hierarchy should be included. Optional. Default is true.
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
  definedInType – where the property is defined in, is one of type, subtype or classification
  definedIn – the name of type, subtype or the classification that the property is defined in
templates – an array of templates that are available for the selected type/ subtype/ classification. Each record in the array will contain:
  label – label of the template
  name – name of the template
  kind – “binder” or “document” to distinguish whether it can be applied to a binder or document
  definedInType – where the template is defined in, is one of type, subtype or classification
  definedIn – the name of the type, subtype, or the classification that the template is defined within

Error Conditions: Refer to Errors section.

Documents Relationships Metadata

End Point URL:/api/{version}/metadata/objects/documents/types/{type}/relationships
Where:
{type} -  is one of the values of property types returned from the /api/{version}/metadata/objects/documents/types call
HTTP Method: GET
Since Version: v3.0
Request Parameters: none
Response:
relationshipTypes – an array of relationships available for this document type, each array item giving details for each relationship type as follows:
value – the name of relationship type
label – the label of relationship type
targetDocumentTypes – an array of possible target document types that a relationship can be created to
A list of properties available for the relationship. Each property has the following:
name – name of the property
type – the type of the property
required – if the field is required
length – the length of the property
editable – is the property editable
setOnCreateOnly – if the property can be set on create only
queryable – if the property is exposed in query
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.

Document Properties

Get metadata for all document properties of the Vault.
End Point URL: /api/{version}/metadata/objects/documents/properties
HTTP Method: GET
Since Version: v4.0
Request Parameters: none
Response: properties - An array of all the document properties of the Vault. 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
definedInType – where the property is defined in, is one of type, subtype or classification
definedIn – the name of type, subtype or the classification that the property is defined in
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.

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

Create Document

End Point URL: /api/{version}/objects/documents
HTTP Method: POST
Since Version: v1.0 (create from template supported since v5.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.
To create a document from a template, include a parameter “fromTemplate” and specify the name of the template as returned from the document type metadata API’s: /api/{version}/metadata/objects/documents/types/{type}
/api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype}
/api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype}/classification/{classification}
Only templates of type “document” are allowed and the document type of the document being created must match the metadata API path.
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.

List Document Relationships

End Point URL:/api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships
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: v3.0
Request Parameters: None
Response:On success an array of document relations is returned. Each relationship has the following properties:
id – id of the relationship
relationship_type__v – the name of relationship type
target_doc_id__v – relationship target document id
target_major_version__v – major version of the target document, a null value indicates that the relationship applies to all major versions of the target document
target_minor_version__v – minor version of the target document, a null value indicates that the relationship applies to all minor versions of the target document
Error Conditions: Refer to Errors section.

Create a Document Relationship

End Point URL:/api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships
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: POST
Since Version: v3.0
Request Parameters:
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” (/api/{version}/metadata/objects/documents/types/{type}/relationships) 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 the id of the newly created document relationship will be returned
Error Conditions: Refer to Errors section.

Retrieve a Document Relationship

End Point URL:/api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships/{relationshipId}
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
{relationshipId} - is a relationship id returned from the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships call
HTTP Method: GET
Since Version: v3.0
Request Parameters: None
Response:On success the requested relationship is returned. The relationship has the following properties:
id – id of the relationship
relationship_type__v – the name of relationship type
target_doc_id__v – relationship target document id
target_major_version__v – major version of the target document, a null value indicates that the relationship applies to all major versions of the target document
target_minor_version__v – minor version of the target document, a null value indicates that the relationship applies to all minor versions of the target document
Error Conditions: Refer to Errors section.

Delete a Document Relationship

End Point URL:/api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships/{relationshipId}
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
{relationshipId} - is a relationship id returned from the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships call
HTTP Method: DELETE
Since Version: v3.0
Request Parameters: None
Response:On success the requested relationship is deleted and the id of the deleted relationship is returned.
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

The Retrieve Documents API mimics the behavior of the pre-canned document lists 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.
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.
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 – 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 200
sort – sort field followed by sort order, e.g. name__v desc; optional
Response: Retrieves an array of documents and binders matching the retrieve request.
There is a parameter called “binder__v” which indicates whether the returned document is a regular document or a binder.
binder__v = true means it is a binder.
No value or binder__v = false means it is a document.
Binder structure is not listed as part of the response and must be determined through the appropriate binder API call.
Error Conditions: Refer to Errors section.
4.0 Notes: the scope parameter is only supported as of v4.0 of the API. The response set of this API now includes term-hit highlighting hints.
5.0 Notes: the response set distinguishes between documents and binders

Binders

Binders organize document 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

End Point URL: /api/{version}/objects/binders
HTTP Method: POST
Since Version: v5.0
Request Parameters: Refer to the output of the Retrieve Document Metadata API  for request parameters, only those properties that are marked as onCreateEditable=true are valid. No file can be uploaded as part of a binder
To create a document from a template, include a parameter “fromTemplate” and specify the name of the template as returned from the document type metadata API’s: /api/{version}/metadata/objects/documents/types/{type}
/api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype}
/api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype}/classification/{classification}
Only templates of type “binder” are allowed and the document type of the binder being created must match the metadata API path.

Response: On success the id of the newly created binder document will be returned.
Error Conditions: Refer to Errors section.

Retrieve Binder

End Point URL: /api/{version}/objects/binders/{id}
Where:
{id} - is a valid binder id (a document ID for a binder)
HTTP Method: GET
Since Version: v5.0
Request Parameters: depth – 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: 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 document, the API will return:

• order__v – order within the section or binder
• type__v = “document”
• id – node ID of the document, unique within the binder
• document_id__v – ID of the document
• name__v – name of the document
• major_version_number__v – major version (if binding rule = specific)
• minor_version_number__v – minor version (if binding rule = specific)

For each section, the API will return:

• order__v – order within the section or binder
• type__v = “section”
• id – ID of the section, unique within the binder
• name__v – name of the section
• section_number__v – section number (optional)

For each binder, the API will return:

• order__v – order within the section or binder
• type__v = “binder”
• id – ID of the binder
• name__v – name of the binder

Note that when a contained binder is listed here, no children of that binder are listed. It will require a separate Retrieve Binder API call for that binder to get that structure.

Error conditions:

Update Binder Properties

Update the binder properties.
End Point URL: /api/{version}/objects/binders/{id}
Where:
{id} - is a valid binder id
HTTP Method: PUT
Since Version: v5.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 selected binder will be returned.
Error conditions:

Delete Binder

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

Create a Binder Relationship

End Point URL: /api/{version}/objects/binders/{id}/versions/{major}/{minor}/relationships
Where:
{id} - is a valid binder id
{major} and {minor} - are one of the numbers of property versions returned from the /api/{version}/objects/binders/{id}/versions call
HTTP Method: POST
Since Version: v5.0
Request Parameters:

• 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” (/api/{version}/metadata/objects/documents/types/{type}/relationships) 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 the id of the newly created binder relationship will be returned
Error Conditions: Refer to Errors section.

Retrieve a Binder Relationship

End Point URL: /api/{version}/objects/binders/{id}/versions/{major}/{minor}/relationships/{relationshipId}
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
• {relationshipId} – is a relationship id returned from the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships call

HTTP Method: GET
Since Version: v5.0
Request Parameters: None
Response: On success the requested relationship is returned. The relationship has the following properties:

• id – id of the relationship
• relationship_type__v – the name of relationship type
• target_doc_id__v – relationship target document id
• target_major_version__v – major version of the target document, a null value indicates that the relationship applies to all major versions of the target document
• target_minor_version__v – minor version of the target document, a null value indicates that the relationship applies to all minor versions of the target document

Error Conditions: Refer to Errors section.

Delete a Binder Relationship

End Point URL: /api/{version}/objects/binders/{id}/versions/{major}/{minor}/relationships/{relationshipId}
Where:

• {id} – is a valid binder id
• {major} and {minor} – are one of the numbers of property versions returned from the /api/{version}/objects/documents/{id}/versions call
• {relationshipId} – is a relationship id returned from the /api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships call

HTTP Method: DELETE
Since Version: v5.0
Request Parameters: None
Response: On success the requested relationship is deleted and the id of the deleted relationship is returned.
Error Conditions: Refer to Errors section.

Retrieve Binder Versions

Binders have versions just like regular documents
End Point URL: /api/{version}/objects/binders/{id}/versions
Where:

• {id} – is a valid binder id

HTTP Method: GET
Since Version: v5.0
Request Parameters: None
Response: On success a list of the available versions is returned.
Error Conditions: Refer to Errors section.

Retrieve Binder Version

Retrieve a specific version of a binder.
End Point URL: /api/{version}/objects/binders/{id}/versions/{major}/{minor}
Where:

• {id} – is a valid binder id
• {major} and {minor} – are one of the numbers of property versions returned from the /api/{version}/objects/binder/{id}/versions call

HTTP Method: GET
Since Version: v5.0
Request Parameters: None
Response: On success a list of the properties for the version is returned. The response is similar to the response returned from the current version of the document.
Error Conditions: Refer to Errors section.

Update Binder Version Properties

Update a specific version of the document.
End Point URL: /api/{version}/objects/binders/{id}/versions/{major}/{minor}
Where:

• {id} – is a valid binder id
• {major} and {minor} – are one of the numbers of property versions returned from the /api/{version}/objects/binders/{id}/versions call

HTTP Method: PUT
Since Version: v5.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 binder is updated and id of the updated binder is returned.
Error Conditions: Refer to Errors section.

Delete Binder Version

Delete a specific version of the binder.

Note: If a binder has only one version, you cannot delete it.
End Point URL: /api/{version}/objects/binders/{id}/versions/{major}/{minor}
Where:

• {id} – is a valid binder id
• {major} and {minor} – are one of the numbers of property versions returned from the /api/{version}/objects/binders/{id}/versions call

HTTP Method: DELETE
Since Version: v5.0
Request Parameters: None
Response: On success the specified version of the binder is deleted.
Error Conditions: Refer to Errors section.

Update Binder Binding Rule

Update document version binding rules for the binder – either for all documents and sections within the binder that don’t already have binding rules set or for all documents and sections regardless of previous binding rules.

End Point URL: /api/{version}/objects/binders/{id}/binding_rule

Where:

• {id} – is a valid binder id

HTTP Method: PUT
Since Version: v5.0
Request Parameters:

• binding_rule__v – 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 – version currently in use
• binding_rule_override__v – if set to TRUE then binding rule is applied to all document 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.

Response: On success the id of the selected binder will be returned.
Error conditions:

Create Section

End Point URL: /api/{version}/objects/binders/{binder ID}/sections
HTTP Method: POST
Since Version: v5.0
Request Parameters:

• name__v – required, name of the section
• section_number__v – optional section number
• parent_id__v – optional ID if creating the section within another section. Blank means creating the section at the top-level binder.
• order__v – optional order within the parent section or binder (with “0” being the first position). Blank means add it as the last element in the binder or parent section. Order numbers that don’t make sense will be ignored.

Response: On success the id of the newly created section will be returned. It is unique within the binder, regardless of level.
Error Conditions:

Retrieve Section

End Point URL: /api/{version}/objects/binders/{id}/sections/{section id}

Where:

• {id} – is a valid binder id (a document ID for a binder)
• {section id} is a valid section ID. If blank, sections directly linked to the top-level binder will be listed.

HTTP Method: GET
Since Version: v5.0
Request Parameters: None
Response: Retrieves a list of all sections and documents and binders within the top-level binder (if {section id} is blank) or retrieves a list of all sections, documents, and binders within the specified section (if {section id} is a valid section within the binder}.
For each document, the API will return:

• order__v – order within the section
• type__v – “document”
• document_id__v – ID of the document
• name__v – name of the section
• id – unique ID of the node within the binder
• major_version_number__v – major version (if binding rule = specific)
• minor_version_number__v – minor version (if binding rule = specific)

For each section, the API will return:

• order__v – order within the section
• type__v – “section”
• id – ID of the section, unique within the binder
• name__v – name of the section
• section_number__v – section number (optional)

For each binder, the API will return:

• order__v - order within the section
• type__v – “binder”
• binder_id – ID of the binder
• name__v – name of the binder

Note that the section ID passed in may be at any level within the binder hierarchy as section ID is unique within the binder.
Error conditions:

Retrieve Binder Version Section

Retrieve the information for a section for a specific version of a binder.
End Point URL: /api/{version}/objects/binders/{id}/versions/{major}/{minor}/sections/{section id}

Where:

• {id} – is a valid binder id (a document ID for a binder)
• {major} and {minor} – are one of the numbers of property versions returned from the /api/{version}/objects/binders/{id}/versions call
• {section id} is a valid section ID. If blank, sections directly linked to the top-level binder will be listed.

HTTP Method: GET
Since Version: v5.0
Request Parameters: None
Response: Retrieves a list of all sections and documents and binders within the top-level binder (if {section id} is blank) or retrieves a list of all sections, documents, and binders within the specified section (if {section id} is a valid section within the binder}.
For each document, the API will return:

• order__v – order within the section
• type__v – “document”
• document_id__v – ID of the document
• name__v – name of the section
• id – unique ID of the node within the binder
• major_version_number__v – major version (if binding rule = specific)
• minor_version_number__v – minor version (if binding rule = specific)

For each section, the API will return:

• order__v - order within the section
• type__v – “section”
• id – ID of the section, unique within the binder
• name__v – name of the section
• section_number__v – section number (optional)

For each binder, the API will return:

• order__v – order within the section
• type__v – “binder”
• binder_id – ID of the binder
• name__v – name of the binder

Note that the section ID passed in may be at any level within the binder hierarchy as section ID is unique within the binder.
Error conditions:

Update Section

Update section name or number of an existing section and/or moves the section to a different location within the binder.

End Point URL: /api/{version}/objects/binders/{id}/sections/{section id}

Where:

• {id} – is a valid binder id
• {section id} is a valid section ID.

HTTP Method: PUT
Since Version: v5.0
Request Parameters: all optional unless otherwise noted

• name__v – name of the section
• section_number__v – section number
• parent_id__v – if moving the section, this is the new section ID (or binder ID if moving it to the top level of the binder
• order__v – if moving to a new section (as defined by new_parent_id being specified), this is the position within the target section or binder. If new_parent_id is blank, the API will move within the current section. If new_order is greater than the available positions, it will be placed in the last positoin.

All other items in the section or binder will move down one position. If blank and new_parent_id is entered, the section will move to the last position in the new section
Response: On success the id of the selected section will be returned.
Error conditions:

Update Section Binding Rule

Update binding rules within a section. Binding rule setting will apply to the current section and all sub-sections.

End Point URL: /api/{version}/objects/binders/{id}/sections/{section id}/binding_rule
Where:

• {id} – is a valid binder id
• {section id} is a valid section ID.

HTTP Method: PUT
Since Version: v5.0
Request Parameters: all optional unless otherwise noted

• binding_rule__v – 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 – specific version currently in use
• binding_rule_override__v – if set to TRUE then binding rule is applied to all document and sections within the current section. If blank of FALSE then binding rule is applied only to documents and sections within the current section that do not have a binding rule specified.

Response: On success the id of the selected section will be returned.
Error conditions:

Delete Section

Delete the selected 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.
End Point URL: /api/{version}/objects/binders/{id}/sections/{section id}
Where:

• {id} – is a valid binder id
• {section id} - is a valid section ID.

HTTP Method: DELETE
Since Version: v5.0
Request Parameters: None
Response: On success the id of the deleted section will be returned.
Error conditions:

Add Document to Binder

Link an existing document to a location within a binder (either at the top level or within a section in the binder)
End Point URL: /api/{version}/objects/binders/{binder ID}/documents
Where:

• {binder id} – is a valid binder id

HTTP Method: POST
Since Version: v5.0
Request Parameters:

• document_id__v – required, ID of the document being added to the binder
• parent_id__v – optional ID if linking the document to a section within the binder. 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 (with “1” being the first position). Blank means add it as the last element in the binder or parent section. Order numbers that don’t make sense will be ignored.
• 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 the node id of the newly linked in document will be returned.
Error Conditions:

Move Document Within Binder

Move the document to a different location within the binder.

End Point URL: /api/{version}/objects/binders/{id}/documents/{node id}

Where:

• {id} – is a valid binder ID
• {node id} – is a valid ID representing a document node currently linked to the binder

HTTP Method: PUT
Since Version: v5.0
Request Parameters: all optional unless otherwise noted

• parent_id__v – this is the new section ID (or binder ID if moving it to the top level of the binder
• order__v – this is the position within the target section or binder. If parent_if__v is blank, the API will move the document within the current section. If 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 blank and parent_id__v is entered, the document will move to the last position in the new section
Response: On success the id of the selected document will be returned.
Error conditions:

Update Document Binding Rules Within Binder

Update binding rules for the document within a specified binder

End Point URL: /api/{version}/objects/binders/{id}/documents/{node id}/binding_rule

Where:

• {id} – is a valid binder ID
• {node id} - is a valid ID representing a document node currently linked to the binder

HTTP Method: PUT
Since Version: v5.0
Request Parameters: all optional unless otherwise noted

• binding_rule__v – 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 – specific version currently in use
  • 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 the id of the selected document will be returned.
Error conditions:

Remove Document from Binder

Unlink an existing document from a location within a binder (either at the top level or within a section in the binder). Does not actually delete the document
End Point URL: /api/{version}/objects/binders/{binder ID}/documents/{node ID}
Where:

• {binder id} – is a valid binder id
• {node id} - is a valid node ID of a document that is linked to the binder

HTTP Method: DELETE
Since Version: v5.0
Request Parameters: None
Response: ID of the removed document if successful

Error conditions:

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 Role APIs, you can retrieve available roles for a document, determine who can be assigned to the role, default users that get assigned automatically within the Vault UI, and who is currently assigned to the role. You can also add additional users and groups to a role and remove users and groups as needed. Note that all user and group information is returned as IDs and you need to use the Retrieve User or Retrieve Group API to determine the name, etc.

Retrieve Document Roles

Retrieve the active, available roles for a document, available users and groups for the role, and any defaulted users or groups. 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.
End Point URL: /api/{version}/objects/documents/{id}/roles
Where:
{id} – is a valid document ID
HTTP Method: GET
Since Version: v5.0
Request Parameters: none
Response: roles – An array of all active roles assigned for the selected document. For each role listed, the API returns
role_name – role name
label – role label
assigned_users – a list of the ID’s for all users in the selected role assigned to the document
assigned_groups – a list of the ID’s for all groups in the selected role assigned to the document
available_users – a list of the ID’s for all users available in the selected role
available_groups – a list of the ID’s for all groups available in the selected role
default_users – a list of the default user IDs for the selected role
default_groups – a list of the default group IDs for the selected role

Retrieve Document Role Assignments

Get the users and groups assigned to a particular role on a document.
End Point URL: /api/{version}/objects/documents/{id}/roles/{role_name}
Where:
{id} – is a valid document ID
{role_name} – is the name of an available role for the document
HTTP Method: GET
Since Version: v5.0
Request Parameters: none
Response:
users – a list of the ID’s for all users in the selected role assigned to the document
groups – a list of the ID’s for all groups in the selected role assigned to the document
Error Conditions:

Add Users and Groups to a Document’s Role

Add a user or group to a document. This is done by assigning them to an available role for the document
End Point URL: /api/{version}/objects/documents/{id}/roles
Where:
{id} – is a valid document ID
HTTP Method: POST
Since Version: v5.0
Request Parameters: List of users or groups and their corresponding roles in the form of role.[users,groups]=ID1, ID2 as in
consumer__v.users=19376,18234,19456
legal__c.groups=19365, 18923
Response: On success an array of role:ID pairs will be returned for each of the successfully added users or groups. 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.

Delete User/Group from a Document’s Role

Delete a selected user or group from a document’s role.
End Point URL: /api/{version}/objects/documents/{id}/roles/{role_name}.[user/group]/{user or group_id}
Where:
{id} – is a valid document ID
{role_name} – is the name of an available role for the document
{user/group_id} – is the name of a user or group assigned to that role
HTTP Method: DELETE
Since Version: v5.0
Request Parameters: None
Response: on success the name of the deleted user name will be returned
Error Conditions:

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, latest – v5.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

API’s that affect the group object within 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.

Delete Group

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

Catalogs

Catalogs are tailored data tables that support different applications within Vault.

List Available Catalogs

List all catalogs defined in Vault.
End Point URL: /api/{version}/objects/catalogs
HTTP Method: GET
Since Version: v4.0
Request Parameters: None
Response: An array of catalogs available in a particular Vault. The catalogs will vary depending on the application.
name – name of the catalog – will be used in catalog APIs to define the catalog type
label - catalog label

Product and Country should be in all applications. eTMF contains Study, Site, and Location catalogs. Other applications will have their corresponding catalogs.

Catalog Metadata

Determine the properties available for a specified catalog

End Point URL:/api/{version}/metadata/objects/catalogs/{type}
Where:
{type} – is one of the names returned by the List Available Catalogs API and varies by application. Available catalogs include “product__v”, “country__v”, “study__v, “site__v”, “location__v”
HTTP Method: GET
Since Version: v4.0
Request Parameters: None
Response: An array of all properties for the specified catalog type. Each row in the array contains the values:
name – name of the property, to be used with create, update or query
label – property label
type – the type of the property
required – if the property is required
editable – if the property can be edited
length - maximum length of the value for the property
multivalue - if the property can hold multiple values
queryable - if the property is queryable
onCreateEditable - if the property can be set on create only

Create Catalog Entry

End Point URL: /api/{version}/objects/catalogs/{type}
Where:
{type} – name of the catalog
HTTP Method: POST
Since Version: v4.0
Request Parameters: Refer to the output of the Catalog Metadata API for request parameters for the specific properties required and available for the catalog type to be create. All properties marked as required=true must be present.
Response: On success the id of the newly created catalog entry will be returned.

Error conditions:

Retrieve Catalog Entries

End Point URL: /api/{version}/objects/catalogs/{type}
Where:
{type} – is a catalog type, as retrieved by List Available Catalogs API
HTTP Method: GET
Since Version: v30
Request Parameters: none
Response: An array of of valid values for a given catalog. Each row in the array will correspond to one catalog entry of the specified type. The actual properties vary depending on the catalog being retrieved in the Catalog Metadata API.
Note:  This API has new behavior in v4.0. In v3.0 it just returned name and abbreviation  for product and country catalogs. The v3.0 version of this API continues that behavior.
Each row will contain at minimum:

Error conditions:

Retrieve Catalog Entry

End Point URL: /api/{version}/objects/catalogs/{type}/{name}
Where:
{type} – is a catalog type, as retrieved by List Available Catalogs API
{name} – is the unique name for the catalog entry
HTTP Method: GET
Since Version: v4.0
Request Parameters: none
Response: The list of valid values for a given catalog entry. The actual properties vary depending on the catalog being retrieved in the Catalog Metadata API.
Each row will contain the values documented in the Retrieve Catalog Entries API

Error conditions:

Update Catalog Entry

End Point URL: /api/{version}/objects/catalogs/{type}/{name}
Where:
{type} – is a catalog type, as retrieved by List Available Catalogs API
{name} – is the unique name for the catalog entry
HTTP Method: PUT
Since Version: v4.0
Request Parameters: Refer to the output of the Catalog Metadata API for the catalog type. Should be input as a set of name/value pairs. Only those properties that are marked as editable=true are valid. If the property name is not specified, then do not update that property.
Response: on success the id of the updated catalog entry will be returned
Notes: catalog value name is not currently an updatable property. If a property value is not passed in, the value is not changed. To remove a property value, pass in the literal “null”.

Error conditions:

Delete Catalog Entry

End Point URL: /api/{version}/objects/catalogs/{catalog name}/{catalog value name}
Where:
{catalog name} – is a catalog type, as retrieved by List Available Catalogs API
{catalog value name} – is the public key of the catalog record
HTTP Method: DELETE
Since Version: v4.0
Request Parameters: None
Response: on success the id of the deleted catalog record will be returned

Error conditions:

Picklists

Picklists are lists of data that populate drop-down picklist properties in documents and catalogs.

Retrieve Picklists

Get all picklists defined in a vault
End Point URL: /api/{version}/objects/picklists
HTTP Method: GET
Since Version: v4.0
Request Parameters: none
Response: picklists – An array of all picklists in vault. For each picklist, the API returns
name – picklist name
label – picklist label
kind – either “catalog” or “document” depending if it is a picklist used in a catalog or document
used_in – if kind is “document”,  will be one or more document/property pairs. If kind is “catalog” will be one or more catalog name/catalog property pairs.
Error Conditions: Refer to Errors section.

Retrieve Picklist Values

Get all values for a picklist property.
End Point URL: /api/{version}/objects/picklists/{name}
Where:
{name} –  is the name of the picklist, as retrieved by the Retrieve Picklist API
HTTP Method: GET
Since Version: v4.0
Request Parameters: none
Response: properties – An array of all name:label pairs for the picklist where name is the system name of the picklist value and label is the visible picklist value.
Error Conditions:

Add Picklist Value(s) to a Picklist

Add one or more values to an existing picklist.
End Point URL: /api/{version}/objects/picklists/{name}
Where:
{name} – is the name of the picklist
HTTP Method: POST
Since Version: v4.0
Request Parameters: List of new label values for the picklist in the form “value_1=xxx, value_2=yyy, … value_n=zzz.”
Response: On success an array of name:label pairs will be returned for each of the successfully added picklist values.

Error Conditions:

Update Picklist Value

Update one or more specific picklist values. Note that all documents that refer to that picklist value will be updated as well.
End Point URL: /api/{version}/objects/picklists/{name}/
Where:
{name} – is the name of the picklist property
HTTP Method: PUT
Since Version: v4.0
Request Parameters: One or more values in a series of name=value pairs, where “name” is the name of the picklist property value and value is the visible name. The name field can be retrieved through the Retrieve Picklist Values API with endpoint /api/{version}/objects/picklists/{name}
Response: On success the specified picklist will be updated with the provided value.
Error Conditions:

Delete Picklist Value

End Point URL: /api/{version}/objects/picklists/{name}/{picklistPropertyName}
Where:
{name} – is the name of the picklist property
{picklistPropertyName} –  is the name of the picklist element to be removed
HTTP Method: DELETE
Since Version: v4.0
Request Parameters: None
Response: on success the name of the deleted picklist element will be returned
Error Conditions:

Security Policy Retrieval

Retrieve user security policies.
End Point URL: /api/{version}/objects/securitypolicies
HTTP Method: GET
Since Version: v3.0
Request Parameters: None
Response: A list of security policies in the vault.
A security policy value consists of fields:
id: The id of the value
name__v: The name of the value.
description__v: The description of the field.
Note: To assign a security policy in a user field of type object reference, use the id of the value.
Error Conditions: Refer to the errors section.

Workflows

Workflow Metadata

Lists available properties for querying on workflows in Vault. This will mirror the data retrieved via workflow reporting.
End Point URL: /api/{version}/metadata/objects/workflows
HTTP Method: GET
Since Version: v4.0
Request Parameters: None
Response: An array of values that describes the workflows in the user’s vault. Each array row contains the following:
name – name of the workflow property
type - 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.

Currently supported workflow properties include:

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

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. By default maximum of 1000 records are returned. This maximum can be overwritten by setting the limit parameter.
Error Conditions: Refer to the errors section.

Currently Supported Objects

Query currently supports documents, users, and workflow objects. The general query syntax and operators work across all three objects unless otherwise noted.

Query String Syntax

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

• Select the properties to be returned
• Select the object of the query
• Filter the resulting data
• Sort the resulting data
• Enable page-aware result sets by adding limits and offsets to the query
• Do broad searches for keywords across all searchable properties, the document’s content, or both

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. Object can be document, users, or workflows. Only one object can be referenced in each query and joins (where two object queries are correlated) are not currently supported

The selectable properties differ depending on the object being selected. Use the appropriate Metadata API to determine the allowable properties:

Documents

The properties available to query and filter documents will vary significantly depending on the document types that have been defined in the user’s vault. Use the Document Metadata API:

End Point URL:
/api/{version}/metadata/objects/documents/properties

to identify the allowable properties for the query – they will have thequeryable attribute set to TRUE.UsersThe properties available to query and filter users will be constant across different vaults as it is not currently extensible by users. It may change as additional user capabilities are added. As best practice, use the User Metadata API to confirm the user properties available to the query interface:

End Point URL: /api/{version}/metadata/objects/users

and use properties whose queryable attribute is set to TRUE.WorkflowsQuerying for workflows uses the same data source as workflow reporting. Both workflow and task information are available within the workflowsobject. The properties available to query and filter workflows will be constant across different vaults as it is not currently extensible by users. It may change as additional workflow or task functions are added. As best practice, use the Workflow Metadata API to confirm the properties available to the query interface:

End Point URL: /api/{version}/metadata/objects/workflows

Note that the workflows object will return different information depending on the property being queried. If only workflow properties are being selected, then the object will return one row per workflow. If task properties are being queried as well, there will be one row for each task and the workflow information being repeated for each of the workflow’s tasks.

A Note on Date Comparisons
This query object leverages the report data source. It behaves in a very similar manner to the document query including date handling. This can lead to some unobvious date manipulation when doing date comparisons. You need to assume that dates without time qualifiers are set to “00:00:00” (midnight of the day specified in the date portion). Thus if you want to find all workflow tasks completed after Halloween, you need to have the date query specified as

where task_completionDate__v > ‘2012-11-01’

since the completion date of one minute after midnight on November 1st would be considered greater than “2012-11-01”

Where Filter

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

Where property operator literal (plus optional: logical_operator property operator literal)

property: Properties varies depending on the object being queried. Unless otherwise noted, all properties that can be in the select statement for the object can be in the where filter.

operators: Operators consist of =, !=, <, >, between, and like. Like uses the % wildcard to mean any number of characters, there should be at least one character preceding the wildcard %.

logical operators: 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.

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

dates: Dates are in UTC date format – either yyyy-MM-dd (e.g. ’2012-08-13′) or yyyy-MM-dd’T'HH:mm:ss.SSS’Z’ (e.g. ’2012-08-13T15:30:00.000Z’). All dates or datetimes are returned based on UTC  (Coordinated Universal Time) and not the user’s 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

Note: When filtering the selection of objects by a property of type ObjectReference (e.g. catalog id, user id, document id, etc), it is recommended  that less then and greater then operators are not used, since the contents of the object’s {object}_name__v property and not the id is evaluated during the comparison and the end-result might not be as expected.

Sorting & Limiting

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

Order By property asc|desc

Note: When sorting documents objects by “product__v” or “country__v” properties, the result set will contain ID references to catalog objects sorted based on “{catalog}_name__v property” instead. This allows for a simpler retrieval of the sorted catalog labels.

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 (only applicable for the document object)

After the FROM clause you can use a “Find” operator which allows for a broad-based search for a term across all searchable properties and/or the document content.

Find search_terms scope properties | content | all

Find applies only when searching documents and will be equivalent to the search box in the UI. The search terms will be full word matches, but will also support the * wildcard for partial matches. It is strongly recommended not to use Find when specific property matches are critical, but it is appropriate for more interactive applications.

Scope indicates whether the find operation should be executed against searchable properties (“properties” – the default if scope is not present), the text of the document’s content (“content”), or both (“all”).

To find the documents with “indication” in any property:

Select id, name__v, title__v, description__v
From documents Find 'indication'

To find the documents with “insulin” in the text:

Select id, name__v, title__v, description__v
From documents Find 'insulin' scope content

Find can also be further refined by a where clause :

Select id, name__v, title__v, description__v
From documents Find 'established*' scope all 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 callederrors 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 ofresponseStatus for error handling, in other words the values of responseStatus and typeare 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.