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, which varies by Vault. Learn more about session duration and management.

Every Vault API must include the following header:

Basic Auth Header

Name	Description
`Authorization`	{`sessionId`}

Alternatively, you can use Salesforce or OAuth2/OIDC Delegated Requests.

Basic

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

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

Authenticate your account using your Vault user name and password to obtain a Vault Session ID.

If the specified user cannot successfully authenticate to the given vaultDNS, the subdomain is considered invalid and this request instead generates a session for the user’s most relevant available Vault. A DNS is considered invalid for the given user if the user cannot access any Vaults in that subdomain, for example, if the user does not exist in that DNS or if all Vaults in that DNS are inactive. For this reason, it is best practice to inspect the response, compare the desired Vault ID with the list of returned Vault IDs, and confirm the DNS matches the expected login.

Vault limits the number of Authentication API calls based on the user name and the domain name used in the API call. To determine the Vault Authentication API burst limit for your Vault or the length of delay for a throttled response, check the response headers or the API Usage Logs.

POST https://{vaultDNS}/api/{version}/auth

Headers

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

URI Path Parameters

Name	Description
`vaultDNS`	The DNS of the Vault for which you want to generate a session. If the requesting user cannot successfully authenticate to this `vaultDNS`, this request generates a session for the user’s most relevant available Vault.
`version`	The Vault REST API version. Your authentication version does not need to match the version in subsequent calls. For example, you can authenticate with v17.3 and run your integrations with v20.1.

Body Parameters

Name	Description
`username`required	Your Vault user name assigned by your administrator.
`password`required	Your Vault password associated with your assigned Vault user name.
`vaultDNS`optional	The DNS of the Vault for which you want to generate a session. If specified, this optional `vaultDNS` body parameter overrides the value in the URI `vaultDNS`. If the requesting user cannot successfully authenticate to this `vaultDNS`, this request generates a session for the user’s most relevant available Vault. If this `vaultDNS` body parameter is omitted, this request instead generates a session for the domain specified in the URI `vaultDNS`.

Response Details

On SUCCESS, this request returns a valid sessionId for any Vault DNS where the user has access.

The Vault DNS for the returned session is calculated in the following order:

Generates a session for the DNS in the optional vaultDNS body parameter
- If this vaultDNS is invalid, generates a session for the user’s most relevant available Vault:
  1. Generates a session for the Vault where the user last logged in
  2. If the user has never logged in, or if the last logged-in Vault is inactive, generates a session for the oldest active Vault where that user is a member
  3. If the user is not a member of any active Vaults, the user cannot authenticate and the API returns FAILURE
If the optional vaultDNS body parameter is omitted, generates a session for the DNS specified in the vaultDNS URI parameter
- If this vaultDNS is invalid, generates a session for the user’s most relevant available Vault:
  1. Generates a session for the Vault where the user last logged in
  2. If the user has never logged in, or if the last logged-in Vault is inactive, generates a session for the oldest active Vault where that user is a member
  3. If the user is not a member of any active Vaults, the user cannot authenticate and the API returns FAILURE

An invalid DNS is any DNS which the specified user cannot access, for example, if the DNS does not exist, if the user does not exist in that DNS, or if all Vaults in that DNS are inactive.

It is best practice to inspect the response, compare the desired Vault ID with the list of returned vaultIds, and confirm the DNS matches the expected login.

This API only returns FAILURE if it is unable to return a valid sessionId for any Vault the user can access.

OAuth2 / OIDC

$ curl -X POST \
-H "Authorization: Bearer 1C29326C3DF" \
-H "Host: Bearer 1C29326C3DF" \
https://myserver.com/auth/oauth/session/_9ad0a091-cbd6-4c59-ab5a-d4f2870f218c

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

Authenticate your account using OAuth2.0 / Open ID Connect. Returns a Vault sessionId.

POST /auth/oauth/session/{oath_oidc_profile_id}

Headers

Name	Description
`Authorization`	Bearer {`access_token`}
`Host`	`login.veevavault.com`

URI Path Parameters

Name	Description
`oath_oidc_profile_id`	The ID of your OAuth2.0 / Open ID Connect profile.

Body Parameters

Name	Description
`vaultDNS`	The DNS of the Vault where you want to generate a session. If omitted, set to the default Vault DNS.

Salesforce Delegated Requests

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

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

Retrieve API Versions

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

{
   "responseStatus": "SUCCESS",
   "values": {
       "v7.0": "https://myvault.veevavault.com/api/v7.0",
       "v8.0": "https://myvault.veevavault.com/api/v8.0",
       "v9.0": "https://myvault.veevavault.com/api/v9.0",
       "v10.0": "https://myvault.veevavault.com/api/v10.0",
       "v11.0": "https://myvault.veevavault.com/api/v11.0",
       "v12.0": "https://myvault.veevavault.com/api/v12.0",
       "v13.0": "https://myvault.veevavault.com/api/v13.0",
       "v14.0": "https://myvault.veevavault.com/api/v14.0",
       "v15.0": "https://myvault.veevavault.com/api/v15.0",
       "v16.0": "https://myvault.veevavault.com/api/v16.0",
       "v17.1": "https://myvault.veevavault.com/api/v17.1",
       "v17.2": "https://myvault.veevavault.com/api/v17.2",
       "v17.3": "https://myvault.veevavault.com/api/v17.3",
       "v18.1": "https://myvault.veevavault.com/api/v18.1",
       "v18.2": "https://myvault.veevavault.com/api/v18.2",
       "v18.3": "https://myvault.veevavault.com/api/v18.3",
       "v19.1": "https://myvault.veevavault.com/api/v19.1",
       "v19.2": "https://myvault.veevavault.com/api/v19.2",
       "v19.3": "https://myvault.veevavault.com/api/v19.3",
       "v20.1": "https://myvault.veevavault.com/api/v20.1",
       "v20.2": "https://myvault.veevavault.com/api/v20.2",
       "v20.3": "https://myvault.veevavault.com/api/v20.3",
       "v21.1": "https://myvault.veevavault.com/api/v21.1"
   }
}

Retrieve all supported versions of the Vault REST API.

GET /api/

Headers

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

Response Details

On success, Vault returns every supported API version. The last version listed in the response may be the Beta version, which is subject to change. Learn more about Vault REST API versioning.

Discovery

$ curl -X POST \
-H "Accept: application/json" \
https://login.veevavault.com/auth/discovery?username=meganmurray@veepharm.com

{
    "responseStatus": "SUCCESS",
    "data": {
        "auth_type": "sso",
        "auth_profiles": [
            {
                "id": "_9ad0a091-cbd6-4c59-ab5a-d4f2870f218c",
                "label": "PMDemo",
                "description": "",
                "vault_session_endpoint": "https://devauth1.vaultdev.com/auth/oauth/session/_9ad0a091-cbd6-4c59-ab5a-d4f2870f218c",
                "as_metadata": {
                    "issuer": "https://veevatest.okta.com/oauth2/aus1b8xga9o48qdj31d8",
                    "authorization_endpoint": "https://veevatest.okta.com/oauth2/aus1b8xga9o48qdj31d8/v1/authorize",
                    "token_endpoint": "https://veevatest.okta.com/oauth2/aus1b8xga9o48qdj31d8/v1/token",
                    "registration_endpoint": "https://veevatest.okta.com/oauth2/v1/clients",
                    "jwks_uri": "https://veevatest.okta.com/oauth2/aus1b8xga9o48qdj31d8/v1/keys",
                    "response_types_supported": [
                        "code",
                        "token",
                        "code token"
                    ],
                    "response_modes_supported": [
                        "query"
                    ],
                    "introspection_endpoint": "https://veevatest.okta.com/oauth2/aus1b8xga9o48qdj31d8/v1/introspect",
                    "introspection_endpoint_auth_methods_supported": [
                        "client_secret_basic",
                    ],
                    "revocation_endpoint": "https://veevatest.okta.com/oauth2/aus1b8xga9o48qdj31d8/v1/revoke",
                    "revocation_endpoint_auth_methods_supported": [
                        "client_secret_basic",
                    ],
                    "end_session_endpoint": "https://veevatest.okta.com/oauth2/aus1b8xga9o48qdj31d8/v1/logout"
                }
            }
        ]
    }
}

