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.

After acquiring a Vault Session ID, include it on every subsequent API call inside the Authorization HTTP request header.

Basic Authorization

Name Description
Authorization {sessionId}

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

The Vault API also accepts Vault Session IDs as Bearer tokens. Include Bearer keyword to send Vault Session IDs with as bearer tokens:

Bearer Token Authorization

Name Description
Authorization Bearer {sessionId}

User Name and Password

Request

$ curl -X POST https://myvault.veevavault.com/api/v18.3/auth \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "username={username}&password={password}"

Response

{
  "responseStatus": "SUCCESS",
  "sessionId": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 1776,
      "name": "PromoMats",
      "url": "https://promomats-veevapharm.veevavault.com/api"
    },
    {
      "id": 1777,
      "name": "eTMF",
      "url": "https://etmf-veevapharm.veevavault.com/api"
    },
    {
      "id": 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
usernamerequired Your Vault user name assigned by your administrator.
passwordrequired Your Vault password associated with your assigned Vault user name.
vaultDNSoptional 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:

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

OAuth 2.0 / OpenID Connect

Request

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

Response

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

Authenticate your account using OAuth 2.0 / Open ID Connect token to obtain a Vault Session ID. Learn more about OAuth 2.0 / Open ID Connect in Vault Help.

When requesting a sessionId, Vault allows the ability for Oauth2/OIDC client applications to pass the client_id with the request. Vault uses this client_id when talking with the introspection endpoint at the authorization server to validate that the access_token presented by the application is valid. Learn more about Client ID in the REST API Documentation.

POST https://login.veevavault.com/auth/oauth/session/{oath_oidc_profile_id}

Headers

Name Description
Content-Type application/x-www-form-urlencoded
Authorization Bearer {access_token}
Accept application/json (default)

URI Path Parameters

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

Body Parameters

Name Description
vaultDNSoptional The DNS of the Vault for which you want to generate a session. If omitted, the session is generated for the user’s most relevant available Vault.
client_idoptional The ID of the client application at the Authorization server.

Retrieve API Versions

Request

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

Response

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

Authentication Type Discovery

Request

$ curl -X POST \
-H "Accept: application/json" \
-H "X-VaultAPI-AuthIncludeMsal: true" \
https://login.veevavault.com/auth/discovery?username=olivia@veepharm.com&client_id=veepharm-clinical-it-client-int0

Response: Password User

{
    "responseStatus": "SUCCESS",
    "errors": [],
    "data": {
        "auth_type": "password"
    }
}

Response: SSO User

{
"responseStatus": "SUCCESS",
   "errors": [],
   "data": {
       "auth_type": "sso",
       "auth_profiles": [
           {
               "id": "_a45afc-4773-4e17-9831-2905b2a6",
               "label": "OAuth Azure",
               "description": "This Security Profile connects with Microsoft Azure.",
               "vault_session_endpoint": "https://veepharm.com/auth/oauth/session/_a45a10fc-4773-290ab2a6",
               "use_adal": true,
               "use_msal": true,
               "as_metadata": {
                   "token_endpoint": "https://login.microsoftonline.com/dcf3-468/oauth2/v2.0/token",
                   "token_endpoint_auth_methods_supported": [
                       "client_secret_post",
                       "private_key_jwt",
                       "client_secret_basic"
                   ],
                   "jwks_uri": "https://login.microsoftonline.com/4618-934/discovery/v2.0/keys",
                   "response_modes_supported": [
                       "query",
                       "fragment",
                       "form_post"
                   ],
                   "subject_types_supported": [
                       "pairwise"
                   ],
                   "id_token_signing_alg_values_supported": [
                       "RS256"
                   ],
                   "response_types_supported": [
                       "code",
                       "id_token",
                       "code id_token",
                       "id_token token"
                   ],
                   "scopes_supported": [
                       "openid",
                       "profile",
                       "email",
                       "offline_access"
                   ],
                   "issuer": "https://login.microsoftonline.com/7c5d9e-53443/v2.0",
                   "request_uri_parameter_supported": false,
                   "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
                   "authorization_endpoint": "https://login.microsoftonline.com/7c3-9343/oauth2/v2.0/authorize",
                   "device_authorization_endpoint": "https://login.microsoftonline.com/57-618-954-543/oauth2/v2.0/devicecode",
                   "http_logout_supported": true,
                   "frontchannel_logout_supported": true,
                   "end_session_endpoint": "https://login.microsoftonline.com/7c577a96e043/oauth2/v2.0/logout",
                   "claims_supported": [
                       "cloud_instance_name",
                       "cloud_instance_host_name",
                       "cloud_graph_host_name",
                       "msgraph_host",
                       "auth_time",
                       "nonce",
                       "preferred_username",
                       "name",
                       "email"
                   ],
                   "kerberos_endpoint": "https://login.microsoftonline.com/7c5-556343/kerberos",
                   "tenant_region_scope": "NA",
                   "cloud_instance_name": "microsoftonline.com",
                   "cloud_graph_host_name": "graph.windows.net",
                   "msgraph_host": "graph.microsoft.com",
                   "rbac_url": "https://pas.windows.net"
               },
               "oauthProviderType": "Azure"
           }
       ]
   }
}

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

POST https://login.veevavault.com/auth/discovery

Headers

Name Description
Accept application/json (default)
X-VaultAPI-AuthIncludeMsal Set to true to include information about MSAL, an authentication library available for some SSO profiles. If omitted, the response does not include MSAL information.

Query Parameters

Name Description
username The user’s Vault user name.
client_id Optional: The user’s mapped Authorization Server client_id. This only applies the SSO and OAuth / OpenID Connect Profiles auth_type. Learn more about Client ID in the REST API Documentation.

Response Details

The response specifies the user’s authentication type (auth_type):

SSO Security Policy

If the user’s auth_type type is sso, the response specifies the user’s authentication profiles (auth_profiles). If the user’s Security Policy is associated with:

auth_profiles

The auth_profiles array contains information about the OAuth 2.0 / OpenID Connect Security Policy configured in the Vault UI by your Vault Administrator.

Name Description
id The security policy ID.
label The label for this security profile, displayed to Admins in the Vault UI.
use_adal If true, indicates ADAL is available for use as an authentication library. For example, if the Authorization Server Provider is set to use ADFS or Azure, the use_adal field will appear in the response as true.
use_msal If true, indicates MSAL is available for use as an authentication library. If multiple libraries are available, best practice is to use MSAL. This field is included in the response only if the X-VaultAPI-AuthIncludeMsal header is set to true in the initial request.
as_metadata Information about the AS Metadata uploaded by your Vault Administrator during profile configuration.
oauthProviderType The configured Authorization Server Provider. For example, ADFS or Okta.
Client ID

If the user provides a client_id and Client Application client ID mapping is defined on the OAuth 2.0 / OpenID Connect profile, the as_client_id field will appear in the response with the Authorization Server client ID value. If there is no defined mapping for the specified client_id, Vault will not include the as_client_id field in the response. Learn about Client ID Mapping in Vault Help.

Session Keep Alive

Request

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

Response

{
   "responseStatus": "SUCCESS"
}

Given an active sessionId, keep the session active by refreshing the session duration.

A Vault session is considered active as long as some activity (either through the UI or API) happens within the maximum inactive session duration. This maximum inactive session duration varies by Vault and is configured by your Vault Admin. The maximum active session duration is 48 hours, which is not configurable. Learn more about best practices for session management.

POST /api/{version}/keep-alive

Headers

Name Description
Accept application/json (default) or application/xml
Authorization The Vault sessionId to keep active.

Validate Session User

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "users": [
        {
            "user": {
                "user_name__v": "mmurray@veepharm.com",
                "user_first_name__v": "Megan",
                "user_last_name__v": "Murray",
                "user_email__v": "mmurray@veepharm.com",
                "user_timezone__v": "America/Los_Angeles",
                "user_locale__v": "en_US",
                "user_title__v": "",
                "office_phone__v": "8675309",
                "fax__v": "8675309",
                "mobile_phone__v": "8675309",
                "site__v": "",
                "is_domain_admin__v": true,
                "active__v": true,
                "domain_active__v": true,
                "security_policy_id__v": 1863,
                "user_needs_to_change_password__v": false,
                "id": 61579,
                "created_date__v": "2015-10-22T15:05:00.000Z",
                "created_by__v": 1,
                "modified_date__v": "2020-04-30T14:18:14.000Z",
                "modified_by__v": 1,
                "domain_id__v": 3826,
                "domain_name__v": "veepharm.com",
                "vault_id__v": [
                    19523,
                    21556
                ],
                "federated_id__v": "",
                "salesforce_user_name__v": "",
                "last_login__v": "2020-08-28T22:20:30.000Z",
                "medidata_uuid__v": "",
                "user_language__v": "en",
                "company__v": "VeevaPharm",
                "group_id__v": [
                    1392631750202,
                    1392631750801
                ],
                "security_profile__v": "vault_owner__v",
                "license_type__v": "full__v",
                "vault_membership": [
                    {
                        "active__v": true,
                        "security_profile__v": "vault_owner__v",
                        "id": 19523,
                        "license_type__v": "full__v"
                    },
                    {
                        "active__v": true,
                        "security_profile__v": "vault_owner__v",
                        "id": 21556,
                        "license_type__v": "full__v"
                    }
                ],
                "app_licensing": [
                    {
                        "vault_id": 21556,
                        "application__v": "clinicalSsu_v",
                        "active__v": true,
                        "license_type__v": "full__v"
                    },
                    {
                        "vault_id": 21556,
                        "application__v": "clinicalCtms_v",
                        "active__v": true,
                        "license_type__v": "full__v"
                    }
                ]
            }
        }
    ]
}

Given a valid session ID, this request returns information for the currently authenticated user. If the session ID is not valid, this request returns an INVALID_SESSION_ID error type. This is similar to a whoami request.

GET /api/{version}/objects/users/me

Headers

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

Query Parameters

Name Description
exclude_vault_membershipoptional Set to false to include vault_membership fields. If omitted, defaults to true and vault_membership fields are not included in the response. As a best practice to increase performance, please use the default setting and do not set this parameter to false unless you need these fields.
exclude_app_licensingoptional Set to false to include app_licensing fields. If omitted, defaults to true and app_licensing fields are not included in the response. As a best practice to increase performance, please use the default setting and do not set this parameter to false unless you need these fields.

Response Details

On SUCCESS, this request returns information for the currently authenticated user, such as user_name__v and vault_id__v. If the session ID is not valid, this request returns an INVALID_SESSION_ID error type.

If the currently authenticated user is in a delegated session, this request returns a delegate_user_id. For example, if Sophia initiated a delegated session on behalf of Megan, this API call would display Megan’s id and Sophia’s delegate_user_id.

End Session

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.1/session

Response

{
"responseStatus": "SUCCESS"
}

Given an active sessionId, inactivate an API session. If a user has multiple active sessions, inactivating one session does not inactivate all sessions for that user. Each session has its own unique sessionId.

DELETE /api/{version}/session

Headers

Name Description
Accept application/json (default) or application/xml
Authorization The Vault sessionId to end.

Salesforce™ Delegated Requests

Request

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

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:

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.

Delegated Access

Vault’s delegated access feature provides a secure and audited process for you to designate another user to handle Vault responsibilities on your behalf. Vault tracks all activities performed by the delegate and logs their activities in audit trails that meet compliance standards. Learn more about delegated access in Vault Help.

With the Vault REST API’s delegated access endpoints, you can generate a delegated session ID for any Vaults where you have delegate access. This allows you to call the Vault REST API on behalf of any user who granted you delegate access. For example, a user may grant delegate access to an IT professional for help troubleshooting a problem. Your organization may also utilize delegate access for shared accounts, such as a “Migration User.”

Delegation is Vault-specific: If your IT professional needs access to both your PromoMats and Submissions Vaults, you will need to grant them delegate access in both Vaults.

Retrieve Delegations

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "delegated_vaults": [
       {
           "id": 19523,
           "name": "PromoMats",
           "dns": "mypromomatsvault.veevavault..com",
           "delegator_userid": "61579"
       }
   ]
}

Retrieve Vaults where the currently authenticated user has delegate access. You can then use this information to Initiate a Delegated Session.

GET /api/{version}/delegation/vaults

Headers

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

Response Details

On SUCCESS, Vault returns the name, Vault ID, DNS, and user ID for any Vaults the authenticated user has delegate access to. If the response is empty, the authenticated user does not have delegate access to any Vaults.

Initiate Delegated Session

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-d "vault_id=5791" \
-d "delegator_userid=67899" \
https://myvault.veevavault.com/api/v22.3/delegation/login

Response

{
   "responseStatus": "SUCCESS",
   "delegated_sessionid": "1C8DBD593EDCEAD647E5E4C97A438F1F43A25C8679BB8431BDC789BC0BAAE76E0DC42D478721624765A2BA2E923852"
}

Generate a delegated session ID. This allows you to call the Vault REST API on behalf of a user who granted you delegate access. To find which users have granted you delegate access, Retrieve Delegations.

POST /api/{version}/delegation/login

Headers

