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

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

Below is the detailed information for each Veeva Vault API method, note that the string with curly braces in the 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.

Alternatively query string parameter auth can be used instead of HTTP header “Authorization”. The value passed in the auth parameter will overwrite any value in the HTTP header “Authorization”.

Use the url value in the vaultIds key to make further calls against the API.

End Point URL: https://{yourVaultDNS}/api/{version}/auth
Where:
yourVaultDNS - your vault DNS
HTTP Method: POST
Since Version: v6.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.
Note: Auth API fixes a property type issue in version v6.0. To take advantage of the fix, {version} parameter is required on the endpoint. The legacy endpoint /api/auth is still available for backward compatibility.

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.

Domain Information

Retrieve Domain Information

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

End Point URL: /api/{version}/objects/domain
HTTP Method: GET
Since Version: v7.0
Request Parameters: None
Response:

The response contains:

domain_name__v - the domain name
domain_type__v - the domain type as one of: Sandbox, Demo, Test
vaults - a list of Vault instances in the domain
      id - the Vault instance ID
      vault_name__v - the Vault instance name
      vault_status__v - the Vault instance status
      vault_application__v - the Vault instance application type

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 Metadata

End Point URL: /api/{version}/metadata/objects/documents
HTTP Method: GET
Since Version: v1.0
Request Parameters: none
Response:

types – A list of types available in the vault, each type is described with:
  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

lock – The url for the lock metadata.

Error Conditions: Refer to Errors section.

Documents Types Metadata

End Point URL: /api/{version}/metadata/objects/documents/types
HTTP Method: GET
Since Version: v1.0
Request Parameters: none
Response:

types – A list of types available in the vault, each type is described with:
  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

Error Conditions: Refer to Errors section.

Documents Type/Subtype/Classification Metadata