Discover the Authentication type of a user. With this API, you can build applications which could dynamically adjust the the login requirements per user, and support either username/password or OAuth2.0 / OpenID Connect authentication schemes.

POST https://{auth_server_url}/auth/discovery

Headers

Name	Description
`Accept`	`application/json` (default)
`Host`	`login.veevavault.com`

Query Parameters

Name	Description
`username`	The user’s Vault username.

Response Details

The response specifies the user’s auth_type, either:

password: The user is configured with a username and password.
sso: The user is configured with an SSO Security Policy and at least one SSO profile.

The response specifies the user’s auth_profiles, which includes all other information about the user’s authentication profile. If the user’s Security Profile is associated with:

An OAuth2/OIDC profile, the response will also contain the Authentication Server metadata (as_metadata).
A SAML profile, the auth_profiles array will be empty.

Domain Information

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

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "domain__v": {
        "domain_name__v": "veepharm",
        "domain_type__v": "testvaults",
        "vaults__v": [
            {
                "id": "2000",
                "vault_name__v": "PromoMats",
                "vault_status__v": "Active",
                "vault_application__v": "PromoMats",
                "vault_family__v": {
                    "name__v": "commercial__v",
                    "label__v": "Commercial"
                }
            },
            {
                "id": "4000",
                "vault_name__v": "eTMF",
                "vault_status__v": "Active",
                "vault_application__v": "eTMF",
                "vault_family__v": {
                    "name__v": "clinical_ops__v",
                    "label__v": "Clinical Operations"
                }
            }
        ]
    }
}

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`

Response Details

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).
`vault_family__v`	Contains information about the application family each Vault belongs to (Commercial, Clinical Operations, Regulatory, or Quality), such as name and label.

Vault Query Language (VQL)

When an application invokes a query call, it passes in a Vault Query Language (VQL) statement (a SQL-like statement) that specifies the object to query (in the FROM clause), the fields to retrieve (in the SELECT clause), and any optional filters to apply (in the WHERE and FIND clauses) to narrow your results.

Submitting a Query

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "X-VaultAPI-DescribeQuery: true" \
https://myvault.veevavault.com/api/v14.0/query?q=SELECT id FROM documents

{
  "responseStatus": "SUCCESS",
    "queryDescribe": {
        "object": {
            "name": "documents",
            "label": "documents",
            "label_plural": "documents"
        },
        "fields": [
            {
                "type": "id",
                "required": true,
                "name": "id"
            }
        ]
    },
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 17,
        "total": 17
    },
    "data": [
        {
            "id": 24
        }
    ]
}

VQL queries go to the /query REST interface. Submit a query by sending a POST request to the following endpoint:

/api/{version}/query

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`
`X-VaultAPI-DescribeQuery`	Set to `true` to include static field metadata in the response for the data record. If not specified, the response does not include any static field metadata. This option eliminates the need to make additional API calls to understand the shape of query response data.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
`limit`	The number of records displayed per page. This can be modified. Learn more.
`offset`	The records displayed on the current page are offset by this number of records. Learn more.
`size`	The total number of records displayed on the current page.
`total`	The total number of records found.
`previous_page`	The Pagination URL to navigate to the previous page of results. This is not always available. Learn more.
`next_page`	The Pagination URL to navigate to the next page of results. This is not always available. Learn more.
`data`	All records found.

About the X-VaultAPI-DescribeQuery Header

When you include the X-VaultAPI-DescribeQuery header and set it to true, the query response includes the following static metadata description:

Name	Description
`name`	The name of the queryable object.
`label`	The label of the queryable object.
`label_plural`	The plural label of the queryable object

The field metadata may include some or all of the following:

Metadata Field	Description
`name`	Name of the field.
`label`	The UI label of the field.
`type`	The data type, for example, `string` or `int`
`max_length`	The max length of a string field.
`max_value`	The max value a number field.
`min_value`	The minimum value of a number field.
`scale`	The number of digits after a decimal point in a number field.
`required`	Indicates the field is required.
`unique`	Indicates if the value must be unique (true/false).
`status`	Indicates if the field is active (active/inactive).
`picklist`	The picklist name field value.

For formula fields, QueryDescribe should describe the field as specified in the metadata, excluding the formula attribute.

Documents

Vault is a highly configurable system designed to reflect the business model of documents. Each Vault can have different document types, document fields, 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

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

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

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`

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 [VQL(/vql).

Retrieve Common Document Fields

$ 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

    {
      "name": "submission_date__c",
      "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__c",
          "type": "type"
        },
        {
          "key": "compliance_package__v",
          "type": "type"
        },
        {
          "key": "claim__c",
          "type": "type"
        }
      ]
    }
    {
      "name": "withdrawal_effective_date__c",
      "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__c"
    }

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 are eligible for bulk update.

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.

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

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

{
    "responseStatus": "SUCCESS",
    "types": [
        {
            "label": "Base Document",
            "value": "https://etmf-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/base_document__v"
        },
        {
            "label": "Centralized Testing",
            "value": "https://etmf-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/centralized_testing__c"
        },
        {
            "label": "Central Trial Documents",
            "value": "https://etmf-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/central_trial_documents__c"
        },
        {
            "label": "Country Master File",
            "value": "https://etmf-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/country_master_file__v"
        },
        {
            "label": "Data Management",
            "value": "https://etmf-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/data_management__c"
        },
        {
            "label": "Final CRF",
            "value": "https://etmf-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/final_crf__v"
        },
        {
            "label": "IP and Trial Supplies",
            "value": "https://etmf-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/ip_and_trial_supplies__c"
        },
    ],
    "lock": "https://etmf-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/lock"
}

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`

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

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