Name Description
Authorization The sessionId of the currently authenticated user who will initiate the delegated session. Cannot be a delegated_sessionid.
Accept application/json (default) or application/xml

Body Parameters

Name Description
vault_idrequired The id value of the Vault to initiate the delegated session.
delegator_useridrequired The ID of the user who granted the authenticated user delegate access in this Vault.

Response Details

On SUCCESS, Vault returns a delegated_sessionid. To execute REST API calls with this delegated session, use this delegated_sessionid value as the Authorization header value.

Domain Information

Retrieve Domain Information

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v18.1/objects/domain?include_application=true

Response

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

Query Parameters

Name Description
include_application To include Vault application type information in the response, set include_application to true. If omitted, defaults to false and application information is not included.

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). This information only appears if the include_application query parameter is set to true.
vault_family__v Contains information about the application family each Vault belongs to (Commercial, Clinical Operations, Regulatory, or Quality), such as name and label.

Retrieve Domains

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.veevavault.com/api/v18.3/objects/domains

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "domains": [
        {
            "name": "veepharm.com",
            "type": "Production"
        },
        {
            "name": "veepharm-sbx.com",
            "type": "Sandbox"
        }
    ]
}

Non-domain Admins can use this request to retrieve a list of all their domains, including the domain of the current Vault. You can use this data as a valid domain value when creating a sandbox Vault.

GET /api/{version}/objects/domains

Headers

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

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

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "X-VaultAPI-DescribeQuery: true" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
--data-urlencode "q=SELECT id, name__v FROM documents WHERE product__v = ‘cholecap’"
https://myvault.veevavault.com/api/v21.1/query

Response

{
   "responseStatus": "SUCCESS",
   "queryDescribe": {
       "object": {
           "name": "documents",
           "label": "documents",
           "label_plural": "documents"
       },
       "fields": [
           {
               "type": "id",
               "required": true,
               "name": "id"
           },
           {
               "label": "Name",
               "type": "String",
               "required": true,
               "name": "name__v",
               "max_length": 100
           }
       ]
   },
   "responseDetails": {
       "pagesize": 1000,
       "pageoffset": 0,
       "size": 5,
       "total": 5
   },
   "data": [
       {
           "id": 72,
           "name__v": "Cholecap-2021-brochure"
       },
       {
           "id": 63,
           "name__v": "Cholecap - Multisequence"
       },
       {
           "id": 36,
           "name__v": "Cholecap Study"
       },
       {
           "id": 25,
           "name__v": "Clinical Trial Reference"
       },
       {
           "id": 24,
           "name__v": "Formulary Guidelines"
       }
   ]
}

VQL queries go to the /query REST interface.

POST /api/{version}/query

Headers

Name Description
Accept application/json (default) or application/xml
Content-Type application/x-www-form-urlencoded or multipart/form-data
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. Learn More.
X-VaultAPI-RecordProperties Optional: If present, the response includes the record properties object. Possible values are all, hidden, redacted, and weblink. If omitted, the record properties object is not included in the response. Learn more.

Body Parameters

Name Description
qrequired Place your query of up to 50,000 characters in the body of your request. Note that, while the API also allows you to submit your query as a query parameter, doing so may cause you to exceed the maximum URL length. Queries should be formatted as q={query}. For example, q=SELECT id FROM documents.

Response Details

On SUCCESS, the response includes the following information:

Name Description
pagesize The number of records displayed per page. This can be modified. Learn more.
pageoffset 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 The name of the field.
label The UI label of the field.
type The data type, for example, String or Number
max_length The max length of a string field.
max_value The max value of 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 whether the field is required (true/false).
unique Indicates whether the value must be unique (true/false).
status Indicates whether the field is active (active/inactive).
picklist The picklist name field value.
encrypted Indicates whether the Contains Protected Health Information (PHI) or Personally Identifiable Information (PHI) setting is selected for this field (true/false). Learn more in Vault Help.
format_mask The format mask expression if it exists. Learn more about format masks in Vault Help.
function The function name if the VQL query applies a function to this field.
alias If true, the VQL query applies an alias to this field. Omitted if false.

Note: For formula fields, queryDescribe should describe the field as specified in the metadata, excluding the formula attribute.

About the X-VaultAPI-RecordProperties Header

When you include the X-VaultAPI-RecordProperties header, the query response includes the record_properties object. The record_properties object describes the properties of a data record. If set to all, for each record, the response includes:

Name Description
id The record ID.
field_properties Includes arrays of hidden, editable (edit), and redacted fields. To return only hidden or redacted fields, set the X-VaultAPI-RecordProperties header to hidden or redacted, respectively.
permissions Includes whether this record has read, edit, create, and delete permissions.
subquery_properties Includes an array of hidden subquery relationships for this record.
field_additional_data Includes configuration data for link type formula fields. To return only this data, set the X-VaultAPI-RecordProperties header to weblink.

For each field, the field_additional_data metadata includes the name of the field and the web_link object, which contains the following metadata:

Metadata Field Description
label The text that appears as a link in the Vault UI.
target Determines whether the link will open in a new_window or the same_window.
connection Populates another Vault’s DNS within the URL utilizing a configured connection__sys object record.

About the X-VaultAPI-Facets Header

When you include the X-VaultAPI-Facets header with a list of facetable fields, the response includes the facets object containing the count of unique values for each facetable field. Determine which fields are facetable using the Retrieve Object Metadata API. For each facetable field included in the header, the response includes:

Name Description
label The label for the facetable field in the Vault UI.
type The field’s data type.
name The name of the facetable field.
count The number of unique values for this field in the Vault.
truncated_list A boolean indicating that the list is truncated because it contains more than 50 values.

The values metadata contains the unique values for the facetable field in the Vault, sorted first by result_count and secondly by value.

Metadata Field Description
value A value of this facetable field in the Vault. For example, ophthalmology__c.
result_count The number of records with this field value in the Vault.

Metadata Definition Language (MDL)

Vault is configured with a set of component types that make up its configuration elements. Use MDL to create, describe (read), update, and drop (delete) Vault components and manage its configuration. Learn more in our MDL documentation.

Execute MDL Script

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
--data-binary @"mdl.txt" \
https://myvault.veevavault.com/api/mdl/execute

Example Body: RECREATE Picklist

RECREATE Picklist color__c (
   label('Color'),
   active(true),
   Picklistentry red__c(
      value('Red'),
      order(1),
      active(true)
   ),
   Picklistentry blue__c(
      value('Blue'),
      order(2),
      active(true)
   ),
   Picklistentry green__c(
      value('Green'),
      order(3),
      active(true)
   )
);

Example Body: RECREATE Java SDK Trigger

RECREATE Recordtrigger my_custom_trigger_name__c (
active (true),
source_code (<VeevaData>
...
</VeevaData>)
);

Response: RECREATE Picklist

{
    "responseStatus": "SUCCESS",
    "script_execution": {
        "code": "GEN-S-0",
        "message": "OK",
        "warnings": 0,
        "failures": 0,
        "exceptions": 0,
        "components_affected": 1,
        "execution_time": 0.028
    },
    "statement_execution": [
        {
            "vault": "promo-vee.vaultdev.com",
            "statement": 1,
            "command": "RECREATE",
            "component": "Picklist.color__c",
            "message": "[SUCCESS] RECREATE Picklist color__c",
            "response": "SUCCESS"
        }
    ]
}

This synchronous endpoint executes the given MDL script on a Vault. Note that some large operations require use of the asynchronous endpoint.

POST /api/mdl/execute

Headers

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

Body Parameters

The body of the request should contain the MDL script to execute. Enter the body as raw data. The body must start with one of the following values:

Learn more in the MDL Commands documentation.

Example Body: RECREATE Picklist

In this example, we update our picklists using the RECREATE command. If a picklist exists with the name color__c, Vault updates it to conform to the definition provided. If not, Vault creates a new picklist with the definition provided.

Response Details

On SUCCESS, the response contains details of the execute.

Execute MDL Script Asynchronously

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
--data-binary @"raw_object.txt" \
https://myvault.veevavault.com/api/mdl/execute_async

Example Body: RECREATE Picklist

RECREATE Picklist color__c (
   label('Color'),
   active(true),
   Picklistentry red__c(
      value('Red'),
      order(1),
      active(true)
   ),
   Picklistentry blue__c(
      value('Blue'),
      order(2),
      active(true)
   ),
   Picklistentry green__c(
      value('Green'),
      order(3),
      active(true)
   )
);

Response

{
   "responseStatus": "SUCCESS",
   "script_execution": {
       "code": "GEN-S-0",
       "message": "OK",
       "warnings": 0,
       "failures": 0,
       "exceptions": 0,
       "components_affected": 1,
       "execution_time": 0.622
   },
   "job_id": 327103,
   "url": "/api/v20.3/services/jobs/327103"
}

This asynchronous endpoint executes the given MDL script on a Vault.

While you can execute any MDL script with this endpoint, it is required if you’re operating on 10,000+ raw object records and executing one of the following operations:

After initiating this request, your raw object’s configuration_state becomes IN_DEPLOYMENT. While a raw object is IN_DEPLOYMENT, you cannot edit its fields, list layouts, or indexes. If your raw object deployment request has not yet begun execution, you can cancel the deployment.

This endpoint can only queue one asynchronous change at a time. If you have multiple requests, you must wait for the previous request to complete or use a VPK.

POST /api/mdl/execute_async

Headers

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

Body Parameters

The body of the request should contain the MDL script to execute. Enter the body as raw data. The body must start with one of the following values:

Learn more in the MDL Commands documentation.

Response Details

On SUCCESS, the response includes the following information:

Name Description
job_id The Job ID value to retrieve the status and results of this request. Use this ID to query for the job status and results.
url URL to retrieve the current job status of this request.
code The response code indicating whether the script has passed or failed syntax validation.
message A descriptive message for any warnings, failures, or exceptions. If there are none, returns OK.
warnings The number of warnings received while validating the script syntax.
failures The number of errors received while validating the script syntax.
exceptions The number of exceptions received while validating the script syntax.
components_affected The number of components affected by this script.
execution_time The length of time taken to validate this script syntax, in milliseconds.

Retrieve Asynchronous MDL Script Results

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "script_execution": {
       "code": "GEN-S-0",
       "message": "OK",
       "warnings": 0,
       "failures": 0,
       "exceptions": 0,
       "components_affected": 1,
       "execution_time": 1.585
   },
   "statement_execution": [
       {
           "vault": "dev10platform.vaultdev.com",
           "statement": 1,
           "command": "ALTER",
           "component": "Object.10k_raw__c",
           "message": "[SUCCESS] ALTER Object 10k_raw__c",
           "response": "SUCCESS"
       }
   ]
}

After submitting a request to deploy an MDL script asynchronously, you can query Vault to determine the results of the request.

Before submitting this request:

GET /api/mdl/execute_async/{job_id}/results

Headers

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

URI Path Parameters

Name Description
{job_id} The job_id field value returned from the Execute MDL Script Asynchronously request.

Response Details

On SUCCESS, this endpoint returns the results of the asynchronous MDL script execution, including any errors.

Cancel Raw Object Deployment

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.3/metadata/vobjects/product__c/actions/canceldeployment

Response

{
   "responseStatus": "SUCCESS"
}

Cancel a deployment of configuration changes to a raw object. To use this endpoint, your raw object configuration_state must be IN_DEPLOYMENT.

POST /api/{version}/metadata/vobjects/{object_name}/actions/canceldeployment

Headers

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

URI Path Parameters

Name Description
{object_name} The name of the object on which to cancel deployment. This object’s configuration_state must be IN_DEPLOYMENT.

Response Details

If the deployment is cancelled successfully, the API returns SUCCESS.

Retrieve All Component Metadata

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
       {
           "url": "/api/v22.2/metadata/components/Securityprofile",
           "name": "Securityprofile",
           "class": "metadata",
           "abbreviation": "SPR",
           "active": true,
           "label": "Security Profile",
           "label_plural": "Security Profile"
       },
       {
           "url": "/api/v22.2/metadata/components/Tab",
           "name": "Tab",
           "class": "metadata",
           "abbreviation": "TAB",
           "active": true,
           "label": "Tab",
           "label_plural": "Tab",
           "vobject": "vof_tab_sys"
       }
   ]
}

Retrieve metadata of all component types in your Vault.

GET /api/{version}/metadata/components

Headers

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

Response Details

On SUCCESS, the response may include the following for each component type in the currently authenticated Vault:

Name Description
url URL to retrieve metadata for the component type.
name The component type name as used in MDL commands.
class The class of the component type, either code for component types that include SDK source code, or metadata for component types that do not include SDK source code.
abbreviation The abbreviated component type name.
label The component type label as it appears in the Vault UI.
label_plural The plural component type label as it appears in the Vault UI.
cacheable Indicates whether or not the component type has a cache.
cache_type_class Indicates the caching strategy used by the component type. If cacheable is set to false, Vault ignores this value.
vobject The associated Vault object, if applicable.