End Point URL:/api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype}/classifications/{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

Shared Properties:
Shared properties are indicated by “shared: true” metadata field. In addition, “usedIn” metadata field specifies the document types where this property is currently used

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

Shared Properties:
Shared properties are indicated by “shared: true” metadata field. In addition, “usedIn” metadata field specifies the document types where this property is currently used.

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, latest v7.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.

Optional Query Parameters
async - [boolean] false by default, if set to true, causes the metadata to be indexed asynchronously

Response: On success the id of the newly created document will be returned.
Error Conditions: Refer to Errors section.
v5.0 Notes: create from template supported
v7.0 Notes: asynchronous metadata indexing supported

Update Document

End Point URL: /api/{version}/objects/documents/{id}
{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}
{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}
{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
{id} - is a valid document id
HTTP Method: GET
Since Version: v1.0
Request Parameters:
Optional Query Parameters
lockDocument - [boolean] false by default, if set to true, causes the document to be checked out before retrieval

Example:

curl -k -H “Authorization: A0524CEE29925F2D56B74F7EC60D9FB8D0C9141557509F4259CFF72AAFE023CBBDF0153363FBAC2DACF0D3782DD33DCE” https://veevapharm.veevavault.com/api/v7.0/objects/documents/1/file >> file

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.
6.0 Notes: Added lockDocument Query Parameter

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
{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
{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:
locked_by__v – the id of the user who locked the document
locked_date__v – the date the document was locked.
Error Conditions: Refer to Errors section.

Update Document File / Create Draft

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

End Point URL: /api/{version}/objects/documents/{id}
{id} - is a valid document id
HTTP Method: POST
Since Version: v1.0, latest v7.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.

createDraft - optional – [latestContent|uploadedContent]

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

file - contains the binary file attachment.

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

Response: On success the document file is successfully updated.
Error Conditions: Refer to Errors section.
v7.0 Notes: Added “Create Draft” feature

Delete Document Lock

Deleting document lock is analogous to undoing check out of a document.
End Point URL: /api/{version}/objects/documents/{id}/lock
{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, latest v6.0
Request Parameters: None
Response: An array of rendition types and available renditions for the document.
Error Conditions: Refer to Errors section.
v6.0 Notes: now returs both possible rendition types as well as available renditions

List Document Version Renditions

End Point URL: /api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions
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: v7.0
Request Parameters: None
Response: An array of rendition types and available renditions for the document.
Error Conditions: Refer to Errors section.

Retrieve Document Rendition

End Point URL: /api/{version}/objects/documents/{id}/renditions/{renditionType}
{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, latest v6.0
Request Parameters:
{steadyState} – [boolean] optional query string parameter, if set to true, will instruct the API to retrieve the latest steady state version of the document rendition
Response: Retrieves the file associated with the given rendition type of the document with the response content type set to “application/octet-stream”.
v6.0 Notes: added steadyState query string parameter
Error Conditions: Refer to Errors section.

Retrieve Document Version Rendition

End Point URL: /api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType}
{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
{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: v7.0
Request Parameters: None
Response: Retrieves the file associated with the given rendition type of the document with the given document version 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}
{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.

Upload Document Version Rendition

End Point URL: /api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType}
{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
{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: v7.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 with the specified version number.
Error Conditions: Refer to Errors section.

Delete Latest Document Rendition

Delete the rendition of specified type from the latest document version

Endpoint URL: /api/{version}/objects/documents/{id}/renditions/{renditionType}
{version} – API Version
{id} – Document ID
{renditionType} – is one of the values of property renditions returned from the /api/{version}/metadata/objects/documents/types/{type} call
HTTP Method: DELETE
Since Version: v7.0
Request Parameters: None
Response: On success the rendition of specified type is deleted from the latest version of the document identified by {id}.

Delete Document Version Rendition

Delete a rendition of specified type from the specified version of the document

Endpoint URL: /api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType}
{version} – API Version
{id} – Document ID
{major} and {minor} - are one of the numbers of property versions returned from the /api/{version}/objects/documents/{id}/versions call
{renditionType} – is one of the values of property renditions returned from the /api/{version}/metadata/objects/documents/types/{type} call
HTTP Method: DELETE
Since Version: v7.0
Request Parameters: None
Response: On success the rendition of specified type is deleted from the specified version of the document identified by {id}.

Replace Document Rendition

Replace the existing rendition of specified type from the latest version of the document

Endpoint URL: /api/{version}/objects/documents/{id}/renditions/{renditionType}
{version} – API Version
{id} – Document ID
{renditionType} – is one of the values of property renditions returned from the /api/{version}/metadata/objects/documents/types/{type} call
HTTP Method: PUT
Since Version: v7.0
Request Parameters: The request should contain a multi-part body. The file attachment must be named as “file”.
Response: On success the new file successfully replaces the existing file for the rendition type of the latest version for the document identified by {id}

Replace Document Version Rendition

Replace the existing rendition of specified type from the document version

Endpoint URL: /api/{version}/objects/documents/{id}/versions/{major}/{minor}/renditions/{renditionType}
{version} – API Version
{id} – Document ID
{major} and {minor} - are one of the numbers of property versions returned from the /api/{version}/objects/documents/{id}/versions call
{renditionType} – is one of the values of property renditions returned from the /api/{version}/metadata/objects/documents/types/{type} call
HTTP Method: PUT
Since Version: v7.0
Request Parameters: The request should contain a multi-part body. The file attachment must be named as “file”.
Response: On success the new file successfully replaces the existing file for the rendition type for the document in the specified document version.

List Document Relationships

End Point URL:/api/{version}/objects/documents/{id}/versions/{major}/{minor}/relationships
{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
{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}
{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}
{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
{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 Document Version Thumbnail

Get a thumbnail for a specific version of the document.
End Point URL:/api/{version}/objects/documents/{id}/versions/{major}/{minor}/thumbnail
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: v6.0
Request Parameters: None
Response: Retrieves the thumbnail for the specified version of the document with the response content type set to “image/png”.
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 and absolute maximum per page 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

Document Events

Allows logging and retrieving of the document distribution events.

Events Metadata

Determine Event Types

Endpoint: /api/{version}/metadata/objects/documents/events
Method: GET
Since Version: v6.0
Request:
{version} – API Version (e.g. v6.0)
Response: A list of events, and event types per each event if applicable. If the user is not permitted to access the event data, the event type is omitted from the response.

Determine Common Event Type Metadata & Defined Subtypes

Endpoint: /api/{version}/metadata/objects/documents/events/{event type}
Method: GET
Since Version: v6.0
Request:
{version} – API version (e.g. v6.0)
{event type} – one of the event types as returned by the “Determine Event Types” metadata
Response: This API will return all metadata for the specified event type. If event subtypes are defined for the event type, the subtypes will also be included

Events Data

Retrieve Document Events of Specific Type

Endpoint: /objects/documents/{id}/events
Method: GET
Since Version: v6.0
Request:
{version) – API version
{id} – the document id
Query string:

• property names and associated values to filter the response
  • any queryable property can be specified (or combination of queryable properties)
  • example: specifying “event_type__v=Distribution” will return only distribution events, event_type__v=Distribution and “event_subtype__v=Approved Email View” will return only distribution events generated for/by approved email view
• startDate and endDate to specify date range filtering
  • example: the date can be specified in UTC including the time part, although the time part is optional. If time part is not included a midnight on the specified date is assumed.
• limit and start parameters for paging

Response: A list of event objects, each containing the properties as defined by the metadata for its event type. Null and/or false valued properties are omitted from the response. The response is an array enclosed in events object. By default 200 records is returned, however this can be overwritten by specifying an alternative value in the limit parameter.

Log an Event of Specific Type, Subtype, and Classification

Endpoint: /objects/documents/{id}/versions/{maj}/{min}/events
Method: POST
Since Version: v6.0
Request:
Path Parameters:
{version} – API version
{id} – document ID
{maj} – major document version number
{min} – minor document version number
Body Parameters:
The body contains POST data (name/value pairs) consisting of all required properties and values for the event type specified by the path parameters. The required properties are obtained from the metadata API for the event type/subtype. Labels or keys are used for event_type__v, event_subtype__v properties and classification__v.
Response:
- On successful event creation, “SUCCESS” message is returned.
- On failed event creation, “FAILURE” message is returned alongside appropriate error:

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

Initiate Lifecycle Action

Get Lifecycle Actions Available to Be Initiated on the Document or a Binder

Determines which lifecycle actions are available to the current user on a documented or a binder specified by its ID and the version information. This version of the API supports initiating the following three lifecycle actions: Start Workflow, Change State, Obtain a Controlled Copy

End Point URL: /api/{version}/objects/documents/{id}/versions/{major}/{minor}/lifecycle_actions or /api/{version}/objects/binders/{id}/versions/{major}/{minor}/lifecycle_actions
HTTP Method: GET
Since Version: v6.0
Request Parameters: None
{version} – API version number (e.g. v6.0)
{id} – Document/Binder ID
{major} – major version of the document/binder
{minor} – minor version of the document/binder

Response: Returns a list of lifecycle actions which can be initiated by the current user on the document or the binder specified by its ID and version.

lifecycle_actions__v: [array] Contains a list of lifecycle actions available to be started
name__v: [string] The public key for the action
label__v: [string] The user friendly label for the action
lifecycle_action_type__v: [string] The Lifecycle Action type: workflow, stateChange or controlledCopy
entry_requirements__v: [url] The entry requirements URL where required properties to start a lifecycle action can be obtained. If no entry requirements exist, no URL is provided

 

Determine Entry Requirements for Lifecycle Action Initiation

Analyzes which data is required to initiate a lifecycle action on a document or a binder. Returns all the properties that are required. For the properties which are already set, provides a current value

End Point URL:
/api/{version}/objects/documents/{id}/versions/{major}/{minor}/lifecycle_actions/{lifecycle_action}/entry_requirements or /api/{version}/objects/binders/{id}/versions/{major}/{minor}/lifecycle_actions/{lifecycle_action}/entry_requirements

HTTP Method: GET
Since Version: v6.0
Request Parameters: None
{version} – API version number (e.g. v6.0)
{id} – Document/Binder ID
{lifecycle_action} – Lifecycle action public key (name__v) available from /api/{version}/objects/documents/{id}/versions/{major}/{minor}/lifecycle_actions or /api/{version}/objects/binders/{id}/versions/{major}/{minor}/lifecycle_actions call
{major} – major version of the document/binder
{minor} – minor version of the document/binder

Response: Returns a list of metadata elements describing the properties for which values need to be specified in the “Initiate a Lifecycle Action…” API call. If the property is already set, the currently set value is returned as well. The properties are clearly distinguished between document/binder properties, workflow activation (WAD) properties (in case an action is a workflow), or a controlled copy request properties.

The metadata fields used to describe each property are as follows:

Metadata Field	Description
name	[string] public key
description	[string] User visible property label
type	[string] Data type can be one of: string, number, boolean, ObjectReference, Picklist, Date
objectTypeReferenced	[string] Used if type is ObjectReferece and specifies the type of object
required	[boolean] Indicates whether the property is required
editable	[boolean] Indicates whether the property is editable
repeating	[boolean] Indicates whether the property contains a lsit
minValue	[number] Minimum length
maxValue	[number] Maximum length
scope	[string] Property scope can be on of: Document, Binder, Workflow, ControlledCopy
values	[array] A list of selectable values (objects)
currentSetting	[object] The value currently set on the property

 

Initiate a Lifecycle Action

Initiates a specified lifecycle action (e.g. workflow or a state change) on a document or a binder on user’s behalf.

End Point URL:
/api/{version}/objects/documents/{id}/versions/{major}/{minor}/lifecycle_actions/{lifecycle_action} or /api/{version}/objects/binders/{id}/versions/{major}/{minor}/lifecycle_actions/{lifecycle_action}

HTTP Method: PUT
Since Version: v6.0
Request Parameters:
{version} – API version number (e.g. v6.0)
{id} – Document/Binder ID
{lifecycle_action} – Lifecycle Action public key (name__v) available from /api/{version}/objects/documents/{id}/versions/{major}/{minor}/lifecycle_actions or /api/{version}/objects/binders/{id}/versions/{major}/{minor}/lifecycle_actions call.
{major} – major version of the document/binder
{minor} – minor version of the document/binder

Request: For workflow and controlledCopy lifecycle actions, the body of the request shall contain name-value pairs consisting of the workflow activation properties and the corresponding values. (The workflow activation and controlledCopy properties are returned by GET /api/{version}/objects/documents/{id}/versions/{major}/{minor}/lifecycle_actions/{lifecycle_action}/entry_requirements for documents or  /api/{version}/objects/binders/{id}/versions/{major}/{minor}/lifecycle_actions/{lifecycle_action}/entry_requirements for binders). When user/group values are needed to be passed, the following format is used: user:12,user:23,user:34, group:34,group:23,group:12.

NOTE: If document/binder properties need to be set or updated as part of initiating the lifecycle, the Update Document API or Update Binder Properties API need to be used before this call.

Response: The successful lifecycle action initiation will return the “SUCCESS” code and the ID of the document or the binder affected by the transaction.

Errors:

Type	Description
PARAMETER_REQUIRED	This error is returned when the required properties is not provided in the request.
INVALID_DATA	This error is returned when the property value provided is invalid.
INSUFFICIENT_ACCESS	This error is returned when the user doesn’t have sufficient permission to start the Lifecycle Action
OPERATION_NOT_ALLOWED	The error is returned when the Lifecycle Action can’t be started as it is not available for the document or the binder

 

 

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, latest v7.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.

Optional Query Parameters
async - [boolean] false by default, if set to true, causes the metadata to be indexed asynchronously

Response: On success the id of the newly created binder document will be returned.
Error Conditions: Refer to Errors section.
v7.0 Notes: asynchronous metadata indexing supported

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:

Create Draft

End Point URL: /api/{version}/objects/binders/{id}
Where:
{id} - is a valid binder id
HTTP Method: POST
Since Version: v7.0
Request Parameters: None
Response: On success the response contains the major and minor versions of the newly created binder draft.
Error Conditions: Refer to Errors section.

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.

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.
• 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_id__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 – v7.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

Creates a new user in the Domain and/or the current Vault instance.

End Point URL: /api/{version}/objects/users
HTTP Method: POST
Since Version: v1.0, latest – v7.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, only those that marked as required=true must be set.  To upload a profile picture file use multi-part attachment with the file component named “file”.

Domain Level User Management

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

Property	Description
user_name__v	The user’s Vault username in the given Vault domain formatted as email address
user_first_name__v	The user’s first name
user_last_name__v	The user’s last name
user_email__v	The user’s email address
user_timezone__v	The user’s timezone. The valid values are included in the output of the User metadata API
user_locale__v	The user’s locale. The valid values are included in the output of the User metadata API
user_language__v	The user’s language. The valid values are included in the output of the User metadata API
user_title__v	The user’s title
office_phone__v	The user’s office phone number
fax__v	The user’s fax number
mobile_phone__v	The user’s mobile number
company__v	The user’s company name
site__v	The user’s site/location
is_domain_admin__v	Wether user is a domain admin
active__v	[default: true] Whether the user is active in the current Vault instance (required when creating user in Vault instance)
domain_active__v	Whether the user is active in the domain
security_policy_id__v	The user’s security policy. The valid values are included in the output of the Security Policy Retrieval API
user_type_id__v	[default: 2, Document User] The user’s user type ID in the current Vault instance. The valid values are included in the output of the User metadata API (required when creating user in Vault instance)
domain_id__v	The ID of the domain the user is a member of
vault_id__v	Contains a list of Vault instances the user is a member of (available to admin users only)
group_id__v	Contains a list of groups the user is a member of
user_needs_to_change_password__v	Whether user needs to change their password on next login
federated_id__v	The user’s federated ID to be used in SAML Single Sign-on scenario
salesforce_user_name__v	The user’s Salesforce.com username to be used in Salesforce Delegated Auth scenario

Response: on success the id of the newly created user will be returned
Error Conditions: Refer to Errors section.
Notes: v7.0 – added Domain-level properties

Retrieve Users

Retrieves users in the current Vault instance. Allows Administrators to access users’ information across the Domain. Allows Domain Administrators to access users’ Vault membership information across the Domain.

End Point URL: /api/{version}/objects/users
HTTP Method: GET
Since Version: v1.0, latest – v7.0
Request Parameters:

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

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

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

Response: Contains the properties of all the users

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

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

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

Error Conditions: Refer to Errors section.
Notes: v7.0 – added support for accessing the user information across the domain for Administrators.

Retrieve User

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

Update User

Updates the user record in the Domain and/or the current Vault instance.

End Point URL: /api/{version}/objects/users/{id}
{id} - is a valid user ID
HTTP Method: PUT
Since Version: v1.0, latest – v7.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.

Domain Level User Management

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

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

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

user_email__v - should include the domain; ex. apiuser@veevavault.com
user_locale__v - valid values included in the metadata
user_language__v - valid values included in the metadata
company__v – user’s company name
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
federated_id__v - applicable to single sign-on setup with SAML
salesforce_user_name__v - applicable to delegated auth with Salesforce.com

Response: on success the id of the updated user will be returned
Error Conditions: Refer to Errors section.

Disable User

Disables the user in the Domain or the current Vault instance. By default the user is disabled at Vault instance.

The Domain Administrator users can optionally disable the user at the Domain level, affecting user’s status in every Vault in the domain.

End Point URL: /api/{version}/objects/users/{id}
{id} - is a valid user ID
HTTP Method: DELETE
Since Version: v1.0, latest v7.0
Request Parameters:

domain – [boolean, optional, default: false] if true, will cause the API to disable the user at the domain leve

Response: on success the ID of the disabled user will be returned
Error Conditions: Refer to Errors section.

Change Password

Allows the API user to change their own password.

End Point URL: /api/{version}/objects/users/{id}/password
{id} - is a valid user ID
HTTP Method: POST
Since Version: v7.0
Request Parameters:
password__v – current password – [required]
new_password__v – new password – [required]

Error Conditions: In addition to the errors described in the Errors section, the following API-specific errors could occur:

Type	Description
INSUFFICIENT_ACCESS	User attempted to change someone else’s password
PARAMETER_REQUIRED	The required parameter was not specified.
INVALID_DATA	User has typed a password that doesn’t validate against Vault validation rules User has typed a new password that is the same as the old password The user had specified an invalid password__v for their account

Update Vault Membership

Allows the Administrator to manage user’s Vault membership in the domain. Through this API it is possible to:

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

End Point URL: /api/{version}/objects/users/{id}/vault_membership/{vaultId}
{id} - is a valid user ID
{vaultId} – is a valid Vault instance ID

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

user_type_id__v -  [optional, default: 2, Document User] The user’s user type ID in the specified Vault instance. The valid values are included in the output of the User metadata API
active__v - [optional default: true] Whether the user is active in the specified Vault instance

Error Conditions: In addition to the errors described in the Errors section, the following API-specific errors could occur:

Type	Description
INSUFFICIENT_ACCESS	A non-Domain Admin user is updating a domain user in Vault they don’t have access to A non-admin user is attempting to access this endpoint
OPERATION_NOT_ALLOWED	A Domain Admin is attempting change user type for another domain admin user A Domain Admin user is attempted to be deactivated
INVALID_DATA	User is providing an invalid value for user type

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.
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, POST
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, document relationships, document events, users, and workflow objects. The general query syntax and operators work across all four 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 documents, relationships, 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 the queryable 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.

Relationships
The properties available to query on the relationships object will have queryable attribute set to TRUE in the relationships metadata. Use the Relationships Metadata API for a specific document type to confirm the relationship properties available to query interface:

End Point URL: /api/{version}/metadata/objects/documents/types/{type}/relationships

Document Events
The properties available to query on the events object will have queryable attribute set to TRUE in the events metadata. Use the Events Metadata API for a specific event type to confirm the events properties available to query interface:

End Point URL: /api/{version}/metadata/objects/documents/events/{event type}

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.
RACE_CONDITION	A rare condition where the same record is being simultaneously updated by another API call.
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.