{
  "responseStatus": "SUCCESS",
  "name": "promotional_piece__c",
  "label": "Promotional Piece",
  "renditions": [
    "viewable_rendition__v",
    "production_proof__c",
    "distribution_package__c",
    "imported_rendition__c",
    "veeva_distribution_package__c"
  ],
  "relationshipTypes": [
    {
      "label": "CrossLink Latest Bindings",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
    {
      "label": "CrossLink Latest Steady State Bindings",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
    {
      "label": "Linked Documents",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
    {
      "label": "Based on",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    }
  ],
  "templates": [
    {
      "label": "ANSM Submission",
      "name": "ansm_submission__c",
      "kind": "binder",
      "definedIn": "promotional_piece__c",
      "definedInType": "type"
    }
  ],
  "availableLifecycles": [
    {
      "name": "promotional_piece__c",
      "label": "Promotional Piece"
    }
  ],
  "subtypes": [
    {
      "label": "Advertisement",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/subtypes/advertisement__c"
    },
    {
      "label": "Direct Mail",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/subtypes/direct_mail__c"
    },
    {
      "label": "Formulary Announcement",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/subtypes/formulary_announcement__c"
    },
    {
      "label": "Internal Communication",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/subtypes/internal_communication__c"
    },
    {
      "label": "Managed Markets Program",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/subtypes/managed_markets_program__c"
    },
    {
      "label": "Healthcare Practitioner Resources",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/subtypes/healthcare_practitioner_resources__c"
    },
    {
      "label": "Convention Item",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/subtypes/convention_item__c"
    }
  ]
}

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.

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

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

{
  "responseStatus": "SUCCESS",
  "name": "advertisement__c",
  "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.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/subtypes/advertisement__c/classifications/print__c"
    },
    {
      "label": "Television",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/subtypes/advertisement__c/classifications/television__c"
    },
    {
      "label": "Web",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/subtypes/advertisement__c/classifications/web__c"
    }
  ],
  "relationshipTypes": [
    {
      "label": "Linked Documents",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
    {
      "label": "Based on",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
    {
      "label": "Related Claims",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
    {
      "label": "Supporting Documents",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
  ],
  "templates": [
    {
      "label": "ANSM Submission",
      "name": "ansm_submission__c",
      "kind": "binder",
      "definedIn": "promotional_piece__c",
      "definedInType": "type"
    }
  ],
  "availableLifecycles": [
    {
      "name": "promotional_piece__c",
      "label": "Promotional Piece"
    }
  ]
}

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.

Retrieve Document Classification

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

{
  "responseStatus": "SUCCESS",
  "name": "advertisement__c",
  "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.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
    {
      "label": "Based on",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
    {
      "label": "Related Claims",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
    {
      "label": "Supporting Documents",
      "value": "https://promomats-veevapharm.veevavault.com/api/v15.0/metadata/objects/documents/types/promotional_piece__c/relationships"
    },
  ],
  "templates": [
    {
      "label": "ANSM Submission",
      "name": "ansm_submission__c",
      "kind": "binder",
      "definedIn": "promotional_piece__c",
      "definedInType": "type"
    }
  ],
  "availableLifecycles": [
    {
      "name": "promotional_piece__c",
      "label": "Promotional Piece"
    }
  ]
}

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

Retrieve Documents

The following rules govern document retrieval:

Vault only returns documents to which the logged in user has access to, even if more documents exist.
Vault only returns the latest version of each document. To return every version of a document, use the versionscope=all query parameter.
Vault returns a maximum of 200 documents per page. You can lower this number using the limit query parameter.

Identifying Binders

The document pseudo-field binder__v indicates whether the returned document is a 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 sections are not listed as part of the response and must be determined using the Retrieve Binder API with the depth=all query parameter.

Identifying CrossLink Documents

A document pseudo-field crosslink__v indicates whether the returned document is a regular document (false) or a CrossLink document (true).

Retrieve All Documents

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

{
  "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__c": [
          "Print"
        ]
      }
    }
  ]
}

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 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 only documents which you have marked as favorites in the library.
`named_filter=Recent Documents`	Retrieves only documents which you have recently accessed.
`named_filter=Cart`	Retrieves only documents in your cart.
`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`	Limit the number of documents to display. By default, Vault displays up to 200 documents per page.
`sort`	Return documents in a specific order by specifying a document field and either ascending (`ASC`) or descending (`DESC`) order. For example, `sort = name__v DESC`. The default is `sort = id ASC`. See VQL documentation for more information.
`start`	The starting record number. The default is 0.

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

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

{
    "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.veevavault.com/api/v15.0/objects/documents/450/renditions/viewable_rendition__v",
        "veeva_distribution_package__c": "https://myvault.veevavault.com/api/v15.0/objects/documents/450/renditions/veeva_distribution_package__c"
    },
    "versions": [
        {
            "number": "0.1",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/450/versions/0/1"
        },
        {
            "number": "1.0",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/450/versions/1/0"
        },
        {
            "number": "1.1",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/450/versions/1/1"
        }
    ],
    "attachments": [
        {
            "id": 547,
            "url": "https://myvault.veevavault.com/api/v15.0/objects/documents/450/attachments/547"
        }
    ]
}

Retrieve all metadata from a document.

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

Headers

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

URI Path Parameters

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

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 (true) or a CrossLink document (false).

Retrieve Document Versions

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

{
    "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__c": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/veeva_distribution_package__c"
    }
}

Retrieve all versions of a document.

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

Headers

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

URI Path Parameters

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

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

Retrieve Document Version

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

{
    "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__c": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/veeva_distribution_package__c"
        }
    ],
    "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"
        }
    ]
}

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
`{doc_id}`	The document `id` field value.
`{major_version}`	The document `major_version_number__v` field value.
`{minor_version}`	The document `minor_version_number__v` field value.

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

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

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

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

Headers

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

URI Path Parameters

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

Query Parameters

Name	Description
`lockDocument`	Set to `true` to Check Out this document before retrieval. If omitted, defaults to `false`.

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

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

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

Download the file of a specific document version.

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

Headers

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

URI Path Parameters

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

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

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

Download the thumbnail image file of a specific document version.

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

Headers

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

URI Path Parameters

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

Response Details

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

Create Single Document

$ 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

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

Create a single document.

POST /api/{version}/objects/documents

Headers

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

Body Parameters

There are multiple ways to create a document.

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.

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

Create Document from Template

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.

Name	Description
`fromTemplate`	The name of the template to apply.
`type__v`	The name of the document type to assign to the new document.
`subtype__v`	The name of the document subtype (if applicable).
`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.

Create Content Placeholder Document

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. Admin may set other standard or custom document fields to required in your Vault.

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.

Create Unclassified Document

Unclassified documents are documents which have a source file, but no document type. Learn about Unclassified Documents in Vault Help.

Name	Description
`file`	The filepath of the source document. The maximum allowed file size is 4GB.
`type__v`	Set the document type to “Undefined”.
`lifecycle__v`	Set the document lifecycle to “Unclassified”.

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

product__v
study__v
study_country__v
site__v

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

Create CrossLink Document

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.

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.
`source_binding_rule__v`	Optional: Possible values are `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`	Optional: 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`	Optional: 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.

Response Details

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

Create Multiple Documents

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

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

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

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

Note that this API does not support adding multi-value relationship fields by name. To add multi-value fields, you must first retrieve the ID values and add them to the relationship field.

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

Headers

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

Body Parameters

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

Create Documents from Uploaded Files

You must first upload the document source files to your Vault’s FTP staging server.

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.
`suppressRendition`	Optional: `false` by default. Set to `true` to suppress generation of viewable renditions.
`product__v`	Example: This is an example object reference field. To assign value for this field type, include either the document field name `product__v` or the document field name plus the name field on the object `product__v.name__v`.

Create Documents from Templates

When you create a new document from a template, Vault copies the template file in your Vault and uses that copy as the source file for the new document.

Name	Description
`fromTemplate`	The template to apply to the document.
`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.
`product__v`	Example: This is an example object reference field. To assign value for this field type, include either the document field name `product__v` or the document field name plus the name field on the object `product__v.name__v`.

Create Content Placeholder Documents

Vault allows you to create content placeholders when the associated file is not yet available. You can add the source document at a later date.

Name	Description
`file`	Include this column in your input, but leave the values blank.
`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.

Create Unclassified Documents