Retrieve Component Type Metadata

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "Picklist",
        "class": "metadata",
        "abbreviation": "PIL",
        "active": true,
        "attributes": [
            {
                "name": "label",
                "type": "String",
                "requiredness": "required",
                "max_length": 40,
                "editable": true,
                "multi_value": false
            },
            {
                "name": "active",
                "type": "Boolean",
                "requiredness": "required",
                "editable": false,
                "multi_value": false
            }
        ],
        "sub_components": [
            {
                "name": "Picklistentry",
                "json_collection_name": "Picklistentry",
                "attributes": [
                    {
                        "name": "value",
                        "type": "String",
                        "requiredness": "required",
                        "max_length": 128,
                        "editable": true,
                        "multi_value": false
                    },
                    {
                        "name": "order",
                        "type": "Number",
                        "requiredness": "required",
                        "max_value": 9223372036854775807,
                        "min_value": 0,
                        "scale": 0,
                        "editable": true,
                        "multi_value": false
                    },
                    {
                        "name": "active",
                        "type": "Boolean",
                        "requiredness": "required",
                        "editable": false,
                        "multi_value": false
                    }
                ]
            }
        ]
    }
}

Retrieve metadata of a specific component type.

GET /api/{version}/metadata/components/{component_type}

Headers

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

URI Path Parameters

Name Description
{component_type} The component type name (Picklist, Docfield, Doctype, etc.).

Response Details

On SUCCESS, the response contains metadata for the specified component type. Metadata returned varies for each component and subcomponent type. See Component Types for more information.

Note that some attributes return a default_cap value. This is the default edibility of a field and is for internal Veeva use only.

Retrieve Component Records

Component Record Collection

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "name": "color__c",
            "label": "Color",
            "Picklistentry": [
                {
                    "name": "red__c",
                    "value": "Red",
                    "order": 1,
                    "active": true
                },
                {
                    "name": "blue__c",
                    "value": "Blue",
                    "order": 2,
                    "active": true
                },
                {
                    "name": "green__c",
                    "value": "Green",
                    "order": 3,
                    "active": true
                }
            ],
            "active": true,
            "used_in": []
        }
    ]
}

Retrieve all records for a specific component type.

This endpoint does not support retrieving Object component records. Instead, use Retrieve Object Collection.

GET /api/{version}/configuration/{component_type}

Headers

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

URI Path Parameters

Name Description
{component_type} The component type name (Picklist, Docfield, Doctype, etc.). To retrieve records for Object, see Retrieve Object Collection.

Response Details

On SUCCESS, the response contains all component records in the Vault for the specified component type. Each component record returns a minimum of API name and UI label, but most types return more. Complete details of the component can be retrieved using Retrieve Component Record or MDL.

Retrieve Component Record (XML/JSON)

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "color__c",
        "label": "Color",
        "Picklistentry": [
            {
                "name": "red__c",
                "value": "Red",
                "order": 1,
                "active": true
            },
            {
                "name": "blue__c",
                "value": "Blue",
                "order": 2,
                "active": true
            },
            {
                "name": "green__c",
                "value": "Green",
                "order": 3,
                "active": true
            }
        ],
        "active": true,
        "used_in": []
    }
}

Retrieve metadata of a specific component record as JSON or XML. To retrieve as MDL, see Retrieve Component Record MDL. Not all component types are eligible for record description retrieval. For details, see the Describe column in the Component Support Matrix.

GET /api/{version}/configuration/{component_type_and_record_name}

Headers

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

URI Path Parameters

Name Description
{component_type_and_record_name} The component type name (Picklist, Docfield, Doctype, etc.) followed by the name of the record from which to retrieve metadata. The format is {Componenttype}.{record_name}. For example, Picklist.color__c. Find this with the Retrieve Component Record Collection endpoint.

Query Parameters

Name Description
loc When localized (translated) strings are available, retrieve them by setting loc to true.

Response Details

On SUCCESS, the response contains the complete definition for a specific component record. If a field returns as blank or null, it means the record has no value for that field.

Retrieve Component Record (MDL)

Request

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

Response

RECREATE Picklist color__c (
   label('Color'),
   active(true),
   Picklistentry red__c(
      value('Red'),
      order(1),
      active(true)
   ),
   Picklistentry blue__c(
      value('Blue'),
      order(2),
      active(true)
   ),
   Picklistentry green__c(
      value('Green'),
      order(3),
      active(true)
   )
);

Retrieve metadata of a specific component record as MDL. To retrieve as JSON or XML, see Retrieve Component Record. Vault does not generate RECREATE statements for all component types. For details, see the Generate RECREATE column in the Component Support Matrix.

GET /api/mdl/components/{component_type_and_record_name}

Headers

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

URI Path Parameters

Name Description
{component_type_and_record_name} The component type name (Picklist, Docfield, Doctype, etc.) followed by the name of the record from which to retrieve metadata. The format is {Componenttype}.{record_name}. For example, Picklist.color__c. Find this with the Retrieve Component Record Collection endpoint.

Response Details

On SUCCESS, the response contains a RECREATE MDL statement of metadata for the specified component record. Metadata returned varies based on component type. If a field returns as blank, it means the record currently has no value for that field. Execute this RECREATE with the Execute endpoint.

Components with Content

The following Vault component types contain binary content as part of their definition:

The following endpoints allow you to upload, reference, and migrate the binary content of a file.

Upload Content File

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F 'file=@C:\Quote.pdf'
https://myvault.veevavault.com/api/mdl/files

Response

{
  "responseStatus": "SUCCESS",
  "data": {
      "name__v": "4be398c32fc2ccf48adaf6ebe53782a1",
      "format__v": "application/pdf",
      "size__v": 4716,
      "sha1_checksum__v": "4be398c32fc2ccf48adaf6ebe53782a1"
         }
    }

This endpoint allows you to upload a content file to be referenced by a component.

Once uploaded, Vault stores the file in a generic files staging area where they will remain until referenced by a component. Once referenced, Vault cannot access the named file from the staging area.

POST /api/mdl/files

Headers

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

Response Details

On SUCCESS, the response includes the following:

Name Description
name__v The name of the file which can be used in MDL for referencing the component.
format__v The format of the file.
size__v The file size of the file.
sha1_checksum__v The SHA-1 checksum value generated for the file. Use the checksum to ensure the file was transmitted correctly.

Reference Named File

Example Body: Reference Named File

RECREATE Formattedoutput my_formatted_output__c (
    label(‘My Formatted Output’),
    active(true),
    root_object('Object.product__v'),
    root_object_type('Objecttype.product__v.base__v'),
    output_type('native'),
    template('4be398c32fc2ccf48adaf6ebe53782a1')
);

After uploading a content file, you can reference the file by name using the file or template attributes in your MDL statement. This example uses the template attribute.

To change a component file, you must first upload it and update the component to reference the new file.

Retrieve Content File

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "links": [
        {
            "rel": "my_formatted_output__c.template_file",
            "href": "myvault.veevavault.com/api/mdl/components/Formattedoutput.my_formatted_output__c/files/4be398c32fc2ccf48adaf6ebe53782a1",
            "method": "GET",
            "accept": "application/pdf"
        }
    ],
    "data": [
        {
            "name__v": "4be398c32fc2ccf48adaf6ebe53782a1",
            "original_name__v": "Quote.pdf",
            "format__v": "application/pdf",
            "size__v": 654122,
            "sha1_checksum__v": "4be398c32fc2ccf48adaf6ebe53782a1"
        }
    ]
}

Retrieve the content file of a specified component.

GET /api/mdl/components/{component_type_and_record_name}/files

Headers

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

URI Path Parameters

Name Description
component_type_and_record_name The component type of the record followed by the name of the record from which to retrieve the content file. The format is {Componenttype}.{record_name}. For example, Formattedoutput.my_formatted_output__c.

Response Details

On SUCCESS, the response includes the following:

Name Description
name__v The name of the file which can be used in MDL for referencing the component.
original_name__v The original name of the uploaded file.
format__v The format of the file.
size__v The file size of the file.
sha1_checksum__v The SHA-1 checksum value generated for the file. Use the checksum to ensure the file was transmitted correctly.

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

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "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,
           "facetable": false
       },
       {
           "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": 0,
           "hidden": false,
           "queryable": true,
           "shared": false,
           "helpContent": "Displayed throughout application for the document, including in Library, Reporting, Notifications and Workflows.",
           "definedInType": "type",
           "definedIn": "base_document__v",
           "noCopy": false,
           "secureRelationship": false,
           "facetable": false
       },
       {
           "name": "template_document__v",
           "scope": "DocumentVersion",
           "type": "Boolean",
           "required": false,
           "repeating": false,
           "systemAttribute": true,
           "editable": false,
           "setOnCreateOnly": false,
           "disabled": false,
           "defaultValue": "false",
           "label": "Template Document",
           "section": "generalProperties",
           "sectionPosition": 1001,
           "hidden": true,
           "queryable": true,
           "shared": false,
           "definedInType": "type",
           "definedIn": "base_document__v",
           "noCopy": false,
           "secureRelationship": false,
           "facetable": true
       }
    ]
}

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 defined by the currently authenticated user. When false, the field value is read-only or system-managed, or the current user does not have adequate permissions to edit this field.
setOnCreateOnly When true, the field value can only be set once (when creating new documents).
hidden Boolean indicating field availability to the UI. When true, the field is never available to nor visible in the UI. When false, the field is always available to the UI but visibility to users is subject to field-level security overrides. If field-level security is configured to hide a field for the currently authenticated API user, the field is not returned in this API response.
queryable When true, field values can be retrieved using VQL. If field-level security is configured to hide the field from the user running this API, the field is not queryable by that user and will not appear in the API response.
noCopy When true, field values are not copied when using the Make a Copy action.
facetable When true, the field is available for use as a faceted filter in the Vault UI. Learn more about faceted filters in Vault Help.

Retrieve Common Document Fields

Request

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

