Vault Query Language (VQL) provides SQL-like query capabilities for accessing and retrieving Vault data. Supports SELECT, FROM, WHERE, ORDER BY, relationship queries, and functions for querying documents, objects, users, workflows, and system data.
openapi: 3.1.0
info:
title: Veeva Vault REST API
description: >-
Veeva Vault provides life sciences cloud platform APIs for regulatory document
management, quality management (QMS), clinical operations, and commercial content
management. REST APIs enable document lifecycle management, workflow automation,
object CRUD operations, and compliance-validated data exchange. API version v25.3.
version: "25.3"
contact:
name: Veeva Developer Support
url: https://developer.veevavault.com/
license:
name: Veeva Vault Terms of Service
url: https://www.veeva.com/legal/
servers:
- url: https://{vaultDomain}/api/v25.3
description: Veeva Vault API
variables:
vaultDomain:
description: Your Vault domain (e.g., myvault.veevavault.com)
default: myvault.veevavault.com
security:
- VaultSession: []
tags:
- name: Authentication
description: Session management
- name: Documents
description: Document lifecycle management
- name: Objects
description: Vault object CRUD operations
- name: Query
description: VQL query execution
- name: Users
description: User management
- name: Workflows
description: Workflow and task management
paths:
/auth:
post:
operationId: authenticateUser
summary: Veeva Authenticate and Obtain Session ID
description: >-
Authenticates a user with username and password and returns a session ID
for use in subsequent API requests. Session IDs are included in the
Authorization header for all API calls.
tags:
- Authentication
security: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- username
- password
properties:
username:
type: string
description: Vault username (email address)
password:
type: string
format: password
vaultDNS:
type: string
description: Target Vault DNS (for multi-vault environments)
examples:
AuthenticateUserRequestExample:
summary: Default authenticateUser request
x-microcks-default: true
value:
username: [email protected]
password: SecureP@ssword123
vaultDNS: myvault.veevavault.com
responses:
'200':
description: Authentication successful
content:
application/json:
schema:
$ref: '#/components/schemas/AuthResponse'
examples:
AuthenticateUser200Example:
summary: Default authenticateUser 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
sessionId: A8E4F3B2C1D0E9F8A7B6C5D4E3F2A1B0
userId: 12345
vaultId: 1001
vaultIds:
- id: 1001
name: My Vault
url: https://myvault.veevavault.com
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/objects/documents:
get:
operationId: listDocuments
summary: Veeva List All Documents
description: >-
Returns a list of all documents accessible to the authenticated user.
Supports filtering by document type, lifecycle state, and custom fields.
tags:
- Documents
parameters:
- name: limit
in: query
schema:
type: integer
default: 200
maximum: 1000
- name: offset
in: query
schema:
type: integer
default: 0
- name: sort
in: query
schema:
type: string
example: "name__v asc"
responses:
'200':
description: Document list
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentListResponse'
examples:
ListDocuments200Example:
summary: Default listDocuments 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
documents:
- document:
id: 100001
name__v: Study Protocol v1.0
type__v: study_protocol__c
lifecycle__v: general_lifecycle__c
status__v: approved__c
major_version_number__v: 1
minor_version_number__v: 0
size: 1
start: 0
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createDocument
summary: Veeva Create a Document
description: >-
Creates a new document record in Vault. Optionally uploads a file as the
document source file in the same request using multipart/form-data.
tags:
- Documents
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- name__v
- type__v
- lifecycle__v
properties:
name__v:
type: string
description: Document name
type__v:
type: string
description: Document type API name
example: "study_protocol__c"
lifecycle__v:
type: string
description: Document lifecycle API name
example: "general_lifecycle__c"
status__v:
type: string
description: Initial lifecycle state
example: "draft__v"
file:
type: string
format: binary
description: Source file (optional)
description__v:
type: string
study__v:
type: string
description: Study object reference
examples:
CreateDocumentRequestExample:
summary: Default createDocument request
x-microcks-default: true
value:
name__v: Study Protocol Amendment 1
type__v: study_protocol__c
lifecycle__v: general_lifecycle__c
status__v: draft__v
description__v: Protocol amendment for Phase 2 study
responses:
'200':
description: Document created
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentCreateResponse'
examples:
CreateDocument200Example:
summary: Default createDocument 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
id: 100002
external_id__v: PROT-2025-001
major_version_number__v: 0
minor_version_number__v: 1
'400':
description: Validation error
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/objects/documents/{documentId}:
get:
operationId: getDocument
summary: Veeva Retrieve a Document
description: Returns metadata and properties for a specific document.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/DocumentId'
responses:
'200':
description: Document metadata
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentResponse'
examples:
GetDocument200Example:
summary: Default getDocument 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
document:
id: 100001
name__v: Study Protocol v1.0
type__v: study_protocol__c
lifecycle__v: general_lifecycle__c
status__v: approved__c
major_version_number__v: 1
minor_version_number__v: 0
created_by__v: 12345
created_date__v: '2025-03-15T10:30:00Z'
versions:
- number: '1.0'
value: https://myvault.veevavault.com/api/v25.3/objects/documents/100001/versions/1/0
'404':
description: Document not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateDocument
summary: Veeva Update Document Metadata
description: Updates document field values. Does not replace the document file.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/DocumentId'
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
additionalProperties:
type: string
description: Document field name-value pairs
examples:
UpdateDocumentRequestExample:
summary: Default updateDocument request
x-microcks-default: true
value:
description__v: Updated protocol description
status__v: approved__c
responses:
'200':
description: Document updated
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentUpdateResponse'
examples:
UpdateDocument200Example:
summary: Default updateDocument 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
id: 100001
major_version_number__v: 1
minor_version_number__v: 1
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteDocument
summary: Veeva Delete a Document
description: Deletes a document and all versions.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/DocumentId'
responses:
'200':
description: Document deleted
content:
application/json:
schema:
$ref: '#/components/schemas/VaultResponse'
examples:
DeleteDocument200Example:
summary: Default deleteDocument 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
id: 100001
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/objects/documents/{documentId}/file:
get:
operationId: downloadDocumentFile
summary: Veeva Download Document Source File
description: Downloads the source file for the latest version of a document.
tags:
- Documents
parameters:
- $ref: '#/components/parameters/DocumentId'
responses:
'200':
description: Document file binary
content:
application/octet-stream:
schema:
type: string
format: binary
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/objects/documents/{documentId}/actions/{actionName}:
post:
operationId: performDocumentAction
summary: Veeva Perform a Document Lifecycle Action
description: >-
Executes a user action on a document to change its lifecycle state.
Common actions include Approve, Submit for Review, Send to Archive.
tags:
- Documents
- Workflows
parameters:
- $ref: '#/components/parameters/DocumentId'
- name: actionName
in: path
required: true
description: Lifecycle action API name
schema:
type: string
example: "Approve"
responses:
'200':
description: Action performed
content:
application/json:
schema:
$ref: '#/components/schemas/VaultResponse'
examples:
PerformDocumentAction200Example:
summary: Default performDocumentAction 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
id: 100001
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vobjects/{objectName}:
get:
operationId: listObjectRecords
summary: Veeva List Vault Object Records
description: >-
Returns records for a Vault object. Vault objects are configurable
business entities (studies, products, sites, etc.).
tags:
- Objects
parameters:
- name: objectName
in: path
required: true
description: Vault object API name
schema:
type: string
example: "study__v"
- name: limit
in: query
schema:
type: integer
default: 200
- name: offset
in: query
schema:
type: integer
default: 0
- name: fields
in: query
description: Comma-separated list of field names to return
schema:
type: string
responses:
'200':
description: Object records
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectListResponse'
examples:
ListObjectRecords200Example:
summary: Default listObjectRecords 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
data:
- id: 0VO000000000001
name__v: STUDY-001
status__v: active__c
size: 1
start: 0
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createObjectRecord
summary: Veeva Create a Vault Object Record
description: Creates a new record for the specified Vault object.
tags:
- Objects
parameters:
- name: objectName
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: true
description: Object field values keyed by API name
examples:
CreateObjectRecordRequestExample:
summary: Default createObjectRecord request
x-microcks-default: true
value:
name__v: STUDY-002
status__v: active__c
therapeutic_area__c: Oncology
responses:
'200':
description: Record created
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectCreateResponse'
examples:
CreateObjectRecord200Example:
summary: Default createObjectRecord 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
id: 0VO000000000002
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vobjects/{objectName}/{recordId}:
get:
operationId: getObjectRecord
summary: Veeva Get a Vault Object Record
description: Returns a single record for a Vault object.
tags:
- Objects
parameters:
- name: objectName
in: path
required: true
schema:
type: string
- name: recordId
in: path
required: true
schema:
type: string
responses:
'200':
description: Object record
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectRecordResponse'
examples:
GetObjectRecord200Example:
summary: Default getObjectRecord 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
data:
id: 0VO000000000001
name__v: STUDY-001
status__v: active__c
therapeutic_area__c: Oncology
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateObjectRecord
summary: Veeva Update a Vault Object Record
description: Updates fields on an existing Vault object record.
tags:
- Objects
parameters:
- name: objectName
in: path
required: true
schema:
type: string
- name: recordId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: true
examples:
UpdateObjectRecordRequestExample:
summary: Default updateObjectRecord request
x-microcks-default: true
value:
status__v: inactive__c
responses:
'200':
description: Record updated
content:
application/json:
schema:
$ref: '#/components/schemas/VaultResponse'
examples:
UpdateObjectRecord200Example:
summary: Default updateObjectRecord 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteObjectRecord
summary: Veeva Delete a Vault Object Record
description: Deletes a specific Vault object record.
tags:
- Objects
parameters:
- name: objectName
in: path
required: true
schema:
type: string
- name: recordId
in: path
required: true
schema:
type: string
responses:
'200':
description: Record deleted
content:
application/json:
schema:
$ref: '#/components/schemas/VaultResponse'
examples:
DeleteObjectRecord200Example:
summary: Default deleteObjectRecord 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/query:
get:
operationId: executeVQLQuery
summary: Veeva Execute a VQL Query
description: >-
Executes a Vault Query Language (VQL) query to retrieve data from documents,
objects, users, and system data. Supports SELECT, FROM, WHERE, ORDER BY,
FIND, and relationship traversal.
tags:
- Query
parameters:
- name: q
in: query
required: true
description: VQL query string
schema:
type: string
example: "SELECT id, name__v, status__v FROM documents WHERE type__v = 'study_protocol__c'"
responses:
'200':
description: Query results
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
examples:
ExecuteVQLQuery200Example:
summary: Default executeVQLQuery 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
responseDetails:
limit: 200
offset: 0
size: 2
total: 2
data:
- id: 100001
name__v: Study Protocol v1.0
status__v: approved__c
- id: 100002
name__v: Study Protocol Amendment 1
status__v: draft__v
'400':
description: Invalid VQL syntax
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/objects/users:
get:
operationId: listUsers
summary: Veeva List Vault Users
description: Returns all active users in the Vault.
tags:
- Users
parameters:
- name: limit
in: query
schema:
type: integer
default: 200
- name: offset
in: query
schema:
type: integer
default: 0
responses:
'200':
description: User list
content:
application/json:
schema:
$ref: '#/components/schemas/UserListResponse'
examples:
ListUsers200Example:
summary: Default listUsers 200 response
x-microcks-default: true
value:
responseStatus: SUCCESS
users:
- user:
id: 12345
user_name__v: [email protected]
user_first_name__v: John
user_last_name__v: Smith
user_email__v: [email protected]
is_active__v: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
VaultSession:
type: apiKey
in: header
name: Authorization
description: Vault Session ID from /auth endpoint
parameters:
DocumentId:
name: documentId
in: path
required: true
description: Vault document ID
schema:
type: integer
example: 12345
schemas:
AuthResponse:
type: object
properties:
responseStatus:
type: string
example: "SUCCESS"
sessionId:
type: string
description: Session ID for Authorization header
userId:
type: integer
vaultId:
type: integer
vaultIds:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
url:
type: string
DocumentListResponse:
type: object
properties:
responseStatus:
type: string
documents:
type: array
items:
type: object
properties:
document:
$ref: '#/components/schemas/DocumentFields'
size:
type: integer
start:
type: integer
DocumentCreateResponse:
type: object
properties:
responseStatus:
type: string
id:
type: integer
description: New document ID
external_id__v:
type: string
major_version_number__v:
type: integer
minor_version_number__v:
type: integer
DocumentUpdateResponse:
type: object
properties:
responseStatus:
type: string
id:
type: integer
major_version_number__v:
type: integer
minor_version_number__v:
type: integer
DocumentResponse:
type: object
properties:
responseStatus:
type: string
document:
$ref: '#/components/schemas/DocumentFields'
versions:
type: array
items:
type: object
properties:
number:
type: string
value:
type: string
format: uri
DocumentFields:
type: object
description: Document field values (field names end in __v for standard, __c for custom)
properties:
id:
type: integer
name__v:
type: string
type__v:
type: string
subtype__v:
type: string
classification__v:
type: string
lifecycle__v:
type: string
status__v:
type: string
created_by__v:
type: integer
last_modified_by__v:
type: integer
created_date__v:
type: string
format: date-time
last_modified_date__v:
type: string
format: date-time
major_version_number__v:
type: integer
minor_version_number__v:
type: integer
document_number__v:
type: string
description__v:
type: string
size__v:
type: integer
format__v:
type: string
additionalProperties: true
ObjectListResponse:
type: object
properties:
responseStatus:
type: string
data:
type: array
items:
type: object
additionalProperties: true
size:
type: integer
start:
type: integer
ObjectCreateResponse:
type: object
properties:
responseStatus:
type: string
id:
type: string
ObjectRecordResponse:
type: object
properties:
responseStatus:
type: string
data:
type: object
additionalProperties: true
QueryResponse:
type: object
properties:
responseStatus:
type: string
responseDetails:
type: object
properties:
limit:
type: integer
offset:
type: integer
size:
type: integer
total:
type: integer
url:
type: string
format: uri
data:
type: array
items:
type: object
additionalProperties: true
UserListResponse:
type: object
properties:
responseStatus:
type: string
users:
type: array
items:
type: object
properties:
user:
type: object
properties:
id:
type: integer
user_name__v:
type: string
user_first_name__v:
type: string
user_last_name__v:
type: string
user_email__v:
type: string
format: email
user_timezone__v:
type: string
user_locale__v:
type: string
is_active__v:
type: boolean
VaultResponse:
type: object
properties:
responseStatus:
type: string
enum: [SUCCESS, FAILURE]
id:
type: integer
errors:
type: array
items:
type: object
properties:
type:
type: string
message:
type: string
ErrorResponse:
type: object
properties:
responseStatus:
type: string
example: "FAILURE"
errors:
type: array
items:
type: object
properties:
type:
type: string
message:
type: string