Unclassified documents are documents which have a source file, but no document type. The following fields are required, but you can include any 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`	Set the document type to `Undefined`
`lifecycle__v`	Set the document lifecycle to `Unclassified`

Update Documents

Update Single Document

$ 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

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

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

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

Headers

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

URI Path Parameters

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

Body Parameters

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

Update Multiple Documents

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

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

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

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

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

Headers

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

Body Parameters

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

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

Reclassify Document

$ 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__v=Advertisement" \
-d "classification__v=Web" \
-d "lifecycle__v=Promotional Piece" \
https://myvault.veevavault.com/api/v15.0/objects/documents/775

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

Reclassify allows you to change the document type of an existing document or assign a document type to an 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 reclassifying documents in Vault Help.

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

Headers

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

URI Path Parameters

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

Body Parameters

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

Update Document Version

$ 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__c=consumer__c" \
https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0

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

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

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

Headers

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

URI Path Parameters

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

Response Details

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

Create Multiple Document Versions

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

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

Create or add document versions in bulk.

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

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

Headers

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

Body Parameters

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

Query Parameters

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

Create Single Document Version

$ 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

$ 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

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

Add a new draft version of an existing document. You can choose to either use the existing source file, or a new source file. These actions will increase the document’s minor version number. This is analogous to using the Create Draft action in the UI.

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

Headers

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

URI Path Parameters

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

Body Parameters

Name	Description
`createDraft=latestContent`	Create a new draft version from the existing document in the Vault. This does not require uploading a file. This is analogous to the Copy file from current version option in the Create Draft UI.
`createDraft=uploadedContent`	Create a new draft version by uploading the document source file. This requires uploading a new source file with an additional `file` body parameter. The maximum allowed file size is 4GB. This is analogous to the Upload a new file option in the Create Draft UI.
`file`	Optional: If `createDraft=uploadedContent`, use this parameter to include the new document source file. If your target document is a placeholder, use this parameter to upload a source file and create a new draft version of the document.

Query Parameters

Name	Description
`suppressRendition`	Set to `true` to suppress automatic generation of the viewable rendition. If omitted, defaults to `false`.

Delete Documents

After deleting documents, 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. Note that you cannot delete checked out documents unless you have the Power Delete permission. Learn more about Power Delete in Vault Help.

Delete Single Document

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

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

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

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

Headers

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

URI Path Parameters

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

Delete Multiple Documents

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

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

Delete all versions of multiple documents, including all source files and viewable renditions.

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

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

Headers

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

Body Parameters

Some HTTP clients do not support DELETE requests with a body. As a workaround for these cases, you can simulate this request using the POST method with the _method=DELETE query parameter.

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

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

Query Parameters

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

Delete Single Document Version

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

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

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

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

Headers

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

URI Path Parameters

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

Delete Multiple Document Versions

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

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

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

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

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

Headers

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

Body Parameters

Some HTTP clients do not support DELETE requests with a body. As a workaround for these cases, you can simulate this request using the POST method with the _method=DELETE query parameter.

Create a CSV or JSON input file.

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

Query Parameters

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

Retrieve Deleted Document IDs

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

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

        }
      ]
    }

Retrieve IDs of documents deleted within the past 30 days.

After documents and document versions are deleted, their IDs remain 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.

To completely restore a document deleted within the last 30 days, contact Veeva support.

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`

Query Parameters

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

Name	Description
`start_date`	Specify a date (no more than 30 days past) after which Vault will look for deleted documents. Dates must be `YYYY-MM-DDTHH:MM:SSZ` format, for example, 7AM on January 15, 2016 would use `2016-01-15T07:00:00Z`
`end_date`	Specify a date (no more than 30 days past) before which Vault will look for deleted documents. Dates must be `YYYY-MM-DDTHH:MM:SSZ` format, for example, 7AM on January 15, 2016 would use `2016-01-15T07:00:00Z`

Dates and times are in UTC. If the time is not specified, it will default to midnight (T00:00:00Z) on the specified date.

Response Details

The abridged response shows that a total of 88 documents were deleted from this Vault in the past 30 days. Two versions (0.1 and 0.2) were deleted for Document ID 690. Version 0.1 was deleted for both Document ID 691 and Document ID 692. The response includes the date and time when each document was deleted. Date and time display 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 download the document file after locking it, use the Download Document File endpoint.

Learn about Document Checkout (Locks) in Vault Help.

Retrieve Document Lock Metadata

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

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

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

Headers

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

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

Create Document Lock

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

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

A document lock is analogous to checking out a document but without the file attached in the response for download.

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

Headers

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

URI Path Parameters

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

Response Details

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

Retrieve Document Lock

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

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

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

Headers

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

URI Path Parameters

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

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

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

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

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

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

URI Path Parameters

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

Response Details

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

Document Renditions

Learn about Document Renditions in Vault Help.

Note that requests to retrieve renditions might return an UNEXPECTED_ERROR. If this occurs, retry the request after a few seconds.

Retrieve Document Renditions

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

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

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

Headers

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

URI Path Parameters

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

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

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

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

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

Headers

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

URI Path Parameters

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

Download Document Rendition File

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

{
    "responseStatus": "SUCCESS"
}

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

GET /api/{version}/objects/documents/{doc_id}/renditions/{rendition_type}

Headers

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

URI Path Parameters

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

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

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.

Download Document Version Rendition File

$ 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

{
    "responseStatus": "SUCCESS"
}

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

Headers

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

URI Path Parameters

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

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

Add Multiple Document Renditions

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

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

Add document renditions in bulk. You must first load the renditions to the file staging server.

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

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

Headers

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

Body Parameters

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

Query Parameters

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

Add Single Document Rendition

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

{
    "responseStatus": "SUCCESS"
}