Response

    {
      "name": "submission_date__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
docIdsrequired 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, except for noCopy, 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 When true, this field is a shared field.
usedIn (key) When shared is true, this lists the document types/subtypes/classifications which share the field.
usedIn (type) When shared is true, this indicates if the shared field is defined at the document type, subtype, or classification level.
noCopy When true, field values are not copied when using the Make a Copy action.

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

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "types": [
        {
            "label": "Base Document",
            "value": "https://etmf-veevapharm.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.

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

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "name": "promotional_piece__c",
  "label": "Promotional Piece",
  "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,
      "facetable": false
    }
  ],
  "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. The list of document fields defined for the specified type are also 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.
properties List of all the document fields associated to 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

Request

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

Response

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

Response Details

The response may contain the following details, depending on the configuration of your Vault:

Name Description
name Name of the document subtype.
label UI label for the document subtype.
properties List of all the document fields associated to the document subtype.
classifications This will not appear if the subtype has no classifications.
templates List of all templates available for the document subtype. This will not appear if the subtype has no templates.
availableLifecycles List of all lifecycles available for the document subtype.
renditions List of all rendition types available for the document subtype. This will not appear if the subtype has no renditions configured.

Retrieve Document Classification

Request

$ 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

Response

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

Response Details

The response may contain the following details, depending on the configuration of your Vault:

Name Description
name Name of the document subtype.
label UI label for the document subtype.
properties List of all the document fields associated to the document classification.
templates List of all templates available for the document classification. This will not appear if the classification has no templates.
availableLifecycles List of all lifecycles available for the document classification.
renditions List of all rendition types available for the document classification. This will not appear if the classification has no renditions configured.

Retrieve Documents

The following rules govern document retrieval:

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.

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

Retrieve All Documents

Request

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

Response

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

Request

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

Response

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

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "versions": [
        {
            "number": "0.1",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/0/1"
        },
        {
            "number": "0.2",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/0/2"
        },
        {
            "number": "1.0",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/1/0"
        },
        {
            "number": "1.1",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/1/1"
        },
        {
            "number": "2.0",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/0"
        },
        {
            "number": "2.1",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/1"
        },
        {
            "number": "2.2",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/2"
        },
        {
            "number": "2.3",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/versions/2/3"
        }
    ],
    "renditions":
        {
        "viewable_rendition__v": "https://myvault.veevavault.com/api/v15.0/objects/documents/534/renditions/viewable_rendition__v",
        "veeva_distribution_package__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 example response, 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

Request

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

Response

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

Download Document File

Request

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

Response

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

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.

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. Note that for most downloads (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Download Document Version File

Request

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

Response

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

Request

$ 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

Request

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

Response

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

Create a single document.

The API supports all security settings.

POST /api/{version}/objects/documents

Headers

Name Description
Content-Type multipart/form-data
Accept application/json (default) or application/xml
X-VaultAPI-MigrationMode When set to true, Vault applies Document Migration Mode limitations to documents created with the request. You must have the Document Migration permission to use this header. When used with the status__v parameter, allows you to create documents in a state other than Starting State. Learn more about Document Migration Mode in Vault Help.

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
fileconditional The filepath of the source document. The maximum allowed file size is 4GB. Only required when creating a document from an uploaded file. If omitted, creates a placeholder.
name__vrequired The name of the new document.
type__vrequired The label of the document type to assign to the new document.
subtype__voptional The label of the document subtype (if one exists on the document type).
classification__voptional The label of the document classification (if one exists on the document subtype).
lifecycle__vrequired The label of the document lifecycle to assign to the new document.
major_version_number__voptional The major version number to assign to the new document.
minor_version_number__voptional 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
fromTemplateconditional The name of the template to apply. Only required when creating a document from a template.
name__vrequired The name of the new document.
type__vrequired The label of the document type to assign to the new document.
subtype__voptional The label of the document subtype (if applicable).
classification__voptional The label of the document classification (if one exists on the document subtype).
lifecycle__vrequired The label of the document lifecycle to assign to the new document.
major_version_number__voptional The major version number to assign to the new document.
minor_version_number__voptional The minor version number to assign to the new document.

Optional Parameters in PromoMats

In PromoMats Vaults, you can also optionally set the following parameters. Learn more about PromoMats Standard Metrics in Vault Help.

Name Description
global_content_type__voptional The name of the global content type to assign to the new document. If excluded, Vault creates the document with the default global content type, or as “Not Specified” if no default exists.
content_creation_currency__voptional The id of the content creation currency type. If excluded, Vault creates the document with the default content creation currency, or as “Not Specified” if no default exists.
content_creation_cost__voptional The id of the content creation cost. If excluded, Vault creates the document with the default content creation cost, or as “Not Specified” if no default exists.
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__vrequired The name of the new document.
type__vrequired The label of the document type to assign to the new document.
subtype__voptional The label of the document subtype (if one exists on the document type).
classification__voptional The label of the document classification (if one exists on the document subtype).
lifecycle__vrequired The label of the document lifecycle to assign to the new document.
major_version_number__voptional The major version number to assign to the new document.
minor_version_number__voptional 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
fileconditional The filepath of the source document. The maximum allowed file size is 4GB. Only required when creating a document from an uploaded file.
type__vrequired Set the document type to Unclassified or Undefined.*
lifecycle__vrequired Set the document lifecycle to Inbox or Unclassified.*

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

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

* Prior to 21R1.3 (API v21.2), the Unclassified document type and Inbox lifecycle were known as the Undefined document type and Unclassified lifecycle. Relabeling the Undefined document type and Unclassified lifecycle may impact the functionality of custom integrations that use the old labels. Check your integrations before updating this label. We recommend that customers experiencing errors change the labels back to their original values until this issue is resolved.

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__vrequired The name of the new CrossLink document.
type__vrequired The label of the document type to assign to the new CrossLink document.
subtype__voptional The label of the document subtype (if one exists on the document type).
classification__voptional The label of the document classification (if one exists on the document subtype).
lifecycle__vrequired The label of the document lifecycle to assign to the new CrossLink document.
major_version_number__voptional The major version number to assign to the new CrossLink document
minor_version_number__voptional The minor version number to assign to the new CrossLink document.
source_vault_id__vconditional The Vault id field value of the Vault containing the source document that will be bound to the new CrossLink document. Only required when creating a CrossLink document. Learn more.
source_document_id__vconditional The document id field value of the source document that will be bound to the new CrossLink document. Only required when creating a CrossLink document.
source_binding_rule__voptional 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__voptional 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__voptional 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. The generated document id may not be in sequential order.

Create Multiple Documents

Request

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

Response

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

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

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.

The API supports all security settings except document lifecycle role defaults. You must create documents through the UI if your documents require document lifecycle role defaults. Learn more about document lifecycle role defaults in Vault Help.

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

Headers

Name Description
Content-Type text/csv
Accept application/json (default) or text/csv
X-VaultAPI-MigrationMode When set to true, Vault applies Document Migration Mode limitations to documents created with the request. You must have the Document Migration permission to use this header. When used with the status__v parameter, allows you to create documents in a state other than Starting State. Learn more about Document Migration Mode in Vault Help.

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 file staging server.

Name Description
fileconditional The filepath of the source document. The maximum allowed file size is 4GB. Only required when creating a document from an uploaded file.
name__vrequired The name of the new document.
type__vrequired The label of the document type to assign to the new document.
subtype__voptional The label of the document subtype (if one exists on the document type).
classification__voptional The label of the document classification (if one exists on the document subtype).
lifecycle__vrequired The label of the document lifecycle to assign to the new document.
major_version_number__voptional The major version number to assign to the new document
minor_version_number__voptional The minor version number to assign to the new document.
suppressRenditionoptional Set to true to suppress generation of viewable renditions. The default is false.
product__voptional 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.

Download Input File

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
fromTemplateconditional The template to apply to the document. Only required when creating a document from a template.
name__vrequired The name of the new document.
type__vrequired The label of the document type to assign to the new document.
subtype__voptional The label of the document subtype (if one exists on the document type).
classification__voptional The label of the document classification (if one exists on the document subtype).
lifecycle__vrequired The label of the document lifecycle to assign to the new document.
major_version_number__voptional The major version number to assign to the new document
minor_version_number__voptional The minor version number to assign to the new document.
product__voptional 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.

Download Input File

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
filerequired Include this column in your input, but leave the values blank.
name__vrequired The name of the new document.
type__vrequired The label of the document type to assign to the new document.
subtype__voptional The label of the document subtype (if one exists on the document type).
classification__voptional The label of the document classification (if one exists on the document subtype).
lifecycle__vrequired The label of the document lifecycle to assign to the new document.
major_version_number__voptional The major version number to assign to the new document
minor_version_number__voptional The minor version number to assign to the new document.

Download Input File

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
filerequired The filepath of the source document. The maximum allowed file size is 4GB.
name__voptional The name of the new document.
type__vrequired Set the document type to Unclassified or Undefined.*
lifecycle__vrequired Set the document lifecycle to Inbox or Unclassified.*

* Prior to 21R1.3 (API v21.2), the Unclassified document type and Inbox lifecycle were known as the Undefined document type and Unclassified lifecycle. Relabeling the Undefined document type and Unclassified lifecycle may impact the functionality of custom integrations that use the old labels. Check your integrations before updating this label. We recommend that customers experiencing errors change the labels back to their original values until this issue is resolved.

Download Input File

Response Details

On SUCCESS, the documents are created and assigned a system-managed document id field value. The generated document id may not be in sequential order.

Update Documents

Update Single Document

Request

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

Response

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

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
X-VaultAPI-MigrationMode When set to true, Vault applies Document Migration Mode limitations to documents updated with the request. You must have the Document Migration permission to use this header. Learn more about Document Migration Mode in Vault Help.

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

Request

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

Response

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

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.

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
X-VaultAPI-MigrationMode When set to true, Vault applies Document Migration Mode limitations to documents updated with the request. You must have the Document Migration permission to use this header. Learn more about Document Migration Mode in Vault Help.

Body Parameters

You can use Name-Value pairs in the body of your request or upload a CSV file. 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.

The following table includes required fields, and some optional document fields you may want to update:

Name Description
idconditional The ID of the document to update. Only required when uploading a CSV file.
docIdsconditional Comma-separated list of the IDs of documents to update. Only required when entering key-value pairs in the body of your request.
archive__voptional To archive a document, set to true. To unarchive a document, set to false. The default is false. Document archive is not available in all Vaults. Learn more in Vault Help.
template_doctype__voptional If you need to create a controlled document template from this document, enter a value for the Template Document Type field. To retrieve a list of all possible field values for this field, Retrieve the Object Collection for doc_type_detail__v. Learn more about controlled document template creation in Vault Help.

Download Input File

Reclassify Single Document

Request

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

Response

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

Reclassify allows you to change the document type of an existing document or assign a document type to an unclassified document. This endpoint is analogous to the Reclassify action in the Vault UI.

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. Add these new fields and values to the body of this request. If a new required field is missing, the error response will list the name of the required field. To reclassify more than one document, use the Reclassify Multiple Documents endpoint.

Not all documents are eligible for reclassification. For example, you can only reclassify the latest version of a document and you cannot reclassify a checked out document. 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
X-VaultAPI-MigrationMode When set to true, use with the status__v and document_number__v body parameters to reclassify documents to any document lifecycle state and with any document number. You must have the Document Migration permission to use this header. Learn more about Document Migration Mode in Vault Help.

URI Path Parameters

Name Description
{doc_id} The document id field value.

Body Parameters

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.

Name Description
type__vrequired The name of the document type.
subtype__voptional The name of the document subtype (if one exists on the type).
classification__voptional The name of the document classification (if one exists on the subtype).
lifecycle__vrequired The name of the document lifecycle.
reclassifyrequired Set to true. Without this, a standard document update action is performed.
document_number__voptional The document number for the reclassified document. If omitted, the document retains the existing document number. You must set both the reclassify parameter and the X-VaultAPI_MigrationMode header to true to change the document number, and you can only include this parameter when you also change the document lifecycle or type, subtype, or classification.
status__voptional Specifies the document lifecycle state for the reclassified document. If omitted, the document retains the existing state. You must set both the reclassify parameter and the X-VaultAPI_MigrationMode header to true to change the state, and you can only include this parameter when you also change the document lifecycle or type, subtype, or classification.

Reclassify Multiple Documents

Request

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

Response

responseStatus,id,errors,warnings
SUCCESS,44,
SUCCESS,46,

Reclassify documents in bulk. Reclassify allows you to change the document type of existing documents or assign document types to unclassified documents.

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.

Not all documents are eligible for reclassification. For example, you can only reclassify the latest version of a document and you cannot reclassify a checked out document. Learn more about reclassifying documents in Vault Help.

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

Headers

Name Description
Content-Type text/csv
Accept application/json (default) or text/csv
X-VaultAPI-MigrationMode When set to true, use with the status__v and document_number__v body parameters to reclassify documents to any document lifecycle state and with any document number. You must have the Document Migration permission to use this header. Learn more about Document Migration Mode in Vault Help.

Body Parameters

Upload parameters as a CSV file. 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.

Name Description
idrequired The ID of the document to reclassify.
lifecycle__vrequired The name of the document lifecycle.
type__vrequired The name of the document type.
subtype__voptional The name of the document subtype (if one exists on the type).
classification__voptional The name of the document classification (if one exists on the subtype).
document_number__voptional The document number for the reclassified document. If omitted, the document retains the existing document number. You must set both the reclassify parameter and the X-VaultAPI_MigrationMode header to true to change the document number, and you can only include this parameter when you also change the document lifecycle or type, subtype, or classification.
status__voptional Specifies the document lifecycle state for the reclassified document. If omitted, the document retains the existing state. You must set both the reclassify parameter and the X-VaultAPI_MigrationMode header to true to change the state, and you can only include this parameter when you also change the document lifecycle or type, subtype, or classification.

Response Details

On SUCCESS, Vault returns the IDs of the reclassified documents.

Update Document Version

Request

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

Response

{
    "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
X-VaultAPI-MigrationMode When set to true, Vault applies Document Migration Mode limitations to document versions updated with the request. You must have the Document Migration permission to use this header. Learn more about Document Migration Mode in Vault Help.

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

Request

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

Response

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

Create or add document versions in bulk.

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

Headers

Name Description
Content-Type text/csv
Accept application/json (default) or text/csv
X-VaultAPI-MigrationMode Must be set to true. Vault applies Document Migration Mode limitations to document versions created with the request. You must have the Document Migration permission to use this header. Learn more about Document Migration Mode in Vault Help.

Body Parameters

Name Description
filerequired The filepath of your source files.
idconditional The system-assigned document ID of the document to add the versions to. Not required if providing a unique field identifier (idParam) such as external_id__v.
external_id__vconditional Instead of id, you can use this user-defined document external ID.
name__vrequired Enter a name for the new document. This may be the same name as the existing document/version or a different name.
type__vrequired Enter the label of the document type to assign to the new document.
subtype__voptional Enter the label of the document subtype (if one exists on the document type).
classification__voptional Enter the label of the document classification (if one exists on the document subtype).
lifecycle__vrequired 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__vrequired 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__vrequired 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__vrequired Enter a status for the new document, e.g., Draft, In Review, Approved, etc.
product__voptional 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 a unique field, add idParam={fieldname} to the request endpoint. You can use any object field which has unique set to true in the object metadata, with the exception of picklists. For example, idParam=external_id__v.

Download Input File

Note: In PromoMats Vaults with Automated Claims Linking enabled, when a reference document is updated with the Create Multiple Document Versions API, the associated claim record is updated to reference the new version and remains in the approved state, and the reference is not removed.

Create Single Document Version

Request: Copy file from current 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

Request: Upload a new file & Suppress rendition

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

Response

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

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.

Not all documents are eligible for draft creation. For example, you cannot create a draft of a checked out document. Learn more in Vault Help.

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
createDraftrequired Choose one of the two available values:

latestContent: Create a new draft version from the existing document in the Vault. This does not require uploading a file. This option is only available if both the source file and rendition are each 4 GB or less. This is analogous to the Copy file from current version option in the Create Draft UI.

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.
fileconditional The filepath of the source document. Only required when 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.
description__voptional Add a Version Description for the new draft version. Other users may view this description in the document’s Version History. Maximum 1,500 characters.

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

Request

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

Response

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

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

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

Headers

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

URI Path Parameters

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

Delete Multiple Documents

Request

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

Response

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

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

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

Headers

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

Body Parameters

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

Name Description
idconditional The system-assigned document ID of the document to delete. Not required if providing a unique field identifier (idParam) such as external_id__v.
external_id__vconditional 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 a unique field, add idParam={fieldname} to the request endpoint. You can use any object field which has unique set to true in the object metadata, with the exception of picklists. For example, idParam=external_id__v.

Delete Single Document Version

Request

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

Response

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

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

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

Headers

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

URI Path Parameters

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

Delete Multiple Document Versions

Request

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

Response

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

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

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

Headers

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

Body Parameters

Create a CSV or JSON input file.

Name Description
idconditional The system-assigned document ID of the document to delete. Not required if providing a unique field identifier (idParam) such as external_id__v.
external_id__vconditional Instead of id, you can use this user-defined document external ID.
major_version_number__vrequired Major version number of the document version to remove.
minor_version_number__vrequired Minor version number of the document version to remove.

Query Parameters

Name Description
idParam If you’re identifying documents in your input by a unique field, add idParam={fieldname} to the request endpoint. You can use any object field which has unique set to true in the object metadata, with the exception of picklists. For example, idParam=external_id__v.

Download Input File

Retrieve Deleted Document IDs

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "responseMessage": "OK",
   "responseDetails": {
       "total": 3,
       "size": 3,
       "limit": 1000,
       "offset": 0
   },
   "data": [
       {
           "id": 23,
           "major_version_number__v": 0,
           "minor_version_number__v": 1,
           "date_deleted": "2021-02-26T23:46:49Z",
           "global_id__sys": "10000760_23",
           "global_version_id__sys": "10000760_23_39",
           "external_id__v": null,
           "deletion_type": "version_change__sys"
       },
       {
           "id": 7,
           "major_version_number__v": 0,
           "minor_version_number__v": 16,
           "date_deleted": "2021-02-26T23:55:22Z",
           "global_id__sys": "10000760_7",
           "global_version_id__sys": "10000760_7_22",
           "external_id__v": null,
           "deletion_type": "document_version__sys"
       },
       {
           "id": 10,
           "major_version_number__v": "",
           "minor_version_number__v": "",
           "date_deleted": "2021-02-26T23:55:45Z",
           "global_id__sys": "10000760_10",
           "global_version_id__sys": null,
           "external_id__v": null,
           "deletion_type": "document__sys"
       }
   ]
}

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

Name Description
total The total number of deleted documents and document versions.
id The ID of the deleted document or version. If the same document has multiple deleted versions, the same ID may appear twice.
major_version_number__v The major version of the deleted version. If all versions of the document were deleted (for example, using the Delete user action in the Vault UI), this value is blank ("").
minor_version_number__v The minor version of the deleted version. If all versions of the document were deleted (for example, using the Delete user action in the Vault UI), this value is blank ("").
date_deleted The date and time this document or version was deleted.
global_id__sys The global ID of the deleted document or version.
global_version_id__sys The global version ID of the deleted document or version. If all versions of the document were deleted (for example, using the Delete user action in the Vault UI), this value is null.
external_id__v The external ID of the deleted document or version. May be null if no external ID was set for this document.
deletion_type Describes how this document or version was deleted.
  • document__sys: this document was deleted in full, including all versions. For example, this document was deleted with the Delete user action in the Vault UI.
  • document_version__sys: this document version was deleted. For example, this document version was deleted with Delete Single Document Version API.
  • version_change__sys: this document version no longer exists, as it became a new major version through the Set new major version entry action.

Document Locks

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

Learn about Document Checkout (Locks) in Vault Help.

Retrieve Document Lock Metadata

Request

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

Response

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

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.

Create Document Lock

Request

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

Response

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

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

Request

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

Response

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

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

Request

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

Response

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

Deleting a document lock is analogous to undoing check out of a document. The authenticated user must have Edit Document permission in the document lifecycle state security settings as well as one of the following:

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.

Undo Collaborative Authoring Checkout

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: application/json" \
--data "id
7652
3
8" \
https://myvault.veevavault.com/api/v24.2/objects/documents/batch/lock

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "responseStatus": "EXCEPTION",
           "responseMessage": "Document not found 19523/7652",
           "id": 7652
       },
       {
           "responseStatus": "FAILURE",
           "responseMessage": "Cannot use office365__sys undo check out for a document checked out to basic__sys",
           "id": 3
       },
       {
           "responseStatus": "SUCCESS",
           "responseMessage": "Undo check out successful",
           "id": 8
       }
   ]
}

