API Reference (v4.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}/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.

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

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.

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

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

Note that the scope parameter is only supported as of v4.0 of the API. Also note that as of 4.0 the response set of this API includes term-hit highlighting hints.

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

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:

Type	Description
INSUFFICIENT_ACCESS	User does not have permission to create a catalog entry (e.g. is not a Business Admin, System Admin, or Vault Owner)
INVALID_DATA	Data entered was of incompatible type for a specific field
REQUIRED_FIELD_NOT_FOUND	A required property for the catalog was not present
CATALOG_NOT_FOUND	Catalog does not exist in this vault
DUPLICATE_CATALOG_VALUE	Catalog with this name has already been created

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:

Label	Name	Type	Comment
Active	active__v	boolean	TRUE if catalog record is active, FALSE otherwise
Created By	created_by__v	ObjectReference	ID of the user who created the catalog record
Created Date	created_date__v	datetime	Date and time the catalog object was created
Modified By	modified_by__v	ObjectReference	ID of the user who last modified the catalog record
Modified Date	modified_date__v	datetime	Date and time the catalog object was modified

Error conditions:

Type	Description
CATALOG_NOT_FOUND	Catalog does not exist in this vault

Retrieve Catalog Entry

Error conditions:

Type	Description
CATALOG_NOT_FOUND	Catalog does not exist in this vault
CATALOG_ENTRY_NOT_FOUND	Catalog entry does not exist in this vault

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:

Type	Description
INSUFFICIENT_ACCESS	User does not have permission to update a catalog entry (e.g. is not a Business Admin, System Admin, or Vault Owner)
INVALID_DATA	Data entered was of incompatible type for a specific field
REQUIRED_FIELD_NOT_FOUND	A required property for the catalog was not present
CATALOG_NOT_FOUND	Catalog does not exist in this vault

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:

Type	Description
CATALOG_IN_USE	The catalog entry could not be deleted because it is used by a document or another catalog
INSUFFICIENT_ACCESS	User does not have permission to delete a catalog entry (e.g. is not a Business Admin, System Admin, or Vault Owner)
CATALOG_NOT_FOUND	Catalog does not exist in this vault

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:

Type	Description
PICKLIST_NOT_FOUND	Picklist of name {name} was not found

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:

Type	Description
PICKLIST_NOT_FOUND	Picklist of name {name} was not found

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:

Type	Description
PICKLIST_NOT_FOUND	Picklist of name {name} was not found
PICKLIST_VALUE_NOT_FOUND	Picklist value of name {picklistPropertyName} was not found

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:

Type	Description
PICKLIST_NOT_FOUND	Picklist of name {name} was not found
PICKLIST_VALUE_NOT_FOUND	Picklist value of name {picklistPropertyName} was not found

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:

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

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

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

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.

Users

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

Workflows

Querying 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

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.

By default, the query API will return maximum of 1000 records. Limits on queries can be set and overwritten using the following form:

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.