Vault API Reference

API Reference (v17.1 Beta)

This is the documentation for Vault API v17.1 Beta.

For general information on Vault, refer to Vault Help.

Authentication

Authenticate your account using one of the methods outlined below. The response returns a session ID that you can use in subsequent API calls. Session IDs time out after a period of inactivity. The period varies by vault, but is 20 minutes by default.

Basic

Authenticate your account using your Vault user name and password.

POST /api/{version}/auth

Headers

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

Body Parameters

Name Description
Username Your Vault user name assigned by your administrator.
Password Your Vault password associated with your assigned vault user name.

Request

$ curl -X POST https://{vault_domain_name}/api/{versions}/auth \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/xml" \ 
-d "username={username}&password={password}"

Response

{
  "responseStatus": "SUCCESS",
  "sessionId": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 1776,
      "name": "PromoMats",
      "url": "https://promomats-veevapharm.veevavault.com/api"
    },
    {
      "id": 1777,
      "name": "eTMF",
      "url": "https://etmf-veevapharm.veevavault.com/api"
    },
    {
      "id": 1778,
      "name": "MedComms",
      "url": "https://medcomms-veevapharm.veevavault.com/api"
    },
    {
      "id": 1779,
      "name": "QualityDocs",
      "url": "https://qualitydocs-veevapharm.veevavault.com/api"
    }
  ],
  "vaultId": 1776
}

Salesforce Delegated Requests

If your vault uses Salesforce Delegated Authentication, you can call the Vault API using your Salesforce session token. Learn about Salesforce Delegated Authentication in Vault Help.

The following prerequisites apply: * A valid Vault user must exist with a Security Policy enabled for Salesforce.com Delegated Authentication. * The trusted 18-character Salesforce.com Org ID must be provided. * A user with matching username must exist in Salesforce.com Org ID.

Headers

Name Description
Authorization Your Salesforce session token.
X-Auth-Host Salesforce URL which Vault can use to validate the Salesforce session token.
X-Auth-Provider Set to sfdc to indicate that Salesforce is the authorization provider.

Query String Parameters

You can also use query string parameters instead of the headers outlined above.

Name Description
auth Your salesforce session token.
ext_url Salesforce URL which Vault can use to validate the Salesforce session token.
ext_ns Set to sfdc to indicate that Salesforce is the authorization provider.

Request

$ curl -X GET \
-H "Authorization: {SFDC_SESSION_TOKEN}" \
-H "X-Auth-Provider: sfdc" \
-H "X-Auth-Host: https://{my_sfdc_domain}" \
https://myveevavault.com/api/{version}/{Vault_Endpoint}

Domain Information

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

GET /api/{version}/objects/domain

Headers

Name Description
Content-Type application/json
Accept application/json (default) or application/xml

Request

$ 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": "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": "7000",
        "vault_name__v": "RIM Submissions",
        "vault_status__v": "Active",
        "vault_application__v": "RIM"
      }
    ]
  }
}

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

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.

Retrieve Document Fields

Retrieve All Document Fields

Retrieve all standard and custom document fields and field properties.

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

Headers

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

Request

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

Response

    {
      "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"
    }

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

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.

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

Headers

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

Body Parameters

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

Request

$ 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

    {
      "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"
    }    

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

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

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

Headers

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

Request

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

Response

{
    "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"
        },
    ],
    "lock": "https://etmf-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/lock"
}

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

Retrieve Document Type

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

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

Headers

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

URI Path Parameters

Name Description
{type} The document type. See Retrieve Document Types.

Request

$ 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"
    }
  ],
  "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": "Convention Item",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/convention_item__vs"
    }
  ]
}

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

Retrieve Document Subtype

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

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

Headers

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

URI Path Parameters

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

Request

$ 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

{
  "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": "Print",
      "value": "https://promomats-veevapharm.vaultdev.com/api/v15.0/metadata/objects/documents/types/promotional_piece__vs/subtypes/advertisement__vs/classifications/print__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": "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"
    },
  ],
  "templates": [
    {
      "label": "ANSM Submission",
      "name": "ansm_submission__vs",
      "kind": "binder",
      "definedIn": "promotional_piece__vs",
      "definedInType": "type"
    }
  ],
  "availableLifecycles": [
    {
      "name": "promotional_piece__vs",
      "label": "Promotional Piece"
    }
  ]
}    

Retrieve Document Classification

Retrieve all metadata from a document classification.

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

Headers

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