Undo Collaborative Authoring checkout on up to 500 documents at once. Learn more about Collaborative Authoring in Vault Help.

To undo basic checkout, see Delete Document Lock.

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

Headers

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

Body Parameters

Upload parameters as a CSV file.

Name Description
idrequired The id of the document to undo checkout. Maximum 500 documents per request.

Response Details

On SUCCESS, Vault returns a responseStatus and responseMessage for each id in the request body. Partial success is allowed, meaning some documents in the batch may succeed while others fail. For any failed documents, the response includes a reason for the failure.

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

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "renditionTypes": [
        "viewable_rendition__v",
        "imported_rendition__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

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "renditionTypes": [
        "viewable_rendition__v",
        "imported_rendition__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

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

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.
protectedRendition If your Vault is configured to use protected renditions, set to false to download the non-protected rendition. If omitted, defaults to true. You must have the Download Non-Protected Rendition permission to download non-protected renditions.

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

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

Download a rendition for a specified version of a document.

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.

Query Parameters

Name Description
protectedRendition If your Vault is configured to use protected renditions, set to false to download the non-protected rendition. If omitted, defaults to true. You must have the Download Non-Protected Rendition permission to download non-protected renditions.

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

Request

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

Response

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

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

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

Headers

Name Description
Content-Type text/csv
Accept application/json (default) or text/csv
X-VaultAPI-MigrationMode When set to true, Vault applies Document Migration Mode limitations to renditions created with the request. You must have the Document Migration permission to use this header. Learn more about Document Migration Mode in Vault Help.

Body Parameters

Name Description
filerequired The filepath of the rendition on the file staging server.
idconditional The system-assigned document ID of the document to add renditions to. Not required if providing a unique field identifier (idParam) such as external_id__v.
external_id__vconditional Instead of id, you can use this user-defined document external ID.
rendition_type__vrequired Document rendition type to assign to the new rendition. Only one rendition of each type may exist on each document.
major_version_number__vrequired Major version number to assign to the new document rendition.
minor_version_number__vrequired Minor version number to assign to the new document rendition.

Query Parameters

Name Description
idParam If you’re identifying documents in your input by a unique field, add idParam={fieldname} to the request endpoint. You can use any object field which has unique set to true in the object metadata, with the exception of picklists. For example, idParam=external_id__v.
largeSizeAsset If set to true, indicates that the renditions to add are of the Large Size Asset (large_size_asset__v) rendition type. Vault applies Document Migration Mode limitations to renditions created with the request, but Document Migration permission is not required and your Vault need not be in Migration Mode to use the parameter. Note that the request results in an error if the CSV contains any rendition type other than large_size_asset__v.

Download Input File

Add Single Document Rendition

Request

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

Response

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

Request

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

Response

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

Update Multiple Document Renditions

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Documents\update_document_renditions.csv" \
https://myvault.veevavault.com/api/v24.1/objects/documents/batch/actions/rerender

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 1,
            "major_version_number__v": "0",
            "minor_version_number__v": "1"
        },
        {
            "responseStatus": "SUCCESS",
            "id": 2,
            "major_version_number__v": "0",
            "minor_version_number__v": "1"
        }
    ]
}

Update or re-render document renditions in bulk.

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

Headers

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

Body Parameters

Upload parameters as a CSV file.

Name Description
idrequired The system-assigned ID of the document.
major_version_number__vrequired The major version number of the existing document.
minor_version_number__vrequired The minor version number of the existing document.

Response Details

On SUCCESS, Vault returns whether each document rendition was successfully re-rendered.

Replace Document Rendition

Request

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

Response

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

Request

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

Response

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

Request

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

Response

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

Delete document renditions in bulk.

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

Headers

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

Body Parameters

Create a CSV or JSON input file.

Name Description
idconditional The system-assigned document ID of the document to delete. Not required if providing a unique field identifier (idParam) such as external_id__v.
external_id__vconditional Instead of id, you can use this user-defined document external ID.
rendition_type__vrequired Rendition type to delete from the document.
major_version_number__vrequired Major version number of the document rendition to remove.
minor_version_number__vrequired Minor version number of the document rendition to remove.

Query Parameters

Name Description
idParam If you’re identifying documents in your input by a unique field, add idParam={fieldname} to the request endpoint. You can use any object field which has unique set to true in the object metadata, with the exception of picklists. For example, idParam=external_id__v.

Delete Single Document Rendition

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

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

Request

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

Response

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

Request

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

Response

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

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 566,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 2,
            "created_by__v": 46916,
            "created_date__v": "2015-01-14T00:35:01.775Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.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

Request

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

Response

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

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "version__v": 1,
            "url": "https://myvault.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 Attachment Versions

Request

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

Response

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

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 566,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 2,
            "created_by__v": 46916,
            "created_date__v": "2015-01-14T00:35:01.775Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.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

Request

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

Response

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

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

Request

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

Response

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

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

Request

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

Response

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

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

Request

$ 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

Response

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.

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 All Document Attachments

Request

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

Response

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

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

Request

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

Response

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.

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.

Delete Single Document Attachment

Request

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

Response

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

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

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

Request

$ 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

Response

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

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

Prepare a CSV or JSON input file.

Name Description
idconditional The attachment ID to delete. Not required if providing a unique field identifier (idParam) such as external_id__v.
external_id__voptional Identify documents by their external ID instead of regular id. You must also add the idParam=external_id__v query parameter.
document_id__voptional The source document id value.

Query Parameters

Name Description
idParam If you’re identifying attachments in your input by external id, add idParam=external_id__v to the request endpoint.

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

Request

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

Response

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

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

Request

$ 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

Response

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

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__vrequired The document ID to add this attachment.
filename__vrequired The name for the new attachment. This name must include the file extension, for example, MyAttachment.pdf. If an attachment with this name already exists, this attachment is added as a new version.
filerequired The filepath of the attachment on the file staging server.
description__voptional Description of the attachment. Maximum 1000 characters.
major_version_number__voptional The major version of the source document.
minor_version_number__voptional The minor version of the source document.
external_id__voptional Set an external ID value on the attachment.

Download Input File

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

Request

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

Response

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

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

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

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__vrequired This is the only editable field. The maximum character length is 1000.

Update Multiple Document Attachment Descriptions

Request

$ 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

Response

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

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
idconditional The attachment ID to update. Not required if providing a unique field identifier (idParam) such as external_id__v.
external_id__vconditional Identify attachments by their external ID instead of regular id. You must also add the idParam=external_id__v query parameter.
description__vrequired Description of the attachment. Maximum 1,000 characters.

Download Input File

Query Parameters

Name Description
idParam If you’re identifying attachments in your input by external id, add idParam=external_id__v to the request endpoint.

Response Details

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

Document Annotations

The document viewer in the Vault UI allows users to mark up and comment on documents with a wide variety of annotations. Users can choose to create comment, line, link, or anchor annotations, and can reply to other annotations. Learn about Document Annotations in Vault Help.

CrossLink documents only allow annotations and anchors if they are statically bound to their source document. Dynamically bound CrossLinks do not allow annotations, and the API returns an error when you attempt to export or import annotations to or from a dynamically bound CrossLink document.

Retrieve Annotation Type Metadata

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.2/metadata/objects/documents/annotations/types/note__sys' \

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "note__sys",
        "allows_replies": true,
        "allowed_placemark_types": [
            "arrow__sys",
            "ellipse__sys",
            "page_level__sys",
            "rectangle__sys",
            "sticky__sys",
            "text__sys"
        ],
        "allowed_reference_types": [],
        "fields": [
            {
                "name": "created_by_delegate_user__sys",
                "type": "String",
                "system_managed": true,
                "value_set": []
            },
            {
                "name": "created_by_user__sys",
                "type": "String",
                "system_managed": true,
                "value_set": []
            },
            {
                "name": "created_date_time__sys",
                "type": "DateTime",
                "system_managed": true,
                "value_set": []
            },
            {
                "name": "document_version_id__sys",
                "type": "String",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "id__sys",
                "type": "String",
                "system_managed": true,
                "value_set": []
            },
            {
                "name": "modified_by_user__sys",
                "type": "String",
                "system_managed": true,
                "value_set": []
            },
            {
                "name": "modified_date_time__sys",
                "type": "DateTime",
                "system_managed": true,
                "value_set": []
            },
            {
                "name": "title__sys",
                "type": "String",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "color__sys",
                "type": "String",
                "system_managed": false,
                "value_set": [
                    "yellow_light__sys",
                    "green_dark__sys",
                    "green_light__sys",
                    "orange_dark__sys",
                    "orange_light__sys",
                    "pink_dark__sys",
                    "pink_light__sys",
                    "purple_dark__sys",
                    "purple_light__sys",
                    "red_dark__sys",
                    "red_light__sys",
                    "yellow_dark__sys"
                ]
            },
            {
                "name": "comment__sys",
                "type": "String",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "original_source_document_version_id__sys",
                "type": "String",
                "system_managed": true,
                "value_set": []
            },
            {
                "name": "reply_count__sys",
                "type": "Number",
                "system_managed": true,
                "value_set": []
            },
            {
                "name": "state__sys",
                "type": "String",
                "system_managed": false,
                "value_set": [
                    "open__sys",
                    "resolved__sys"
                ]
            },
            {
                "name": "tag_names__sys",
                "type": "String list",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "type__sys",
                "type": "String",
                "system_managed": false,
                "value_set": [
                    "note__sys"
                ]
            }
        ]
    }
}