POST /api/{version}/objects/documents/{doc_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
`{doc_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.

Response Details

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

Upload Document Version Rendition

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

{
    "responseStatus": "SUCCESS"
}

POST /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/renditions/{rendition_type}

Headers

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

URI Path Parameters

Name	Description
`{doc_id}`	The document `id` field value.
`{major_version}`	The document `major_version_number__v` field value.
`{minor_version}`	The document `minor_version_number__v` field value.
`{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.

Response Details

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

Replace Document Rendition

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

{
    "responseStatus": "SUCCESS"
}

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

Headers

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

URI Path Parameters

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

Response Details

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

Replace Document Version Rendition

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

{
    "responseStatus": "SUCCESS"
}

PUT /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/renditions/{rendition_type}

Headers

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

URI Path Parameters

Name	Description
`{doc_id}`	The document `id` field value.
`{major_version}`	The document `major_version_number__v` field value.
`{minor_version}`	The document `minor_version_number__v` field value.
`{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.

Response Details

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

Delete Multiple Document Renditions

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

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

Delete document renditions in bulk.

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

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

Headers

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

Body Parameters

Some HTTP clients do not support DELETE requests with a body. As a workaround for these cases, you can simulate this request using the POST method with the _method=DELETE query parameter.

Create a CSV or JSON input file.

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

Query Parameters

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

Delete Single Document Rendition

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

{
    "responseStatus": "SUCCESS"
}

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

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

Headers

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

URI Path Parameters

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

Delete Document Version Rendition

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

{
    "responseStatus": "SUCCESS"
}

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

Headers

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

URI Path Parameters

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

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

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

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

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

Headers

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

URI Path Parameters

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

Response Details

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

Retrieve Document Attachments

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

{
    "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.veevavault.com/api/v15.0/objects/documents/565/attachments/566/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.veevavault.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.veevavault.com/api/v15.0/objects/documents/565/attachments/567/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/567/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/567/versions/3"
                }
            ]
        }
    ]
}

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

Headers

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

URI Path Parameters

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

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 Version Attachments

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.3/objects/documents/17/versions/0/1/attachments

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 39,
            "filename__v": "New",
            "format__v": "application/x-tika-ooxml",
            "size__v": 55762,
            "md5checksum__v": "c5e7eaafc39af8ba42081a213a68f781",
            "version__v": 1,
            "created_by__v": 61603,
            "created_date__v": "2017-10-30T17:03:29.878Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.veevavault.com/api/v17.3/objects/documents/17/versions/0/1/attachments/39/versions/1"
                }
            ]
        }
    ]
}

Retrieve attachments on a specific version of a document.

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

Headers

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

URI Path Parameters

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

Retrieve Document Attachment Versions

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

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

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

Headers

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

URI Path Parameters

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

Response 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 Version Attachments

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.3/objects/documents/17/versions/0/1/attachments/39/versions/1

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 39,
            "filename__v": "New",
            "format__v": "application/x-tika-ooxml",
            "size__v": 55762,
            "md5checksum__v": "c5e7eaafc39af8ba42081a213a68f781",
            "version__v": 1,
            "created_by__v": 61603,
            "created_date__v": "2017-10-30T17:03:29.878Z"
        }
    ]
}

Retrieve versions of an attachment on a specific version of a document.

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

Headers

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

URI Path Parameters

Name	Description
`{doc_id}`	The document `id` field value.
`{major_version}`	The document `major_version_number__v` field value.
`{minor_version}`	The document `minor_version_number__v` field value.
`{attachment_id}`	The `id` of the document attachment to retrieve.
`{attachment_version}`	Optional: The version of the attachment to retrieve. If omitted, the endpoint retrieves all versions of the specified attachment.

Retrieve Document Attachment Metadata

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

{
    "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.veevavault.com/api/v15.0/objects/documents/565/attachments/566/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.veevavault.com/api/v15.0/objects/documents/565/attachments/566/versions/2"
                }
            ]
        }
    ]
}

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

Headers

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

URI Path Parameters

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

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.

Retrieve Document Attachment Version Metadata

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

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

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

Headers

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

URI Path Parameters

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

Download Document Attachment

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

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

Downloads the latest version of the specified attachment from the document.

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

Headers

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

URI Path Parameters

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

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 the MIME type of the file. For example, if the attachment is a PNG image, the Content-Typeis image/png. If we cannot detect the MIME file type, Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename attribute 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

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

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

Downloads the specified version of the attachment from the document.

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

Headers

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

URI Path Parameters

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

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 the MIME type of the file. For example, if the attachment is a PNG image, the Content-Type is image/png. If we cannot detect the MIME file type, Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename attribute 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 Document Version Attachment Version

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.3/objects/documents/56/versions/0/1/attachments/14/versions/3/file

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

Downloads the specified attachment version from the specified document version.

GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/attachments/{attachment_id}/versions/{attachment_version}/file

Headers

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

URI Path Parameters

Name	Description
`{doc_id}`	The document `id` field value.
`{major_version}`	The document `major_version_number__v` field value.
`{minor_version}`	The document `minor_version_number__v` field value.
`{attachment_id}`	The `id` field value of the attachment.
`{attachment_version}`	The version of the attachment.

Response Details

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

Download All Document Attachments

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

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

Downloads the latest version of all attachments from the document.

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

Headers

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

URI Path Parameters

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

Response Details

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/zip. The HTTP Response Header Content-Disposition contains a filename attribute 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 Version Attachments

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

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

Downloads the latest version of all attachments from the specified version of the document.

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

Headers

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

URI Path Parameters

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

Response Details

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

Delete Single Document Attachment

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

{
    "responseStatus": "SUCCESS"
}

Deletes the specified attachment and all of its versions.

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

Headers

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

URI Path Parameters

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

Response Details

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

Delete Single Document Attachment Version

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

{
    "responseStatus": "SUCCESS"
}

Deletes the specified version of the specified attachment.

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

Headers

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

URI Path Parameters

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

Delete Multiple Document Attachments

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

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 26
        }
    ]
}

Delete multiple document attachments in bulk with a JSON or CSV input file. This works for version-specific attachments and attachments at the document level.

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

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

Headers

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

Body Parameters

Some HTTP clients do not support DELETE requests with a body. As a workaround for these cases, you can simulate this request using the POST method with the _method=DELETE query parameter.

Prepare a CSV or JSON input file.

Name	Description
`id`	The attachment ID to delete.
`document_id__v`	Optional: The source document `id` value.
`external_id__v`	Optional: Identify documents by their external ID instead of regular `id`. You must also add the `idParam=external_id__v` query parameter.

Response Details

On SUCCESS, the response returns the id of all successfully deleted attachments. You can only delete the latest version of an attachment.

Create Document Attachment

$ 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

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

Create an attachment on the latest version of a document. If the attachment already exists, Vault uploads the attachment as a new version of the existing attachment. Learn more about attachment versioning in Vault Help.

To create a version-specific attachment, or to create multiple attachments at once, use the bulk API.

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

Headers

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

URI Path Parameters

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

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.

Create Multiple Document Attachments

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

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 39,
            "version": 1
        }
    ]
}

Create multiple document attachments in bulk with a JSON or CSV input file. You must first load the attachments to the FTP staging server. This works for version-specific attachments and attachments at the document level. If the attachment already exists, Vault uploads the attachment as a new version of the existing attachment. Learn more about attachment versioning in Vault Help.

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

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

Headers

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

Body Parameters

Prepare a CSV or JSON input file.

Name	Description
`document_id__v`	The document ID to add this attachment.
`filename__v`	The name for the new attachment. If an attachment with this name already exists, the attachment is added as a new version.
`file`	The filepath of the attachment on the FTP server.
`description__v`	Optional: Description of the attachment. Maximum 1000 characters.
`major_version_number__v`	Optional: The major version of the source document.
`minor_version_number__v`	Optional: The minor version of the source document.
`external_id__v`	Optional: Set an external ID value on the attachment.

Response Details

On SUCCESS, returns the ID and version of new attachments. Attachments created unsuccessfully are reported with an error message.

Restore Document Attachment Version

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

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

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

Headers

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

URI Path Parameters

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

Query Parameters

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

Response Details

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

$ 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

{
    "responseStatus": "SUCCESS"
}

Update an attachment on the latest version of a document. To update a version-specific attachment, or to update multiple attachments at once, use the bulk API.

PUT /api/{version}/objects/documents/{doc_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
`{doc_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.

Update Multiple Document Attachment Descriptions

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

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 38,
            "version": 2
        }
    ]
}

Update multiple document attachments in bulk with a JSON or CSV input file. This works for version-specific attachments and attachments at the document level. You can only update the latest version of an attachment.

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

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

Headers

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

Body Parameters

Prepare a CSV or JSON input file.

Name	Description
`id`	The attachment ID to update.
`external_id__v`	Optional: Identify attachments by their external ID instead of regular `id`. You must also add the `idParam=external_id__v` query parameter.
`description__v`	Optional: Description of the attachment. Maximum 1,000 characters.

Response Details

On SUCCESS, the response gives the id and version of all successfully updated attachments.

Document Annotations

Learn about Document Annotations in Vault Help.

Download Document Annotations

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

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

Headers

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

URI Path Parameters

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

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.

Download Document Version Annotations

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

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

Headers

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

URI Path Parameters

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

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 Video Annotations

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

* Name: Cholecap Presentation
* Number: VV-00040
* Version: 2
* Status: draft
* Download timestamp: 1/4/18 11:32:02 AM PST

-------------------------------
Time signature: 00:01:35
Note ID: 1515092438330
Author: Lateef Gills
Time stamp: 1/4/18 11:00:38 AM PST
Version of origin: 2
Status: Open
Comment: Slide 3 displays here

Reply author: Teresa Ibanez
Reply time stamp: 1/4/18 12:31:05 PM PST
Reply comment: Thanks!

## END

Retrieve annotations on a video document.

GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/export-video-annotations

Headers

Name	Description
`Accept`	`text/csv` (default)

URI Path Parameters

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

Response Details

On SUCCESS, Vault includes the following information:

Metadata Field	Description
`Note ID`	The `id` of the video annotation to retrieve.
`Author`	The name of the user who created the annotation.
`Timestamp`	Timestamp when the annotation was created.
`Version of origin`	The original version of the document where the annotation was created.
`Note status`	Indicates if the annotation is open or closed.
`Comment text`	The annotation text.

This example includes a reply and the reply details which displays under the parent note. Vault orders annotations by time signature.

Upload Document Annotations

$ 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

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

POST /api/{version}/objects/documents/{doc_id}/annotations

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
`{doc_id}`	The document `id` field value.

Response Details

On SUCCESS, Vault uploads the file and its annotations.

Upload Document Version Annotations

$ 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

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

POST /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/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
`{doc_id}`	The document `id` field value.
`{major_version}`	The document `major_version_number__v` field value.
`{minor_version}`	The document `minor_version_number__v` field value.

Response Details

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

Document Relationships

You cannot create or delete standard relationship types. Examples of standard relationship types include Based On and Original Source. Learn about Document Relationships in Vault Help.

Retrieve Document Type Relationships

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