URI Path Parameters

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

Request

$ 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

{
  "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": "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"
    },
  ],
  "templates": [
    {
      "label": "ANSM Submission",
      "name": "ansm_submission__vs",
      "kind": "binder",
      "definedIn": "promotional_piece__vs",
      "definedInType": "type"
    }
  ],
  "availableLifecycles": [
    {
      "name": "promotional_piece__vs",
      "label": "Promotional Piece"
    }
  ]
}  

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.

GET /api/{version}/objects/documents

Headers

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

Query String Parameters

You can optionally include one of the following parameters to filter the results:

Name Description
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 Retrieveßs all documents which you have recently accessed.
scope=contents Searches only within the document content.
scope=all Searches both within the document content and searchable document fields.
versionscope=all Retrieves all document versions, rather than only the latest version.
search={keyword} Search for documents based on a {keyword} in searchable document fields.
limit,sort, start See VQL Query Syntax & Structure for more information.

Request

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

Response

{
  "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": []
        },
        "viewer__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"
        ]
      }
    },
    ...  

Response Details

On SUCCESS, Vault lists all documents and binders along with their fields and field values. If binder__v = true, the object is a binder. The document metadata returned will vary based on your vault configuration. Crosslink documents are supported.

Retrieve Document

Retrieve all metadata from a document.

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Request

$ 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"
        }
    ]
}

Response Details

The boolean field binder__v indicates whether the returned document is a regular document (true) or a binder (false). The absence of this field means it is a document. Binder node structures are not listed as part of the response; they must be determined through the Binder API.

The boolean field crosslink__v indicates whether the returned document is a regular document (ture) or a CrossLink document (false).

Retrieve Document Versions

Retrieve all versions of a document.

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Request

$ 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"
    }
}

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

Retrieve Document Version

Retrieve all fields and values configured on a document version.

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

Headers

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

URI Path Parameters

Name Description
{document_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.

Request

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

Response

{
    "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"
        }
    ]
}

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

Download Document File

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Query String Parameters

Name Description
lockDocument Optional: Set to true to Check Out this document before retrieval.

Request

$ 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 Details

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.

Download Document Version File

Download the file of a specific document version.

GET /api/{version}/objects/documents/{document_id}/versions/{major_version}/{minor_version}/file

Headers

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

URI Path Parameters

Name Description
{document_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.

Query String Parameters

Name Description
lockDocument Optional: Set to true to Check Out this document before retrieval.

Request

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

Download Document Version Thumbnail File

Download the thumbnail image file of a specific document version.

GET /api/{version}/objects/documents/{document_id}/versions/{major_version}/{minor_version}/thumbnail

Headers

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

URI Path Parameters

Name Description
{document_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.

Request

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

Create Documents

These all involve creating one document at a time. Many of these actions are also available in the Bulk Documents API.

Create Document from Uploaded File

Most documents in your vault are created from uploaded source files, such as a file from your computer. 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.

POST /api/{version}/objects/documents

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml

Body Parameters

The following standard fields are required in all vaults. Others may be required depending on your configuration. If a required field is not included, Vault returns a PARAMETER_REQUIRED error with the name of the missing field. You may optionally include any other editable document field.

Name Description
file The filepath of the source document. The maximum allowed file size is 4GB.
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.

Request

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

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.

POST /api/{version}/objects/documents

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml

Body Parameters

When creating a new document, the following standard fields are required in all vaults. Admin may set other standard or custom document fields to required in your vault. You may include other optional, editable document fields and values.

Name Description
fromTemplate The name of the template to apply.
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.

Request

$ 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

Response

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

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.

POST /api/{version}/objects/documents

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml

Body Parameters (Required)

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

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.

Request

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

POST /api/{version}/objects/documents

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or 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.

Body Parameters (Required)

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

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

Body Parameters (Required)

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.

Request (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

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

POST /api/{version}/objects/documents

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml

Body Parameters (Required)

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

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.

Body Parameters (Optional)

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

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

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.

Request

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

Update Documents

Update Document

Update editable field values on the latest version of a document. See also Update Document Version below and Bulk Documents API.

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

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

Response

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

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:

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Body Parameters

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

Query String Parameters

Name Description
reclassify Set to true. Without this, a standard document update action is performed.

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.

Request

$ 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
}

Update Document Version

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

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

Headers

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

URI Path Parameters

Name Description
{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.

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

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.

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

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml

URI Path Parameters

Name Description
{document_id} The document id field value.

Query String Parameters

To create a new draft version from the existing document in the vault, include createDraft=latestContent in the input as shown in Request 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 Request 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.

Name Description
suppressRendition Set to true. With either of the above options, you may suppress automatic generation of the viewable rendition. This is shown in Request 3 below.

Request 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

Request 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

Request 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 Document

Delete all versions of a document, including all source files and viewable renditions. See also Delete Document Version.

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 document id field value.

Request

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

Response

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

Delete Document Version

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/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}

Headers

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

URI Path Parameters

Name Description
{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.

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
}

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.

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

Headers

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

URI Path Parameters

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

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

Request

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

Document Locks

A document "lock" is analogous to "checking out a document" but without the file attached in the response for download. To check out and retrieve the document file, use the Retrieve Document File request described below.

Learn about Document Checkout (Locks) in Vault Help.

Retrieve Document Lock Metadata

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

Headers

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

Request

$ 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 check out and retrieve the document file, use the Retrieve Document File request described below.

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

Headers

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

URI Path Parameters

Name Description
{document_id}

Request

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

Retrieve Document Lock

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Request

$ 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"
    }
}

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