Retrieves the metadata of an annotation type, including metadata and value sets for all supported fields on the annotation type. Learn more about annotation types in the Vault Java SDK documentation.

GET /api/{version}/objects/documents/annotations/types/{annotation_type}

Headers

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

URI Path Parameters

Name Description
{annotation_type}required The name of the annotation type. For example, note__sys. Learn more about annotation types in the Vault Java SDK documentation.

Response Details

On SUCCESS, the response includes a list of metadata information for the specified annotation type. Each response may include some or all of the following fields depending on type:

Field Description
allows_replies if true, this annotation type allows replies.
allowed_placemark_types A list of placemark types this annotation type allows. Learn more about placemark types in the Vault Java SDK documentation.
allowed_reference_types A list of reference types that this annotation type allows. Learn more about reference types in the Vault Java SDK documentation.
fields A list of fields configured on the annotation type. For more details about annotation fields, see Read Annotations by Document Version and Type.

Retrieve Annotation Placemark Type Metadata

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.2/metadata/objects/documents/annotations/placemarks/types/arrow__sys \

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "arrow__sys",
        "fields": [
            {
                "name": "coordinates__sys",
                "type": "Number list",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "height__sys",
                "type": "Number",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "width__sys",
                "type": "Number",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "x_coordinate__sys",
                "type": "Number",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "y_coordinate__sys",
                "type": "Number",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "page_number__sys",
                "type": "Number",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "style__sys",
                "type": "String",
                "system_managed": false,
                "value_set": [
                    "arrow_down_left__sys",
                    "arrow_down_right__sys",
                    "arrow_left_down__sys",
                    "arrow_left_up__sys",
                    "arrow_right_down__sys",
                    "arrow_right_up__sys",
                    "arrow_up_left__sys",
                    "arrow_up_right__sys"
                ]
            },
            {
                "name": "type__sys",
                "type": "String",
                "system_managed": false,
                "value_set": [
                    "arrow__sys"
                ]
            }
        ]
    }
}

Retrieves the metadata of a specified annotation placemark type. Learn more about placemark types in the Vault Java SDK documentation.

GET /api/{version}/objects/documents/annotations/placemarks/types/{placemark_type}

Headers

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

URI Path Parameters

Name Description
{placemark_type}required The name of the placemark type. For example, sticky__sys. Learn more about placemark types in the Vault Java SDK documentation.

Response Details

On SUCCESS, the response includes a list of metadata information for the specified placemark type. Each response may include some or all of the following fields depending on type:

Field Description
coordinates__sys A list of all coordinates for the placemark.
height__sys The height of the selection, measured in pixels at 72 DPI.
width__sys The width of the selection, measured in pixels at 72 DPI.
x_coordinate__sys The X coordinate of the position of the top-left of the selection, measured in pixels at 72 DPI.
y_coordinate__sys The Y coordinate of the position of the top-left of the selection, measured in pixels at 72 DPI.
page_number__sys The document page number where the annotation appears. Page numbers start at 1.
style__sys The style of the placemark. For example, sticky_icon__sys.
reply_parent__sys Reply-type annotations only. The ID of the parent annotation.
reply_position_index__sys The position of a reply in a series of replies to a parent annotation. Positions start at 1.
text_start_index__sys Annotations placed on text selections only. The index of the first selected word on a page.
text_end_index__sys Annotations placed on text selections only. The index of the last selected word on a page.

Retrieve Annotation Reference Type Metadata

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.2/metadata/objects/documents/annotations/references/types/document__sys \

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "document__sys",
        "fields": [
            {
                "name": "annotation__sys",
                "type": "String",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "document_version_id__sys",
                "type": "String",
                "system_managed": false,
                "value_set": []
            },
            {
                "name": "type__sys",
                "type": "String",
                "system_managed": true,
                "value_set": [
                    "document__sys"
                ]
            }
        ]
    }
}

Retrieves the metadata of a specified annotation reference type. Learn more about reference types in the Vault Java SDK documentation.

GET /api/{version}/objects/documents/annotations/references/types/{reference_type}

Headers

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

URI Path Parameters

Name Description
{reference_type}required The name of the reference type. For example, permalink__sys. Learn more about reference types in the Vault Java SDK documentation.

Response Details

On SUCCESS, the response includes a list of annotations of the specified type(s) for the document version. Each Annotation object may include some or all of the following fields depending on type:

Field Description
annotation__sys Document-type references only. The ID of the referenced anchor annotation, or null for references to an entire document.
document_version_id__sys Document-type references only. The ID and version number of the referenced document in the format {documentId}_{majorVersion}_{minorVersion}. For example, 138_2_1.
permalink__sys Permalink-type references only. The ID of the referenced permalink.
url__sys External-type references only. The URL of the external reference. Allows up to 32,000 characters.

Create Multiple Annotations

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '[
   {
       "type__sys": "note__sys",
       "document_version_id__sys": "1_0_1",
       "color__sys": "orange_dark__sys",
       "comment__sys": "hello world",
       "placemark": {
           "type__sys": "sticky__sys",
           "page_number__sys": 1,
           "x_coordinate__sys": 50.5,
           "y_coordinate__sys": 25.5
       }
   },
   {
       "type__sys": "document_link__sys",
       "document_version_id__sys": "2_0_1",
       "placemark": {
           "type__sys": "text__sys",
           "page_number__sys": 2,
           "text_start_index__sys": 10,
           "text_end_index__sys": 15
       },
       "references": [
           {
               "type__sys": "document__sys",
               "document_version_id__sys": "301_0_3",
               "annotation__sys": "56"
           },
           {
               "type__sys": "document__sys",
               "document_version_id__sys": "4_0_1"
           }
       ]
   }
]'
https://myvault.veevavault.com/api/v24.2/objects/documents/annotations/batch \

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "document_version_id__sys": "1_0_1",
            "global_version_id__sys": "123456_1_1",
            "id__sys": "58"
        },
        {
            "responseStatus": "SUCCESS",
            "document_version_id__sys": "2_0_1",
            "global_version_id__sys": "123456_2_2",
            "id__sys": "59"
        }
    ]
}

Create up to 500 annotations.

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

Headers

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

Body Parameters

Prepare a JSON-formatted list of annotation objects, each containing a list of annotation properties and their values. For more details about annotation fields, see Read Annotations by Document Version and Type.

Response Details

On SUCCESS, the response includes a responseStatus indicating whether each annotation object in the request body was successfully created. For successfully created annotations, the response also includes the following:

Field Description
document_version_id__sys The ID and version number of the document where the annotation appears in the format {documentId}_{majorVersion}_{minorVersion}. For example, 138_2_1.
global_version_id__sys The Vault ID, document ID, and document version ID in the format {vaultId}_{documentId}_{docVersionId}. For example, 123456_2_1.
id The annotation ID.

Add Annotation Replies

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '[
   {
       "document_version_id__sys": "1_0_1",
       "type__sys": "reply__sys",
       "comment__sys": "first reply from the api",
       "placemark": {
           "type__sys": "reply__sys",
           "reply_parent__sys": "54"
       }
   },
   {
       "document_version_id__sys": "1_0_1",
       "type__sys": "reply__sys",
       "color__sys": "green_light__sys",
       "comment__sys": "first reply from the api",
       "placemark": {
           "type__sys": "reply__sys",
           "reply_parent__sys": "55"
       }
   },
   {
       "document_version_id__sys": "1_0_1",
       "type__sys": "reply__sys",
       "comment__sys": "second reply from the api",
       "placemark": {
           "type__sys": "reply__sys",
           "reply_parent__sys": "54"
       }
   }
]'
https://myvault.veevavault.com/api/v24.2/objects/documents/annotations/replies/batch \

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "document_version_id__sys": "1_0_1",
            "global_version_id__sys": "123456_1_1",
            "id__sys": "60"
        },
        {
            "responseStatus": "SUCCESS",
            "document_version_id__sys": "1_0_1",
            "global_version_id__sys": "123456_1_1",
            "id__sys": "62"
        },
        {
            "responseStatus": "SUCCESS",
            "document_version_id__sys": "1_0_1",
            "global_version_id__sys": "123456_1_1",
            "id__sys": "61"
        }
    ]
}

Create up to 500 annotation replies.

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

Headers

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

Body Parameters

Prepare a JSON-formatted list of annotation reply objects. Each object must contain the id_sys, document_version_id__sys, and the annotation field(s) to be set, and a placemark object containing the following:

Placemark Field Description
type__sysrequired The annotation type. This must always be reply__sys.
reply_parent__sysrequired The ID of the parent annotation.

Response Details

On SUCCESS, the response includes the document version ID, global version ID, and ID and version of each successfully created reply. See Create Annotations for details. Replies that were not added successfully are reported with an error message.

Update Annotations

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '[
   {
       "id__sys": "58",
       "document_version_id__sys": "1_0_1",
       "comment__sys": "Updated comment from api"
   },
   {
       "id__sys": "54",
       "document_version_id__sys": "1_0_1",
       "color__sys": "yellow_light__sys"
   }
]'
https://myvault.veevavault.com/api/v24.2/objects/documents/annotations/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "document_version_id__sys": "1_0_1",
            "global_version_id__sys": "123456_1_1",
            "id__sys": "58"
        },
        {
            "responseStatus": "SUCCESS",
            "document_version_id__sys": "1_0_1",
            "global_version_id__sys": "123456_1_1",
            "id__sys": "54"
        }
    ]
}

Update up to 500 existing annotations.

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

Headers

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

Body Parameters

Prepare a JSON-formatted list of annotation objects. Each object must contain the id_sys, document_version_id__sys, and the annotation field(s) to be updated. For more details about annotation fields, see Read Annotations by Document Version and Type.

Response Details

On SUCCESS, the response includes the document version ID, global version ID, and ID and version of updated annotations. See Create Annotations for details. Annotations that did not update successfully are reported with an error message.

Read Annotations by Document Version and Type

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.1/objects/documents/47/versions/0/1/annotations?annotation_types=document_link__sys,note__sys

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "document_version_id__sys": "47_0_1",
            "modified_by_user__sys": "1003079",
            "id__sys": "15",
            "placemark": {
                "y_coordinate__sys": 474.32,
                "coordinates__sys": [
                    481.01,
                    474.32,
                    598.37,
                    474.32,
                    481.01,
                    363.04,
                    598.37,
                    363.04
                ],
                "type__sys": "rectangle__sys",
                "height__sys": 111.28,
                "width__sys": 117.36,
                "x_coordinate__sys": 481.01,
                "page_number__sys": 1,
                "style__sys": "rectangle_solid__sys"
            },
            "created_by_user__sys": "1003079",
            "comment__sys": "Make this green.",
            "created_date_time__sys": "2023-06-26T19:59:41.000Z",
            "modified_date_time__sys": "2024-03-04T18:47:43.000Z",
            "title__sys": "",
            "type__sys": "note__sys",
            "tag_names__sys": [
                "CholeCap"
            ],
            "state__sys": "open__sys",
            "reply_count__sys": 0,
            "color__sys": "yellow_light__sys"
        },
        {
            "document_version_id__sys": "47_0_1",
            "modified_by_user__sys": "1003079",
            "references": [
                {
                    "document_version_id__sys": "7_1_0",
                    "type__sys": "document__sys",
                    "annotation__sys": "21"
                }
            ],
            "id__sys": "22",
            "placemark": {
                "y_coordinate__sys": 491.46,
                "coordinates__sys": [
                    349.48,
                    491.46,
                    408.54,
                    491.46,
                    349.48,
                    454.25,
                    408.54,
                    454.25
                ],
                "type__sys": "rectangle__sys",
                "height__sys": 37.21,
                "width__sys": 59.06,
                "x_coordinate__sys": 349.48,
                "page_number__sys": 1,
                "style__sys": "rectangle_solid__sys"
            },
            "created_by_user__sys": "1003079",
            "comment__sys": "",
            "created_date_time__sys": "2024-03-04T18:51:54.000Z",
            "modified_date_time__sys": "2024-03-04T18:52:16.000Z",
            "title__sys": "",
            "type__sys": "document_link__sys",
            "state__sys": "open__sys",
            "color__sys": "blue_dark__sys"
        }
    ],
    "responseDetails": {
        "offset": 0,
        "limit": 500,
        "size": 2,
        "total": 2
    }
}

Retrieve annotations from a specific document version. You can retrieve all annotations or choose to retrieve only certain annotation types.

You must have View Content permission on the specified document version.

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