{
  "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__c"
        },
        {
          "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__c"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__c"
        },
        {
          "label": "Multichannel Slide",
          "value": "slide__v"
        },
        {
          "label": "Compliance Package",
          "value": "compliance_package__v"
        },
        {
          "label": "Undefined",
          "value": "undefined__v"
        }
      ]
    },
    {
      "value": "references__c",
      "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__c"
        },
        {
          "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__c"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__c"
        },
        {
          "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__c"
        },
        {
          "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__c"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__c"
        },
        {
          "label": "Multichannel Slide",
          "value": "slide__v"
        },
        {
          "label": "Compliance Package",
          "value": "compliance_package__v"
        },
        {
          "label": "Undefined",
          "value": "undefined__v"
        }
      ]
    },
    {
      "value": "basedon__c",
      "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__c"
        },
        {
          "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__c"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__c"
        },
        {
          "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__c"
        },
        {
          "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__c"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__c"
        },
        {
          "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__c"
        },
        {
          "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__c"
        },
        {
          "label": "Reference Document",
          "value": "reference_document__c"
        },
        {
          "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"
      }
    }
  ]
}

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.

Response Details

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

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 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 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 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 only applies when the source document is bound to a specific version of the target document.
`relationship_type__v`	The relationship type (`basedon__c`, `supporting_documents__c`, `related_claims__c`, `related_pieces__c`, 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.

Retrieve Document Relationships

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

{
  "responseStatus": "SUCCESS",
  "responseMessage": null,
  "errorCodes": null,
  "relationships": [
    {
      "relationship": {
        "source_doc_id__v": 886,
        "relationship_type__v": "related_pieces__c",
        "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__c",
        "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__c",
        "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__c",
        "created_date__v": "2015-12-15T22:06:21.000Z",
        "id": 215,
        "target_doc_id__v": 889,
        "created_by__v": 46916
      }
    }
  ],
  "errorType": null
}

Retrieve all relationships from a document.

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

Headers

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

URI Path Parameters

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

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__c relationship type. The other two referenced documents - target_doc_id__v 885 and 887 have the supporting_documents__c relationship type.

Create Single Document Relationship

$ 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

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

Create a new relationship on a document.

You cannot create or delete standard relationship types. Examples of standard relationship types include Based On and Original Source. Learn about Document Relationships in Vault Help.

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

Field Name	Description
`target_doc_id__v`	The document `id` of the target document.
`relationship_type__v`	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.

Response Details

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

Create Multiple Document Relationships

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

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

Create new relationships on multiple documents.

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

You cannot create or delete standard relationship types. Examples of standard relationship types include Based On and Original Source. Learn about Document Relationships in Vault Help.

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

Headers

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

Body Parameters

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

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

Create Source Version-Specific Relationships

The following fields are required when creating a source version-specific relationship.

Name	Description
`source_major_version__v`	The major version number of the source document.
`source_minor_version__v`	The minor version number of the source document.
`relationship_type__v`	The type of relationship the target document will have with the source document.

Create Target Version-Specific Relationships

The following fields are required when creating a target version-specific relationship.

Name	Description
`target_major_version__v`	The major version number of the target document to which the source document will be bound.
`target_minor_version__v`	The minor version number of the target document to which the source document will be bound.
`relationship_type__v`	The type of relationship the target document will have with the source document.

Query Parameters

Name	Description
`idParam`	To create relationships based on an external id field, set to `external_id__v`. You must set `Content-Type` to `text/csv` and include an `external_id__v` column.

Response Details

On SUCCESS, Vault returns the IDs of the newly created document relationships.

Retrieve Document Relationship

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

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

Retrieve details of a specific document relationship.

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

Headers

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

URI Path Parameters

Name	Description
`{doc_id}`	The document `id` field value.
`{major_version}`	The document `major_version_number__v` field value.
`{minor_version}`	The document `minor_version_number__v` field value.
`{relationship_id}`	The relationship `id` field value. See Retrieve Document Relationships.

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 Single Document Relationship

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

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

Delete a relationship from a document.

You cannot create or delete standard relationship types. Examples of standard relationship types include Based On and Original Source. Learn about Document Relationships in Vault Help.

Send DELETE to /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.

Response Details

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

Delete Multiple Document Relationships

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

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

Delete relationships from multiple documents.

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

You cannot create or delete standard relationship types. Examples of standard relationship types include Based On and Original Source. Learn about Document Relationships in Vault Help.

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

Headers

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

Body Parameters

Some HTTP clients do not support DELETE requests with a body. As a workaround for these cases, you can simulate this request using the POST method with the _method=DELETE query parameter.

Create a CSV or JSON input file.

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

Response Details

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

Export Documents

The Export Documents API allows you to query a set of documents for export to your Vault’s FTP staging server. You can export the following artifacts for a given document:

Source document
Renditions
All versions or latest version

This API does not support the following:

Fields
Attachments
Audit trails
Related documents
Signature Pages
Overlays
Archived documents. To export archived documents, use API v20.3+.

Note that the maximum number of document versions (source files) you can export per request is 10,000.

Export Documents

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--data-binary @"C:\Vault\Documents\export_documents.json" \
https://myvault.veevavault.com/api/v17.3/objects/documents/batch/actions/fileextract?source=true&renditions=false&allversions=true

{
    "responseStatus": "SUCCESS",
    "url": "/api/v17.3/services/jobs/36203",
    "job_id": "36203"
}

Use this request to export a set of documents to your Vault’s FTP staging server.

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

Headers

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

Body Parameters

Name	Description
`id`	The `id` value of the document(s) to export.

Query Parameters

Name	Description
`source`	Optional: To exclude source files, include a query parameter `source=false`. If omitted, defaults to `true`.
`renditions`	Optional: To include renditions, include a query parameter `renditions=true`. If omitted, defaults to `false`.
`allversions`	Optional: To include all versions or latest version, include a query parameter `allversions=true`. If omitted, defaults to `false`.

Response Details

On SUCCESS, the response includes the following information:

Field Name	Description
`job_id`	The Job ID value to retrieve the status and results of the document export request.
`url`	URL to retrieve the current status of the document export job.

Export Document Version

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--data-binary @"C:\Vault\Documents\export_document_version.json" \
https://myvault.veevavault.com/api/v17.3/objects/documents/versions/batch/actions/fileextract

{
    "responseStatus": "SUCCESS",
    "url": "/api/v19.1/services/jobs/40604",
    "job_id": "40604"
}

Export a specific set of document versions to your Vault’s FTP staging server. The files you export go to the u{userID} folder, regardless of your security profile.

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

Headers

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

Body Parameters

Prepare a JSON input file with the following body parameters:

Name	Description
`id`	ID of the document to export.
`major_version_number__v`	The major version number of the document to export.
`minor_version_number__v`	The minor version number of the document to export.

Query Parameters

Name	Description
`source`	To exclude source files, include a query parameter `source=false`. If omitted, defaults to `true`.
`renditions`	To include renditions, include a query parameter `renditions=true`. If omitted, defaults to `false`.

Response Details

On SUCCESS, the response includes the following information:

Field Name	Description
`url`	URL to retrieve the current status of the document export job.
`job_id`	The Job ID value of the document export request.

Retrieve Document Export Results

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.3/objects/documents/batch/actions/fileextract/{jobid}/results

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 23,
            "major_version_number__v": 0,
            "minor_version_number__v": 1,
            "file": "/82701/23/0_1/New Document.png",
            "user_id__v": 88973
        }
    ]
}

After submitting a request to export documents from your Vault, you can query Vault to determine the results of the request.

Before submitting this request:

You must have previously requested a document export job (via the API) which is no longer active.
You must have a valid job_id value (retrieved from the document export binder request above).
You must be a a Vault Owner, System Admin or the user who initiated the job.

GET /api/{version}/objects/documents/batch/actions/fileextract/{jobid}/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 document requests above.

Response Details

On SUCCESS, the response includes the following information:

Field Name	Description
`job_id`	The Job ID value of the document export request.
`id`	The `id` value of the exported document.
`major_version_number__v`	The major version number of the exported document.
`minor_version_number__v`	The minor version number of the exported document.
`file`	The path on the FTP staging server.
`user_id__v`	The `id` value of the Vault user who initiated the document export job.