Delete Document Lock

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

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Request

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

Document Renditions

Learn about Document Renditions in Vault Help.

Retrieve Document Renditions

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Request

$ 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"
    }
}

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

Retrieve Document Version Renditions

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

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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"
    }
}

Download Document Rendition File

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

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

Query String Parameters

Name Description
steadyState Set to true to download a rendition (file) from the latest steady state version (1.0, 2.0, etc.) of a document.

Request

$ 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"
}

Response 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

GET /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/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.
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.

Request

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

Upload Document Rendition

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

Headers

Name Description
Content-Type application/json or multipart/form-data
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.

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.

Request

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

Upload Document Version Rendition

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

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml

URI Path Parameters

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

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.

Request

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

Replace Document Rendition

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

Headers

Name Description
Content-Type multipart/form-data
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.

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.

Request

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

Replace Document Version Rendition

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

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml

URI Path Parameters

Name Description
{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.

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.

Request

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

Delete Document Rendition

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.

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 Document Version Rendition

DELETE /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/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.
{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.

Request

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

Document Attachments

Learn about Document Attachments in Vault Help.

Determine if a Document has Attachments

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Request

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

List Document Attachments

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Request

$ 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"
                }
            ]
        }
    ]
}

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

Retrieve Document Attachment Metadata

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.
{attachment_id} The attachment id field value.

Request

$ 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"
                }
            ]
        }
    ]
}

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

List Document Attachment Versions

Request

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.
{attachment_id} The attachment id field value.

Request

$ 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"
        }
    ]
}

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

Retrieve Document Attachment Version Metadata

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

Headers

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

URI Path Parameters

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

Request

$ 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"
        }
    ]
}

Download Document Attachment File

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.
{attachment_id} The attachment id field value.

Request

$ 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"

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

Download Document Attachment Version File

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

Headers

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

URI Path Parameters

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

Request

$ 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"

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

Download All Document Attachment Files

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Request

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

Delete Document Attachment

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.
{attachment_id} The attachment id field value.

Request

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

Delete Document Attachment Version

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

Headers

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

URI Path Parameters

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

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

Add Document Attachment

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

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml

URI Path Parameters

Name Description
{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.

Request

$ 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
    }
}

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

Restore Document Attachment Version

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

Headers

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

URI Path Parameters

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

Query String Parameters

Name Description
restore The parameter restore must be set to true.

Request

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

Update Document Attachment Description

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.
{attachment_id} The attachment id field value.

Body Parameters

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

Request

$ 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"
}

Document Annotations

Learn about Document Annotations in Vault Help.

Retrieve Document Annotations

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

Headers

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

URI Path Parameters

Name Description
{document_id} The document id field value.

Request

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

Retrieve Document Version Annotations

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

Headers

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

URI Path Parameters

Name Description
{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.

Request

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

Upload Document Annotations

POST /api/{version}/objects/documents/{document_id}/annotationsoint

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or 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.

URI Path Parameters

Name Description
{document_id} The document id field value.

Request

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

Upload Document Version Annotations

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

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.

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml

URI Path Parameters

Name Description
{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.

Request

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

Document Relationships

Learn about Document Relationships in Vault Help.

Retrieve Document Type Relationships

Retrieve all relationships from a document type.

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

Headers

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

URI Path Parameters

Name Description
{type} The document type. See Retrieve Document Types.

Request

$ 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"
      }
    }
  ]
}

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

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

