API Reference (v16.0 GA)

This is the documentation for Vault API v16.0 GA.

We recommend using a newer version of the API.

For general information on Vault, refer to Vault Help.

General Information

Authentication

Authentication calls are how you gain access to a vault through the API. The following methods are supported:

Username & Password Authentication
SAML Single Sign-on (SSO) Authentication
Salesforce Delegated Authentication

The authentication call response includes an authentication token which is valid for the current session and will "time-out" after a period of idle time. The token must be included with the HTTP Authorization request header with each subsequent request. In the examples shown here, the token is indicated by {SESSION_ID}. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/{version}/objects/documents

$ curl -X GET -H "Authorization: 3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B" \ 
https://myvault.veevavault.com/api/{version}/objects/documents

Alternatively, you can include the auth request parameter set to the {SESSION_ID}. This is used instead of the Authorization header. For example:

$ curl -X GET https://myvault.veevavault.com/api/{version}/objects/documents?auth=3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B

Note that if a request includes both the auth parameter and the Authorization header, the auth parameter is used.

History

v1+ - Supports Username & Password Authentication
v5+ - Supports Salesforce Delegated Authentication
v12+ - Supports SAML Single Sign-On (SSO) Authentication

Security

Vault's API respects the security profiles and permission sets assigned to each user. To use the API, users be assigned a permission set which allows API access. These include All API, Metadata API, Access API, and Events API access. Additionally, users can only access vaults, documents, binders, objects, etc., to which they have been assigned permission. Most of these items include individual permissions for Read, Create, Edit, Delete, and others.

When an API user submits a GET request, the response will only include data which they are allowed to view, even if additional data is available. For requests which the user is not allowed to perform, an INSUFFICIENT_ACCESS error is returned. Learn about Authentication & Vault Security in Vault Help.

HTTP Methods

Vault API uses the POST, GET, PUT, and DELETE HTTP methods.
These correspond to Create, Retrieve (Read), Update, and Delete (or CRUD) operations, respectively.

API Versions

Retrieve all supported versions of the Vault API.

Request

Send GET to /api

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com.veevavault.com/api/

Response

{
    "responseStatus": "SUCCESS",
    "values": {
        "v15.0": "https://myvault.veevavault.com/api/v15.0",
        "v16.0": "https://myvault.veevavault.com/api/v16.0",
        "v17.1": "https://myvault.veevavault.com/api/v17.1"
    }
}

Details

New versions of the API are released every 3 to 4 months and with each new version, a corresponding API Reference (this document) is published on this site. When making API calls to your vault, you may use any version by specifying the api/{version}/... in the request endpoint. Later versions include additional endpoints, parameters, metadata, and options.

When making API calls, make sure you're referring to the same API Reference as the version specified in your requests.

The last version listed in the response is the latest API Beta version.

History

Since v1

Response Formats

Vault's API supports JSON (default), XML, and (with some requests) CSV response formats. The available response format options are listed in the Headers section of each request. If no particular format is requested, the response is JSON.

To request a different format, set the HTTP request header Accept to application/xml (always available) or text/csv (when available). For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
-H "Accept: application/xml" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
-H "Accept: text/csv" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents

Alternatively, you can include the format request parameter set to xml. This is used instead of the Accept header. For example:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents?format=xml

Note that if a request includes both the format parameter and the Accept header, the format parameter is used.

All responses include a responseStatus with a SUCCESS or FAILURE value. For values other than SUCCESS, the response includes an errors key/value array with an error type and message. These provide key information regarding the reason for the error. If there are no errors, errors is either absent from the response or has an empty value. Many requests documented here include a Details and Errors section which provide additional response information specific to the request.

There is a third responseStatus with an EXCEPTION value. These are returned for API system-level errors. The response format for system-level errors is always JSON.

See the API Errors section below for additional information.

Domain Information

Domain Admins can use this request to retrieve a list of all vaults currently in their domain.

Request

Send GET to /api/{version}/objects/domain

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/domain

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "domain__v": {
    "domain_name__v": "veevapharm",
    "domain_type__v": "testvaults",
    "vaults__v": [
      {
        "id": "2000",
        "vault_name__v": "PromoMats",
        "vault_status__v": "Active",
        "vault_application__v": "PromoMats"
      },
      {
        "id": "3000",
        "vault_name__v": "MedComms",
        "vault_status__v": "Active",
        "vault_application__v": "MedComms"
      },      
      {
        "id": "4000",
        "vault_name__v": "eTMF",
        "vault_status__v": "Active",
        "vault_application__v": "eTMF"
      },      
      {
        "id": "5000",
        "vault_name__v": "QualityDocs",
        "vault_status__v": "Active",
        "vault_application__v": "QualityDocs"
      },
      {
        "id": "6000",
        "vault_name__v": "Submissions",
        "vault_status__v": "Active",
        "vault_application__v": "Submissions"
      },      
      {
        "id": "7000",
        "vault_name__v": "RIM Submissions",
        "vault_status__v": "Active",
        "vault_application__v": "RIM"
      },
      {
        "id": "8000",
        "vault_name__v": "Platform",
        "vault_status__v": "Active",
        "vault_application__v": "Base"
      }
    ]
  }
}

Details

Field Name	Description
`domain_name__v`	The name of the domain containing the vaults. This is unique to each customer and part of the DNS of each vault.
`domain_type__v`	The type of domain (Production, Sandbox, Demo, or Test).
`id`	The system-managed numeric ID assigned to each vault. This is the Vault ID (`vault_id__v`) required in some requests.
`vault_name__v`	The name of each vault. This may be the same as the application or set to something unique.
`vault_status__v`	The current status of each vault (Active or Inactive). Inactive vaults are inaccessible.
`vault_application__v`	The application of each vault (PromoMats, MedComms, eTMF, Quality Docs, Submissions, RIM Submissions, or Platform).

In the UI, this information is displayed in Admin > Settings > General Settings and Admin > Settings > Domain Information.

History

Since v7

Metadata Endpoints

Retrieve API metadata endpoints for documents, users, groups, security policies, and objects.

Request

Send GET to /api/{version}/metadata/objects

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/objects

Response

{
  "responseStatus": "SUCCESS",
  "values": {
    "documents": "https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/types",
    "users": "https://myvault.veevavault.com/api/v15.0/metadata/objects/users",
    "groups": "https://myvault.veevavault.com/api/v15.0/metadata/objects/groups",
    "securitypolicies": "https://myvault.veevavault.com/api/v15.0/metadata/objects/securitypolicies",
    "vobjects": "https://myvault.veevavault.com/api/v15.0/metadata/vobjects"
  }
}

Details

Field Name	Description
`documents`	Endpoint to retrieve a list of all document types configured in your vault. See details below.
`users`	Endpoint to retrieve a list of all user metadata configured in your vault. See details below.
`groups`	Endpoint to retrieve a list of all group metadata configured in your vault. See details below.
`securitypolicies`	Endpoint to retrieve a list of all security policy metadata configured in your vault. See details below.
`vobjects`	Endpoint to retrieve a list of all standard and custom Vault Objects configured in your vault. See details below.

History

Since v1

API Limits

Vault imposes a limit to the number of API calls that can occur within a 24-hour period (Daily Limit) and within a 5-minute period (Burst API Limit). The default limits are quite high, but if they are exceeded, Vault no longer accepts API calls until enough time has passed so that the number of calls falls below the limit. The limits are configured on each individual vault in a domain.

The default limit every 5 minutes is 2000 calls.
The default limit every 24 hours is 100,000 calls.

As of API v14.0, the header of each response includes the number of calls remaining for the daily and burst limits. For example:

Cache-Control → private, no-store
Connection → Keep-Alive
Content-Encoding → gzip
Content-Language → en-US
Content-Type → application/json;charset=UTF-8
Date → Wed, 02 Mar 2016 22:20:55 GMT
Expires → Thu, 01 Jan 1970 00:00:00 GMT
Keep-Alive → timeout=15, max=100
Server → Apache/2.2.27 (Unix)
Transfer-Encoding → chunked
Vary → Accept-Encoding
X-VaultAPI-BurstLimitRemaining → 1999
X-VaultAPI-DailyLimitRemaining → 99967
X-VaultAPI-ExecutionId → http-DEV-7674-3

Vault automatically sends a notification to all users with system notifications enabled whenever the API limit is exceeded. Admins can also set up "threshold" limits to notify users when the daily API count is close to the limit. Learn more in Vault Help.

Retrieve Limits on Vault Objects

Vault limits the number of object records that can be created for each object (product__v, study__v, custom_object__c, etc.). There is also a limit to the number of custom objects that can be created in each vault. To retrieve these limits:

Request

Send GET to /api/{version}/limits

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/limits

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "name": "records_per_object",
      "max": 1000000
    },
    {
      "name": "custom_objects",
      "remaining": 7,
      "max": 20
    }
  ]
}

Details

Field Name	Description
`records_per_object`	The maximum number of records that can be created per object in the vault.
`custom_objects`	The maximum number of custom objects that can be created in the vault and the number remaining.

History

Since v14

Documents

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 APIs allow you to query the vault to understand what document-based metadata is available to use. Learn about Documents & Binders in Vault Help.

Vault Document Metadata

Retrieve all standard and custom document metadata fields in a vault by sending GET to /api/{version}/metadata/objects/documents/properties. See request details below.

The tables below describe document metadata in API v15.0.

Document Fields (General)
Document Date & DateTime Fields
Document User Fields
Document Role Fields
Document Annotation Fields
CrossLink Document Fields
Document Field Types
Metadata Fields (Properties)

Additionally, the sections below describe:

About Document Lookup Fields
About Document Archive

Note that the lists of document fields below does not include custom fields or standard fields existing only in specific vault applications and integrations. Use the Document Metadata API to retrieve a complete list of fields existing in your vault.

Document Fields (General)

Field Name	Default Field Label	Field Type	Description	Required	Editable	Queryable
`id`	ID	ID	Unique document identifier (permanent). Numeric value.	System-Managed	False	True
`version_id`	Version ID	ID	Unique document version identifier (permanent). Numeric value.	System-Managed	False	True
`external_id__v`	External ID	String	Unique document identifier (user-defined). Alphanumeric value.	Configurable	True	True
`document_number__v`	Document Number	Autonumber	Unique document identifier. Alphanumeric value.	System-Managed	False	True
`md5checksum__v`	Checksum	ExactMatchString	Unique document identifier. Alphanumeric value.	System-Managed	False	True
`filename__v`	Filename	ExactMatchString	Unique document identifier. Alphanumeric value.	System-Managed	False	True
`format__v`	Format	ExactMatchString	Document format (application/pdf, image/jpeg, etc.).	System-Managed	False	True
`export_filename__v`	Export File Name	String	Document file name on export.	Configurable	True	True
`pages__v`	Pages	Number	Document page count.	System-Managed	False	True
`size__v`	Size	Number	Document size (KB).	System-Managed	False	True
`name__v`	Name	String	Document name.	True	True	True
`type__v`	Type	String	Document type.	True	False	True
`subtype__v`	Subtype	String	Document subtype.	True	False	True
`classification__v`	Classification	String	Document classification.	True	False	True
`lifecycle__v`	Lifecycle	String	Document lifecycle.	True	False	True
`major_version_number__v`	Major Version Number	Number	Given document version "1.0", the major version number is "1".	True	True	True
`minor_version_number__v`	Minor Version Number	Number	Given document version "1.0", the minor version number is "0".	True	True	True
`title__v`	Title	String	Document title.	Configurable	True	True
`description__v`	Description	String	Document description.	Configurable	True	True
`language__v`	Language	Picklist	Document language.	Configurable	True	True
`status__v`	Status	String	Document status (Draft, In Review, Approved, etc.).	False	True	True
`locked__v`	Checked Out	Boolean	Whether or not the document is "checked out" by another user.	False	False	True
`latest_version__v`	Latest Version	Boolean	Whether or not the document is the latest version	System-managed	False	True
`merge_fields__v`	Merge Fields	Boolean	Whether or not field merging is enabled on the document.	False	True	True
`copy_depth__v`	Copy Depth	Number	The number of levels in the copy hierarchy for the current document.	System-managed	False	True
`suppress_rendition__v`	Suppress Rendition	Boolean	Whether or not generation of the viewable rendition is suppressed.	System-managed	False	True
`binder__v`	Binder	Boolean	Whether or not the document is a binder.	System=managed	False	True
`binder_metadata__v`	Binder Metadata	ObjectReference	References document-binder metadata.	System-Managed	False	True
`archive__v`	Archive	Boolean	Whether or not the document has been archived. See About Document Archive below.	False	True	True
`tag__v`	Tag	Picklist	Document tags, used for searching and filtering.	Configurable	False	True

Document Date & DateTime Fields

Date fields have the following format: YYYY-MM-DD ('2014-12-20').
DateTime fields have the following format: YYYY-MM-DD'T'HH:MM:SS.SSS'Z' ('2014-12-20T15:30:00.000Z').
Date and DateTime fields are specified in UTC (Coordinated Universal Time) and not the user's time zone.

Field Name	Description	Comments
`document_creation_date__v`	Document Creation Date	When the original source document was first created.
`version_creation_date__v`	Version Creation Date	When the document version was first created.
`version_modified_date__v`	Version Modified Date	When the document version was last modified/updated.
`locked_date__v`	Document Locked Date	When the document version was locked (checked-out). See the Document Locks API below.

Document User Fields

These list key document user information. See the Users API below. Learn about Users & Groups in Vault Help.

Field Name	Description	Comments
`owner__v`	Document Owner	User `id` field value of the owner of the document.
`created_by__v`	Document Created By	User `id` field value of the person who first created the document.
`version_created_by__v`	Version Created By	User `id` field value of the person who created the retrieved version.
`last_modified_by__v`	Document Last Modified By	User `id` field value of the person who last modified/updated the document.
`locked_by__v`	Document Locked By	User `id` field value of the person who locked (checked out) the document. See the Document Locks API below.

Document Role Fields

These list the users and groups assigned to various roles on each document. Admins may create additional roles. See the Roles API below. Learn about Lifecycle Roles in Vault Help.

Field Name	Description	Comments
`viewer__v.users`	Viewer Users	User `id` values of individual users assigned the "Viewer" role on the document.
`viewer__v.groups`	Viewer Groups	Group `id` values of groups of users assigned the "Viewer" role on the document.
`reviewer__v.users`	Reviewer Users	User `id` values of individual users assigned the "Reviewer" role on the document.
`reviewer__v.groups`	Reviewer Groups	Group `id` values of groups of users assigned the "Reviewer" role on the document.
`editor__v.users`	Editor Users	User `id` values of individual users assigned the "Editor" role on the document.
`editor__v.groups`	Editor Groups	Group `id` values of groups of users assigned the "Editor" role on the document.
`approver__v.users`	Approver Users	User `id` values of individual users assigned the "Approver" role on the document.
`approver__v.groups`	Approver Groups	Group `id` values of groups of users assigned the "Approver" role on the document.
`coordinator__v.users`	Coordinator Users	User `id` values of individual users assigned the "Coordinator" role on the document.
`coordinator__v.groups`	Coordinator Groups	Group `id` values of groups of users assigned the "Coordinator" role on the document.
`consumer__v.users`	Consumer Users	User `id` values of individual users assigned the "Consumer" role on the document.
`consumer__v.groups`	Consumer Groups	Group `id` values of groups of users assigned the "Consumer" role on the document.
`distribution_contacts__v`	Distribution Contacts	User `id` values of individual users assigned the "Distribution Contacts" role on the document.

Document Annotation Fields

These list the number of annotations on a document (if any). See the Document Annotations API below. Learn about Document Annotations in Vault Help.

Field Name	Description	Comments
`annotations_all__v`	All Document Annotations	Total number of all annotation types listed below, resolved and unresolved.
`annotations_links__v`	Link Annotations	Number of link annotations on the document.
`annotations_lines__v`	Line Annotatations	Number of line annotations on the document.
`annotations_anchors__v`	Document Anchors	Number of anchor annotations on the document.
`annotations_notes__v`	Document Notes	Number of text annotations on the document.
`annotations_resolved__v`	Resolved Annotations	Number of annotations on the document which have been resolved.
`annotations_unresolved__v`	Unresolved Annotations	Number of annotations on the document which have not been resolved.

CrossLink Document Fields

These are configured with values on documents which are bound to CrossLinks or documents which are themselves CrossLinks. See the Create CrossLink Document API below. Learn about CrossLinks in Vault Help.

Field Name	Description	Comments
`crosslink__v`	CrossLink Document (true/false)	Whether or not the document is a CrossLink.
`source_document_id__v`	Source Document ID	Document `id` value of the source document in the source vault.
`source_document_name__v`	Source Document Name	Document `name__v` value of the source document in the source vault.
`source_document_number__v`	Source Document Number	`document_number__v` value of the source document in the source vault.
`source_owner__v`	Source Document Owner	Document `owner__v` value of the source document in the source vault.
`source_vault_id__v`	Source Vault ID	Vault `id` value of the vault containing the source document. Learn more.
`source_vault_name__v`	Source Vault Name	Name of the vault containing the source document.
`source_binding_rule__v`	Source Binding Rule	Binding rule applied to the CrossLink.
`bound_source_major_version__v`	Bound Source Major Version	Current major version of the source document bound to the CrossLink.
`bound_source_minor_version__v`	Bound Source Minor Version	Current minor version of the source document bound to the CrossLink.
`latest_source_major_version__v`	Latest Source Major Version	Latest major version of the source document bound the CrossLink.
`latest_source_minor_version__v`	Latest Source Minor Version	Latest minor version of the source document bound to the CrossLink.
`link_status__v`	Link Status	Whether or not the link to the source document is currently active.

Document Field Types

All standard and custom document fields are of one of the following types:

Field Type	Description
ID	Reserved for the system-managed document `id` and `version_id` fields.
Autonumber	Reserved for the system-managed `document_number__v` field.
String	Alphanumeric field that accepts any entered value up to a maximum length, including text, numbers, punctuation, and special characters.
ExactMatchString	These function just like string (text) fields, except during search. They are not tokenized like regular string fields. When searching document fields, Vault only finds matches on this field type if you enter an exact match to its value. They are also case-sensitive.
Number	Stores document number values. These adhere to minimum, maximum, and decimal precision values.
Date	Stores document date values (YYYY-MM-DD).
DateTime	Stores document date and time values (YYYY-MM-DD'T'HH:MM:SS.SSS'Z').
Picklist	Stores one or more items selected from a list of allowed values.
ObjectReference	Stores references to one or more Vault Objects, each of which have their own object fields.
Boolean	Stores "true" or "false" field values.
Formula	Stores formulas using a combination of fields, functions, constants, and math operations in an expression. These are used only in reporting and are not currently exposed in the API.
URL	Stores URL values which link to another resource.
Lookup	Stores object field lookup on the document. See About Document Lookup Fields below.

Document Metadata Fields (Properties)

The following information may be included with each field:

Metadata Field	Description	Comments
`name`	Field Name	The document field name (`name__v`, `title__v`, etc.) is the primary method of identifying fields in the API.
`label`	Field Label	The document field label (Name, Title, etc.) is the primary method of identifying fields in the UI.
`type`	Field Type	See Document Field Types above.
`required`	Required	Indicates (true/false) if the field must be configured with a value when creating a new document.
`setOnCreateOnly`	Set On Create Only	Indicates (true/false) if the field value can only be set once (when creating a new document).
`editable`	Editable	Indicates (true/false) if the field value can be set or changed by the user, i.e., not system-managed.
`systemAttribute`	System Attribute	Indicates (true/false) if the field is system-managed, i.e., not editable by the user.
`repeating`	Repeating	Indicates (true/false) if the field can have multiple values.
`queryable`	Queryable	Indicates (true/false) if the field can be used as a keyword search parameter when searching documents.
`shared`	Shared	Indicates (true/false) if the field is shared with other document types. See Retrieve Common Document Fields below.
`disabled`	Disabled	Indicates (true/false) if the field has been disabled by your Vault Admin and no longer available when creating or editing documents.
`hidden`	Hidden	Indicates (true/false) if the field is "hidden" (not available) because it is dependent on another controlling field whose conditions have not been met.
`objectType`	Object Type	When the document field `type` is `ObjectReference`, this indicates the object which is being referenced.
`minValue`	Minimum Value	When the document field `type` is `Number`, this indicates the minimum numerical value which can be used.
`maxValue`	Maximum Value	When the document field `type` is `Number`, this indicates the maximum numerical value which can be used.
`scale`	Scale	When the document field `type` is `Number`, this indicates the maximum number of decimal places (0, 1, 2, etc.) which can be used.
`maxLength`	Maximum Length	When the document field `type` is `id` or `String`, this indicates the maximum character length which can be used.
`entryLabels`	Entry Labels	When the document field `type` is `Picklist`, this indicates the available picklist values.
`scope`	Scope	Document "scope" values include `Document` and `DocumentVersion`, indicating to which the field applies.
`helpContent`	Help Content	Displays any optional "help" text describing the document field. This is displayed in the UI when users hover over the document field.
`definedInType`	Defined In Type	Indicates (true/false) if the document field is defined at the document "type", "subtype", or "classification" level.
`definedIn`	Defined In	Displays the document "type", "subtype", or "classification" on which the document field is defined.
`section`	Section	The "section" in the UI document fields layout where the field is displayed.
`sectionPosition`	Section Position	Within the section described above, this indicates the document field's "position" (numerical order from top to bottom) in the section.
`relationshipType`	Relationship Type	When the document field `type` is `ObjectReference`, this indicates the type of relationship.
`relationshipName`	Relationship Name	For the `relationshipType` described above, this indicates the "name" which is used to perform a relationship query on the document and object.
`lookupObjectField`	Lookup Object Field	On fields of `"type": "Lookup"`, displays the name of the document field pointing to the object in the lookup relationship. See About Document Lookup Fields below.
`lookupSourceField`	Lookup Source Field	On fields of `"type": "Lookup"`, displays the name of the object field being "looked-up". See About Document Lookup Fields below.

About Document Lookup Fields

Document fields of "type": "Lookup" propagate field values from a referenced object to a document. This allows users to view field values from a referenced object record in a document. Lookup fields are not editable; they simply pull information from an object record.

Lookup fields are custom document fields that are added to a document type, subtype, or classification in the Admin UI. Here's an example:

    {
      "name": "therapeutic_area__c",
      "scope": "DocumentVersion",
      "type": "Lookup",
      "required": false,
      "repeating": true,
      "systemAttribute": false,
      "editable": true,
      "setOnCreateOnly": false,
      "disabled": false,
      "label": "Therapeutic Area",
      "entryLabels": [
        "Cardiology",
        "Endocrinology",
        "Gastroenterology",
        "Hematology",
        "Immunology",
        "Neurology",
        "Gynecology",
        "Oncology",
        "Veterinary"
      ],
      "section": "generalProperties",
      "sectionPosition": 1000,
      "hidden": false,
      "queryable": true,
      "shared": false,
      "definedInType": "type",
      "definedIn": "claim__vs",
      "lookupObjectField": "product__v",
      "lookupSourceField": "therapeutic_area__vs"
    }

Note the following metadata fields and values:

"type": "Lookup" - Identifies the document field as a lookup.
"lookupObjectField": "product__v" - The name of the document field pointing to the object in the lookup relationship. This is limited to document fields whose type is "Object".
"lookupSourceField": "therapeutic_area__vs" - The name of the object field being "looked-up". This is limited to object fields whose type is "Object" or "Picklist".
"entryLabels" - The available object field values to which this lookup field can be set.
"definedIn": "claim__vs" - This lookup field is defined on all documents of the type claim__vs.

For example: When creating a document of type "Claim" and associating it with a product, Vault will automatically set the "Therapeutic Area" field on the document to that of the associated product.

Lookup-type fields are supported in v15 or later.

Learn more about Lookup Fields in Vault Help.

About Document Archive

Note: The archive__v field is currently only available in select vaults and must be enabled by Support. To use the archive action, you must be assigned the Manage Archives permission. Vault Owners and System Admins have this permission by default.

All vaults in which this feature is enabled are provisioned with a shared document field (Boolean) called "Archive" (archive__v). The field is defined on the base_document__v document type.

    {
      "name": "archive__v",
      "scope": "Document",
      "type": "Boolean",
      "required": false,
      "repeating": false,
      "systemAttribute": true,
      "editable": true,
      "setOnCreateOnly": false,
      "disabled": false,
      "label": "Archive",
      "section": "generalProperties",
      "sectionPosition": 2000,
      "hidden": false,
      "queryable": true,
      "shared": true,
      "usedIn": [
        {
          "key": "base_document__v",
          "type": "type"
        }
      ]
    }

To archive a document, set archive__v to true. For example:

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "archive__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/documents/115

On SUCCESS, all versions of the document are archived. You can archive documents using both create and update actions on single and bulk document API calls.

Retrieve Document Fields

Retrieve All Document Fields

Retrieve all standard and custom document fields and field properties.

Request

Send GET to /api/{version}/metadata/objects/documents/properties

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/properties

Response (abridged)

    {
      "name": "name__v",
      "scope": "DocumentVersion",
      "type": "String",
      "required": true,
      "maxLength": 100,
      "repeating": false,
      "systemAttribute": true,
      "editable": true,
      "setOnCreateOnly": false,
      "disabled": false,
      "label": "Name",
      "section": "generalProperties",
      "sectionPosition": 1,
      "hidden": false,
      "queryable": true,
      "shared": false,
      "helpContent": "The document name.",
      "definedInType": "type",
      "definedIn": "base_document__v"
    }
    {
      "name": "product__v",
      "scope": "DocumentVersion",
      "type": "ObjectReference",
      "required": true,
      "repeating": true,
      "systemAttribute": true,
      "editable": true,
      "setOnCreateOnly": false,
      "disabled": false,
      "objectType": "product__v",
      "label": "Product",
      "section": "productInformation",
      "sectionPosition": 1,
      "hidden": false,
      "queryable": true,
      "shared": false,
      "definedInType": "type",
      "definedIn": "base_document__v",
      "relationshipType": "reference",
      "relationshipName": "document_product__vr"
    }
    {
      "name": "document_creation_date__v",
      "scope": "Document",
      "type": "DateTime",
      "required": true,
      "repeating": false,
      "systemAttribute": true,
      "editable": false,
      "setOnCreateOnly": false,
      "disabled": false,
      "label": "Created Date",
      "section": "generalProperties",
      "sectionPosition": 18,
      "hidden": false,
      "queryable": true,
      "shared": false,
      "definedInType": "type",
      "definedIn": "base_document__v"
    }

Details

The response lists all standard and custom document fields and field metadata. Note the following field metadata:

Metadata Field	Description
`required`	When true, the field value must be set when creating new documents.
`editable`	When true, the field value can be user-defined. When false, the field value is system-managed.
`setOnCreateOnly`	When true, the field value can only be set once (when creating new documents).
`queryable`	When true, field values can be retrieved using the Query API.

History

Since v4

Retrieve Common Document Fields

Retrieve all document fields and field properties which are common to (shared by) a specified set of documents.

This allows you to determine which document fields can be updated on documents in bulk.

Learn about Shared Fields in Vault Help.

Request

Send POST to /api/{version}/metadata/objects/documents/properties/find_common

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Input

docIds - Input a comma-separated list of document id field values.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIds=101,102,103" \
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/properties/find_common

Response (abridged)

    {
      "name": "submission_date__vs",
      "scope": "DocumentVersion",
      "type": "Date",
      "required": false,
      "repeating": false,
      "systemAttribute": false,
      "editable": true,
      "setOnCreateOnly": false,
      "disabled": false,
      "label": "Submission Date",
      "section": "submissionDetails",
      "sectionPosition": 3,
      "hidden": false,
      "queryable": true,
      "shared": true,
      "usedIn": [
        {
          "key": "promotional_piece__vs",
          "type": "type"
        },
        {
          "key": "compliance_package__v",
          "type": "type"
        },
        {
          "key": "claim__vs",
          "type": "type"
        }
      ]
    }
    {
      "name": "withdrawal_effective_date__vs",
      "scope": "DocumentVersion",
      "type": "Date",
      "required": false,
      "repeating": false,
      "systemAttribute": false,
      "editable": true,
      "setOnCreateOnly": false,
      "disabled": false,
      "label": "Withdrawal Effective Date",
      "section": "pieceDetails",
      "sectionPosition": 17,
      "hidden": false,
      "queryable": true,
      "shared": false,
      "definedInType": "type",
      "definedIn": "promotional_piece__vs"
    }

Details

The response includes all fields shared by the three documents (docIds=101,102,103).

Vault allows you to reuse fields across multiple document types by creating shared fields, which exist outside the context of a document type. You can create shared fields or convert existing fields into shared fields in the Vault Admin application. If a shared field is only used in one document type, you can also convert it to a non-shared field. All document fields include the Boolean shared document field. A value of true indicates which the field is shared and the following additional fields are included:

Note the following field metadata:

Metadata Field	Description
`shared`	May be set to true or false.
`usedIn` (`key`)	When `"shared": true`, this lists the document types/subtypes/classifications which share the field.
`usedIn` (`type`)	When `"shared": true`, this indicates if the shared field is defined at the document type, subtype, or classification level.

History

Since v9

Retrieve Document Types

Document type refers both to the structure of hierarchical fields (Type > Subtype > Classification) that determines the relevant document fields, rendition types, and other settings for a document, and to the highest level in that hierarchy.

Vault Document Type API Endpoints:

Retrieve All Document Types - Retrieve all standard and custom document types.
Retrieve Document Type - Specify a document type to retrieve its metadata and subtypes.
Retrieve Document Subtype - Specify a document subtype to retrieve its metadata and classifications.
Retrieve Document Classification - Specify a document classification to retrieve its metadata.

Learn about Configuring Document Types in Vault Help.

Retrieve All Document Types

Retrieve all document types. These are the top-level of the document type/subtype/classification hierarchy.

Request

Send GET to /api/{version}/metadata/objects/documents/types

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents

Response (abridged)

{
    "responseStatus": "SUCCESS",
    "types": [
        {
            "label": "Base Document",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/base_document__v"
        },
        {
            "label": "Centralized Testing",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/centralized_testing__vs"
        },
        {
            "label": "Central Trial Documents",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/central_trial_documents__vs"
        },
        {
            "label": "Country Master File",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/country_master_file__v"
        },
        {
            "label": "Data Management",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/data_management__vs"
        },
        {
            "label": "Final CRF",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/final_crf__v"
        },
        {
            "label": "IP and Trial Supplies",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/ip_and_trial_supplies__vs"
        },
        {
            "label": "IRB/IEC and other Approvals",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/irbiec_and_other_approvals__vs"
        },
        {
            "label": "Regulatory",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/regulatory__vs"
        },
        {
            "label": "Safety Reporting",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/safety_reporting__vs"
        },
        {
            "label": "Site Management",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/site_management__vs"
        },
        {
            "label": "Site Master File",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/site_master_file__v"
        },
        {
            "label": "Statistics",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/statistics__vs"
        },
        {
            "label": "General",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/research_document__c"
        },
        {
            "label": "Third parties",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/third_parties__vs"
        },
        {
            "label": "Trial Management",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/trial_management__vs"
        },
        {
            "label": "Trial Master File",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/trial_master_file__v"
        },
        {
            "label": "Undefined",
            "value": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/undefined__v"
        }
    ],
    "lock": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/lock"
}

Details

The response lists all document types configured in the vault. These vary by vault application and configuration.

Standard types end in __v.
Some vaults include sample types __vs.
Admins can configure custom types __c.

The response includes the following information:

Metadata Field	Description
`types`	List of all standard and custom document types in your vault. These are the top-level of the document type/subtype/classification hierarchy.
`label`	Label of each document type as seen in the API and UI.
`value`	URL to retrieve the metadata associated with each document type.
`lock`	URL to retrieve the document lock metadata (document check-out).

The label is displayed in the UI. These can be applied to documents and binders.

History

Since v1

Retrieve Document Type

Retrieve all metadata from a document type, including all of its subtypes (when available).

Request

Send GET to /api/{version}/metadata/objects/documents/types/{type}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{type} - The document type. See Retrieve Document Types.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs

Response

{
  "responseStatus": "SUCCESS",
  "name": "promotional_piece__vs",
  "label": "Promotional Piece",
  "renditions": [
    "viewable_rendition__v",
    "production_proof__vs",
    "distribution_package__vs",
    "imported_rendition__vs",
    "veeva_distribution_package__vs"
  ],
  "relationshipTypes": [
    {
      "label": "CrossLink Latest Bindings",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "CrossLink Latest Steady State Bindings",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Linked Documents",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Based on",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Related Claims",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Supporting Documents",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "CrossLink Static Bindings",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Related Pieces",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    }
  ],
  "templates": [
    {
      "label": "ANSM Submission",
      "name": "ansm_submission__vs",
      "kind": "binder",
      "definedIn": "promotional_piece__vs",
      "definedInType": "type"
    }
  ],
  "availableLifecycles": [
    {
      "name": "promotional_piece__vs",
      "label": "Promotional Piece"
    }
  ],
  "subtypes": [
    {
      "label": "Advertisement",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs"
    },
    {
      "label": "Direct Mail",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/direct_mail__vs"
    },
    {
      "label": "Formulary Announcement",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/formulary_announcement__vs"
    },
    {
      "label": "Internal Communication",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/internal_communication__vs"
    },
    {
      "label": "Managed Markets Program",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/managed_markets_program__vs"
    },
    {
      "label": "Healthcare Practitioner Resources",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/healthcare_practitioner_resources__vs"
    },
    {
      "label": "Patient Education",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/patient_education__vs"
    },
    {
      "label": "Promotional Labeling",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/promotional_labeling__vs"
    },
    {
      "label": "Press Kit Material",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/press_kit_material__vs"
    },
    {
      "label": "Reminder Item",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/reminder_item__vs"
    },
    {
      "label": "Reprint",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/reprint__vs"
    },
    {
      "label": "Speaker Program Materials",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/speaker_program_materials__vs"
    },
    {
      "label": "Training Materials",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/training_materials__vs"
    },
    {
      "label": "Convention Item",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/convention_item__vs"
    }
  ]
}

Details

The response includes all metadata for the document specified type. If the type contains subtypes in the document type hierarchy, the list of subtypes and the URLs pointing to their metadata will be included in the response. If no subtypes exist in the document type hierarchy, the list of document fields defined for the specified type will be included in the response.

Each document type may include some or all of the following fields:

Metadata Field	Description
`name`	Name of the document type. Used primarily in the API.
`label`	Label of the document type as seen in the API and UI.
`renditions`	List of all rendition types available for the document type.
`relationshipTypes`	List of all relationship types available for the document type.
`processes`	List of all processes available for the document type (when configured).
`etmfDepartment`	In eTMF vaults only. List of all eTMF departments available for the document type (when configured).
`referenceModels`	In eTMF vaults only. List of all reference models available for the document type.
`defaultWorkflows`	List of all workflows available for the document type.
`availableLifecycles`	List of all lifecycles available for the document type.
`templates`	List of all templates available for the document type (when configured).
`subtypes`	List of all standard and custom document subtypes available for the document type.

History

Since v1

Retrieve Document Subtype

Retrieve all metadata from a document subtype, including all of its classifications (when available).

Request

Send GET to /api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{type} - The document type. See Retrieve Document Types.
{subtype} - The document type. See Retrieve Document Type.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "name": "advertisement__vs",
  "label": "Advertisement",
  "properties": [
    {
      "name": "id",
      "type": "id",
      "required": true,
      "maxLength": 20,
      "minValue": 0,
      "maxValue": 9223372036854775807,
      "repeating": false,
      "systemAttribute": true,
      "editable": false,
      "setOnCreateOnly": true,
      "disabled": false,
      "hidden": true,
      "queryable": true
    },
    {
      "name": "name__v",
      "scope": "DocumentVersion",
      "type": "String",
      "required": true,
      "maxLength": 100,
      "repeating": false,
      "systemAttribute": true,
      "editable": true,
      "setOnCreateOnly": false,
      "disabled": false,
      "label": "Name",
      "section": "generalProperties",
      "sectionPosition": 1,
      "hidden": false,
      "queryable": true,
      "shared": false,
      "helpContent": "The document name.",
      "definedInType": "type",
      "definedIn": "base_document__v"
    },
    {
      "name": "product__v",
      "scope": "DocumentVersion",
      "type": "ObjectReference",
      "required": true,
      "repeating": true,
      "systemAttribute": true,
      "editable": true,
      "setOnCreateOnly": false,
      "disabled": false,
      "objectType": "product__v",
      "label": "Product",
      "section": "productInformation",
      "sectionPosition": 1,
      "hidden": false,
      "queryable": true,
      "shared": false,
      "definedInType": "type",
      "definedIn": "base_document__v",
      "relationshipType": "reference",
      "relationshipName": "document_product__vr"
    },
    ...
    ...
    ...
  ],
  "classifications": [
    {
      "label": "Other Electronic",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs/classifications/other_electronic__vs"
    },
    {
      "label": "Print",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs/classifications/print__vs"
    },
    {
      "label": "Radio",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs/classifications/radio__vs"
    },
    {
      "label": "Television",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs/classifications/television__vs"
    },
    {
      "label": "Web",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs/classifications/web__vs"
    }
  ],
  "relationshipTypes": [
    {
      "label": "CrossLink Latest Bindings",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Linked Documents",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "CrossLink Latest Steady State Bindings",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Based on",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Related Claims",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Supporting Documents",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "CrossLink Static Bindings",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Related Pieces",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    }
  ],
  "templates": [
    {
      "label": "ANSM Submission",
      "name": "ansm_submission__vs",
      "kind": "binder",
      "definedIn": "promotional_piece__vs",
      "definedInType": "type"
    }
  ],
  "availableLifecycles": [
    {
      "name": "promotional_piece__vs",
      "label": "Promotional Piece"
    }
  ]
}

History

Since v1

Retrieve Document Classification

Retrieve all metadata from a document classification.

Request

Send GET to /api/{version}/metadata/objects/documents/types/{type}/subtypes/{subtype}/classifications/{classification}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{type} - The document type. See Retrieve Document Types.
{subtype} - The document type. See Retrieve Document Type.
{classification} - The document classification. See Retrieve Document Subtype.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs/classifications/print__vs

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "name": "advertisement__vs",
  "label": "Advertisement",
  "properties": [
    {
      "name": "id",
      "type": "id",
      "required": true,
      "maxLength": 20,
      "minValue": 0,
      "maxValue": 9223372036854775807,
      "repeating": false,
      "systemAttribute": true,
      "editable": false,
      "setOnCreateOnly": true,
      "disabled": false,
      "hidden": true,
      "queryable": true
    },
    {
      "name": "name__v",
      "scope": "DocumentVersion",
      "type": "String",
      "required": true,
      "maxLength": 100,
      "repeating": false,
      "systemAttribute": true,
      "editable": true,
      "setOnCreateOnly": false,
      "disabled": false,
      "label": "Name",
      "section": "generalProperties",
      "sectionPosition": 1,
      "hidden": false,
      "queryable": true,
      "shared": false,
      "helpContent": "The document name.",
      "definedInType": "type",
      "definedIn": "base_document__v"
    },
    {
      "name": "product__v",
      "scope": "DocumentVersion",
      "type": "ObjectReference",
      "required": true,
      "repeating": true,
      "systemAttribute": true,
      "editable": true,
      "setOnCreateOnly": false,
      "disabled": false,
      "objectType": "product__v",
      "label": "Product",
      "section": "productInformation",
      "sectionPosition": 1,
      "hidden": false,
      "queryable": true,
      "shared": false,
      "definedInType": "type",
      "definedIn": "base_document__v",
      "relationshipType": "reference",
      "relationshipName": "document_product__vr"
    },
    ...
    ...
    ...
  ],
  "relationshipTypes": [
    {
      "label": "CrossLink Latest Bindings",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Linked Documents",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "CrossLink Latest Steady State Bindings",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Based on",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Related Claims",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Supporting Documents",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "CrossLink Static Bindings",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    },
    {
      "label": "Related Pieces",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships"
    }
  ],
  "templates": [
    {
      "label": "ANSM Submission",
      "name": "ansm_submission__vs",
      "kind": "binder",
      "definedIn": "promotional_piece__vs",
      "definedInType": "type"
    }
  ],
  "availableLifecycles": [
    {
      "name": "promotional_piece__vs",
      "label": "Promotional Piece"
    }
  ]
}

History

Since v1

Retrieve Documents

The following rules govern document retrieval:

Vault only returns documents to which the logged in user has been given access (even if more documents exist).
Unless version operators are used, Vault only returns the latest version of each document.
Vault returns a maximum of 200 documents per page. This can be changed (lowered) using the limit operator. Learn more below.

Identifying Binders

A document pseudo-field binder__v indicates whether the returned document is a regular document or a binder.
The value of true means it is a binder, false or absence of this field means it is a document.
If it is a binder, the binder node structure is not listed as part of the response and must be determined through the appropriate Binder API call.

Identifying CrossLink Documents

A document pseudo-field crosslink__v indicates whether the returned document is a regular document or a CrossLink document.
The value of true means it is a CrossLink.

Retrieve All Documents

Retrieve the latest version of documents and binders to which you have access.

Request

Send GET to /api/{version}/objects/documents

Headers

Response Accept - JSON application/json (default) or XML application/xml

Options

Using Named Filters: You can include one of the following parameters to filter the results:

named_filter=My Documents - Retrieves only documents which you have created.
named_filter=Favorites - Retrieves all documents which you have marked as favorites in the library.
named_filter=Recent Documents - Retrieves all documents which you have recently accessed.

For example: /api/{version}/objects/documents?named_filter=My Documents

Searching Document Versions: By default, this request returns the latest version of all documents to which you have been given access. However, you can request that the search be performed across all versions of the documents by including the versionscope=all parameter. For example:

/api/{version}/objects/documents?versionscope=all

Performing Keyword Searches: You can search for documents based on keywords in searchable document fields by using the search operator. For example:

/api/{version}/objects/documents?search=hemophilia.

You can expand the search to document content by using the scope operator set to contents or all. For example:

search=hemophilia?scope=contents - Searches only within the document content.
search=hemophilia?scope=all - Searches both within the document content and searchable document fields.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "size": 69,
  "start": 0,
  "limit": 200,
  "documents": [
    {
      "document": {
        "id": 105,
        "version_id": "105_0_1",
        "binder__v": false,
        "coordinator__v": {
          "groups": [],
          "users": []
        },
        "owner__v": {
          "groups": [],
          "users": [
            25524
          ]
        },
        "approver__v": {
          "groups": [],
          "users": []
        },
        "reviewer__v": {
          "groups": [],
          "users": []
        },
        "distribution_contacts__v": {
          "groups": [],
          "users": []
        },
        "viewer__v": {
          "groups": [],
          "users": []
        },
        "consumer__v": {
          "groups": [],
          "users": []
        },
        "editor__v": {
          "groups": [],
          "users": []
        },
        "format__v": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
        "version_creation_date__v": "2016-03-23T22:03:04.094Z",
        "major_version_number__v": 0,
        "annotations_links__v": 0,
        "annotations_all__v": 2,
        "status__v": "Draft",
        "language__v": [
          "English"
        ],
        "suppress_rendition__v": "false",
        "filename__v": "cholecap_presentation_q316.pptx",
        "product__v": [
          "00P000000000101"
        ],
        "version_created_by__v": 25524,
        "country__v": [],
        "annotations_anchors__v": 0,
        "document_number__v": "PP-WD--0014",
        "minor_version_number__v": 1,
        "lifecycle__v": "Promotional Piece",
        "subtype__v": "Advertisement",
        "annotations_notes__v": 2,
        "allow_pdf_download__v": [
          "00W000000000201"
        ],
        "classification__v": "Other Electronic",
        "name__v": "CholeCap Presentation",
        "locked__v": false,
        "pages__v": 29,
        "restrict_fragments_by_product__v": true,
        "type__v": "Promotional Piece",
        "size__v": 623694,
        "md5checksum__v": "0405da0c29698e4249c2a0eca8f6642a",
        "annotations_unresolved__v": 2,
        "last_modified_by__v": 25524,
        "document_creation_date__v": "2016-03-23T22:03:04.094Z",
        "annotations_resolved__v": 0,
        "annotations_lines__v": 0,
        "version_modified_date__v": "2016-03-23T22:04:16.000Z",
        "created_by__v": 25524,
        "media__vs": [
          "Print"
        ]
      }
    },
    ...

Details

On SUCCESS, Vault lists all documents and binders along with their fields and field values.
The document metadata returned will vary based on your vault configuration.

Limit, Sort, and Paginate Results

By default, Vault returns a maximum of 200 documents per page. You can change (lower) this using the limit operator. For example, to limit the number of documents to 20 per page:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents?limit=20

The limit operator must be a positive integer. Values over 200 are ignored.

The default sort order is not based on any document field. You can change the sort parameters by including the sort operator with a field and indicating descending desc or ascending asc. For example, to sort by the name of each document in descending order:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents?sort=name__v desc

With a maximum of 200 records returned per page, you must submit a new request to see the "next page" of results (when more than 200 documents exist). Use the start operator in the same way as the limit operator above. For example, if you're viewing the first page of 200 results out of 1000 total results found and want to see the next 200 results, enter start=201.

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents?start=201

The start operator must be a positive integer. Values equaling to a number larger than the total number of documents will not return any results.

To use limit, start, and sort together, structure the string in the following manner:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents?limit=10&start=51&sort=name__v desc

The request shown above will return 10 results per page, staring with page 5 (results 51-60), and sort the results by the document name in descending order.

History

Since v1
v4+ - Supports the SCOPE request parameter.
v4+ - Response includes term highlight hints.
v5+ - Includes the binder__v true/false field to distinguish between documents and binders.
v10+ - Supports CrossLink documents.

Retrieve Document

Retrieve all metadata from a document.

Request

Send GET to /api/{version}/objects/documents/{document_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/450

Response

{
    "responseStatus": "SUCCESS",
    "document": {
        "id": 450,
        "binder__v": false,
        "allow_download_embedded_viewer__v": true,
        "reviewer__v": {
            "users": [
                25519,
                25516
            ],
            "groups": [
                1358979070034                    
            ]
        },
        "viewer__v": {
            "users": [
                25519,
                25516,
                25597
            ],
            "groups": [
                1358979070034                    
            ]
        },
        "distribution_contacts__v": {
            "users": [],
            "groups": []
        },
        "consumer__v": {
            "users": [],
            "groups": []
        },
        "approver__v": {
            "users": [
                25516
            ],
            "groups": []
        },
        "editor__v": {
            "users": [
                25519,
                25516
            ],
            "groups": []
        },
        "owner__v": {
            "users": [
                46916
            ],
            "groups": []
        },
        "coordinator__v": {
            "users": [],
            "groups": []
        },
        "crosslink__v": false,
        "lifecycle__v": "General Lifecycle",
        "version_created_by__v": 46916,
        "language__v": [
            "English"
        ],
        "minor_version_number__v": 1,
        "created_by__v": 46916,
        "annotations_lines__v": 0,
        "version_creation_date__v": "2015-03-12T16:24:33.539Z",
        "country__v": [],
        "md5checksum__v": "94e18bdbcf695c905a5968429e0c5204",
        "restrict_fragments_by_product__v": true,
        "annotations_notes__v": 0,
        "version_modified_date__v": "2015-03-12T16:24:54.000Z",
        "pages__v": 1,
        "major_version_number__v": 1,
        "annotations_anchors__v": 0,
        "product__v": [
            "1357662840293"
        ],
        "export_filename__v": "451Chole",
        "annotations_resolved__v": 0,
        "type__v": "Reference Document",
        "size__v": 11599,
        "description__v": "This is my document.",
        "status__v": "Draft",
        "annotations_unresolved__v": 0,
        "document_creation_date__v": "2015-02-25T01:26:55.845Z",
        "locked__v": false,
        "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "annotations_links__v": 0,
        "document_number__v": "REF-0201",
        "annotations_all__v": 0,
        "last_modified_by__v": 46916,
        "name__v": "CholeCap Information",
        "subtype__v": "Prescribing Information"
    },
    "renditions": 
        {
        "viewable_rendition__v": "https://myvault.vaultdev.com/api/v15.0/objects/documents/450/renditions/viewable_rendition__v",
        "veeva_distribution_package__vs": "https://myvault.vaultdev.com/api/v15.0/objects/documents/450/renditions/veeva_distribution_package__vs"
    },
    "versions": [
        {
            "number": "0.1",
            "value": "https://myvault.vaultdev.com/api/v15.0/objects/documents/450/versions/0/1"
        },
        {
            "number": "1.0",
            "value": "https://myvault.vaultdev.com/api/v15.0/objects/documents/450/versions/1/0"
        },
        {
            "number": "1.1",
            "value": "https://myvault.vaultdev.com/api/v15.0/objects/documents/450/versions/1/1"
        }
    ],
    "attachments": [
        {
            "id": 547,
            "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/450/attachments/547"
        }
    ]
}

Identifying Binders

A document pseudo-field binder__v indicates whether the returned document is a regular document or a binder.
The value of true means it is a binder, false or absence of this field means it is a document.
If it is a binder, the binder node structure is not listed as part of the response and must be determined through the appropriate Binder API call.

Identifying CrossLink Documents

A document pseudo-field crosslink__v indicates whether the returned document is a regular document or a CrossLink document.
The value of true means it is a CrossLink.

History

Since v1
v4+ - Response includes term highlight hints.
v5+ - Includes the binder__v true/false field to distinguish between documents and binders.
v10+ - Supports CrossLink documents.

Retrieve Document Versions

Retrieve all versions of a document.

Request

Send GET to /api/{version}/objects/documents/{document_id}/versions

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions

Response

{
    "responseStatus": "SUCCESS",
    "versions": [
        {
            "number": "0.1",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/0/1"
        },
        {
            "number": "0.2",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/0/2"
        },        
        {
            "number": "1.0",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/1/0"
        },        
        {
            "number": "1.1",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/1/1"
        },
        {
            "number": "2.0",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0"
        },
        {
            "number": "2.1",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/1"
        },
        {
            "number": "2.2",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/2"
        },
        {
            "number": "2.3",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/3"
        }
    ],
    "renditions":
        {
        "viewable_rendition__v": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/viewable_rendition__v",   
        "veeva_distribution_package__vs": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/veeva_distribution_package__vs"
    }
}

Details

On SUCCESS, Vault returns a list of all available versions of the specified document. In the response above, document id:534 has 8 different versions. Version 2.0 is the latest steady state version. Version 2.3 is the latest version. This document also has two different renditions: The viewable_rendition__v and a veeva_distribution_package__vs rendition.

History

Since v1

Retrieve Document Version

Retrieve all fields and values configured on a document version.

Request

Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/3

Response (abridged)

{
    "responseStatus": "SUCCESS",
    "document": {
        "id": 534,
        "allow_download_embedded_viewer__v": true,
        "reviewer__v": {
            "users": [
                46916,
                45589
            ],
            "groups": [
                1359484520721
            ]
            ...
        },    
        "crosslink__v": false,
        "lifecycle__v": "General Lifecycle",
        "version_created_by__v": 46916,
        "language__v": [
            "English"
        ],
        "minor_version_number__v": 3,
        "created_by__v": 46916,
        "annotations_lines__v": 0,
        "version_creation_date__v": "2015-03-13T16:24:33.539Z",
        "country__v": [],
        "md5checksum__v": "94e18bdbcf695c905a5989629e0c5204",
        "restrict_fragments_by_product__v": true,
        "annotations_notes__v": 0,
        "version_modified_date__v": "2015-03-13T16:24:54.000Z",
        "pages__v": 1,
        "major_version_number__v": 2,
        "annotations_anchors__v": 0,
        "product__v": [
            "1357662840293"
        ],
        "export_filename__v": "WD",
        "annotations_resolved__v": 0,
        "type__v": "Reference Document",
        "size__v": 11518,
        "description__v": "",
        "status__v": "Draft",
        "annotations_unresolved__v": 0,
        "document_creation_date__v": "2015-02-25T01:26:55.845Z",
        "locked__v": false,
        "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "annotations_links__v": 0,
        "document_number__v": "REF-0059",
        "annotations_all__v": 0,
        "last_modified_by__v": 46916,
        "name__v": "Wonderdrug Information",
        "binder__v": false,
        "subtype__v": "Prescribing Information"
    },
    "renditions": [
        {
        "viewable_rendition__v": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/viewable_rendition__v",   
        "veeva_distribution_package__vs": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/veeva_distribution_package__vs"
        }
    ],
    "versions": [
        {
            "number": "2.3",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/3"
        }
    ],
    "attachments": [
        {
            "id": 547,
            "url": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/attachments/547"
        },
        {
            "id": 561,
            "url": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/attachments/561"
        }
    ]
}

Details

On SUCCESS, Vault returns all fields and values for the specified version of the document. The response above shows information for document id:534 version 2.3.

History

Since v1

Download Document File

Request

Send GET to /api/{version}/objects/documents/{document_id}/file

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/file > file

You can also "check out" the document before the retrieval by setting lockDocument request parameter to true (this is set to false by default).

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/file?lockDocument=true > file

Response

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="CholeCap-Presentation.pptx"

Response

On SUCCESS, Vault retrieves the latest version of the source file from the document. The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file.

History

Since v1
v6+ - Supports document lock (check-out) prior to download.

Download Document Version File

Download the file of a specific document version.

Request

Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/file

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/file > file

You can also "check out" the document version before the retrieval by setting lockDocument request parameter to true (this is set to false by default).

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/file?lockDocument=true > file

Response

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="CholeCap-Presentation.pptx"

Details

On SUCCESS, Vault retrieves the specified version of the source file from the document. The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file.

History

Since v1
v6+ - Supports document lock (check-out) prior to download.

Download Document Version Thumbnail File

Download the thumbnail image file of a specific document version.

Request

Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/thumbnail

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/3/thumbnail > thumbnail.png

Response

On SUCCESS, Vault returns the thumbnail image for the specified version of the document. The HTTP Response Header Content-Type is set to image/png.

History

Since v6

Create Documents

These all involve creating one document at a time.

About Required & Editable Fields

When creating a new document, certain standard fields are required in all vaults. These are listed below with each request.
Your Vault Admin may set additional standard or custom document fields to required in your vault.
If a required field is not included in the request, Vault returns a PARAMETER_REQUIRED error with the name of the missing field.

To retrieve document fields in your vault:

Use the Document Metadata API to retrieve all fields configured on documents. In the field specifications: Required fields: required:true / Editable fields: editable:true.
Use the Vault Loader Document Extract to retrieve fields and values configured on specific documents.
Go to Admin > Configuration > Document Fields and find all fields marked "Required" and those which are editable. Learn more in Vault Help.

About Document Name Defaulting

When creating new documents, the document name__v is a required standard field.
However, your Vault Admin may define a format for auto-populating the field's default value.
When configured for document name defaulting, the name__v field is not required.
If the name__v field is provided through the API, the value overwrites the auto-generated default name.
Learn about Document Name Defaulting in Vault Help.

For example:

The table below describes the behavior when document name defaulting is not enabled.

`file`	`name__v`	Result
Storyboard_0725.docx	My Story Board 07-25	The new document is created and named "My Story Board 07-25"
Storyboard_0725.docx		The document is not created and an error is returned: "Missing required parameter `name__v`".

The table below describes the behavior when document name defaulting is enabled.

`file`	`name__v`	Key	Result
Storyboard_0725.docx		{filename}	The new document is created and named "Storyboard_0725". With document name defaulting on, the `name__v` field value is not required. The custom name key {filename} key tells Vault to use the name of the uploaded file as the document name.
Storyboard_0725.docx	My Story Board 07-25	{filename}	The new document is created and named "My Story Board 07-25". Even though the custom format says to use the filename, the user-defined `name__v` value overrides it.

Where:

file is the name of the file being used to create the document.
name__v is the user-defined name for the new document.
"Key" is the token entered into the "Use Custom Name" field section of the document type details.

About Default Document Field Values

Some document fields allow default values to be specified by Admin. When a field includes default values and the field is omitted from the request, the field is automatically populated with the value during document creation. When the field is included in the request, the field values specified in the input override the default values.

You can find out which field has a default by analyzing the defaultValue metadata field on the document field.

For example:

{
    "name": "region__c",
    "type": "Picklist",
    "required": false,
    "editable": true,
    "defaultValue": [
        "North America"
    ],
    "label": "Region",
    "entryLabels": [
        "North America",
        "South America"
    ],...
}

Shown above are select portions of the region__c document field metadata.

The field is not required when creating a new document.
The field is editable, meaning you can add or remove its values.
The field has a default value. When a document is created, this field is automatically assigned the value "North America".
The field can be assigned the alternate value "South America" by including it in the input when creating the document.

Create Document from Uploaded File

Most documents in your vault are created from uploaded source files, e.g., "mydocument.docx". Learn about Supported File Formats in Vault Help. Once uploaded with values assigned to document fields, Vault generates the viewable rendition, e.g., "mydocument.docx.pdf". Learn about Viewable Renditions in Vault Help.

Request

Send POST to /api/{version}/objects/documents

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB.

Required Standard Fields

When creating a new document, the following standard fields are required in all vaults:

Field Name	Description
`name__v`	The name of the new document.
`type__v`	The name of the document type to assign to the new document.
`subtype__v`	The name of the document subtype (if one exists on the document type).
`classification__v`	The name of the document classification (if one exists on the document subtype).
`lifecycle__v`	The name of the document lifecycle to assign to the new document.
`major_version_number__v`	The major version number to assign to the new document.
`minor_version_number__v`	The minor version number to assign to the new document.

Additional Required & Editable Fields

Admin may set other standard or custom document fields to required in your vault. Learn about Required Document Fields above. If a required field is not included, Vault returns a PARAMETER_REQUIRED error with the name of the missing field. You may include name-value pairs for other optional, editable document fields and values. Learn about Editable Document Fields above.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "file=gludacta-document-01.docx" \
-F "name__v=Gludacta Document" \
-F "type__v=Promotional Piece" \
-F "subtype__v=Advertisement" \
-F "classification__v=Web" \
-F "lifecycle__v=Promotional Piece" \
-F "major_version_number__v=0" \
-F "minor_version_number__v=1" \
-F "product__v=0PR0303" \
-F "external_id__v=GLU-DOC-0773" \
https://myvault.veevavault.com/api/v15.0/objects/documents

This example includes:

The file parameter with the name of the source file being used to create the new document.
All required fields (in our vault) to create a new document of the specified document type.
The specified major and minor document version numbers will create this document as version 0.1.
The optional (in our vault) product__v document field name with the product object record ID to assign to the new document.
The optional (in our vault) external_id__v document field with a document external ID to assign to the new document.

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 773
}

On SUCCESS, the document is created and assigned a system-managed document id field value.

History

Since v1
v7+ - Supports asynchronous metadata indexing.
v8+ - Supports suppress generation of viewable rendition.

Create Document from Template

Vault document templates allow quick creation of new documents from preconfigured templates in your vault. When you create the new document, Vault copies the template file and uses that copy as the source file for the new document. This process bypasses the content upload process and allows for more consistent document creation. Document templates are associated with a specific document type, like documents themselves. Learn about Document Templates in Vault Help.

Request

Send POST to /api/{version}/objects/documents

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Select the Document Template

To indicate the template to apply, use the multi-part attachment with the file component "fromTemplate={template_name}". The template must exist in the vault.

Required Standard Fields

When creating a new document, the following standard fields are required in all vaults:

Field Name	Description
`name__v`	The name of the new document.
`type__v`	The name of the document type to assign to the new document.
`subtype__v`	The name of the document subtype (if one exists on the document type).
`classification__v`	The name of the document classification (if one exists on the document subtype).
`lifecycle__v`	The name of the document lifecycle to assign to the new document.
`major_version_number__v`	The major version number to assign to the new document.
`minor_version_number__v`	The minor version number to assign to the new document.

Additional Required & Editable Fields

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-d "fromTemplate=promo_doc_template__c" \
-d "name__v=Gludacta Document" \
-d "type__v=Promotional Piece" \
-d "subtype__v=Advertisement" \
-d "classification__v=Web" \
-d "lifecycle__v=Promotional Piece" \
-d "major_version_number__v=0" \
-d "minor_version_number__v=2" \
-d "product__v=0PR0303" \
-d "external_id__v=GLU-DOC-0774" \
https://myvault.veevavault.com/api/v15.0/objects/documents

This example includes:

The fromTemplate parameter with the name of the template being used to create the new document.
All required fields (in our vault) to create a new document of the specified document type.
The specified major and minor document version numbers will create this document as version 0.2.
The optional (in our vault) product__v document field name with the product object record ID to assign to the new document.
The optional (in our vault) external_id__v document field with a document external ID to assign to the new document.

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 774
}

On SUCCESS, the document is created and assigned a system-managed document id field value.

History

Since v5
v7+ - Supports asynchronous metadata indexing.
v8+ - Supports suppress generation of viewable rendition.

Create Content Placeholder Document

You can create a content placeholder document when the associated source file is not yet available and then, add the source file at a later date. Creating a content placeholder document is just like creating a document from an uploaded file, but the file parameter is not included in the request. Learn about Content Placeholders in Vault Help.

Request

Send POST to /api/{version}/objects/documents

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Required Standard Fields

When creating a new document, the following standard fields are required in all vaults:

Field Name	Description
`name__v`	The name of the new document.
`type__v`	The name of the document type to assign to the new document.
`subtype__v`	The name of the document subtype (if one exists on the document type).
`classification__v`	The name of the document classification (if one exists on the document subtype).
`lifecycle__v`	The name of the document lifecycle to assign to the new document.
`major_version_number__v`	The major version number to assign to the new document.
`minor_version_number__v`	The minor version number to assign to the new document.

Additional Required & Editable Fields

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-d "name__v=Gludacta Document" \
-d "type__v=Promotional Piece" \
-d "subtype__v=Advertisement" \
-d "classification__v=Web" \
-d "lifecycle__v=Promotional Piece" \
-d "major_version_number__v=0" \
-d "minor_version_number__v=2" \
-d "product__v=0PR0303" \
-d "external_id__v=GLU-DOC-0775" \
https://myvault.veevavault.com/api/v15.0/objects/documents

This example includes:

All required fields (in our vault) to create a new document of the specified document type.
The specified major and minor document version numbers will create this document as version 0.2.
The optional (in our vault) product__v document field name with the product object record ID to assign to the new document.
The optional (in our vault) external_id__v document field with a document external ID to assign to the new document.

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 775
}

On SUCCESS, the document is created and assigned a system-managed document id field value.

History

Since v1
v7+ - Supports asynchronous metadata indexing.
v8+ - Supports suppress generation of viewable rendition.

Create Unclassified Document

Unclassified documents are documents which have a source file, but no document type. Bypassing the steps to classify the document and populate document properties allows you to upload source files and create documents more quickly. Learn about Unclassified Documents in Vault Help.

Request

Send POST to /api/{version}/objects/documents

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB.

Required Standard Fields

When creating an unclassified document, the following standard fields are required in all vaults:

Field Name	Description
`type__v`	Set the document type to "Undefined".
`lifecycle__v`	Set the document lifecycle to "Unclassified".

In eTMF vaults, you can also (optionally) set the following fields:

product__v
study__v
study_country__v
site__v

Any other fields included in the input will be ignored. The document name (name__v) will default to the name of the uploaded file.

Example (All vaults)

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "file=CholeCap Information.docx" \
-F "type__v=Undefined" \
-F "lifecycle__v=Unclassified" \
https://myvault.veevavault.com/api/v15.0/objects/documents

Example (eTMF vaults)

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "file=CholeCap Information.docx" \
-F "type__v=Undefined" \
-F "lifecycle__v=Unclassified" \
-F "product__v=00P000000000101" \
-F "study__v=0ST000000000501" \
-F "study_country__v=0SC000000000401" \
-F "site__v=0SI000000000301" \
https://myvault.veevavault.com/api/v15.0/objects/documents

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 776
}

On SUCCESS, the new unclassified document is created and assigned a document id.

History

Since v1
v7+ - Supports asynchronous metadata indexing.
v8+ - Supports suppress generation of viewable rendition.

Create CrossLink Document

CrossLink documents enable content from one vault to be used in another vault within the same domain. A CrossLink document in your vault uses the viewable rendition from a source document in another [source] vault, with different fields, lifecycle, and workflows. When creating a CrossLink document, you must include all document fields that are required for the specified document type/subtype/classification and no file is uploaded. You must also specify the vault ID and document ID for the source document which will be bound to the new CrossLink document. Learn about CrossLinks in Vault Help.

Request

Send POST to /api/{version}/objects/documents

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Required Standard Fields

When creating a new CrossLink document, the following standard fields are required in all vaults:

Field Name	Description
`name__v`	The name of the new CrossLink document.
`type__v`	The name of the document type to assign to the new CrossLink document.
`subtype__v`	The name of the document subtype (if one exists on the document type).
`classification__v`	The name of the document classification (if one exists on the document subtype).
`lifecycle__v`	The name of the document lifecycle to assign to the new CrossLink document.
`major_version_number__v`	The major version number to assign to the new CrossLink document
`minor_version_number__v`	The minor version number to assign to the new CrossLink document.
`source_vault_id__v`	The vault `id` field value of the vault containing the source document that will be bound to the new CrossLink document. Learn more.
`source_document_id__v`	The document `id` field value of the source document that will be bound to the new CrossLink document.

Optional Standard Fields

When creating a new CrossLink document, the following standard fields referencing the source document are optional:

Field Name	Description
`source_binding_rule__v`	Possible values: `Latest version`, `Latest Steady State version`, or `Specific Document version`. These define which version of the source document will be bound to the CrossLink document. If not specified, this defaults to the `Latest Steady State version`.
`bound_source_major_version__v`	When the `source_binding_rule__v` is set to `Specific Document version`, you must specify the major version number of the source document to bind to the CrossLink document.
`bound_source_minor_version__v`	When the `source_binding_rule__v` is set to `Specific Document version`, you must specify the minor version number of the source document to bind to the CrossLink document.

Additional Required & Editable Fields

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-d "name__v=Gludacta Document" \
-d "type__v=Promotional Piece" \
-d "subtype__v=Advertisement" \
-d "classification__v=Web" \
-d "lifecycle__v=Promotional Piece" \
-d "major_version_number__v=0" \
-d "minor_version_number__v=1" \
-d "source_vault_id__v=2112" \
-d "source_document_id__v=101" \
-d "source_binding_rule__v=Specific Document version" \
-d "bound_source_major_version__v=1" \
-d "bound_source_major_version__v=3" \
-d "product__v=0PR0303" \
-d "external_id__v=GLU-DOC-0777" \
https://myvault.veevavault.com/api/v15.0/objects/documents

This example includes:

All required fields (in our vault) to create a new document of the specified document type.
The specified major and minor document version numbers will create this CrossLink document as version 0.1.
The ID of the source vault and source document which will be bound to the CrossLink document in our vault.
The binding rule specifying that the new CrossLink document will be statically bound to version 1.3 of the source document.
The optional (in our vault) product__v document field name with the product object record ID to assign to the new CrossLink document.
The optional (in our vault) external_id__v document field with a document external ID to assign to the new CrossLink document.

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "successfully created document",
    "id": 775
}

On SUCCESS, the document is created and assigned a system-managed document id field value.

History

Since v10

Create Multiple Documents

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\create_documents.csv" \
https://myvault.veevavault.com/api/v9.0/objects/documents/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773"
        },        
        {
            "responseStatus": "FAILURE"
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this document was not created."
                }
            ]
        }
    ]
}

This endpoint allows you to create multiple documents at once with a CSV input file.

The maximum CSV input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.

POST /api/{version}/objects/documents/batch

Headers

Name	Description
`Content-Type`	`text/csv`
`Accept`	`application/json` (default) or `text/csv`

Body Parameters

Prepare a CSV input file. There are multiple ways to create documents in bulk. The following shows the required standard fields needed to create documents, but an Admin may set other standard or custom document fields as required in your vault. To find which fields are required, retrieve document fields. You can also optionally include any editable document field.

Update Documents

Update Single Document

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "language__v=English" \
-d "product__v=1357662840171" \
-d "audience__vs=consumer__vs" \
https://myvault.veevavault.com/api/v15.0/objects/documents/534

Example Response

{
"responseStatus": "SUCCESS",
"id": 534
}

Update editable field values on the latest version of a single document. To update past document versions, see Update Document Version. Note that this endpoint does not allow you to update the archive__v field. To archive a document, or to update multiple documents at once, see Update Multuple Documents.

PUT /api/{version}/objects/documents/{doc_id}

Headers

Name	Description
`Content-Type`	`application/x-www-form-urlencoded`
`Accept`	`application/json` (default) or `application/xml`

URI Path Parameters

Name	Description
`{doc_id}`	The document `id` field value.

Body Parameters

In the body of the request, add any editable field values that you wish to update. To find these fields, retrieve fields configured on documents. Editable fields will have editable:true. To remove existing field values, include the field name and set its value to null.

Update Multiple Documents

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\update_documents.csv" \
https://myvault.veevavault.com/api/v9.0/objects/documents/batch

Example Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773"
        }
    ]
}

Bulk update editable field values on multiple documents. You can only update the latest version of each document. To update past document versions, see Update Document Version.

The maximum CSV input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 1,000.

PUT /api/{version}/objects/documents/batch

Headers

Name	Description
`Content-Type`	`text/csv` or `application/x-www-form-urlencoded`
`Accept`	`application/json` (default) or `text/csv`

Body Parameters

You can use Name-Value pairs in the body of your request or you can upload a CSV. id is the only required field, and you can update values of any editable document field. To find these fields, retrieve fields configured on documents. Editable fields will have editable:true. To remove existing field values, include the field name and set its value to null.

Name	Description
`id`	ID of the document to update
`archive__v`	Optional: To archive a document, set to `true`. To unarchive a document, set to `false`.

Reclassify Document

Reclassify allows you to change the document type of an existing document or assign a document type to an existing unclassified document. A document "type" is the combination of the type__v, subtype__v, and classification__v fields on a document. When you reclassify, Vault may add or remove certain fields on the document. You can only reclassify the latest version of a document and only one document at a time. The API does not currently support Bulk Reclassify.

Learn more about:

Vault Help: Reclassifying Documents.
API: Retrieve Documents
API: Retrieve Document Fields
API: Retrieve Document Types, Subtypes, and Classifications
API: Create Unclassified Documents

Request

Send PUT to /api/{version}/objects/documents/{document_id}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Input

Field Name	Description
`reclassify`	Set to `true`. Without this, a standard document update action is performed.
`type__v`	The name of the document type.
`subtype__v`	The name of the document subtype (if one exists on the type).
`classification__v`	The name of the document classification (if one exists on the subtype).
`lifecycle__v`	The name of the document lifecycle.

You can also add or remove values for any other editable document field. Note that additional fields may be required depending on the document type, subtype, and classification being assigned to the document. Use the Document Metadata API to retrieve required and editable fields in your vault. If a required field is missing, the error response will list the name of the required field.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "reclassify=true" \
-d "type__v=Promotional Piece" \
-d "subtype=Advertisement" \
-d "classification__v=Web" \
-d "lifecycle__v=Promotional Piece" \
https://myvault.veevavault.com/api/v15.0/objects/documents/775

Response

{
    "responseStatus": "SUCCESS",
    "id": 775
}

Errors

Type	Message	Comments
`OPERATION_NOT_ALLOWED`	Operation not allowed because document falls under one or more legal holds.	You cannot reclassify a document which is related to an approved legal hold. Learn more about Legal Hold in Vault Help.

History

Since v8

Update Document Version

Update editable field values on a specific version of a document. See also Update Document above.

Request

Send PUT to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "language__v=English" \
-d "product__v=1357662840171" \
-d "audience__vs=consumer__vs" \
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0

Response

{
    "responseStatus": "SUCCESS",
    "id": 534
}

On SUCCESS, Vault updates field values for the specified version of the document and returns the ID of the updated document.

History

Since v1

Create Document Versions

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\add_document_versions.csv" \
https://myvault.veevavault.com/api/v10.0/objects/documents/versions/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771",
            "major_version_number__v": 0,
            "minor_version_number__v": 2
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772",
            "major_version_number__v": 0,
            "minor_version_number__v": 2
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773",
            "major_version_number__v": 1,
            "minor_version_number__v": 0
        },        
        {
            "responseStatus": "FAILURE"
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this document version was not added."
                }
            ]
        }
    ]
}

Create or add document versions in bulk.

Your vault must be in Migration Mode.
The maximum CSV input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.

POST /api/{version}/objects/documents/versions/batch

Headers

Name	Description
`Content-Type`	`text/csv`
`Accept`	`application/json` (default) or `text/csv`

Body Parameters

Name	Description
`file`	The filepath of your source file. If the current version of the document includes a source file, you must include a source file for any past versions. The maximum allowed file size is 4GB.
`id`	The system-assigned document ID of the document to delete.
`external_id__v`	Optional: Instead of `id`, you can use this user-defined document external ID.
`name__v`	Enter a name for the new document. This may be the same name as the existing document/version or a different name.
`type__v`	Enter the name of the document type to assign to the new document.
`subtype__v`	Enter the name of the document subtype (if one exists on the document type).
`classification__v`	Enter the name of the document classification (if one exists on the document subtype).
`lifecycle__v`	Enter the name of the document lifecycle to assign to the new document. This may be the same lifecycle as the existing document/version or a different lifecycle.
`major_version_number__v`	Enter the major version number to assign to the new document version. This must be a version that does not yet exist on the document being updated.
`minor_version_number__v`	Enter the minor version number to assign to the new document. This must be a version that does not yet exist on the document being updated.
`status__v`	Enter a status for the new document, e.g., Draft, In Review, Approved, etc.
`product__v`	Example: This is an example object reference field. To assign value for this field type, include either the document field name `product__v` or the document field name plus the name field on the object `product__v.name__v`.

Query String Parameters

Name	Description
`idParam`	If you're identifying documents in your input by their external ID, add `idParam=external_id__v` to the request endpoint.

Create Document Version

Create a new draft version of an existing document or create a new draft version by uploading and replacing the document source file. Both of these actions will increase the document by a minor version number.

Request

Send POST to /api/{version}/objects/documents/{document_id}

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Options

To create a new draft version from the existing document in the vault, include createDraft=latestContent in the input as shown in Example 1 below. This does not require uploading a file. For example, you want to create version 0.2 from the existing version 0.1. This is analogous to using the Create Draft action in the UI.

To create a new draft version by uploading and replacing the document source file, include the createDraft=uploadedContent in the input as shown in Example 2 below. This requires uploading a new source file. To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB. For example, you want to create version 0.2 but do not want to use the existing version 0.1. This is analogous to using the Upload New Version action in the UI.

With either of the above options, you may suppress automatic generation of the viewable rendition by adding the suppressRendition=true query parameter to the request endpoint. This is shown in Example 3 below.

Example 1

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "createDraft=latestContent" \
https://myvault.veevavault.com/api/v15.0/objects/documents/534

Example 2

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "file=CholeCap-Presentation.pptx" \
-F "createDraft=uploadedContent" \
https://myvault.veevavault.com/api/v15.0/objects/documents/534

Example 3

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "file=CholeCap-Presentation.pptx" \
-F "createDraft=uploadedContent" \
https://myvault.veevavault.com/api/v15.0/objects/documents/534?suppressRendition=true

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "New draft successfully created.",
  "major_version_number__v": 0,
  "minor_version_number__v": 2
}

History

Since v7
v8+ - Supports suppress generation of viewable rendition

Delete Documents

The API allows you to delete all versions of a document or a specific version. This can also be done in bulk using the Bulk Documents API or Vault Loader (UI). After documents are deleted, the API allows you to retrieve their IDs for up to 30 days. The deleted files themselves are removed from the server and can only be retrieved by Vault Support.

Delete Single Document

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534

Response

{
    "responseStatus": "SUCCESS",
    "id": 534
}

Delete all versions of a document, including all source files and viewable renditions.

DELETE /api/{version}/objects/documents/{document_id}

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`

URI Path Parameters

Name	Description
`document_id`	The system-assigned document ID of the document to delete.

Delete Multiple Documents

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\delete_documents.csv" \
https://myvault.veevavault.com/api/v13.0/objects/documents/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773"
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this document was not deleted."
                }
            ]
        }
    ]
}

Delete all versions of a document, including all source files and viewable renditions.

The maximum input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.

DELETE /api/{version}/objects/documents/batch

Headers

Name	Description
`Content-Type`	`text/csv` or `application/json`
`Accept`	`application/json` (default) or `text/csv`

Body Parameters

Create a CSV or JSON input file. Choose one of the following two ways to identify documents for deletion:

Name	Description
`id`	The system-assigned document ID of the document to delete.
`external_id__v`	Optional: Instead of `id`, you can use this user-defined document external ID.

Query String Parameters

Name	Description
`idParam`	If you're identifying documents in your input by their external ID, add `idParam=external_id__v` to the request endpoint.

Delete Single Document Version

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/0/2

Response

{
    "responseStatus": "SUCCESS",
    "id": 534
}

Delete a specific version of a document, including the version's source file and viewable rendition. Other versions of the document remain unchanged. See also Delete Document.

DELETE /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}

Headers

Name	Description
`Accept`	`application/json` (default) or `text/csv`

URI Path Parameters

Name	Description
`{doc_id}`	The document `id` field value.
`{major_version}`	The document `major_version_number__v` field value.
`{minor_version}`	The document `minor_version_number__v` field value.

Delete Multiple Document Versions

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\delete_document_versions.csv" \
https://myvault.veevavault.com/api/v13.0/objects/documents/versions/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771",
            "major_version_number__v": 0,
            "minor_version_number__v": 2
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772",
            "major_version_number__v": 0,
            "minor_version_number__v": 2
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773",
            "major_version_number__v": 1,
            "minor_version_number__v": 0
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this document version was not deleted."
                }
            ]
        }
    ]
}

Delete a specific version from multiple documents, including the version's source file and viewable rendition.

The maximum input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.

DELETE /api/{version}/objects/documents/versions/batch

Headers

Name	Description
`Content-Type`	`text/csv` or `application/json`
`Accept`	`application/json` (default) or `text/csv`

Body Parameters

Create a CSV or JSON input file.

Name	Description
`id`	The system-assigned document ID of the document to delete.
`external_id__v`	Optional: Instead of `id`, you can use this user-defined document external ID.
`major_version_number__v`	Major version number of the document version to remove.
`minor_version_number__v`	Minor version number of the document version to remove.

Query String Parameters

Name	Description
`idParam`	If you're identifying documents in your input by their external ID, add `idParam=external_id__v` to the request endpoint.

Retrieve Deleted Document IDs

Retrieve the IDs of documents that have been deleted from a vault within the past 30 days.

After documents and document versions are deleted from a vault, their IDs are still available for retrieval for 30 days. After that, they cannot be retrieved. This request supports optional parameters to narrow the results to a specific date and time range within the past 30 days.

Request

Send GET to /api/{version}/objects/deletions/documents

Headers

Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Options

You can modify the request by using one or both of the following parameters:

start_date - [Optional] Specify a date (no more than 30 days past) after which Vault will look for deleted documents.
end_date - [Optional] Specify a date (no more than 30 days past) before which Vault will look for deleted documents.

For example, assuming today is January 20:

To retrieve all documents deleted since 7AM on January 15: api/v15.0/objects/deletions/documents?start_date=2016-01-16T07:00:00Z
To retrieve all documents deleted between 7AM - 5PM on January 15: api/v15.0/objects/deletions/documents?start_date=2016-01-16T07:00:00Z&end_date=2016-01-16T17:00:00Z

About dates and times:

Dates and times are in UTC and must be formatted as YYYY-MM-DDTHH:MM:SSZ.
If the time is not specified, it will default to midnight (T00:00:00Z) on the specified date.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/deletions/documents

Response (abridged)

{
    "responseStatus": "SUCCESS",
    "responseMessage": "OK",
    "responseDetails": {
        "limit": 1000,
        "size": 88,
        "offset": 0,
        "total": 88

    },
    "data": [
        {
            "id": 690,

                    "major_version_number__v": 0,
                    "minor_version_number__v": 1,
                    "date_deleted": "2016-02-10T00:29:45Z"

        },
        {
            "id": 690,

                    "major_version_number__v": 0,
                    "minor_version_number__v": 2,
                    "date_deleted": "2016-02-10T00:29:45Z"

        },
        {
            "id": 691,

                    "major_version_number__v": 0,
                    "minor_version_number__v": 1,
                    "date_deleted": "2016-02-10T23:46:07Z"

        },
        {
            "id": 692,

                    "major_version_number__v": 0,
                    "minor_version_number__v": 1,
                    "date_deleted": "2016-02-10T00:29:37Z"

        },
        ...

Details

The abridged response shows that a total of 88 documents were deleted from this vault in the past 30 days. Document ID 690 had two versions (0.1 and 0.2) which were deleted. Document IDs 691 and 692 each has their 0.1 versions deleted. The response includes the date and time when each document was deleted. This is displayed in UTC, not in the user's time zone.

History

Since v13

Document Locks

A document "lock" is analogous to "checking out a document" but without the file attached in the response for download. To download the document file after locking it, use the Download Document File endpoint.

Learn about Document Checkout (Locks) in Vault Help.

Retrieve Document Lock Metadata

Request

Send GET to /api/{version}/metadata/objects/documents/lock

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/lock

Response

{
    "responseStatus": "SUCCESS",
    "name": "lock",
    "properties": [
        {
            "name": "locked_by__v",
            "scope": "Lock",
            "type": "ObjectReference",
            "required": true,
            "systemAttribute": true,
            "editable": false,
            "setOnCreateOnly": false,
            "disabled": false,
            "objectType": "User",
            "label": "Locked By",
            "hidden": false
        },
        {
            "name": "locked_date__v",
            "scope": "Lock",
            "type": "DateTime",
            "required": true,
            "systemAttribute": true,
            "editable": false,
            "setOnCreateOnly": false,
            "disabled": false,
            "objectType": "DateTime",
            "label": "Locked Date",
            "hidden": false
        }
    ]
}

Details

Metadata Field	Description
`name`	The "name" of the field used in the API. These include `locked_by__v`, `locked_date__v`, etc.
`label`	The "label" of the field used in the UI. These include "Locked By", "Locked Date", etc.
`type`	The "type" of field. These include "ObjectReference", "DateTime", etc.
`scope`	The "scope" of the field. This value is "Lock" for all fields.
`required`	Indicates if the field is required.
`systemAttribute`	Boolean (true/false) field which indicates if the field is a standard (system-managed) field, i.e., not editable by the user.
`editable`	Boolean (true/false) field which indicates if the field can be set or changed by the user, i.e., not system-managed.
`setOnCreateOnly`	Boolean (true/false) field which indicates if the field can only be set during creation of a new document.
`objectType`	When the field `type` is "ObjectReference", this field indicates the object which is being referenced.
`hidden`	Boolean (true/false) field which indicates if the field is "hidden" (not available).

History

Since v1
v6 - Changes to metadata property names.

Create Document Lock

A document lock is analogous to checking out a document but without the file attached in the response for download. To download the document file after locking it, use the Download Document File endpoint.

Request

Send POST to /api/{version}/objects/documents/{document_id}/lock

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/lock

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document successfully checked out."
}

On SUCCESS, Vault locks the document and other users are not allowed to lock (check-out) the document.

History

Since v1

Retrieve Document Lock

Request

Send GET to /api/{version}/objects/documents/{document_id}/lock

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/lock

Response

{
    "responseStatus": "SUCCESS",
    "lock": {
        "locked_by__v": 46916,
        "locked_date__v": "2015-03-20T23:47:11.000Z"
    }
}

Details

If the document is locked (checked out), the response includes the user id field value of the person who checked it out and the date and time. If the document is not locked, the lock fields shown above will not be returned.

History

Since v1

Delete Document Lock

Deleting a document lock is analogous to undoing check out of a document.

Request

Send DELETE t /api/{version}/objects/documents/{document_id}/lock

Parameters

{document_id} - The document id field value.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/lock

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Undo check out successful."
}

On SUCCESS, Vault unlocks the document, allowing other users to lock/check out the document.

History

Since v1

Document Renditions

Learn about Document Renditions in Vault Help.

Retrieve Document Renditions

Request

Send GET to /api/{version}/objects/documents/{document_id}/renditions

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions

Response

{
    "responseStatus": "SUCCESS",
    "renditionTypes": [
        "viewable_rendition__v",
        "imported_rendition__vs",
        "veeva_distribution_package__vs"
    ],
    "renditions": {
        "viewable_rendition__v": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/viewable_rendition__v",
        "veeva_distribution_package__vs": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/veeva_distribution_package__vs"
    }
}

Details

Metadata Field	Description
`renditionTypes[n]`	List of all rendition types configured for the specified document.
`renditions[n]`	List of renditions available for the specified document and the endpoint URL to retrieve them.

History

Since v1

Retrieve Document Version Renditions

Request

Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/renditions

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0/renditions

Response

{
    "responseStatus": "SUCCESS",
    "renditionTypes": [
        "viewable_rendition__v",
        "imported_rendition__vs",
        "veeva_distribution_package__vs"
    ],
    "renditions": {
        "viewable_rendition__v": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0/renditions/viewable_rendition__v",
        "veeva_distribution_package__vs": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0/renditions/veeva_distribution_package__vs"
    }
}

History

Since v7

Download Document Rendition File

Download a rendition (file) from the latest version of a document.

Request

Send GET to /api/{version}/objects/documents/{document_id}/renditions/{rendition_type}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{rendition_type} - The document rendition type.

Options

/api/{version}/objects/documents/{document_id}/renditions/{rendition_type}?steadyState=true
Download a rendition (file) from the latest steady state version (1.0, 2.0, etc.) of a document.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/viewable_rendition__v > file

Response

{
    "responseStatus": "SUCCESS"
}

Details

On SUCCESS, Vault retrieves the file associated with the given renditions type for the document.
The HTTP Response Header Content-Type is set to application/octet-stream.

History

Since v1
v6+ - Supports the steadyState request parameter.

Download Document Version Rendition File

Request

Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/renditions/{rendition_type}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{major_version_number__v} - The document major_version_number__v field value.
{minor_version_number__v} - The document minor_version_number__v field value.
{rendition_type} - The document rendition type.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0/renditions/viewable_rendition__v > file

Response

{
    "responseStatus": "SUCCESS"
}

Details

On SUCCESS, Vault retrieves the file associated with the given renditions type for the specified document version.
The HTTP Response Header Content-Type is set to application/octet-stream.

History

Since v7

Add Multiple Document Renditions

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\add_document_renditions.csv" \
https://myvault.veevavault.com/api/v10.0/objects/documents/renditions/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771",
            "major_version_number__v": 0,
            "minor_version_number__v": 2,
            "rendition_type__c": "imported_rendition__c"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772",
            "major_version_number__v": 0,
            "minor_version_number__v": 2,
            "rendition_type__c": "imported_rendition__c"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773",
            "major_version_number__v": 1,
            "minor_version_number__v": 0,
            "rendition_type__c": "imported_rendition__c"
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this document rendition was not added."
                }
            ]
        }
    ]
}

Add document renditions in bulk.

Your vault must be in Migration Mode.
The maximum CSV input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.

POST /api/{version}/objects/documents/renditions/batch

Headers

Name	Description
`Content-Type`	`text/csv`
`Accept`	`application/json` (default) or `text/csv`

Body Parameters

Name	Description
`file`	The file path of your source files.
`id`	The system-assigned document ID of the document to delete.
`external_id__v`	Optional: Instead of `id`, you can use this user-defined document external ID.
`rendition_type__v`	Document rendition type to assign to the new rendition. Only one rendition of each type may exist on each document.
`major_version_number__v`	Major version number to assign to the new document rendition.
`minor_version_number__v`	Minor version number to assign to the new document rendition.

Query String Parameters

Name	Description
`idParam`	If you're identifying documents in your input by their external ID, add `idParam=external_id__v` to the request endpoint.

Upload Document Rendition

Request

Send POST to /api/{version}/objects/documents/{document_id}/renditions/{rendition_type}

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{rendition_type} - The document rendition type.

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "file=CholeCap-Document.pdf" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/imported_rendition__vs

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, Vault associates the uploaded file with the given rendition type for the specified document.

History

Since v1

Upload Document Version Rendition

Request

Send POST to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/renditions/{rendition_type}

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Parameters

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "file=CholeCap-Document.pdf" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0/renditions/imported_rendition__vs

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, Vault associates the uploaded file with the given rendition type for the document with the specified version number.

History

Since v7

Replace Document Rendition

Request

Send PUT to /api/{version}/objects/documents/{document_id}/renditions/{rendition_type}

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{rendition_type} - The document rendition type.

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "file=CholeCap-Document.pdf" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/imported_rendition__vs

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, Vault replaces the rendition of the given type from the latest version of the document.

Errors

Type	Message	Comments
`OPERATION_NOT_ALLOWED`	Cannot replace `viewable_rendition__v` for document because document falls under one or more legal holds.	You cannot delete or replace renditions which are related to an approved legal hold. Learn more about Legal Hold in Vault Help.

History

Since v7

Replace Document Version Rendition

Request

Send PUT to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/renditions/{rendition_type}

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Parameters

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "file=CholeCap-Document.pdf" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0/renditions/imported_rendition__vs

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, Vault replaces the rendition of the given type for the specified version of the document.

Errors

Type	Message	Comments
`OPERATION_NOT_ALLOWED`	Cannot replace `viewable_rendition__v` for document because document falls under one or more legal holds.	You cannot delete or replace renditions which are related to an approved legal hold. Learn more about Legal Hold in Vault Help.

History

Since v7

Delete Multiple Document Renditions

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\delete_document_renditions.csv" \
https://myvault.veevavault.com/api/v13.0/objects/documents/renditions/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "external_id__v": "ALT-DOC-0771",
            "major_version_number__v": 0,
            "minor_version_number__v": 2,
            "rendition_type__c": "imported_rendition__c"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "external_id__v": "CHO-DOC-0772",
            "major_version_number__v": 0,
            "minor_version_number__v": 2,
            "rendition_type__c": "imported_rendition__c"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 773,
            "external_id__v": "GLU-DOC-0773",
            "major_version_number__v": 1,
            "minor_version_number__v": 0,
            "rendition_type__c": "imported_rendition__c"
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this document rendition was not added."
                }
            ]
        }
    ]
}

Delete document renditions in bulk.

The maximum input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.

DELETE /api/{version}/objects/documents/renditions/batch

Headers

Name	Description
`Content-Type`	`text/csv` or `application/json`
`Accept`	`application/json` (default) or `text/csv`

Body Parameters

Create a CSV or JSON input file.

Name	Description
`id`	The system-assigned document ID of the document to delete.
`external_id__v`	Optional: Instead of `id`, you can use this user-defined document external ID.
`rendition_type__v`	Rendition type to delete from the document.
`rendition_type__v`	Document rendition type to delete from the document.
`major_version_number__v`	Major version number of the document rendition to remove.
`minor_version_number__v`	Minor version number of the document rendition to remove.

Query String Parameters

Name	Description
`idParam`	If you're identifying documents in your input by their external ID, add `idParam=external_id__v` to the request endpoint.

Delete Single Document Rendition

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/imported_rendition__vs

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, Vault deletes the rendition of specified type from the latest document version.

DELETE /api/{version}/objects/documents/{document_id}/renditions/{rendition_type}

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`

URI Path Parameters

Name	Description
`{document_id}` - The document `id` field value.
`{rendition_type}` - The document rendition type.

Delete Document Version Rendition

Request

Send DELETE to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/renditions/{rendition_type}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0/renditions/imported_rendition__vs

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, Vault deletes the rendition of the given type from the specified version of the document.

Errors

Type	Message	Comments
`OPERATION_NOT_ALLOWED`	Cannot delete `viewable_rendition__v` for document because document falls under one or more legal holds.	You cannot delete or replace renditions which are related to an approved legal hold. Learn more about Legal Hold in Vault Help.

History

Since v1

Document Attachments

Learn about Document Attachments in Vault Help.

Determine if a Document has Attachments

Request

Send GET to /api/{version}/objects/documents/{document_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565

Response (abridged)

{
    ...
    "attachments": [
        {
            "id": 566,
            "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/566"
        },
        {
            "id": 567,
            "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/567"
        }
    ]
}

Shown above, document id 565 has two different attachments: id 566 and id 567. Note that this endpoint does not retrieve the number of versions of each attachment nor the attachment metadata. The "attachments" attribute is displayed in the response for documents in which attachments have been enabled on the document type (even if the document has no attachments).

History

Since v12

List Document Attachments

Request

Send GET to /api/{version}/objects/documents/{document_id}/attachments

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 566,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 2,
            "created_by__v": 46916,
            "created_date__v": "2015-01-14T00:35:01.775Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/566/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/566/versions/2"
                }
            ]
        },
        {
            "id": 567,
            "filename__v": "Site Facilities Contacts.docx",
            "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "size__v": 11483,
            "md5checksum__v": "bddd2e18f40dd09ab4939ddd2acefeac",
            "version__v": 3,
            "created_by__v": 46916,
            "created_date__v": "2015-01-14T00:35:12.320Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/567/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/567/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/567/versions/3"
                }
            ]
        }
    ]
}

Details

Shown above, document id 565 has two different attachments. Attachment id 566 is an image file with two versions. Attachment id 567 is a Word document with three versions. Unlike "regular" document versioning, attachment versioning uses integer numbers beginning with 1 and incrementing sequentially (1, 2, 3,...). There is no concept of major or minor version numbers with attachments.

History

Since v12

Retrieve Document Attachment Metadata

Request

Send GET to /api/{version}/objects/documents/{document_id}/attachments/{attachment_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{attachment_id} - The attachment id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/566

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 566,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 2,
            "created_by__v": 46916,
            "created_date__v": "2015-01-14T00:35:01.775Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/566/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/566/versions/2"
                }
            ]
        }
    ]
}

Details

The md5checksum__v field is calculated on the latest version of the attachment. If an attachment is added which has the same MD5 checksum value as an existing attachment on a given document, the new attachment is not added.

Vault Document Attachments include the following fields (metadata):

Field Name	Description
`id`	ID of the attachment. This is set by the system.
`version__v`	Version of the attachment. Attachment versioning uses integer numbers beginning with 1 and incrementing sequentially (1, 2, 3,...). There is no concept of major or minor version numbers with attachments.
`filename__v`	File name of the attachment.
`description__v`	Optional description added to the attachment. You can add descriptions up to 1000 characters in length.
`format__v`	File format of the attachment. You can add any type of file as an attachment.
`size__v`	File size of the attachment. You can add up to 50 attachments to a document; each must be under 2GB.
`md5checksum__v`	MD5 checksum value calculated for the attachment. To avoid creating identical versions, Vault assigns each a checksum value. When you add an attachment with the same file name and checksum value, Vault ignores the new file and does not version the existing attachment.
`created_by__v`	User ID of the person who created the attachment.
`created_date__v`	Date the attachment was created.
`versions[n]`	List of links to earlier versions of the attachment.

Errors

Error Type	Error Message	Comments
`INVALID_DOCUMENT`	Document not found {id}.	You are trying to retrieve attachments from a document {id} which does not exist.
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to retrieve metadata from an attachment {id} which does not exist on the specified document.

History

Since v12

List Document Attachment Versions

Request

Send GET to /api/{version}/objects/documents/{document_id}/attachments/{attachment_id}/versions

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{attachment_id} - The attachment id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/566/versions

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "version__v": 1,
            "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/566/versions/1"
        },
        {
            "version__v": 2,
            "url": "https://myvault.vaultdev.com/api/v15.0/objects/documents/565/attachments/566/versions/2"
        }
    ]
}

Details

Unlike documents, attachment versions use integer values starting with version 1 and incrementing sequentially (2, 3, 4,...). Attachments do not use major or minor version numbers.

Errors

Error Type	Error Message	Comments
`INVALID_DOCUMENT`	Document not found {id}.	You are trying to retrieve attachments from a document {id} which does not exist.
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to retrieve metadata from an attachment {id} which does not exist on the specified document.
`MALFORMED_URL`	The resource [{id}/versions/{version}] does not exist.	You are trying to retrieve metadata from a specific version {version} of an attachment {id} which does not exist on the specified document. The attachment {id} exists but the version number {version} does not.

History

Since v12

Retrieve Document Attachment Version Metadata

Request

Send GET to /api/{version}/objects/documents/{document_id}/attachments/{attachment_id}/versions/{attachment_version}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{attachment_id} - The attachment id field value.
{attachment_version} - The attachment version__v field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/566/versions/2

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 566,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 2,
            "created_by__v": 46916,
            "created_date__v": "2015-01-14T00:35:01.775Z"
        }
    ]
}

Errors

Error Type	Error Message	Comments
`INVALID_DOCUMENT`	Document not found {id}. You are trying to retrieve attachments from a document {id} which does not exist.
`MALFORMED_URL`	The resource [{id}] does not exist. You are trying to retrieve metadata from an attachment {id} which does not exist on the specified document.
`MALFORMED_URL`	The resource [{id}/versions/{version}] does not exist. You are trying to retrieve metadata from a specific version {version} of an attachment {id} which does not exist on the specified document. The attachment {id} exists but the version number {version} does not.

History

Since v12

Download Document Attachment File

Request

Send GET to /api/{version}/objects/documents/{document_id}/attachments/{attachment_id}/file

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{attachment_id} - The attachment id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/567/file

Response

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="file.pdf"

Details

On SUCCESS, Vault retrieves the latest version of the attachment from the document. The file name is the same as the attachment file name.

The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. When retrieving attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachment downloads (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Errors

Error Type	Error Message	Comments
`INVALID_DOCUMENT`	Document not found {id}.	You are trying to retrieve an attachment from a document {id} which does not exist.
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to retrieve an attachment {id} which does not exist on the specified document.
`MALFORMED_URL`	The resource does not contain attachments.	You are trying to retrieve an attachment from a document which does not have any attachments.

History

Since v12

Download Document Attachment Version File

Request

Send GET to /api/{version}/objects/documents/{document_id}/attachments/{attachment_id}/versions/{attachment_version}/file

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{attachment_id} - The attachment id field value.
{attachment_version} - The attachment version__v field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/567/versions/1/file

Response

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="file.pdf"

Details

On SUCCESS, Vault retrieves the specified version of the attachment from the document. The file name is the same as the attachment file name.

The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. When downloading attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachment downloads (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Errors

Error Type	Error Message	Comments
`INVALID_DOCUMENT`	Document not found {id}.	You are trying to retrieve an attachment from a document {id} which does not exist.
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to retrieve an attachment {id} which does not exist on the specified document.
`MALFORMED_URL`	The resource [{id}/versions/{version}] does not exist.	You are trying to retrieve a specific version {version} of an attachment {id} which does not exist on the specified document. The attachment {id} exists but the version number {version} does not.
`MALFORMED_URL`	The resource does not contain attachments.	You are trying to retrieve an attachment from a document which does not have any attachments.

History

Since v12

Download All Document Attachment Files

Request

Send GET to /api/{version}/objects/documents/{document_id}/attachments/file

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/file

Response

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="Document VV-02839 (v0.1) - attachments.zip"

On SUCCESS, Vault retrieves the latest version of all attachments from the document. The attachments are packaged in a ZIP file with the file name: Document {document number} (v. {major version}.{minor version}) - attachments.zip.

The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. When downloading attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachment downloads (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Errors

Error Type	Error Message	Comments
`INVALID_DOCUMENT`	Document not found {id}.	You are trying to retrieve an attachment from a document {id} which does not exist.
`MALFORMED_URL`	The resource does not contain attachments.	You are trying to retrieve attachments from a document which does not have any attachments.

History

Since v12

Delete Document Attachment

Request

Send DELETE to /api/{version}/objects/documents/{document_id}/attachments/{attachment_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{attachment_id} - The attachment id field value.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/567

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, Vault deletes the specific attachment and all its versions.

Errors

Type	Message	Comments
`INVALID_DOCUMENT`	Document not found {id}.	You are trying to delete an attachment from a document {id} which does not exist.
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to delete an attachment {id} which does not exist on the specified document.
`OPERATION_NOT_ALLOWED`	Operation not allowed because document falls under one or more legal holds.	You cannot delete an attachment if its document falls under one or more legal holds. Learn more about Legal Hold in Vault Help.

History

Since v12

Delete Document Attachment Version

Request

Send DELETE to /api/{version}/objects/documents/{document_id}/attachments/{attachment_id}/versions/{attachment_version}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{attachment_id} - The attachment id field value.
{attachment_version} - The attachment version__v field value.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/567/versions/3

Response

{
    "responseStatus": "SUCCESS"
}

Errors

Type	Message	Comments
`INVALID_DOCUMENT`	Document not found {id}.	You are trying to delete an attachment from a document {id} which does not exist.
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to delete an attachment {id} which does not exist on the specified document.
`OPERATION_NOT_ALLOWED`	Operation not allowed because document falls under one or more legal holds.	You cannot delete an attachment if its document falls under one or more legal holds. Learn more about Legal Hold in Vault Help.

History

Since v12

Add Document Attachment

Request

Send POST to /api/{version}/objects/documents/{document_id}/attachments

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 2GB.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "file=my_attachment_file.png" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments

Response

{
    "responseStatus": "SUCCESS",
    "data":
    {
        "id": "567",
        "version__v": 3
    }
}

Details

On SUCCESS, the response will contain the attachment ID and version of the newly added attachment. Document attachments are automatically bound to all versions of a document. The following attribute values are determined based on the file in the request: filename__v, format__v, size__v.

Errors

Error Type	Error Message	Comments
`INVALID_DOCUMENT`	Document not found {id}.	You are trying to add an attachment from a document {id} which does not exist.
`MALFORMED_URL`	The resource is not enabled for attachments.	You are trying to add an attachment to a document for which attachments have not been enabled.
`OPERATION_NOT_ALLOWED`	Cannot add an attachment : number of allowed attachments exceeds max [50].	You are trying to add an attachment to a document which already has the maximum number of allowed attachments (50).
`OPERATION_NOT_ALLOWED`	Cannot add an attachment : maximum attachment file size exceeds max [{n}].	You are trying to add an attachment to a document which exceeds the maximum file size allowed for an attachment (2GB).

History

Since v12

Restore Document Attachment Version

Request

Send POST to /api/{version}/objects/documents/{document_id}/attachments/{attachment_id}/versions/{attachment_version}?restore=true

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{attachment_id} - The attachment id field value.
{attachment_version} - The attachment version__v field value.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/567/versions/2?restore=true

The parameter restore must be set to true

Response

{
    "responseStatus": "SUCCESS",
    "data":
    {
        "id": "567",
        "version__v": 3
    }
}

On SUCCESS, Vault restores the specific version of an existing attachment to make it the latest version. The response will contain the attachment ID and version of the restored attachment.

Errors

Error Type	Error Message	Comments
`INVALID_DOCUMENT`	Document not found {id}.	You are trying to restore an attachment to a document {id} which does not exist.
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to restore an attachment {id} which does not exist on the specified document.
`MALFORMED_URL`	The resource [{id}/versions/{version}] does not exist.	You are trying to restore a specific version {version} of an attachment {id} to make it the latest version, but the attachment or version do not exist.
`PARAMETER_REQUIRED`	Missing required parameter [restore].	You are trying to restore a specific version of an attachment but did not include the "restore" parameter.
`MALFORMED_URL`	The resource is not enabled for attachments.	You are trying to restore an attachment to a document for which attachments have not been enabled.

History

Since v12

Update Document Attachment Description

Request

Send PUT to /api/{version}/objects/documents/{document_id}/attachments/{attachment_id}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{attachment_id} - The attachment id field value.

Input

description__v - This is the only editable field. The maximum character length is 1000.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "description__v=This is my description for this attachment." \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments

Response

{
    "responseStatus": "SUCCESS"
}

Errors

Error Type	Error Message	Comments
`INVALID_DOCUMENT`	Document not found {id}.	You are trying to update an attachment on a document {id} which does not exist.
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to update an attachment {id} which does not exist on the specified document.
`MALFORMED_URL`	The resource is not enabled for attachments.	You are trying to add or restore an attachment to a document for which attachments have not been enabled.
`INVALID_DATA`	Invalid value [{value}] specified for parameter [description__v] : string exceeds max length [1000].	You are trying to update the attachment description when the description exceeds the maximum character length (1000)

History

Since v12

Document Annotations

Learn about Document Annotations in Vault Help.

Retrieve Document Annotations

Request

Send GET to /api/{version}/objects/documents/{document_id}/annotations

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/14/annotations

Response

On SUCCESS, Vault retrieves the specified version document rendition and its associated annotations.

The HTTP Response Header Content-Type is set to application/pdf.
The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file.

History

Since v12

Retrieve Document Version Annotations

Request

Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/annotations

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/14/versions/2/1/annotations

Response

On SUCCESS, Vault retrieves the specified version document rendition and its associated annotations.

The HTTP Response Header Content-Type is set to application/pdf.
The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file.

History

Since v12

Upload Document Annotations

Request

Send POST to /api/{version}/objects/documents/{document_id}/annotations

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB.

Parameters

{document_id} - The document id field value.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "file=document2016.pdf" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/548/annotations

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "OK",
    "replies": 0,
    "failures": 0,
    "new": 0
}

On SUCCESS, Vault uploads the file and its annotations.

History

Since v12

Upload Document Version Annotations

Request

Send POST to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/annotations

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB.

Parameters

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "file=document2016.pdf" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/548/versions/2/1/annotations

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "OK",
    "replies": 0,
    "failures": 0,
    "new": 0
}

On SUCCESS, Vault associates the uploaded file with the given rendition type for the document with the specified version number.

History

Since v12

Document Relationships

Learn about Document Relationships in Vault Help.

Retrieve Document Type Relationships

Retrieve all relationships from a document type.

Request

Send GET to /api/{version}/metadata/objects/documents/types/{type}/relationships

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{type} - The document type. See Retrieve Document Types.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/relationships

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "properties": [
    {
      "name": "id",
      "type": "id",
      "length": 20,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "source_doc_id__v",
      "type": "id",
      "length": 20,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "source_major_version__v",
      "type": "Integer",
      "length": 10,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "source_minor_version__v",
      "type": "Integer",
      "length": 10,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "target_doc_id__v",
      "type": "id",
      "length": 20,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "target_major_version__v",
      "type": "Integer",
      "length": 10,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "target_minor_version__v",
      "type": "Integer",
      "length": 10,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "relationship_type__v",
      "type": "String",
      "length": 255,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "created_date__v",
      "type": "DateTime",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_by__v",
      "type": "ObjectReference",
      "length": 10,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "source_vault_id__v",
      "type": "id",
      "length": 20,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    }
  ],
  "relationshipTypes": [
    {
      "value": "crosslink_document_latest__v",
      "label": "CrossLink Latest Bindings",
      "sourceDocVersionSpecific": true,
      "targetDocVersionSpecific": false,
      "system": true,
      "singleUse": false,
      "targetDocumentTypes": [
        {
          "label": "Attachment",
          "value": "attachment__v"
        },
        {
          "label": "Template Fragment",
          "value": "template_fragment__v"
        },
        {
          "label": "Integration Template",
          "value": "testing__c"
        },
        {
          "label": "Resources",
          "value": "resources__c"
        },
        {
          "label": "Master Email Fragment",
          "value": "master_email_fragment__v"
        },
        {
          "label": "Promotional Piece",
          "value": "promotional_piece__vs"
        },
        {
          "label": "Email Fragment",
          "value": "email_fragment__v"
        },
        {
          "label": "Multichannel Presentation",
          "value": "engage_presentation__v"
        },
        {
          "label": "Health Authority Form",
          "value": "health_authority_form__v"
        },
        {
          "label": "Email Template",
          "value": "email_template__v"
        },
        {
          "label": "Claim",
          "value": "claim__vs"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__vs"
        },
        {
          "label": "Multichannel Slide",
          "value": "slide__v"
        },
        {
          "label": "Compliance Package",
          "value": "compliance_package__v"
        },
        {
          "label": "Undefined",
          "value": "undefined__v"
        }
      ]
    },
    {
      "value": "references__vs",
      "label": "Linked Documents",
      "sourceDocVersionSpecific": true,
      "targetDocVersionSpecific": true,
      "system": true,
      "singleUse": false,
      "targetDocumentTypes": [
        {
          "label": "Attachment",
          "value": "attachment__v"
        },
        {
          "label": "Template Fragment",
          "value": "template_fragment__v"
        },
        {
          "label": "Integration Template",
          "value": "testing__c"
        },
        {
          "label": "Resources",
          "value": "resources__c"
        },
        {
          "label": "Master Email Fragment",
          "value": "master_email_fragment__v"
        },
        {
          "label": "Promotional Piece",
          "value": "promotional_piece__vs"
        },
        {
          "label": "Email Fragment",
          "value": "email_fragment__v"
        },
        {
          "label": "Multichannel Presentation",
          "value": "engage_presentation__v"
        },
        {
          "label": "Health Authority Form",
          "value": "health_authority_form__v"
        },
        {
          "label": "Email Template",
          "value": "email_template__v"
        },
        {
          "label": "Claim",
          "value": "claim__vs"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__vs"
        },
        {
          "label": "Multichannel Slide",
          "value": "slide__v"
        },
        {
          "label": "Compliance Package",
          "value": "compliance_package__v"
        },
        {
          "label": "Undefined",
          "value": "undefined__v"
        }
      ]
    },
    {
      "value": "crosslink_document_latest_steady_state__v",
      "label": "CrossLink Latest Steady State Bindings",
      "sourceDocVersionSpecific": true,
      "targetDocVersionSpecific": false,
      "system": true,
      "singleUse": false,
      "targetDocumentTypes": [
        {
          "label": "Attachment",
          "value": "attachment__v"
        },
        {
          "label": "Template Fragment",
          "value": "template_fragment__v"
        },
        {
          "label": "Integration Template",
          "value": "testing__c"
        },
        {
          "label": "Resources",
          "value": "resources__c"
        },
        {
          "label": "Master Email Fragment",
          "value": "master_email_fragment__v"
        },
        {
          "label": "Promotional Piece",
          "value": "promotional_piece__vs"
        },
        {
          "label": "Email Fragment",
          "value": "email_fragment__v"
        },
        {
          "label": "Multichannel Presentation",
          "value": "engage_presentation__v"
        },
        {
          "label": "Health Authority Form",
          "value": "health_authority_form__v"
        },
        {
          "label": "Email Template",
          "value": "email_template__v"
        },
        {
          "label": "Claim",
          "value": "claim__vs"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__vs"
        },
        {
          "label": "Multichannel Slide",
          "value": "slide__v"
        },
        {
          "label": "Compliance Package",
          "value": "compliance_package__v"
        },
        {
          "label": "Undefined",
          "value": "undefined__v"
        }
      ]
    },
    {
      "value": "basedon__vs",
      "label": "Based on",
      "sourceDocVersionSpecific": false,
      "targetDocVersionSpecific": true,
      "system": true,
      "singleUse": false,
      "targetDocumentTypes": [
        {
          "label": "Attachment",
          "value": "attachment__v"
        },
        {
          "label": "Template Fragment",
          "value": "template_fragment__v"
        },
        {
          "label": "Integration Template",
          "value": "testing__c"
        },
        {
          "label": "Resources",
          "value": "resources__c"
        },
        {
          "label": "Master Email Fragment",
          "value": "master_email_fragment__v"
        },
        {
          "label": "Promotional Piece",
          "value": "promotional_piece__vs"
        },
        {
          "label": "Email Fragment",
          "value": "email_fragment__v"
        },
        {
          "label": "Multichannel Presentation",
          "value": "engage_presentation__v"
        },
        {
          "label": "Health Authority Form",
          "value": "health_authority_form__v"
        },
        {
          "label": "Email Template",
          "value": "email_template__v"
        },
        {
          "label": "Claim",
          "value": "claim__vs"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__vs"
        },
        {
          "label": "Multichannel Slide",
          "value": "slide__v"
        },
        {
          "label": "Compliance Package",
          "value": "compliance_package__v"
        },
        {
          "label": "Undefined",
          "value": "undefined__v"
        }
      ]
    },
    {
      "value": "original_source__v",
      "label": "Original Source",
      "sourceDocVersionSpecific": false,
      "targetDocVersionSpecific": true,
      "system": false,
      "singleUse": false,
      "targetDocumentTypes": [
        {
          "label": "Attachment",
          "value": "attachment__v"
        },
        {
          "label": "Template Fragment",
          "value": "template_fragment__v"
        },
        {
          "label": "Integration Template",
          "value": "testing__c"
        },
        {
          "label": "Resources",
          "value": "resources__c"
        },
        {
          "label": "Master Email Fragment",
          "value": "master_email_fragment__v"
        },
        {
          "label": "Promotional Piece",
          "value": "promotional_piece__vs"
        },
        {
          "label": "Email Fragment",
          "value": "email_fragment__v"
        },
        {
          "label": "Multichannel Presentation",
          "value": "engage_presentation__v"
        },
        {
          "label": "Health Authority Form",
          "value": "health_authority_form__v"
        },
        {
          "label": "Email Template",
          "value": "email_template__v"
        },
        {
          "label": "Claim",
          "value": "claim__vs"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__vs"
        },
        {
          "label": "Multichannel Slide",
          "value": "slide__v"
        },
        {
          "label": "Compliance Package",
          "value": "compliance_package__v"
        },
        {
          "label": "Undefined",
          "value": "undefined__v"
        }
      ]
    },
    {
      "value": "crosslink_document_static__v",
      "label": "CrossLink Static Bindings",
      "sourceDocVersionSpecific": true,
      "targetDocVersionSpecific": true,
      "system": true,
      "singleUse": false,
      "targetDocumentTypes": [
        {
          "label": "Attachment",
          "value": "attachment__v"
        },
        {
          "label": "Template Fragment",
          "value": "template_fragment__v"
        },
        {
          "label": "Integration Template",
          "value": "testing__c"
        },
        {
          "label": "Resources",
          "value": "resources__c"
        },
        {
          "label": "Master Email Fragment",
          "value": "master_email_fragment__v"
        },
        {
          "label": "Promotional Piece",
          "value": "promotional_piece__vs"
        },
        {
          "label": "Email Fragment",
          "value": "email_fragment__v"
        },
        {
          "label": "Multichannel Presentation",
          "value": "engage_presentation__v"
        },
        {
          "label": "Health Authority Form",
          "value": "health_authority_form__v"
        },
        {
          "label": "Email Template",
          "value": "email_template__v"
        },
        {
          "label": "Claim",
          "value": "claim__vs"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__vs"
        },
        {
          "label": "Multichannel Slide",
          "value": "slide__v"
        },
        {
          "label": "Compliance Package",
          "value": "compliance_package__v"
        },
        {
          "label": "Undefined",
          "value": "undefined__v"
        }
      ]
    }
  ],
  "relationships": [
    {
      "relationship_name": "source__vr",
      "relationship_label": "Source Relationship",
      "relationship_type": "reference_outbound",
      "object": {
        "name": "documents"
      }
    },
    {
      "relationship_name": "target__vr",
      "relationship_label": "Target Relationship",
      "relationship_type": "reference_outbound",
      "object": {
        "name": "documents"
      }
    }
  ]
}

Details

The abridged response above shows the metadata for the relationship type configured for the specified document promotional_piece__vs.

Relationship Fields

The relationships object includes the following fields:

Field Name	Description
`id`	The relationship `id` field.
`source_doc_id__v`	The document `id` field of the source document on which the relationship is defined.
`source_major_version__v`	The `major_version_number__v` of the source document. This is only applies when the target document is bound to a specific version of the source document.
`source_minor_version__v`	The `minor_version_number__v` of the source document. This is only applies when the target document is bound to a specific version of the source document.
`target_doc_id__v`	The document `id` field of the target document which is bound to the source document.
`target_major_version__v`	The `major_version_number__v` of the target document. This is only applies when the source document is bound to a specific version of the target document.
`target_minor_version__v`	The `minor_version_number__v` of the target document. This is only applies when the source document is bound to a specific version of the target document.
`relationship_type__v`	The relationship type (`basedon__vs`, `supporting_documents__vs`, `related_claims__vs`, `related_pieces__vs`, etc.).
`created_date__v`	The date and time when the relationship is created.
`created_by__v`	The user `id` value of the person who creates the relationship.
`source_vault_id__v`	The Vault `id` value where the source document exists. Learn more.

Relationship Type Properties

Relationship types and their properties are configurable and vary from vault to vault.

Metadata Field	Description
`value`	The relationship type name (API key).
`label`	The relationship type label.
`sourceDocVersionSpecific`	Indicates whether or not the relationship type applies to a specific version of the source document. If `false`, the relationship type applies to all versions.
`targetDocVersionSpecific`	Indicates whether or not the relationship type applies to a specific version of the target document. If `false`, the relationship type applies to all versions.
`system`	Indicates whether or not the relationship type is a standard Vault relationship type.
`singleUse`	Indicates whether or not the relationship type can only be used once for each document.
`targetDocumentTypes`	Lists all document types which are valid target documents for the relationship type.

Relationships

The source__vr and target__vr relationship names can be used to perform document relationship lookup queries.

History

Since v3
v10+ - Supports the CrossLink document relationship types (when enabled). v15+ - Includes the original_source__v relationship type (when enabled).

Retrieve Document Relationships

Retrieve all relationships from a document.

Request

Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/relationships

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/866/versions/1/1/relationships

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": null,
  "errorCodes": null,
  "relationships": [
    {
      "relationship": {
        "source_doc_id__v": 886,
        "relationship_type__v": "related_pieces__vs",
        "created_date__v": "2015-12-15T21:42:01.000Z",
        "id": 214,
        "target_doc_id__v": 890,
        "created_by__v": 46916
      }
    },
    {
      "relationship": {
        "source_doc_id__v": 886,
        "relationship_type__v": "related_pieces__vs",
        "created_date__v": "2015-12-15T22:06:28.000Z",
        "id": 216,
        "target_doc_id__v": 884,
        "created_by__v": 46916
      }
    },
    {
      "relationship": {
        "source_doc_id__v": 886,
        "relationship_type__v": "supporting_documents__vs",
        "created_date__v": "2015-12-15T21:41:10.000Z",
        "id": 213,
        "target_doc_id__v": 885,
        "created_by__v": 46916
      }
    },
    {
      "relationship": {
        "source_doc_id__v": 886,
        "relationship_type__v": "supporting_documents__vs",
        "created_date__v": "2015-12-15T22:06:21.000Z",
        "id": 215,
        "target_doc_id__v": 889,
        "created_by__v": 46916
      }
    }
  ],
  "errorType": null
}

Details

On SUCCESS, Vault returns a list of all relationships configured on the document. In this example, document ID 886 v1.1 has reference relationships with four other documents in our vault. This is the source document. Two of the referenced documents - target_doc_id__v 890 and 884 have the related_pieces__vs relationship type. The other two referenced documents - target_doc_id__v 885 and 887 have the supporting_documents__vs relationship type.

History

Since v3

Create Document Relationship

Create a new relationship on a document.

Request

Send POST to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/relationships

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Input

Field Name	Description
`target_doc_id__v`	[Required] The document `id` of the target document.
`relationship_type__v`	[Required] The relationship type retrieved from the Document Relationships Metadata call above.
`target_major_version__v`	[Optional] The major version number of the target document to which the source document will be bound.
`target_minor_version__v`	[Optional] The minor version number of the target document to which the source document will be bound.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "target_doc_id__v=548" \
-d "relationship_type__v=supporting_documents__vs" \
-d "target_major_version__v=0" \
-d "target_minor_version__v=2" \
https://myvault.veevavault.com/api/v15.0/objects/documents/548/versions/0/1/relationships

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document relationship successfully created.",
    "id": 200
}

On SUCCESS, Vault returns the ID of the newly created document relationship.

Errors

Error Type	Error Message	Comments
`INVALID_DATA`	Relationship already exists.	This relationship already exists on the specified document.
`INVALID_DATA`	Cannot create or delete relationship of type [`relationship_type`]	You cannot manually create system-managed relationships, such as Based On or Original Source relationships. Learn more in Vault Help.
`INVALID_DATA`	Document version major {major_version_number__v}, minor {minor_version_number__v} not found for document {document_id}.	The version specified for the document was not found.

History

Since v3

Create Multiple Document Relationships

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Document Relationships\document_relationships.csv" \
https://myvault.veevavault.com/api/v15.0/objects/documents/relationships/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 10
        },
        {
            "responseStatus": "SUCCESS",
            "id": 11
        },       
    ]
}

Create new relationships on a document.

The maximum input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 1000.

POST /api/{version}/objects/documents/relationships/batch

Headers

Name	Description
`Content-Type`	`application/json` or `text/csv`
`Accept`	`application/json` (default) or `text/csv`

Body Parameters

Create a JSON or CSV input file. There are multiple ways to create document relationships. The following standard fields are required to create document relationships.

Name	Description
`source_doc_id__v`	Document `id` value of the document on which the relationship is being created.
`target_doc_id__v`	Document `id` value of the document which is being associated with the source document as a related document.
`relationship_type__v`	The type of relationship the target document will have with the source document.

Retrieve Document Relationship

Retrieve details of a specific document relationship.

Request

Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/relationships/{relationship_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0/relationships/200

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": null,
    "errorCodes": null,
    "relationships": [
        {
            "relationship": {
                "id": 200,
                "source_doc_id__v": 534,
                "relationship_type__v": "supporting_documents__vs",
                "created_by__v": 46916,
                "created_date__v": "2015-03-20T20:44:56.000Z",
                "target_doc_id__v": 548
            }
        }
    ],
    "errorType": null
}

Details

Field Name	Description
`id`	Relationship ID
`source_doc_id__v`	The source document `id` field value.
`relationship_type__v`	The relationship type.
`target_doc_id__v`	The target document `id` field value.
`created_by__v`	The user `id` field value of the person who created the relationship.
`created_date__v`	The date and time when the relationship was created.

History

Since v3

Delete Document Relationship

Delete a relationship from a document.

Request

Send DELETE to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/relationships/{relationship_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0/relationships/200

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document relationship successfully deleted.",
    "id": 200
}

On SUCCESS, Vault returns the relationship ID of the deleted relationship.

Errors

Type	Message	Comments
`OPERATION_NOT_ALLOWED`	Operation not allowed because document falls under one or more legal holds.	You cannot delete a document relationship if the document is in an approved legal hold. Learn more about Legal Hold in Vault Help.

History

Since v3

Delete Multiple Document Relationships

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Document Relationships\document_relationships.csv" \
https://myvault.veevavault.com/api/v15.0/objects/documents/relationships/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 10
        },
        {
            "responseStatus": "SUCCESS",
            "id": 11
        },       
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this relationship was not deleted."
                }
            ]
        }
    ]
}

Delete multiple relationship from a document.

The maximum input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 1000.

DELETE /api/{version}/objects/documents/relationships/batch

Headers

Name	Description
`Content-Type`	`application/json` (default) or `text/csv`
`Accept`	`application/json` (default) or `text/csv`

Body Parameters

Create a CSV or JSON input file.

Name	Description
`id`	The ID of the relationship to delete.

Response Details

On SUCCESS, Vault returns the relationship IDs of the deleted relationships.

Document Events

Learn about Document Events in Vault Help.

Retrieve Document Event Types and Subtypes

Request

Send GET to /api/{version}/metadata/objects/documents/events

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/events

Response

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "name": "distribution__v",
            "label": "Distribution Event",
            "subtypes": [
                {
                    "name": "approved_email__v",
                    "label": "Approved Email",
                    "value": "https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/events/distribution__v/types/approved_email__v"
                },
                {
                    "name": "controlled_copy__v",
                    "label": "Controlled Copy",
                    "value": "https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/events/distribution__v/types/controlled_copy__v"
                },
                {
                    "name": "irep__v",
                    "label": "CRM",
                    "value": "https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/events/distribution__v/types/irep__v"
                },
                {
                    "name": "engage__v",
                    "label": "Engage",
                    "value": "https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/events/distribution__v/types/engage__v"
                },
                {
                    "name": "published_content__v",
                    "label": "Published Content",
                    "value": "https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/events/distribution__v/types/published_content__v"
                },
                {
                    "name": "clm__v",
                    "label": "CLM",
                    "value": "https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/events/distribution__v/types/clm__v"
                }
            ]
        }
    ]
}

Details

On SUCCESS, Vault returns the 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. In this example, one document event distribution__v is configured in our vault. This "Distribution Event" is configured with six document event "subtypes".

History

Since v6

Retrieve Document Event SubType Metadata

Request

Send GET to /api/{version}/metadata/objects/documents/events/{event_type}/types/{event_subtype}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/events/distribution__v/types/approved_email__v

Response

{
    "responseStatus": "SUCCESS",
    "name": "approved_email__v",
    "label": "Approved Email",
    "properties": [
        {
            "name": "event_date__v",
            "label": "Event Date",
            "type": "DateTime",
            "queryable": true,
            "systemAttribute": true
        },
        {
            "name": "document_id__v",
            "label": "Document ID",
            "type": "ObjectReference",
            "objectType": "Documents",
            "queryable": true
        },
        {
            "name": "major_version_number__v",
            "label": "Document Major Version Number",
            "type": "Number",
            "queryable": true
        },
        {
            "name": "minor_version_number__v",
            "label": "Document Minor Version Number",
            "type": "Number",
            "queryable": true
        },
        {
            "name": "triggered_by__v",
            "label": "User ID",
            "type": "ObjectReference",
            "objectType": "Users",
            "queryable": true,
            "systemAttribute": true
        },
        {
            "name": "event_type__v",
            "label": "Event Type",
            "type": "String",
            "required": true,
            "queryable": true
        },
        {
            "name": "event_subtype__v",
            "label": "Event Subtype",
            "type": "String",
            "required": true,
            "queryable": true
        },
        {
            "name": "classification__v",
            "label": "Event Classification",
            "type": "String",
            "values": [
                {
                    "name": "distribute__v",
                    "label": "Distribute"
                },
                {
                    "name": "view__v",
                    "label": "View"
                },
                {
                    "name": "download__v",
                    "label": "Download"
                }
            ],
            "required": true,
            "queryable": true
        },
        {
            "name": "external_id__v",
            "label": "External ID",
            "type": "String",
            "required": true,
            "queryable": true
        },
        {
            "name": "user_email__v",
            "label": "User Email",
            "type": "String",
            "required": true,
            "queryable": true
        },
        {
            "name": "document_title__v",
            "label": "Document Title",
            "type": "String",
            "queryable": true,
            "systemAttribute": true
        },
        {
            "name": "document_number__v",
            "label": "Document Number",
            "type": "String",
            "queryable": true,
            "systemAttribute": true
        },
        {
            "name": "document_name__v",
            "label": "Document Name",
            "type": "String",
            "queryable": true,
            "systemAttribute": true
        }
    ]
}

On SUCCESS, Vault returns all metadata for the specified event subtype.

History

Since v6

Create Document Event

Request

Send POST to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/events

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Input

Provide the name-value pairs consisting of all required fields and the values for the event subtype specified.
The required fields are obtained from the event subtype metadata (described above).
You can use either field value names or labels for the event_type__v, event_subtype__v and classification__v field values in the request.
The Approved Email event subtype metadata shows the five event fields below as required.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "event_type__v=distribution__v" \
-d "event_subtype__v=approved_email__v" \
-d "classification__v=download__v" \
-d "external_id__v=1234"
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0/events

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, Vault logs the document event.

Errors

Error Type	Error Message	Comments
`INSUFFICIENT_ACCESS`	You do not have permission to log an event of specified type.
`INVALID_DATA`	The value specified for the parameter is invalid (validation error).	As part of the error, a list of all fields which have an error will be returned.
`PARAMETER_REQUIRED`	A required parameter is not provided.	As part of the error, a list of all missing parameters will be returned.
`METHOD_NOT_SUPPORTED`	The URL is constructed with an invalid event type.	This also includes other endpoint related errors.

History

Since v6

Retrieve Document Events

Request

Send GET to /api/{version}/objects/documents/{document_id}/events

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.

Input

You can include one or more queryable event fields and associated values in the request parameters to filter the response. For example:
Specifying event_type__v=Distribution will return only distribution events.
Specifying event_type__v=Distribution&event_subtype__v=Approved Email will return only distribution events generated for/by Approved Email.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/534/events

Response

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "name": "download__v",
            "label": "Approved Email Download",
            "properties": {
                "event_date__v": "2015-03-20T22:06:40.000Z",
                "document_id__v": 534,
                "major_version_number__v": 2,
                "minor_version_number__v": 0,
                "triggered_by__v": 46916,
                "event_type__v": "Distribution Event",
                "event_subtype__v": "Approved Email",
                "classification__v": "Download",
                "external_id__v": "1234",
                "user_email__v": "quinntaylor@myemail.com",
                "event_modified_by__v": 46916,
                "event_modified_date__v": "2015-03-20T22:06:40.000Z",
                "document_number__v": "REF-0059",
                "document_name__v": "Wonderdrug Information"
            }
        }
    ]
}

Details

On SUCCESS, Vault returns the list of event objects, each containing the fields as defined by the metadata for its event type. Null and/or false valued fields are omitted from the response.

History

Since v6

Document Templates

Learn about Document Templates in Vault Help.

Retrieve Document Template Metadata

Retrieve the metadata which defines the shape of document templates in your vault.

Request

Send GET to /api/{version}/metadata/objects/documents/templates

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/templates

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "name": "name__v",
      "type": "String",
      "requiredness": "required",
      "max_length": 50,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "label__v",
      "type": "String",
      "requiredness": "required",
      "max_length": 100,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "active__v",
      "type": "Boolean",
      "requiredness": "required",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "type__v",
      "type": "Component",
      "requiredness": "required",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "subtype__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "classification__v",
      "type": "Component",
      "requiredness": "optional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "format__v",
      "type": "String",
      "requiredness": "required",
      "max_length": 200,
      "editable": false,
      "multi_value": false
    },
    {
      "name": "size__v",
      "type": "Number",
      "requiredness": "required",
      "max_value": 9223372036854775807,
      "min_value": 0,
      "scale": 0,
      "editable": false,
      "multi_value": false
    },
    {
      "name": "created_by__v",
      "type": "Number",
      "requiredness": "required",
      "max_value": 9223372036854775807,
      "min_value": 0,
      "scale": 0,
      "editable": false,
      "multi_value": false
    },
    {
      "name": "file_uploaded_by__v",
      "type": "Number",
      "requiredness": "required",
      "max_value": 9223372036854775807,
      "min_value": 0,
      "scale": 0,
      "editable": false,
      "multi_value": false
    },
    {
      "name": "md5checksum__v",
      "type": "String",
      "requiredness": "required",
      "max_length": 100,
      "editable": false,
      "multi_value": false
    }
  ]
}

Details

Field Name	Field Type	Description	Required	Editable
`name__v`	String	Document template name. Used in the API when retrieving/creating/updating templates.	True	True
`label__v`	String	Document template label. The name users see in the UI when selecting templates.	True	True
`active__v`	Boolean	Indicates whether or not the template is available for creating documents.	True	True
`type__v`	Component	The document type to which the template is associated.	True	True
`subtype__v`	Component	The document subtype to which the template is associated.	Conditional *	True
`classification__v`	Component	The document classification to which the template is associated.	Conditional *	True
`format__v`	String	Document template format (.doc, .pdf, etc.).	System-Managed	False
`size__v`	Number	Document template size (Kb).	System-Managed	False
`created_by__v`	Number	Vault user ID of the person who created the template.	System-Managed	False
`file_uploaded_by__v`	Number	Vault user ID of the person who uploaded the template file.	System-Managed	False
`md5checksum__v`	String	A string calculated using MD5 algorithm that can be used to uniquely identify the source file.	System-Managed	False

The document subtype and classification fields are "conditional" in that they are only required if the template exists at the document subtype or classification level.

History

Since v13

Retrieve Document Template Collection

Retrieve all document templates.

Request

Send GET to /api/{version}/objects/documents/templates

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "name__v":"claim_document_template__c",
         "label__v":"Claim Document Template",
         "active__v":true,
         "type__v":"claim__vs",
         "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
         "size__v": 2781904,
         "created_by__v": 12021,
         "file_uploaded_by__v": 12021,
         "md5checksum__v": 98238947109287333
      },
      {
         "name__v":"clinical_study_document_template__c",
         "label__v":"Clinical Study Document Template",
         "active__v":true,
         "type__v":"reference_document__vs",
         "subtype__v":"clinical_study__vs",
         "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
         "size__v": 15776,
         "created_by__v": 12021,
         "file_uploaded_by__v": 12021,
         "md5checksum__v": 75886214401031117
      },
      {
         "name__v":"promo_ad_print_document_template__c",
         "label__v":"Promo Ad Print Document Template",
         "active__v":true,
         "type__v":"promotional_piece__vs",
         "subtype__v":"advertisement__vs",
         "classification__v":"print__vs",
         "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
         "size__v": 82923,
         "created_by__v": 12021,
         "file_uploaded_by__v": 12021,
         "md5checksum__v": 52478042594365555
      }     
   ]
}

Details

The response lists all document templates which have been added to the vault. Shown above, three document templates exist in our vault:

The first claim_document_template__c exists at the document type level. It is intended for use with new documents of the claim__vs type.
The second clinical_study_document_template__c exists at the document subtype level. It is intended for use with new documents of the clinical_study__vs subtype.
The third promo_ad_print_document_template__c exists at the document classification level. It is intended for use with new documents of the print__vs classification.

For information about the document template metadata, refer to the "Retrieve Document Template Attributes" response below.

History

Since v13

Retrieve Document Template Attributes

Retrieve the attributes from a document template.

Request

Send GET to /api/{version}/objects/documents/templates/{template_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{template_name} - The document template name__v field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates/promo_ad_print_document_template__c

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "name__v":"promo_ad_print_document_template__c",
         "label__v":"Promo Ad Print Document Template",
         "active__v":true,
         "type__v":"promotional_piece__vs",
         "subtype__v":"advertisement__vs",
         "classification__v":"print__vs",
         "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
         "size__v": 82923,
         "created_by__v": 12021,
         "file_uploaded_by__v": 12021,
         "md5checksum__v": 52478042594365555
      }     
   ]
}

Details

The response lists all attributes configured on a specific document template in the vault. Shown above are the attributes configured on the specified template:

Field Name	Description
`name__v`	Name of the document template. This value is not displayed to end users in the UI. It is seen by Admins and used in the API.
`label__v`	Label of the document template. When users in the UI create documents from templates, they see this value in the list of available templates.
`type__v`	Vault document type to which the template is associated.
`subtype__v`	Vault document subtype to which the template is associated. This field is only displayed if the template exists at the document subtype or classification level.
`classification__v`	Vault document classification to which the template is associated. This field is only displayed if the template exists at the document classification level. The template shown in this response is configured for use with documents of the `print__vs` classification.
`format__v`	File format of the document template.
`size__v`	Size of the document template (Kb).
`created_by__v`	Vault user ID of the person who created the document template.
`file_uploaded_by__v`	Vault user ID of the person who uploaded the document template.
`md5checksum__v`	A string calculated using MD5 algorithm that can be used to uniquely identify the source file.

History

Since v13

Download Document Template File

Download the file of a specific document template.

Request

Send GET to /api/{version}/objects/documents/templates/{template_name}/file

Headers

Response Accept - JSON application/json (default) or XML application/xml
For this request, the Accept header controls only the error response. On SUCCESS, the response is a file stream (download).

Parameters

{template_name} - The document template name__v field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates/claim_document_template__c/file

Response

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="claim_document_template__c.pdf"

Details

On SUCCESS, Vault retrieves the document template file.

The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. When retrieving templates with very small file size, the HTTP Response Header Content-Length is set to the size of the template file. Note that for template downloads of larger file sizes, the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

History

Since v13

Create Document Template

Upload one document template. To upload multiple document templates, see Bulk Create Document Templates.

Request

Send POST to /api/{version}/objects/documents/templates

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB.

Input

When creating document templates, the following fields are required in all vaults:

Field Name	Description
`name__v`	The name of the new document template. If not included, Vault will use the specified `label__v` value to generate a value for the `name__v` field.
`label__v`	The label of the new document template. This is the name users will see among the available binder templates in the UI.
`type__v`	The name of the document type to which the template will be associated.
`subtype__v`	The name of the document subtype to which the template will be associated. This is only required if associating the template with a document subtype.
`classification__v`	The name of the document classification to which the template will be associated. This is only required if associating the template with a document classification.
`active__v`	Set to true or false to indicate whether or not the new document template should be set to active, i.e., available for selection when creating a document.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-H "Accept: text/csv" \ 
-F "file=Promo Ad Template.docx" \
-F "label__v=Promo Ad Template" \
-F "type__v=promotional_piece__vs" \
-F "subtype__v=advertisement__vs" \
-F "classification__v=print__vs" \
-F "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates

Details

The input format is set to multipart/form-data (name-value pair with file upload).
The response format is set to text/csv.
The path/name of the document template source file on the FTP staging server is specified.
The name__v field is not included. Vault will use the specified label__v field value to create the name__v=promo_ad_template__c
The label__v field specifies the document template label "Promo Ad Template". This is what users will see among the available templates in the UI.
The document type__v, subtype__v, and classification__v are all specified. This template is being created for documents of classification__v=print__vs.
The template is being set to active__v=true. It will be available for selection when creating a new document.

Response

responseStatus,name,errors
SUCCESS,promo_ad_template__c,

On SUCCESS, Vault returns the name of the new document template.

Errors

Refer to the Bulk Create Document Templates Errors section below.

History

Since v13

Bulk Create Document Templates

Upload from 1-500 document templates. To upload one document template, see Create Document Template.

Request

Send POST to /api/{version}/objects/documents/templates

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml

File Upload

Before submitting this request, you must upload the document template source files to the staging server.
Then, in your JSON or CSV input, include the file parameter set to the {path/file_name} of each source file on the server.

Input

When creating document templates, the following fields are required in all vaults:

Field Name	Description
`name__v`	The name of the new document template. If not included, Vault will use the specified `label__v` value to generate a value for the `name__v` field.
`label__v`	The label of the new document template. This is the name users will see among the available binder templates in the UI.
`type__v`	The name of the document type to which the template will be associated.
`subtype__v`	The name of the document subtype to which the template will be associated. This is only required if associating the template with a document subtype.
`classification__v`	The name of the document classification to which the template will be associated. This is only required if associating the template with a document classification.
`active__v`	Set to true or false to indicate whether or not the new document template should be set to active, i.e., available for selection when creating a document.

Example CSV Input

`file`	`name__v`	`label__v`	`type__v`	`subtype__v`	`classification__v`	`active__v`
templates/doc_template_1.doc	site_document_template__c	SMF Template	site_master_file__v			true
templates/doc_template_2.doc		TMF Document Template	trial_master_file__v			true
templates/doc_template_3.doc		Trial Protocol Document Template	central_trial_documents__vs	trial_documents__vs	protocol__vs	true
templates/doc_template_4.doc		Clinical Study Report Document Template	central_trial_documents__vs	reports__vs	clinical_study_report__vs	false

In this example input, we're creating four new document templates in our vault:

We've included the file parameter with the path/name of four document template source files located in the "templates" directory of our vault's staging server.
We've only specified the name__v value for the first template and given it a different label__v value. The other templates will inherit their name__v values from the label__v values.
We've specified the document type, subtype, and classification to which each document template will be associated.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Templates\add_document_templates.csv" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates

In this example:

The input file format is set to CSV.
The response format is not set and will default to JSON.
The path/name of the CSV input file in our local directory is specified.

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "name":"site_document_template__c"
      },
      {
         "responseStatus":"SUCCESS",
         "name":"tmf_document_template__c"
      },
      {
         "responseStatus":"SUCCESS",
         "name":"trial_protocol_document_template__c"
      },      
      {
         "responseStatus":"FAILURE",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this template was not created."
            }
         ]
      }
   ]
}

Errors

Error Type	Error Message	Comments
`INVALID_DATA`	Cannot parse the request body.	The input contains information which cannot be parsed by the API.
`INVALID_DATA`	Cannot process the request : max 500 records expected.	The input has more than 500 records (not allowed).
`INVALID_DATA`	Cannot parse the request body : at least 1 record is expected.	The input has no records (at least one is required).
`INVALID_DATA`	Cannot create document : source file [{FILE_NAME}] not found.	When creating new document templates, you must first upload the template source files to the FTP staging server. The file value in the input may contain either a single filename (if the file is located at the root of the FTP staging server) or a full path to the file (relative to the FTP root). If the API cannot find the file in the specified location, this error is returned for that row in the input.
`REQUIRED_PARAMETER`	Missing required parameter [{field_name}].	A required field is missing from the input. The error message includes the missing field name.
`INVALID_VALUE`	Invalid value [{FIELD_VALUE]} specified for parameter [{PARAMETER}].	A field value specified in the input is invalid. The error message includes invalid value and field name on which it is specified.
`INVALID_DATA`	Cannot create template : another template already exists with [name__v={specified name}].	The name specified for the template is a duplicate of an existing document template in your vault.
`INVALID_DATA`	Cannot create template : input already defines another template with [name__v={specified name}].	The name specified for the template is a duplicate of another template name specified in the same input.
`INVALID_DATA`	String exceeds max length [{MAX_VALUE}].	The string value exceeds the maximum length for the `label__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{type}].	An invalid value is specified for the `type__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{subtype}] under [{Value specified for `type__v`}].	An invalid value is specified for the `subtype__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{classification}] under [{Value specified for `classification__v`}].	An invalid value is specified for the `classification__v` field.

History

Since v13

Update Document Template

Update a document template to your vault.

See also: Bulk Update Document Templates below

Request

Send PUT to /api/{version}/objects/documents/templates/{template_name}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{template_name} - The document template name__v field value.

Input

You can update the following fields on document templates:

Field Name	Description
`name__v`	Change the name of an existing document template.
`label__v`	Change the label of an existing document template. This is the name users will see among the available document templates in the UI.
`type__v`	Change the document type to which the template is associated.
`subtype__v`	Change the document subtype to which the template is associated. This is only required if associating the template with a document subtype.
`classification__v`	Change the document classification to which the template is associated. This is only required if associating the template with a document classification.
`active__v`	Set to true or false to indicate whether or not the document template should be set to active, i.e., available for selection when creating a document.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: text/csv" \ 
-d "name__v=promo_ad_web_document_template__c" \
-d "label__v=Promo Ad Web Document Template" \
-d "type__v=promotional_piece__vs" \
-d "subtype__v=advertisement__vs" \
-d "classification__v=web__vs" \
-d "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates/promo_ad_print_document_template__c

In this example:

The input format is set to application/x-www-form-urlencoded.
The response format is set to text/csv.
The new name__v field is specified.
The new label__v field is specified. This is what users will see among the available templates in the UI.
The document type__v, subtype__v, and classification__v are all specified. This template is being updated for documents of classification__v=web__vs.
The template is being set to active__v=true.

Response

responseStatus,name,errors
SUCCESS,promo_ad_web_document_template__c,

Errors

Refer to the Bulk Update Document Templates Errors section below.

History

Since v13

Bulk Update Document Templates

Update from 1-500 document templates to your vault.

See also: Update [Single] Document Template above.

Request

Send PUT to /api/{version}/objects/documents/templates

Headers

Input Content-Type - JSON application/json (default) or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml

Input

You can update the following fields on document templates:

Field Name	Description
`name__v`	Change the name of an existing document templates.
`label__v`	Change the label of an existing document templates. This is the name users will see among the available binder templates in the UI.
`type__v`	Change the document type to which the templates are associated.
`subtype__v`	Change the document subtype to which the templates are associated. This is only required if associating templates with document subtypes.
`classification__v`	Change the document classification to which the templates are associated. This is only required if associating templates with document classifications.
`active__v`	Set to true or false to indicate whether or not the document templates should be set to active, i.e., available for selection when creating a document.

Example CSV Input

See Bulk Create Document Templates above for example inputs, which are the same as those used in this request.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Templates\update_document_templates.csv" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates

In this example:

The input file format is set to CSV.
The response format is not set and will default to JSON.
The path/name of the CSV input file is specified.

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "name":"claim_document_template__c"
      },
      {
         "responseStatus":"SUCCESS",
         "name":"clinical_study_document_template__c"
      },
      {
         "responseStatus":"FAILURE",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this template was not created."
            }
         ]
      }
   ]
}

Errors

Error Type	Error Message	Comments
`INVALID_DATA`	Cannot parse the request body.	The input contains information which cannot be parsed by the API.
`INVALID_DATA`	Cannot process the request : max 500 records expected.	The input has more than 500 records (not allowed).
`INVALID_DATA`	Cannot parse the request body : at least 1 record is expected.	The input has no records (at least one is required).
`INVALID_DATA`	Cannot update document : source file [{FILE_NAME}] not found.	When updating document template files, you must first upload the template source files to the FTP staging server. The file value in the input may contain either a single filename (if the file is located at the root of the FTP staging server) or a full path to the file (relative to the FTP root). If the API cannot find the file in the specified location, this error is returned for that row in the input.
`INVALID_VALUE`	Invalid value [{FIELD_VALUE]} specified for parameter [{PARAMETER}].	A field value specified in the input is invalid. The error message includes invalid value and field name on which it is specified.
`INVALID_DATA`	Cannot create template : another template already exists with [name__v={specified name}].	The name specified for the template is a duplicate of an existing document template in your vault.
`INVALID_DATA`	Cannot create template : input already defines another template with [name__v={specified name}].	The name specified for the template is a duplicate of another template name specified in the same input.
`INVALID_DATA`	String exceeds max length [{MAX_VALUE}].	The string value exceeds the maximum length for the `label__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{type}].	An invalid value is specified for the `type__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{subtype}] under [{Value specified for `type__v`}].	An invalid value is specified for the `subtype__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{classification}] under [{Value specified for `classification__v`}].	An invalid value is specified for the `classification__v` field.

History

Since v13

Delete Document Template

Delete a document template from your vault.

Request

Send DELETE to /api/{version}/objects/documents/templates/{template_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{template_name} - The document template name__v field value.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates/promo_ad_web_document_template__c

Response

{
    "responseStatus": "SUCCESS"
}

History

Since v13

Document Tokens

The Vault Document Tokens API allows you to generates document access tokens needed by the external viewer to view documents outside of Vault. Learn more.

Request

Send POST to /api/{version}/objects/documents/tokens

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Document IDs:

Required - Include the docIds request parameter with a comma-separated string of document id values. This will generate tokens for each document. For example: docIds=101,102,103,104

Token Expiration Date:

Optional - Include the expiryDateOffset request parameter set to the number of days after which the tokens will expire and the documents will no longer be available in the viewer. If not specified, the tokens will expire after 10 years by default.

Download Option:

Optional - Include the downloadOption request parameter set to PDF, source, both, or none. These allow users viewing the document to be able to download a PDF version or source version (Word, PPT, etc.) of the document. If not specified, the download options default to those set on each document.

Distribution Channel:

Optional - Include the channel request parameter set to the website object record id value that corresponds to the distribution channel where the document is being made available.

Token Groups:

Optional - Include the tokenGroup request parameter. This only required if you want to group together generated tokens for multiple documents in order to display the documents being referenced in the same viewer. This value accepts strings of alphanumeric characters (a-z, A-Z, 0-9, and single consecutive underscores) up to 255 characters in length.

The token that is passed as a URL parameter to the External Viewer is the primary token and the document it references will be displayed normally. However, any additional documents that have tokens generated with the same case-sensitive tokenGroup string will be displayed in a sidebar of the viewer.

The order of documents in the sidebar depends on the order in which the tokens are generated. If multiple tokens are generated with one request, the documents will be ordered top-to-bottom based on the order they are passed to the docIds parameter.

For example: If passing the parameters docIds=101,102,103,104 and tokenGroup=group_1 with the request, the top-to-bottom order in the sidebar will be documents 101, 102, 103, 104. If a new request is then made with the parameters docIds=105 and tokenGroup=group_1, document 105 will be added below document 104 in the previous list.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIds=101,102,103,104" \
-d "expiryDateOffset=90" \
-d "downloadOption=PDF" \
-d "channel=00W000000000301" \
https://myvault.veevavault.com/api/v15.0/objects/documents/tokens

Response

{
    "responseStatus": "SUCCESS",
    "tokens": [
        {
            "document_id__v": 101,
            "token__v": "3003-cb6e5c3b-4df9-411c-abc2-6e7ae120ede7"
        }
        {
            "document_id__v": 102,
            "token__v": "3003-1174154c-ac8e-4eb9-b453-2855de273bec"
        },
        {
            "document_id__v": 103,
            "token__v": "3003-51ca652c-36d9-425f-894f-fc2f42601fa9"
        },        
        {
            "document_id__v": 104,
            "errorType": "OPERATION_NOT_ALLOWED",
            "errors": [
                {
                    "type": "INVALID_DOCUMENT",
                    "message": "Document not found [104]."
                }
            ]
        }
    ]
}

Details

In the example above, tokens are generated for the first three documents. The fourth document could not be found. This indicates either an incorrect document id or that the specified document is a binder.

History

Since v12

Binders

Binders organize documents, 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.

Learn about Documents & Binders in Vault Help.

Retrieve Binders

Retrieve All Binders

In Vault, binders are just another kind of document. Therefore, to retrieve a list of all binders in your vault, you must use the same API endpoint to retrieve documents: /api/{version}/objects/documents. By searching the response, you can distinguish binders from "regular" documents by using the document field binder__v set to true or false. See the response details below. Note that nested binders (a binder contained within another binder) are not retrieved.

Alternatively, you can use VQL to find just binders (SELECT id FROM documents WHERE binder__v=true). See the Vault Query API Overview article for details.

Request

Send GET to /api/{version}/objects/documents

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/documents

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "size": 77,
  "start": 0,
  "limit": 200,
  "documents": [
    {
      "document": {
        "id": 101,
        "binder__v": true,
        "coordinator__v": {
          "groups": [],
          "users": [
            25525,
            25513,
            25514
          ]
        },
        ...
        "version_creation_date__v": "2015-03-11T22:04:44.725Z",
        "major_version_number__v": 0,
        "annotations_links__v": 0,
        "annotations_all__v": 0,
        "status__v": "Planned",
        "language__v": [
          "English"
        ],
        "product__v": [
          "1357662840171"
        ],
        "version_created_by__v": 25524,
        "country__v": [],
        "annotations_anchors__v": 0,
        "document_number__v": "VV-00127",
        "minor_version_number__v": 1,
        "lifecycle__v": "General Lifecycle",
        "crosslink__v": false,
        "annotations_notes__v": 0,
        "name__v": "CholeCap Presentation",
        ...

      "document": {
        "id": 102,
        "binder__v": false,
        "coordinator__v": {
          "groups": [],
          "users": [
            25514,
            25525,
            25513
          ]
        },
        ...
        "format__v": "application/pdf",
        "version_creation_date__v": "2014-04-16T21:14:11.235Z",
        "major_version_number__v": 1,
        "annotations_links__v": 9,
        "annotations_all__v": 9,
        "status__v": "Approved for Distribution",
        "language__v": [
          "English"
        ],
        "filename__v": "NYAXA 3 Page Magazine Spread.pdf",
        "product__v": [
          "00P000000000101"
        ],
        "version_created_by__v": 25513,
        "country__v": [
          "1357662840400"
        ],
        "annotations_anchors__v": 0,
        "document_number__v": "PP-NYA-US-0001",
        "minor_version_number__v": 0,
        "lifecycle__v": "Promotional Piece",
        "subtype__v": "Advertisement",
        "crosslink__v": false,
        "annotations_notes__v": 0,
        "classification__v": "Print",
        "name__v": "Nyaxa Print Ad",
        ...
      }
    }

Details

The abridged response above shows the field names and values configured on two separate documents in our vault:

The first record retrieved "id": 101 has the binder__v field value set to true: "binder__v": true. This document is a "binder".
The second record retrieved "id": 102 has the binder__v field value set to false: "binder__v": false. This document is a "regular" document.

Using this endpoint allows you to retrieve all documents in your vault and distinguish those which are "documents" from those which are "binders".

Note that for binders, this response does not show the binder section node tree structure.
To retrieve all metadata configured on a binder, including the section nodes, you must use the binder IDs retrieved from this request in the **Retrieve Binder" endpoint described below.

History

Since v1
v5+ - Includes the binder__v true/false field to distinguish between documents and binders.

Retrieve Binder

Use this endpoint to retrieve all fields and values configured on a specific binder in you vault (using the binder ID).
The response includes the "first level" of the binder section node structure.
To retrieve additional levels in the binder section node structure, use one of the depth parameters described below.

Request

Send GET to /api/{version}/objects/binders/{binder_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Options

To retrieve all levels (depths) of the binder, include the ?depth=all.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/29

Response

{
  "responseStatus": "SUCCESS",
  "document": {
    "id": 29,
    "binder__v": true,
    "coordinator__v": {
      "groups": [],
      "users": [
        63606
      ]
    },
    "owner__v": {
      "groups": [],
      "users": [
        46916
      ]
    },
    "approver__v": {
      "groups": [],
      "users": [
        25524
      ]
    },
    "reviewer__v": {
      "groups": [],
      "users": [
        60145
      ]
    },
    "distribution_contacts__v": {
      "groups": [],
      "users": []
    },
    "viewer__v": {
      "groups": [
        3
      ],
      "users": []
    },
    "consumer__v": {
      "groups": [],
      "users": [
        60145
      ]
    },
    "editor__v": {
      "groups": [],
      "users": [
        25496
      ]
    },
    "version_creation_date__v": "2016-03-09T21:55:22.000Z",
    "major_version_number__v": 0,
    "lifecycle__v": "Field Medical",
    "subtype__v": "Training Materials",
    "annotations_links__v": 0,
    "annotations_notes__v": 0,
    "name__v": "VeevaProm Info Binder",
    "locked__v": false,
    "annotations_all__v": 0,
    "status__v": "Draft",
    "type__v": "Field Medical",
    "description__v": "",
    "annotations_unresolved__v": 0,
    "last_modified_by__v": 46916,
    "product__v": [
      "00P000000000102"
    ],
    "version_created_by__v": 46916,
    "document_creation_date__v": "2016-03-09T20:42:18.692Z",
    "country__v": [
      "00C000000000109"
    ],
    "annotations_anchors__v": 0,
    "document_number__v": "VV-MED-00029",
    "annotations_resolved__v": 0,
    "annotations_lines__v": 0,
    "version_modified_date__v": "2016-03-09T21:55:22.000Z",
    "created_by__v": 46916,
    "minor_version_number__v": 2
  },
  "versions": [
    {
      "number": "0.1",
      "value": "https://medcomms-veevapharm.vaultdev.com/api/v15.0/objects/binders/29/versions/0/1"
    },
    {
      "number": "0.2",
      "value": "https://medcomms-veevapharm.vaultdev.com/api/v15.0/objects/binders/29/versions/0/2"
    }
  ],
  "binder": {
    "nodes": [
      {
        "properties": {
          "document_id__v": 7,
          "name__v": "VeevaProm Information",
          "order__v": 0,
          "type__v": "document",
          "id": "1457556160448:810987462",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "document_id__v": 2,
          "name__v": "VeevaProm Consumer Info",
          "order__v": 300,
          "type__v": "document",
          "id": "1457559259279:-602158059",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "document_id__v": 5,
          "name__v": "VeevaProm Brochure",
          "order__v": 301,
          "type__v": "document",
          "id": "1457556176044:-743019200",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "section_number__v": null,
          "name__v": "First Section Folder",
          "order__v": 401,
          "type__v": "section",
          "id": "1457560333810:-909497856",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "section_number__v": null,
          "name__v": "Second Section Folder",
          "order__v": 501,
          "type__v": "section",
          "id": "1457560348267:1179700878",
          "parent_id__v": "rootNode"
        }
      }
    ]
  }
}

Details

The abridged response above shows fields and values configured on binder "id": 29, including the first level of binder nodes in the binder's structure. In this first level, there is one document "id": 567 and two sections "section_number__v": "1" and "section_number__v": "2". The second example below, uses the depth=all request parameter to retrieve all levels of binder nodes in the binder's structure.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/29?depth=all

Response

{
  "responseStatus": "SUCCESS",
  "document": {
    "id": 29,
    "binder__v": true,
    "coordinator__v": {
      "groups": [],
      "users": [
        63606
      ]
    },
    "owner__v": {
      "groups": [],
      "users": [
        46916
      ]
    },
    "approver__v": {
      "groups": [],
      "users": [
        25524
      ]
    },
    "reviewer__v": {
      "groups": [],
      "users": [
        60145
      ]
    },
    "distribution_contacts__v": {
      "groups": [],
      "users": []
    },
    "viewer__v": {
      "groups": [
        3
      ],
      "users": []
    },
    "consumer__v": {
      "groups": [],
      "users": [
        60145
      ]
    },
    "editor__v": {
      "groups": [],
      "users": [
        25496
      ]
    },
    "version_creation_date__v": "2016-03-09T21:55:22.000Z",
    "major_version_number__v": 0,
    "lifecycle__v": "Field Medical",
    "subtype__v": "Training Materials",
    "annotations_links__v": 0,
    "annotations_notes__v": 0,
    "name__v": "VeevaProm Info Binder",
    "locked__v": false,
    "annotations_all__v": 0,
    "status__v": "Draft",
    "type__v": "Field Medical",
    "description__v": "",
    "annotations_unresolved__v": 0,
    "last_modified_by__v": 46916,
    "product__v": [
      "00P000000000102"
    ],
    "version_created_by__v": 46916,
    "document_creation_date__v": "2016-03-09T20:42:18.692Z",
    "country__v": [
      "00C000000000109"
    ],
    "annotations_anchors__v": 0,
    "document_number__v": "VV-MED-00029",
    "annotations_resolved__v": 0,
    "annotations_lines__v": 0,
    "version_modified_date__v": "2016-03-09T21:55:22.000Z",
    "created_by__v": 46916,
    "minor_version_number__v": 2
  },
  "versions": [
    {
      "number": "0.1",
      "value": "https://medcomms-veevapharm.vaultdev.com/api/v15.0/objects/binders/29/versions/0/1"
    },
    {
      "number": "0.2",
      "value": "https://medcomms-veevapharm.vaultdev.com/api/v15.0/objects/binders/29/versions/0/2"
    }
  ],
  "binder": {
    "nodes": [
      {
        "properties": {
          "document_id__v": 7,
          "name__v": "VeevaProm Information",
          "order__v": 0,
          "type__v": "document",
          "id": "1457556160448:810987462",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "document_id__v": 2,
          "name__v": "VeevaProm Consumer Info",
          "order__v": 300,
          "type__v": "document",
          "id": "1457559259279:-602158059",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "document_id__v": 5,
          "name__v": "VeevaProm Brochure",
          "order__v": 301,
          "type__v": "document",
          "id": "1457556176044:-743019200",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "section_number__v": null,
          "name__v": "First Section Folder",
          "order__v": 401,
          "type__v": "section",
          "id": "1457560333810:-909497856",
          "parent_id__v": "rootNode"
        },
        "nodes": [
          {
            "properties": {
              "document_id__v": 28,
              "name__v": "Alterin Prescribing Information",
              "order__v": 0,
              "type__v": "document",
              "id": "1457560375017:-1371674753",
              "parent_id__v": "1457560333810:-909497856"
            }
          },
          {
            "properties": {
              "document_id__v": 26,
              "name__v": "Alterin Health Notes",
              "order__v": 100,
              "type__v": "document",
              "id": "1457560377637:-2013602559",
              "parent_id__v": "1457560333810:-909497856"
            }
          },
          {
            "properties": {
              "document_id__v": 27,
              "name__v": "Alterin Information Packet",
              "order__v": 200,
              "type__v": "document",
              "id": "1457560379150:954844502",
              "parent_id__v": "1457560333810:-909497856"
            }
          }
        ]
      },
      {
        "properties": {
          "section_number__v": null,
          "name__v": "Second Section Folder",
          "order__v": 501,
          "type__v": "section",
          "id": "1457560348267:1179700878",
          "parent_id__v": "rootNode"
        },
        "nodes": [
          {
            "properties": {
              "document_id__v": 24,
              "name__v": "Nyaxa Information Packet",
              "order__v": 0,
              "type__v": "document",
              "id": "1457560406595:-2060980086",
              "parent_id__v": "1457560348267:1179700878"
            }
          },
          {
            "properties": {
              "document_id__v": 23,
              "name__v": "Nyaxa and Your Health",
              "order__v": 100,
              "type__v": "document",
              "id": "1457560409271:-1499449603",
              "parent_id__v": "1457560348267:1179700878"
            }
          },
          {
            "properties": {
              "document_id__v": 25,
              "name__v": "Nyaxa Prescribing Information",
              "order__v": 200,
              "type__v": "document",
              "id": "1457560412997:-1622511549",
              "parent_id__v": "1457560348267:1179700878"
            }
          }
        ]
      }
    ]
  }
}

On SUCCESS, Vault retrieves the fields and 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.

Details

For each node in a binder, the API returns the following fields:

Field Name	Description
`nodes [n]`	List of all nodes (documents and sections) at each level in the binder.
`properties [n]`	List of all properties associated with each document or section node.
`order__v`	Order of the node (document or section) within the binder or within the binder section. Note: There is a known issue affecting this parameter. It may not accurately reflect order.
`section_number__v`	Optional number which can be added to each section.
`type`	Type of node (document or section).
`document_id__v`	The document ID of the document in the binder. This is the same as the document's actual document `id`
`id`	The document ID or section ID specific to the binder. For documents, this is different from the document's actual document `id`.
`parent_id__v`	Section ID of the parent node, e.g., "rootNode".
`name__v`	Name of the document or section. For sections, this is the name of the "subfolder" seen in the binder hierarchy in the UI.
`major_version_number__v`	If the document binding rule is "specific", this is major version number of the document.
`minor_version_number__v`	If the document binding rule is "specific", this is minor version number of the document.

History

Since v5

Retrieve All Binder Versions

Retrieve all versions of a binder.

Request

Send GET to /api/{version}/objects/binders/{binder_id}/versions

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/binders/29/versions

Response

{
  "responseStatus": "SUCCESS",
  "versions": [
    {
      "number": "0.1",
      "value": "https://medcomms-veevapharm.vaultdev.com/api/v15.0/objects/binders/29/versions/0/1"
    },
    {
      "number": "0.2",
      "value": "https://medcomms-veevapharm.vaultdev.com/api/v15.0/objects/binders/29/versions/0/2"
    }
  ]
}

Binders have versions just like regular documents. On SUCCESS, Vault returns a list of the available versions for the specified binder.

History

Since v5

Retrieve Binder Version

Retrieve the fields and values configured on a specific version of a specific binder.

Request

Send GET to /api/{version}/objects/binders/{binder_id}/versions/(major_version_number__v}/{minor_version_number__v}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.
{major_version_number__v} - The binder major_version_number__v field value.
{minor_version_number__v} - The binder minor_version_number__v field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/binders/566/versions/0/3

See the response from the Retrieve Binder endpoint above for additional details.

History

Since v5

Create Binders

Create Binder

Use this request to create a new binder in your vault. Learn about Creating Binders in Vault Help.

Request

Send POST to /api/{version}/objects/binders

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Input

All required binder (document) fields must be included in the request. When creating a binder, no file is included in the request. Refer to the next section to create a binder from a template.

Options

When creating a binder, the binder metadata is indexed synchronously by default. To process the indexing asynchronously, include a query parameter async set to true (objects/binders?async=true). This helps speed up the response time from Vault when processing large amounts of data.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name__v=Wonderdrug Compliance Package" \
-d "type__v=Compliance Package" \
-d "subtype__v=Professional" \
-d "lifecycle__v=Binder Lifecycle" \
-d "product__v=1357662840293" \
-d "major_version_number__v=0" \
-d "minor_version_number__v=1" \
https://myvault.veevavault.com/api/v15.0/objects/binders

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Successfully created binder.",
    "id": 563
}

Errors

Error Type	Error Message	Comments
`PARAMETER_REQUIRED`	Missing required parameter [{field_name}].	A required field or field value was not included in the request.
`INVALID_DATA`	Invalid values {field_value} specified for parameter {field_name}.	The value entered for a specified document field does not match with available values.

History

Since v1
v7+ - Supports asynchronous indexing.

Create Binder from Template

Request

Send POST to /api/{version}/objects/binders

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Input

All required binder (document) fields must be included in the request. When creating a binder, no file is included in the request. Include the parameter fromTemplate and specify the name of the template as returned from the document metadata as shown below. Only templates of "kind": binder are allowed.

Example

Since we're creating a new binder with the document type "Compliance Package" and subtype "Professional", we need to find the available templates in the type/subtype metadata:

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/metadata/objects/documents/types/compliance_package__v/subtypes/professional__v

Response (abridged)

    ...
    "templates": [
        {
            "label": "Compliance Package Template",
            "name": "compliance_package__v",
            "kind": "binder",
            "definedIn": "compliance_package__v",
            "definedInType": "type"
        },
        {
            "label": "eCTD Compliance Package",
            "name": "ectd_compliance_package_template__v",
            "kind": "binder",
            "definedIn": "compliance_package__v",
            "definedInType": "type"
        }
        ...

The abridged response above shows the "templates" section of the type/subtype response. There are two available templates we can use to create this binder (each template has the "kind": binder). Both are defined on the compliance_package__v document type. We'll use the binder template ectd_compliance_package_template__v to create our new binder as shown below.

Example (Create Binder from Template)

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "fromTemplate=ectd_compliance_package_template__v" \
-d "name__v=CholeCap eCTD Compliance Package" \
-d "type__v=Compliance Package" \
-d "subtype__v=Professional" \
-d "lifecycle__v=Binder Lifecycle" \
-d "product__v=1357662840171" \
-d "major_version_number__v=0" \
-d "minor_version_number__v=1" \
https://myvault.veevavault.com/api/v15.0/objects/binders

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Successfully created binder.",
    "id": 565
}

Errors

Error Type	Error Message	Comments
`PARAMETER_REQUIRED`	Missing required parameter [{field_name}].	A required document field or field value was not included in the request.
`INVALID_DATA`	Invalid values {field_value} specified for parameter {field_name}.	The value entered for a specified document field does not match with available values.

History

Since v5
v7+ - Supports asynchronous indexing.

Create Binder Version

Request

Send POST to /api/{version}/objects/binders/{binder_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/binders/566

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "New draft successfully created",
    "major_version_number__v": 0,
    "minor_version_number__v": 4
}

Errors

Error Type	Error Message	Comments
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	You are not assigned permission to complete the request.
`INVALID_BINDER`	Binder not found {id}.	The error condition occurs when the user specifies a binder {id} that does not exist.

History

Since v7

Update Binders

Update Binder

Request

Send PUT to /api/{version}/objects/binders/{binder_id}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "audience__vs=Healthcare Provider" \
-d "country__v=1357662840400" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566

Response

{
    "responseStatus": "SUCCESS",
    "id": 566
}

History

Since v5

Reclassify Binder

Reclassify allows you to change the document type of an existing binder. A document "type" is the combination of the type__v, subtype__v, and classification__v fields on a binder. When you reclassify, Vault may add or remove certain fields on the binder. You can only reclassify the latest version of a binder and only one binder at a time. The API does not currently support Bulk Reclassify.

Learn more about:

Vault Help: Reclassifying Documents.
API: Retrieve Binders
API: Retrieve Document Fields
API: Retrieve Document Types, Subtypes, and Classifications

About this Request

You can only reclassify the latest version of a specified binder.
You can only reclassify one binder at a time. Bulk reclassify is not currently supported.

Request

Send PUT to /api/{version}/objects/binders/{binder_id}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Input

Field Name	Description
`reclassify`	Set to `true`. Without this, a standard binder update action is performed.
`type__v`	The name of the document type being assigned to the binder.
`subtype__v`	The name of the document subtype (if one exists on the type).
`classification__v`	The name of the document classification (if one exists on the subtype).
`lifecycle__v`	The name of the lifecycle.

You can also add or remove values for any other editable field.

Note that additional fields may be required depending on the document type, subtype, and classification being assigned to the binder.

Use the Document Metadata API to retrieve required and editable fields in your vault.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "reclassify=true" \
-d "type__v=Claim" \
-d "lifecycle__v=Binder Lifecycle" \
https://myvault.veevavault.com/api/v15.0/objects/binders/776

Response

{
    "responseStatus": "SUCCESS",
    "id": 776
}

Errors

Type	Message	Comments
`OPERATION_NOT_ALLOWED`	Operation not allowed because document falls under one or more legal holds.	You cannot reclassify a binder which is related to an approved legal hold. Learn more about Legal Hold in Vault Help.

History

Since v8

Update Binder Version

Request

Send PUT to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "audience__vs=Healthcare Provider" \
-d "country__v=1357662840400" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/0/1

Response

{
    "responseStatus": "SUCCESS",
    "id": 566
}

History

Since v5

Refresh Binder Auto-Filing

Note: This is only available in eTMF vaults on binders configured with the TMF Reference Models.

Request

Send POST to /api/{version}/objects/binders/{binder_id}/actions

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "action=refresh_auto_filing" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/actions

Response

{
    "responseStatus": "SUCCESS"
}

Errors

Error Type	Error Message	Comments
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	You are not assigned permission to complete the request.
`INVALID_DATA`	Invalid value [{value}] specified for parameter [{parameter}] : Object record ID does not resolve to a valid active [`hierarchy__v`].

History

Since v13

Delete Binders

Delete Binder

Request

Send DELETE to /api/{version}/objects/binders/{binder_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/binders/566

Response

{
  "responseStatus": "SUCCESS",
  "id": 35
}

Errors

Error Type	Error Message	Comments
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	You are not assigned permission to complete the request.
`INVALID_BINDER`	Binder not found {id}.	The error condition occurs when the user specifies a binder {id} that does not exist.
`OPERATION_NOT_ALLOWED`	Operation not allowed because binder falls under one or more legal holds.	You cannot delete a binder if it is related to an approved legal hold. Learn more about Legal Hold in Vault Help.

History

Since v5

Delete Binder Version

Request

Send DELETE to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/binders/566/versions/0/2

Response

{
  "responseStatus": "SUCCESS",
  "id": 124
}

Errors

Error Type	Error Message	Comments
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	You are not assigned permission to complete the request.
`INVALID_BINDER`	Binder not found {id}.	The error condition occurs when the user specifies a binder {id} that does not exist.
`OPERATION_NOT_ALLOWED`	Operation not allowed because binder falls under one or more legal holds.	You cannot delete a binder if it is related to an approved legal hold. Learn more about Legal Hold in Vault Help.

History

Since v5

Export Binders

The Export Binder API allows you to export a zip archive with all documents from a binder, or a subset of those documents.

You can also export different artifacts for the selected documents, including source documents, renditions, versions, and document fields.

Learn about Exporting Binders in Vault Help.

Export Binder

Use this request to export the latest version or a specific version of a binder in your vault.

This will export the complete binder, including all binder sections and documents.
To export only specific binder sections and documents, refer to the next section.
After initiating an export, you can retrieve its status, results, and download the exported binder.

Request

To export the latest version of a binder, Send POST to /api/{version}/objects/binders/{binder_id}/actions/export
To export a specific version of a binder, Send POST to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/actions/export

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Exporting Document Source Files

By default, the source files of all documents in the binder are exported.
Source documents can be any type of file (ZIP, DOCX, CSV, etc.).
To exclude source files, add the parameter source=false to the request endpoint.
For example: .../actions/export?source=false

Exporting Document Renditions

By default, document renditions are not exported.
To include renditions, add the parameter renditiontype={rendition_type} to the request endpoint.
For example: .../actions/export?renditiontype=viewable_rendition__v
The viewable_rendition__v is the most common, which exports the (typically auto-generated) PDF rendition of your document.
Note that if the document source file is a PDF, there is no separate viewable rendition to download.

Exporting Document Versions

By default, the document versions that are exported are determined by the version binding rule configured for the binder, section, or binder document.
To override the binding rule and export all major versions of each document, add the parameter docversion=major to the request endpoint.
For example: .../actions/export?docversion=major
To override the binding rule and export all major and minor versions of each document, add the parameter docversion=major_minor to the request endpoint.
For example: .../actions/export?docversion=major_minor

Exporting Attachments

To export binder attachments, include the parameter attachments=all or attachments=latest
For example: .../actions/export?attachments=all will export all versions of all attachments.
For example: .../actions/export?attachments=latest will export the latest version of all attachments.
Available in API v15 or later.

Exporting Document Field Values & Metadata

By default, exported files include the name__v field value only.
To export additional fields, include a comma-separated list of field values to export.
For example, to export the binder name, title, document number, and export file name: .../actions/export?name__v,title__v,document_number__v,export_filename__v
By default, all document metadata is exported. To exclude the metadata, add the parameter docfield=false

Combining Multiple Request Parameters

To add multiple parameters to the request endpoint, separate each with the ampersand (&) character.
For example, to exclude the source file and export a rendition: .../actions/export?source=false&renditiontype=viewable_rendition__v

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/454/actions/export

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Job for Binder Export Started",
  "URL": "https://myvault.veevavault.com/api/v15.0/services/jobs/1201",
  "job_id": 1201
}

Details

On SUCCESS, the response includes the following information:

url - The URL to retrieve the current status of the binder export job.
job_id - The Job ID value is used to retrieve the status and results of the binder export request.

Errors

Vault will not start the export job until all errors have been corrected and resubmitted.

Error Type	Error Message	Comments
`METHOD_NOT_SUPPORTED`	Requested method {METHOD} not supported.	You must use the HTTP `POST` method for this request.
`INVALID_DATA`	Invalid input parameter value for {PARAMETER}.	You have provided a parameter which is invalid. The error message includes the name of the invalid parameter.
`INVALID_BINDER`	Binder not found.	The specified binder `id` value was not found in your vault.
`INSUFFICIENT_ACCESS`	User {USER ID} authorized for view or export on binder.	The logged-in API user must have API permission and proper permissions to perform an export on the requested binder.
`INSUFFICIENT_ACCESS`	User {USER ID} not licensed for this permission [VAULT ACTIONS API ACCESS].	The logged-in API user must have API permission and proper permissions to perform an export on the requested binder.
`INSUFFICIENT_ACCESS`	User {USER ID} not authorized for FTP download.	The logged-in API user must have API permission and proper permissions to perform an export on the requested binder.
`OPERATION_NOT_ALLOWED`	Binder export not enabled for this vault.	The binder cannot be exported because the "Binder Export" function has not been enabled for the vault.

History

Since v14
v15+ - Supports attachments export.

Export Binder Sections

Use this request to export only specific sections and documents from the latest version of a binder in your vault. This will export only parts of the binder, not the complete binder.

Before submitting this request:

The Export Binder feature must be enabled in your vault.
You must be assigned permissions to use the API.
You must have the Export Binder permission.
You must have the View Document permission for the binder.
Only documents in the binder which you have the View Document permission are available to export.

Request

To export the latest version, Send POST to /api/{version}/objects/binders/{binder_id}/actions/export
To export a specific version, Send POST to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/actions/export

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Input

Create a CSV or JSON input file with the id values of the binder sections and/or documents to be exported.

To retrieve a list of all nodes from a binder, Send GET to /api/{version}/objects/binders/{binder_id}?depth=all. You may include any number of valid nodes. Vault will ignore id values which are invalid, but will export all which are valid.

For example, the abridged response below includes two nodes from a binder. Node "id": "1415381339215" is a section (folder) and "id": "1415381339220" is a document node.

Exporting a binder section node will automatically include all of its subsections and documents therein.

  "nodes": [
    {
      "properties": {
        "section_number__v": "02.01.01",
        "name__v": "Investigator Brochure",
        "order__v": 0,
        "type__v": "section",
        "id": "1415381339215",
        "parent_id__v": "1415381339209"
      },
      "nodes": [
        {
          "properties": {
            "document_id__v": 18,
            "name__v": "CHC032-194 Investigator Brochure",
            "order__v": 0,
            "type__v": "document",
            "id": "1415381339220",
            "parent_id__v": "1415381339215"
          }
        },

Example CSV Input File

To export just this one section and document from the binder, we would submit the following input file:

id
1415381339215
1415381339220

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Binders\export-binder-sections.csv" \
https://myvault.veevavault.com/api/v15.0/objects/binders/454/1/0/actions/export

In this example:

The input file format is set to CSV.
The response format is not set and will default to JSON.
The path\name of the CSV input file is specified.

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Job for Binder Export Started",
  "URL": "https://myvault.veevavault.com/api/v15.0/services/jobs/1201",
  "job_id": 1201
}

Details

On SUCCESS, the response includes the following information:

URL - The URL to retrieve the current status of the binder export job.
job_id - The Job ID value is used to retrieve the status and results of the binder export request.

Errors

Error Type	Error Message	Comments
`METHOD_NOT_SUPPORTED`	Requested method {METHOD} not supported.	You must use the HTTP `POST` method for this request.
`INVALID_DATA`	Invalid input parameter value for {PARAMETER}.	You have provided a parameter which is invalid. The error message includes the name of the invalid parameter.
`INVALID_BINDER`	Binder not found.	The specified binder `id` value was not found in your vault.
`INSUFFICIENT_ACCESS`	User {USER ID} authorized for view or export on binder.	The logged-in API user must have API permission and proper permissions to perform an export on the requested binder.
`INSUFFICIENT_ACCESS`	User {USER ID} not licensed for this permission [VAULT ACTIONS API ACCESS].	The logged-in API user must have API permission and proper permissions to perform an export on the requested binder.
`INSUFFICIENT_ACCESS`	User {USER ID} not authorized for FTP download.	The logged-in API user must have API permission and proper permissions to perform an export on the requested binder.
`OPERATION_NOT_ALLOWED`	Binder export not enabled for this vault.	The binder cannot be exported because the "Binder Export" function has not been enabled for the vault.

History

Since v14

Retrieve Binder Export Results

After submitting a request to export a binder from your vault, you can query vault to determine the results of the request.

Before submitting this request:

You must have previously requested a binder export job (via the API) which is no longer active.
You must have a valid job_id value (retrieved from the export binder request above).

Request

Send GET to /api/{version}/objects/binders/actions/export/{job_id}/results

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{job_id} - The id value of the requested export job. This is returned with the export binder requests above.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/actions/export/1201/results

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 1201,
  "id": 454,
  "major_version_number__v": 1,
  "minor_version_number__v": 0,
  "file": "/1201/454/1_0/Nyaxa Compliance Package.zip",
  "user_id__v": 44533
}

Details

On SUCCESS, the response includes the following information:

Field Name	Description
`job_id`	The Job ID value of the binder export request.
`id`	The `id` value of the exported binder.
`major_version_number__v`	The major version number of the exported binder.
`minor_version_number__v`	The minor version number of the exported binder.
`file`	The path/location of the downloaded binder ZIP file.
`user_id__v`	The `id` value of the Vault user who initiated the binder export job.

History

Since v14

Download Exported Binder Files via FTP

Once your binder export job has been successfully completed, you can download the files from your FTP Staging Server.

Prerequisites

Before downloading the files, the following conditions must be met:

The binder export job must have been successfully completed.
The API user must have a permission set which allows them FTP download permissions.

Downloading the Files

The exported binder is packaged in a ZIP file on your FTP Staging Server.

Binder Relationships

Learn about Binder Relationships in Vault Help.

Retrieve Binder Relationship

Request

Send GET to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/relationships/{relationship_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/versions/0/3/relationships/202

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": null,
    "errorCodes": null,
    "relationships": [
        {
            "relationship": {
                "source_doc_id__v": 566,
                "relationship_type__v": "supporting_documents__vs",
                "created_date__v": "2015-03-24T22:37:20.000Z",
                "id": 202,
                "target_doc_id__v": 254,
                "created_by__v": 46916
            }
        }
    ],
    "errorType": null
}

Details

Field Name	Description
`id`	Relationship ID.
`source_doc_id`	Document ID of the source document.
`relationship_type__v`	Relationship type
`created_by__v`	User ID of user who created the relationship
`created_date__v`	Timestamp when the relationship was created
`target_doc_id__v`	Document ID for target document
`target_major_version__v`	Major version of the target document; null values indicate that the relationship applies to all major versions
`target_minor_version__v`	Minor version of the target document; null values indicate that the relationship applies to all minor versions

History

Since v5

Create Binder Relationship

Request

Send POST to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/relationships

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Inputs

Set the target_doc_id__v to the document id of the "target document" to which a relationship will be established with the binder.
Set the relationship_type__v to the field value of one of the desired relationshipTypes from the "Documents Relationships Metadata" call.
[Optional] - If you're creating a relationship with a specific version of the target document, set the target_major_version__v to the major version number of the target document.
[Optional] - If you're creating a relationship with a specific version of the target document, set the target_minor_version__v to the minor version number of the target document.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "target_doc_id__v=13" \
-d "relationship_type__v=supporting_documents__vs" \
-d "target_major_version__v=0" \
-d "target_minor_version__v=1" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/versions/0/3/relationships

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document relationship successfully created.",
    "id": 202
}

On SUCCESS, Vault returns the relationship id of the newly created binder relationship.

History

Since v5

Delete Binder Relationship

Request

Send DELETE to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/relationships/{relationship_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/versions/0/4/relationships/202

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document relationship successfully deleted.",
    "id": 202
}

On SUCCESS, Vault deletes the requested relationship and returns the relationship id of the deleted relationship.

History

Since v5

Binder Sections

Retrieve Binder Sections

Retrieve all sections (documents and subfolders) in a binder's top-level root node or sub-level node.

Request

Send GET to /api/{version}/objects/binders/{binder_id}/sections

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Options

/api/{version}/objects/binders/{binder_id}/sections/{node_id} - Retrieve all sections (documents and subfolders) in a binder's sub-level node. If not included, all sections from the binder's top-level root node will be returned.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/29/sections

Response

{
  "responseStatus": "SUCCESS",
  "binder": {
    "nodes": [
      {
        "properties": {
          "document_id__v": 7,
          "name__v": "VeevaProm Information",
          "order__v": 0,
          "type__v": "document",
          "id": "1457556160448:810987462",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "document_id__v": 2,
          "name__v": "VeevaProm Consumer Info",
          "order__v": 300,
          "type__v": "document",
          "id": "1457559259279:-602158059",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "document_id__v": 5,
          "name__v": "VeevaProm Brochure",
          "order__v": 301,
          "type__v": "document",
          "id": "1457556176044:-743019200",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "section_number__v": null,
          "name__v": "First Section Folder",
          "order__v": 401,
          "type__v": "section",
          "id": "1457560333810:-909497856",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "section_number__v": null,
          "name__v": "Second Section Folder",
          "order__v": 501,
          "type__v": "section",
          "id": "1457560348267:1179700878",
          "parent_id__v": "rootNode"
        }
      }
    ]
  }
}

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/29/sections/1457560348267:1179700878

Response

{
  "responseStatus": "SUCCESS",
  "node": {
    "properties": {
      "section_number__v": null,
      "name__v": "Second Section Folder",
      "order__v": 501,
      "type__v": "section",
      "id": "1457560348267:1179700878",
      "parent_id__v": "rootNode"
    },
    "nodes": [
      {
        "properties": {
          "document_id__v": 24,
          "name__v": "Nyaxa Information Packet",
          "order__v": 0,
          "type__v": "document",
          "id": "1457560406595:-2060980086",
          "parent_id__v": "1457560348267:1179700878"
        }
      },
      {
        "properties": {
          "document_id__v": 23,
          "name__v": "Nyaxa and Your Health",
          "order__v": 100,
          "type__v": "document",
          "id": "1457560409271:-1499449603",
          "parent_id__v": "1457560348267:1179700878"
        }
      },
      {
        "properties": {
          "document_id__v": 25,
          "name__v": "Nyaxa Prescribing Information",
          "order__v": 200,
          "type__v": "document",
          "id": "1457560412997:-1622511549",
          "parent_id__v": "1457560348267:1179700878"
        }
      }
    ]
  }
}

Details

Field Name	Description
`nodes [n]`	List of all nodes (documents and sections) at each level in the binder.
`properties [n]`	List of all properties associated with each document or section node.
`hierarchy__v`	Specifies a single record from the `hierarchy__v` object that has been mapped this binder node.
`section_number__v`	Optional number which can be added to each section.
`order__v`	Order of the component (document or section) within the binder or within the binder section. Note: There is a known issue affecting this parameter. It may not accurately reflect order.
`type`	Type of node (document or section).
`document_id__v`	The document ID of the document in the binder. This is the same as the document's actual document `id`
`id`	The document ID or section ID specific to the binder. For documents, this is different from the document's actual document `id`.
`parent_id__v`	Section ID of the parent node, e.g., "rootNode".
`name__v`	Name of the document or section. For sections, this is the name of the "subfolder" seen in the binder hierarchy in the UI.
`major_version_number__v`	If the document binding rule is "specific", this is major version number of the document.
`minor_version_number__v`	If the document binding rule is "specific", this is minor version number of the document.

History

Since v5

Retrieve Binder Version Section

For a specific version, retrieve all sections (documents and subfolders) in a binder's top-level root node or sub-level node.

Request

Send GET to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/sections

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Options

/api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/sections/{node_id} - Retrieve all sections (documents and subfolders) in a binder's sub-level node. If not included, all sections from the binder's top-level root node will be returned.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/29/versions/0/2/sections

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/29/versions/0/2/sections/1457560348267:1179700878

Response

See Retrieve Binder Sections response above.

History

Since v5

Create Binder Section

Create a new section in a binder.

Request

Send POST to /api/{version}/objects/binders/{binder_id}/sections

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Input

Field Name	Description
`name__v`	[Required] Specify a name for the new section.
`section_number__v`	[Optional] Enter a numerical value for the new section.
`parent_id__v`	[Optional] If the new section is going to be a subsection, enter the Node ID of the parent section. If left blank, the new section will become a top-level section in the binder.
`order__v`	[Optional] Enter a number reflecting the position of the section within the binder or parent section. By default, new components appear below existing components. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name__v=VeevaProm Additional Information" \
-d "section_number__v=1.3" \
-d "parent_id__v=1427232809771:1381853041" \
-d "order__v=1" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/sections

Response

{
    "responseStatus": "SUCCESS",
    "id": "1427486900128:1467568099"
}

On SUCCESS, Vault returns the Node ID of the newly created section. This is unique within the binder, regardless of level.

Errors

Error Type	Error Message	Comments
`INVALID_BINDER`	ID passed is not for a binder.
`REQUIRED_FIELD_NOT_PRESENT`	Section name not present.
`INVALID_SECTION`	Parent section ID is not a valid section.

History

Since v5

Update Binder Section

Update a section in a binder.

Request

Send PUT to /api/{version}/objects/binders/{binder_id}/sections/{node_id}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.
{node_id} - The binder node id of the section.

Input

Configure one or more of the following fields with values. These are all optional.

Field Name	Description
`name__v`	Change the name of the binder section.
`section_number__v`	Update the section number value.
`order__v`	[Optional] Enter a number reflecting the position of the section within the binder or parent section. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.
`parent_id__v`	To move the section to a different section in the binder, include the value of the parent node where it will be moved.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name__v=VeevaProm Additional Information" \
-d "section_number__v=3" \
-d "parent_id__v=rootNode" \
-d "order__v=4" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/sections/1427232809771:1381853041

Response

{
    "responseStatus": "SUCCESS",
    "id": "1427486900128:1467568099"
}

On SUCCESS, Vault returns the Node ID of the newly created section. This is unique within the binder, regardless of level.

Errors

Error Type	Error Message
`INVALID_BINDER`	ID passed is not for a binder.
`REQUIRED_FIELD_NOT_PRESENT`	Section name not present.
`INVALID_SECTION`	Parent section ID is not a valid section.

History

Since v5

Delete Binder Section

Delete a section from a binder.

Request

Send DELETE to /api/{version}/objects/binders/{binder_id}/sections/{node_id}

By deleting the 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.

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.
{node_id} - The binder node id field value.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/sections/1427486900128:1467568099

Response

{
    "responseStatus": "SUCCESS",
    "id": "1427486900128:1467568099"
}

On SUCCESS, Vault returns the Node ID of the deleted section.

Errors

Error Type	Error Message	Comments
`INVALID_BINDER`	ID passed is not for a binder.
`INVALID_SECTION`	Section ID is not a valid section

History

Since v5

Binder Documents

Add Document to Binder

Add a document to a binder.

Request

Send POST to /api/{version}/objects/binders/{binder_id}/documents

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Inputs

Field Name	Description
`document_id__v`	[Required] ID of the document being added to the binder.
`parent_id__v`	[Required] Section ID of the parent section, if the document will be in a section rather than top-level. 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] Enter a number reflecting the position of the document within the binder or section. By default, new components appear below existing components. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.
`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` (bind to the latest available version (assumed if binding_rule is blank)), `steady-state` (bind to latest version in a steady-state), `current` (bind to current version), or `specific` (bind to a specific version).
`major_version_number__v`	If the `binding_rule` is `specific`, then this is required and indicates the major version of the document to be linked. Otherwise it is ignored.
`minor_version_number__v`	If the `binding_rule` is `specific`, then this is required and indicates the minor version of the document to be linked. Otherwise it is ignored.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "document_id__v=585" \
-d "parent_id__v=1427232809771:1381853041" \
-d "section_id__v=1" \
-d "binding_rule__v=steady-state" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/documents

Response

{
    "responseStatus": "SUCCESS",
    "id": "1427491342404:-1828014479"
}

Errors

Error Type	Error Message	Comments
`INVALID_BINDER`	ID passed is not for a binder.
`INVALID_DOCUMENT`	Document ID is not present.
`INVALID_SECTION`	Parent section ID is not a valid section.
`MISSING_MAJOR`	Document major version was not specified and binding rule was `specific`.
`MISSING_MINOR`	Document minor version was not specified and binding rule was `specific`.

History

Since v5

Move Document in Binder

Move a document to a different position within a binder.

Request

Send PUT to /api/{version}/objects/binders/{binder_id}/documents/{node_id}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.
{node_id} - The binder node id field value.

Input

Field Name	Description
`order__v`	[Optional] Enter a number reflecting the new position of the document within the binder or section. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.
`parent_id__v`	[Optional] To move the document to a different section or from a section to the binder's root node, enter the value of the new parent node.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "parent_id__v=1457560333810:-909497856" \
-d "order__v=2" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/documents/1457559259279:-602158059

Response

{
  "responseStatus": "SUCCESS",
  "id": "1457559259279:-602158059"
}

On SUCCESS, Vault returns the new node ID of the document.

Errors

Error Type	Error Message	Comments
`INVALID_BINDER`	ID passed is not for a binder.
`INVALID_DOCUMENT`	Document ID is not a valid document or the document is not linked to the selected binder.
`INVALID_TARGET_SECTION`	Parent ID is not a valid section within the binder or the Binder ID itself.

History

Since v5

Remove Document from Binder

Request

Send DELETE to /api/{version}/objects/binders/{binder_id}/documents/{node_id}

By unlinking the document, you remove it from the specified location within the binder, this does not actually delete the document from Vault.

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.
{node_id} - The binder node id field value.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/documents/1427491342404:-1828014479

Response

{
    "responseStatus": "SUCCESS",
    "id": "1427491342404:-1828014479"
}

On SUCCESS, Vault returns the Node ID of the deleted document.

Errors

Error Type	Error Message	Comments
`INVALID_BINDER`	ID passed is not for a binder.
`INVALID_DOCUMENT`	Document ID is not present.

History

Since v5

Binder Templates

Retrieve Binder Template Metadata

Retrieve the metadata which defines the shape of binder templates in your vault.

Request

Send GET to /api/{version}/metadata/objects/binders/templates

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/metadata/objects/binders/templates

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "name": "name__v",
      "type": "String",
      "requiredness": "required",
      "max_length": 50,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "label__v",
      "type": "String",
      "requiredness": "required",
      "max_length": 100,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "active__v",
      "type": "Boolean",
      "requiredness": "required",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "type__v",
      "type": "Component",
      "requiredness": "required",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "subtype__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "classification__v",
      "type": "Component",
      "requiredness": "optional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "filing_model__v",
      "type": "Object",
      "requiredness": "optional",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "enable_dynamic_view__v",
      "type": "Boolean",
      "requiredness": "optional",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "binder_template_parameters__v",
      "type": "String",
      "requiredness": "optional",
      "max_length": 100,
      "editable": false,
      "multi_value": true,
      "ordered": false
    }
  ]
}

Details

Field Name	Description
`name__v`	Binder template name, e.g., `binder_template_1__c`. This is used in the API when retrieving, creating, updating, or deleting binder templates.
`label__v`	Binder template label, e.g., "Binder Template 1". This is the name users see in the UI when selecting a binder template.
`type__v`	Vault document type to which the template is associated.
`subtype__v`	Vault document subtype to which the template is associated. This field is only required if the template exists at the document subtype or classification level.
`classification__v`	Vault document classification to which the template is associated. This field is only required if the template exists at the document classification level.
`filing_model__v`	eTMF vaults only. The filing model for the binder template.
`enable_dynamic_view__v`	eTMF vaults only. Indicates if the binder template is available in the Dynamic Binder Viewer.
`binder_template_parameters__v`	eTMF vaults only. Lists the available binder template parameters for the Dynamic Binder Viewer.

Metadata Field	Description
`name`	The binder template field name (`name__v`, `label__v`, `type__v`, etc.).
`type`	The binder template field type. This can be one of String, Boolean, Component, or Object (eTMF vaults).
`requiredness`	Indicates whether or not a value must be added when creating a binder template. These include: - `required` : A value must be added. - `conditional` : For a template to exist at the document subtype or classification level, this is required.
`editable`	Boolean (true/false) field indicating whether or not a value can be added or edited by a user when creating or updating a binder template.
`multi_value`	Boolean (true/false) field indicating whether or not the field can have multiple values.
`component`	The component property applies to the `type__v`, `subtype__v`, and `classification__v` fields and defines the data type that can be set into this field.

History

Since v13

Retrieve Binder Template Node Metadata

Retrieve the metadata which defines the shape of binder template nodes in your vault.

Request

Send GET to /api/{version}/metadata/objects/binders/templates/bindernodes

Headers

Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/metadata/objects/binders/templates/bindernodes

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "name": "id",
      "type": "id",
      "requiredness": "required",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "parent_id__v",
      "type": "id",
      "requiredness": "optional",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "order__v",
      "type": "Number",
      "requiredness": "optional",
      "max_value": 2147483647,
      "min_value": 0,
      "scale": 0,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "node_type__v",
      "type": "Enum",
      "requiredness": "required",
      "editable": true,
      "multi_value": false,
      "enums": [
        "planned_document",
        "section"
      ]
    },
    {
      "name": "label__v",
      "type": "String",
      "requiredness": "required",
      "max_length": 100,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "number__v",
      "type": "String",
      "requiredness": "optional",
      "max_length": 50,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "lifecycle__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Documentlifecycle"
    },
    {
      "name": "type__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "subtype__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "classification__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "document_template__v",
      "type": "String",
      "requiredness": "conditional",
      "max_length": 50,
      "editable": true,
      "multi_value": false
    }
  ]
}

Details

Binder "nodes" are individual sections or documents in the binder template hierarchy. These can include folders and subfolders in the binder or documents existing within the sections.

Field Name	Description
`id`	For a given binder, these are the binder node (section or planned document) IDs.
`parent_id__v`	For a given binder template node, this is the node ID of its parent node. The top-level node is the `rootNode`.
`node_type__v`	Binder node types include `section` and `planned_document` (content placeholder documents within the binder template).
`label__v`	Binder template node label (name). For `section` node types, this is the name of the folder within the binder template. Example: `"label__v": "Operational Procedures"`. For `planned document` node types, this is the name of the content placeholder document and may include document field tokens. Example: `"label__v": "${study_b} - ${site_b} Operational Procedure"`.
`number__v`	These apply to binder `section` node types and are a numerical representation of the section's hierarchy within the binder template. Example: Given two folders in a binder (under the root node), each containing three subfolders, the first and second folder numbers would be 01 and 02, respectively. The three subfolder numbers within the first and second folders would then be 01.01, 01.02, 01.03 and 02.01, 02.02, 02.03, respectively.
`order__v`	Order of the node within the binder or within the parent node. Note: There is a known issue affecting this parameter. It may not accurately reflect order.
`type__v`	Name of the document type to which templates are associated.
`subtype__v`	Name of the document subtype to which templates are associated.
`classification__v`	Name of the document classification to which templates are associated.
`lifecycle__v`	Name of the binder lifecycle to which templates are associated.
`document_template__v`	Name of the planned document template.
`milestone_type__v`	eTMF vaults only. Name of the milestone type associated with the planned document template.
`hierarchy_mapping__v`	eTMF vaults only. Object ID pointing to the lowest level in the TMF reference model.

Metadata Field	Description
`name`	The binder template node field name (`id`, `parent_id__v`, `node_type__v`, etc.).
`type`	The binder template field type. This can be one of ID, String, Number, Enum, or Component.
`requiredness`	Indicates whether or not a value must be added when creating a binder template. These include: - `required` : A value must be added. - `conditional` : For a template to exist at the document subtype or classification level, this is required.
`editable`	Boolean (true/false) field indicating whether or not a value can be added or edited by a user when creating or updating a binder template.
`multi_value`	Boolean (true/false) field indicating whether or not the field can have multiple values.
`component`	The component property applies to the `type__v`, `subtype__v`, `classification__v`, and `lifecycle__v` fields and defines the data type that can be set into this field.

History

Since v13

Retrieve Binder Template Collection

Retrieve the collection of all binder templates in your vault.

Request

Send GET to /api/{version}/objects/binders/templates

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "name__v": "study_site_level_file_tmf_rm_30__c",
         "label__v": "Study Site Level File TMF RM 2.0",
         "active__v": true,
         "type__v": "trial_master_file__v",
         "subtype__v": null,
         "classification__v": null,
         "filing_model__v": "0MO000000000101"
      },
      {
         "name__v": "study_site_level_file_tmf_rm_20__c",
         "label__v": "Study Site Level File TMF RM 2.0",
         "active__v": "true",
         "type__v": "site_master_file__v",
         "subtype__v": null,
         "classification__v": null,
         "filing_model__v": "0MO000000000102"
      }
   ]
}

Details

The response lists all binder templates which have been added to the vault. Shown above, two binder templates exist in our vault. Both exist at the document type level and are intended for use with the compliance_package__v type. For information about the document template metadata, refer to the "Retrieve Binder Template Attributes" response below.

History

Since v13

Retrieve Binder Template Attributes

Retrieve the attributes of a specific binder template in your vault.

Request

Send GET to /api/{version}/objects/binders/templates/{template_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.
{template_name} - The binder template name__v field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates/study_site_level_file_tmf_rm_20__c

Example JSON Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "name__v": "study_site_level_file_tmf_rm_20__c",
         "label__v": "Study Site Level File TMF RM 2.0",
         "active__v": "true",
         "type__v": "site_master_file__v",
         "subtype__v": null,
         "classification__v": null,
         "filing_model__v": "0MO000000000102"
      }
   ]
}

Details

The response lists all attributes configured on a specific binder template in the vault. Shown above are the attributes configured on the specified template:

Field Name	Description
`name__v`	Name of the binder template. This value is not displayed to end users in the UI. It is seen by Admins and used in the API.
`label__v`	Label of the binder template. When users in the UI create binders from templates, they see this value in the list of available templates.
`type__v`	Vault document type to which the template is associated.
`subtype__v`	Vault document subtype to which the template is associated. This field is only displayed if the template exists at the document subtype or classification level.
`classification__v`	Vault document classification to which the template is associated. This field is only displayed if the template exists at the document classification level.
`filing_model__v`	eTMF vaults only. Filing model for the binder template.

History

Since v13

Retrieve Binder Template Node Attributes

Retrieve the attributes of each node (folder/section) of a specific binder template in your vault.

Request

Send GET to /api/{version}/objects/binders/templates/{template_name}/bindernodes

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{template_name} - The binder template name__v field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates/study_site_level_file_tmf_rm_20__c/bindernodes

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": "5148",
            "parent_id__v": "studySiteLevelFileTMFRM20",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Trial Management",
            "number__v": "01"
        },
        {
            "id": "9647",
            "parent_id__v": "studySiteLevelFileTMFRM20",
            "order__v": "100",
            "node_type__v": "section",
            "label__v": "Central Trial Documents",
            "number__v": "02"            
        },
        {
            "id": "0908",
            "parent_id__v": "studySiteLevelFileTMFRM20",
            "order__v": "200",
            "node_type__v": "section",
            "label__v": "Site Management",
            "number__v": "03"            
        },
        {
            "id": "6671",
            "parent_id__v": "5148",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Trial Oversight",
            "number__v": "01.01"            
        },
        {
            "id": "4509",
            "parent_id__v": "5148",
            "order__v": "100",
            "node_type__v": "section",
            "label__v": "General",
            "number__v": "01.02"            
        },
        {
            "id": "3623",
            "parent_id__v": "6671",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Operational Procedure",
            "number__v": "01.01.01",
            "hierarchy_mapping__v": "00H00484"     
        },
        {
            "id": "5575",
            "parent_id__v": "6671",
            "order__v": "100",
            "node_type__v": "section",
            "label__v": "Recruitment Plan",
            "number__v": "01.01.02",
            "hierarchy_mapping__v": "00H00488"                      
        },
        {
            "id": "StudyBSiteBOperationalProcedur",
            "parent_id__v": "3623",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Operational Procedure",
            "lifecycle__v": "etmf_lifecycle__vs",
            "type__v": "trial_management__vs",
            "subtype__v": "trial_oversight__vs",
            "classification__v": "operational_procedure_manual__vs"
        },
        {
            "id": "StudyBSiteBRecruitmentPlan",
            "parent_id__v": "5575",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Recruitment Plan",
            "lifecycle__v": "etmf_lifecycle__vs",
            "type__v": "trial_management__vs",
            "subtype__v": "trial_oversight__vs",
            "classification__v": "recruitment_plan__vs"
        },
        {
            "id": "9454",
            "parent_id__v": "4509",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Tracking Information",
            "number__v": "01.02.01",
            "hierarchy_mapping__v": "00H00511"                      
        },
        {
            "id": "5014",
            "parent_id__v": "4509",
            "order__v": "100",
            "node_type__v": "section",
            "label__v": "Filenote",
            "number__v": "01.02.02",
            "hierarchy_mapping__v": "00H00515"                      
        },
        {
            "id": "StudyBSiteBOperationalProcedu1",
            "parent_id__v": "9454",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Tracking Information",
            "lifecycle__v": "etmf_lifecycle__vs",
            "type__v": "trial_management__vs",
            "subtype__v": "general__vs",
            "classification__v": "tracking_information__vs"
        },
        {
            "id": "StudyBSiteBFileNote",
            "parent_id__v": "5014",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} File Note",
            "lifecycle__v": "etmf_lifecycle__vs",
            "type__v": "trial_management__vs",
            "subtype__v": "general__vs",
            "classification__v": "filenote__vs"
        },
        {
            "id": "2443",
            "parent_id__v": "9647",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Trial Documents",
            "number__v": "02.01"            
        },
        {
            "id": "0413",
            "parent_id__v": "9647",
            "order__v": "100",
            "node_type__v": "section",
            "label__v": "Subject Information Sheet",
            "number__v": "02.02"            
        },
        {
            "id": "5118",
            "parent_id__v": "2443",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Protocol",
            "number__v": "02.01.01",
            "hierarchy_mapping__v": "00H00536"                       
        },
        {
            "id": "StudyBSiteBTrialProtocol",
            "parent_id__v": "5118",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Trial Protocol",
            "lifecycle__v": "etmf_lifecycle__vs",
            "type__v": "central_trial_documents__vs",
            "subtype__v": "trial_documents__vs",
            "classification__v": "protocol__vs"
        },
        {
            "id": "StudyBSiteBSubjectInformationS",
            "parent_id__v": "0413",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Subject Information Sheet",
            "lifecycle__v": "etmf_lifecycle__vs",
            "type__v": "central_trial_documents__vs",
            "subtype__v": "subject_documents__vs",
            "classification__v": "subject_information_sheet__vs"
        },
        {
            "id": "9135",
            "parent_id__v": "0908",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Site Selection",
            "number__v": "03.01"            
        },
        {
            "id": "StudyBSiteBConfidentialityAgre",
            "parent_id__v": "9135",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Confidentiality Agreement",
            "lifecycle__v": "etmf_lifecycle__vs",
            "type__v": "site_management__vs",
            "subtype__v": "site_selection__vs",
            "classification__v": "confidentiality_agreement__vs"
        },
        {
            "id": "StudyBSiteBSiteContacts",
            "parent_id__v": "9135",
            "order__v": "100",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Site Contacts",
            "lifecycle__v": "etmf_lifecycle__vs",
            "type__v": "site_management__vs",
            "subtype__v": "site_selection__vs",
            "classification__v": "site_contact_details__vs"
        }
    ]
}

Details

The response lists all attributes configured on each node of a specific binder template in the vault. The binder template shown above has six nodes.

Field Name	Description
`id`	The binder node (section or planned document) IDs.
`parent_id__v`	The node ID of a section or planned document's parent node. The top-level node is the `rootNode`.
`node_type__v`	Binder node types include `section` and `planned_document` (content placeholder documents within the binder template).
`label__v`	Label of the binder section or planned document.
`type__v`	Vault document type to which planned documents are associated.
`subtype__v`	Vault document subtype to which planned documents are associated. This field is only displayed if the planned document exists at the document subtype or classification level.
`classification__v`	Vault document classification to which planned documents are associated. This field is only displayed if the planned document exists at the document classification level.
`lifecycle__v`	Name of the binder lifecycle to which planned documents are associated.
`number__v`	These apply to binder `section` node types and are a numerical representation of the section's hierarchy within the binder template. Example: Given two folders in a binder (under the root node), each containing three subfolders, the first and second folder numbers would be 01 and 02, respectively. The three subfolder numbers within the first and second folders would then be 01.01, 01.02, 01.03 and 02.01, 02.02, 02.03, respectively.
`order__v`	Order of the node within the binder or within the parent node. Note: There is a known issue affecting this parameter. It may not accurately reflect order.
`hierarchy_mapping__v`	eTMF vaults only. Object ID pointing to the lowest level in the TMF reference model.

History

Since v13

Create Binder Template

Create a new binder template in your vault.

See also: Bulk Create Binder Templates below.

Request

Send POST to /api/{version}/objects/binders/templates

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Input

When creating binder templates, the following fields are required in all vaults:

Field Name	Description
`name__v`	The name of the new binder template. If not included, Vault will use the specified `label__v` value to generate a value for the `name__v` field.
`label__v`	The label of the new binder template. This is the name users will see among the available binder templates in the UI.
`type__v`	The name of the document type to which the template will be associated.
`subtype__v`	The name of the document subtype to which the template will be associated. This is only required if associating the template with a document subtype.
`classification__v`	The name of the document classification to which the template will be associated. This is only required if associating the template with a document classification.
`active__v`	Set to true or false to indicate whether or not the new binder template should be set to active, i.e., available for selection when creating a binder.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "label__v=Claim Binder Template" \
-d "type__v=claim__vs" \
-d "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates

In this example:

The input format is set to application/x-www-form-urlencoded.
The response format is not set and will default to JSON.
The name__v field is not included. Vault will use the specified label__v field value to create the name__v=claim_binder_template__c.
The label__v field specifies the binder template label "Claim Binder Template". This is what users will see among the available templates in the UI.
The document type__v is specified. This template is being created for binders of type__v=claim__vs. Since this exists at the document type level, the subtype and classification are not required.
The template is being set to active__v=true. It will be available for selection when creating a new binder.

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "name__v":"claim_binder_template__c"
      }
   ]
}

On SUCCESS, Vault returns the name of the new binder template.

Errors

Refer to the Bulk Create Binder Templates Errors section below.

History

Since v13

Bulk Create Binder Templates

Create from 1-500 new binder templates in your vault.

See also: Create (Single) Binder Template above.

Request

Send POST to /api/{version}/objects/binders/templates

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml

Input

When creating binder templates, the following fields are required in all vaults:

Field Name	Description
`name__v`	The name of the new binder templates. If not included, Vault will use the specified `label__v` value to generate a value for the `name__v` field.
`label__v`	The label of the new binder templates. This is the name users will see among the available binder templates in the UI.
`type__v`	The name of the document type to which the templates will be associated.
`subtype__v`	The name of the document subtype to which the templates will be associated. This is only required if associating the templates with document subtypes.
`classification__v`	The name of the document classification to which the templates will be associated. This is only required if associating the templates with document classifications.
`active__v`	Set to true or false to indicate whether or not the new binder templates should be set to active, i.e., available for selection when creating a binder.

Example CSV Input

`name__v`	`label__v`	`type__v`	`subtype__v`	`classification__v`	`active__v`
binder_template_1__c	First Binder Template	site_master_file__v			true
	Binder Template 2	trial_master_file__v			true
	Binder Template 3	central_trial_documents__vs	trial_documents__vs	protocol__vs	true
	Binder Template 4	central_trial_documents__vs	reports__vs	clinical_study_report__vs	false

In this example input, we're creating four new binder templates in our vault:

We've only specified the name__v value for the first template and given it a different label__v value. The other templates will inherit their name__v values from the label__v values.
We've specified the document type, subtype, and classification to which each binder template will be associated.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Templates\add_binder_templates.csv" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates

In this example:

The input file format is set to CSV.
The response format is not set and will default to JSON.
The path/name of the CSV input file in our local directory is specified.

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "name":"binder_template_1__c"
      },
      {
         "responseStatus":"SUCCESS",
         "name":"binder_template_2__c"
      },
      {
         "responseStatus":"SUCCESS",
         "name":"binder_template_3__c"
      },      
      {
         "responseStatus":"FAILURE",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this template was not created."
            }
         ]
      }
   ]
}

On SUCCESS, Vault returns the names of the new binder templates.

Errors

Error Type	Error Message	Comments
`INVALID_DATA`	Cannot parse the request body.	The input contains information which cannot be parsed by the API.
`INVALID_DATA`	Cannot process the request : max 500 records expected.	The input has more than 500 records (not allowed).
`INVALID_DATA`	Cannot parse the request body : at least 1 record is expected.	The input has no records (at least one is required).
`REQUIRED_PARAMETER`	Missing required parameter [{field_name}].	A required field is missing from the input. The error message includes the missing field name.
`INVALID_VALUE`	Invalid value [{FIELD_VALUE]} specified for parameter [{PARAMETER}].	A field value specified in the input is invalid. The error message includes invalid value and field name on which it is specified.
`INVALID_DATA`	Cannot create template : another template already exists with [name__v={specified name}].	The name specified for the template is a duplicate of an existing binder template in your vault.
`INVALID_DATA`	Cannot create template : input already defines another template with [name__v={specified name}].	The name specified for the template is a duplicate of another template name specified in the same input.
`INVALID_DATA`	String exceeds max length [{MAX_VALUE}].	The string value exceeds the maximum length for the `label__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{type}].	An invalid value is specified for the `type__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{subtype}] under [{Value specified for `type__v`}].	An invalid value is specified for the `subtype__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{classification}] under [{Value specified for `classification__v`}].	An invalid value is specified for the `classification__v` field.

History

Since v13

Create Binder Template Node

Create nodes in an existing binder template.

Request

Send POST to /api/{version}/objects/binders/templates/{template_name}/bindernodes

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{template_name} - The binder template name__v field value.

Input

When creating binder template nodes, the following fields are required in all vaults:

Field Name	Description
`id`	The ID of the binder node. This must be set to a unique number.
`parent_id__v`	[Required] Enter the `id` of the parent section. To create a node in the top level of the binder (rootNode), leave the value blank.
`node_type__v`	[Required] Set to `section` or `planned_document`.
`label__v`	Label for the section or planned document. For planned documents, this corresponds to "Planned Name" in the UI.
`type__v`	The name of the document type to which the template will be associated.
`subtype__v`	The name of the document subtype to which the templates will be associated. This is only required if associating the template with a document subtype.
`classification__v`	The name of the document classification to which the template will be associated. This is only required if associating the template with a document classification.
`active__v`	Set to true or false to indicate whether or not the binder template should be set to active, i.e., available for selection when creating a binder.
`order__v`	Order of the component (planned document or section) within the binder template or within the template section. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.

Example CSV Input: Create Top-Level Section Binder Nodes

`id`	`node_type__v`	`label__v`	`order__v`	`number__v`
100	section	Folder A	1	01
200	section	Folder B	2	02
300	section	Folder C	3	03

In this example input, we're creating three new binder nodes in the template.

These will be new section node types.
The required parent_id__v name is included but its value left blank. By default, the new sections will be added to the top-level in the binder hierarchy.
The optional section order and number are set. These define the position of the three new sections in the binder template hierarchy.

Example CSV Input: Create Sub-Level Section Binder Nodes

`id`	`node_type__v`	`label__v`	`order__v`	`number__v`	`parent_id__v`
101	section	SubFolder A1	1	01.01	100
102	section	SubFolder A2	2	01.02	100

In this example input, we're creating three new binder nodes in the template.

These will be new section node types.
The required parent_id__v name is included. If the values are left blank, the new sections will be added to the top-level in the binder hierarchy by default.
The optional section order and number are set. These define the position of the three new sections in the binder template hierarchy.

Example CSV Input: Create Planned Document Binder Node

`id`	`node_type__v`	`label__v`	`order__v`	`parent_id__v`	`type__v`	`subtype__v`	`classification__v`	`lifecycle__v`
101PD	planned_document	Planned Document A1	1	101	promotional_piece__vs	advertisement__vs	web__vs	promotional_piece__vs

In this example input, we're creating new binder node of the type planned_document.

The required parent_id__v name is included. If the values are left blank, the planned document will be added to the top-level in the binder hierarchy by default.
The optional section order and number are set. These define the position of the planned document in the binder template hierarchy.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Templates\add_binder_template_nodes.csv" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates/binder_template_1__c/bindernodes

In this example:

The input file format is set to CSV.
The response format is not set and will default to JSON.
The path/name of the CSV input file in our local directory is specified.

Errors

Error Type	Error Message	Comments
`INVALID_DATA`	Cannot parse the request body.
`REQUIRED_PARAMETER`	Missing required parameter [{field_name}].
`INVALID_VALUE`	Invalid value [{FIELD_VALUE]} specified for parameter [{PARAMETER}].
`INVALID_VALUE`	Invalid value [{FIELD_VALUE]} specified for parameter [{PARAMETER}]. One of [section, planned_document] is expected.
`INVALID_DATA`	String exceeds max length [{MAX_VALUE}].	The string value exceeds the maximum length for the `label__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{type}].	An invalid value is specified for the `type__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{subtype}] under [{Value specified for `type__v`}].	An invalid value is specified for the `subtype__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{classification}] under [{Value specified for `classification__v`}].	An invalid value is specified for the `classification__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{LIFECYCLE}].	An invalid value is specified for the `lifecycle__v` field.
`INVALID_DATA`	Value doesn't resolve to a valid [{DOCUMENT_TEMPLATE}] under the [{type}:{subtype}:{classification}].	The value specified for the binder template doesn't resolve to a valid document template under for the specified document type/subtype/classification.
`INVALID_DATA`	Picklist [{Milestone Type Picklist Name}] does not contain [{Specified Picklist Entry Name}].	A non-existing Milestone Type is specified. eTMF vaults only.
`INVALID_DATA`	One of [section,planned_document] is expected.	An invalid enum is specified for the `node_type__v` field.
`INVALID_DATA`	Positive whole numeric value is expected.	An invalid value is specified for the `order__v` field.

History

Since v13

Update Binder Template

Update an existing binder template in your vault.

By changing the document type/subtype/classification, you can move an existing binder template to a different level of the document type hierarchy, effectively reclassifying the template.

See also: Bulk Update Binder Templates below.

Request

Send PUT to /api/{version}/objects/binders/templates

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Input

You can update the following fields on binder templates:

Field Name	Description
`name__v`	Change the name of an existing binder template.
`label__v`	Change the label of an existing binder template. This is the name users will see among the available binder templates in the UI.
`type__v`	Change the document type to which the template is associated.
`subtype__v`	Change the document subtype to which the template is associated. This is only required if associating the template with a document subtype.
`classification__v`	Change the document classification to which the template is associated. This is only required if associating the template with a document classification.
`active__v`	Set to true or false to indicate whether or not the binder template should be set to active, i.e., available for selection when creating a binder.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: text/csv" \ 
-d "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates/binder_template_1__c

In this example:

The input file format is set to application/x-www-form-urlencoded.
The response format is set to text/csv.
The active__v field is set to false. We're changing the status of this binder template from "Active" to "Inactive".

Response (CSV)

responseStatus,name,errors
SUCCESS,binder_template_1__c,

On SUCCESS, Vault returns the name of the updated binder template.

History

Since v13

Bulk Update Binder Templates

Update from 1-500 binder templates in your vault.

By changing the document type/subtype/classification, you can move an existing binder template to a different level of the document type hierarchy, effectively reclassifying the template.

See also: Update [Single] Binder Template above.

Request

Send PUT to /api/{version}/objects/binders/templates

Headers

Input Content-Type - JSON application/json (default) or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml

Input

You can update the following fields on binder templates:

Field Name	Description
`name__v`	Change the name of existing binder templates.
`label__v`	Change the label of existing binder templates. This is the name users will see among the available binder templates in the UI.
`type__v`	Change the document type to which the templates are associated.
`subtype__v`	Change the document subtype to which the templates are associated. This is only required if associating the templates with document subtypes.
`classification__v`	Change the document classification to which the templates are associated. This is only required if associating the templates with document classifications.
`active__v`	Set to true or false to indicate whether or not the binder templates should be set to active, i.e., available for selection when creating a binder.

Example CSV Input

`name__v`	`label__v`	`active__v`
binder_template_2__c	Second Binder Template	true
binder_template_3__c	Binder Template 3	true
binder_template_4__c	Binder Template 4	false

In this example input, we're updating three existing binder templates in our vault.

On the first template, we're updating both the name__v and label__v values.
On the second template, we're updating the name__v value and setting the active__v value to true.
On the third template, we're updating the name__v value and setting the active__v value to false.

Including a binder field name in the input but leaving its value blank will clear existing values from the field.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Templates\update_binder_templates.csv" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates

In this example:

The input file format is set to CSV.
The response format is not set and will default to JSON.
The path/name of the CSV input file in our local directory is specified.

Response (CSV)

responseStatus,name,errors
SUCCESS,binder_template_2__c,
SUCCESS,binder_template_3__c,
SUCCESS,binder_template_4__c,

On SUCCESS, Vault returns the names of the updated binder templates.

History

Since v13

Replace Binder Template Nodes

Replace all binder nodes in an existing binder template. This action removes all existing nodes and replaces them with those specified in the input.

Request

Send PUT to /api/{version}/objects/binders/templates/{template_name}/bindernodes

Headers

Input Content-Type - JSON application/json (default) or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{template_name} - The binder template name__v field value.

Example CSV Input

See the Create Binder Template Node above for example inputs, which are the same as those used in this request.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates/binder_template_1__c

History

Since v13

Delete Binder Template

Delete an existing binder template from your vault.

Request

Send DELETE to /api/{version}/objects/binders/templates/{template_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{template_name} - The binder template name__v field value.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates/binder_template_1__c

Response

json { "responseStatus": "SUCCESS" }`

Errors

Error Type	Error Message	Comments
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	You are not assigned permission to complete the request.
`METHOD_NOT_SUPPORTED`	The requested method {METHOD} is not supported.	Use the HTTP DELETE method for this request.
`MALFORMED_URL`	The resource {NAME} does not exist.	The specified binder template name could not be found in your vault.

History

Since v13

Binding Rules

Learn about Version Binding in Vault Help.

Update Binding Rule

Request

Send PUT to /api/{version}/objects/binders/{binder_id}/binding_rule

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.

Input

Field Name Description

binding_rule__v [Required] Indicates which binding rule to apply (which document versions to link to the section). Options are: default (bind to the latest available version (assumed if binding_rule is blank)), steady-state (bind to latest version in a steady-state), or current (bind to current version).

binding_rule_override__v [Required] Set to true or false to indicate if the specified binding rule should override documents or sections which already have binding rules set. If set to true, the binding rule is applied to all documents and sections within the current section. If blank or set to false, the binding rule is applied only to documents and sections within the current section that do not have a binding rule specified.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "binding_rule__v=steady-state" \
-d "binding_rule_override__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/binding_rule

Response

{
    "responseStatus": "SUCCESS",
    "id": 566
}

Errors

Error Type	Error Message	Comments
`INVALID_BINDER`	ID passed is not for a binder.
`INVALID_BINDING_RULE`	Binder rule not recognized.

History

Since v5

Update Binder Section Binding Rule

Request

Send PUT to /api/{version}/objects/binders/{binder_id}/sections/{node_id}/binding_rule

Binding rule setting applies to the current section and all sub-sections.

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.
{node_id} - The binder node id field value.

Input

Field Name Description

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "binding_rule__v=steady-state" \
-d "binding_rule_override__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/sections/1427232809771:1381853041/binding_rule

Response

{
    "responseStatus": "SUCCESS",
    "id": "1427491342404:-1828014479"
}

On SUCCESS, Vault returns the Node ID of the updated section.

Errors

Error Type	Error Message	Comments
`INVALID_BINDER`	ID passed is not for a binder.
`INVALID_SECTION`	Section ID is not a valid section.

History

Since v5

Update Binder Document Binding Rule

Request

Send PUT to /api/{version}/objects/binders/{binder_id}/documents/{node_id}/binding_rule

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value.
{node_id} - The binder node id field value.

Input

Field Name	Description
`binding_rule__v`	[Optional] Indicates which binding rule to apply (which document versions to link to the section). Options are: `default` (bind to the latest available version (assumed if binding_rule is blank)), `steady-state` (bind to latest version in a steady-state), `current` (bind to current version), or `specific` (bind to a specific version).
`major_version_number__v`	If the `binding_rule` is `specific`, then this is required and indicates the major version of the document to be linked. Otherwise it is ignored.
`minor_version_number__v`	If the `binding_rule` is `specific`, then this is required and indicates the major version of the document to be linked. Otherwise it is ignored.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "binding_rule__v=specific" \
-d "major_version_number__v=1" \
-d "minor_version_number__v=0" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/documents/1427491342404:-1828014479/binding_rule

Response

{
  "responseStatus": "SUCCESS",
  "id": "1427491342404:-1828014479"
}

On SUCCESS, Vault returns the Node ID of the updated document node within the binder

Errors

Error Type	Error Message	Comments
`INVALID_BINDER`	ID passed is not for a binder.
`INVALID_DOCUMENT`	Document ID is not a valid document or the document is not linked to the selected binder.

Objects

Each vault is configured with a set of standard objects (product__v, country__v, study__v, etc.). These vary by application and configuration.

Admins may also create custom objects (region__c, agency__c, manufacturer__c, etc.). Vault limits the total number of custom objects that Admins can create in a single vault. By default, the limit is 20.

The API supports retrieval of Vault Objects and their metadata.
The API does not support creating or updating Vault Objects. This must be done by Admin in the UI.

Each object can have multiple object records. For example, the product__v object may have records for products named CholeCap, Nyaxa, and Wonderdrug. All object records are user-defined.

The API supports retrieval of Vault Object Records and their metadata.
The API supports creating, updating, and deleting object records.

Learn about Vault Objects & Fields in Vault Help.

Vault Object Metadata

You can retrieve object metadata by sending a GET request to the /api/{version}/metadata/vobjects/{OBJECT_NAME} See the full request below.

The tables below provide detailed information about metadata available in API v15.0 and later.

Additionally, see About Document Reference Fields.

Object Fields (Default)

When creating a new custom object, the following fields are added by default:

Field Name	Default Field Label	Field Type	Description	Required	Editable	Queryable
`id`	ID	id	Object record ID. Unique object identifier (primary). Alphanumeric value.	System-Managed	False	True
`name__v`	Name	String	Object record name. Unique object record identifier.	True *	True *	True
`status__v`	Status	Picklist	Either `active__v` or `inactive__v`.	False	True	True
`created_by__v`	Created By	Object	Vault user ID of the person who created the object record.	System-Managed	False	True
`created_date__v`	Created Date	DateTime	The date and time when the object record was created.	System-Managed	False	True
`modified_by__v`	Modified By	Object	Vault user ID of the person who last modified the object record.	System-Managed	False	True
`modified_date__v`	Modified Date	DateTime	The date and time when the object record was last modified.	System-Managed	False	True

* Users cannot set or change the name__v field on objects when system-managed naming is enabled. See About System-Managed Object Record Names below.

Object Fields (EDL Node Metadata)

Objects in an EDL hierarchy contain metadata for each node. To retrieve this metadata, use the Retrieve Root Nodes endpoint.

Field Name	Default Field Label	Field Type	Description	Required	Editable	Queryable
`id`	ID	id	Unique ID of a node.	System-Managed	False	False
`order__v`	Order	Numeric	The position of a node in a hierarchy, relative to its siblings. For example, each level of a tree will have a node with `order__v = 1.`	True	True	False
`ref_type__v`	Object	Picklist	The type of object that the node is referencing.	False	False	False
`ref_name__v`	Reference Name	String	The name of the record being referenced.	False	False	False
`url`	URL	String	A link to the referenced object or record.	System-Managed	False	False
`ref_id__v`	Reference ID	ID	Id of the object/record being referenced.	System-Managed	False	False
`parent_id__v`	Parent ID	ID	Parent ID of a given node. This value is null for root nodes.	False	False	False

Object Metadata Fields

The following properties apply to the object itself and affect its object records. Not all properties are returned on all objects.

Metadata Fields	Description
`name`	Object name (`product__v`, `region__c`, etc.). This is the primary method of identifying objects in the API.
`label`	Object label (`Product`, `Region`, etc.). This is the primary method of identifying objects in the UI.
`label_plural`	Object label plural (`Products`, `Regions`, etc.). This is used only in the UI. It has no functional use in the API.
`prefix`	Object prefix. This is a 3-digit alphanumeric value automatically assigned to each object (`00P`, `00C`, `A01`, etc.). When creating a new record for the object, Vault uses the prefix as the first three characters of its object record ID. For example, if the `Product` object has the prefix `00P`, all product object record IDs could be `00P077101`, `00P077102`, etc. The object prefix and object record ID values vary from vault to vault and are not editable. In the UI, the object prefix is displayed in the URL when viewing objects in the Business Admin menu.
`description`	Short description of the object. Descriptions are displayed only in the API and in the object configuration page of the UI.
`help_content`	Short help message for the object. Help content appears in the UI with the question mark icon in the header of the object's maintenance page.
`source`	Either `standard` or `custom`. Standard objects (created by the system) have the `__v` suffix. Custom objects (created by Admin) have the `__c` suffix.
`status`	Either `active__v` or `inactive__v`. Standard objects (created by the system) cannot be set to inactive. Custom objects (created by Admin) can be enabled and disabled by Admin.
`in_menu`	Whether or not Admin has enabled the object to be listed in the Business Admin UI menu.
`order`	Integer value indicating the top-to-bottom order of objects listed in the Business Admin UI menu.
`auditable`	Whether or not Admin has enabled audit trail tracking on the object to track changes made to its object records. For standard objects, this is enabled by default and cannot be disabled. For custom objects, this can be enabled and disabled by Admin. Learn about Audit Trails in Vault Help.
`role_overrides`	Whether or not Admin has configured role override rules on the object.
`dynamic_security`	Whether or not Admin has enabled dynamic security (Custom Sharing Rules) on the object. When enabled, access to object records is controlled at the object record-level instead of at the object-level. Available in v11 or later. See the Retrieve Object Record response below. Learn about Dynamic Security in Vault Help.
`allow_attachments`	Whether or not Admin has enabled attachments on the object. When enabled on an object, users can "attach" related files (Documents, Images, etc.) to its object records. Available in v13 or later. See Object Record Attachments below. Learn about Object Record Attachments in Vault Help.
`system_managed`	Whether or not the object fields and records are entirely managed by the system (cannot be extended by users). This is only `true` for a limited number of standard objects, such as `workflow__v` and `doc_type_detail__v`. This is different from the `system_managed_name` field property described below.
`available_lifecycles`	Lists all available lifecycles that can be assigned to the object. Available in API v14 or later.
`urls`	Lists API endpoints to retrieve information about the object.
`fields`	Lists all fields (standard and custom) configured on the object. See Object Fields below.
`relationships`	Lists all relationships configured on the object. See Object Relationships below.
`created_by`	Vault user ID of the person who created the object. For standard objects (created by the system), this shows `1` (one).
`created_date`	Date and time when the object was created in UTC format (`YYYY-MM-DDTHH:MM:SS.000Z`).
`modified_by`	Vault user ID of the person who last modified the object.
`modified_date`	Date and time when the object was last modified in UTC format.

Object Metadata Fields (Properties)

The following information may be included with each field:

Metadata Fields	Description
`name`	Field name (`id`, `name__v`, `external_id__v`, etc.). This is the primary method of identifying fields in the API.
`label`	Field label (`ID`, `Name`, `External ID`, etc.). This is the primary method of identifying fields in the UI.
`type`	Field data type. See Object Field Types below.
`source`	Either `standard`, `sample`, or `custom`. Standard and sample object fields (created by the system) have the `__v` and `__vs` suffix, respectively. Custom objects (created by Admin) have the `__c` suffix.
`required`	Either `"required": true` or `"required": false`. This indicates whether or not the field must be configured with a value when creating a new object record.
`editable`	Either `"editable": true` or `"editable": false`. This indicates whether or not users can add or change the field value.
`status`	Either `active__v` or `inactive__v`. Standard (`__v`) object fields (created by the system) cannot be set to inactive. Custom object fields (`__c`) (created by Admin) and sample (`__vs`) object fields (created by the system) can be enabled and disabled by Admin.
`unique`	Whether or not the value stored in this field is unique. For example, the value for `name__v` can only be assigned to one object record (`"name__v": "CholeCap"` is unique); a value for `therapeutic_area__vs` (picklist) can be assigned to many object records (`"therapeutic_area__vs": "cardiology__vs"` is not unique).
`system_managed_name`	See About System-Managed Object Record Names below.
`value_format`	See About System-Managed Object Record Names below.
`start_number`	See About System-Managed Object Record Names below.
`lookup_relationship_name`	See About Object Lookup Fields below.
`lookup_source_field`	See About Object Lookup Fields below.
`component`	When the field type is `Component`, this lists the Vault component referenced by the field. Currently, this applies only to object lifecycles and lifecycle states.
`relationship_deep_copy`	Whether or not copying object records includes "deep copy". This property is only available on object reference fields for which deep copying is available. Deep copying object records can only be performed in the UI. Learn about Deep Copy in Vault Help.
`max_length`	This property is only on String/Text field types. It indicates the maximum number of characters that can be in the field value.
`max_value`	This property is only on Number field types. It indicates the maximum number of characters that can be set in the field value. Number fields will also show `min_value` and `scale` properties, indicating the minimum number of characters and the number of decimal places the value will store.
`list_column`	Either `true` or `false`. Whether or not the field column is displayed in the Business Admin object record table in the Vault UI.
`order`	The order (top to bottom) in which the field is listed in the object record details in Vault UI.
`created_by`	Vault user ID of the person who created the object. For standard objects (created by the system), this shows `1` (one).
`created_date`	Date and time when the object was created in UTC format (`YYYY-MM-DDTHH:MM:SS.000Z`).
`modified_by`	Vault user ID of the person who last modified the object.
`modified_date`	Date and time when the object was last modified in UTC format.

Object Relationships

The following properties apply object relationships:

Property	Description
`field`	n the selected object, this is the name of the field on which the relationship is defined.
`relationship_name`	The name of the relationship between the two objects. This always takes the singular or plural form of the related object ending in `__vr` for standard objects and `__cr` for custom objects.
`relationship_label`	The label of the related object.
`relationship_deletion`	Whether or not deletion of the relationship is blocked.
`object`	The object which has a relationship with the specified object. This field includes the endpoint URL to access the related object and its `name`, `label`, `label_plural`, and `prefix`.

Object Field Types

Standard and custom objects include the following field data types:

Field Type	Description
ID	System-managed field used only for the object record `id` field.
String/Text	Stores alphanumeric values up to a maximum length.
Number	Stores number values up to a maximum length.
Picklist	Stores picklist values. These can be configured as single-value or multi-value.
Boolean	Stores Yes/No and true/false values.
Date	Stores date values in UTC format (`YYYY-MM-DD`).
Date/Time	Stores date and time values in UTC format (`YYYY-MM-DDTHH:MM:SS.000Z`).
Object	References another object. These are used to create reference relationships with other Vault Objects and users.
Component	Used to store object lifecycles.

About Document Reference Fields

As of v15.0, Admins can configure Document Reference fields on objects. An object can reference a specific document version, or dynamically reference the latest version of a document. Learn more about Document Reference Fields in Vault Help.

Document Reference Field

To set the reference field, use the Bulk Object Records API to set the document’s version_id on the reference field’s name. Find this name by retrieving object metadata, where you can identify Document Reference fields with the following properties:

"relationship_type" : "reference" - shows the field has a reference relationship.
"name": "documents" - The name field on the related object shows that the reference relationship is a Document, aka the field is a Document Reference Field. See the example metadata below.

After identifying the Document Reference Field, use the field’s name to set the referred object. In the example metadata below, the field name is document_reference__c. The following JSON input will set the object to reference a document with id 12 and version number 2.3:

{
  "document_reference__c": "12.2.3"
}

Note that document_reference__c is the name set by your Admin, so you must check the metadata to find the given name.

Example Document Reference metadata:

{
  "label": "Product",
  "name": "product__v",
  "fields": [
    {
      "lookup_relationship_name": null,
      "source": "custom",
      "type": "Object",
      "relationship_outbound_name": "document_reference__cr",
      "required": false,
      "relationship_type": "reference",
      "relationship_criteria": null,
      "list_column": false,
      "document_version_reference": "specific",
      "order": 18,
      "help_content": null,
      "editable": true,
      "relationship_deletion": "block",
      "label": "Document Reference",
      "modified_date": "2016-07-18T20:36:48.000Z",
      "created_by": 61579,
      "relationship_inbound_label": "Products",
      "unique": false,
      "name": "document_reference__c",
      "modified_by": 61579,
      "relationship_inbound_name": "products__cr",
      "created_date": "2016-07-18T20:36:48.000Z",
      "lookup_source_field": null,
      "status": [
        "active__v"
      ],
      "object": {
        "label": "Documents",
        "name": "documents"
      }
    }
  ]
}

Unbound Reference Field

To set the unbound reference field, use the Bulk Object Records API to set the document’s id on the reference field’s name. Find this name by retrieving object metadata, where the Unbound Document Reference field will have the following property:

related_document_reference_field - The Document Reference Field paired with this Unbound Document Reference field. This attribute also identifies the field as an Unbound Document Reference field.

After identifying the Unbound Document Reference Field, use the field’s name to set the referred object. In the example metadata below, the field name is document_reference_unbound__c. The following JSON input will set the object to reference a document with id 12.

{
  "document_reference_unbound__c": "12"
}

Because this is an unbound document reference field, you do not need to add a specific version, as it will always point to the latest version. Note that document_reference_unbound__c is the name set by your Admin, so you must check the metadata to find the given name.

Example Unbound Document Reference metadata:

{
  "help_content": null,
  "editable": true,
  "lookup_relationship_name": null,
  "scale": 0,
  "label": "Document Reference (unbound)",
  "source": "custom",
  "type": "Number",
  "modified_date": "2016-07-18T20:36:48.000Z",
  "created_by": 61579,
  "required": false,
  "min_value": 1,
  "unique": false,
  "name": "document_reference_unbound__c",
  "list_column": false,
  "modified_by": 61579,
  "created_date": "2016-07-18T20:36:48.000Z",
  "related_document_reference_field": "document_reference__c",
  "lookup_source_field": null,
  "status": [
    "active__v"
  ],
  "max_value": 2147483647,
  "order": 19
}

About System-Managed Object Record Names

As of v14.0, Admins can configure Vault to automatically set the name__v field value of new object records on any custom object. Learn about System-Managed Object Record Naming in Vault Help.

When retrieving object metadata, the name__v field on all Vault Objects includes the following properties:

Metadata Field	Description
`system_managed_name`	Indicates (true/false) whether or not Admin has enabled system-managed naming on the object.
`value_format`	When the `"system_managed_name": true`, this shows the numbering format which Vault uses to automatically name the object records.
`start_number`	When the `"system_managed_name": true`, this shows the first number which Vault will use to name the object records.

The system_managed_name can only be set to true for custom objects. It cannot be set on standard objects such as product, country, study, etc.

The impact of system-managed names is that users cannot set or update the name of object records when creating or updating object records.

Shown below is the name__v field on a custom object where "system_managed_name": true.

      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "start_number": 1,
        "label": "Name",
        "source": "standard",
        "type": "String",
        "modified_date": "2016-02-29T22:36:03.000Z",
        "created_by": 46916,
        "required": true,
        "system_managed_name": true,
        "value_format": "VV-{######}",
        "unique": true,
        "name": "name__v",
        "list_column": true,
        "modified_by": 46916,
        "created_date": "2016-02-29T22:34:53.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 128,
        "order": 1
      }

"value_format": "VV-{######}" - The format which Vault uses to name the object records.
"start_number": 1 - The first object record will be named VV-000001, the second VV-000002, etc.

About Object Lookup Fields

As of v14.0, Admins can configure objects with fields that are mirror copies (replicas) of fields on a related object. These fields get their values by "looking up" the field values on the related objects through an object reference, parent-child, or document relationship. Hence, they are called "Lookup Fields". Learn about Object Relationships in Vault Help.

When retrieving object metadata, all standard and custom object fields include the following properties:

lookup_relationship_name - The outbound relationship name. These are generally named for the object that they reference.
lookup_source_field - The name of the field on the referenced/parent object. Vault displays this field value in the lookup field.

The properties will only have values for fields configured as lookups. These fields must utilize an outbound (parent or reference) object relationship. Often, the name of these fields match the name of the field they pull data from, but this is not required.

Shown below is the product_therapeutic_area__c field on the marketing_campaign__c object. Admin has set this as a lookup field pointing to the therapeutic_area__vs field on the product__v object.

"lookup_relationship_name": "product__cr" - The name of the relationship joining the product__v parent object and the marketing_campaign__c child object.
"lookup_source_field": "therapeutic_area__vs" - The field on the parent object that will be used to populate the product_therapeutic_area__c field on the child object.

      {
        "help_content": null,
        "multi_value": false,
        "editable": false,
        "lookup_relationship_name": "product__cr",
        "picklist": "therapeutic_area__vs",
        "label": "Product Therapeutic Area",
        "source": "custom",
        "type": "Picklist",
        "modified_date": "2016-02-17T18:08:07.000Z",
        "created_by": 25524,
        "required": false,
        "unique": false,
        "name": "product_therapeutic_area__c",
        "list_column": false,
        "modified_by": 25524,
        "created_date": "2016-02-17T18:08:07.000Z",
        "lookup_source_field": "therapeutic_area__vs",
        "status": [
          "active__v"
        ],
        "order": 12
      }

Retrieve Object Metadata

Retrieve all metadata configured on a standard or custom Vault Object.

Request

Send GET to /api/{version}/metadata/vobjects/{object_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{object_name} - The object name__v field value (product__v, country__v, custom_object__c, etc.).

Options

loc - To retrieve localized (translated) strings, include the parameter loc=true. See the next request below for details.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/vobjects/product__v

Response

{
  "responseStatus": "SUCCESS",
  "object": {
    "available_lifecycles": [],
    "label_plural": "Products",
    "help_content": null,
    "prefix": "00P",
    "in_menu": true,
    "description": null,
    "label": "Product",
    "source": "standard",
    "modified_date": "2015-07-30T20:55:16.000Z",
    "created_by": 1,
    "allow_attachments": false,
    "dynamic_security": false,
    "relationships": [
      {
        "relationship_name": "user_role_setup__cr",
        "relationship_label": "User Role Setup",
        "field": "product__c",
        "relationship_type": "reference_inbound",
        "relationship_deletion": "block",
        "object": {
          "url": "/api/v15.0/metadata/vobjects/user_role_setup__v",
          "label": "User Role Setup",
          "name": "user_role_setup__v",
          "label_plural": "User Role Setup",
          "prefix": "0MY"
        }
      }
    ],
    "urls": {
      "field": "/api/v15.0/metadata/vobjects/product__v/fields/{name}",
      "record": "/api/v15.0/vobjects/product__v/{id}",
      "list": "/api/v15.0/vobjects/product__v",
      "metadata": "/api/v15.0/metadata/vobjects/product__v"
    },
    "role_overrides": false,
    "auditable": true,
    "name": "product__v",
    "modified_by": 1,
    "created_date": "2015-07-30T20:55:16.000Z",
    "system_managed": false,
    "fields": [
      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "label": "ID",
        "source": "standard",
        "type": "ID",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "name": "id",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 0
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "start_number": null,
        "label": "Product Name",
        "source": "standard",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": true,
        "system_managed_name": false,
        "value_format": null,
        "unique": true,
        "name": "name__v",
        "list_column": true,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 128,
        "order": 1
      },
      {
        "help_content": null,
        "multi_value": false,
        "editable": true,
        "lookup_relationship_name": null,
        "picklist": "default_status__v",
        "label": "Status",
        "source": "standard",
        "type": "Picklist",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": true,
        "unique": false,
        "name": "status__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 2
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "Product Abbreviation",
        "source": "sample",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "abbreviation__vs",
        "list_column": true,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 10,
        "order": 3
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "Generic Name",
        "source": "sample",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "generic_name__vs",
        "list_column": true,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 100,
        "order": 4
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "Internal Name",
        "source": "sample",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "internal_name__vs",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 100,
        "order": 5
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "Compound ID",
        "source": "sample",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "compound_id__vs",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 100,
        "order": 6
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "INN",
        "source": "sample",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "inn__vs",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 100,
        "order": 7
      },
      {
        "help_content": null,
        "multi_value": false,
        "editable": true,
        "lookup_relationship_name": null,
        "picklist": "therapeutic_area__vs",
        "label": "Therapeutic Area",
        "source": "sample",
        "type": "Picklist",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "therapeutic_area__vs",
        "list_column": true,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 8
      },
      {
        "help_content": null,
        "multi_value": true,
        "editable": true,
        "lookup_relationship_name": null,
        "picklist": "product_family__vs",
        "label": "Product Family",
        "source": "sample",
        "type": "Picklist",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "product_family__vs",
        "list_column": true,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 9
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "External ID",
        "source": "standard",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": true,
        "name": "external_id__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 50,
        "order": 10
      },
      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "label": "Created By",
        "source": "standard",
        "type": "Object",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "relationship_type": "reference",
        "unique": false,
        "name": "created_by__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "object": {
          "name": "users"
        },
        "order": 11
      },
      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "label": "Created Date",
        "source": "standard",
        "type": "DateTime",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "name": "created_date__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 12
      },
      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "label": "Last Modified By",
        "source": "standard",
        "type": "Object",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "relationship_type": "reference",
        "unique": false,
        "name": "modified_by__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "object": {
          "name": "users"
        },
        "order": 13
      },
      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "label": "Last Modified Date",
        "source": "standard",
        "type": "DateTime",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "name": "modified_date__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 14
      }
    ],
    "object_class": "base",
    "status": [
      "active__v"
    ],
    "order": 1
  }
}

The response includes all metadata configured on the object.

Retrieve Localized Strings

When available, you can retrieve localized (translated) strings for the label, label_plural, and help_content object fields by adding loc=true to request.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/vobjects/product__v?loc=true

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "object": {
    "available_lifecycles": [],
    "label_plural": "Products",
    "prefix": "00P",
    "description": null,
    "source": "standard",
    "allow_attachments": false,
    "relationships": [
      {
        "relationship_name": "user_role_setup__cr",
        "relationship_label": "User Role Setup",
        "field": "product__c",
        "relationship_type": "reference_inbound",
        "localized_data": {
          "relationship_label": {
            "en": "User Role Setup"
          }
        },
        "relationship_deletion": "block",
        "object": {
          "url": "/api/v15.0/metadata/vobjects/user_role_setup__v",
          "label": "User Role Setup",
          "name": "user_role_setup__v",
          "label_plural": "User Role Setup",
          "prefix": "0MY",
          "localized_data": {
            "label_plural": {
              "de": "Benutzerrollenkonfiguration",
              "ru": "Настройки функции пользователя",
              "kr": "사용자 역할 설정",
              "en": "User Role Setup",
              "it": "Configurazione ruolo utente",
              "pt_BR": "Configuração da função de usuário",
              "fr": "Configuration du rôle utilisateur",
              "zh": "用户角色设置",
              "es": "Configuración de cargos de usuario",
              "zh_TW": "使用者角色設定",
              "ja": "ユーザロール設定",
              "pl": "Konfiguracja roli użytkownika",
              "tr": "Kullanıcı Rolü Ayarı",
              "pt_PT": "Configuração da função de utilizador"
            },
            "label": {
              "de": "Benutzerrollenkonfiguration",
              "ru": "Настройки функции пользователя",
              "kr": "사용자 역할 설정",
              "en": "User Role Setup",
              "it": "Configurazione ruolo utente",
              "pt_BR": "Configuração da função de usuário",
              "fr": "Configuration du rôle utilisateur",
              "zh": "用户角色设置",
              "es": "Configuración de cargos de usuario",
              "zh_TW": "使用者角色設定",
              "ja": "ユーザロール設定",
              "pl": "Konfiguracja roli użytkownika",
              "tr": "Kullanıcı Rolü Ayarı",
              "pt_PT": "Configuração da função de utilizador"
            }
          }
        }
      }
    ],
    "urls": {
      "field": "/api/v15.0/metadata/vobjects/product__v/fields/{name}",
      "record": "/api/v15.0/vobjects/product__v/{id}",
      "list": "/api/v15.0/vobjects/product__v",
      "metadata": "/api/v15.0/metadata/vobjects/product__v"
    },
    "role_overrides": false,
    "localized_data": {
      "label_plural": {
        "de": "Produkte",
        "ru": "Продукты",
        "kr": "제품",
        "en": "Products",
        "pt_BR": "Produtos",
        "it": "Prodotti",
        "fr": "Produits",
        "es": "Productos",
        "zh": "产品",
        "zh_TW": "產品",
        "ja": "製品",
        "pl": "Produkty",
        "tr": "Ürünler",
        "pt_PT": "Produtos"
      },
      "label": {
        "de": "Produkt",
        "ru": "Продукт",
        "kr": "제품",
        "en": "Product",
        "pt_BR": "Produto",
        "it": "Prodotto",
        "fr": "Produit",
        "es": "Producto",
        "zh": "产品",
        "zh_TW": "產品",
        "ja": "製品",
        "pl": "Produkt",
        "tr": "Ürün",
        "pt_PT": "Produto"
      }
    },
    ...

Details

When localized data is requested, the response includes an additional localized_data field. This contains translated fields and field values on each object field for which localized strings have been configured. This data is only available at the object and field level and only if localized strings have been configured on objects in your vault.

History

Since v8

Retrieve Object Field Metadata

Request

Send GET to /api/{version}/metadata/vobjects/{object_name}/fields/{object_field_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{object_name} - The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_field_name} - The object field name value (id, name__v, external_id__v, etc.).

Options

loc - To retrieve localized (translated) strings, include the parameter loc=true. See the next request below for details.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/vobjects/product__v/fields/name__v

Response

{
  "responseStatus": "SUCCESS",
  "field": {
    "help_content": null,
    "editable": true,
    "lookup_relationship_name": null,
    "start_number": null,
    "label": "Product Name",
    "source": "standard",
    "type": "String",
    "modified_date": "2015-07-30T20:55:16.000Z",
    "created_by": 1,
    "required": true,
    "system_managed_name": false,
    "value_format": null,
    "unique": true,
    "name": "name__v",
    "list_column": true,
    "modified_by": 1,
    "created_date": "2015-07-30T20:55:16.000Z",
    "lookup_source_field": null,
    "status": [
      "active__v"
    ],
    "max_length": 128,
    "order": 1
  }
}

The response includes all metadata configured on the specific Vault Object field. Refer to the Vault Object Metadata tables above for field descriptions.

Retrieve Localized Strings

When available, you can retrieve localized (translated) strings for the label and help_content object fields by adding loc=true to request.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/vobjects/product__v/fields/name__v?loc=true

Response

{
  "responseStatus": "SUCCESS",
  "field": {
    "help_content": null,
    "editable": true,
    "lookup_relationship_name": null,
    "start_number": null,
    "label": "Product Name",
    "source": "standard",
    "type": "String",
    "modified_date": "2015-07-30T20:55:16.000Z",
    "created_by": 1,
    "required": true,
    "localized_data": {
      "label": {
        "de": "Produktbezeichnung",
        "ru": "Название продукта",
        "kr": "제품 이름",
        "en": "Product Name",
        "pt_BR": "Nome do produto",
        "it": "Nome prodotto",
        "fr": "Nom de produit",
        "es": "Nombre de producto",
        "zh": "产品名称",
        "zh_TW": "產品名稱",
        "ja": "製品名",
        "pl": "Nazwa produktu",
        "tr": "Ürün Adı",
        "pt_PT": "Nome do produto"
      }
    },
    "system_managed_name": false,
    "value_format": null,
    "unique": true,
    "name": "name__v",
    "list_column": true,
    "modified_by": 1,
    "created_date": "2015-07-30T20:55:16.000Z",
    "lookup_source_field": null,
    "status": [
      "active__v"
    ],
    "max_length": 128,
    "order": 1
  }
}

Details

History

Since v8

Retrieve Object Collection

Request

Send GET to /api/{version}/metadata/vobjects

Headers

Response Accept - JSON application/json (default) or XML application/xml

Options

loc - To retrieve localized (translated) strings, include the parameter loc=true. See the next request below for details.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/vobjects

Response

{
  "responseStatus": "SUCCESS",
  "objects": [
    {
      "url": "/api/v15.0/metadata/vobjects/product__v",
      "label": "Product",
      "name": "product__v",
      "label_plural": "Products",
      "prefix": "00P",
      "order": 1,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/country__v",
      "label": "Country",
      "name": "country__v",
      "label_plural": "Countries",
      "prefix": "00C",
      "order": 2,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/application_role__v",
      "label": "Application Role",
      "name": "application_role__v",
      "label_plural": "Application Role",
      "prefix": "0AR",
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/doc_type_group__v",
      "label": "Document Type Group",
      "name": "doc_type_group__v",
      "label_plural": "Document Type Groups",
      "prefix": "0DG",
      "order": 3,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/doc_type_detail__v",
      "label": "Document Type Detail",
      "name": "doc_type_detail__v",
      "label_plural": "Document Type Details",
      "prefix": "0DT",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/user_role_setup__v",
      "label": "User Role Setup",
      "name": "user_role_setup__v",
      "label_plural": "User Role Setup",
      "prefix": "0MY",
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/binder_metadata__v",
      "label": "Binder Section Metadata",
      "name": "binder_metadata__v",
      "label_plural": "Binder Sections Metadata",
      "prefix": "OBD",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/vault_component__v",
      "label": "Vault Component",
      "name": "vault_component__v",
      "label_plural": "Vault Components",
      "prefix": "0CD",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/outbound_package__v",
      "label": "Outbound Package",
      "name": "outbound_package__v",
      "label_plural": "Outbound Packages",
      "prefix": "0PO",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/package_component__v",
      "label": "Package Component",
      "name": "package_component__v",
      "label_plural": "Package Components",
      "prefix": "0CP",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/directory__v",
      "label": "Directory",
      "name": "directory__v",
      "label_plural": "Directories",
      "prefix": "0DI",
      "order": 4,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/survey__v",
      "label": "Survey",
      "name": "survey__v",
      "label_plural": "Surveys",
      "prefix": "0SV",
      "order": 5,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/distribution__v",
      "label": "Distribution",
      "name": "distribution__v",
      "label_plural": "Distributions",
      "prefix": "0DS",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/crm_org__v",
      "label": "CRM Org",
      "name": "crm_org__v",
      "label_plural": "CRM Orgs",
      "prefix": "0CO",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    }
  ]
}

Details

The response includes a summary of key information (url, label, name, prefix, status, etc.) for all standard and custom Vault Objects configured in your vault. Refer to the Vault Object Metadata tables above for field descriptions.

Retrieve Localized Strings

When available, you can retrieve localized (translated) strings for the label and label_plural object fields by adding loc=true to request.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/vobjects?loc=true

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "objects": [
    {
      "url": "/api/v15.0/metadata/vobjects/product__v",
      "label": "Product",
      "name": "product__v",
      "label_plural": "Products",
      "prefix": "00P",
      "order": 1,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ],
      "localized_data": {
        "label_plural": {
          "de": "Produkte",
          "ru": "Продукты",
          "kr": "제품",
          "en": "Products",
          "pt_BR": "Produtos",
          "it": "Prodotti",
          "fr": "Produits",
          "es": "Productos",
          "zh": "产品",
          "zh_TW": "產品",
          "ja": "製品",
          "pl": "Produkty",
          "tr": "Ürünler",
          "pt_PT": "Produtos"
        },
        "label": {
          "de": "Produkt",
          "ru": "Продукт",
          "kr": "제품",
          "en": "Product",
          "pt_BR": "Produto",
          "it": "Prodotto",
          "fr": "Produit",
          "es": "Producto",
          "zh": "产品",
          "zh_TW": "產品",
          "ja": "製品",
          "pl": "Produkt",
          "tr": "Ürün",
          "pt_PT": "Produto"
        }
      }
    },
    ...

Details

History

Since v8

Retrieve Object Record Collection

Retrieve all records for a specific Vault Object.

Request

Send GET to /api/{version}/vobjects/{object_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{object_name} - The object name__v field value (product__v, country__v, custom_object__c, etc.).

Options

fields - To specify fields to retrieve, include the parameter fields={FIELD_NAMES}. See the next request below for details.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 3,
        "limit": 200,
        "offset": 0,
        "url": "/api/v15.0/vobjects/product__v",
        "object": {
            "url": "/api/v15.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            "prefix": "0PR",
            "order": 1,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "label_plural": "Products",
            "in_menu": true
    },
    "data": [
        {
            "id": "0PR0202",
            "name__v": "CholeCap"
        },
        {
            "id": "0PR0303",
            "name__v": "Gludacta"
        },
        {
            "id": "0PR0404",
            "name__v": "Nyaxa"
        }
    ]
}

The response includes the object metadata for the specified object and the id and name__v of all object records configured on the object.

Limit, Sort, and Paginate Results

By default, Vault returns a maximum of 200 object records per page. You can change (lower) this using the limit operator. For example, to limit the number of records to 20 per page:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/study__v?limit=20

The limit operator must be a positive integer. Values over 200 are ignored.

By default, Vault sorts the list by the object record id in ascending order. You can change this to sort in descending desc or ascending asc order based on an object field. For example, to sort by the name of each product in descending order:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/study__v?sort=name__v desc

With a maximum of 200 records returned per page, you must submit a new request to see the "next page" of results (when more than 200 object records exist). Vault provides two methods to accomplish pagination: the offset operator and the next_page/previous_page URLs.

The offset operator is used in request in the same way as the limit operator above. For example, if you're viewing the first page of 200 results (default maximum per page) out of 1000 total results found and want to see the next 200 results, enter offset=201.

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/study__v?offset=201

The offset operator must be a positive integer. Values equaling to a number larger than the total number of records in the collection will not return any results.

To use limit, offset, and sort together, structure the string in the following manner:

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/study__v?limit=10&offset=51&sort=name__v desc

The request shown above will return 10 results per page, staring with page 5 (results 51-60), and sort the results by the object record name in descending order.

Alternatively, you can use the next_page/previous_page URLs in the response to paginate results. Consider the following abridged response for an object record request:

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 1000,
        "limit": 200,
        "offset": 601,
        "previous_page": "/api/v15.0/vobjects/study__v?limit=200&offset=401",
        "next_page": "/api/v15.0/vobjects/study__v?limit=200&offset=801",
        "object": {
        ...

There are a total of 1000 object records found. We used the default maximum of 200 records per page and offset the results to 601, meaning this response is displaying results 601-800 (page 3). Notice the next_page URL shows a limit of 200 and offset of 401 (to view page 4) and the previous_page URL shows a limit of 200 and offset of 801 (to view page 4.).

The pagination URLs are automatically provided in the response when the number of records exceeds the maximum number of results per page. These strings can be used to basically "copy and paste" your next query to paginate the entire result set. The numbers at the end of the string (?limit=200&offset=801") can also be modified with different limits and offsets before using the string to change the pagination.

Note that the next_page and previous_page strings only remain active for about 15 minutes following the query.

Retrieve Specific Object Record Fields

You can augment the request to retrieve fields other than the default object record id and name__v by using the fields parameter and a comma-delimited list of object field names.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/product__v?fields=id,name__v,external_id__v,generic_name__vs

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 3,
        "limit": 200,
        "object": {
            "url": "/api/v15.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            ...
        "url": "/api/v15.0/vobjects/product__v?fields=id,name__v,external_id__v,generic_name__vs"
    },
    "data": [
        {
            "id": "0PR0202",
            "name__v": "CholeCap",
            "external_id__v": "CHO-PROD-0772",
            "generic_name__vs": "cholepriol phosphate"
        },
        {
            "id": "0PR0303",
            "name__v": "Gludacta",
            "external_id__v": "GLU-PROD-0773",
            "generic_name__vs": "glucerin sulfate"
        },
        {
            "id": "0PR0404",
            "name__v": "Nyaxa",
            "external_id__v": "NYA-PROD-0774",
            "generic_name__vs": "nitroprinaline oxalate"
        }
    ]
}

History

Since v8

Retrieve Object Record

Retrieve metadata configured on a specific object record in your vault.

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{object_name} - The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id} - The object record id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/product__v/0PR0202

Response

{
  "responseStatus": "SUCCESS",
  "responseDetails": {
    "url": "/api/v15.0/vobjects/product__v/00PR0202",
    "object": {
      "url": "/api/v15.0/metadata/vobjects/product__v",
      "label": "Product",
      "name": "product__v",
      "label_plural": "Products",
      "prefix": "00P"
    }
  },
  "data": {
    "external_id__v": "CHO-457",
    "product_family__vs": [
      "cholepriol__c"
    ],
    "compound_id__vs": "CHO-55214",
    "abbreviation__vs": "CHO",
    "therapeutic_area__vs": [
      "endocrinology__vs"
    ],
    "name__v": "CholeCap",
    "modified_by__v": 12022,
    "modified_date__v": "2016-05-10T21:06:11.000Z",
    "inn__vs": null,
    "created_date__v": "2015-07-30T20:55:16.000Z",
    "id": "00PR0202",
    "internal_name__vs": null,
    "generic_name__vs": "cholepriol phosphate",
    "status__v": [
      "active__v"
    ],
    "created_by__v": 1
  },
  "manually_assigned_sharing_roles": {
    "owner__v": {
      "groups": null,
      "users": [
        12022
      ]
    },
    "viewer__v": {
      "groups": [
        3311303
      ],
      "users": [
        35551,
        48948,
        55002
      ]
    },
    "editor__v": {
      "groups": [
        4411606
      ],
      "users": [
        60145,
        70012,
        89546
      ]
    }
  }
}

Details

On SUCCESS, the response lists all fields and values configured on the object record.

When Custom Sharing Rules have been enabled on the object ("dynamic_security": true), the response includes the following additional information:

manually_assigned_sharing_roles

owner__v
viewer__v
editor__v

These are the users and groups that have been manually assigned to each role on the object record.

Not all object records will have users and groups assigned to roles. You can update object records to add or remove users and/or groups on each role.

History

Since v8
v11+ - Supports Custom Sharing Rules. Response includes manually_assigned_sharing_roles (when configured).

Create Object Records

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Object Records\create_object_records.csv" \
https://myvault.veevavault.com/api/v8.0/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "0PR0771",
                "url": "api/v8.0/vobjects/product__v/0PR0771"
            }
        },
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "0PR0772",
                "url": "api/v8.0/vobjects/product__v/0PR0772"
            }
        },
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "0PR0773",
                "url": "api/v8.0/vobjects/product__v/0PR0773"
            }
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not created."
                }
            ]
        }
    ]
}

Create Object Records in bulk.

The maximum input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.

POST /api/{version}/vobjects/{object_name}

Headers

Name	Description
`Content-Type`	`text/csv` or `application/json`
`Accept`	`application/json` (default) or `text/csv`

URI Path Parameters

Name	Description
`{object_name}`	The name of the object, for example, `product__v`.

Body Parameters

Upload parameters as a JSON or CSV file.

Name	Description
`name__v`	This field is required unless it is set to system-managed. To find out if an object uses system-managed naming, retrieve its `name__v` field and look for the `system_managed_name` property set to `true` or `false`. Learn more about system-managed naming in Vault Help.
`source_record_id`	Optional: To copy an existing object record, add this field with the `id` of the existing object record. Any values specified for other fields will override the copied values. If you want to make a deep copy of a record, see the Deep Copy endpoint.

Admin may set other standard or custom object fields to required. Use the Object Metadata API to retrieve all fields configured on objects. You can add any object field with editable: true.

Update Object Records

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Object Records\update_object_records.csv" \
https://myvault.veevavault.com/api/v8.0/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        },
        {
            "responseStatus": "SUCCESS"
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not updated."
                }
            ]
        }
    ]
}

Update Object Records in bulk.

The maximum input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.

PUT /api/{version}/vobjects/{object_name}

Headers

Name	Description
`Content-Type`	`text/csv` or `application/json`
`Accept`	`application/json` (default) or `text/csv`

URI Path Parameters

Name	Description
`{object_name}`	The name of the object, for example, `product__v`.

Body Parameters

Upload parameters as a JSON or CSV file.

Name	Description
`id`	The object record ID.

Admin may set other standard or custom object fields to required. Use the Object Metadata API to retrieve all fields configured on objects. You can update any object field with editable: true.

Note that if an object is a parent in a parent-child relationship with another object, you cannot update its status__v field in bulk.

If Dynamic Security (Custom Sharing Rules) is configured on an object, you can add or remove users and groups on manually assigned roles. For example, editor__v.users. This will overwrite any users currently in the role.

Delete Object Record

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Object Records\delete_object_records.csv" \
https://myvault.veevavault.com/api/v14.0/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        },
        {
            "responseStatus": "SUCCESS"
        },        
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not deleted."
                }
            ]
        }
    ]
}

Delete Object Records in bulk.

The maximum input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.

DELETE /api/{version}/vobjects/{object_name}

Headers

Name	Description
`Content-Type`	`text/csv` or `application/json`
`Accept`	`application/json` (default) or `text/csv`

URI Path Parameters

Name	Description
`{object_name}`	The name of the object, for example, `product__v`.

Body Parameters

Upload parameters as a JSON or CSV file.

Name	Description
`id`	The system-assigned object record ID to delete.
`external_id__v`	Optional: Instead of `id`, you can use this user-defined document external ID.

Query String Parameters

Name	Description
`idParam`	If you're identifying documents in your input by their external ID, add `idParam=external_id__v` to the request endpoint.

Admin may set other standard or custom object fields to required. Use the Object Metadata API to retrieve all fields configured on objects. You can update any object field with editable: true.

Cascade Delete Object Record

This asynchronous endpoint will delete a single parent object record and all related children and grandchildren.

Request

Send POST to /api/{version}/vobjects/{object_name}/{object_record_id}/actions/cascadedelete

Headers

Accept: application/json (default) or text/csv

Parameters

object_name - The name of the object to delete.
object_record_id - The ID of the specific object record to delete.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v16.0/vobjects/product__v/00P000000000302/actions/cascadedelete

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 27301,
  "url": "/api/v16.0/services/jobs/27404"
}

Get Results of Cascade Delete Job

After submitting a request to deep copy an object record, you can query vault to determine the results of the request. Before submitting this request:

You must have previously requested a cascade delete job (via the API) which is no longer active.
You must have a valid job_id value, retrieved from the response of the cascade delete request.

Request

Send GET to /api/{version}/vobjects/cascadedelete/results/{object_name}/{job_status}/{job_id}

Headers

Accept: text/csv (default)

Parameters

object_name - The name of the object which was deleted.
job_id - The ID of the job, retrieved from the response of the job request.
job_status - Possible values are success or failure. Find if your job succeeded or failed by retrieving the job status.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Accept: text/csv" \
https://myvault.veevavault.com/api/v16.0/vobjects/cascadedelete/results/product__v/success/27404

Response

Source Object, Record Id
product__v, OP0000146
edl__v, OE0000147
edl_item__v, EE123456

Deep Copy Object Record

Deep Copy copies an object record, including all of the record’s related child and grandchild records. A single deep copy cannot copy more than 10,000 records at a time.

You can perform a regular copy an object record using the Bulk Object API with the source_record_id field.

Request

Send POST to /api/{version}/vobjects/{object_name}/{object_record_ID}/actions/deepcopy

Headers

Content-Type: application/json or text/csv Accept: application/json (default) or application/xml

Parameters

object_name - The name of the parent object to copy. For example, product__v. object_record_ID - The ID of the specific object record to copy.

Body

In the body, pass in any fields to override the copied fields. For example, add the abbreviation__vs field to override the copied value for abbreviation.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
https://myvault.veevavault.com/api/v16.0/vobjects/product__v/00P000000000202/actions/deepcopy

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 26001,
  "url": "/api/v16.0/services/jobs/26001"
}

Get Results of Deep Copy Job

After submitting a request to deep copy an object record, you can query vault to determine the results of the request. Before submitting this request:

You must have previously requested a cascade delete job (via the API) which is no longer active.
You must have a valid job_id value, retrieved from the response of the deep copy request.

Request

Send GET to /api/{version}/vobjects/deepcopy/results/{object_name}/{job_status}/{job_id}

Headers

Accept: text/csv (default)

Parameters

object_name - The name of the object which was deleted.
job_id - The ID of the job, retrieved from the response of the job request.
job_status - Possible values are success or failure. Find if your job succeeded or failed by retrieving the job status.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Accept: text/csv" \
https://myvault.veevavault.com/api/v16.0/vobjects/deepcopy/results/product__v/failure/26901

Response

line number,vobject,sourceRecordId,errors
1,product__v,00P000000000301,"""PARAMETER_REQUIRED|Missing required parameter [internal_name__vs]"",""OPERATION_NOT_ALLOWED|Another resource already exists with [name__v=WonderDrug]"""

Retrieve Deleted Object Record ID

Retrieve the IDs of object records that have been deleted from your vault within the past 30 days. After object records are deleted from a vault, their IDs are still available for retrieval for 30 days. After that, they cannot be retrieved. You can use the optional request parameters below to narrow the results to a specific date and time range within the past 30 days.

Request

Send GET to /api/{version}/objects/deletions/vobjects/{object_name}

Headers

Response Accept - JSON application/json (default) or CSV text/csv

Parameters

By default, Vault will retrieve all object records deleted within the past 30 days. This can be modified by using one or both of the following parameters:

start_date - [Optional] Specify a date (no more than 30 days past) after which Vault will look for deleted object records.
end_date - [Optional] Specify a date (no more than 30 days past) before which Vault will look for deleted object records.

For example, assuming today is January 20:

To retrieve all object records deleted since 7AM on January 15: api/v15.0/objects/deletions/vobjects?start_date=2016-01-16T07:00:00Z
To retrieve all object records deleted between 7AM - 5PM on January 15: api/v15.0/objects/deletions/vobjects?start_date=2016-01-16T07:00:00Z&end_date=2016-01-16T17:00:00Z

About dates and times:

Dates and times are in UTC and must be formatted as YYYY-MM-DDTHH:MM:SSZ. If the time is not specified, it will default to midnight (T00:00:00Z) on the specified date.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/deletions/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 35,
        "limit": 200,
        "size": 35,
        "offset": 0,
    },
    "data": [
        {
            "id": "0PR0202",
            "deleted_date": "2016-01-20T05:24:20Z"
        },
        {
            "id": "0PR0303",
            "deleted_date": "2016-01-20T04:23:21Z"
        },
        {
            "id": "0PR0404",
            "deleted_date": "2016-01-20T03:22:22Z"
        },
        ...
    ]
}

History

Since v14

Object Record Attachments

Determine if Attachments are Enabled on an Object

Request

Send GET request to the /api/{version}/metadata/vobjects/{object_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{object_name} - The object name__v field value (product__v, country__v, custom_object__c, etc.).

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/vobjects/site__v

Response (abridged)

{
    "responseStatus": "SUCCESS",
    "object": {
        "created_date": "2014-02-03T20:12:29.000Z",
        "created_by": 1,
        "allow_attachments": true,
        "auditable": true,
        "modified_date": "2015-01-06T22:34:15.000Z",
        "status": [
            "active__v"
        ],
        "urls": {
            "field": "/api/v15.0/metadata/vobjects/site__v/fields/{NAME}",
            "record": "/api/v15.0/vobjects/site__v/{id}",
            "attachments": "/api/v15.0/vobjects/site__v/{id}/attachments",
            "list": "/api/v15.0/vobjects/site__v",
            "metadata": "/api/v15.0/metadata/vobjects/site__v"
        },
        "label_plural": "Study Sites",
        "role_overrides": false,
        "label": "Study Site",
        "in_menu": true,
        "help_content": null,
        "source": "standard",
        "order": null,
        "modified_by": 46916,
        "description": null,
        "name": "site__v",
        ...
}

Details

Shown above, "allow_attachments" is set to true for this object and "attachments" is included in the list of urls, indicating that attachments are enabled on the site__v object. This means that any of the object records can have attachments.

History

Since v12

Retrieve Object Record Attachments

Retrieve a list of all attachments on a specific object record.

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{object_name} - The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id} - The object record id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/metadata/vobjects/site__v/1357752909483/attachments

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 558,
            "filename__v": "Site Contact List.docx",
            "description__v": "Facilities information and contacts",
            "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "size__v": 11450,
            "md5checksum__v": "9c6f61847207898ca98431d3e9ad176d",
            "version__v": 3,
            "created_by__v": 46916,
            "created_date__v": "2015-01-07T21:42:47.772Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.vaultdev.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/3"
                }
            ]
        },
        {
            "id": 571,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 1,
            "created_by__v": 46916,
            "created_date__v": "2015-01-16T22:28:44.039Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions/1"
                }
            ]
        }
    ]
}

Details

Shown above, the site__v object record has three versions of attachment id 558 and one version of attachment id 571. Attachment versioning uses integer numbers beginning with 1 and incrementing sequentially (1, 2, 3,...). There is no concept of major or minor version numbers with attachments.

History

Since v12

Retrieve Object Record Attachment Metadata

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{object_name} - The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id} - The object record id field value.
{attachment_id} - The attachment id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 558,
            "filename__v": "Site Contact List.docx",
            "description__v": "Facilities information and contacts",
            "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "size__v": 11450,
            "md5checksum__v": "9c6f61847207898ca98431d3e9ad176d",
            "version__v": 3,
            "created_by__v": 46916,
            "created_date__v": "2015-01-07T21:42:47.772Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.vaultdev.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.vaultdev.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.vaultdev.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/3"
                }
            ]
        }
    ]
}

Details

History

Since v12

Retrieve Object Record Attachment Versions

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/versions

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "version__v": 1,
            "url": "https://myvault.vaultdev.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions/1"
        }
    ]
}

Errors

Error Type	Error Message	Comments
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to retrieve metadata from an attachment {id} which does not exist on the specified object record.
`MALFORMED_URL`	The resource [{id}/versions/{version}] does not exist.	You are trying to retrieve metadata from a specific version {version} of an attachment {id} which does not exist on the specified object record. The attachment {id} exists but the version number {version} does not.

History

Since v12

Retrieve Object Record Attachment Version Metadata

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/versions/{attachment_version}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions/1

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 571,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 1,
            "created_by__v": 46916,
            "created_date__v": "2015-01-16T22:28:44.039Z"
        }
    ]
}

Errors

Error Type	Error Message	Comments
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to retrieve metadata from an attachment {id} which does not exist on the specified object record.
`MALFORMED_URL`	The resource [{id}/versions/{version}] does not exist.	You are trying to retrieve metadata from a specific version {version} of an attachment {id} which does not exist on the specified object record. The attachment {id} exists but the version number {version} does not.

History

Since v12

Download Object Record Attachment File

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/file

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/file

Response

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="file.pdf"

Details

The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. When downloading attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachments (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Errors

Error Type	Error Message	Comments
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to retrieve an attachment {id} which does not exist on the specified object record.
`MALFORMED_URL`	The resource does not contain attachments.	You are trying to retrieve an attachment from an object record which does not have any attachments.

History

Since v12

Download Object Record Attachment Version File

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/versions/{attachment_version}/file

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions/1/file

Details

On SUCCESS, Vault retrieves the specified version of the attachment from the object record. The file name is the same as the attachment file name.

The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. When downloading attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachments (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Response Header

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="file.pdf"

Errors

Error Type	Error Message	Comments
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to retrieve an attachment {id} which does not exist on the specified object record.
`MALFORMED_URL`	The resource [{id}/versions/{version}] does not exist.	You are trying to retrieve a specific version {version} of an attachment {id} which does not exist on the specified object record. The attachment {id} exists but the version number {version} does not.
`MALFORMED_URL`	The resource does not contain attachments.	You are trying to retrieve an attachment from an object record which does not have any attachments.

History

Since v12

Download All Object Record Attachment Files

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/file

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{object_name} - The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id} - The object record id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/file

Response

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="Product CholeCap - attachments.zip"

Details

On SUCCESS, Vault retrieves the latest version of all attachments from the object record. The attachments are packaged in a ZIP file with the file name: {object type label} {object record name} - attachments.zip.

The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. When downloading attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachment downloads (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Errors

Error Type	Error Message	Comments
`MALFORMED_URL`	The resource does not contain attachments.	You are trying to retrieve attachments from an object record which does not have any attachments.

History

Since v12

Create Object Record Attachment

Request

Send POST to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{object_name} - The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id} - The object record id field value.

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed file size is 4GB.

If an attachment is added which has the same filename as an existing attachment on a given object record, the new attachment is added as a new version of the existing attachment. If an attachment is added which is exactly the same (same MD5 checksum value) as an existing attachment on a given object record, the new attachment is not added.

The following attribute values are determined based on the file in the request: filename__v, format__v, size__v.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: multipart/form-data" \
-F "file=my_attachment_file.png" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments

Response

{
    "responseStatus": "SUCCESS",
    "data":
    {
        "id": "558",
        "version__v": 3
    }
}

Errors

Error Type	Error Message	Comments
`MALFORMED_URL`	The resource is not enabled for attachments.	You are trying to add an attachment to an object record for which attachments have not been enabled.
`OPERATION_NOT_ALLOWED`	Cannot add an attachment : number of allowed attachments exceeds max [50].	You are trying to add an attachment to an object record which already has the maximum number of allowed attachments (50).
`OPERATION_NOT_ALLOWED`	Cannot add an attachment : maximum attachment file size exceeds max [{n}].	You are trying to add an attachment to an object record which exceeds the maximum file size allowed for an attachment (2GB).

History

Since v12

Restore Object Record Attachment Version

Request

Send POST to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/versions/{attachment_version}?restore=true

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions/2?restore=true

Response

{
    "responseStatus": "SUCCESS",
    "data":
    {
        "id": "571",
        "version__v": 2
    }
}

Errors

Error Type	Error Message	Comments
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to restore an attachment {id} which does not exist on the specified object record.
`MALFORMED_URL`	The resource [{id}/versions/{version}] does not exist.	You are trying to restore a specific version {version} of an attachment {id} to make it the latest version, but the attachment or version do not exist.
`PARAMETER_REQUIRED`	Missing required parameter [restore].	You are trying to restore a specific version of an attachment but did not include the "restore" parameter.
`MALFORMED_URL`	The resource is not enabled for attachments.	You are trying to restore an attachment to an object record for which attachments have not been enabled.

History

Since v12

Update Object Record Attachment Description

Request

Send PUT to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Input

description__v - This is the only editable field. The maximum length is 1000 characters.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "description__v=This is my description for this attachment." \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571

Response

{
    "responseStatus": "SUCCESS"
}

Errors

Error Type	Error Message	Comments
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to update an attachment {id} which does not exist on the specified object record.
`MALFORMED_URL`	The resource is not enabled for attachments.	You are trying to add or restore an attachment to an object record for which attachments have not been enabled.
`INVALID_DATA`	Invalid value [{value}] specified for parameter [description__v] : string exceeds max length [1000].	You are trying to update the attachment description when the description exceeds the maximum character length (1000)

History

Since v12

Delete Object Record Attachment

Request

Send DELETE to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571

Response

{
    "responseStatus": "SUCCESS"
}

History

Since v12

Delete Object Record Attachment Version

Request

Send DELETE to /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/versions/{attachment_version}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions/1

Response

{
    "responseStatus": "SUCCESS"
}

Errors

Error Type	Error Message	Comments
`MALFORMED_URL`	The resource [{id}] does not exist.	You are trying to delete an attachment {id} which does not exist on the specified object record.
`MALFORMED_URL`	The resource [{id}/versions/{version}] does not exist.	You are trying to delete a specific version {version} of an attachment {id} which does not exist on the specified object record. The attachment {id} exists but the version number {version} does not.

History

Since v12

Object Types

Vault Objects can be can be partitioned into Object Types. For example, a Product object may have two different object types: "Pharmaceutic Product" and "Medical Device Product". These object types may share some fields but also have fields only used in each object type. By using object types, two product groups can not only manage data specific to their business but also easily report on products in both groups.

Retrieve Details from All Object Types
Retrieve Details from All Object Types on a Specific Object
Change Object Type

Retrieve Details from All Object Types

Request

Send GET to /api/{version}/configuration/Objecttype

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/configuration/Objecttype

Response

The response lists all object types and all fields configured on each object type. See the next response for details.

Retrieve Details from All Object Types on a Specific Object

Request

Send GET to /api/{version}/configuration/Objecttype.{object_name}.{object_type}

Headers

Response Accept - JSON application/json (default) or XML application/xml

URL Parameters

{object_name} - The name of the object.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/configuration/Objecttype.product__v

Response

The response lists all object types and all fields configured on each object type for the specific object. See the next response for details.

Change Object Type

Change the object types assigned to object records. Any field values which exist on both the original and new object type will carry over to the new type. All other field values will be removed, as only fields on the new type are valid. You can set field values on the new object type in the CSV input.

Request

Send POST to /api/{version}/vobjects/{object_name}/actions/changetype

Headers

Input Content-Type - JSON application/json or CSV text/csv Response Accept - JSON application/json (default) or CSV text/csv

URL Parameters

{object_name} - The name of the object.

Inputs

id - The ID of the object record. object_type__v - The id of the object type to which the object record is being changed. Note: If the object has a lifecycle, changing its type will reset its state to the initial state type.

Example CSV Input:

id	object_type__v
00P07710	OOT000000000602

Where "00P07710" is the object record ID and "OOT000000000602" is the object type ID.

Example JSON Input:

[
{
    "id": "00P07710",
    "object_type__v": "OOT000000000602"
}
]

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \ 
--data-binary @"C:\Vault\Objects\objecttypes.csv" \
https://myvault.veevavault.com/api/v15.0/metadata/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "00P07710",
                "url": "api/v15.0/vobjects/product__v/00P07710"
            }
        }
    ]    
}

Errors

Error Type	Error Message	Comments
`MALFORMED_URL`	The specified resource cannot be found.	The action or combination of the specified name, ID, and action are invalid.
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	The user has not been assigned permission to perform the action.
`PARAMETER_REQUIRED`	Missing required parameters [{parameter1, parameter2, parametern}].	One or more of the required fields are missing from the input.
`OPERATION_NOT_ALLOWED`	Cannot initiate action: [{action}] is already running.	The workflow is already running on the object record.
`INVALID_PARAMETER`	Invalid parameter [{parameter}]. The parameter is not valid for object type {object type}].	The user is attempting to set a field value that doesn't belong to the new object type.
`INVALID_DATA`	The object type [object_type__v] does not exist for [object.name].	The user is attempting to change the object type to a value that doesn't exist.
`INVALID_DATA`	Invalid value [{value}] specified for parameter [{param}] : {one of the following reasons}.	The value specified fails validation per metadata definition. This occurs due to one of the following: String exceeds max length [{max}], Number greater than max [{max}], Number less than min [{min}], Numeric value is expected, Picklist [picklist_name_v] does not contain [picklist_entry_v], Boolean value is expected, String value is expected, Date value is expected, DateTime value is expected, Valid users/groups are expected.

RIM Submissions

This API allows you to import eCTD or non-eCTD submission packages into your RIM SubmissionsArchive vault.

To use this API, you must have Vault's RIM Submissions suite of applications.

Learn more about RIM Submissions in Vault Help:

The RIM SubmissionArchive Import API allows you to import completed submissions into a RIM SubmissionsArchive vault.

This can be used by Vault Submissions Application developers to integrate submissions import into your SubmissionsArchive vault.
This can be used by services and developers to enable integration between your SubmissionsArchive vault and external systems.
This can be used by services and developers to develop migration tools which facilitate migration of completed submissions into your SubmissionsArchive vault.

Import Submission

Import a submission into your vault.

Before submitting this request:

You must be assigned permissions to use the API and have permissions to view and edit the specified submission__v object record.
You must create the corresponding object records for the Submission and Application objects in your vault.
You must create and upload a valid submission import file or folder to your FTP staging server. The submission to be imported must be located in a folder called "SubmissionsArchive" at the root of your FTP server. In the request, add the file column to your input and enter the path/name of each file relative to the FTP root.

Request

Send POST to /api/{version}/vobjects/submission__v/{submission_id}/actions/import

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{submission_id} - The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Input

file - Use the file parameter to specify the location of the submission folder and files or ZIP file previously uploaded to your FTP staging server.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "file=/SubmissionsArchive/submission_2015" \
https://myvault.veevavault.com/api/v15.0/objects/vobjects/submission__v/00S000000000101/actions/import

Details

The Content-Type header is set to accept a name-value pair input.
The file parameter specifies the location/name of the folder or ZIP file to be imported. The file must be located in the "SubmissionsArchive" folder on your FTP staging server.

Response

{
  "responseStatus": "SUCCESS",
  "warnings": [
    {
      "type": "APPLICATION_MISMATCH",
      "message": "Application folder name does not match the Application record name."
    },
    {
      "type": "SUBMISSION_MISMATCH",
      "message": "Submission folder name does not match the Submission record name."
    }
  ],
  "job_id": 1301,
  "url": "/api/v15.0/services/jobs/1301"
}

Details

On SUCCESS, the response includes the following information:

job_id - The Job ID value is used to retrieve the status and results of the binder export request.
url - The URL to retrieve the current status of the import request.

You may also receive one or more warnings. The warnings shown above indicate that the folders being imported do not match the object records in our vault. We can either change the names in either location or simply ignore the warnings.

Additional notes:

Before submitting this request, we created a submission__v object record and application__v object record in our vault. We also created submissions ZIP file containing a "Submission" folder and "Application" folder. This was loaded to our FTP staging server awaiting import. Ideally, we would have named and structured the folders to match that of the submission that was sent to the health authority and which we are now archiving. However, this is not critical to the import process.

Errors

Vault will not start the import job until all errors have been corrected and resubmitted.

Error Type	Error Message	Comments
`METHOD_NOT_SUPPORTED`	Requested method {METHOD} not supported.	Use the HTTP `POST` method for this request.
`INVALID_DATA`	Invalid input parameter value for {PARAMETER}.	You have provided a parameter which is invalid. The error message includes the name of the invalid parameter.
`MALFORMED_URL`	Object not found.	The object record `id` value does not refer to a valid `submission__v` object record in your vault.
`INSUFFICIENT_ACCESS`	User does not have permission to view or edit the {OBJECT} object.	The logged-in API user must have permissions on the `submissions__v` object.
`INSUFFICIENT_ACCESS`	User does not have access to the specified submission object record.	The logged-in API user must have permission on the `submissions__v` object record.
`INSUFFICIENT_ACCESS`	User does not have RIM Submission Archive Import permission.	The logged-in API user must have permission on the RIM Submission Archive.
`OPERATION_NOT_ALLOWED`	Submission archive already exists.	A submission archive for the specified submission already exists and must be removed before proceeding.
`INVALID_LOCATION`	Location specified does not reference a valid import.	The path specified in the Location parameter does not refer to a valid folder or ZIP file.
`INVALID_IMPORT_FORMAT`	Import contains zero files.	The import package does not contain at least one non-hidden file.
`INVALID_IMPORT_FORMAT`	Import contains invalid XML.
`INVALID_IMPORT_FORMAT`	Import contains unsupported region or DTD.	Import specified region or DTD is not currently supported.
`INVALID_IMPORT_FORMAT`	Import missing regional XML.

History

Since v14

Retrieve Submission Import Results

After Vault has finished processing the submission import job, use this request to retrieve the results of the completed submission binder.

Before submitting this request:

You must be assigned permissions to use the API and permissions to view the specified submission__v object record.
There must be a previously submitted and completed submission import request, i.e., the status of the import job must be no longer active.

Request

Send GET to /api/{version}/vobjects/submission__v/{submission_id}/actions/import/{job_id}/results

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{submission_id} - The id field value of the submission__v object record. See Retrieve Object Record Collection above. {job_id} - The jobId field value returned from the Import Submission request above.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/import/1301/results

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "responseStatus": "SUCCESS",
      "id": 16,
      "major_version_number__v": "1",
      "minor_version_number__v": "0"
    }
  ]
}

Details

On SUCCESS, the response includes the following information:

Field Name	Description
`id`	The `id` field value of the submission binder which was created by the imported files.
`major_version_number__v`	The major version number of the binder.
`minor_version_number__v`	The minor version number of the binder.

To retrieve the metadata from the newly created submission binder, send GET to /api/{version}/objects/binders/{id}.

Errors

Error Type	Error Message	Comments
`METHOD_NOT_SUPPORTED`	Requested method {METHOD} not supported.	Use the HTTP `GET` method for this request.
`MALFORMED_URL`	The specified resource cannot be found.	You have provided a `submission_id` or `job_id` value that is not valid.
`OPERATION_NOT_ALLOWED`	The specified resource is not complete.	Vault has not finished importing the submission. This may take a while. Use the previous request to retrieve its status.

History

Since v14

Retrieve Submission Metadata Mapping

Retrieve the metadata mapping values of an eCTD submission package.

Request

Send GET to /api/{version}/vobjects/submission__v/{submission_id}/actions/ectdmapping

Headers

Response Accept - JSON application/json (default) or CSV text/csv

Parameters

{submission_id} - The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/ectdmapping

Response

{
 "responseStatus": "SUCCESS",
    "responseDetails": {
    "total": 2,
    },
    "data": [
    {
      "name__v": "1675_00S000000000802",
      "external_id__v": null,
      "drug_substance__v":"Ethyl Alcohol",
      "drug_substance__v.name__v": "",
      "xml_id": "m2-3-s-drug-substance",
      "manufacturer__v":"Veeva",
      "manufacturer__v.name__v": ""
    },
    {
      "name__v": "1681_00S000000000802",
      "external_id__v": null,
      "nonclinical_study__v":"Study001",
      "nonclinical_study__v.name__v": "",
      "xml_id": "S001"
    }
  ]
}

Details

On SUCCESS, the response includes the following information for each XML metadata node which requires mapping:

Field Name	Description
`name__v`	The name of the metadata mapping record in the submission metadata.
`external_id__v`	The external ID of the metadata mapping record. This value is only available if the mappings were created or updated externally.
`xml_id`	The XML ID (`leaf_id`) of the section being mapped. This is an identifier from the imported XML of the XML node. This is analogous to the `submission_metadata__v.tag_id__v`.

Mapping Fields:

Possible mappings include: clinical_site__v, clinical_study__v, drug_product__v, drug_substance__v, indication__v, manufacturer__v, and nonclinical_study__v.

Mapping fields are returned as a pair of properties: a source property that has the mapping identifier from the imported XML and a second property as [mapping].name__v which specifies the target object record. If the second property is empty, the mapping has not been completed. See Update Submission Metadata Mapping below.

Errors

Error Type	Error Message	Comments
`METHOD_NOT_SUPPORTED`	Requested method {METHOD} not supported.	Use the HTTP `GET` method for this request.
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	You are not assigned permission on the `submissions__v` object and object record.
`MALFORMED_URL`	The specified resource cannot be found.	The `submission_id` value cannot be found in your vault.

History

Since v14

Update Submission Metadata Mapping

Update the mapping values of a submission.

Request

Send PUT to /api/{version}/vobjects/submission__v/{submission_id}/actions/ectdmapping

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or CSV text/csv

Parameters

{submission_id} - The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Input

Note that XML identifiers are read-only and cannot be updated via the API. If including XML identifiers in the request, the values will be ignored.

[
    {
      "external_id__v": null,
      "drug_substance__v.name__v": "ethyl alcohol",
      "name__v": "1675_00S000000000802",
      "xml_id": "m2-3-s-drug-substance",
      "manufacturer__v.name__v": "Veeva Chemical"
    },
    {
      "external_id__v": null,
      "drug_substance__v.name__v": "ethyl alcohol",
      "name__v": "1677_00S000000000802",
      "xml_id": "m3-2-s-drug-substance",
      "manufacturer__v.name__v": "Veeva Chemical"
    },
    {
      "external_id__v": null,
      "nonclinical_study__v.name__v": "S001",
      "name__v": "1681_00S000000000802",
      "xml_id": "S001"
    },
    {
      "external_id__v": null,
      "clinical_study__v.name__v": "S001",
      "name__v": "1693_00S000000000802",
      "xml_id": "S001"
    }
]

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/ectdmapping

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "name__v": "1675_00S000000000802",
            "responseStatus": "SUCCESS"
        },
        {
            "name__v": "1677_00S000000000802",
            "responseStatus": "SUCCESS"
        },
        {
            "name__v": "1681_00S000000000802",
            "responseStatus": "SUCCESS"
        },
        {
            "name__v": "1693_00S000000000802",
            "responseStatus": "SUCCESS"
        }
    ],
    "responseDetails": {
        "total": 4
    }
}

History

Since v14

Remove Submission

Delete a previously imported submission from your vault.

By removing a submission, you delete any sections created in the archive binder as part of the submission import. This will also remove any documents in the submission from the archive binder. This does not delete the documents from Vault, but does mean that they no longer appear in the Viewer tab and users will not be able to access them using cross-document navigation. You must re-import the submission to make it available.

Request

Send DELETE to /api/{version}/vobjects/submission__v/{submission_id}/actions/import

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{submission_id} - The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/import

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 15002,
  "url": "/api/v15.0/services/jobs/15002"
}

History

Since v14

Cancel Submission

You can use this request on a submission object record that has a SubmissionsArchive status (archive_status__v) of:

IMPORT_IN_PROGRESS - This will terminate the import job and set the archive_status__v field on the submission__v object record to "Error". The submission must be removed before a re-import can be done. See Remove Submission above.
REMOVAL_IN_PROGRESS - This will terminate the import removal job and set the archive_status__v field on the submission__v object record to "Error". The submission must be removed before a re-import can be done. See Remove Submission above.
IMPORT_IN_QUEUE - This will remove the import from the job queue and set the archive_status__v field on the submission__v object record to "Null". See Import Submission above.
REMOVAL_IN_QUEUE - This will remove the import removal from the job queue and set the archive_status__v field on the submission__v object record to "Error". See Import Submission above.

To retrieve the archive_status__v, send GET to /api/{version}/vobjects/submission__v/{submission_id}. See Retrieve Object Record above.

Request

Send POST to /api/{version}/vobjects/submission__v/{submission_id}/actions/import?cancel=true

Headers

Response Accept - JSON application/json (default) or XML application/xml

URL Parameters

{submission_id} - The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Query Parameters

cancel - You must include cancel=true to the request endpoint.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/import?cancel=true

Response

{
  "responseStatus": "SUCCESS"
}

Errors

Error Type	Error Message	Description
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	You are not assigned permission on the `submissions__v` object and object record.
`MALFORMED_URL`	The specified resource cannot be found.	The `submission_id` value cannot be found in your vault.
`INVALID_DATA`	Invalid input parameter value for [source].	The query parameter must be set to `cancel=true`.
`OPERATION_NOT_ALLOWED`	Cancel not supported, archive status is [archive_status__v].	This action is only allowed when the submission record `archive_status__v` is set to one of the four values listed above.
`UNEXPECTED_ERROR`	Job cannot be cancelled.	An unexpected error has occurred. Try submitting the request again. Contact Veeva Support if the problem continues.

History

Since v15

Export Submission

Request

To export the latest version of a SubmissionsArchive binder:

Send POST to /api/{version}/objects/binders/{binder_id}/actions/export?submission={submission_id}

To export a specific version of a SubmissionsArchive binder:

Send POST to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/actions/export?submission={submission_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{binder_id} - The binder id field value. See Retrieve Binders above.
{major_version_number__v} - The major_version_number__v field value of the binder.
{minor_version_number__v} - The minor_version_number__v field value of the binder.
{submission_id} - The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/454/actions/export?submission=00S000000000101

Response

{
  "responseStatus": "SUCCESS",
  "URL": "https://myvault.veevavault.com/api/v15.0/services/jobs/1201",
  "job_id": 1201
}

Details

On SUCCESS, the response includes the following information:

URL - The URL to retrieve the current status of the export job.
job_id - The Job ID value is used to retrieve the status and results of the request.

Errors

Vault will not start the export job until all errors have been corrected and resubmitted.

Error Type	Error Message	Comments
`METHOD_NOT_SUPPORTED`	Requested method {METHOD} not supported.	You must use the HTTP `POST` method for this request.
`INVALID_DATA`	Invalid input parameter value for {PARAMETER}.	You have provided a parameter which is invalid. The error message includes the name of the invalid parameter. For example: the submission parameter is passed for a non-SubmissionsArchive binder; the submission parameter is used with API v15.0 or later; other parameters are passed in addition to the submission parameter for a SubmissionsArchive binder; the `submission_id` value is not part of the SubmissionsArchive binder being exported.
`INVALID_BINDER`	Binder not found.	The specified binder `id` value was not found in your vault.
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	The logged-in API user must have API Access permission.
`INSUFFICIENT_ACCESS`	User {USER ID} not licensed for this permission [VAULT ACTIONS API ACCESS].	The logged-in API user must have API permission and proper permissions to perform an export on the requested binder.
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	The logged-in API user must have API permission and proper permissions to perform an export on the requested binder.
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	The logged-in API user must have View Access on the Submission record.
`INSUFFICIENT_ACCESS`	User {USER ID} not authorized for this permission {SubmissionsArchive Export}.	The logged-in API user must have Export permission for SubmissionsArchive application.
`INSUFFICIENT_ACCESS`	User {USER ID} not authorized for this permission Viewer Tab.	Returned if the user does not have Viewer permission for Viewer tab.
`PARAMETER_REQUIRED`	Missing required parameter {PARAMETER}.	Returned if the submission parameter is not passed for a SubmissionsArchive binder.

History

Since v15

Export Partial Submission

Use this request to export only specific sections and documents from the latest version of a submissions binder in your vault. This will export only parts of the binder, not the complete binder.

Before submitting this request:

The Export Binder feature must be enabled in your vault.
You must be assigned permissions to use the API.
You must have the Export Binder permission.
You must have the View Document permission for the binder. Only documents in the binder which you have the View Document permission are available to export.

Request

To export the latest version of a submissions binder:

Send POST to /api/{version}/objects/binders/{binder_id}/actions/export?submission={submission_id}

To export a specific version of a submissions binder:

Send POST to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/actions/export?submission={submission_id}

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Input

Create a CSV or JSON input file with the id values of the binder sections and/or documents to be exported. You may include any number of valid nodes. Vault will ignore id values which are invalid, but will export all which are valid.

For example, the abridged response below includes two nodes from a binder. Node "id": "1415381339215" is a section (folder) and "id": "1415381339220" is a document node.

Exporting a binder section node will automatically include all of its subsections and documents therein.

  "nodes": [
    {
      "properties": {
        "section_number__v": "02.01.01",
        "name__v": "Investigator Brochure",
        "order__v": 0,
        "type__v": "section",
        "id": "1415381339215",
        "parent_id__v": "1415381339209"
      },
      "nodes": [
        {
          "properties": {
            "document_id__v": 18,
            "name__v": "CHC032-194 Investigator Brochure",
            "order__v": 0,
            "type__v": "document",
            "id": "1415381339220",
            "parent_id__v": "1415381339215"
          }
        },

To export just this one section and document from the binder, we would submit the following input file:

id
1415381339215
1415381339220

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Binders\export-submissions-binder-sections.csv" \
https://myvault.veevavault.com/api/v15.0/objects/binders/454/1/0/actions/export?submission=00S000000000101

In this example:

The input file format is set to CSV.
The response format is not set and will default to JSON.
The path\name of the CSV input file is specified.

Response

{
  "responseStatus": "SUCCESS",
  "URL": "https://myvault.veevavault.com/api/v15.0/services/jobs/1201",
  "job_id": 1201
}

Details

On SUCCESS, the response includes the following information:

URL - The URL to retrieve the current status of the export job.
job_id - The job_id field value is used to retrieve the status and results of the export request.

Errors

Vault will not start the export job until all errors have been corrected and resubmitted.

Error Type	Error Message	Comments
`METHOD_NOT_SUPPORTED`	Requested method {METHOD} not supported.	You must use the HTTP `POST` method for this request.
`INVALID_DATA`	Invalid input parameter value for {PARAMETER}.	You have provided a parameter which is invalid. The error message includes the name of the invalid parameter. For example: the submission parameter is passed for a non-SubmissionsArchive binder; the submission parameter is used with API v15.0 or later; other parameters are passed in addition to the submission parameter for a SubmissionsArchive binder; the `submission_id` value is not part of the SubmissionsArchive binder being exported.
`INVALID_BINDER`	Binder not found.	The specified binder `id` value was not found in your vault.
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	The logged-in API user must have API Access permission.
`INSUFFICIENT_ACCESS`	User {USER ID} not licensed for this permission [VAULT ACTIONS API ACCESS].	The logged-in API user must have API permission and proper permissions to perform an export on the requested binder.
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	The logged-in API user must have API permission and proper permissions to perform an export on the requested binder.
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	The logged-in API user must have View Access on the Submission record.
`INSUFFICIENT_ACCESS`	User {USER ID} not authorized for this permission {SubmissionsArchive Export}.	The logged-in API user must have Export permission for SubmissionsArchive application.
`INSUFFICIENT_ACCESS`	User {USER ID} not authorized for this permission Viewer Tab.	Returned if the user does not have Viewer permission for Viewer tab.
`PARAMETER_REQUIRED`	Missing required parameter {PARAMETER}.	Returned if the submission parameter is not passed for a SubmissionsArchive binder.

History

Since v15

Retrieve SubmissionsArchive Binder

Before submitting this request:

You must be assigned permissions to use the API.
You must have the View Document permission for the binder. Only documents in the binder which you have the View Document permission will be returned.

Request

To retrieve submission structure from the latest version of the SubmissionsArchive binder:

Send GET to /api/{version}/vobjects/submission__v/{submission_id}/actions/viewer

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{submission_id} - The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/viewer

Response (abridged)

{
    "responseStatus": "SUCCESS",
    "document": {
        "id": 454,
        "binder__v": true,
        ...
        "major_version_number__v": 1,
        "minor_version_number__v": 0,       
        "status__v": "Final",
        "Applications__v": [
            "00A000000000101"
        ],   
        "name__v": "nda123456",
        "lifecycle__v": "SubmissionsArchive Lifecycle",        
        "type__v": "SubmissionsArchive",
        "subtype__v": "Structure",
        ...
    },
    "versions": [
        {
            "number": "1.0",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/binders/454/versions/1/0"
        }
    ],
    "binder": {
        "nodes": [
        {
        "properties": {
          "section_number__v": "1",
          "name__v": "m1-administrative-information-and-prescribing-information",
          "order__v": 1,
          "type__v": "section",
          "id": "1458077095468:-826390827",
          "parent_id__v": "rootNode",
          "sa_title": "Module 1 Administrative Information"
        },
        {
        "properties": {
          "name__v": "m1-1-forms",
          "order__v": 1,
          "type__v": "section",
          "id": "1458077095654:-1282798513",
          "parent_id__v": "1458077095468:-826390827",
          "sa_title": "1.1 Forms"
        },
        {
        "properties": {
          "name__v": "m1-1-2-form-356h",
          "order__v": 1,
          "type__v": "section",
          "id": "1458077095823:-61354986",
          "parent_id__v": "1458077095654:-1282798513",
          "sa_title": "1.12 Application form: FDA form 356h"
        },
        {
        "properties": {
          "document_id__v": 2318,
          "name__v": "1-1-2-form-356h",
          "order__v": 1,
          "type__v": "document",
          "id": "1458077095823:-61354986",
          "parent_id__v": "1458077095823:-61354986",
          "sa_title": "FDA Form 356h",
          "sa_id": "veeva10923",
          "sa_operation": "New",
          "sa_xlinkhref": "1-1-2-form-356h.pdf",
          "sa_xlinktype": "simple",
          "sa_checksum_type": "md5",
          "sa_checksum": "96b3eb46bfa348c0c798943e78381ca6",
          "sa_application_version": "PDF 1.4"
        },
        {
        "properties": {
          "name__v": "m3-quality",
          "order__v": 2,
          "type__v": "section",
          "id": "1458079746774:-718199953",
          "parent_id__v": "rootNode",
          "sa_title": "Module 3 Quality"
        },
        {
        "properties": {
          "name__v": "m3-2-body-of-data",
          "order__v": 1,
          "type__v": "section",
          "id": "1458079747018:182443898",
          "parent_id__v": "1458079746774:-718199953",
          "sa_title": "3.2 Body of Data"
        },
        {
        "properties": {
          "name__v": "m3-2-s-drug-substance",
          "order__v": 1,
          "type__v": "section",
          "id": "1458079747401:1533319790",
          "parent_id__v": "1458079747018:182443898",
          "sa_title": "3.2.S Drug substance",
          "drug_substance_xml": "Cholecapacin",
          "drug_substance__v": "0DS000000000101",
          "manufacturer_xml": "Veeva Labs",
          "manufacturer__v": "00M000000000101"
        },
        {
        "properties": {
          "name__v": "m3-2-s-4-control-of-drug-substance",
          "order__v": 1,
          "type__v": "section",
          "id": "1458079747664:-30973505",
          "parent_id__v": "1458079747401:1533319790",
          "sa_title": "3.2.S.4 Control of drug substance",
          "drug_substance_xml": "Cholecapacin",
          "drug_substance__v": "0DS000000000101",
          "manufacturer_xml": "Veeva Labs",
          "manufacturer__v": "00M000000000101"
        },
        {
        "properties": {
          "name__v": "m3-2-s-4-2-analytical-procedures",
          "order__v": 1,
          "type__v": "section",
          "id": "1458079747892:2036125551",
          "parent_id__v": "1458079747664:-30973505",
          "sa_title": "3.2.S.4.2 Analytical Procedures",
          "drug_substance_xml": "Cholecapacin",
          "drug_substance__v": "0DS000000000101",
          "manufacturer_xml": "Veeva Labs",
          "manufacturer__v": "00M000000000101"
        },
        {
        "properties": {
          "document_id__v": 1016,
          "name__v": "32s42-m062sf220-analytical-method",
          "order__v": 1,
          "type__v": "document",
          "id": "1458077095823:1029339123",
          "parent_id__v": "1458079747664:-30973505",
          "sa_title": "Analytical Method M-062-SF220",
          "sa_id": "veeva1543",
          "sa_operation": "New",
          "sa_xlinkhref": "m3/32-body-data/32s-drug-sub/cholecapacin-veeva-labs/32s4-contr-drug-sub/32s42-analyt-proc/32s42-m062sf220-analytical-method.pdf",
          "sa_xlinktype": "simple",
          "sa_checksum_type": "md5",
          "sa_checksum": "0022dea54ca0dfb309f49ff22dcf1c46",
          "sa_application_version": "PDF 1.4",
          "drug_substance_xml": "Cholecapacin",
          "drug_substance__v": "0DS000000000101",
          "manufacturer_xml": "Veeva Labs",
          "manufacturer__v": "00M000000000101"
        }
    }
}

Retrieve Submission Export Results

After submitting a request to export a submission from your vault, you can query vault to determine the results of the request.

Before submitting this request:

You must have previously requested a submission export job (via the API) which is no longer active.
You must have a valid job_id field value returned from the Export Submission request above.

Request

Send GET to /api/{version}/objects/binders/actions/export/{job_id}/results

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{job_id} - The jobId field value returned from the Export Submission request above.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/binders/actions/export/1201/results

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 1201,
  "id": 454,
  "major_version_number__v": 1,
  "minor_version_number__v": 0,
  "file": "/1201/454/1_0/RIM Submission Packet.zip",
  "user_id__v": 44533
}

Details

On SUCCESS, the response includes the following information:

Field Name	Description
`job_id`	The `job_id` field value of the submission export request.
`id`	The `id` field value of the exported submission.
`major_version_number__v`	The major version number of the exported submission.
`minor_version_number__v`	The minor version number of the exported submission.
`file`	The path/location of the exported submission. This is packaged in a ZIP file on your FTP staging server.
`user_id__v`	The `id` field value of the Vault user who initiated the submission export job.

History

Since v15

Download Exported Submission Files via FTP

Once your submission export job has been successfully completed, you can download the files from your FTP staging server.

Prerequisites

Before downloading the files, the following conditions must be met:

The submission export job must have been successfully completed.
The API user must have a permission set which allows them FTP download permissions.

Downloading the Files

The exported submission is packaged in a ZIP file on your FTP staging server.

Roles

Documents and binders 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, Admins can create 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 Roles 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 Roles

Retrieve all available roles on a document or binder and the users and groups assigned to them.

Request

Documents: Send GET to /api/{version}/objects/documents/{document_id}/roles
Binders: Send GET to /api/{version}/objects/binders/{binder_id}/roles

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{binder_id} - The binder id field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/documents/245/roles

Response (abridged)

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document roles retrieved",
    "errorCodes": null,
    "documentRoles": [
        {
            "name": "reviewer__v",
            "label": "Reviewer",
            "assignedUsers": [
                25496,
                26231
            ],
            "assignedGroups": [
                1,
                2
            ],
            "availableUsers": [
                25496,
                26231,
                28874
            ],
            "availableGroups": [
                1,
                2,
                3
            ],
            "defaultUsers": [
                25496,
                26231
            ],
            "defaultGroups": [
                1,
                2
            ]
        },
        {
            "name": "viewer__v",
            "label": "Viewer",
            ...
        },
        {
            "name": "consumer__v",
            "label": "Consumer",
            ...
        },
        {
            "name": "approver__v",
            "label": "Approver",
            ...
        },
        {
            "name": "owner__v",
            "label": "Owner",
            ...
        },
        {
            "name": "editor__v",
            "label": "Editor",
            ...
        },
        {
            "name": "coordinator__v",
            "label": "Coordinator",
            ...
        }
    ],
    "errorType": null
}

Details

In the abridged response above, document ID 245 is configured with several roles. Two users (25496 & 26231) and two groups (1 & 2) are assigned to the reviewer__v role by default.

History

Since v5

Retrieve Users & Groups Assigned to Role

Retrieve all users and groups assigned to a specific role on a document or binder.

Request

Documents: Send GET to /api/{version}/objects/documents/{document_id}/roles/{role_name}
Binders: Send GET to /api/{version}/objects/binders/{binder_id}/roles/{role_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{document_id} - The document id field value.
{binder_id} - The binder id field value.
{role_name} - The role name__v field value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/documents/245/roles/reviewer__v

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document role retrieved",
    "errorCodes": null,
    "documentRoles": [
        {
            "name": "reviewer__v",
            "label": "Reviewer",
            "assignedUsers": [
                25496,
                26231
            ],
            "assignedGroups": [
                1,
                2
            ],
            "availableUsers": [
                25496,
                26231,
                28874
            ],
            "availableGroups": [
                1,
                2,
                3
            ],
            "defaultUsers": [
                25496,
                26231
            ],
            "defaultGroups": [
                1,
                2
            ]
        }
    ],
    "errorType": null
}

History

Since v5

Assign Users & Groups to Roles on a Single Document

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "consumer__v.users=35565,35571" \
-d "approver__v.users-45585,45594" \
https://myvault.veevavault.com/api/v15.0/objects/documents/245/roles

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Document roles updated",
  "updatedRoles": {
    "consumer__v": {
      "users": [
        19376,18234,19456
      ]
    },
    "legal__c": {
      "groups": [
        19365,18923
      ]
    }
  }
}

Assign users and groups to roles on a single document or binder.

POST /api/{version}/objects/documents/{id}/roles

Headers

Name	Description
`Content-Type`	`application/x-www-form-urlencoded`
`Accept`	`application/json` (default) or `application/xml`

URI Path Parameters

Name	Description
`{id}`	The document or binder `id` field value.

Body Parameters

Include name-value pairs of all users or groups with their corresponding roles in the form {Role_name}.{USERS or GROUPS}=ID1,ID2,ID3. For example, reviewer__v.users = "3003, 4005".

Response Details

The response includes ROLE:ID pairs for the users and groups successfully assigned to roles on the document or binder.

Assign Users & Groups to Roles on Multiple Documents

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Document Roles\assign_document_roles.csv" \
https://myvault.veevavault.com/api/v9.0/objects/documents/roles/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.groups": [
                3311303,
                4411606
            ],
            "reviewer__v.users": [
                12021,
                12022,
                12023,
                12124
            ]           
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.groups": [
                3311303,
                4411606
            ],
            "reviewer__v.users": [
                12021,
                12022,
                12023,
                12124
            ]           
        },        
        {
           "responseStatus":"FAILURE",
           "id":"773",
           "errors":[
              {
                 "type":"INVALID_DATA",
                 "message":"Error message describing why the users and groups were not assigned to roles on this document.."
              }
           ]
        }
    ]
}

Assign users and groups to roles on a document or binder in bulk.

The maximum CSV input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 1000.

POST /api/{version}/objects/documents/roles/batch

Assigning users and groups to document roles is additive. For example, if groups 1, 2, and 3 are currently assigned to a particular role and you assign groups 3, 4, and 5 to the same role, the final list of groups assigned to the role will be 1, 2, 3, 4, and 5. Users and groups (IDs) in the input that are either invalid (not recognized) or cannot be assigned to a role due to permissions are ignored and not processed.

Headers

Name	Description
`Content-Type`	`text/csv` or `application/x-www-form-urlencoded`
`Accept`	`application/json` (default) or `application/xml`

Body Parameters

You can add parameters in the request body, or upload them as a CSV file.

Name	Description
`id`	The document ID.
`role__v.users`	A string of user `id` values for the new role.
`role__v.groups`	A string of user `id` values for the new group.

For example,

`id`	`reviewer__v.users`	`reviewer__v.groups`	`approver__v.users`	`approver__v.groups`
771	"12021,12022"	"3311303,3311404"	22124	4411606

Response Details

The response includes role:id pairs for the users and groups successfully assigned to roles.

Remove Users & Groups from Roles on a Single Document

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/documents/1234/roles/consumer__v.user/19376

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "User/group deleted from document role",
  "updatedRoles": {
    "consumer__v": {
      "users": [
        19376
      ]
    }
  }
}

Remove users and groups from roles on a single document or binder.

DELETE /api/{version}/objects/documents/{doc_id}/roles/{role_name}.{user_or_group}/{id}

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`

URI Path Parameters

Name	Description
`{doc_id}`	The `id` value of the document or binder from which to remove roles.
`{role_name}`	The name of the role to remove the users or groups from.
`{user_or_group}`	Choose to remove a user or a group from a role. Possible values for this parameter are either `user` or `group`.
`{id}`	The `id` value of the user or group to remove from the role.

Remove Users and Groups from Roles on Multiple Documents

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Document Roles\remove_document_roles.csv" \
https://myvault.veevavault.com/api/v9.0/objects/documents/roles/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.groups": [
                4411606
            ],
            "reviewer__v.users": [
                12124
            ]           
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.groups": [
                4411606
            ],
            "reviewer__v.users": [
                12124
            ]           
        },        
        {
           "responseStatus":"FAILURE",
           "id":"773",
           "errors":[
              {
                 "type":"INVALID_DATA",
                 "message":"Error message describing why the users and groups were not removed from roles on this document."
              }
           ]
        }
    ]
}

Remove users and groups to roles on a document or binder in bulk.

The maximum CSV input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 1000.

DELETE /api/{version}/objects/documents/roles/batch

Headers

Name	Description
`Content-Type`	`text/csv` or `application/x-www-form-urlencoded`
`Accept`	`application/json` (default) or `application/xml`

Body Parameters

You can add parameters in the request body, or upload them as a CSV file.

Name	Description
`id`	The document ID.
`role__v.users`	A string of user `id` values to delete.
`role__v.groups`	A string of user `id` values to delete.

For example,

`id`	`reviewer__v.users`	`reviewer__v.groups`	`approver__v.users`	`approver__v.groups`
771	"12021,12022"	"3311303,3311404"	22124	4411606

Users

Learn about Creating & Managing Users and Managing Users Across Vaults in Vault Help.
See also Bulk Users API.

Vault User Metadata

The Vault users object includes a fixed set of metadata. You cannot add or remove fields, nor can you change the field names or labels.

Required Fields: With the exception of id, the fields listed below are required when adding new users.

Field Name	Field Label	Field Type	Description	Required	Editable	Queryable
`id`	ID	id	Unique user identifier (permanent). Numeric value.	System-Managed	False	True
`user_name__v`	User Name	String	Unique user identifier. This is the user's vault login credential.	True	True	True
`user_email__v`	Email	String	The user's email address. Vault notifications are sent to this address.	True	True	True
`user_first_name__v`	First Name	String	The user's first name.	True	True	True
`user_last_name__v`	Last Name	String	The user's last name.	True	True	True
`user_language__v`	Language	String	The user's preferred language. Available values displayed in metadata response.	True	True	True
`user_timezone__v`	Timezone	String	The user's time zone. Available values displayed in metadata response.	True	True	True
`user_locale__v`	Locale	String	The user's location. Available values displayed in metadata response.	True	True	True
`security_policy_id__v`	Security Policy	ObjectReference	The user's security policy. Learn how to retrieve values.	True	True	True
`vault_id__v`	Vault ID	ObjectReference	The ID of the vault to which the user is assigned. Learn how to retrieve values.	True ** `vault_membership`	False	True
`security_profile__v`	Security Profile *	ObjectReference	The user's security profile. Available values displayed in metadata response.	True ** `vault_membership`	True	True
`license_type__v`	License Type *	Picklist	The user's license type. Learn how to retrieve values.	True ** `vault_membership`	True	True
`active__v`	Active	Boolean	Whether or not the user is active in the current Vault application.	True ** `vault_membership`	True	True

* The security_profile__v and license_type__v fields are available in API v10.0 or later.
** The vault_membership fields are not required to add users to the domain. They are required to assign users to vaults. See Create User and Update Vault Membership below.

Optional Fields: The fields listed below are optional, editable user fields or system-managed fields.

Field Name	Field Label	Field Type	Description	Required	Editable	Queryable
`company__v`	Company	String	The user's company.	False	True	True
`user_title__v`	Title	String	The user's title.	False	True	True
`alias__v`	Alias	String	Nickname. Used to differentiate users with the same first and last name.	False	True	False
`site__v`	Site	String	The user's location, such as a city. In user profiles (UI), this is labeled "Location".	False	True	True
`office_phone__v`	Office Phone Number	String	The user's office phone number.	False	True	True
`mobile_phone__v`	Mobile Phone Number	String	The user's mobile phone number.	False	True	True
`fax__v`	Fax Phone Number	String	The user's fax number.	False	True	True
`user_needs_to_change_password__v`	Change Password	Boolean	The user is required to change their password on next login.	False	True	True
`domain_active__v`	Domain Active	Boolean	Whether or not the user is active in the domain.	False	True	True
`is_domain_admin__v`	Is Domain Admin	Boolean	The user is a Domain Administrator.	False	True	True
`domain_id__v`	Domain ID	ObjectReference	The ID of the domain to which the user is assigned.	System-Managed	False	True
`federated_id__v`	Federated ID	String	The user's federated ID if using SAML Single Sign-on Authentication.	False	True	True
`salesforce_user_name__v`	Salesforce Username	String	The user's Salesforce.com username if using Salesforce Delegated Authentication.	False	True	True
`medidata_uuid__v`	Medidata UUID	String	The user's Medidata email if using Medidata Delegated Authentication.	False	True	True
`group_id__v`	Group ID	ObjectReference	The IDs of the groups to which the user is assigned.	False	False	False
`created_date__v`	Created Date	Calendar	The date and time when the user account was created.	System-Managed	False	True
`created_by__v`	Created By	ObjectReference	The user ID of the person who created the user account.	System-Managed	False	True
`modified_date__v`	Modified Date	Calendar	The date and time when the user account was last modified.	System-Managed	False	True
`modified_by__v`	Modified By	ObjectReference	The user ID of the person who last modified the user account.	System-Managed	False	True
`last_login__v`	Last Login	Calendar	The date the user last logged into the vault.	System-Managed	False	True

Metadata Fields (Properties): The information listed below may be included with each field.

Metadata Field	Description
`name`	Field name.
`type`	Field type.
`object`	When the field type is "ObjectReference", this shows the name of the object being referenced.
`multivalue`	Whether or not the field can have multiple values.
`queryable`	Whether or not the field can be used in API queries.
`length`	When the field type is "String", this shows the maximum character length allowed.
`required`	Whether or not the field is required when creating a new user.
`onCreateEditable`	Whether or not the field can be set when creating a new user.
`editable`	Whether or not the field is editable.
`values`	Lists allowed values for the `user_locale__v`, `user_language__v`, `user_timezone__v`, and `security_profile__v` fields.

Domain-Level User Management

Vault user accounts exist at the domain level, so in multi-vault domains, user details are shared across vaults.

Users in the Vault Owner and System Admin roles have access to all users in the vaults where they are assigned administrative access. Users with the Domain Admin setting enabled in their user profile and assigned the Admin: Users: Create, Edit permission in every domain vault, have access to all users across all vaults in your domain. Learn about Permission Sets in Vault Help.

To support domain-level user management, the API includes the following input options and request parameters:

domain=true - When creating a user, this can be (optionally) included in the input to add the user to the domain but not assign them to any vaults in the domain. When disabling a user, this is added to the request endpoint.

domain_active__v - When updating a user, this can be (optionally) included in the input and set to either true or false to enable or disable the user at the domain-level. Disabling a user at the domain-level will disable the user in every vault in your domain. Re-enabling a user enables them in the domain but does not re-activate them in their vaults. After re-enabling a user, you must update their vault membership to make them active in the individual vaults.

is_domain_admin__v - When creating or updating a user, this can be (optionally) included in the input and set to true to make a user a Domain Admin. When updating a user, this can be set to false to remove them from the Domain Admin role. Note that only another Domain Admin can do this. There must always be at least one Domain Admin.

Domain-level user management is available in API v7.0 or later.

Retrieve User Metadata

Request

Send GET to /api/{version}/metadata/objects/users

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/metadata/objects/users

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "properties": [
    {
      "name": "user_name__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_first_name__v",
      "type": "String",
      "length": 100,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_last_name__v",
      "type": "String",
      "length": 100,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "alias__v",
      "type": "String",
      "length": 40,
      "editable": true,
      "queryable": false,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_email__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_timezone__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "Pacific/Niue",
          "label": "(GMT-11:00) Niue Time (Pacific/Niue)"
        },
        {
          "value": "Pacific/Pago_Pago",
          "label": "(GMT-11:00) Samoa Standard Time (Pacific/Pago_Pago)"
        },
        ...
        ...
        ...
      ]
    },
    {
      "name": "user_locale__v",
      "type": "String",
      "length": 10,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "pt_BR",
          "label": "Brazil"
        },
        {
          "value": "es_ES",
          "label": "Spain"
        },
        ...
        ...
        ...
      ]
    },
    {
      "name": "user_title__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "office_phone__v",
      "type": "String",
      "length": 20,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "fax__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "mobile_phone__v",
      "type": "String",
      "length": 20,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "site__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "is_domain_admin__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "active__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "domain_active__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "security_policy_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "securitypolicies",
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_needs_to_change_password__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "id",
      "type": "id",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_date__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_by__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "modified_date__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "modified_by__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "domain_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "domains",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "vault_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "vaults",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": true,
      "onCreateEditable": false
    },
    {
      "name": "federated_id__v",
      "type": "String",
      "length": 100,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "salesforce_user_name__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "last_login__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "medidata_uuid__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_language__v",
      "type": "String",
      "length": 10,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "en",
          "label": "English"
        },
        {
          "value": "ja",
          "label": "Japanese"
        },
        ...
        ...
        ...
      ]
    },
    {
      "name": "company__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "group_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "groups",
      "editable": false,
      "queryable": false,
      "required": false,
      "multivalue": true,
      "onCreateEditable": false
    },
    {
      "name": "security_profile__v",
      "type": "ObjectReference",
      "length": 40,
      "object": "Securityprofile",
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "business_admin__v",
          "label": "Business Administrator"
        },
        {
          "value": "document_user__v",
          "label": "Document User"
        },
        {
          "value": "external_user__v",
          "label": "External User"
        },
        {
          "value": "read_only_user__v",
          "label": "Read-Only User"
        },
        {
          "value": "system_admin__v",
          "label": "System Administrator"
        },
        {
          "value": "vault_owner__v",
          "label": "Vault Owner"
        },
        {
          "value": "view_based_user__v",
          "label": "View-Based User"
        }
      ]
    },
    {
      "name": "license_type__v",
      "type": "Picklist",
      "length": 40,
      "picklist": "license_type__v",
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    }
  ]
}

Details

This response includes a full list of fields for users. Some field values are abridged to shorten this example response.

History

Since v1
v7+ - Supports domain-level user management. Learn more.
v10+ - Includes security_profile__v and license_type__v user fields.

Retrieve All Users

Request

Send GET to /api/{version}/objects/users

Headers

Response Accept - JSON application/json (default) or XML application/xml

Options

Using the endpoint alone with no optional parameters will retrieve users assigned only to the vault in which the request is made. For customers with multiple vaults in their domain, users with Domain Admin, System Admin, and Vault Owner privileges can access user information across different vaults in the domain by including the optional parameter vaults set to one of the following values:

Parameter & Value	Description
`vaults=all`	Retrieve all users assigned to all vaults in your domain.
`vaults=-1`	Retrieve all users assigned to all vaults in your domain except for the vault in which the request is made.
`vaults={Vault IDs}`	Use a comma-separated list of Vault IDs to retrieve users assigned only to the specified vaults.

System Admins and Vault Owners must have administrative access to Vault applications referenced in the vaults parameter to be able to access users from those vault.

Learn about Domain-Level User Management above.

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

Field	Description
`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`)

Example

This request will retrieve all users assigned to the vault in which the request is made.

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/users

Example

This request will retrieve all users assigned to all vaults in the domain. This is available only to Admin users with administrative access to the vaults.

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/users?vaults=all

Example

This request will retrieve all users assigned to all vaults in the domain except the vault in which the request is made. This is available only to Admin users with administrative access to the vaults.

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/users?vaults=-1

Example

This request will retrieve all users assigned to vault ID 3003, vault ID 4004, and vault ID 5005. This is available only to Admin users with administrative access to the vaults.

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/users?vaults=3003,4004,5005

Response (abridged)

{
    "responseStatus": "SUCCESS",
    "size": 200,
    "start": 0,
    "limit": 200,
    "sort": "id asc",
    "users": [
        {
            "user": {
                "id": 25501,
                "user_name__v": "ewoodhouse@veevapharm.com",
                "user_first_name__v": "Elaine",
                "user_last_name__v": "Woodhouse",
                ...
        },
        {
            "user": {
                "id": 25502,
                "user_name__v": "bashton@veevapharm.com",
                "user_first_name__v": "Bruce",
                "user_last_name__v": "Ashton",
                ...
        },                
        {
            "user": {
                "id": 25503,
                "user_name__v": "tchung@veevapharm.com",
                "user_first_name__v": "Thomas",
                "user_last_name__v": "Chung",
                ...
        },                
        ...

See the Vault User Metadata tables above for field descriptions.

History

Since v1
v7+ - Supports domain-level user management. Learn more.
v10+ - Includes security_profile__v and license_type__v user fields.

Retrieve User

Request

Send GET to /api/{version}/objects/users/{user_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{user_id} - The user id field value. See Retrieve All Users above.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/users/25496

Response

{
    "responseStatus": "SUCCESS",
    "users": [
        {
            "user": {
                "user_name__v": "ewoodhouse@veevapharm.com",
                "user_first_name__v": "Elaine",
                "user_last_name__v": "Woodhouse",
                "user_email__v": "ewoodhouse@veevapharm.com",
                "user_timezone__v": "America/New_York",
                "user_locale__v": "en_US",
                "user_title__v": "Research Associate",
                "office_phone__v": "5559876543",
                "fax__v": "5556789123",
                "mobile_phone__v": "5551234567",
                "site__v": "Manhattan",
                "is_domain_admin__v": false,
                "active__v": true,
                "domain_active__v": true,
                "security_policy_id__v": 821,
                "user_needs_to_change_password__v": false,
                "id": 25496,
                "created_date__v": "2013-01-08T15:55:27.000Z",
                "created_by__v": 25001,
                "modified_date__v": "2015-02-12T18:22:18.000Z",
                "modified_by__v": 25001,
                "domain_id__v": 3003,
                "vault_id__v": [
                    3003,
                    4004
                ],
                "federated_id__v": "",
                "salesforce_user_name__v": "",
                "last_login__v": "2015-01-20T23:58:02.000Z",
                "medidata_uuid__v": "",
                "user_language__v": "en",
                "company__v": "VeevaPharm",
                "group_id__v": [
                    2555089996,
                    2111844470
                ],
                "security_profile__v": "document_user__v",
                "license_type__v": "full__v",
                "vault_membership": [
                    {
                        "id": 3003,
                        "active__v": true,
                        "security_profile__v": "document_user__v",
                        "license_type__v": "full__v"
                    },
                    {
                        "id": 4004,
                        "active__v": true,
                        "security_profile__v": "document_user__v",
                        "license_type__v": "full__v"
                    }
                ]
            }
        }
    ]
}

See the Vault User Metadata tables above for field descriptions.

History

Since v1
v7+ - Supports domain-level user management. Learn more.
v10+ - Includes security_profile__v and license_type__v user fields.

Create User

Create a new user account. See also Bulk Users API.

Request

Send POST to /api/{version}/objects/users

Headers

Input Content-Type - Name-Value Pair multipart/form-data
Response Accept - JSON application/json (default) or XML application/xml

Input

When creating new users, the following fields are required in all vaults:

user_name__v
user_first_name__v
user_last_name__v
user_email__v
user_timezone__v
user_locale__v
user_language__v
security_policy_id__v

See the Vault User Metadata tables above for field descriptions.

Options

You may add values to any other editable user field.

You may add a user profile picture. To do so, include the file parameter in the input with the path/location of the image to be uploaded. For example: -F "file=images/elaine.jpg". Uploaded profile pictures must be JPG, PNG, or GIF files, and less than 10MB in size. Vault automatically resizes images to 64 x 64 pixels, and removes the animations for animated GIFs. Images of approximately square aspect ratio will work best as profile pictures.

Example: Add User to Domain

This request will add one new user to your domain. It will not assign them to individual vaults in your domain. See also: Update Vault Membership.

This request includes all required fields to create a new user. By including domain=true, the user will not be assigned to a vault.

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "user_name__v=ewoodhouse@veevapharm.com" \
-F "user_email__v=ewoodhouse@veevapharm.com" \
-F "user_first_name__v=Elaine" \
-F "user_last_name__v=Woodhouse" \
-F "user_language__v=en" \
-F "user_timezone__v=America/Denver" \
-F "user_locale__v=en_US" \
-F "security_policy_id__v=821" \
-F "domain=true" \
https://myvault.veevavault.com/api/v15.0/objects/users

On SUCCESS, the user account will be created and set to active. The new user will not be assigned a license type or security profile, nor will they have access to any vaults in your domain.

Example: Add User to Current Vault

This request will add one new user to your domain. It will also assign them to the vault in which the request is made. See also: Update Vault Membership.

This request includes all required fields to create a new user. This request includes the security profile and license type fields. This is optional. If not included in the request, this user would be assigned the document_user__v security profile and full__v license type by default.

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "user_name__v=ewoodhouse@veevapharm.com" \
-F "user_email__v=ewoodhouse@veevapharm.com" \
-F "user_first_name__v=Elaine" \
-F "user_last_name__v=Woodhouse" \
-F "user_language__v=en" \
-F "user_timezone__v=America/Denver" \
-F "user_locale__v=en_US" \
-F "security_policy_id__v=821" \
-F "security_profile__v=business_admin__v" \
-F "license_type__v=full__v" \
https://myvault.veevavault.com/api/v15.0/objects/users

Details

On SUCCESS, the user account will be created and set to active. The new user will be a member of the vault instance in which the request was made and assigned the Business Admin security profile and Full User license type. They will receive a welcome email with instructions for logging into the vault. They will not have access to any other vaults in your domain. To give them access to other vaults, see Update Vault Membership below.

History

Since v1
v7+ - Supports domain-level user management. Learn more.
v8+ - domain_active__v field cannot be set when creating a user.
v10+ - Includes security_profile__v and license_type__v user fields.

Create Multiple Users

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Users\create_users.csv" \
https://myvault.veevavault.com/api/v12.0/objects/users

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "id":"12021"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12022"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12023"
      },      
      {
         "responseStatus":"FAILURE",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not created."
            }
         ]
      }
   ]
}

Create new users and assign them to vaults in bulk.

The maximum input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.
If you want to add profile pictures, you must upload these to the FTP staging server.

Headers

Name	Description
`Content-Type`	`application/json` or `text//csv`
`Accept`	`application/json` (default) or `text//csv`

Body Parameters

Prepare a JSON or CSV input file. You may add values to any other editable user field. See Retrieve User Metadata for all possible values. Using only the required fields will add users to your domain but will not assign them to individual vaults within your domain. See Vault Membership below.

Name	Description
`user_name__v`	The user’s vault username (login credential). For example, `ewoodhouse@veepharm.com`
`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 time zone. Retrieve values from Retrieve User Metadata.
`user_locale__v`	The user's location. Retrieve values from Retrieve User Metadata.
`security_policy_id__v`	The user's security policy. Retrieve values from Retrieve All Security Policies.
`user_language__v`	The user's preferred language. Retrieve values from Retrieve User Metadata.
`file`	Optional: The file path of a profile picture from the FTP. Must be JPG, PNG, or GIF, and less than 10MB in size. Vault automatically resizes images to 64 x 64 pixels and removes the animations from GIFs.
`domain`	Optional: If you set this to `true`, the user will not be assigned to a vault.
`security_profile__v`	Optional: The user’s security profile. If omitted, default value is `document_user__v`.
`license_type__v`	Optional: The user’s license type. If omitted, default value is `full__v`.
`vault_membership`	Optional: Use this field to assign a user to individual vaults within your domain. See below for how to configure.

Vault Membership

To assign user permissions across vaults, you must include the vault_membership field and configured with the following fields:

Name	Description
`id`	The vault ID to assign the user to.
`active__v`	Optional: Set the user to active (`true`) or inactive (`false`). If not specified, default value is `true`.
`security_profile__v`	Optional: Set the user's security profile, for example, `read_only_user__v`. If not specified, this value defaults to `document_user__v`.
`license_type__v`	Optional: Set the user's license type, for example, `read_only__v`. If not specified, this value defaults to `full__v`.

For example, to add an active user to vault ID 3003 with the system_admin__vsecurity profile and the full__v license type:

`vault_membership`
`3003`:`true`:`system_admin__v`:`full__v`

Application Licensing

To add a user to specific applications within a vault or across vaults, you must include the app_licensing column configured with the following fields:

Name	Description
`vault_id`	The vault ID to assign the user to.
`active__v`	Optional: Set the user to active (`true`) or inactive (`false`). If not specified, default value is `true`.
`application_name`	The application to add the user to. Possible values are: `rimSubsArch_v` `rimSubs_v` `rimReg_v` `qualityQms_v` `qualityQdocs_v`
`license_type__v`	Optional: Set the user's license type, for example, `read_only__v`.

The format for adding these fields is:

{vault_id}|{application_name}{:active__v}{:license_type__v}

To add a user to more than one application, separate the applications with a pipe. To add a user to applications in multiple vaults, separate the vaults with a semicolon. For example:

`app_licensing`
`3003`\|`rimReg_v:true:full__v`\|`rimSubs_v:true:full__v;4112`\|`rimSubs_v:true:full__v`

This adds an active user to both RIM Registrations and RIM Submissions in vault ID 3003, and to the RIM Submissions application in vault ID 4112, all with the full__v license type.

Query String Parameters: Upsert Users

Upsert is a combination of create and update. Use one input file to create new users and update existing users at the same time. If a matching user record is found in your vault, it is updated with the field values specified in the input. If no matching user record is found, a new user is created using values in the input.

Name	Description
`operation`	To upsert users, you must include `operation=upsert`
`idParam`	To upsert users, you must include either `idParam=id` or `idParam=user_name__v` to the request endpoint.

Response Details:

On SUCCESS, Vault responds will list the id of each user. The order results are displayed in the response is the same as the order of records in the input.

Update User

Update information for a user. See also Bulk Users API.

Permissions

System Admins and Vault Owners can update users in the vaults where they have administrative access.
System Admins who are also Domain Admins have an unrestricted access to users across all vaults in the domain.

Request

Send PUT to /api/{version}/objects/users/{user_id}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{user_id} - The user id field value. See Retrieve All Users above.

Example: Update User Profile Information

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "user_timezone__v=America/Los Angeles" \
-d "company__v=VeevaPharm" \
-d "user_title__v=Product Manager" \
-d "alias__v=Skipper" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001

See the Vault User Metadata tables above for field descriptions.

Example: Disable User at Domain-Level

Only Domain Admins may use this request.

This request will set the user (ID: 25001) profile to inactive in all vaults in your domain. The user will still be a member in the vaults and retain their license types and security profiles, but their user profile will be inactive and they will no longer have access to any vaults in your domain.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "domain_active__v=false" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001

See the Vault User Metadata tables above for field descriptions.

Example: Re-Enable User at Domain-Level

Only Domain Admins may use this request.

This request will set the (previously inactive) user (ID: 25001) profile to active in your vault domain. However, they will still be inactive in and unable to access your domain vaults. Use the Update Vault Membership request below to set their status to active in the individual vaults in your domain.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "domain_active__v=false" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001

See the Vault User Metadata tables above for field descriptions.

Example: Promote a User to Domain Admin

Only Domain Admins may use this request.

This request will promote a user to Domain Admin. To remove a user from the Domain Admin role, set the is_domain_admin__v field to false. Each domain must have at least one user in the Domain Admin role.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "is_domain_admin__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001

See the Vault User Metadata tables above for field descriptions.

Response

{
    "responseStatus": "SUCCESS",
    "id": 25001
}

History

Since v1
v7+ - Supports domain-level user management. Learn more.
v10+ - Includes security_profile__v and license_type__v user fields.

Update Multiple Users

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Users\update_users.csv" \
https://myvault.veevavault.com/api/v12.0/objects/users

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "id":"12021"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12022"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12023"
      },      
      {
         "responseStatus":"FAILURE",
         "id":"22124",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not updated."
            }
         ]
      }
   ]
}

Update information for multiple users at once.

The maximum input file size is 1GB.
The values in the input must be UTF-8 encoded.
CSVs must follow the standard format.
The maximum batch size is 500.
If you want to update profile pictures, you must upload these to the FTP staging server.

PUT /api/{version}/objects/users

Headers

Name	Description
`Content-Type`	`application/json` or `text/csv`
`Accept`	`application/json` (default) or `text/csv`

Body Parameters

Prepare a JSON or CSV input file. The following are the only required fields. You can include any editable user field and value in the input.

Name	Description
`id`	The ID of the user to update.

Disable User

Disable a user in a specific vault or disable a user in all vaults in the domain. See also Bulk Users API.

Permissions

Request

Send DELETE to /api/{version}/objects/users/{user_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{user_id} - The user id field value. See Retrieve All Users above.

Options

/api/{version}/objects/users/{user_id}?domain=true - This disables the user account in all vaults in the domain.

Example: Disable User in a Vault

This request will set the user (ID: 25001) profile to inactive in the vault in which the request is made. The user will still be a member in the vault and retain their license type and security profile, but their user profile will be inactive and they will no longer have access to the vault.

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001

Example: Disable User in All Domain Vaults

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001?domain=true

Response

{
    "responseStatus": "SUCCESS",
    "id": 25001
}

History

Since v1
v7+ - Supports domain-level user management. Learn more.
v10+ - Includes security_profile__v and license_type__v user fields.

Change User Password

Change the password for a user. See also Bulk Users API.

Request

Send POST to /api/{version}/objects/users/{user_id}/password

Permissions

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{user_id} - The user id field value. See Retrieve All Users above.

Input

password__v - Enter the current password.
new_password__v - Enter the new password.

Passwords must meet minimum requirements. Learn about Password Requirements in Vault Help.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "password__v=CurrentPassword" \
-d "new_password__v=NewPassword" \
https://myvault.veevavault.com/api/v15.0/objects/users/25496/password

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, the password will be changed and the user will receive an email notification with instructions.

History

Since v7

Update Vault Membership

Use this request to:

Assign an existing user to a vault in your domain.
Remove (disable) an existing user from a vault in your domain.
Update the security profile and license type of an existing user.

You cannot use this request to:

Create a new user. See Create User above.
Update other user profile information. See Update User above.

Additional information:

For a list of user fields and properties, see Vault User Metadata above.
Learn about Creating & Managing Users and Managing Users Across Vaults in Vault Help.
See also Bulk Users API.

Permissions

Request

Send PUT to /api/{version}/objects/users/{user_id}/vault_membership/{vault_id}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{user_id} - The user id field value. See Retrieve All Users above.
{vault_id} - The system-managed id field value assigned to each vault in the domain. See Retrieve Domain Vaults above.

Input

The following fields and values may be (optionally) submitted with the request:

Field & Value	Description
`active__v=true`	Assigns the user to the vault sets their status to active.
`active__v=false`	Sets the user status to inactive in the vault.
`security_profile__v={security_profile}`	Assigns the user a specific security profile in the vault.
`license_type__v={license_type}`	Assigns the user a specific license type in the vault.

See the example requests below for additional information about using these input values.

Example: Add User to a Vault

This request will assign the user (ID: 25001) to the vault (ID: 3003). There are a few default settings that will be applied here:

The user's status will be set to active in the vault. This is the default setting; the "active__v=true" parameter can omitted and produce the same results. We've not included the optional security_profile__v and license_type__v in the input. Therefore, the user will be assigned a full__v license type and document_user__v security profile by default.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001/vault_membership/3003

Example: Disable User in a Vault

This request will set the user (ID: 25001) profile to inactive in the vault (ID: 3003). They will still be a member in the vault and retain their license type and security profile, but their user profile will be inactive and they will no longer have access to the vault.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "active__v=false" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001/vault_membership/3003

Example: Set Security Profile & License Type

This request will set the user (ID: 25001) security profile and license type to specific values in the vault (ID: 3003). If the user is already a member of the vault, this will change their security profile and license type. If the user is not a member of the vault, this will assign them to the vault, set their status to active, and their security profile and license type to the specified values.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "security_profile__v=business_admin__v" \
-d "license_type__v=full__v"
https://myvault.veevavault.com/api/v15.0/objects/users/25001/vault_membership/3003

History

Since v1
v7+ - Supports domain-level user management. Learn more.
v10+ - Includes security_profile__v and license_type__v user fields.

Retrieve Your Information

The user authenticated with the API can retrieve their own user profile information.

Request

Send GET to /api/{version}/objects/users/me

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/users/me

Response (abridged)

{
    "responseStatus": "SUCCESS",
    "users": [
        {
            "user": {
                "user_name__v": "quinn.taylor@veevapharm.com",
                "user_first_name__v": "Quinn",
                "user_last_name__v": "Taylor",
                "alias__v": "Vault Admin",
                "user_email__v": "quinn.taylor@veevapharm.com",
                "user_timezone__v": "America/Los_Angeles",
                "user_locale__v": "en_US",
                ...

Details

See Vault User Metadata above for detailed user field information.
Learn about Changing Passwords & User Profiles in Vault Help.

History

Since v12

Update Your Information

The user authenticated with the API can update their own user profile information.

Request

Send PUT to /api/{version}/objects/users/me

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Input

Add or remove values on any editable user field.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "alias__v=API Admin" \
-d "user_timezone__v=America/Denver" \
https://myvault.veevavault.com/api/v15.0/objects/users/me

Response

{
    "responseStatus": "SUCCESS",
    "id": 25001
}

Details

See Vault User Metadata above for detailed user field information.
Learn about Changing Passwords & User Profiles in Vault Help.

History

Since v12

Change Your Password

The user authenticated with the API can change their own password.

Request

Send POST to /api/{version}/objects/users/me/password

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Input

password__v - Your current password
new_password__v - Your new password

Passwords must meet minimum requirements. Learn about Password Requirements in Vault Help.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "password__v=MyCurrentPassword" \
-d "new_password__v=MyNewPassword" \
https://myvault.veevavault.com/api/v15.0/objects/users/me/password

Response

{
    "responseStatus": "SUCCESS"
}

Details

See Vault User Metadata above for detailed user field information.
Learn about Changing Passwords & User Profiles in Vault Help.

History

Since v12

Groups

Groups are key to managing user access in Vault. A group is simply a named list of users, but by defining groups that reflect the teams and roles in your company, and assigning those groups to document roles, you can manage document access more easily and efficiently. In vaults using Dynamic Access Control (DAC) for documents, Vault also automatically creates groups that correspond to one lifecycle role and additional document field criteria. These are called Auto Managed Groups.

Learn about Groups in Vault Help.

Vault Group Metadata

The Vault groups object includes a fixed set of fields. You cannot add or remove fields, nor can you change the field names or labels.

All group fields are listed in the table below:

Field Name	Field Label	Field Type	Description	Required	Editable	Queryable
`id`	ID	id	Unique group identifier (permanent). Numeric value.	System-Managed	False	True
`name__v`	Name	String	Unique group identifier. Alphanumeric value.	False	False	True
`label__v`	Label	String	Unique group identifier. Alphanumeric value.	True	True	True
`group_description__v`	Description	String	Group description.	False	True	True
`members__v`	Members	ObjectReference	Users assigned individually (not implied users added via security profile).	False	True	False
`implied_members__v`	Implied Members *	ObjectReference	Users assigned automatically by adding a security profile.	False	False	False
`security_profiles__v`	Security Profiles *	ObjectReference	Security profile to automatically add implied members.	False	True	False
`active__v`	Active	Boolean	Whether or not the group is active.	False	True	True
`type__v`	Type	String	User Managed Group or System Provided Group.	System-Managed	False	True
`editable__v`	Editable	Boolean	Whether or not the group is editable (not system-managed).	System-Managed	False	True
`system_group__v`	System Group	Boolean	Whether or not the group was automatically created by the system.	System-Managed	False	True
`created_date__v`	Created Date	ObjectReference	The date and time when the group was created.	System-Managed	False	False
`created_by__v`	Created By	ObjectReference	The user ID of the person who created the group.	System-Managed	False	False
`modified_date__v`	Modified Date	ObjectReference	The date and time when the group was last modified.	System-Managed	False	False
`modified_by__v`	Modified By	ObjectReference	The user ID of the person who last modified the group.	System-Managed	False	False

* The implied_members__v and security_profiles__v fields are available in API v12.0 or later.

Metadata Fields (Properties): The information listed below may be included with each field.

Metadata Field	Description
`name`	Field name.
`type`	Field type.
`object`	When the field type is "ObjectReference", this shows the name of the object being referenced.
`multivalue`	Whether or not the field can have multiple values.
`queryable`	Whether or not the field can be used in API queries.
`length`	When the field type is "String", this shows the maximum character length allowed.
`required`	Whether or not the field is required when creating a new group.
`onCreateEditable`	Whether or not the field can be set when creating a new group.
`editable`	Whether or not the field is editable.

Retrieve Group Metadata

Request

Send GET to /api/{version}/metadata/objects/groups

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/metadata/objects/groups

Response

{
  "responseStatus": "SUCCESS",
  "properties": [
    {
      "name": "id",
      "type": "id",
      "length": 20,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "label__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "group_description__v",
      "type": "String",
      "length": 200,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "system_group__v",
      "type": "Boolean",
      "length": 1,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_date__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_by__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "modified_date__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "modified_by__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "members__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": true,
      "queryable": false,
      "required": true,
      "multivalue": true,
      "onCreateEditable": true
    },
    {
      "name": "implied_members__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": false,
      "required": false,
      "multivalue": true,
      "onCreateEditable": false
    },
    {
      "name": "security_profiles__v",
      "type": "ObjectReference",
      "length": 40,
      "object": "Securityprofile",
      "editable": true,
      "queryable": false,
      "required": false,
      "multivalue": true,
      "onCreateEditable": true
    },
    {
      "name": "active__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "name__v",
      "type": "String",
      "length": 40,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "editable__v",
      "type": "Boolean",
      "length": 1,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "type__v",
      "type": "String",
      "length": 40,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    }
  ]
}

See the Vault Group Metadata tables above for field descriptions.

History

Since v1

Retrieve All Groups

Request

Send GET to /api/{version}/objects/groups

Headers

Response Accept - JSON application/json (default) or XML application/xml

Options

/api/{version}/objects/groups?includeImplied=true - When used, the response includes the implied_members__v field. These users are automatically added to the group when their security_profiles__v are added to the group. When not used, the response includes only the members__v field. These users are individually added to a group by Admin.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/groups

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "groups": [
    {
      "group": {
        "members__v": [
          25496,
          25513,
          25514,
          25515,
          25519,
          25524,
          25525,
          25526,
          25527,
          25528,
          25532
        ],
        "active__v": true,
        "security_profiles__v": [
          "document_user__v",
          "business_admin__v",
          "system_admin__v",
          "vault_owner__v"
        ],
        "name__v": "all_internal_users__v",
        "modified_by__v": 25524,
        "editable__v": true,
        "modified_date__v": "2016-03-08T21:13:49.000Z",
        "group_description__v": "All Internal Vault Users (System Provided Group)",
        "system_group__v": true,
        "label__v": "All Internal Users",
        "created_date__v": "2014-02-17T10:09:03.000Z",
        "type__v": "System Provided Group",
        "id": 1,
        "created_by__v": 1
      }
    },
    ...

See the Vault Group Metadata tables above for field descriptions.

History

Since v1

Retrieve Group

Request

Send GET to /api/{version}/objects/groups/{group_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{group_id} - The group id field value.

Options

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/groups/1435176677013

Response

{
  "responseStatus": "SUCCESS",
  "groups": [
    {
      "group": {
        "members__v": [
          25518,
          25519,
          25520
        ],
        "active__v": true,
        "security_profiles__v": [],
        "name__v": "cholecap_editors_group__c",
        "modified_by__v": 46916,
        "editable__v": true,
        "modified_date__v": "2015-06-24T20:11:17.000Z",
        "group_description__v": null,
        "system_group__v": false,
        "label__v": "Cholecap Editors Group",
        "created_date__v": "2015-06-24T20:11:17.000Z",
        "type__v": "User Managed Group",
        "id": 1435176677013,
        "created_by__v": 46916
      }
    }
  ]
}

See the Vault Group Metadata tables above for field descriptions.

History

Since v1

Create Group

Request

Send POST to /api/{version}/objects/groups

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Input

Field Name	Description
`label__v`	[Required] Enter a group label. Vault uses this to create the group `name__v` value.
`members__v`	[Optional] Add a comma-separated list of user IDs. This manually assigns individual users to the group.
`security_profiles__v`	[Optional] Add a comma-separated list of security profiles. This automatically adds all users with the security profile to the group. These are `implied_members__v`.
`active__v`	[Optional] By default, the new group will be created as active. To set the group to inactive, set this value to `false`
`group_description__v`	[Optional] Add a description of the group.

See the Vault Group Metadata tables above for field descriptions.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "label__v=Cholecap Team US Compliance" \
-d "members__v=45501,45002" \
-d "security_profiles__v=document_user__v"
https://myvault.veevavault.com/api/v15.0/objects/groups

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Group successfully created.",
  "id": 1358979070034
}

History

Since v1

Update Group

Update editable group field values. Add or remove group members and security profiles.

Request

Send PUT to /api/{version}/objects/groups/{group_id}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{group_id} - The group id field value.

Input

You may change the values of any editable group field. Changing the security_profiles__v will automatically replace all previous implied users assigned via the previous security profile. All user IDs included in members__v will replace all previous users who were manually assigned. This action is not additive.

See the Vault Group Metadata tables above for field descriptions.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "label__v=Cholecap Team" \
-d "members__v=45501,45502,45503,45004" \
https://myvault.veevavault.com/api/v15.0/objects/groups/1358979070034

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Group successfully updated.",
  "id": 1358979070034
}

History

Since v1

Delete Group

Delete a user-defined group. You cannot delete system-managed groups.

Request

Send DELETE to /api/{version}/objects/groups/{group_id}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{group_id} - The group id field value.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/groups/1358979070034

Response

{
    "responseStatus": "SUCCESS",
    "id": 1358979070034
}

History

Since v1

Picklists

Picklists allow users to select a value for a field from a range of predefined options. A single picklist may contain up to 1024 options (values). The API supports retrieving picklists and picklist values, creating and deleting picklist values, and updating picklist value labels and names. The API does not support creating, updating, or deleting the picklists themselves; this must be done in the Admin UI.

Learn about Picklists in Vault Help.

Retrieve All Picklists

Request

Send GET to /api/{version}/objects/picklists

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/picklists

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "errorCodes": null,
  "picklists": [
    {
      "name": "agency_name1__vs",
      "label": "Agency Name",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "otherAgencies_pm"
        }
      ]
    },
    {
      "name": "agency_name__vs",
      "label": "Agency Name",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "creativeAgency_pm"
        }
      ]
    },
    {
      "name": "application_type__vs",
      "label": "Application Type",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "compliance_package__v",
          "propertyName": "applicationType_pm"
        }
      ]
    },
    {
      "name": "asset_type__vs",
      "label": "Asset Type",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs:advertisement__vs:web__vs",
          "propertyName": "assetType_pm"
        },
        {
          "documentTypeName": "claim__vs",
          "propertyName": "assetType_pm"
        }
      ]
    },
    {
      "name": "audience__vs",
      "label": "Audience",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "audience_pm"
        }
      ]
    },
    {
      "name": "branding__vs",
      "label": "Branding",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "brandingStatus_pm"
        }
      ]
    },
    {
      "name": "campaign_name__vs",
      "label": "Campaign",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "campaign_pm"
        }
      ]
    },
    {
      "name": "claim_category__vs",
      "label": "Claim Category",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "claim__vs",
          "propertyName": "claimCategory_pm"
        }
      ]
    },
    {
      "name": "email_template_type__v",
      "label": "Email Template Type",
      "kind": "global",
      "system": true,
      "usedIn": [
        {
          "documentTypeName": "email_template__v",
          "propertyName": "emailTemplateType_b"
        }
      ]
    },
    {
      "name": "language__v",
      "label": "Language",
      "kind": "global",
      "system": true,
      "usedIn": [
        {
          "documentTypeName": "base_document__v",
          "propertyName": "language__v"
        }
      ]
    },
    {
      "name": "material_type__vs",
      "label": "Material Type",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "materialType_pm"
        }
      ]
    },
    {
      "name": "media_type__vs",
      "label": "Media Type",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "mediaType_pm"
        }
      ]
    },
    {
      "name": "method_of_delivery__vs",
      "label": "Method of Delivery",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "methodOfDelivery"
        }
      ]
    },
    {
      "name": "mlr_type__vs",
      "label": "MLR Type",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__vs",
          "propertyName": "mlrType_pm"
        }
      ]
    },
    {
      "name": "product_family__vs",
      "label": "Product Family",
      "kind": "global",
      "usedIn": [
        {
          "objectName": "product__v",
          "propertyName": "product_family__vs"
        }
      ]
    },
    {
      "name": "therapeutic_area__vs",
      "label": "Therapeutic Area",
      "kind": "global",
      "usedIn": [
        {
          "objectName": "product__v",
          "propertyName": "therapeutic_area__vs"
        }
      ]
    },
    {
      "name": "license_type__v",
      "label": "License Type",
      "kind": "user",
      "system": true
    },
    ...
  ],
  "errorType": null
}

Details

Metadata Field	Description
`name`	Picklist name. This is used only in the API and displayed in the Admin UI.
`label`	Picklist label. This is used in the API and UI. Users see the label on document and object picklist fields.
`kind`	There are two kinds of picklists: `global` picklists apply to documents and objects; `user` picklists apply to Vault users.
`system`	Indicates if the picklist is system-managed. If true, the picklist values cannot be added, edited, or removed.
`usedIn`	The document type or object in which the picklist is defined.
`documentTypeName`	For document picklists, this the document type name in which the picklist is defined.
`objectName`	For object picklists, this is the object name in which the picklist is defined.
`propertyName`	For document picklists, this is the document field name using the picklist. For object picklists, this is the object field name using the picklist.

History

Since v4
v12+ - Includes milestone_type__v picklist (eTMF vaults).
v14+ - Removed document and object picklist types. All picklists are global types.

Retrieve Picklist Values

Retrieve all available values configured on a picklist.

Request

Send GET to /api/{version}/objects/picklists/{picklist_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{picklist_name} - The picklist name field value (license_type__v, product_family__vs, region__c, etc.)

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/picklists/license_type__v

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "picklistValues": [
    {
      "name": "full__v",
      "label": "Full User"
    },
    {
      "name": "read_only__v",
      "label": "Read-only User"
    },
    {
      "name": "external__v",
      "label": "External User"
    },
    {
      "name": "view_based__v",
      "label": "View-Based User"
    }
  ]
}

Details

Metadata Field	Description
`name`	The picklist value name. This is used only in the API and displayed in the Admin UI.
`label`	The picklist value label. This is used in the API and UI. Users see the label when selecting picklist values.

History

Since v4

Create Picklist Values

Add new values to a picklist. You can add up to 1024 values to any picklist.

Request

Send POST to /api/{version}/objects/picklists/{picklist_name}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{picklist_name} - The picklist name field value (license_type__v, product_family__vs, region__c, etc.)

Input

To add new values, use value_1, value_2, etc., set to alphanumeric values. Enter each new picklist value label as they will be displayed in the UI. Vault uses the label to create the picklist value name.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "value_1=North America" \
-d "value_2=Central America" \
-d "value_3=South America" \
https://myvault.veevavault.com/api/v15.0/objects/picklists/regions__c

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Created picklist value(s).",
  "picklistValues": [
    {
      "name": "north_america__c",
      "label": "North America"
    },
    {
      "name": "central_america__c",
      "label": "Central America"
    },
    {
      "name": "south_america__c",
      "label": "South America"
    }
  ]
}

Details

Metadata Field	Description
`name`	The picklist value name. This is used only in the API and displayed in the Admin UI.
`label`	The picklist value label. This is used in the API and UI. Users see the label when selecting picklist values.

History

Since v4

Update Picklist Value Label

Change a picklist value label (only). To change a picklist value name, see the next section below.

CAUTION: Use caution when editing picklist labels or names. When these attributes are changed, they affect all existing document and object metadata that refer to the picklist. For users in the UI who are accustomed to seeing a particular selection, the changes may cause confusion. This may also break existing integrations that access picklist values via the API.

Request

Send PUT to /api/{version}/objects/picklists/{picklist_name}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{picklist_name} - The picklist name field value (license_type__v, product_family__vs, region__c, etc.)

Input

To change an existing picklist value label, use its picklist value name set to a new label. The picklist value name will remain unchanged. For example, to change the label of the existing "north_america__c=North America", enter "north_america__c=North America/United States". You may include one or more picklist values in the request.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "north_america__c=North America/United States" \
https://myvault.veevavault.com/api/v15.0/objects/picklists/regions__c

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Updated picklist value(s).",
  "picklistValues": [
    {
      "name": "north_america__c",
      "label": "North America/United States"
    }
  ]
}

Details

As shown above, only the picklist value label has changed. The picklist value name remains the same. The new label will be automatically updated on all documents and objects in which it is used. In the UI, users will see the new label when selecting values for the picklist. In the UI, Admins will see the new name in Admin > Business Admin > Picklists > {Picklist}.

History

Since v4

Update Picklist Value Name

Change a picklist value name (only). To change a picklist value label, see the previous section above.

Request

Send PUT to /api/{version}/objects/picklists/{picklist_name}/{picklist_value_name}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{picklist_name} - The picklist name field value (license_type__v, product_family__vs, region__c, etc.)
{picklist_value_name} - The picklist value name field value (north_america__c, south_america__c, etc.)

Input

To change an existing picklist value name, use name set to a new value. The picklist value label will remain unchanged. For example, to change the picklist value name north_america__c, enter "name=north_america_united_states". Values may only contain a-z, 0-9, and single consecutive underscores; cannot start or end with an underscore; cannot contain spaces (use underscores). Do not append the name with __v, __vs, or __c. Vault will add __c after processing.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name=north_america_united_states" \
https://myvault.veevavault.com/api/v15.0/objects/picklists/regions__c/north_america__c

Response

{
  "responseStatus": "SUCCESS"
}

Details

Only the picklist value name is changed. The picklist value label remains the same. In the UI, Admins will see the new name in Admin > Business Admin > Picklists > {Picklist}.

History

Since v4

Delete Picklist Value

Remove a value from a picklist.

Request

Send DELETE to /api/{version}/objects/picklists/{picklist_name}/{picklist_value_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/picklists/regions__c/north_america_united_states__c

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Deleted picklist value.",
  "name": "north_america_united_states__c"
}

History

Since v4

Lifecycles

Document lifecycles are the sequences of states (Draft, In Review, etc.) a document goes through during its life. A lifecycle can be simple (two states requiring users to manually move between states) or very complex (multiple states with different security and workflows that automatically move the document to another state). In Vault, lifecycles simplify the implementation of business logic that traditionally required custom coding or time-consuming manual setup.

Lifecycle states are the ordered states within a lifecycle represent the stages a document transitions through as users create, review, approve and eventually archive or replace it. A set of business rules applies to each state and defines what happens to the document in that state. Admins define these rules for each lifecycle state and Vault automatically applies them to every document that enters the state.

Business Rules: Each state has the following configuration options:

User Actions: Actions that end users can perform on a document.
Security Settings: Permissions that users in each role have for a document.
Entry Criteria: Conditions that a document must meet before transitioning into this state.
Entry Actions: Actions that Vault performs automatically when a document enters this state.

Learn about Lifecycles & Workflows in Vault Help.

Document & Binder User Actions

The API supports initiation of the following user action types:

Workflow
State Change
Controlled Copy
Create Presentation

Your vault may include other user action types, all of which cannot be initiated through the Vault API.

Note: The API does not support initiation of user actions requiring eSignatures.

Entry Criteria

Before users can initiate a user action, the document or binder must satisfy certain entry criteria. Entry requirements are dynamic and depend on the lifecycle configuration, entry criteria defined for the lifecycle state, and/or the workflow activation requirements defined in the Start Step of the workflow.

Property Scope

The API specifies the scope for the each requirement:

Document scope means that the property is document-level and must be updated on the document before initiating the user action.
Binder scope means that the property is binder-level and must be updated on the binder before initiating the user action.
Workflow scope means that the property is workflow-level and must be specified at the time of action initiation.
Controlled Copy scope means that the property is controlled copy specific and must be specified at the time of action initiation.

Typical Implementation

In a typical implementation, the client requests the available user actions using the Get User Actions endpoint. The response to this call lists user actions that the current user can initiate on a document or a binder specified by its ID and version.

Overview of Steps

Step 1: Retrieve User Actions

Retrieve a list of available user actions on a specific version of a document or binder.
The response includes the name of each user action used to initiate the action and the endpoint to retrieve the entry criteria.

Step 2: Retrieve Entry Criteria

Before initiating a user action, you need to ensure that the document or binder meets certain conditions (required fields are populated, etc.).
For example, you don't need to assign a user to the "Approver" role when the document is first uploaded, but you do need to when initiating the "Start Approval" workflow.
Not all user actions have entry criteria. In these cases, you can simply proceed with initiation of the user action.
When the entry criteria "scope": "WorkflowActivation", the values can be specified as name-value pairs with the lifecycle initiation request.
When the entry criteria "scope": "Document" or "scope": "Binder" the values must first be updated on the document or binder before initiating the request.

Step 3: Initiate User Action

Once you've determined the entry criteria and completed those which must be configured separately, you can initiate the user action.
Vault will evaluate whether all the entry criteria have been met and, if so, will initiate the user action on the specified version of the document or binder.

Retrieve User Actions

Retrieve all available user actions that can be initiated on a specific version of a document or binder.

Request

Documents: Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions
Binders: Send GET to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "lifecycle_actions__v": [
    {
      "name__v": "startApproval",
      "label__v": "Start Approval",
      "lifecycle_action_type__v": "workflow",
      "entry_requirements__v": "https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval/entry_requirements"
    },
    {
      "name__v": "approve",
      "label__v": "Approve",
      "lifecycle_action_type__v": "stateChange",
      "entry_requirements__v": "https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions/approve/entry_requirements"
    }
  ]
}

Details

The response lists all available user actions (lifecycle_actions__v) that can be initiated on the specified version of the document or binder.

name__v - The user action name (consumed by the API). These vary from vault to vault and may be text, numeric, or alphanumeric values.
label__v - The user action label.
lifecycle_action_type__v - The workflow and stateChange types are the most commonly used and are available in all vaults. Others may exist.
entry_requirements__v - The endpoint to retrieve the entry criteria for each user action. If no entry criteria exist, this will be excluded from the response.

Note that user actions are not returned for documents or binders which are currently in an active workflow.

History

Since v6

Retrieve Entry Criteria

Once you've retrieved the available user actions, you can retrieve the entry criteria for a specific user action.

Request

Documents: Send GET to /api/{version}/objects/documents/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{name__v}/entry_requirements
Binders: Send GET to /api/{version}/objects/binders/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{name__v}/entry_requirements

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

document_id - The document id field value from which to retrieve available user actions.
binder_id - The binder id field value from which to retrieve available user actions.
major_version_number__v - The major version number of the document or binder.
minor_version_number__v - The minor version number of the document or binder.
name__v - The lifecycle name__v field value from which to retrieve entry criteria. This is retrieved from the Retrieve User Action request above.

Example

In this request, we'll retrieve the entry criteria for the "Start Approval" workflow.

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval/entry_requirements

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "properties": [
    {
      "name": "dueDate",
      "description": "Approval Due Date",
      "type": [
        "Date"
      ],
      "required": true,
      "editable": true,
      "scope": "WorkflowActivation"
    },
    {
      "name": "Approver",
      "description": "Approver",
      "type": [
        "ObjectReference"
      ],
      "objectTypeReferenced": {
        "name": "User",
        "label": "User"
      },
      "required": true,
      "editable": true,
      "repeating": true,
      "scope": "WorkflowActivation"
    }
  ]
}

Details

The response above shows two entry criteria to start the approval workflow on this document: dueDate and Approver.

You must assign an Approval Due Date and users/groups to the Approver role on the document when initiating the user action.
Unlike the response from the next example, the Scope for these fields is set to WorkflowActivation ("scope": "WorkflowActivation").
This scope means that you can initiate the user action by including these entry criteria as name-value pairs with the request.

See the Initiate User Action section below for more information.

Example

In this request, we'll retrieve the entry criteria to change the state of a document from "Draft" to "Approved".

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions/approve/entry_requirements

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "properties": [
    {
      "name": "country__v",
      "description": "Country",
      "type": [
        "ObjectReference"
      ],
      "objectTypeReferenced": {
        "name": "country__v",
        "label": "Country",
        "url": "/api/v15.0/metadata/vobjects/country__v",
        "label_plural": "Countries"
      },
      "editable": true,
      "repeating": true,
      "scope": "Document",
      "records": "/api/v15.0/vobjects/country__v"
    }
  ]
}

Details

The response above shows one entry criteria to change the state of this document from "Draft" to "Approved": country__v.

You must assign a value to the Country document field before initiating the user action.
Unlike the response from the previous example, the Scope for this field is set to Document ("scope": "Document").
This scope means that you must first update this field on the document before initiating the user action.

See the Initiate User Action section below for more information.

The response may include the following metadata elements describing the properties for which values need to be specified:

Property	Description
`name`	The entry criteria name (used in the API). This value must be specified when starting the user action.
`description`	The entry criteria name (used in the UI).
`type`	The entry criteria data type. This value can be one of `String`, `Number`, `Date`, `Boolean`, `Picklist`, or `ObjectReference`.
`objectTypeReferenced`	When `type` is `ObjectReference`, this is the object being reference. For example: `User`, `Product`, `Country`, etc.
`required`	Boolean value indicating whether or not the entry criteria must be specified when initiating a user action.
`editable`	Boolean value indicating whether or not the value can be edited by the user.
`repeating`	Boolean value indicating whether or not the entry criteria can have multiple values.
`minValue`	Indicates the minimum character length for the value.
`maxValue`	Indicates the maximum character length for the value.
`values`	When `type` is `Picklist`, this provides a list of possible values that can be used.
`currentSetting`	When a value has already been set, this shows the value.
`scope`	Indicates where the property is defined. This value can be one of `Document`, `Binder`, `WorkflowActivation`, `EmailFragment`, `ControlledCopy`, or `CreatePresentation`.

History

Since v6

Initiate User Action

Once you've identified the entry criteria, you can initiate the user action.

Request

Documents: Send PUT to /api/{version}/objects/documents/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{LIFECYCLE_ACTION}
Binders: Send PUT to /api/{version}/objects/binders/{ID}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{LIFECYCLE_ACTION}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "dueDate=2015-12-25" \
-d "Approver=user:12021,user:12022,group:10030003" \
https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval

This request is initiating a workflow activation user action on the document. We're initiating the "Start Approval" workflow.

Recall from the discussion in the previous section that the two entry criteria are to assign a values to the dueDate and Approver fields.
The entry criteria Scope is set to WorkflowActivation ("scope": "WorkflowActivation"), meaning the values can be included as a name-value pairs with the request.
Format the dueDate value as shown above. To assign users and/or groups to the Approver role, include a comma-separated list of user and group id field values.

On submitting this request, Vault will evaluate whether all the entry criteria have been met and, if so, initiate the user action.

Response

{
  "responseStatus": "SUCCESS",
  "id": 222,
  "workflow_id__v": "115"
}

Details

On SUCCESS, Vault returns the document id field value of the document on which the user action has been initiated and the workflow workflow_id__v field value of the workflow. This document ("id": 222) is now in the "Start Approval" workflow ("workflow_id__v": "115"). On FAILURE, Vault returns an error type and message describing the reason for the error. The user action will not be initiated until all errors have been corrected.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions/approve

This request is initiating a state change user action on the document. We're changing the state from "Draft" to "Approved".

Recall from the discussion in the previous section that the only entry criteria is to assign a value to the document's country__v field.
The entry criteria Scope is set to Document ("scope": "Document"), meaning the country field value cannot be included as a name-value pair with the request.
Instead, before submitting this request, we used a separate Update Document request to update the country field on the document. This fulfilled the entry criteria.
Therefore, we do not need to specify the input format (there is no input requirement) and the request can be submitted as shown in this example.

Response

{
  "responseStatus": "SUCCESS",
  "id": 222
}

Details

On SUCCESS, Vault returns the document id field value of the document on which the user action has been initiated. This document ("id": 222) was previously version 0.1 (Draft State). It is now version 1.0 (Approved/Steady State). On FAILURE, Vault returns an error type and message describing the reason for the error. The user action will not be initiated until all errors have been corrected.

History

Since v6

Bulk Document State Change

Currently, you can only begin a Read & Understood workflow using this functionality. For each bulk action, you may only select a single workflow that Vault will start for all selected and valid documents.

Request

Documents: Send PUT to /api/{version}/objects/documents/lifecycle_actions/{lifecycle_action_name}
Binders: Send PUT to /api/{version}/objects/binders/lifecycle_actions/{lifecycle_action_name}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{lifecycle_action_name} - The user action name__v field value.

Input

Field Name	Description
`docIDs`	Include a comma-separated list of document or binder IDs, major and minor version numbers, as shown below.
`lifecycle`	Include the name of the document or binder lifecycle.
`state`	Include the name of the state to which the documents or binders will be changed.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIDs=222:0:1,223:0:1,224:0:1,225:0:1" \
-d "lifecycle=general_lifecycle__vs" \
-d "state=approved__vs" \
https://myvault.veevavault.com/api/v15.0/objects/documents/lifecycle_actions/approve__c

In this example:

The input file format is set to accept name-value pairs.
The documents and versions are specified. We're changing the state of version 0.1 of document IDs 222, 223, 224, and 225.
The lifecycle is specified. These documents are assigned to the general_lifecycle__vs.
The state is specified. We're changing the state of all four documents to approved.

Response

{
  "responseStatus": "SUCCESS"
}

History

Since v12

Lifecycle Role Assignment Rules

For both standard and custom roles, you can define a subset of users who are allowed in the role and define users that Vault automatically assigns to the role at document creation or when a workflow starts. You can also override the allowed users and default users settings based on standard object-type document fields like Country, Product, Study, etc.

Vault Help Resources

Learn about Lifecycles & Workflows
Learn about Defining Allowed & Default Users for Roles
Learn about Users & Groups
Learn about Fields & Objects

Note the following limitations:

The API can only be used with active lifecycles and roles.
The maximum number of roles that can be created or updated per request is 50,000.
The lifecycle role default rule cannot be set when creating override rules.
A role cannot be assigned more users or groups to default roles than allowed on the role.
The default owner__v role cannot be edited.

Retrieve Lifecycle Role Assignment Rules (Default & Override)

Request

Send GET to api/{version}/configuration/role_assignment_rule

Headers

Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Parameters

This endpoint alone will retrieve a list of all lifecycle role assignment rules (default & override) from all roles in all lifecycles in your vault.

To filter the results by lifecycle or role, add one or both of the following parameters to the request endpoint:

lifecycle__v={lifecycle_name} - Include the name of the lifecycle from which to retrieve information. For example: lifecycle__v=general_lifecycle__vs
role__v={role_name} - Include the name of the role from which to retrieve information. For example: role__v=editor__c

For example, to retrieve the lifecycle role assignment rules (default & override) from:

All roles in a specific lifecycle, use api/{version}/configuration/role_assignment_rule?lifecycle__v={lifecycle_name}
A specific role in all lifecycles, use api/{version}/configuration/role_assignment_rule?role__v={role_name}
A specific role in a specific lifecycle, use api/{version}/configuration/role_assignment_rule?lifecycle__v={lifecycle_name}&role__v={role_name}

The response will include:

The default role assignments.
The override role assignments when an override condition (when configured on the role) is met.
The override conditions (when configured on the role).

You can also filter the results by one or more override conditions. This can be included with the filters above or used on its own to retrieve the information from all roles in all lifecycles in which the conditions have been configured.

For example, to retrieve lifecycle role override rules when the product "CholeCap" and country "United States" are assigned to a document:

Use the system-managed object record id field values: api/{version}/configuration/role_assignment_rule?product__v=0PR0011001&country__v=0CR0022002
Or, use the object record name__v field values (via object__v.name__v lookup): api/{version}/configuration/role_assignment_rule?product__v.name__v=CholeCap&country__v.name__v=United States

The response will exclude the default role assignments and only return the override conditions and role assignments when the override condition is met.

Example

Retrieve lifecycle role assignment rules from a specific role (editor__c) in a specific lifecycle (general_lifecycle__vs):

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__vs&role__v=editor__c

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "lifecycle__v": "general_lifecycle__vs",
            "role__v": "editor__c",
            "allowed_users__v": [
                "ally@veevapharm.com",
                "beth@veevapharm.com",
                "cruz@veevapharm.com",
                "dave@veevapharm.com"
            ],
            "allowed_groups__v": [
                "global_products_team__c",
                "vault_products_team__c",
                "vault_doc_management__c"
            ],
            "allowed_default_users__v": [
                "ally@veevapharm.com"
            ],
            "allowed_default_groups__v": [
                "global_products_team__c"
            ]
        },
        {
            "lifecycle__v": "general_lifecycle__vs",
            "role__v": "editor__c",
            "product__v.name__v": "CholeCap",
            "country__v.name__v": "United States",
            "product__v": "0PR0011001",
            "country__v": "0CR0022002",
            "allowed_users__v": [
                "etta@veevapharm.com",
                "finn@veevapharm.com",
                "greg@veevapharm.com",
                "hope@veevapharm.com"                
            ],
            "allowed_groups__v": [
                "cholecap_us_docs_group__c",
                "cholecap_us_research_group__c",
                "cholecap_us_compliance_group__c",
                "cholecap_us_product_management_group__c"
            ],
            "allowed_default_users__v": [
                "etta@veevapharm.com"
            ],
            "allowed_default_groups__v": [
                "cholecap_us_docs_group__c"
            ]
        }
    ]
}

Details

In the example response above, the editor__c role in the general_lifecycle__vs lifecycle is configured with the following role assignment rules:

Default Rule

When a document is assigned this lifecycle, the following users and groups are automatically assigned to the editor__c role:

allowed_default_users__v - The user ally@veevapharm.com is automatically assigned to the role.
allowed_users__v - The users beth@veevapharm.com, cruz@veevapharm.com, and dave@veevapharm.com can be (optionally) assigned to the role at any time during the lifecycle.
allowed_default_groups__v - The group global_products_team__c is automatically assigned to the role.
allowed_groups__v - The groups vault_products_team__c and vault_doc_management__c can be (optionally) assigned to the role at any time during the lifecycle.

Override Conditions

This lifecycle role has been configured with two override conditions which state: If both the product "CholeCap" and country "United States" are assigned to a document, do not apply the default rule, but instead apply the override rule.

The API returns both the system-managed object record id and the user-defined object record name__v (via the object__v.name__v lookup) field values which define the override conditions:

"product__v.name__v": "CholeCap" - The product object record name.
"country__v.name__v": "United States" - The country object record name.
"product__v": "0PR0011001" - The product object record ID.
"country__v": "0CR0022002" - The country object record ID.

Override Rule

When both the product "CholeCap" and country "United States" are assigned (at any time) to a document in this lifecycle, the following (alternate) users and groups are automatically assigned to the editor__c role:

allowed_default_users__v - The user etta@veevapharm.com is automatically assigned to the role.
allowed_users__v - The users finn@veevapharm.com, greg@veevapharm.com, and hope@veevapharm.com can be (optionally) assigned to the role during its lifecycle.
allowed_default_groups__v - The group cholecap_us_docs_group__c is automatically assigned to the role.
allowed_groups__v - The groups cholecap_us_research_group__c, cholecap_us_compliance_group__c, and cholecap_us_product_management_group__c can be (optionally) assigned to the role during its lifecycle.

Note: If the lifecycle role has not been configured with an override rule, the response will only display the default rule.

Errors

On FAILURE, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Create Override Rules

Request

Send POST to api/{version}/configuration/role_assignment_rule

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Input

Before submitting this request, prepare a JSON or CSV input file with the following information:

The name__v field values of the lifecycle and role to which the override rule is being added.
The id or name__v field values of the object records which define the override condition.
The user_name__v field values of the allowed and default users who will be assigned to the role when the override condition is met.
The name__v field values of the allowed and default groups who will be assigned to the role when the override condition is met.

Note the following scope and limitations:

This request can only be used to specify the override rules (conditions, users, and groups). It cannot be used to configure the default rules.
The input may include override rules for multiple lifecycles and roles.
Each role may be configured with multiple override rules.

Example CSV & JSON Input Files

Create an override rule on the editor__c role of the general_lifecycle__vs with the following override conditions, users, and groups:

`lifecycle__v`	`role__v`	`product__v.name__v`	`country__v.name__v`	`allowed_users__v`	`allowed_groups__v`	`allowed_default_users__v`	`allowed_default_groups__v`
`general_lifecycle__vs`	`editor__c`	CholeCap	United States	"etta@veevapharm.com,finn@veevapharm.com,greg@veevapharm.com,hope@veevapharm.com"	"`cholecap_us_docs_group__c`,`cholecap_us_research_group__c`,`cholecap_us_compliance_group__c`,`cholecap_us_product_management_group__c`"	etta@veevapharm.com	`cholecap_us_docs_group__c`

[
{
    "lifecycle__v": "general_lifecycle__vs",
    "role__v": "editor__c",
    "product__v.name__v": "CholeCap",
    "country__v.name__v": "United States",
    "allowed_users__v": [
        "etta@veevapharm.com",
        "finn@veevapharm.com",
        "greg@veevapharm.com",
        "hope@veevapharm.com"                
    ],
    "allowed_groups__v": [
        "cholecap_us_docs_group__c",
        "cholecap_us_research_group__c",
        "cholecap_us_compliance_group__c",
        "cholecap_us_product_management_group__c"
    ],
    "allowed_default_users__v": [
        "etta@veevapharm.com"
    ],
    "allowed_default_groups__v": [
        "cholecap_us_docs_group__c"
    ]
}
]

To understand how and where these users and groups are being assigned, refer to the Details section of the previous request.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
--data-binary @"C:\Vault\Override Rules\create-lifecycle-role-override-rules.json" \
https://myvault.veevavault.com/api/v15.0/configuration/role_assignment_rule

In this example:

The input file format is set to JSON.
The response format is not set and will default to JSON.
The path/name of the JSON input file is specified.

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        }
    ]
}

Details

For each override rule specified in the input, the response includes a SUCCESS or FAILURE message.

Errors

On FAILURE, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Update Override Rules

Request

Send PUT to api/{version}/configuration/role_assignment_rule

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Input

Before submitting this request, prepare a JSON or CSV input file. See the Create Override Rules request above for details.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Override Rules\update-lifecycle-role-override-rules.csv" \
https://myvault.veevavault.com/api/v15.0/configuration/role_assignment_rule

Details

For each override rule specified in the input, the response includes a SUCCESS or FAILURE message.

Errors

On FAILURE, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Delete Override Rules

Request

Send DELETE to api/{version}/configuration/role_assignment_rule

Headers

Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Parameters

This endpoint alone will retrieve a list of all lifecycle role assignment rules (default & override) from all roles in all lifecycles in your vault.

Parameters

You must add the following parameters to the request endpoint:

lifecycle__v={lifecycle_name} - Include the name of the lifecycle from which to delete override rules. For example: lifecycle__v=general_lifecycle__vs
role__v={role_name} - Include the name of the role from which to delete override rules. For example: role__v=editor__c

This will delete ALL override rules configured on the specified lifecycle role.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__vs&role__v=editor__c

Response

{
  "responseStatus": "SUCCESS",
  "data": {
    "rules_deleted": 2
  }
}

Details

The response above shows that two separate override rules were deleted from the lifecycle role.

If you'd rather delete only one of the override rules, you can include an additional parameter to define the specific override rule to be deleted. This is described in the next example:

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__vs&role__v=editor__c&product__v.name__v=CholeCap

For this request, assume the following:

There are two separate override rules configured on the editor__c role in the general_lifecycle__vs lifecycle.
The first override rule defines the users and groups assigned to the role when the product "CholeCap" is assigned to the document.
The second override rule defines the users and groups assigned to the role when the product "Nyaxa" is assigned to the document.
We only want to delete the first override rule.

When specifying the object records that define the override condition, you can use either the object record id value (e.g., product__v=0PR0011001) or name__v value (e.g., product__v.name__v=CholeCap via object__v.name__v lookup).

Response

{
  "responseStatus": "SUCCESS",
  "data": {
    "rules_deleted": 1
  }
}

Details

The response above shows that one override rule was deleted from the lifecycle role.

Errors

On FAILURE, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Lifecycle Role Assignment Rule Errors

On FAILURE, the response includes an error type and message describing the error.

Error Type	Error Message	Comments
`INSUFFICIENT_ACCESS`	Insufficient privileges to perform the action : permission [{PERMISSION}] is expected.	The logged-in API user does not have sufficient privileges to create the configuration data. The error message includes the name of the required permission.
`METHOD_NOT_SUPPORTED`	Requested method [{METHOD}] not supported.	Use the appropriate HTTP method: `GET`, `POST`, `PUT`, `DELETE`.
`OPERATION_NOT_ALLOWED`	Cannot create rule for role [{LIFECYCLE}.{ROLE}] : max rules exceeds [50000].	There is a maximum of 50,000 rules that can be created per role with this request.
`OPERATION_NOT_ALLOWED`	Multiple default users: can only define one default user for role [{LIFECYCLE}.{ROLE}].	If you specify multiple user IDs in the input for a default user role on a lifecycle which does not allow multiple users, this error is returned. The error message includes the lifecycle and role generating the error. Only one user ID may be assigned to the role.
`OPERATION_NOT_ALLOWED`	Cannot set group to default : default groups not allowed for role [{LIFECYCLE}.{ROLE}].	If you specify a group ID in the input for a default group role which does not allow default groups, this error is returned. The error message includes the lifecycle and role generating the error. You cannot assign a group ID to the default role on this lifecycle.
`OPERATION_NOT_ALLOWED`	Role is not modifiable : cannot modify override rules for role [{LIFECYCLE}.{ROLE}].	If you specify a role in the input which cannot be edited, this error is returned. The error message includes the lifecycle and role generating the error. You cannot create override rules for this role on this lifecycle.
`INVALID_DATA`	Duplicate rule: rule [{FIELD_1}={VALUE_1},{FIELD_2}={VALUE_2}], etc.] exists in the input more than once.	If the input contains duplicate field values, only the first instance is processed. The remaining duplicate fields are ignored.
`INVALID_DATA`	Duplicate rule: rule [{FIELD_1}={VALUE_1},{FIELD_2}={VALUE_2}], etc.] already exists in the database.	If the input contains a rule which is already configured on the specified lifecycle in Vault, this error is returned.
`INVALID_DATA`	Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : no value expected since parent [{PARENT_OBJECT}] is not specified.	Child objects are allowed to be in a condition only when the parent object is already in a condition.
`INVALID_DATA`	Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : child record of [{PARENT_OBJECT}.{ID}] is expected.	The child object record must be validated as an actual child of the selected parent. If validation fails, this error is returned.
`INVALID_DATA`	Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : value does not resolve to a valid lifecycle or role.	Vault performs a check of all lifecycle and role values included in the input. If a value does not resolve to a valid lifecycle or role, this error is returned. The error message includes the name of the lifecycle or role and the invalid value entered in the input. When creating override rules for a specific lifecycle and/or specific role, make sure the lifecycle value (e.g., `general_lifecycle__vs` and/or role value (e.g., `editor__c`) exists in your vault and is entered correctly in the input.
`INVALID_DATA`	Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : object record ID does not resolve to a valid object [{OBJECT_RECORD}].	Vault performs a check of all object record IDs included as a condition in the input (e.g., `product__v=00P2889114`). If a value does not resolve to a valid object record ID, this error is returned. The error message includes the name of object record and invalid value entered in the input. When creating override rules for documents assigned a specific object record (e.g., product, country, study, etc.), you must enter the value of the object record ID (not the object record name). Make sure the object record value exists in your vault and is entered correctly in the input. Note that the object record does not need to be active.
`INVALID_DATA`	Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : object record ID does not resolve to a unique valid object [{OBJECT_RECORD}].	If the condition is used with a lookup (e.g., `"product__v.name__v": "CholeCap"`) and there are multiple object records in the input with the same object record ID, this error is returned. The exception to this rule is that as long as the name is unique within its parent, there can be duplicate records.
`INVALID_DATA`	Invalid values [{VALUE_1},{VALUE_2}] specified for parameter [user_list] : values do not resolve to a valid active [user].	User values in the input are validated. Each username must resolve to a valid active user in the current vault application. Duplicate users in the input are ignored. The error message includes a comma-delimited list of all users who were identified as invalid.
`INVALID_DATA`	Invalid values [{VALUE_1},{VALUE_2}] specified for parameter [group_list] : values do not resolve to a valid active [group].	Group values in the input are validated. Each group must resolve to a valid active group in the current vault application. Duplicate groups in the input are ignored. The error message includes a comma-delimited list of all groups which were identified as invalid.

Object Record User Actions

The API supports retrieval and initiation of user actions on Vault object records.

Retrieve Object Record user Actions

Retrieve all available user actions that can be initiated on a specific object record.

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/actions

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{object_name} - The object name__v field value.
{object_record_id} - The object record id field value.

Retrieve Localized Strings

When available, you can retrieve localized (translated) strings for the label field by adding loc=true to the request endpoint.

For example: /api/{version}/vobjects/{object_name}/{object_record_id}/actions?loc=true

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/vobjects/product__v/0PR0771/actions

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "type": "workflow",
      "name": "start_approval__v",
      "label": "Start Approval"
    },
    {
      "type": "state_change",
      "name": "change_state_to_inactive__c",
      "label": "Change State to Inactive"
    }    
  ]
}

Details

On SUCCESS, the response lists all available user actions that can be initiated on the specified object record.

type - The type of user action. This can be workflow or state_change.
name - The user action name. This is the lifecycle_action_name parameter used in the two requests below.
label - The user action label as seen in the UI.

When localized strings are requested (loc=true), the response includes an additional localized_data field containing translated fields and field values on each object field for which localized strings have been configured. This data is only available at the object and field level and only if localized strings have been configured.

Errors

On FAILURE, the response displays an error type and message describing the error.

Error Type	Error Message	Description
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	The logged-in API user must be assigned the appropriate privileges.
`METHOD_NOT_SUPPORTED`	The requested method {METHOD} is not supported.	Use the HTTP GET method for this request.
`MALFORMED_URL`	The resource {RESOURCE} does not exist.	The specified `object_name` or `object_record_id` could not be found in your vault.

History

Since v14

Retrieve User Action Details

Once you've retrieved the available user actions, use this request to retrieve the details for a specific user action.

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/actions/{lifecycle_action_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

object_name - The object name__v field value.
object_record_id - The object record id field value from which to retrieve user actions.
lifecycle_action_name - The name of the user action to be initiated. This is obtained from the Retrieve User Actions request above.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/vobjects/product__v/0PR0771/actions/start_approval__v

In this example, we're retrieving the requirements to initiate a "Start Approval" workflow on the product object record.

Response

{
  "responseStatus": "SUCCESS",
  "data": [
      {
        "name":"start_review__v",
        "label":"Start Approval Workflow",
        "type": "workflow", 
        "controls": [                
          {
            "label": "Instructions",
            "type": "instructions",
            "instructions": "Please specify the users and dates for this workflow.",
            "prompts": []
          },
          {
            "label": "Participant",
            "type": "participant",
            "prompts": 
              [
                {
                  "name": "approvers__c",
                  "label": "Approvers"
                }
              ]                    
          },
          {
            "label": "Date",
            "type": "date",
            "prompts": 
              [
                {
                  "name": "due_date__c",
                  "label": "Due Date"
                }
              ]                     
          },
          {
            "label": "Fields",
            "type": "field",
            "prompts": 
              [
                {
                  "name": "product__v.generic_name__vs",
                  "label": "Generic Name",
                  "required": true,
                  "mutli_value": false,
                  "current_value": 
                    [
                      "0PR0771"
                    ]
                },
                {
                  "name": "product__v.internal_name__vs",
                  "label": "Internal Name",
                  "required": false,
                  "mutli_value": false,
                  "current_value": 
                    [
                      "0PR0771"
                    ]
                },
                {
                  "name": "product__v.compound_id__vs",
                  "label": "Compound Id",
                  "required": false,
                  "mutli_value": false,
                  "current_value": 
                    [
                      "0PR0771"
                    ]
                }
            ]                 
        }                
    ]
}

Details

On SUCCESS, the response lists the fields that must be configured with values in order to initiate the user action. These are based on the controls configured in the workflow start step.

The following types of controls may be returned:

instructions - Contains static instruction text regarding workflow initiation.
participant - Used to specify users who will be part of the workflow.
date - Date selections for the workflow, such as due date.
field - All object fields requiring values.

For each control, the following data may be returned:

label - Label for the control.
type - Type of control (instructions, participants, date, or fields).
prompts - The input prompts (if any are configured) which would accept values when initiating the workflow.

Prompts of type field accept values per the metadata specified for the field in the object metadata.

The example above specifies that when initiating the workflow, the input must include (or may optionally include) the following:

approvers__c - The workflow approvers must be set.
due_date__c - The workflow due date must be set.
product__v.generic_name__vs - The generic name product field is required and must be set.
product__v.internal_name__vs - The internal name product field is not required, but can be (optionally) set.
product__v.compound_id__vs - The compound ID product field is not required, but can be (optionally) set.

See the section below for an example request with input.

Errors

On FAILURE, the response displays an error type and message describing the error.

Error Type	Error Message	Description
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	The logged-in API user must be assigned the appropriate privileges.
`METHOD_NOT_SUPPORTED`	The requested method {METHOD} is not supported.	Use the HTTP GET method for this request.
`MALFORMED_URL`	The resource {RESOURCE} does not exist.	The specified `object_name`, `object_record_id`, or `lifecycle_action_name` could not be found in your vault.

History

Since v14

Initiate Object Record User Action

Once you've identified the details, use this request to initiate the user action on a specific object record.

Request

Send POST to /api/{version}/vobjects/{object_name}/{object_record_id}/actions/{lifecycle_action_name}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

Input

Include name-value pairs for all required and optional fields returned in the Retrieve User Actions Entry Criteria request above.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "approvers__c": "user:23423,user:5455,group:23421" \
-d "due_date__c": "2015-12-12T01:22:17.000Z" \
-d "product__v.generic_name__vs": "chopredol" \
-d "product__v.internal_name__vs": "CholeCap" \
-d "product__v.compound_id__vs": "CC-127" \
https://myvault.veevavault.com/api/v14.0/vobjects/product__v/0PR0771/actions/start_approval__v

In this example:

The Content-Type header is set to accept name-value pairs in the input.
We've specified the users and a group who will be part of the approval workflow.
We've specified the due date of the workflow in UTC.
We've configured the required product generic name field with a value.
We've configured the optional product internal name and compound ID fields with values.

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, the specified user action is initiated on the object record.

Errors

On FAILURE, the response displays an error type and message describing the error.

Error Type	Error Message	Description
`INSUFFICIENT_ACCESS`	User does not have sufficient privileges to perform the action.	The logged-in API user must be assigned the appropriate privileges.
`METHOD_NOT_SUPPORTED`	The requested method {METHOD} is not supported.	Use the HTTP POST method for this request.
`MALFORMED_URL`	The resource {RESOURCE} does not exist.	The specified `object_name`, `object_record_id`, or `lifecycle_action_name` could not be found in your vault.
`PARAMETER_REQUIRED`	Missing required parameters [{PARAMETER_1, PARAMETER_2, PARAMETER_3}].	The input is missing one or more of the required parameters. The response includes the names of the missing parameters. Check the entry criteria response to ensure you have included all required fields.
`INVALID_DATA`	Invalid value [{VALUE}] specified for parameter [{PARAMETER}].	The input includes an invalid value for one of the parameters. The response includes the specific reason for the error.
`OPERATION_NOT_ALLOWED`	Cannot initiate action: [{ACTION}] is already running.	The specified `lifecycle_action_name` has already been initiated on the object record.

History

Since v14

Workflows

A workflow is a series of steps configured in Vault to align with specific business processes. The different types of steps offer a flexible way to organize a wide variety of processes for a document, including assigning tasks to users, sending notifications and changing document status. User task steps in workflows also serve various purposes. User tasks can allow users to enter comments, choose verdicts (approve, deny, etc.), update required fields, or provide electronic signatures.

Workflows are specific to a lifecycle, meaning that a single workflow cannot apply to multiple lifecycles. A single document can only be in one workflow at a time.

Learn about Lifecycles & Workflows in Vault Help.

Workflow Metadata

Retrieve all workflow metadata fields in a vault by sending GET to /api/{version}/metadata/objects/workflows. See request details below.

The tables below describe workflow metadata in API v15.0. These mirror the data retrieved from workflow reports in the Vault UI.

Workflow Fields

The Vault workflows object includes the following fields:

Field Name	Description	Field Type	Comments
`workflow_id__v`	Workflow ID	ID	The workflow `id` field value of the workflow instance.
`workflow_name__v`	Workflow Name	Picklist	The name of the workflow (Review, Approval, etc.).
`workflow_type__v`	Workflow Type	Picklist	The type of workflow (Standard, Read & Understood, etc.).
`workflow_status__v`	Workflow Status	Picklist	The status of the workflow (Active, Completed, Canceled, etc.).
`workflow_document_id__v`	Workflow Document ID	ID	The document `id` field value of the document associated with the workflow.
`workflow_document_major_version_number__v`	Workflow Document Major Version	Number	The major version number of the document associated with the workflow.
`workflow_document_minor_version_number__v`	Workflow Document Minor Version	Number	The minor version number of the document associated with the workflow.
`workflow_initiator__v`	Workflow Initiator	ObjectReference	The user `id` field value of the person who initiated the workflow.
`workflow_startDate__v`	Workflow Start Date	DateTime	The date and time when the workflow was started.
`workflow_dueDate__v`	Workflow Due Date	Date	When the workflow due date is defined, this displays the date.
`workflow_completionDate__v`	Workflow Completion Date	DateTime	If the workflow has been completed, this displays the date and time.
`workflow_cancelationDate__v`	Workflow Cancelation Date	DateTime	If the workflow has been canceled, this displays the date and time.
`workflow_duration__v`	Workflow Duration	Number	The number of days (including partial days) the workflow was active before it was completed or canceled.
`workflow_process_instance_group__v`	Workflow Process Instance Group	String
`task_id__v`	Task ID	ID	The task `id` field value of the task instance.
`task_name__v`	Task Name	Picklist	The name of the task (Approve, Review and Provide Annotations, etc.).
`task_status__v`	Task Status	Picklist	The current status of the task (Available, Assigned, Completed, etc.).
`task_verdict__v`	Task Verdict	Picklist	The outcome or verdict of the task (Approved, Not Approved, etc.).
`task_capacity__v`	Task Capacity	Picklist
`task_assignee__v`	Task Assignee	ObjectReference	The user `id` field value of the person who was assigned the task.
`task_assignee_name__v`	Task Assignee Name	String	The name of the person who was assigned the task.
`task_delegate__v`	Task Delegate	ObjectReference	If the task was delegated to another user, this displays the user `id` field value of the delegated user.
`task_queueGroup__v`	Task Queue Group	Picklist	If the task was sent to a group, this displays the group name (Reviewer, Approver, etc.).
`task_creationDate__v`	Task Creation Date	DateTime	The date and time when the task was created.
`task_assignmentDate__v`	Task Assignment Date	DateTime	The date and time when the task was assigned.
`task_dueDate__v`	Due Date	Date	If the task due date is defined, this displays the date.
`task_completionDate__v`	Task Completion Date	DateTime	If the task has been completed, this displays the date and time.
`task_cancelationDate__v`	Task Cancelation Date	DateTime	If the task has been canceled, this displays the date and time.
`task_duration__v`	Task Duration	Number	The number of days (including partial days) the task was active before it was completed or canceled.
`task_comment__v`	Task Comment	String	Any comments included with the task.

Workflow Metadata Fields (Properties)

The following information may be included with each field:

Metadata Field	Description
`name`	The name of the field (`workflow_name__v`, `task_name__v`, etc.).
`type`	The type of field (ID, String, Picklist, ObjectReference, etc.).
`object`	When the field `type` is `ObjectReference`, this shows the name of the object being referenced.
`multivalue`	Indicates (true/false) if the field can have multiple values.
`length`	When the field `type` is `String`, this shows the maximum character length which can be used.
`values`	When the field `type` is `Picklist`, this lists the available values.

Retrieve Workflow Metadata

Request

Send GET to /api/{version}/metadata/objects/workflows

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/metadata/objects/workflows

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "properties": [
    {
      "name": "workflow_document_id__v",
      "type": "id",
      "multivalue": false
    },
    {
      "name": "workflow_initiator_name__v",
      "type": "String",
      "length": 255,
      "multivalue": false
    },
    {
      "name": "workflow_process_version__v",
      "type": "Number",
      "multivalue": false
    },
    {
      "name": "workflow_id__v",
      "type": "id",
      "multivalue": false
    },
    {
      "name": "workflow_name__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Approval"
        },
        {
          "label": "Distribute"
        },
        {
          "label": "MLR Approval"
        },
        {
          "label": "MLR Review"
        },
        ...
      ]
    },
    {
      "name": "workflow_initiator__v",
      "type": "ObjectReference",
      "object": "User",
      "multivalue": false
    },
    {
      "name": "workflow_status__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Active"
        },
        {
          "label": "Cancelled"
        },
        {
          "label": "Complete"
        },
        {
          "label": "Error"
        }
      ]
    },
    {
      "name": "workflow_startDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "workflow_completionDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "workflow_cancelationDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "workflow_duration__v",
      "type": "Number",
      "multivalue": false
    },
    {
      "name": "workflow_dueDate__v",
      "type": "Date",
      "multivalue": false
    },
    {
      "name": "workflow_type__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Read and Understood"
        },
        {
          "label": "Standard"
        }
      ]
    },
    {
      "name": "workflow_document_major_version_number__v",
      "type": "Number",
      "multivalue": false
    },
    {
      "name": "workflow_document_minor_version_number__v",
      "type": "Number",
      "multivalue": false
    },
    {
      "name": "workflow_process_instance_group__v",
      "type": "String",
      "length": 255,
      "multivalue": false
    },
    {
      "name": "task_assignee_name__v",
      "type": "String",
      "length": 255,
      "multivalue": false
    },
    {
      "name": "task_id__v",
      "type": "id",
      "multivalue": false
    },
    {
      "name": "task_name__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Approve"
        },
        {
          "label": "Assess Outcome"
        },
        {
          "label": "Legal Approval"
        },
        {
          "label": "Medical Approval"
        },
        {
          "label": "Regulatory Approval"
        },
        {
          "label": "Legal Review"
        },
        {
          "label": "Medical Review"
        },
        {
          "label": "Regulatory Review"
        },
        ...
      ]
    },
    {
      "name": "task_assignee__v",
      "type": "ObjectReference",
      "object": "User",
      "multivalue": false
    },
    {
      "name": "task_delegate__v",
      "type": "ObjectReference",
      "object": "User",
      "multivalue": false
    },
    {
      "name": "task_queueGroup__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Approver"
        },
        {
          "label": "Coordinator"
        },
        {
          "label": "Reviewer"
        },
        ...
      ]
    },
    {
      "name": "task_status__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Created"
        },
        {
          "label": "Available"
        },
        {
          "label": "Cancelled"
        },
        {
          "label": "Assigned"
        },
        {
          "label": "Completed"
        }
      ]
    },
    {
      "name": "task_verdict__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Approved"
        },
        {
          "label": "Not Approved"
        },
        {
          "label": "Approved for Production"
        },
        {
          "label": "Approved with Changes"
        },
        ...
      ]
    },
    {
      "name": "task_capacity__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false
    },
    {
      "name": "task_creationDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "task_assignmentDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "task_completionDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "task_cancelationDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "task_duration__v",
      "type": "Number",
      "multivalue": false
    },
    {
      "name": "task_dueDate__v",
      "type": "Date",
      "multivalue": false
    },
    {
      "name": "task_comment__v",
      "type": "String",
      "length": 4000,
      "multivalue": false
    }
  ]
}

Expected Document Lists

Expected Document Lists (EDLs) help you to measure the completeness of projects. Learn about EDLs in Vault Help. Note that if your vault is configured to set milestone values by EDL item, the following EDL endpoints may trigger updates to a document’s milestone fields. Learn about milestones in Vault Help.

Create EDLs

Create a new Expected Document List.

Request

Send POST to /api/{version}/vobjects/study__v/{study_id}/actions/etmfcreateedl

Headers

Content-Type: application/json or text/csv
Accept: application/json (default) or text/csv

URL Parameters

{study_id} - The ID of the study.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \ 
--data-binary @"C:\Vault\Objects\edl.csv" \
https://myvault.veevavault.com/api/V16.0/vobjects/study__v/00S07710/actions/etmfcreateedl

Response

{
  "responseStatus": "SUCCESS",
  "URL": "https://myvault.veevavault.com/api/v15.0/services/jobs/1201",
  "job_id": 1201
}

Apply EDL Template to a Milestone

Apply an EDL template to a Milestone object record.

Request

Send POST to /api/{version}/vobjects/milestone__v/{milestone_id}/actions/etmfcreateedl

Headers

Content-Type: application/x-www-form-urlencoded
Accept: application/json (default)

URL Parameters

{milestone_id} - The ID of the milestone.

Inputs

Field Name	Description
`edl_id`	The ID of the EDL template to apply to this milestone.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \ 
-d "edl_id=0EL000000000105" \
https://myvault.veevavault.com/api/V16.0/vobjects/milestone__v/0M0007710/actions/etmfcreateedl

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 9901,
  "url": "/api/v16.0/services/jobs/9901"
}

Errors

Error Type	Error Message	Comments
`INVALID_DATA`	Required String parameter '`edl_id`' is not present	You must include the `edl_id` of the EDL template to apply to the milestone.
`INVALID_DATA`	Parameter `milestone__v.study__v` cannot be blank	The referenced milestone record must have a study if the EDL template matches on study.
`INVALID_DATA`	Parameter `edl__v.id__v` must be an active record	The EDL record is Inactive, and only active records can apply as templates.
`INVALID_DATA`	Parameter `edl__v.id__v` must be a template record	The EDL record must be a template, meaning the Is Template? field on the EDL is set to Yes.
`INVALID_DATA`	Parameter `edl__v.id__v` cannot have a parent template	The EDL record cannot have a parent template, so it must be at the root level.
`INVALID_DATA`	Level of parameter `edl__v.id__v` must match level of milestone	The EDL record is not at the same level as the milestone (study, country, or site).
`MALFORMED_URL`	The resource [`edl_id`] does not exist	The EDL record provided does not match any existing records.

Retrieve Root Nodes

Retrieves all root EDL nodes and node metadata. Learn more EDL hierarchies in Vault Help.

Request

Send GET to /api/{version}/composites/trees/edl_hierarchy__v

Headers

Content-Type: application/json (default) or text/csv
Accept: application/json (default) or application/xml or text/csv

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v16.0/composites/trees/edl_hierarchy__v

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "id": "0000000000000JIT",
      "order__v": 1,
      "ref_type__v": "edl__v",
      "ref_name__v": "NewEDL",
      "url": "/vobjects/edl__v/0EL000000001901",
      "ref_id__v": "0EL000000001901",
      "parent_id__v": null
    }
  ]
}

Errors

Error Type	Error Message	Comments
INVALID_DATA	The resource [edl_hierarchy__v] does not exist	EDL hierarchies are not enabled in your vault. Learn more in Vault Help.

Retrieve a Node’s Children

Given an EDL node ID, retrieves immediate children (not grandchildren) of that node. Learn more EDL hierarchies in Vault Help.

Request

Send GET to /api/{version}/composites/trees/edl_hierarchy__v/{parent_node_id}/children

Headers

Content-Type: application/json (default) or text/csv
Accept: application/json (default) or application/xml or text/csv

Parameters

parent_node_id - The ID of a parent node in the hierarchy.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v16.0/composites/trees/edl_hierarchy__v/0000000000000JIT/children

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "id": "0000000000000JLL",
      "order__v": 1,
      "ref_type__v": "edl_item__v",
      "ref_name__v": "NewEDL Child",
      "url": "/vobjects/edl_item__v/0EI000000009401",
      "ref_id__v": "0EI000000009401",
      "parent_id__v": "0000000000000JIT"
    }
  ]
}

Update Node Order

Given an EDL parent node, update the order of it’s children.

Request

Send PUT to /api/{version}/composites/trees/edl_hierarchy__v/{parent_node_id}/children

Headers

Content-Type: application/json (default) or text/csv
Accept: application/json (default) or application/xml or text/csv

Parameters

parent_node_id - The ID of a parent node in the hierarchy.

Body

Expressed as a JSON or a CSV.

id - The ID of the child node to update.
order__v - The new order for the node in the hierarchy, such as “1”, “2”, etc.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-d '{"id": "0000000000000JLL","order__v": "2"}'
https://myvault.veevavault.com/api/v16.0/composites/trees/edl_hierarchy__v/0000000000000JIT/children

Response

{
  "responseStatus": "SUCCESS"
}

Security Policies

Vault security policies you to create and manage password policies for users. These settings control password requirements, expiration period, reuse policy, security question policy, and delegated authentication via Salesforce.com. Security policies apply across all vaults in a multi-vault domain.

Learn about Authentication & Security in Vault Help.

Retrieve All Security Policies

Request

Send GET to /api/{version}/objects/securitypolicies

Headers

Response Accept - JSON application/json (default) or XML application/xml

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/securitypolicies

Response

{
  "responseStatus": "SUCCESS",
  "security_policies__v": [
    {
      "name__v": "821",
      "label__v": "Basic",
      "value__v": "https://myvault.veevavault.com/api/v15.0/objects/securitypolicies/821"
    },
    {
      "name__v": "958",
      "label__v": "Default",
      "value__v": "https://myvault.veevavault.com/api/v15.0/objects/securitypolicies/958"
    },
    {
      "name__v": "957",
      "label__v": "High Security",
      "value__v": "https://myvault.veevavault.com/api/v15.0/objects/securitypolicies/957"
    },
    {
      "name__v": "1909",
      "label__v": "Single Sign-On OKTA",
      "value__v": "https://myvault.veevavault.com/api/v15.0/objects/securitypolicies/1909"
    }
  ]
}

Details

The response lists all security_policies__v in the vault:

Field Name	Description
`name__v`	System-managed value automatically assigned to security policies. This is typically a numeric value.
`label__v`	Security policy label displayed in Admin UI.
`value__v`	URL value to retrieve security policy metadata.

History

Since v3

Retrieve Security Policy

Request

Send GET to /api/{version}/objects/securitypolicies/{security_policy_name}

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

{security_policy_name} - Security policy name__v field value (retrieved from previous request). This is typically a numeric value.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/securitypolicies/958

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "security_policy__v": {
    "policy_details__v": {
      "name__v": "958",
      "label__v": "Default",
      "is_active__v": true
    },
    "policy_security_settings__v": {
      "authentication_type__v": {
        "name__v": "Password",
        "label__v": "Password"
      },
      "passwords_require_number__v": true,
      "passwords_require_uppercase_letter__v": true,
      "min_password_length__v": 8,
      "password_expiration__v": 0,
      "password_history_reuse__v": 0
    }
  }
}

Details

Depending on the configuration, the response may include some or all of the following security_policy__v fields:

Field Name	Description
`policy_details__v`	Policy Details
`name__v`	Security Policy ID
`label__v`	Security Policy Label
`description__v`	Security Policy Description
`is_active__v`	Active (true/false)
`policy_security_settings__v`	Policy Security Settings
`authentication_type__v`	Authentication Type
`name__v`	Authentication Type Name
`label__v`	Authentication Type Label
`passwords_require_number__v`	Passwords Require Number (true/false)
`passwords_require_uppercase_letter__v`	Passwords Require Upper-Case Letter (true/false)
`passwords_require_nonalpha_char__v`	Passwords Require Non-Alphanumeric Character (true/false)
`min_password_length__v`	Minimum Password Length (7, 8, 10, or 12 characters)
`password_expiration__v`	Password Expiration (90 days, 180 days, or no expiration)
`password_history_reuse__v`	Password History Reuse (prevent reuse of the last 3 passwords, 5 passwords, or no limitations)
`require_question_on_password_reset__v`	Require Security Question on Password Reset (true/false)
`allow_delegated_auth_sfdc__v`	Allow Salesforce Delegated Authentication (true/false)
`sfdc_org_id__v`	Salesforce Org ID

Note: Boolean fields are only returned when the value is set to true.

Configuration Migration

Export Package

Request

Send POST to /api/{version}/services/package

Headers

Content-Type: application/x-www-form-urlencoded

Body

packageName - The name of the Outbound Package you would like to export.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "packageName=PKG-0001" \
--output "myVPK.vpk" \
https://myvault.veevavault.com/api/v16.0/services/package

Response

The response body is the binary .vpk file.

Errors

Type	Message	Comments
`NO_RESULT`	Fail to create VPK for package [`PKG-####`]	There are no components, the package is empty.
`OBJECT_NOT_FOUND`	Cannot find outbound package by name [`PKG-####`]	The specifed package does not exist; double check the `packageName`.

Import Package

Request

Send PUT to /api/{version}/services/package

Headers

Content-Type: multipart/form-data

Accept: application/json (default) or application/xml

Body

file - The .vpk file. See Export Package above.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-F "file=my_package.vpk" \ 
https://myvault.veevavault.com/api/v16.0/services/package

Response

{
  "responseStatus": "SUCCESS",
  "vaultPackage": {
    "id": "0PI000000000101",
    "name": "PKG-0071",
    "status": "Active",
    "components": [
      {
        "id": "0VP000000000101",
        "name": "Object.perf_stats__v",
        "status": "Verified",
        "step": "00010"
      },
      {
        "id": "0VP000000000102",
        "name": "Object.mlr_meeting__c",
        "status": "Verified",
        "step": "00020"
      },
      {
        "id": "0VP000000000103",
        "name": "Object.pm_contact__v",
        "status": "Verified",
        "step": "00030"
      },
      {
        "id": "0VP000000000104",
        "name": "Object.pm_application__v",
        "status": "Verified",
        "step": "00040"
      },
      {
        "id": "0VP000000000105",
        "name": "Object.binder_metadata__v",
        "status": "Verified",
        "step": "00050"
      },
      {
        "id": "0VP000000000106",
        "name": "Object.application_role__v",
        "status": "Verified",
        "step": "00060"
      },
     ],
    "renamed": false
  }
}

Errors

Type	Message	Comments
`INVALID_DATA`	File is not a valid VPK format.	The uploaded file is not a valid VPK format; you may need to export the package again.
`OPERATION_NOT_ALLOWED`	Inbound packages hasn't been enabled or you don't have enough permission for the operation.	Inbound Packages must be enabled in the target vault, and you must have view permission on all components in the package.

Deploy Package

Request

Send POST to /api/{version}/vobject/vault_package__v/{package_id}/actions/deploy

Headers

Content-Type: multipart/form-data

Accept: application/json (default) or application/xml

Parameters

package_id - The id field value of the vault_package__v object record used for deploy. See Import Package above.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
https://myvault.veevavault.com/api/v16.0/vobject/vault_package__v/0PI000000000101/actions/deploy

Response

On SUCCESS, the response includes the following information:

URL - The URL to retrieve the current status of the export job.
job_id - The Job ID value is used to retrieve the status and results of the request.

{
  "responseStatus": "SUCCESS",
  "url": "/api/v16.0/services/jobs/23301",
  "job_id": 23301
}

Errors

Type	Message	Comments
`MALFORMED_URL`	The resource [`package_id]` does not exist	The specified package ID does not exist. Check your value for `package_id`.
`OPERATION_NOT_ALLOWED`	Inbound packages hasn't been enabled or you don't have enough permission for the operation.	Inbound Packages must be enabled in the target vault, and you must have the deploy permission.
`INSUFFICIENT_ACCESS`	User does not have permission to deploy components of type [`component type`].	For each component type included in the package, the requesting user must have create and edit permissions on those configuration objects.

Retrieve Package Deploy Results

After Vault has finished processing the deploy job, use this request to retrieve the results of the completed deploy.

Request

Send GET to /api/{version}/vobject/vault_package__v/{package_id}/actions/deploy/results

Headers

Accept: application/json (default) or application/xml

Parameters

package_id - The id field value of the vault_package__v object record used for deploy. See Deploy Package above.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v16.0/vobject/vault_package__v/0PI000000000101/actions/deploy/results

Response

{
  "responseStatus": "SUCCESS",
  "responseDetails": {
    "warnings": 0,
    "total_components": 13,
    "deployed_components": 1,
    "skipped_components": 0,
    "error_components": 1,
    "deployment_status__v": "error__v",
    "deployment_log": [
      {
        "filename": "PKG-0071-23301.log",
        "url": "https://myvault.veevavault.com/ui/proxy/getAttachmentsVersionFile/vault_package__v/0PI000000000101/35/1",
        "created_date__v": "2016-09-28 23:54:56.536"
      }
    ]
  },
  "package_components": [
    {
      "external_id__v": null,
      "component_type__v": "Object",
      "checksum__v": "7b66e3aeb8b4482864a920ce17f2d61a",
      "step__v": "00010",
      "name__v": "Object.perf_stats__v",
      "id": "0VP000000000101",
      "component_name__v": "perf_stats__v",
      "deployment_status__v": "deployed__v"
    },
    {
      "external_id__v": null,
      "component_type__v": "Object",
      "checksum__v": "dc08134292ddd224c8f252a6f85753eb",
      "step__v": "00020",
      "name__v": "Object.mlr_meeting__c",
      "id": "0VP000000000102",
      "component_name__v": "mlr_meeting__c",
      "deployment_status__v": "error__v"
    },
    {
      "external_id__v": null,
      "component_type__v": "Object",
      "checksum__v": "9a7a9e6fbb4689fc1d171eb80c2add4b",
      "step__v": "00030",
      "name__v": "Object.pm_contact__v",
      "id": "0VP000000000103",
      "component_name__v": "pm_contact__v",
      "deployment_status__v": "verified__v"
    }
  ]
}

Learn more about the possible response values for deployment_status__v in Vault Help.

Errors

Type	Message	Comments
`MALFORMED_URL`	The specified resource cannot be found	The specified package ID does not exist. Check your value for `package_id`.

Jobs

Retrieve Job Status

After submitting a request, you can query vault to determine the status of the request. To do this, you must have a valid job_id for a job previously requested through the API.

Example Jobs:

Binder Export
Import Submission
Export Submission
Create EDL
Deploy Package
Deep Copy Object Record
Cascade Delete Object Record

Request

Send GET to /api/{version}/services/jobs/{job_id}

Headers

Accept: application/json (default) or application/xml

URL Parameters

{job_id} - The ID of the job, returned from the original job request.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/services/jobs/1201

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "OK",
  "data": {
    "id": 1201,
    "status": "SUCCESS",
    "method": "POST",
    "links": [
      {
        "rel": "self",
        "href": "/api/v15.0/services/jobs/1601",
        "method": "GET",
        "accept": "application/json"
      },
      {
        "rel": "artifacts",
        "href": "/api/v15.0/objects/binders/actions/export/1201/results",
        "method": "GET",
        "accept": "application/json"
      }
    ],
    "created_by": 44533,
    "created_date": "2016-04-20T18:14:42.000Z",
    "run_start_date": "2016-04-20T18:14:43.000Z",
    "run_end_date": "2016-04-20T18:14:44.000Z"
  }
}

Details

On SUCCESS, the response includes the following information:

Metadata Field	Description
`id`	The `job_id` field value for the job.
`status`	The status of the job.
`method`	The HTTP method used in the request.
`links`	Once the job is finished, use these endpoints and methods to retrieve other job details.
`created_by`	The `id` field value of the user who started the job.
`created_date`	The date and time when the job was requested.
`run_start_date`	The date and time when the export job started.
`run_end_date`	The date and time when the export job finished.

Errors

The Vault response to every API call includes a field called responseStatus. Possible values are:

SUCCESS - The API request has been successfully processed.
FAILURE - The API request could not be processed because of API user error.
EXCEPTION - The API request could not be processed because of API system error.

For a responseStatus other than SUCCESS, API users can inspect another field in the response called errors. Each error includes the following fields:

type

The specific type of error, e.g., INVALID_DATA, PARAMETER_REQUIRED, etc.
These values are not subject to change for a given version of the API, even when newer versions of the API are available.
API applications need to use the error type value in combination with the responseStatus value for error handling.
In other words, the type and responseStatus values ARE contractual parts for error handling.

message

The message accompanying each error type, e.g., Missing required parameter [{field_name}].
When available, the error message includes the specific reason, e.g., {FIELD_NAME} for the error.
Other error messages provide more general reasons for each error.
These values are subject to change for a given version of the API and ARE NOT contractual parts for error handling.

For a responseStatus of SUCCESS, the errors field is either omitted or has a null value.

Example: 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, the 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
`EXCEEDS_FILE_MAX_SIZE`	The size of uploaded file exceeds the maximum size allowed (4 GB).
`API_LIMIT_EXCEEDED`	Vault limits the number of API calls that can be made every 5 minutes and every 24 hours. When either of these limits are reached, this error message is returned and no further calls will be processed until the next 5 minute or 24 hour period begins. Learn more about API Limits above.
`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.