Document Events

The Document Events are used to track the document and binder distribution events across sub-systems such as iRep, Controlled Copy, Approved Email and Engage.

Retrieve Document Event Types and Subtypes

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

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

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

Headers

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

Response Details

On SUCCESS, Vault returns the list of events, and event types per each event (if applicable). If the user is not permitted to access the event data, the event type is omitted from the response. In this example, one document event distribution__v is configured in our Vault. This “Distribution Event” is configured with six document event “subtypes”.

Retrieve Document Event SubType Metadata

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

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

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

Headers

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

Response Details

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

Create Document Event

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

{
    "responseStatus": "SUCCESS"
}

POST /api/{version}/objects/documents/{document_id}/versions/{major_version}/{minor_version}/events

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}`	The document `major_version_number__v` field value.
`{minor_version}`	The document `minor_version_number__v` field value.

Response Details

On SUCCESS, Vault logs the document event.

Retrieve Document Events

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

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

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

Headers

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

URI Path Parameters

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

Response Details

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

Document Templates

Learn about Document Templates in Vault Help.

Retrieve Document Template Metadata

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

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

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`

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

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

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "name__v":"claim_document_template__c",
         "label__v":"Claim Document Template",
         "active__v":true,
         "type__v":"claim__c",
         "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__c",
         "subtype__v":"clinical_study__c",
         "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__c",
         "subtype__v":"advertisement__c",
         "classification__v":"print__c",
         "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
         "size__v": 82923,
         "created_by__v": 12021,
         "file_uploaded_by__v": 12021,
         "md5checksum__v": 52478042594365555
      }
   ]
}

Retrieve all document templates.

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

Headers

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

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

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

Retrieve Document Template Attributes

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

{
   "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__c",
         "subtype__v":"advertisement__c",
         "classification__v":"print__c",
         "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
         "size__v": 82923,
         "created_by__v": 12021,
         "file_uploaded_by__v": 12021,
         "md5checksum__v": 52478042594365555
      }
   ]
}

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.

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__c` 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

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

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

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.

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

$ 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__c" \
-F "subtype__v=advertisement__c" \
-F "classification__v=print__c" \
-F "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates

responseStatus,name,errors
SUCCESS,promo_ad_template__c,

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.

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__c.
The template is being set to active__v=true. It will be available for selection when creating a new document.

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

Bulk Create Document Templates

$ 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

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

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.

Response Details

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

$ 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 "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates/promo_ad_print_document_template__c

responseStatus,name,errors
SUCCESS,promo_ad_web_document_template__c,

Update a document template to your Vault.

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

Bulk Update Document Templates

$ 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

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

Update from 1-500 document templates to your Vault.

PUT /api/{version}/objects/documents/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 document templates:

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 binder templates in the UI.
`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 for example inputs, which are the same as those used in this request.

Delete Document Template

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

{
    "responseStatus": "SUCCESS"
}

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.

Document Tokens

$ 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

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

The Vault Document Tokens API allows you to generate 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.

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.

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

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

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

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. By searching the response, you can distinguish binders from 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.

This endpoint does not retrieve binder sections, which means the response will not include binders within other binder sections. To retrieve all metadata configured on a binder, including sections, you must use the binder IDs retrieved from this request in the Retrieve Binder endpoint.

Alternatively, you can use VQL to find just binders SELECT id FROM documents WHERE binder__v=true. See VQL documentation for details.

GET /api/{version}/objects/documents

Headers

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

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 "binder__v": true. This document is a binder.
The second record retrieved "id": 102 has "binder__v": false. This document is a regular document.

Retrieve Binder

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

{
  "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.veevavault.com/api/v15.0/objects/binders/29/versions/0/1"
    },
    {
      "number": "0.2",
      "value": "https://medcomms-veevapharm.veevavault.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"
            }
          }
        ]
      }
    ]
  }
}

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

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.

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.

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

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.

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.

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

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

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

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.

Response Details

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

Retrieve Binder Version

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

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

GET /api/{version}/objects/binders/{binder_id}/versions/(major_version}/{minor_version}

Headers

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

URI Path Parameters

Name	Description
`{binder_id}`	The binder `id` field value.
`{major_version}`	The binder `major_version_number__v` field value.
`{minor_version}`	The binder `minor_version_number__v` field value.

Create Binders

Create Binder

$ 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

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

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 Parameters

All required binder (document) fields must be included in the request. When creating a binder, no file is included in the request.

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.

Create Binder from Template

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

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

$ 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

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

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.

Response Details

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.

Create Binder Version

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

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

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.

Update Binders

Update Binder

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

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

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.

Reclassify Binder

$ 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

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

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

Learn more about:

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

About this Request

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

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.

Update Binder Version

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

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

PUT /api/{version}/objects/binders/{binder_id}/versions/{major_version}/{minor_version}

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}`	The binder `major_version_number__v` field value.
`{minor_version}`	The binder `minor_version_number__v` field value.

Refresh Binder Auto-Filing

$ 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

{
    "responseStatus": "SUCCESS"
}

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.

Delete Binders

Delete Binder

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

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

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.

Delete Binder Version

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

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

DELETE /api/{version}/objects/binders/{binder_id}/versions/{major_version}/{minor_version}

Headers

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

URI Path Parameters

Name	Description
`{binder_id}`	The binder `id` field value.
`{major_version}`	The binder `major_version_number__v` field value.
`{minor_version}`	The binder `minor_version_number__v` field value.

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

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

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Job for Binder Export Started",
  "URL": "https://myvault.veevavault.com/api/v15.0/services/jobs/1201",
  "job_id": 1201
}

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}/{minor_version}/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}`	The binder `major_version_number__v` field value.
`{minor_version}`	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

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.

Export Binder Sections

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

$ 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

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Job for Binder Export Started",
  "URL": "https://myvault.veevavault.com/api/v15.0/services/jobs/1201",
  "job_id": 1201
}

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}/{minor_version}/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}`	The binder `major_version_number__v` field value.
`{minor_version}`	The binder `minor_version_number__v` field value.

Query Parameters

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.

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.

Retrieve Binder Export Results

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

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

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.

Response 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

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

{
    "responseStatus": "SUCCESS",
    "responseMessage": null,
    "errorCodes": null,
    "relationships": [
        {
            "relationship": {
                "source_doc_id__v": 566,
                "relationship_type__v": "supporting_documents__c",
                "created_date__v": "2015-03-24T22:37:20.000Z",
                "id": 202,
                "target_doc_id__v": 254,
                "created_by__v": 46916
            }
        }
    ],
    "errorType": null
}

GET /api/{version}/objects/binders/{binder_id}/versions/{major_version}/{minor_version}/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}`	The binder `major_version_number__v` field value.
`{minor_version}`	The binder `minor_version_number__v` field value.
`{relationship_id}`	The binder relationship `id` field value.

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

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

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

POST /api/{version}/objects/binders/{binder_id}/versions/{major_version}/{minor_version}/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}`	The binder `major_version_number__v` field value.
`{minor_version}`	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.

Delete Binder Relationship

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

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

DELETE /api/{version}/objects/binders/{binder_id}/versions/{major_version}/{minor_version}/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}`	The binder `major_version_number__v` field value.
`{minor_version}`	The binder `minor_version_number__v` field value.
`{relationship_id}`	The binder relationship `id` field value.

Binder Sections

Retrieve Binder Sections

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

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

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

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

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

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

Headers

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

URI Path Parameters

Name	Description
`{binder_id}`	The binder `id` field value.
`{section_id}`	Optional: Retrieve all sections (documents and subsections) in a binder’s sub-level node. If not included, all sections from the binder’s top-level root node will be returned.

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

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

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

For a specific version, retrieve all sections (documents and subsection) in a binder’s top-level root node or sub-level node.