Headers

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

URI Path Parameters

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

Request

$ 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
}

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

Create Document Relationship

Create a new relationship on a document.

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

Headers

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

URI Path Parameters

Name Description
{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.

Body Parameters

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.

Request

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

Retrieve Document Relationship

Retrieve details of a specific document relationship.

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

Headers

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

URI Path Parameters

Name Description
{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.
{relationship_id} The relationship id field value. See Retrieve Document Relationships.

Request

$ 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
}

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

Delete Document Relationship

Delete a relationship from a document.

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

Headers

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

URI Path Parameters

Name Description
{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.
{relationship_id} The relationship id field value. See Retrieve Document Relationships.

Request

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

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.

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

Headers

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

Request

$ 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
    }
  ]
}

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

Retrieve Document Template Collection

Retrieve all document templates.

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

Headers

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

Request

$ 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
      }     
   ]
}

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

Retrieve Document Template Attributes

Retrieve the attributes from a document template.

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

Headers

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

URI Path Parameters

Name Description
{template_name} The document template name__v field value.

Request

$ 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
      }     
   ]
}

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

Download Document Template File

Download the file of a specific document template.

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

Headers

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

URI Path Parameters

Name Description
{template_name} The document template name__v field value.

Request

$ 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"

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

Create Document Template

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

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

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or 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.

Body Parameters

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

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.

Request

$ 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

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

Bulk Create Document Templates

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

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

Headers

Name Description
Content-Type application/json or text/csv
Accept application/json (default) or 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.

Body Parameters

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

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.

Request

$ 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."
            }
         ]
      }
   ]
}

Update Document Template

Update a document template to your vault.

See also: Bulk Update Document Templates below

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

Headers

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

URI Path Parameters

Name Description
{template_name} The document template name__v field value.

Body Parameters

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.

Request

$ 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,

Bulk Update Document Templates

Update from 1-500 document templates to your vault.

See also: Update [Single] Document Template above.

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

Headers

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

Body Parmeters

You can update the following fields on document templates:

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.

Request

$ 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."
            }
         ]
      }
   ]
}

Delete Document Template

Delete a document template from your vault.

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

Headers

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

URI Path Parameters

Name Description
{template_name} The document template name__v field value.

Request

$ 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"
}

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.

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

Headers

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

Body Parameters

Name Description
docIds 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
expiryDateOffset 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.
downloadOption 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.
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.
tokenGroup 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.

Request

$ 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]."
                }
            ]
        }
    ]
}

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

Bulk Documents API

Bulk Documents API Method API Endpoint Input Output Batch Size Available in API
Create Documents POST /api/{version}/objects/documents/batch CSV CSV, JSON 1-500 v9.0 or later
Update Documents PUT /api/{version}/objects/documents/batch CSV, Form Data CSV, JSON 1-1000 v9.0 or later
Delete Documents DELETE /api/{version}/objects/documents/batch CSV, JSON CSV, JSON 1-500 v13.0 or later
Add Document Versions POST /api/{version}/objects/documents/versions/batch CSV CSV, JSON 1-500 v10.0 or later
Delete Document Versions DELETE /api/{version}/objects/documents/versions/batch CSV, JSON CSV, JSON 1-500 v13.0 or later
Add Document Renditions POST /api/{version}/objects/documents/renditions/batch CSV CSV, JSON 1-500 v10.0 or later
Delete Document Renditions DELETE /api/{version}/objects/documents/renditions/batch CSV, JSON CSV, JSON 1-500 v13.0 or later

See request details in the Bulk Documents API article.
See input file requirements and examples in the Bulk Input Files article.

Bulk Document Roles API

Bulk Document Roles API Method API Endpoint Input Output Batch Size Available in API
Assign Users & Groups to Document Roles POST /api/{VERSION}/objects/documents/roles/batch CSV, Name-Value Pair CSV, JSON 1-1000 v9.0 or later
Remove Users & Groups from Document Roles DELETE /api/{VERSION}/objects/documents/roles/batch CSV, Name-Value Pair CSV, JSON 1-1000 v9.0 or later

See request details in the Bulk Document Roles API article.
See input file requirements and examples in the Bulk Input Files article.

Bulk Document Relationships API