Query Parameters

Name Description
offsetoptional This parameter is used to paginate the results. It specifies the amount of offset from the first record returned. Vault returns 200 records per page by default. If you are viewing the first 200 results (page 1) and want to see the next page, set this to offset=201.
limitoptional Paginate the results by specifying the maximum number of records per page in the response. This can be any value between 1 and 500. If omitted, defaults to 500. Values greater than 500 are ignored.
pagination_idoptional A unique identifier used to load requests with paginated results. For example, b688a6f4-d0c4-4f72-9eb4-ceba01136466.
annotation_typesoptional The type(s) of annotations to retrieve. For example, note__sys,anchor__sys. If omitted, Vault returns all annotation types except replies.

Response Details

On SUCCESS, the response includes a list of annotations of the specified type(s) for the document version. Each Annotation object may include some or all of the following fields depending on type:

Annotation Field Description
document_version_id__sys The ID and version number of the document where the annotation appears in the format {documentId}_{majorVersion}_{minorVersion}. For example, 138_2_1.
modified_by_user__sys The ID of the user who last modified the annotation. If no last modified information exists, this defaults to the value of created_by_user__sys.
id__sys The annotation ID.
placemark A list of fields whose values define where on a document an annotation appears. See below for details.
references A list of annotation references. See below for details.
created_by_user__sys The ID of the user who created the annotation.
created_by_delegate_user__sys The ID of the delegate user who created the annotation, if applicable.
comment__sys The annotation comment text. Allows up to 32,000 characters. Not all annotation types allow comments.
created_date_time__sys The date and time when the annotation was created.
modified_date_time__sys The date and time when the annotation was last modified. If no last modified information exists, this defaults to the value of created_date_time__sys.
linked_object__sys The name of the primary linked object for the annotation. Not all annotation types support linked objects.
linked_records__sys The ID(s) of the object record or records the annotation is linked to. Not all annotation types support linked records.
title__sys The title of the annotation. Allows up to 1,500 characters. For annotations with text placemarks, this must be set to the selected text.
type__sys The name of the annotation type. For example, note__sys.
state__sys The name of the state of the annotation, either open__sys or resolved__sys. Not all annotation types support states.
reply_count__sys For annotation types that support replies, the number of replies to this annotation.
color__sys The name of the annotation color. Some annotation types allow users to select from a variety of colors, while others are always the same color.
tag_names__sys A list of the names of each tag associated with each annotation. Not all annotation types support tags.
anchor_name__sys Anchor annotations only: The name of the anchor. Allows up to 140 characters.
match_text_variation__sys PromoMats Vaults with Suggested Links enabled only: The ID of the matched_text_variation__sys object record linked to the annotation_keywords__sys record associated with the annotation.
offset The offset value specified in the request.
limit The limit value specified in the request.
size The number of records displayed on the current page.
total The total number of annotations found.
next_page The pagination URL to navigate to the next page of results. Only included if the number of results exceeds the number defined by a request’s limit.
previous_page The pagination URL to navigate to the previous page of results. Only included if the request included an offset, or after navigating to the next_page URL.

Placemarks

A placemark defines where on a document an annotation appears. For example, a text selection, a page number, or the coordinates of an area selection.

Placemark coordinates are listed in the style of PDF quad points and are measured in pixels from the bottom-left of the page at 72 DPI. There will be 8*n coordinates, where n is the number of rectangles that make up the placemark. Annotation placemarks include the following fields:

Placemark Field Description
coordinates__sys A list of all coordinates for the placemark. Text placemarks must set the title__sys field to the selected text in addition to specifying coordinates.
y_coordinate__sys The Y coordinate of the position of the top-left of the selection, measured in pixels at 72 DPI.
x_coordinate__sys The X coordinate of the position of the top-left of the selection, measured in pixels at 72 DPI.
text_start_index__sys Annotations placed on text selections only. The index of the first selected word on a page.
text_end_index__sys Annotations placed on text selections only. The index of the last selected word on a page.
type__sys The placemark type. For example, text__sys.
height__sys The height of the selection, measured in pixels at 72 DPI.
width__sys The width of the selection, measured in pixels at 72 DPI.
page_number__sys The document page number where the annotation appears. Page numbers start at 1.
style__sys The style of the placemark. For example, sticky_icon__sys.
reply_parent__sys Reply-type annotations only. The ID of the parent annotation.
reply_position_index__sys The position of a reply in a series of replies to a parent annotation. Positions start at 1.

References

A reference is a way for an annotation to refer to an external entity. This can be a document, an anchor annotation on a document, an external URL, or a permalink.

Annotation references include the following fields:

Reference Field Description
document_version_id__sys Document-type references only. The ID and version number of the referenced document in the format {documentId}_{majorVersion}_{minorVersion}. For example, 138_2_1.
permalink__sys Permalink-type references only. The ID of the referenced permalink.
url__sys External-type references only. The URL of the external reference. Allows up to 32,000 characters.
type__sys The reference type:document__sys, external__sys, or permalink__sys.
annotation__sys Document-type references only. The ID of the referenced anchor annotation, or null for references to an entire document.

Read Annotations by ID

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "document_version_id__sys": "102_0_2",
            "modified_by_user__sys": "133999",
            "id__sys": "40",
            "placemark": {
                "y_coordinate__sys": 469.97,
                "coordinates__sys": [
                    239.56,
                    469.97,
                    408.11,
                    469.97,
                    239.56,
                    199.16,
                    408.11,
                    199.16
                ],
                "type__sys": "line__sys",
                "height__sys": 270.81,
                "width__sys": 168.55,
                "x_coordinate__sys": 239.56,
                "page_number__sys": 1,
                "style__sys": "line_weight_two__sys"
            },
            "created_by_user__sys": "133999",
            "comment__sys": "Replace image",
            "created_date_time__sys": "2024-02-07T00:18:57.000Z",
            "modified_date_time__sys": "2024-02-07T00:18:57.000Z",
            "title__sys": "",
            "type__sys": "line__sys",
            "tag_names__sys": [
                "IMG"
            ],
            "state__sys": "open__sys",
            "reply_count__sys": 0,
            "color__sys": "red_dark__sys"
        }
    ]
}

Retrieve a specific annotation by the annotation ID. You must have View Content permission on the document version containing the specified ID.

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

Headers

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

URI Path Parameters

Name Description
{doc_id}required The document id field value.
{major_version}required The document major_version_number__v field value.
{minor_version}required The document minor_version_number__v field value.
{annotation_id}required The annotation ID, which can be retrieved with Read Annotations by Document Version and Type.

Response Details

On SUCCESS, the response includes all fields and values for the specified annotation. For more details about annotation fields, see Read Annotations by Document Version and Type.

Read Replies of Parent Annotation

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "document_version_id__sys": "102_0_2",
            "modified_by_user__sys": "133999",
            "type__sys": "reply__sys",
            "id__sys": "41",
            "tag_names__sys": [
                "IMG"
            ],
            "state__sys": "open__sys",
            "placemark": {
                "reply_position_index__sys": 1,
                "type__sys": "reply__sys",
                "reply_parent__sys": "40"
            },
            "created_by_user__sys": "133999",
            "comment__sys": "I think this image is fine.",
            "created_date_time__sys": "2024-02-07T00:37:36.000Z",
            "modified_date_time__sys": "2024-02-07T00:37:36.000Z",
            "color__sys": "red_dark__sys"
        }
    ],
    "responseDetails": {
        "offset": 0,
        "limit": 500,
        "size": 1,
        "total": 1
    }
}

Given a parent annotation ID, retrieves all replies to the annotation. You must have View Content permission on the document version containing the specified parent annotation ID.

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

Headers

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

URI Path Parameters

Name Description
{doc_id}required The document id field value.
{major_version}required The document major_version_number__v field value.
{minor_version}required The document minor_version_number__v field value.
{annotation_id}required The parent annotation ID, which can be retrieved with Read Annotations by Document Version and Type.

Response Details

On SUCCESS, the response lists all fields and values for all replies to the specified annotation. For more details about annotation fields, see Read Annotations by Document Version and Type.

Delete Annotations

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "responseStatus": "SUCCESS",
           "document_version_id__sys": "1_0_1",
           "id__sys": "58",
           "global_version_id__sys": "119899_1_1"
       }
   ]
}

Delete multiple annotations. You must have Annotate permission on the specified document versions to delete annotations.

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

Headers

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

Body Parameters

Upload parameters as a JSON or CSV file. You can delete up to 500 annotations per batch.

Name Description
id__sysrequired The ID of the annotation to delete.
document_version_id__sysrequired The ID and version number of the document where the annotation appears in the format {documentId}_{majorVersion}_{minorVersion}. For example, 138_2_1.

Export Document Annotations to PDF

Request

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

Export the latest version of any document, along with its annotations, as an annotated PDF. This is equivalent to the Export Annotations action in the Vault document viewer UI. You can then view annotations, reply to existing annotations, and create new annotations in a supported PDF editor. When finished, you can import your new notes and replies to Vault using the Import Document Annotations from PDF endpoint.

You must have View Content permission on the latest document version and a security profile that grants the Document: Download Rendition permission to export annotations.

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

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 in PDF format.

Export Document Version Annotations to PDF

Request

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

Export a specific version of any document, along with its annotations, as an annotated PDF. This is equivalent to the Export Annotations action in the Vault document viewer UI. You can then view annotations, reply to existing annotations, and create new annotations in a supported PDF editor. When finished, you can import your new notes and replies to Vault using the Import Document Version Annotations from PDF endpoint.

You must have View Content permission on the specified document version and a security profile that grants the Document: Download Rendition permission to export annotations.

GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations/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

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

Import Document Annotations from PDF

Request

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

Response

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

Load annotations from a PDF to Vault. This is equivalent to the Import Annotations action in the Vault document viewer UI. The file must be a PDF created by exporting annotations for the latest version of the same document through either the Export Annotations action in the Vault UI or the Export Document Annotations as PDF endpoint and edited in a supported PDF editor. You must have a role on the document that includes the Annotate permission.

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

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. Vault truncates annotations that exceed the following character limits:

URI Path Parameters

Name Description
{doc_id} The document id field value.

Response Details

On SUCCESS, Vault uploads the file and its annotations.

Import Document Version Annotations from PDF

Request

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

Response

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

Load annotations from a PDF to Vault. This is equivalent to the Import Annotations action in the Vault document viewer UI. The file must be a PDF created by exporting annotations for the specified version of the same document through either the Export Annotations action in the Vault UI or the Export Document Version Annotations as PDF endpoint. You must have a role on the document that includes the Annotate permission.

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

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. Vault truncates annotations that exceed the following character limits:

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 uploads the file and its annotations.

Retrieve Anchor IDs

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "anchorDataList": [
       {
           "anchorId": 5,
           "noteId": 1567562347570,
           "anchorName": "Cholecap Indications",
           "noteAuthor": "Olivia Cattington",
           "noteTimestamp": "2019-09-04 01:59.08",
           "pageNumber": 3
       },
       {
           "anchorId": 10,
           "noteId": 1568086425522,
           "anchorName": "Elderly patients without clinically evident coronary heart disease",
           "noteAuthor": "Seymour Stein",
           "noteTimestamp": "2019-09-10 03:33.46",
           "pageNumber": 3
       },
       {
           "anchorId": 4,
           "noteId": 1567562218164,
           "anchorName": "Cholecap reduces total-C, LDL-C, and apo B in patients",
           "noteAuthor": "Olivia Cattingtom",
           "noteTimestamp": "2019-09-04 01:56.58",
           "pageNumber": 11
       },
       {
           "anchorId": 6,
           "noteId": 1567562566851,
           "anchorName": "Lower Triglycerides",
           "noteAuthor": "Olivia Cattington",
           "noteTimestamp": "2019-09-04 02:02.47",
           "pageNumber": 19
       }
   ]
}

Retrieve all anchor IDs from the latest version of a document. You must have the View Document permission to retrieve anchor IDs.

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

Headers

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

URI Path Parameters

Name Description
{doc_id} The document id field value.

Response Details

Name Description
anchorId The id of the anchor.
noteId The id of the note annotation that contains the anchor.
anchorName The name of the anchor.
noteAuthor The user who created the anchor.
noteTimestamp The date and time the anchor was created.
pageNumber The page number where the anchor appears in the document.

Retrieve Document Version Notes as CSV

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
  https://myvault.veevavault.com/api/v19.3/objects/documents/10/versions/1/0/doc-export-annotations-to-csv

Response

Doc Name,Doc Number,Doc Version,Note ID,Title,Author,Created,Page,Type,Style,Comment,Status,Tags,Anchor Name
Cholecap Prescribing Information,PPI-0001,1.0,1568086425522,(image annotation),Olivia Cattington,2019-09-10 03:33.46,3,Anchor,Image,,Live,,Elderly patients without clinically evident coronary heart disease
Cholecap Prescribing Information,PPI-0001,1.0,1567562347570,(image annotation),Peter Murphy,2019-09-04 01:59.08,3,Anchor,Image,,Live,,Cholecap Indications
Cholecap Prescribing Information,PPI-0001,1.0,1567562218164,(image annotation),Olivia Cattington,2019-09-04 01:56.58,11,Anchor,Image,,Live,,"Cholecap reduces total-C, LDL-C, and apo B in patients"
Cholecap Prescribing Information,PPI-0001,1.0,1567562566851,(image annotation),Jason Miller,2019-09-04 02:02.47,19,Anchor,Image,,Live,,Lower Triglycerides