GET /api/{version}/objects/binders/{binder_id}/versions/{major_version}/{minor_version}/sections/{section_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}`	The binder `major_version_number__v` field value.
`{minor_version}`	The binder `minor_version_number__v` field value.
`{section_id}`	Retrieve all sections (documents and subsections) in a binder’s sub-level node. If not included, all sections from the binder’s top-level root node will be returned.

Response Details

See Retrieve Binder Sections response above.

Create Binder Section

$ 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

{
    "responseStatus": "SUCCESS",
    "id": "1427486900128:1467568099"
}

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.

Response Details

On SUCCESS, Vault returns the Node ID of the newly created section. This is unique within the binder, regardless of level.

Update Binder Section

$ 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

{
    "responseStatus": "SUCCESS",
    "id": "1427486900128:1467568099"
}

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.

Response Details

On SUCCESS, Vault returns the Node ID of the newly created section. This is unique within the binder, regardless of level.

Delete Binder Section

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

{
    "responseStatus": "SUCCESS",
    "id": "1427486900128:1467568099"
}

Delete a section from a binder.

DELETE /api/{version}/objects/binders/{binder_id}/sections/{section_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.
`{section_id}`	The binder node `id` field value.

Response Details

On SUCCESS, Vault returns the Node ID of the deleted section.

Binder Documents

Add Document to Binder

$ 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

{
    "responseStatus": "SUCCESS",
    "id": "1427491342404:-1828014479"
}

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 `binding_rule__v=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 `binding_rule__v=specific`, then this is required and indicates the minor version of the document to be linked. Otherwise it is ignored.

Move Document in Binder

$ 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

{
  "responseStatus": "SUCCESS",
  "id": "1457559259279:-602158059"
}

Move a document to a different position within a binder.

PUT /api/{version}/objects/binders/{binder_id}/documents/{section_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.
`{section_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.

Response Details

On SUCCESS, Vault returns the new node ID of the document.

Remove Document from Binder

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

{
    "responseStatus": "SUCCESS",
    "id": "1427491342404:-1828014479"
}

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

Headers

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

URI Path Parameters

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

Response Details

On SUCCESS, Vault returns the Node ID of the deleted document.

Binder Templates

Learn about Binder Templates in Vault Help.

Retrieve Binder Template Metadata

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

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

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`

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.

Name	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

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

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

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`

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

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

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

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`

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

$ 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

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

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.

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

$ 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

{
    "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__c",
            "type__v": "trial_management__c",
            "subtype__v": "trial_oversight__c",
            "classification__v": "operational_procedure_manual__c"
        },
        {
            "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__c",
            "type__v": "trial_management__c",
            "subtype__v": "trial_oversight__c",
            "classification__v": "recruitment_plan__c"
        },
        {
            "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__c",
            "type__v": "trial_management__c",
            "subtype__v": "general__c",
            "classification__v": "tracking_information__c"
        },
        {
            "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__c",
            "type__v": "trial_management__c",
            "subtype__v": "general__c",
            "classification__v": "filenote__c"
        },
        {
            "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__c",
            "type__v": "central_trial_documents__c",
            "subtype__v": "trial_documents__c",
            "classification__v": "protocol__c"
        },
        {
            "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__c",
            "type__v": "central_trial_documents__c",
            "subtype__v": "subject_documents__c",
            "classification__v": "subject_information_sheet__c"
        },
        {
            "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__c",
            "type__v": "site_management__c",
            "subtype__v": "site_selection__c",
            "classification__v": "confidentiality_agreement__c"
        },
        {
            "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__c",
            "type__v": "site_management__c",
            "subtype__v": "site_selection__c",
            "classification__v": "site_contact_details__c"
        }
    ]
}

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.

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

$ 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__c" \
-d "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "name__v":"claim_binder_template__c"
      }
   ]
}

Create a new binder template in your Vault.

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.

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

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

Bulk Create Binder Templates

$ 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

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

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

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.

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 Details

On SUCCESS, Vault returns the names of the new binder templates.

Create Binder Template Node

$ 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

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.

Body Parameters

When creating binder template nodes, the following fields are required in all Vaults:

Name	Description
`id`	The ID of the binder node. This must be set to a unique number.
`parent_id__v`	[Required] Enter the `id` of the parent section. To create a node in the top level of the binder (rootNode), leave the value blank.
`node_type__v`	[Required] Set to `section` or `planned_document`.
`label__v`	Label for the section or planned document. For planned documents, this corresponds to “Planned Name” in the UI.
`type__v`	The name of the document type to which the template will be associated.
`subtype__v`	The name of the document subtype to which the templates will be associated. This is only required if associating the template with a document subtype.
`classification__v`	The name of the document classification to which the template will be associated. This is only required if associating the template with a document classification.
`active__v`	Set to true or false to indicate whether or not the binder template should be set to active, i.e., available for selection when creating a binder.
`order__v`	Order of the component (planned document or section) within the binder template or within the template section. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.

Example CSV Input: Create Top-Level Section Binder Nodes

`id`	`node_type__v`	`label__v`	`order__v`	`number__v`
100	section	Folder A	1	01
200	section	Folder B	2	02
300	section	Folder C	3	03

In this example input, we’re creating three new binder nodes in the template.

These will be new section node types.
The required parent_id__v name is included but its value left blank. By default, the new sections will be added to the top-level in the binder hierarchy.
The optional section order and number are set. These define the position of the three new sections in the binder template hierarchy.

Example CSV Input: Create Sub-Level Section Binder Nodes

`id`	`node_type__v`	`label__v`	`order__v`	`number__v`	`parent_id__v`
101	section	SubFolder A1	1	01.01	100
102	section	SubFolder A2	2	01.02	100

In this example input, we’re creating three new binder nodes in the template.

These will be new section node types.
The required parent_id__v name is included. If the values are left blank, the new sections will be added to the top-level in the binder hierarchy by default.
The optional section order and number are set. These define the position of the three new sections in the binder template hierarchy.

Example CSV Input: Create Planned Document Binder Node

`id`	`node_type__v`	`label__v`	`order__v`	`parent_id__v`	`type__v`	`subtype__v`	`classification__v`	`lifecycle__v`
101PD	planned_document	Planned Document A1	1	101	promotional_piece__vs	advertisement__vs	web__vs	promotional_piece__vs

In this example input, we’re creating new binder node of the type planned_document.

The required parent_id__v name is included. If the values are left blank, the planned document will be added to the top-level in the binder hierarchy by default.
The optional section order and number are set. These define the position of the planned document in the binder template hierarchy.

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

$ 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

responseStatus,name,errors
SUCCESS,binder_template_1__c,

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.

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 Details

On SUCCESS, Vault returns the name of the updated binder template.

Bulk Update Binder Templates

$ 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

responseStatus,name,errors
SUCCESS,binder_template_2__c,
SUCCESS,binder_template_3__c,
SUCCESS,binder_template_4__c,

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.

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 Details

On SUCCESS, Vault returns the names of the updated binder templates.

Replace Binder Template Nodes

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

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.

Delete Binder Template

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

{
    "responseStatus": "SUCCESS"
}

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.

Binding Rules

Learn about Version Binding in Vault Help.

Update Binding Rule

$ 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

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

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.

Body Parameters

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.

Update Binder Section Binding Rule

$ 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

{
    "responseStatus": "SUCCESS",
    "id": "1427491342404:-1828014479"
}

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.

Body Parameters

Name Description

Response Details

On SUCCESS, Vault returns the Node ID of the updated section.

Update Binder Document Binding Rule

$ 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

{
  "responseStatus": "SUCCESS",
  "id": "1427491342404:-1828014479"
}

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.

Body Parameters

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 `binding_rule__v=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 `binding_rule__v=specific`, then this is required and indicates the major version of the document to be linked. Otherwise it is ignored.

Response Details

On SUCCESS, Vault returns the Node ID of the updated document node within the binder

Vault 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

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

{
  "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,
        "na