Bulk Document Relationships API Method API Endpoint Input Output Batch Size Available in API
Create Document Relationships POST /api/{VERSION}/objects/documents/relationships/batch CSV, JSON CSV, JSON 1-1000 v15.0 or later
Delete Document Relationships DELETE /api/{VERSION}/objects/documents/relationships/batch CSV, JSON CSV, JSON 1-1000 v15.0 or later

See request details in the Bulk Document Relationships API article.
See input file requirements and examples in the Bulk Input Files article.

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.

GET /api/{version}/objects/documents

Headers

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

Request

$ 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",
        ...
      }
    }

Response 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

Retrieve all fields and values configured on a specific binder in you vault. By default, the response only includes the first level (root) of the binder structure. To retrieve all levels, use one of the depth parameters described below.

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

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.

Query String Parameters

Name Description
depth To retrieve all information in all levels of the binder, set this to all. By default, only one level is returned.

Request

$ 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"
        }
      }
    ]
  }
}

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

Retrieve All Binder Versions

Retrieve all versions of a binder.

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

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.

Request

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

Retrieve Binder Version

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

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

Headers

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

URI Path Parameters

Name Description
{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.

Reqauest

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

Create Binders

Create Binder

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

POST /api/{version}/objects/binders

Headers

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

Query String Parameters

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.

Name Description
async 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.

Request

$ 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
}

History

Since v1
v7+ - Supports asynchronous indexing.

Create Binder from Template

POST /api/{version}/objects/binders

Headers

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

Body Parameters

Name Description
fromTemplate 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.

Request

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.

Request (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
}

History

Since v5
v7+ - Supports asynchronous indexing.

Create Binder Version

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

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.

Request

$ 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
}

Update Binders

Update Binder

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

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.

Request

$ 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
}

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:

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.

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

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.

Body Parameters

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.

Request

$ 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
}

Update Binder Version

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

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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
}

Refresh Binder Auto-Filing

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

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

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.

Request

$ 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"
}

Delete Binders

Delete Binder

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

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.

Request

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

Response

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

Delete Binder Version

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

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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
}

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.

To export the latest version of a binder, POST /api/{version}/objects/binders/{binder_id}/actions/export

To export a specific version of a binder, POST /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/actions/export

Headers

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

URI Path Parameters

Name Description
{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.

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

Request

$ 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
}

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

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.

To export the latest version, POST /api/{version}/objects/binders/{binder_id}/actions/export

To export a specific version, POST /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/actions/export

Headers

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

URI Path Parameters

Name Description
{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.

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, GET /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.

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

GET /api/{version}/objects/binders/actions/export/{job_id}/results

Headers

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

URI Path Parameters

Name Description
{job_id} The id value of the requested export job. This is returned with the export binder requests above.

Request

$ 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
}

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

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

Binder Relationships

Learn about Binder Relationships in Vault Help.

Retrieve Binder Relationship

GET /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/relationships/{relationship_id}

Headers

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

URI Path Parameters

Name Description
{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.
{relationship_id} The binder relationship id field value.

Request

$ 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
}

Response 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

Create Binder Relationship

POST /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/relationships

Headers

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

URI Path Parameters

Name Description
{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.

Body Parameters

Name Description
target_doc_id__v Set the target_doc_id__v to the document id of the "target document" to which a relationship will be established with the binder.
relationship_type__v Set the relationship_type__v to the field value of one of the desired relationshipTypes from the "Documents Relationships Metadata" call.
target_major_version__v 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.
target_minor_version__v 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.

Request

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

Delete Binder Relationship

DELETE /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/relationships/{relationship_id}

Headers

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

URI Path Parameters

Name Description
{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.
{relationship_id} The binder relationship id field value.

Request

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

Binder Sections

Retrieve Binder Sections

Retrieve all sections (documents and subfolders) in a binder's top-level root node or sub-level node.

GET /api/{version}/objects/binders/{binder_id}/sections

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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"
        }
      }
    ]
  }
}

Request

$ 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"
        }
      }
    ]
  }
}

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

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.

GET /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/sections

Headers

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

URI Path Parameters

Name Description
{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.

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.

Request

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

Request

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

Create Binder Section

Create a new section in a binder.

POST /api/{version}/objects/binders/{binder_id}/sections

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.

Body Parameters

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.

Request

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

Update Binder Section

Update a section in a binder.

PUT /api/{version}/objects/binders/{binder_id}/sections/{node_id}

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.
{node_id} The binder node id of the section.

Body Parameters

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.

Request

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

Delete Binder Section

Delete a section from a binder.

DELETE /api/{version}/objects/binders/{binder_id}/sections/{node_id}

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.
{node_id} The binder node id field value.

Request

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

Binder Documents

Add Document to Binder

Add a document to a binder.

POST /api/{version}/objects/binders/{binder_id}/documents

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.

Body Parameters

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.

Request

$ 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"
}