Retrieve notes in CSV format for any document. You must have View Content permission for the specified document version.

GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/doc-export-annotations-to-csv

Headers

Name Description
Accept text/csv (default)

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 returns annotation metadata in CSV format if the document has a viewable rendition and at least one annotation. Otherwise, Vault returns an empty CSV.

Retrieve Video Annotations

Request

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

Response

* 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
Timestamp: 1/4/18 11:00:38 AM PST
Version of origin: 2
Status: Open
Comment: Slide 3 displays here

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

## END

Retrieve annotations on any version of a document with a video file as its viewable rendition. You must have the View Content permission on the specified document version to retrieve video annotations.

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 in plain text format:

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 the status of a note annotation, either Open or Resolved.
Comment text The annotation text.

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

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

Request

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

Response

{
    "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": "Staged",
                    "value": "staged__v"
                },
                {
                    "label": "Medication Packaging Text",
                    "value": "medication_packaging_text__c"
                },
                {
                    "label": "Promotional",
                    "value": "promotional__c"
                },
                {
                    "label": "Unclassified",
                    "value": "undefined__v"
                }
            ]
        },
        {
            "value": "supporting_documents__c",
            "label": "Supporting Documents",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": false,
            "system": false,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Staged",
                    "value": "staged__v"
                },
                {
                    "label": "Medication Packaging Text",
                    "value": "medication_packaging_text__c"
                },
                {
                    "label": "Promotional",
                    "value": "promotional__c"
                },
                {
                    "label": "Unclassified",
                    "value": "undefined__v"
                }
            ]
        },
        {
            "value": "references__v",
            "label": "Linked Documents",
            "sourceDocVersionSpecific": true,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Staged",
                    "value": "staged__v"
                },
                {
                    "label": "Medication Packaging Text",
                    "value": "medication_packaging_text__c"
                },
                {
                    "label": "Promotional",
                    "value": "promotional__c"
                },
                {
                    "label": "Unclassified",
                    "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": "Staged",
                    "value": "staged__v"
                },
                {
                    "label": "Medication Packaging Text",
                    "value": "medication_packaging_text__c"
                },

                {
                    "label": "Promotional",
                    "value": "promotional__c"
                },
                {
                    "label": "Unclassified",
                    "value": "undefined__v"
                }
            ]
        },
        {
            "value": "basedon__v",
            "label": "Based on",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Staged",
                    "value": "staged__v"
                },
                {
                    "label": "Medication Packaging Text",
                    "value": "medication_packaging_text__c"
                },
                {
                    "label": "Promotional",
                    "value": "promotional__c"
                },
                {
                    "label": "Unclassified",
                    "value": "undefined__v"
                }
            ]
        },
        {
            "value": "original_source__v",
            "label": "Original Source",
            "sourceDocVersionSpecific": false,
            "targetDocVersionSpecific": true,
            "system": true,
            "singleUse": false,
            "targetDocumentTypes": [
                {
                    "label": "Attachment",
                    "value": "attachment__v"
                },
                {
                    "label": "Staged",
                    "value": "staged__v"
                },
                {
                    "label": "Medication Packaging Text",
                    "value": "medication_packaging_text__c"
                },
                {
                    "label": "Promotional",
                    "value": "promotional__c"
                },
                {
                    "label": "Unclassified",
                    "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": "Staged",
                    "value": "staged__v"
                },
                {
                    "label": "Medication Packaging Text",
                    "value": "medication_packaging_text__c"
                },
                {
                    "label": "Doc Roles Doc",
                    "value": "doc_roles_doc__c"
                },
                {
                    "label": "Promotional",
                    "value": "promotional__c"
                },
                {
                    "label": "Unclassified",
                    "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 example response shows the metadata for the relationship type configured for the specified document type promotional__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

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": null,
  "errorCodes": null,
  "relationships": [
    {
      "relationship": {
        "source_doc_id__v": 886,
        "relationship_type__v": "related_pieces__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.

Note that when Strict Security Mode is on, if the authenticated user does not have explicit role-based View permission to the document (listed in Sharing Settings), custom document relationships added at the subtype or classification level are not returned by this API. Without this permission, custom relationships must be added at the document type level to be returned with this API. Learn more about Strict Security Mode in Vault Help.

Create Single Document Relationship

Request

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

Response

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

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__vrequired The document id of the target document.
relationship_type__vrequired The relationship type retrieved from the Document Relationships Metadata call above.
target_major_version__voptional The major version number of the target document to which the source document will be bound.
target_minor_version__voptional 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

Request

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

Response

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

Create new relationships on multiple documents.

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__vrequired Document id value of the document on which the relationship is being created.
target_doc_id__vrequired Document id value of the document which is being associated with the source document as a related document.
relationship_type__vrequired The type of relationship the target document will have with the source document.

Download Input FileDownload Input File

Create Source Version-Specific Relationships

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

Name Description
source_major_version__vrequired The major version number of the source document.
source_minor_version__vrequired The minor version number of the source document.
relationship_type__vrequired The type of relationship the target document will have with the source document.

Download Input File

Create Target Version-Specific Relationships

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

Name Description
target_major_version__vrequired The major version number of the target document to which the source document will be bound.
target_minor_version__vrequired The minor version number of the target document to which the source document will be bound.
relationship_type__vrequired The type of relationship the target document will have with the source document.

Download Input File

Query Parameters

Name Description
idParam To create relationships based on an unique field, set idParam to a unique field name. You can use any object field which has unique set to true in the object metadata, with the exception of picklists. For example, idParam=external_id__v. You must then set Content-Type to text/csv and include your field name as a column.

Response Details

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

Retrieve Document Relationship

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": null,
    "errorCodes": null,
    "relationships": [
        {
            "relationship": {
                "id": 200,
                "source_doc_id__v": 534,
                "relationship_type__v": "supporting_documents__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.

Note that when Strict Security Mode is on, if the authenticated user does not have explicit role-based View permission to the document (listed in Sharing Settings), custom document relationships added at the subtype or classification level are not returned by this API. Without this permission, custom relationships must be added at the document type level to be returned with this API. Learn more about Strict Security Mode in Vault Help.

Delete Single Document Relationship

Request

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

Response

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

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.

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

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

Delete Multiple Document Relationships

Request

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

Response

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

Delete relationships from multiple documents.

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

Create a CSV or JSON input file.

Name Description
idrequired 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 use the document id field to export a set of documents to your Vault’s file staging server. For example, you could use VQL to query the id of all documents from 2016 where type__v = Promotional Piece, then pass the results into the Export Documents API. This starts an asynchronous job whose status you can check with the Retrieve Document Export Results API.

You can export the following artifacts for a given document:

You can export all versions or choose to export only the latest version.

This API does not support the following:

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

Export Documents

Request

$ 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

Example Body

[{"id": "58"}, {"id":"134"}, {"id":"122"}]

Response

{
    "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 file 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
idrequired 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 job status of the document export request.

Export Document Versions

Request

$ 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

Response

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

Export a specific set of document versions to your Vault’s file 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 for each document version you wish to export:

Name Description
idrequired ID of the document to export.
major_version_number__vrequired The major version number of the document to export.
minor_version_number__vrequired 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

Request

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

Response

{
    "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 your Vault to determine the results of the request.

Before submitting this request:

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

Request

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

Response

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

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

Request

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

Response

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

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

Headers

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

URI Path Parameters

Name Description
{event_type} The event type. For example, distribution__v.
{event_subtype} The event subtype. For example, approved_email__v.

Response Details

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

Create Document Event

Request

$ 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" \
-d "user_email__v=vern@veeva.com" \
https://myvault.veevavault.com/api/v15.0/objects/documents/72/versions/0/2/events

Response

{
    "responseStatus": "SUCCESS"
}

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

Body Parameters

Name Description
event_type__vrequired The event type. For example, distribution__v.
event_subtype__vrequired The event subtype. For example, approved_email__v.
classification__vrequired The event classification. The available classifications vary based on the event_subtype__v.
external_id__vconditional Set an external ID value on the document event. This parameter may be required depending on the document type, subtype, and classification.

Additional fields may be required depending on the document event type, subtype, and classification. Use the Retrieve Document Event SubType Metadata endpoint to retrieve metadata for the required fields.

Response Details

On SUCCESS, Vault logs the document event.

Retrieve Document Events

Request

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

Response

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

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

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

Document templates allow quick creation of new documents from a configured template. When users create a new document from a template, Vault copies the template file and uses that copy as the source file for the new document. This bypasses the content upload process and allows for more consistent document creation. Document templates are associated with a specific document type.

Learn more about Document Template types and limits in Vault Help.

Retrieve Document Template Metadata

Request

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

Response

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

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

Request

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

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "name__v":"claim_document_template__c",
         "label__v":"Claim Document Template",
         "active__v":true,
         "type__v":"claim__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:

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

Retrieve Document Template Attributes

Request

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

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "name__v":"promo_ad_print_document_template__c",
         "label__v":"Promo Ad Print Document Template",
         "active__v":true,
         "type__v":"promotional_piece__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

Request

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

Response

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

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

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-H "Accept: text/csv" \
-F "file=Promo Ad Template.docx" \
-F "label__v=Promo Ad Template" \
-F "type__v=promotional_piece__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

Response

responseStatus,name,errors
SUCCESS,promo_ad_template__c,

Create one basic document template. To create multiple document templates, see Create Multiple Document Templates.

You cannot create templates if your Vault exceeds template limits. Learn more about document template limits in Vault Help.

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

Headers

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

Body Parameters: Basic Document Template

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

Name Description
name__voptional 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__vrequired The label of the new document template. This is the name users will see among the available templates in the UI.
type__vrequired The name of the document type to which the template will be associated.
subtype__voptional 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__voptional 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__vrequired 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.
filerequired The filepath of the file for this document template. Maximum allowed size is 4GB.

Create Multiple Document Templates

Request

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

Response

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

Create up to 500 document templates. You cannot create templates if your Vault exceeds template limits. Learn more about document template limits in Vault Help.

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

Headers

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

Body Parameters: Basic Document Templates

To create basic document templates, create a CSV or JSON input file with the following fields:

Name Description
name__voptional 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__vrequired The label of the new document template. This is the name users will see among the available binder templates in the UI.
type__vrequired The name of the document type to which the template will be associated.
subtype__voptional The name of the document subtype to which the template will be associated.
classification__voptional The name of the document classification to which the template will be associated.
active__vrequired 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.
filerequired The filepath of the file for this document template, from the file staging server. Maximum allowed size is 4GB.

Download Input File

Body Parameters: Controlled Document Templates

To create controlled document templates, create a CSV or JSON input file with the following fields:

Name Description
name__voptional 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__vrequired The label of the new document template. This is the name users will see among the available binder templates in the UI.
active__vrequired 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.
is_controlled__vrequired Set to true to indicate this template is a controlled document template.
template_doc_id__vrequired The document id value to use as the Template Document for this controlled document template. Learn more about setting up valid Template Documents in Vault Help.

Example CSV Input: Basic Document Templates

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:

Update Single Document Template

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-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

Response

responseStatus,name,errors
SUCCESS,promo_ad_web_document_template__c,

Update a single document template in your Vault.

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

Body Parameters

You can update the following fields on document templates:

Field Name Description
name__voptional The name of an existing document template. This is required.
new_nameoptional Change the name of an existing document template.
label__voptional Change the label of an existing document template. This is the name users will see among the available document templates in the UI.
active__voptional 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.

Convert Basic Document Template to Controlled Document Template

To convert a basic document template to a controlled document template, specify the Template Document. Vault will automatically update is_controlled__v on this template to true.

It is not possible to convert a controlled document template into a basic document template.

Field Name Description
template_doc_id__voptional The document id value to use as the Template Document for this controlled document template. Learn more about setting up valid Template Documents in Vault Help.

Update Multiple Document Templates

Request

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

Response

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

Update up to 500 document templates in 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

To update document templates, prepare a CSV or JSON input file. You can update the following fields on document templates:

Name Description
name__vrequired Include the name of an existing document template.
new_nameoptional Change the name of an existing document template.
label__voptional Change the label of an existing document template. This is the name users will see among the available binder templates in the UI.
active__voptional 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.

Download Input File

Convert Basic Document Template to Controlled Document Template

To convert a basic document template to a controlled document template, specify the Template Document. Vault will automatically update is_controlled__v on this template to true.

It is not possible to convert a controlled document template into a basic document template.

Field Name Description
template_doc_id__voptional The document id value to use as the Template Document for this controlled document template. Learn more about setting up valid Template Documents in Vault Help.

Delete Basic Document Template

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

Delete a basic document template from your Vault. You cannot delete controlled document templates. Learn more about controlled template deletion in Vault Help.

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

Headers

Name Description
Accept