Move Document in Binder

Move a document to a different position within a binder.

PUT /api/{version}/objects/binders/{binder_id}/documents/{node_id}

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.
{node_id} The binder node id field value.

Body Parameters

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.

Request

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

Remove Document from Binder

DELETE /api/{version}/objects/binders/{binder_id}/documents/{node_id}

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.
{node_id} The binder node id field value.

Request

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

Binder Templates

Learn about Binder Templates in Vault Help.

Retrieve Binder Template Metadata

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

GET /api/{version}/metadata/objects/binders/templates

Headers

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

Request

$ 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
    }
  ]
}

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

Retrieve Binder Template Node Metadata

Retrieve the metadata which defines the shape of binder template nodes in your vault.

GET /api/{version}/metadata/objects/binders/templates/bindernodes

Headers

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

Request

$ 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
    }
  ]
}

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

Retrieve Binder Template Collection

Retrieve the collection of all binder templates in your vault.

GET /api/{version}/objects/binders/templates

Headers

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

Request

$ 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"
      }
   ]
}

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

Retrieve Binder Template Attributes

Retrieve the attributes of a specific binder template in your vault.

GET /api/{version}/objects/binders/templates/{template_name}

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.
{template_name} The binder template name__v field value.

Request

$ 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"
      }
   ]
}

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

Retrieve Binder Template Node Attributes

Retrieve the attributes of each node (folder/section) of a specific binder template in your vault.

GET /api/{version}/objects/binders/templates/{template_name}/bindernodes

Headers

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

URI Path Parameters

Name Description
{template_name} The binder template name__v field value.

Request

$ 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"
        }
    ]
}

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

Create Binder Template

Create a new binder template in your vault.

See also: Bulk Create Binder Templates below.

POST /api/{version}/objects/binders/templates

Headers

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

Body Parameters

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

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.

Request

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

Bulk Create Binder Templates

Create from 1-500 new binder templates in your vault.

See also: Create (Single) Binder Template above.

POST /api/{version}/objects/binders/templates

Headers

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

Body Parameters

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

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.

Request

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

Create Binder Template Node

Create nodes in an existing binder template.

POST /api/{version}/objects/binders/templates/{template_name}/bindernodes

Headers

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

URI Path Parameters

Name Description
{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 parent_id__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.

Request

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

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.

PUT /api/{version}/objects/binders/templates

Headers

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

Body Parameters

You can update the following fields on binder templates:

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.

Request

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

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.

PUT /api/{version}/objects/binders/templates

Headers

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

Body Parameters

You can update the following fields on binder templates:

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.

Request

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

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.

PUT /api/{version}/objects/binders/templates/{template_name}/bindernodes

Headers

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

URI Path Parameters

Name Description
{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.

Request

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

Delete Binder Template

Delete an existing binder template from your vault.

DELETE /api/{version}/objects/binders/templates/{template_name}

Headers

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

URI Path Parameters

Name Description
{template_name} The binder template name__v field value.

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

Binding Rules

Learn about Version Binding in Vault Help.

Update Binding Rule

PUT /api/{version}/objects/binders/{binder_id}/binding_rule

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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
}

Update Binder Section Binding Rule

PUT /api/{version}/objects/binders/{binder_id}/sections/{node_id}/binding_rule

Headers

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

URI Path Parameters

Name Description
{binder_id} The binder id field value.
{node_id} The binder node 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.

Request

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

Update Binder Document Binding Rule

PUT /api/{version}/objects/binders/{binder_id}/documents/{node_id}/binding_rule

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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

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.

Retrieve Object Metadata

Retrieve all metadata configured on a standard or custom Vault Object.

GET /api/{version}/metadata/vobjects/{object_name}

Headers

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

URI Path Parameters

Name Description
{object_name} The object name__v field value (product__v, country__v, custom_object__c, etc.).

Query String Parameters

Name Description
loc To retrieve localized (translated) strings, include the parameter loc=true. See the next request below for details.

Request

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

Request

$ 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"
      }
    },
    ...     

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

Retrieve Object Field Metadata

GET /api/{version}/metadata/vobjects/{object_name}/fields/{object_field_name}

Headers

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

URI Path Parameters

Name Description
{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.).

Query String Parameters

Name Description
loc To retrieve localized (translated) strings, include the parameter loc=true. See the next request below for details.

Request

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

Request

$ 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
  }
}

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

Retrieve Object Collection

GET /api/{version}/metadata/vobjects

Headers

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

Query String Parameters

Name Description
loc To retrieve localized (translated) strings, include the parameter loc=true. See the next request below for details.

Request

$ 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"
      ]
    }
  ]
}

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

Request

$ 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"
        }
      }
    },
    ...

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

Retrieve Object Record Collection

Retrieve all records for a specific Vault Object.

GET /api/{version}/vobjects/{object_name}

Headers

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

URI Path Parameters

Name Description
{object_name} The object name__v field value (product__v, country__v, custom_object__c, etc.).

Body Parameters

Name Description
fields To specify fields to retrieve, include the parameter fields={FIELD_NAMES}. See the next request below for details.

Request

$ 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"
        }
    ]
}

Retrieve Object Record

Retrieve metadata configured on a specific object record in your vault.

GET /api/{version}/vobjects/{object_name}/{object_record_id}

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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
      ]
    }
  }
}

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

See Update Object Record Roles in the Bulk Input files article.

History

Since v8
v11+ - Supports Custom Sharing Rules. Response includes manually_assigned_sharing_roles (when configured).

Create Object Record

See Bulk Object Records API.

Update Object Record

See Bulk Object Records API.

Delete Object Record

Use Bulk Object Records API.

Cascade Delete Object Record

This asynchronous endpoint will delete a single parent object record and all related children and grandchildren.

POST /api/{version}/vobjects/{object_name}/{object_record_id}/actions/cascadedelete

Headers

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

URI Path Parameters

Name Description
{object_name} The name of the object to delete.
{object_record_id} The ID of the specific object record to delete.

Request

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

GET /api/{version}/vobjects/cascadedelete/results/{object_name}/{job_status}/{job_id}

Headers

Name Description
Accept text/csv (default)

URI Path Parameters

Name Description
{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.

Request

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

POST /api/{version}/vobjects/{object_name}/{object_record_ID}/actions/deepcopy

Headers

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

URI Path Parameters

Name Description
{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.

Request

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

GET /api/{version}/vobjects/deepcopy/results/{object_name}/{job_status}/{job_id}

Headers

Name Description
Accept text/csv (default)

URI Path Parameters

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

Request

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

GET /api/{version}/objects/deletions/vobjects/{object_name}

Headers

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

URI Path Parameters

Name Description
{object_name} The object name__v field value (product__v, country__v, custom_object__c, etc.).

Body Parameters

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

Request

$ 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"
        },
        ...
    ]
}

Object Record Attachments

Determine if Attachments are Enabled on an Object

GET /api/{version}/metadata/vobjects/{object_name}

Headers

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

URI Path Parameters

Name Description
{object_name} The object name__v field value (product__v, country__v, custom_object__c, etc.).

Request

$ 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",
        ...
}

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

Retrieve Object Record Attachments

Retrieve a list of all attachments on a specific object record.

GET /api/{version}/vobjects/{object_name}/{object_record_id}/attachments

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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"
                }
            ]
        }
    ]
}

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

Retrieve Object Record Attachment Metadata

GET /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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"
                }
            ]
        }
    ]
}

Response 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 object record, the new attachment is not added.

Retrieve Object Record Attachment Versions

GET /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/versions

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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"
        }
    ]
}

Retrieve Object Record Attachment Version Metadata

GET /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/versions/{attachment_version}

Headers

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

URI Path Parameters

Name Description
{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.
{attachment_version} The attachment version__v field value.

Request

$ 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"
        }
    ]
}

Download Object Record Attachment File

GET /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/file

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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"

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

Download Object Record Attachment Version File

GET /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/versions/{attachment_version}/file

Headers

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

URI Path Parameters

Name Description
{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.
{attachment_version} The attachment version__v field value.

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions/1/file

Response 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"

Download All Object Record Attachment Files

GET /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/file

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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"

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

Create Object Record Attachment

POST /api/{version}/vobjects/{object_name}/{object_record_id}/attachments

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml

URI Path Parameters

Name Description
{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.

Request

$ 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
    }
}

Restore Object Record Attachment Version

POST /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/versions/{attachment_version}?restore=true

Headers

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

URI Path Parameters

Name Description
{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.
{attachment_version} The attachment version__v field value.

Request

$ 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
    }
}

Update Object Record Attachment Description

PUT /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}

Headers

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

URI Path Parameters

Name Description
{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.

Body Parameters

Name Description
description__v This is the only editable field. The maximum length is 1000 characters.

Request

$ 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"
}

Delete Object Record Attachment

DELETE /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571

Response

{
    "responseStatus": "SUCCESS"
}

Delete Object Record Attachment Version

DELETE /api/{version}/vobjects/{object_name}/{object_record_id}/attachments/{attachment_id}/versions/{attachment_version}

Headers

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

URI Path Parameters

Name Description
{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.
{attachment_version} The attachment version__v field value.

Request

$ 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"
}

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

GET /api/{version}/configuration/Objecttype

Headers

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

Request

$ 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 a Specific Object

GET /api/{version}/configuration/Objecttype.{object_name}.{object_type}

Headers

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

URI Path Parameters

Name Description
{object_name} The object name.
{object_type} Optional: The object type name. If omitted, all object types are included.

Request

$ 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. Note that if the object has a lifecycle, changing its type will reset its state to the initial state type.

POST /api/{version}/vobjects/{object_name}/actions/changetype

Headers

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

URI Path Parameters

Name Description
{object_name} The name of the object.

Body Parameters

Name Description
id The ID of the object record.
object_type__v The ID of the new object type.

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: application/json" \ 
--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"
            }
        }
    ]    
}

Retrieve Limits on Objects

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.

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:

GET /api/{version}/limits

Headers

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

Request

$ 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
    }
  ]
}

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

RIM Submissions

To use this API, you must have Vault's RIM Submissions suite of applications. Learn more about RIM Submissions in Vault Help.

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

POST /api/{version}/vobjects/submission__v/{submission_id}/actions/import

Headers

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

URI Path Parameters

Name Description
{submission_id} The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Body Parameters

Name Description
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. Learn more.

Request

$ 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

Response 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"
}

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

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.
  • Use the Retrieve Submission Import Status request above to make sure Vault has finished processing the import request.

GET /api/{version}/vobjects/submission__v/{submission_id}/actions/import/{job_id}/results

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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"
    }
  ]
}

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

Retrieve Submission Metadata Mapping

Retrieve the metadata mapping values of an eCTD submission package.

GET /api/{version}/vobjects/submission__v/{submission_id}/actions/ectdmapping

Headers

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

URI Path Parameters

Name Description
{submission_id} The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Request

$ 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"
    }
  ]
}

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

Update Submission Metadata Mapping

Update the mapping values of a submission.

PUT api/{version}/vobjects/submission__v/{submission_id}/actions/ectdmapping

Headers

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

URI Path Parameters

Name Description
{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
    }
}

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.

DELETE /api/{version}/vobjects/submission__v/{submission_id}/actions/import

Headers

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

URI Path Parameters

Name Description
{submission_id} The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Request

$ 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"
}

Cancel Submission

You can use this request on a submission object record that has a SubmissionsArchive status (archive_status__v) of:

Name Description
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, GET /api/{version}/vobjects/submission__v/{submission_id}. See Retrieve Object Record above.

POST /api/{version}/vobjects/submission__v/{submission_id}/actions/import?cancel=true

Headers

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

URI Path Parameters

Name Description
{submission_id} The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Query String Parameters

Name Description
cancel You must include cancel=true to the request endpoint.

Request

$ 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"
}

Export Submission

To export the latest version of a SubmissionsArchive binder:

POST api/{version}/objects/binders/{binder_id}/actions/export?submission={submission_id}

To export a specific version of a SubmissionsArchive binder:

POST /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/actions/export?submission={submission_id}

Headers

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

URI Path Parameters

Name Description
{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.

Request

$ 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
}

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

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.

To export the latest version of a submissions binder:

POST /api/{version}/objects/binders/{binder_id}/actions/export?submission={submission_id}

To export a specific version of a submissions binder:

POST /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/actions/export?submission={submission_id}

Headers

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

URI Path Parameters

Name Description
{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.

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

Request

$ 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
}

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

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.

To retrieve submission structure from the latest version of the SubmissionsArchive binder:

GET /api/{version}/vobjects/submission__v/{submission_id}/actions/viewer

Headers

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

URI Path Parameters

Name Description
{submission_id} The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Request

$ 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"