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

• password: The user is configured with a username and password.
• sso: The user is configured with an SSO Security Policy.

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:

• A SAML profile, the auth_profiles array is empty. Learn about SAML profiles in Vault Help.
• An OAuth 2.0 / OpenID Connect profile, the auth_profiles array contains information about the policy. Learn about Configuring OAuth 2.0 / OpenID Connect Profiles in Vault Help.

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.

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:

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

Headers

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

Query Parameters

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

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

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:

• CREATE
• RECREATE
• RENAME
• ALTER
• DROP

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.

Asynchronous MDL Requests

Instead of a synchronous request, you must use an asynchronous request if you are executing one of the following operations on 10,000+ raw object records:

• Enabling lifecycles
• Enabling or disabling object types
• Adding or removing a field
• Updating the max length of any variable-length field, such as Text, Long Text, or Rich Text
• Adding or removing an Index
• Changing the fields that compose an Index or otherwise would cause reindexing to occur

A raw object is a Vault object where the data_store attribute is set to raw. To determine if an object is a raw object, retrieve the value of the data_store parameter from the Retrieve Object Metadata endpoint. Learn more about raw objects in Vault Help.

After initiating an asynchronous 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.

If you don’t need to use the asynchronous request, it is best practice to use the synchronous request.

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:

• Enabling lifecycles
• Enabling or disabling object types
• Adding or removing a field
• Updating the max length of any variable-length field, such as Text, Long Text, or Rich Text
• Adding or removing an Index
• Changing the fields that compose an Index or otherwise would cause reindexing to occur

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:

• CREATE
• RECREATE
• RENAME
• ALTER
• DROP

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:

• You must have previously requested a submission export job (via the API) which is no longer active.
• You must have a valid job_id field value returned from the Execute MDL Script Asynchronously 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

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

• Formattedoutput
• Overlaytemplate
• Signaturepage

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

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 hierarchy (Type > Subtype > Classification).

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

Headers

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

Response Details

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

• Standard types end in __v.
• Some Vaults include sample types __c.
• Admins can configure custom types __c.

The response includes the following information:

Metadata Field	Description
types	List of all standard and custom document types in your Vault. These are the top-level of the document hierarchy (Type > Subtype > Classification).
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:

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

Identifying Binders

The document pseudo-field binder__v indicates whether the returned document is a document or a binder. The value of true means it is a binder, false or absence of this field means it is a document. If it is a binder, the binder sections are not listed as part of the response and must be determined using the Retrieve Binder API with the depth=all query parameter.

Identifying CrossLink Documents

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

Retrieve All Documents

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=false > 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. If omitted, defaults to false.

Response Details

On SUCCESS, Vault retrieves the latest version of the source file from the document. The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. 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, you can use the status__v field to create documents in any lifecycle state. Additionally, you can manually set the name, document number, and version number. Vault also bypasses entry criteria, entry actions, and event actions. You must have the Document Migration permission to use this header. 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 name or label of the document type to assign to the new document.
subtype__voptional	The name or label of the document subtype (if one exists on the document type).
classification__voptional	The name or label of the document classification (if one exists on the document subtype).
lifecycle__vrequired	The name or 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 name or label of the document type to assign to the new document.
subtype__voptional	The name or label of the document subtype (if applicable).
classification__voptional	The name or label of the document classification (if one exists on the document subtype).
lifecycle__vrequired	The name or 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 name or label of the document type to assign to the new document.
subtype__voptional	The name or label of the document subtype (if one exists on the document type).
classification__voptional	The name or label of the document classification (if one exists on the document subtype).
lifecycle__vrequired	The name or 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 (undefined__v).*
lifecycle__vrequired	Set the document lifecycle to Inbox or Unclassified (unclassified__v).*

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

• product__v
• study__v
• study_country__v
• site__v

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

* Prior to 21R1.3 (API v21.2), the Unclassified (undefined__v) document type and Inbox (unclassified__v) 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.

Create CrossLink Document

When creating a CrossLink document, you must include all document fields that are required for the specified document type/subtype/classification and no file is uploaded. You must also specify the Vault ID and document ID for the source document which will be bound to the new CrossLink document. Learn about CrossLinks in Vault Help.

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

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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

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 allows you to create documents in any lifecycle state using the status__v field, and to manually set the name, document number, and version number. Vault also bypasses entry criteria, entry actions, and event actions. You must have the Document Migration permission to use this header. 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.

Name	Description
fileconditional	The filepath of the source document. The maximum allowed file size is 500GB. Only required when creating a document from an uploaded file.
name__vrequired	The name of the new document.
type__vrequired	The name or label of the document type to assign to the new document.
subtype__voptional	The name or label of the document subtype (if one exists on the document type).
classification__voptional	The name or label of the document classification (if one exists on the document subtype).
lifecycle__vrequired	The name or 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.

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 name or label of the document type to assign to the new document.
subtype__voptional	The name or label of the document subtype (if one exists on the document type).
classification__voptional	The name or label of the document classification (if one exists on the document subtype).
lifecycle__vrequired	The name or 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.

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 name or label of the document type to assign to the new document.
subtype__voptional	The name or label of the document subtype (if one exists on the document type).
classification__voptional	The name or label of the document classification (if one exists on the document subtype).
lifecycle__vrequired	The name or 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 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 500GB.
name__voptional	The name of the new document.
type__vrequired	Set the document type to Unclassified or Undefined (undefined__v).*
lifecycle__vrequired	Set the document lifecycle to Inbox or Unclassified (unclassified__v).*

* Prior to 21R1.3 (API v21.2), the Unclassified (undefined__v) document type and Inbox (unclassified__v) 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.

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 allows you to change the document number. All other Document Migration Mode overrides available at document creation are ignored, but do not generate an error message. 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.

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

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

Headers

Name	Description
Content-Type	text/csv or application/x-www-form-urlencoded
Accept	application/json (default) or text/csv
X-VaultAPI-MigrationMode	When set to true, Vault allows you to change the document number. All other Document Migration Mode overrides available at document creation are ignored, but do not generate an error message. 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.

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, Vault allows you to manually set the document number and to update documents to any lifecycle state using the status__v field. All other Document Migration Mode overrides available at document creation are ignored, but do not generate an error message. 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.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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, Vault allows you to manually set the document number and to update documents to any lifecycle state using the status__v field. All other Document Migration Mode overrides available at document creation are ignored, but do not generate an error message. 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 allows you to manually set the document number. All other Document Migration Mode overrides available at document creation are ignored, but do not generate an error message. 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.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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

Headers

Name	Description
Content-Type	text/csv
Accept	application/json (default) or text/csv
X-VaultAPI-MigrationMode	Must be set to true. Vault allows you to manually set the name and version number and to create documents in any lifecycle state using the status__v field, but does not allow you to change the document number. Vault also bypasses entry criteria, entry actions, and event actions. 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 file. The maximum allowed file size is 500GB.
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 name or label of the document type to assign to the new document.
subtype__voptional	Enter the name or label of the document subtype (if one exists on the document type).
classification__voptional	Enter the name or label of the document classification (if one exists on the document subtype).
lifecycle__vrequired	Enter the name or label 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 the name or label of the 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.

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 increase the target 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 about creating new draft versions 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
createDraftconditional	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. This parameter is only required to create a new draft version from an existing document or by uploading a source file. To create a new version for a placeholder document, you must omit this parameter.
fileconditional	The filepath of the source document. This parameter is only required in the following scenarios: If createDraft=uploadedContent, use this parameter to include the new document source file. If your target document is a placeholder, use this parameter to upload a source file and create a new draft version of the document.
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.

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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

Headers

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

Body Parameters

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

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

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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

Headers

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

Body Parameters

Create a CSV or JSON input file.

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

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:

• Document Owner role on the document
• All Documents: All Document Actions permission
• Document: Cancel Checkout permission

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

• If the largeSizeAsset query parameter is not set to true, you must include the X-VaultAPI-MigrationMode header.
• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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

Headers

Name	Description
Content-Type	text/csv
Accept	application/json (default) or text/csv
X-VaultAPI-MigrationMode	Must be set to true when importing any rendition type other than large_size_asset__v. 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 file staging.
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.

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.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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.

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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

Headers

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

Body Parameters

Create a CSV or JSON input file.

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

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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

Headers

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

Body Parameters

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 file staging. This works for version-specific attachments and attachments at the document level. If the attachment already exists, Vault uploads the attachment as a new version of the existing attachment. Learn more about attachment versioning in Vault Help.

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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

Headers

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

Body Parameters

Prepare a CSV or JSON input file.

Name	Description
document_id__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 file staging.
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.

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.

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

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

Headers

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

Body Parameters

Prepare a CSV or JSON input file.

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

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.3/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": "external_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": "persistent_id__sys",
                "type": "String",
                "system_managed": false,
                "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}/metadata/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. Valid annotation types include: note__sys line__sys document_link__sys permalink_link__sys anchor__sys reply__sys external_link__sys The following annotation types are only valid in PromoMats Vaults: suggested_link__sys approved_link__sys auto_link__sys keyword_link__sys

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}/metadata/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}/metadata/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": "1001_0_1",
       "external_id__sys": "12345",
       "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": "1001_0_1",
       "placemark": {
           "type__sys": "text__sys",
           "page_number__sys": 1,
           "text_start_index__sys": 10,
           "text_end_index__sys": 15
       },
       "references": [
           {
               "type__sys": "document__sys",
               "document_version_id__sys": "301_0_4",
               "annotation__sys": "104"
           },
           {
               "type__sys": "document__sys",
               "document_version_id__sys": "601_0_1"
           }
       ]
   }
]'
https://myvault.veevavault.com/api/v24.3/objects/documents/annotations/batch \

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "document_version_id__sys": "1001_0_1",
            "global_version_id__sys": "119899_1001_36",
            "id__sys": "141"
        },
        {
            "responseStatus": "SUCCESS",
            "document_version_id__sys": "1001_0_1",
            "global_version_id__sys": "119899_1001_36",
            "id__sys": "142"
        }
    ]
}

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.3/objects/documents/502/versions/0/1/annotations?annotation_types=document_link__sys,note__sys

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "document_version_id__sys": "502_0_1",
            "modified_by_user__sys": "133999",
            "references": [],
            "id__sys": "129",
            "placemark": {
                "y_coordinate__sys": 627.82,
                "coordinates__sys": [
                    72.024,
                    627.82,
                    108.489,
                    627.82,
                    72.024,
                    616.78,
                    108.489,
                    616.78
                ],
                "text_start_index__sys": 5,
                "text_end_index__sys": 5,
                "type__sys": "text__sys",
                "height__sys": 11.04,
                "width__sys": 36.465,
                "x_coordinate__sys": 72.024,
                "page_number__sys": 1,
                "style__sys": "text_highlight__sys"
            },
            "created_by_user__sys": "133999",
            "comment__sys": "Fix kerning",
            "created_date_time__sys": "2024-09-12T23:37:55.000Z",
            "modified_date_time__sys": "2024-09-12T23:37:55.000Z",
            "persistent_id__sys": "119899_129",
            "title__sys": "Patients",
            "type__sys": "note__sys",
            "tag_names__sys": [
                "Typography"
            ],
            "state__sys": "open__sys",
            "reply_count__sys": 0,
            "color__sys": "yellow_light__sys"
        },
        {
            "document_version_id__sys": "502_0_1",
            "modified_by_user__sys": "133999",
            "references": [
                {
                    "document_version_id__sys": "301_0_3",
                    "type__sys": "document__sys",
                    "annotation__sys": "56"
                }
            ],
            "id__sys": "143",
            "external_id__sys": "12345",
            "placemark": {
                "y_coordinate__sys": 717.82,
                "coordinates__sys": [
                    124.188,
                    717.82,
                    177.622,
                    717.82,
                    124.188,
                    706.78,
                    177.622,
                    706.78,
                    72.024,
                    695.38,
                    101.479,
                    695.38,
                    72.024,
                    684.34,
                    101.479,
                    684.34,
                    72.024,
                    672.82,
                    111.348,
                    672.82,
                    72.024,
                    661.78,
                    111.348,
                    661.78,
                    72.024,
                    650.38,
                    120.975,
                    650.38,
                    72.024,
                    639.34,
                    120.975,
                    639.34,
                    72.024,
                    627.82,
                    108.489,
                    627.82,
                    72.024,
                    616.78,
                    108.489,
                    616.78
                ],
                "text_start_index__sys": 1,
                "text_end_index__sys": 5,
                "type__sys": "text__sys",
                "height__sys": 101.04,
                "width__sys": 105.598,
                "x_coordinate__sys": 72.024,
                "page_number__sys": 1,
                "style__sys": "text_link__sys"
            },
            "created_by_user__sys": "133999",
            "comment__sys": "",
            "created_date_time__sys": "2024-09-13T23:04:25.000Z",
            "modified_date_time__sys": "2024-09-13T23:04:25.000Z",
            "persistent_id__sys": "119899_143",
            "title__sys": "Information Insulin Diabetes Indications Patients",
            "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. Valid annotation types include: note__sys line__sys document_link__sys permalink_link__sys anchor__sys reply__sys external_link__sys The following annotation types are only valid in PromoMats Vaults: suggested_link__sys approved_link__sys auto_link__sys keyword_link__sys

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.
persistent_id__sys	The persistent ID. This ID remains the same across all document versions when brought forward. Some older annotations may not have a persistent ID. You can generate one by updating or bringing forward the annotation.
external_id_sys	The external ID. This field is optional and can be any non-empty string with a maximum of 250 characters. If no value is set, the field is excluded from the response.
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.3/objects/documents/301/versions/0/4/annotations/134

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "document_version_id__sys": "301_0_4",
            "modified_by_user__sys": "133999",
            "references": [],
            "id__sys": "134",
            "external_id__sys": "12345",
            "placemark": {
                "type__sys": "sticky__sys",
                "y_coordinate__sys": 25.5,
                "x_coordinate__sys": 50.5,
                "page_number__sys": 1,
                "style__sys": "sticky_icon__sys"
            },
            "created_by_user__sys": "133999",
            "comment__sys": "Remove this.",
            "created_date_time__sys": "2024-09-13T21:57:00.000Z",
            "modified_date_time__sys": "2024-09-13T21:57:00.000Z",
            "persistent_id__sys": "119899_134",
            "title__sys": "",
            "type__sys": "note__sys",
            "state__sys": "open__sys",
            "reply_count__sys": 0,
            "color__sys": "orange_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. Learn more about permissions required to delete annotations and delete brought forward annotations in Vault Help.

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.

• The HTTP Response Header Content-Type is set to application/pdf.
• The HTTP Response Header Content-Disposition contains a filename component which is used as the default name for the local file.

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.

• The HTTP Response Header Content-Type is set to application/pdf.
• The HTTP Response Header Content-Disposition contains a filename component which is used as the default name for the local file.

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:

• Note annotations: Subject (in Header) limited to 32,000 characters
• Note, Line, and Reply annotations: Comment limited to 32,000 characters

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:

• Note annotations: Subject (in Header) limited to 32,000 characters
• Note, Line, and Reply annotations: Comment limited to 32,000 characters

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
X-VaultAPI-MigrationMode	When set to true, creates a document relationship in migration mode. 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
{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__vconditional	The major version number of the target document to which the source document will be bound. Required for target version-specific relationships.
target_minor_version__vconditional	The minor version number of the target document to which the source document will be bound. Required for target version-specific relationships.

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.

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 1000.

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

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

Headers

Name	Description
Content-Type	application/json or text/csv
Accept	application/json (default) or text/csv
X-VaultAPI-MigrationMode	When set to true, creates a document relationship in migration mode. You must have the Document Migration permission to use this header. Learn more about Document Migration Mode in Vault Help.

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.

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.

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.

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.

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 1000.

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

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

Headers

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

Body Parameters

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

• Source document
• Renditions

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

This API does not support the following:

• Fields
• Attachments
• Audit trails
• Related documents
• Signature Pages
• Overlays
• Protected renditions

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.

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

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

GET /api/{version}/objects/documents/batch/actions/fileextract/{jobid}/results

Headers

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

URI Path Parameters

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

Response Details

On SUCCESS, the response includes the following information:

Field Name	Description
job_id	The Job ID value of the document export request.
id	The id value of the exported document.
major_version_number__v	The major version number of the exported document.
minor_version_number__v	The minor version number of the exported document.
file	The path on the file staging.
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:

• The first claim_document_template__c exists at the document type level. It is intended for use with new documents of the claim__c type.
• The second clinical_study_document_template__c exists at the document subtype level. It is intended for use with new documents of the clinical_study__c subtype.
• The third promo_ad_print_document_template__c exists at the document classification level. It is intended for use with new documents of the print__c classification.

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

Retrieve Document Template Attributes

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 file staging. Maximum allowed size is 4GB.

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:

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

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.

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	application/json (default) or application/xml

URI Path Parameters

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

Document Signatures

Retrieve all metadata for signatures on documents and archived documents.

Retrieve Document Signature Metadata

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.2/metadata/query/documents/relationships/document_signature__sysr

Response

{
  "responseStatus": "SUCCESS",
  "properties": {
    "name": "document_signature__sysr",
    "fields": [
      {
        "name": "id",
        "type": "id"
      },
      {
        "name": "signature_user__sys",
        "type": "id"
      },
      {
        "name": "signed_document__sys",
        "type": "id"
      },
      {
        "name": "signed_document_major_version__sys",
        "type": "Number"
      },
      {
        "name": "signed_document_minor_version__sys",
        "type": "Number"
      },
      {
        "name": "signature_time__sys",
        "type": "DateTime"
      },
      {
        "name": "manifest_signature__sys",
        "type": "Boolean"
      },
      {
        "name": "task__sys",
        "type": "String"
      },
      {
        "name": "task_label__sys",
        "type": "String"
      },
      {
        "name": "workflow_label__sys",
        "type": "String"
      },
      {
        "name": "workflow_name__sys",
        "type": "String"
      },
      {
        "name": "signature_meaning__sys",
        "type": "String"
      },
      {
        "name": "verdict_name__sys",
        "type": "String"
      },
      {
        "name": "verdict__sys",
        "type": "String"
      },
      {
        "name": "delegate_user__sys",
        "type": "id"
      },
      {
        "name": "task_description__sys",
        "type": "String"
      },
      {
        "name": "workflow__sys",
        "type": "id"
      },
      {
        "name": "signature_name__sys",
        "type": "String"
      },
      {
        "name": "signature_title__sys",
        "type": "String"
      },
      {
        "name": "delegate_title__sys",
        "type": "String"
      },
      {
        "name": "delegate_name__sys",
        "type": "String"
      }
    ]
  }
}

Retrieve all metadata for signatures on documents. Learn more about signature pages in Vault Help.

GET /api/{version}/metadata/query/documents/relationships/document_signature__sysr

Headers

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

Response Details

On SUCCESS, Vault returns all metadata for document signatures.

Retrieve Archived Document Signature Metadata

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.2/metadata/query/archived_documents/relationships/document_signature__sysr

Response

{
  "responseStatus": "SUCCESS",
  "properties": {
    "name": "document_signature__sysr",
    "fields": [
      {
        "name": "id",
        "type": "id"
      },
      {
        "name": "signature_user__sys",
        "type": "id"
      },
      {
        "name": "signed_document__sys",
        "type": "id"
      },
      {
        "name": "signed_document_major_version__sys",
        "type": "Number"
      },
      {
        "name": "signed_document_minor_version__sys",
        "type": "Number"
      },
      {
        "name": "signature_time__sys",
        "type": "DateTime"
      },
      {
        "name": "manifest_signature__sys",
        "type": "Boolean"
      },
      {
        "name": "task__sys",
        "type": "String"
      },
      {
        "name": "task_label__sys",
        "type": "String"
      },
      {
        "name": "workflow_label__sys",
        "type": "String"
      },
      {
        "name": "workflow_name__sys",
        "type": "String"
      },
      {
        "name": "signature_meaning__sys",
        "type": "String"
      },
      {
        "name": "verdict_name__sys",
        "type": "String"
      },
      {
        "name": "verdict__sys",
        "type": "String"
      },
      {
        "name": "delegate_user__sys",
        "type": "id"
      },
      {
        "name": "task_description__sys",
        "type": "String"
      },
      {
        "name": "workflow__sys",
        "type": "id"
      },
      {
        "name": "signature_name__sys",
        "type": "String"
      },
      {
        "name": "signature_title__sys",
        "type": "String"
      },
      {
        "name": "delegate_title__sys",
        "type": "String"
      },
      {
        "name": "delegate_name__sys",
        "type": "String"
      }
    ]
  }
}

Retrieve all metadata for signatures on archived documents. Learn more about signature pages in Vault Help.

GET /api/{version}/metadata/query/archived_documents/relationships/document_signature__sysr

Headers

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

Response Details

On SUCCESS, Vault returns all metadata for archived document signatures.

Document Tokens

Request

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

Response

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

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

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

Headers

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

Body Parameters

Name	Description
docIdsrequired	Include the docIds request parameter with a comma-separated string of document id values. This will generate tokens for each document. For example: docIds=101,102,103,104
expiryDateOffsetoptional	Include the expiryDateOffset request parameter set to the number of days after which the tokens will expire and the documents will no longer be available in the viewer. If not specified, the tokens will expire after 10 years by default.
downloadOptionoptional	Include the downloadOption request parameter set to PDF, source, both, or none. These allow users viewing the document to be able to download a PDF version or source version (Word™, PowerPoint™, etc.) of the document. If not specified, the download options default to those set on each document.
channeloptional	Include the channel request parameter set to the website object record id value that corresponds to the distribution channel where the document is being made available. If no website record is specified, Vault will assume the request is for Approved Email.
tokenGroupoptional	Include the tokenGroup request parameter to group together generated tokens for multiple documents in order to display the documents being referenced in the same viewer. This value accepts strings of alphanumeric characters (a-z, A-Z, 0-9, and single consecutive underscores) up to 255 characters in length. The token that is passed as a URL parameter to the External Viewer is the primary token and the document it references will be displayed normally. However, any additional documents that have tokens generated with the same case-sensitive tokenGroup string will be displayed in a sidebar of the viewer. The order of documents in the sidebar depends on the order in which the tokens are generated. If multiple tokens are generated with one request, the documents will be ordered top-to-bottom based on the order they are passed to the docIds parameter. For example: If passing the parameters docIds=101,102,103,104 and tokenGroup=group_1 with the request, the top-to-bottom order in the sidebar will be documents 101, 102, 103, 104. If a new request is then made with the parameters docIds=105 and tokenGroup=group_1, document 105 will be added below document 104 in the previous list.
steadyStateoptional	If set to true, Vault generates a token for the latest steady state version of a document. If you do not have View permission, or if a steady-state version does not exist, Vault returns an INVALID_STATE error. If omitted, the default value is false, and Vault generates a token for the latest version, regardless of state.

Response Details

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

Binders

Binders organize documents, sections, and other binders into a hierarchical structure that is useful for packaging related documents together for easier management or eventual publishing. Binders are a kind of document and many of the Document API calls, such as metadata, retrieving and setting properties, security, etc. can be used directly on a binder and will not be replicated here. All API calls related to files and renditions will not work on a binder object. Binders do have unique APIs that allow for interrogating and manipulating the binder structure.

Learn about Documents & Binders in Vault Help.

Retrieve Binders

Retrieve All Binders

Request

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

Response

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

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

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

Alternatively, you can use VQL to find just binders SELECT id FROM binders. See VQL documentation for details.

GET /api/{version}/objects/documents

Headers

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

Response Details

The example response shows the field names and values configured on two separate documents in our Vault:

• The first record retrieved "id": 101 has "binder__v": true. This document is a binder.
• The second record retrieved "id": 102 has "binder__v": false. This document is a regular document.

Retrieve Binder

Request

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

Response

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

• Use this endpoint to retrieve all fields and values configured on a specific binder in you Vault (using the binder ID).
• The response includes the “first level” of the binder section node structure.
• To retrieve additional levels in the binder section node structure, use one of the depth parameters described below.
• For binders with unbound documents, the response includes versions based on binder display options for unbound documents set in the UI. Learn more about Document Type Settings in Vault Help.

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

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

Query Parameters

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

Response Details

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

On SUCCESS, Vault retrieves the fields and components of the binder in a hierarchical structure clearly showing the parent-child relationships for each item and maintaining the specific order of the objects in each level.

Response Details

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

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

Retrieve All Binder Versions

Retrieve all versions of a binder.

Request

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

Response

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

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Response Details

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

Retrieve Binder Version

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "document": {
        "id": 302,
        "version_id": "302_0_1",
        "binder__v": true,
        "owner__v": {
            "groups": [],
            "users": [
                1008906
            ]
        },
        "editor__v": {
            "groups": [],
            "users": []
        },
        "reviewer__v": {
            "groups": [],
            "users": []
        },
        "viewer__v": {
            "groups": [
                1394917493401
            ],
            "users": []
        },
        "coordinator__v": {
            "groups": [],
            "users": []
        },
        "approver__v": {
            "groups": [],
            "users": []
        },
        "consumer__v": {
            "groups": [],
            "users": []
        },
        "distribution_contacts__v": {
            "groups": [],
            "users": []
        },
        "version_creation_date__v": "2024-03-29T15:10:26.574Z",
        "major_version_number__v": 0,
        "annotations_links__v": 0,
        "bookmarks_edited__sys": "false",
        "annotations_all__v": 0,
        "global_version_id__sys": "1000660_302_650",
        "annotations_permalink__v": 0,
        "status__v": "Proposed",
        "annotations_auto__v": 0,
        "product__v": [
            "cholecap"
        ],
        "version_created_by__v": 1008906,
        "annotations_anchors__v": 0,
        "document_number__v": "VV-00033",
        "minor_version_number__v": 1,
        "lifecycle__v": "Campaign Document Lifecycle",
        "global_id__sys": "1000660_302",
        "latest_version__v": true,
        "crosslink__v": false,
        "annotations_notes__v": 0,
        "annotations_suggested__v": 0,
        "locked__v": false,
        "name__v": "Cholecap Campaign Toolkit",
        "type__v": "Campaign Document",
        "annotations_unresolved__v": 0,
        "last_modified_by__v": 1006595,
        "annotations_approved__v": 0,
        "document_creation_date__v": "2024-03-29T15:10:26.574Z",
        "archive__v": false,
        "annotations_resolved__v": 0,
        "annotations_lines__v": 0,
        "version_modified_date__v": "2024-10-23T15:52:24.000Z",
        "created_by__v": 1008906,
        "annotations_claim__v": 0
    },
    "versions": [
        {
            "number": "0.1",
            "value": "https://techpubs.vaultdev.com/api/v24.3/objects/binders/302/versions/0/1"
        }
    ],
    "binder": {
        "nodes": [
            {
                "properties": {
                    "section_number__v": "",
                    "name__v": "Component Items",
                    "order__v": 100,
                    "type__v": "section",
                    "id": "1711725042042:-1375762845",
                    "parent_id__v": "rootNode"
                }
            },
            {
                "properties": {
                    "section_number__v": "",
                    "name__v": "TV Commercials",
                    "order__v": 200,
                    "type__v": "section",
                    "id": "1711725061829:-1997055985",
                    "parent_id__v": "rootNode"
                }
            },
            {
                "properties": {
                    "section_number__v": "",
                    "name__v": "Print Templates",
                    "order__v": 300,
                    "type__v": "section",
                    "id": "1711725049747:736173623",
                    "parent_id__v": "rootNode"
                }
            },
            {
                "properties": {
                    "document_id__v": 601,
                    "name__v": "Cholecap Prescribing Information (PI)-WM",
                    "order__v": 950,
                    "type__v": "document",
                    "id": "1712324813123:1222973257",
                    "parent_id__v": "rootNode"
                }
            },
            {
                "properties": {
                    "document_id__v": 502,
                    "name__v": "Role of CholeCap (veevastatin) in Dyslipidemia- A Clinical Study",
                    "order__v": 1050,
                    "type__v": "document",
                    "id": "1712324748962:-340772953",
                    "parent_id__v": "rootNode"
                }
            },
            {
                "properties": {
                    "document_id__v": 1301,
                    "name__v": "Additional Promotional Materials",
                    "order__v": 1150,
                    "type__v": "binder",
                    "id": "1729698491236:1735240281",
                    "minor_version_number__v": 1,
                    "parent_id__v": "rootNode",
                    "major_version_number__v": 0
                }
            }
        ]
    }
}

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

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

Headers

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

URI Path Parameters

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

Response Details

On SUCCESS, Vault returns the binder contents, fields, and values configured on the binder, including the first level of nodes in the binder’s structure. If a child node has "type__v": "binder" and that binder is bound to a specific version, the response includes the major and minor versions.

For binders with unbound documents, the response includes versions based on binder display options for unbound documents set in the UI. Learn more about Document Type Settings in Vault Help.

Create Binders

Create Binder

Request

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

Response

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

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

POST /api/{version}/objects/binders

Headers

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

Query Parameters

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

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

Create Binder from Template

Request

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

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

Response

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

Request (Create Binder from Template)

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

Response

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

POST /api/{version}/objects/binders

Headers

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

Body Parameters

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

Name	Description
fromTemplaterequired	Include the parameter fromTemplate and specify the name of the template as returned from the document metadata as shown below. Only templates of "kind": binder are allowed.

Response Details

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

Create Binder Version

Request

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

Response

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

Create a new draft version of an existing binder.

Binders cannot be versioned with this endpoint if they exceed 10,000 nodes. Nodes include documents, sections, and component binders.

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Update Binders

Update Binder

Request

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

Response

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

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Reclassify Binder

Request

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

Response

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

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

Learn more about:

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

About this Request

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

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Body Parameters

Name	Description
reclassifyrequired	Set to true. Without this, a standard binder update action is performed.
type__voptional	The name of the document type being assigned to the binder.
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__voptional	The name of the lifecycle.

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

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

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

Update Binder Version

Request

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

Response

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

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

Headers

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

URI Path Parameters

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

Refresh Binder Auto-Filing

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Body Parameters

Name	Description
action=refresh_auto_filingrequired	Trigger auto-filing for a specific binder. This is analogous to the Refresh Auto-Filing action in the UI.

Delete Binders

Delete Binder

Request

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

Response

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

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Delete Binder Version

Request

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

Response

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

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

Headers

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

URI Path Parameters

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

Export Binders

The Export Binder API allows you to export a zip archive with all documents from a binder, or a subset of those documents.

You can also export different artifacts for the selected documents, including source documents, renditions, versions, and document fields.

Learn about Exporting Binders in Vault Help.

Export Binder

Request

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

Response

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

Use this request to export the latest version or a specific version of a binder in your Vault.

• This will export the complete binder, including all binder sections and documents.
• To export only specific binder sections and documents, refer to the next section.
• After initiating an export, you can retrieve its status, results, and download the exported binder.

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

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

Headers

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

URI Path Parameters

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

Exporting Document Source Files

• By default, the source files of all documents in the binder are exported.
• Source documents can be any type of file (ZIP, DOCX, CSV, etc.).
• To exclude source files, add the parameter source=false to the request endpoint.
• For example: .../actions/export?source=false

Exporting Document Renditions

• By default, document renditions are not exported.
• To include renditions, add the parameter renditiontype={rendition_type} to the request endpoint.
• For example: .../actions/export?renditiontype=viewable_rendition__v
• The viewable_rendition__v is the most common, which exports the (typically auto-generated) PDF rendition of your document.
• Note that if the document source file is a PDF, there is no separate viewable rendition to download.

Exporting Document Versions

• By default, the document versions that are exported are determined by the version binding rule configured for the binder, section, or binder document.
• To override the binding rule and export all major versions of each document, add the parameter docversion=major to the request endpoint.
• For example: .../actions/export?docversion=major
• To override the binding rule and export all major and minor versions of each document, add the parameter docversion=major_minor to the request endpoint.
• For example: .../actions/export?docversion=major_minor

Exporting Attachments

• To export binder attachments, include the parameter attachments=all or attachments=latest
• For example: .../actions/export?attachments=all will export all versions of all attachments.
• For example: .../actions/export?attachments=latest will export the latest version of all attachments.
• Available in API v15 or later.

Exporting Document Field Values & Metadata

• By default, exported files include the name__v field value only.
• To export additional fields, include a comma-separated list of field values to export.
• For example, to export the binder name, title, document number, and export file name: .../actions/export?name__v,title__v,document_number__v,export_filename__v
• By default, all document metadata is exported. To exclude the metadata, add the parameter docfield=false

Combining Multiple Request Parameters

• To add multiple parameters to the request endpoint, separate each with the ampersand (&) character.
• For example, to exclude the source file and export a rendition: .../actions/export?source=false&renditiontype=viewable_rendition__v

Response Details

On SUCCESS, the response includes the following information:

• url - The URL to retrieve the current status of the binder export job.
• job_id - The Job ID value is used to retrieve the status and results of the binder export request.

Export Binder Sections

Response

{
  "nodes": [
    {
      "properties": {
        "section_number__v": "02.01.01",
        "name__v": "Investigator Brochure",
        "order__v": 0,
        "type__v": "section",
        "id": "1415381339215",
        "parent_id__v": "1415381339209"
      },
      "nodes": [
        {
          "properties": {
            "document_id__v": 18,
            "name__v": "CHC032-194 Investigator Brochure",
            "order__v": 0,
            "type__v": "document",
            "id": "1415381339220",
            "parent_id__v": "1415381339215"
          }
        },
      ]
    }
  ]
}

Request CSV Input File

To export just this one section and document from the binder, we would submit the following input file:

id
1415381339215
1415381339220

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Binders\export-binder-sections.csv" \
https://myvault.veevavault.com/api/v15.0/objects/binders/454/1/0/actions/export

Response

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

Use this request to export only specific sections and documents from the latest version of a binder in your Vault. This will export only parts of the binder, not the complete binder.

Before submitting this request:

• The Export Binder feature must be enabled in your Vault.
• You must be assigned permissions to use the API.
• You must have the Export Binder permission.
• You must have the View Document permission for the binder.
• Only documents in the binder which you have the View Document permission are available to export.

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

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

Headers

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

URI Path Parameters

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

Query Parameters

Create a CSV or JSON input file with the id values of the binder sections and/or documents to be exported.

To retrieve a list of all nodes from a binder, GET /api/{version}/objects/binders/{binder_id}?depth=all. You may include any number of valid nodes. Vault will ignore id values which are invalid, but will export all which are valid.

For example, the abridged response below includes two nodes from a binder. Node “id”: “1415381339215” is a section (folder) and “id”: “1415381339220” is a document node.

Exporting a binder section node will automatically include all of its subsections and documents therein.

Response Details

On SUCCESS, the response includes the following information:

• url - The URL to retrieve the current status of the binder export job.
• job_id - The Job ID value is used to retrieve the status and results of the binder export request.

Retrieve Binder Export Results

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 1201,
  "id": 454,
  "major_version_number__v": 1,
  "minor_version_number__v": 0,
  "file": "/1201/454/1_0/Nyaxa Compliance Package.zip",
  "user_id__v": 44533
}

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

Before submitting this request:

• You must have previously requested a binder export job (via the API) which is no longer active.
• You must have a valid job_id value (retrieved from the export binder request above).

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

Headers

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

URI Path Parameters

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

Response Details

On SUCCESS, the response includes the following information:

Field Name	Description
job_id	The Job ID value of the binder export request.
id	The id value of the exported binder.
major_version_number__v	The major version number of the exported binder.
minor_version_number__v	The minor version number of the exported binder.
file	The path/location of the downloaded binder ZIP file.
user_id__v	The id value of the Vault user who initiated the binder export job.

Download Exported Binder Files via File Staging

Once your binder export job has been successfully completed, you can download the files from file staging.

Prerequisites

Before downloading the files, the following conditions must be met:

• The binder export job must have been successfully completed.
• The API user must have a permission set which allows the Application: File Staging: Access permission.

Downloading the Files

The exported binder is packaged in a ZIP file on file staging. Learn more.

Binder Relationships

Learn about Binder Relationships in Vault Help.

Retrieve Binder Relationship

Request

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

Response

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

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

Headers

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

URI Path Parameters

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

Response Details

Field Name	Description
id	Relationship ID.
source_doc_id	Document ID of the source document.
relationship_type__v	Relationship type
created_by__v	User ID of user who created the relationship
created_date__v	Timestamp when the relationship was created
target_doc_id__v	Document ID for target document
target_major_version__v	Major version of the target document; null values indicate that the relationship applies to all major versions
target_minor_version__v	Minor version of the target document; null values indicate that the relationship applies to all minor versions

Create Binder Relationship

Request

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

Response

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

POST /api/{version}/objects/binders/{binder_id}/versions/{major_version}/{minor_version}/relationships

Headers

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

URI Path Parameters

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

Body Parameters

Name	Description
target_doc_id__vrequired	Set the target_doc_id__v to the document id of the “target document” to which a relationship will be established with the binder.
relationship_type__vrequired	Set the relationship_type__v to the field value of one of the desired relationshipTypes from the “Documents Relationships Metadata” call.
target_major_version__voptional	If you’re creating a relationship with a specific version of the target document, set the target_major_version__v to the major version number of the target document.
target_minor_version__voptional	If you’re creating a relationship with a specific version of the target document, set the target_minor_version__v to the minor version number of the target document.

Delete Binder Relationship

Request

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

Response

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

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

Headers

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

URI Path Parameters

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

Binder Sections

Retrieve Binder Sections

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "binder": {
    "nodes": [
      {
        "properties": {
          "document_id__v": 7,
          "name__v": "VeevaProm Information",
          "order__v": 0,
          "type__v": "document",
          "id": "1457556160448:810987462",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "document_id__v": 2,
          "name__v": "VeevaProm Consumer Info",
          "order__v": 300,
          "type__v": "document",
          "id": "1457559259279:-602158059",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "document_id__v": 5,
          "name__v": "VeevaProm Brochure",
          "order__v": 301,
          "type__v": "document",
          "id": "1457556176044:-743019200",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "section_number__v": null,
          "name__v": "First Section Folder",
          "order__v": 401,
          "type__v": "section",
          "id": "1457560333810:-909497856",
          "parent_id__v": "rootNode"
        }
      },
      {
        "properties": {
          "section_number__v": null,
          "name__v": "Second Section Folder",
          "order__v": 501,
          "type__v": "section",
          "id": "1457560348267:1179700878",
          "parent_id__v": "rootNode"
        }
      }
    ]
  }
}

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "node": {
    "properties": {
      "section_number__v": null,
      "name__v": "Second Section Folder",
      "order__v": 501,
      "type__v": "section",
      "id": "1457560348267:1179700878",
      "parent_id__v": "rootNode"
    },
    "nodes": [
      {
        "properties": {
          "document_id__v": 24,
          "name__v": "Nyaxa Information Packet",
          "order__v": 0,
          "type__v": "document",
          "id": "1457560406595:-2060980086",
          "parent_id__v": "1457560348267:1179700878"
        }
      },
      {
        "properties": {
          "document_id__v": 23,
          "name__v": "Nyaxa and Your Health",
          "order__v": 100,
          "type__v": "document",
          "id": "1457560409271:-1499449603",
          "parent_id__v": "1457560348267:1179700878"
        }
      },
      {
        "properties": {
          "document_id__v": 25,
          "name__v": "Nyaxa Prescribing Information",
          "order__v": 200,
          "type__v": "document",
          "id": "1457560412997:-1622511549",
          "parent_id__v": "1457560348267:1179700878"
        }
      }
    ]
  }
}

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

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

Headers

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

URI Path Parameters

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

Response Details

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

Retrieve Binder Version Section

Request

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

Request

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

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

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

Headers

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

URI Path Parameters

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

Response Details

See Retrieve Binder Sections example response.

Create Binder Section

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name__v=VeevaProm Additional Information" \
-d "section_number__v=1.3" \
-d "parent_id__v=1427232809771:1381853041" \
-d "order__v=1" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/sections

Response

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

Create a new section in a binder.

Binders cannot exceed 50,000 nodes. Nodes include documents, sections, and component binders. If a binder has reached its limit, binder nodes cannot be added to the binder or any of its component binders, even if the component binders have not reached the 50,000 node limit.

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Body Parameters

Field Name	Description
name__vrequired	Specify a name for the new section.
section_number__voptional	Enter a numerical value for the new section.
parent_id__voptional	If the new section is going to be a subsection, enter the Node ID of the parent section. If left blank, the new section will become a top-level section in the binder. When querying fields on binder nodes, this field corresponds to the parent_section_id__sys field.
order__voptional	Enter a number reflecting the position of the section within the binder or parent section. By default, new components appear below existing components. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.

Response Details

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

Update Binder Section

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name__v=VeevaProm Additional Information" \
-d "section_number__v=3" \
-d "parent_id__v=rootNode" \
-d "order__v=4" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/sections/1427232809771:1381853041

Response

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

Update a section in a binder.

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.
{node_id}	The binder node id of the section. When querying fields on binder nodes, this field corresponds to the section_id__sys field.

Body Parameters

Configure one or more of the following fields with values. These are all optional.

Field Name	Description
name__voptional	Change the name of the binder section.
section_number__voptional	Update the section number value.
order__voptional	Enter a number reflecting the position of the section within the binder or parent section. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.
parent_id__voptional	To move the section to a different section in the binder, include the value of the parent node where it will be moved. When querying fields on binder nodes, this field corresponds to the parent_section_id__sys field.

Response Details

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

Delete Binder Section

Request

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

Response

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

Delete a section from a binder.

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

Headers

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

URI Path Parameters

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

Response Details

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

Binder Documents

Add Document to Binder

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "document_id__v=585" \
-d "parent_id__v=1427232809771:1381853041" \
-d "section_id__v=1" \
-d "binding_rule__v=steady-state" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/documents

Response

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

Add a document to a binder.

Binders cannot exceed 50,000 nodes. Nodes include documents, sections, and component binders. If a binder has reached its limit, binder nodes cannot be added to the binder or any of its component binders, even if the component binders have not reached the 50,000 node limit.

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Body Parameters

Field Name	Description
document_id__vrequired	ID of the document being added to the binder.
parent_id__voptional	Section ID of the parent section, if the document will be in a section rather than top-level. Note: the section ID is unique no matter where it is in the binder hierarchy. Blank means adding the document at the top-level binder.
order__voptional	Enter a number reflecting the position of the document within the binder or section. By default, new components appear below existing components. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.
binding_rule__voptional	The binding rule indicating which version of the document will be linked to the binder and the ongoing behavior. Options are: default (bind to the latest available version (assumed if binding_rule is blank)), steady-state (bind to latest version in a steady-state), current (bind to current version), or specific (bind to a specific version).
major_version_number__voptional	If binding_rule__v=specific, then this is required and indicates the major version of the document to be linked. Otherwise it is ignored.
minor_version_number__voptional	If binding_rule__v=specific, then this is required and indicates the minor version of the document to be linked. Otherwise it is ignored.

Move Document in Binder

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "parent_id__v=1457560333810:-909497856" \
-d "order__v=2" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/documents/1457559259279:-602158059

Response

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

Move a document to a different position within a binder.

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

Headers

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

URI Path Parameters

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

Body Parameters

Field Name	Description
order__voptional	Enter a number reflecting the new position of the document within the binder or section. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.
parent_id__voptional	To move the document to a different section or from a section to the binder’s root node, enter the value of the new parent node.

Response Details

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

Remove Document from Binder

Request

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

Response

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

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

Headers

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

URI Path Parameters

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

Response Details

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

Binder Templates

Learn about Binder Templates in Vault Help.

Retrieve Binder Template Metadata

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "name": "name__v",
      "type": "String",
      "requiredness": "required",
      "max_length": 50,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "label__v",
      "type": "String",
      "requiredness": "required",
      "max_length": 100,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "active__v",
      "type": "Boolean",
      "requiredness": "required",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "type__v",
      "type": "Component",
      "requiredness": "required",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "subtype__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "classification__v",
      "type": "Component",
      "requiredness": "optional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "filing_model__v",
      "type": "Object",
      "requiredness": "optional",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "enable_dynamic_view__v",
      "type": "Boolean",
      "requiredness": "optional",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "binder_template_parameters__v",
      "type": "String",
      "requiredness": "optional",
      "max_length": 100,
      "editable": false,
      "multi_value": true,
      "ordered": false
    }
  ]
}

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

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

Headers

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

Response Details

Field Name	Description
name__v	Binder template name, e.g., binder_template_1__c. This is used in the API when retrieving, creating, updating, or deleting binder templates.
label__v	Binder template label, e.g., “Binder Template 1”. This is the name users see in the UI when selecting a binder template.
type__v	Vault document type to which the template is associated.
subtype__v	Vault document subtype to which the template is associated. This field is only required if the template exists at the document subtype or classification level.
classification__v	Vault document classification to which the template is associated. This field is only required if the template exists at the document classification level.
filing_model__v	eTMF Vaults only. The filing model for the binder template.
enable_dynamic_view__v	eTMF Vaults only. Indicates if the binder template is available in the Dynamic Binder Viewer.
binder_template_parameters__v	eTMF Vaults only. Lists the available binder template parameters for the Dynamic Binder Viewer.

Name	Description
name	The binder template field name (name__v, label__v, type__v, etc.).
type	The binder template field type. This can be one of String, Boolean, Component, or Object (eTMF Vaults).
requiredness	Indicates whether or not a value must be added when creating a binder template. These include: - required : A value must be added. - conditional : For a template to exist at the document subtype or classification level, this is required.
editable	Boolean (true/false) field indicating whether or not a value can be added or edited by a user when creating or updating a binder template.
multi_value	Boolean (true/false) field indicating whether or not the field can have multiple values.
component	The component property applies to the type__v, subtype__v, and classification__v fields and defines the data type that can be set into this field.

Retrieve Binder Template Node Metadata

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "name": "id",
      "type": "id",
      "requiredness": "required",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "parent_id__v",
      "type": "id",
      "requiredness": "optional",
      "editable": true,
      "multi_value": false
    },
    {
      "name": "order__v",
      "type": "Number",
      "requiredness": "optional",
      "max_value": 2147483647,
      "min_value": 0,
      "scale": 0,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "node_type__v",
      "type": "Enum",
      "requiredness": "required",
      "editable": true,
      "multi_value": false,
      "enums": [
        "planned_document",
        "section"
      ]
    },
    {
      "name": "label__v",
      "type": "String",
      "requiredness": "required",
      "max_length": 100,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "number__v",
      "type": "String",
      "requiredness": "optional",
      "max_length": 50,
      "editable": true,
      "multi_value": false
    },
    {
      "name": "lifecycle__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Documentlifecycle"
    },
    {
      "name": "type__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "subtype__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "classification__v",
      "type": "Component",
      "requiredness": "conditional",
      "editable": true,
      "multi_value": false,
      "component": "Doctype"
    },
    {
      "name": "document_template__v",
      "type": "String",
      "requiredness": "conditional",
      "max_length": 50,
      "editable": true,
      "multi_value": false
    }
  ]
}

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

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

Headers

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

Response Details

Binder “nodes” are individual sections or documents in the binder template hierarchy. These can include folders and subfolders in the binder or documents existing within the sections.

Field Name	Description
id	For a given binder, these are the binder node (section or planned document) IDs.
parent_id__v	For a given binder template node, this is the node ID of its parent node. The top-level node is the rootNode.
node_type__v	Binder node types include section and planned_document (content placeholder documents within the binder template).
label__v	Binder template node label (name). For section node types, this is the name of the folder within the binder template. Example: "label__v": "Operational Procedures". For planned document node types, this is the name of the content placeholder document and may include document field tokens. Example: "label__v": "${study_b} - ${site_b} Operational Procedure".
number__v	These apply to binder section node types and are a numerical representation of the section’s hierarchy within the binder template. Example: Given two folders in a binder (under the root node), each containing three subfolders, the first and second folder numbers would be 01 and 02, respectively. The three subfolder numbers within the first and second folders would then be 01.01, 01.02, 01.03 and 02.01, 02.02, 02.03, respectively.
order__v	Order of the node within the binder or within the parent node. Note: There is a known issue affecting this parameter. It may not accurately reflect order.
type__v	Name of the document type to which templates are associated.
subtype__v	Name of the document subtype to which templates are associated.
classification__v	Name of the document classification to which templates are associated.
lifecycle__v	Name of the binder lifecycle to which templates are associated.
document_template__v	Name of the planned document template.
milestone_type__v	eTMF Vaults only. Name of the milestone type associated with the planned document template.
hierarchy_mapping__v	eTMF Vaults only. Object ID pointing to the lowest level in the TMF reference model.

Metadata Field	Description
name	The binder template node field name (id, parent_id__v, node_type__v, etc.).
type	The binder template field type. This can be one of ID, String, Number, Enum, or Component.
requiredness	Indicates whether or not a value must be added when creating a binder template. These include: - required : A value must be added. - conditional : For a template to exist at the document subtype or classification level, this is required.
editable	Boolean (true/false) field indicating whether or not a value can be added or edited by a user when creating or updating a binder template.
multi_value	Boolean (true/false) field indicating whether or not the field can have multiple values.
component	The component property applies to the type__v, subtype__v, classification__v, and lifecycle__v fields and defines the data type that can be set into this field.

Retrieve Binder Template Collection

Request

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

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "name__v": "study_site_level_file_tmf_rm_30__c",
         "label__v": "Study Site Level File TMF RM 2.0",
         "active__v": true,
         "type__v": "trial_master_file__v",
         "subtype__v": null,
         "classification__v": null,
         "filing_model__v": "0MO000000000101"
      },
      {
         "name__v": "study_site_level_file_tmf_rm_20__c",
         "label__v": "Study Site Level File TMF RM 2.0",
         "active__v": "true",
         "type__v": "site_master_file__v",
         "subtype__v": null,
         "classification__v": null,
         "filing_model__v": "0MO000000000102"
      }
   ]
}

Retrieve the collection of all binder templates in your Vault.

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

Headers

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

Response Details

The response lists all binder templates which have been added to the Vault. Shown above, two binder templates exist in our Vault. Both exist at the document type level and are intended for use with the compliance_package__v type. For information about the document template metadata, refer to the “Retrieve Binder Template Attributes” response below.

Retrieve Binder Template Attributes

Request

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

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "name__v": "study_site_level_file_tmf_rm_20__c",
         "label__v": "Study Site Level File TMF RM 2.0",
         "active__v": "true",
         "type__v": "site_master_file__v",
         "subtype__v": null,
         "classification__v": null,
         "filing_model__v": "0MO000000000102"
      }
   ]
}

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

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

Headers

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

URI Path Parameters

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

Response Details

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

Field Name	Description
name__v	Name of the binder template. This value is not displayed to end users in the UI. It is seen by Admins and used in the API.
label__v	Label of the binder template. When users in the UI create binders from templates, they see this value in the list of available templates.
type__v	Vault document type to which the template is associated.
subtype__v	Vault document subtype to which the template is associated. This field is only displayed if the template exists at the document subtype or classification level.
classification__v	Vault document classification to which the template is associated. This field is only displayed if the template exists at the document classification level.
filing_model__v	eTMF Vaults only. Filing model for the binder template.

Retrieve Binder Template Node Attributes

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": "5148",
            "parent_id__v": "studySiteLevelFileTMFRM20",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Trial Management",
            "number__v": "01"
        },
        {
            "id": "9647",
            "parent_id__v": "studySiteLevelFileTMFRM20",
            "order__v": "100",
            "node_type__v": "section",
            "label__v": "Central Trial Documents",
            "number__v": "02"
        },
        {
            "id": "0908",
            "parent_id__v": "studySiteLevelFileTMFRM20",
            "order__v": "200",
            "node_type__v": "section",
            "label__v": "Site Management",
            "number__v": "03"
        },
        {
            "id": "6671",
            "parent_id__v": "5148",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Trial Oversight",
            "number__v": "01.01"
        },
        {
            "id": "4509",
            "parent_id__v": "5148",
            "order__v": "100",
            "node_type__v": "section",
            "label__v": "General",
            "number__v": "01.02"
        },
        {
            "id": "3623",
            "parent_id__v": "6671",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Operational Procedure",
            "number__v": "01.01.01",
            "hierarchy_mapping__v": "00H00484"
        },
        {
            "id": "5575",
            "parent_id__v": "6671",
            "order__v": "100",
            "node_type__v": "section",
            "label__v": "Recruitment Plan",
            "number__v": "01.01.02",
            "hierarchy_mapping__v": "00H00488"
        },
        {
            "id": "StudyBSiteBOperationalProcedur",
            "parent_id__v": "3623",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Operational Procedure",
            "lifecycle__v": "etmf_lifecycle__c",
            "type__v": "trial_management__c",
            "subtype__v": "trial_oversight__c",
            "classification__v": "operational_procedure_manual__c"
        },
        {
            "id": "StudyBSiteBRecruitmentPlan",
            "parent_id__v": "5575",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Recruitment Plan",
            "lifecycle__v": "etmf_lifecycle__c",
            "type__v": "trial_management__c",
            "subtype__v": "trial_oversight__c",
            "classification__v": "recruitment_plan__c"
        },
        {
            "id": "9454",
            "parent_id__v": "4509",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Tracking Information",
            "number__v": "01.02.01",
            "hierarchy_mapping__v": "00H00511"
        },
        {
            "id": "5014",
            "parent_id__v": "4509",
            "order__v": "100",
            "node_type__v": "section",
            "label__v": "Filenote",
            "number__v": "01.02.02",
            "hierarchy_mapping__v": "00H00515"
        },
        {
            "id": "StudyBSiteBOperationalProcedu1",
            "parent_id__v": "9454",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Tracking Information",
            "lifecycle__v": "etmf_lifecycle__c",
            "type__v": "trial_management__c",
            "subtype__v": "general__c",
            "classification__v": "tracking_information__c"
        },
        {
            "id": "StudyBSiteBFileNote",
            "parent_id__v": "5014",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} File Note",
            "lifecycle__v": "etmf_lifecycle__c",
            "type__v": "trial_management__c",
            "subtype__v": "general__c",
            "classification__v": "filenote__c"
        },
        {
            "id": "2443",
            "parent_id__v": "9647",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Trial Documents",
            "number__v": "02.01"
        },
        {
            "id": "0413",
            "parent_id__v": "9647",
            "order__v": "100",
            "node_type__v": "section",
            "label__v": "Subject Information Sheet",
            "number__v": "02.02"
        },
        {
            "id": "5118",
            "parent_id__v": "2443",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Protocol",
            "number__v": "02.01.01",
            "hierarchy_mapping__v": "00H00536"
        },
        {
            "id": "StudyBSiteBTrialProtocol",
            "parent_id__v": "5118",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Trial Protocol",
            "lifecycle__v": "etmf_lifecycle__c",
            "type__v": "central_trial_documents__c",
            "subtype__v": "trial_documents__c",
            "classification__v": "protocol__c"
        },
        {
            "id": "StudyBSiteBSubjectInformationS",
            "parent_id__v": "0413",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Subject Information Sheet",
            "lifecycle__v": "etmf_lifecycle__c",
            "type__v": "central_trial_documents__c",
            "subtype__v": "subject_documents__c",
            "classification__v": "subject_information_sheet__c"
        },
        {
            "id": "9135",
            "parent_id__v": "0908",
            "order__v": "0",
            "node_type__v": "section",
            "label__v": "Site Selection",
            "number__v": "03.01"
        },
        {
            "id": "StudyBSiteBConfidentialityAgre",
            "parent_id__v": "9135",
            "order__v": "0",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Confidentiality Agreement",
            "lifecycle__v": "etmf_lifecycle__c",
            "type__v": "site_management__c",
            "subtype__v": "site_selection__c",
            "classification__v": "confidentiality_agreement__c"
        },
        {
            "id": "StudyBSiteBSiteContacts",
            "parent_id__v": "9135",
            "order__v": "100",
            "node_type__v": "planned_document",
            "label__v": "${study_b} - ${site_b} Site Contacts",
            "lifecycle__v": "etmf_lifecycle__c",
            "type__v": "site_management__c",
            "subtype__v": "site_selection__c",
            "classification__v": "site_contact_details__c"
        }
    ]
}

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

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

Headers

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

URI Path Parameters

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

Response Details

The response lists all attributes configured on each node of a specific binder template in the Vault. The binder template shown above has six nodes.

Field Name	Description
id	The binder node (section or planned document) IDs.
parent_id__v	The node ID of a section or planned document’s parent node. The top-level node is the rootNode.
node_type__v	Binder node types include section and planned_document (content placeholder documents within the binder template).
label__v	Label of the binder section or planned document.
type__v	Vault document type to which planned documents are associated.
subtype__v	Vault document subtype to which planned documents are associated. This field is only displayed if the planned document exists at the document subtype or classification level.
classification__v	Vault document classification to which planned documents are associated. This field is only displayed if the planned document exists at the document classification level.
lifecycle__v	Name of the binder lifecycle to which planned documents are associated.
number__v	These apply to binder section node types and are a numerical representation of the section’s hierarchy within the binder template. Example: Given two folders in a binder (under the root node), each containing three subfolders, the first and second folder numbers would be 01 and 02, respectively. The three subfolder numbers within the first and second folders would then be 01.01, 01.02, 01.03 and 02.01, 02.02, 02.03, respectively.
order__v	Order of the node within the binder or within the parent node. Note: There is a known issue affecting this parameter. It may not accurately reflect order.
hierarchy_mapping__v	eTMF Vaults only. Object ID pointing to the lowest level in the TMF reference model.

Create Binder Template

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "label__v=Claim Binder Template" \
-d "type__v=claim__c" \
-d "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates

Response

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

Create a new binder template in your Vault.

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

Headers

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

Body Parameters

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

Name	Description
name__voptional	The name of the new binder template. If not included, Vault will use the specified label__v value to generate a value for the name__v field.
label__vrequired	The label of the new binder 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. 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 binder template should be set to active, i.e., available for selection when creating a binder.

In this example:

• The input format is set to application/x-www-form-urlencoded.
• The response format is not set and will default to JSON.
• The name__v field is not included. Vault will use the specified label__v field value to create the name__v=claim_binder_template__c.
• The label__v field specifies the binder template label “Claim Binder Template”. This is what users will see among the available templates in the UI.
• The document type__v is specified. This template is being created for binders of type__v=claim__c. Since this exists at the document type level, the subtype and classification are not required.
• The template is being set to active__v=true. It will be available for selection when creating a new binder.

Response Details

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

Bulk Create Binder Templates

Request

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

Response

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

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

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

Headers

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

Body Parameters

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

Name	Description
name__voptional	The name of the new binder templates. If not included, Vault will use the specified label__v value to generate a value for the name__v field.
label__vrequired	The label of the new binder templates. 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 templates will be associated.
subtype__voptional	The name of the document subtype to which the templates will be associated. This is only required if associating the templates with document subtypes.
classification__voptional	The name of the document classification to which the templates will be associated. This is only required if associating the templates with document classifications.
active__vrequired	Set to true or false to indicate whether or not the new binder templates should be set to active, i.e., available for selection when creating a binder.

Example CSV Input

name__v	label__v	type__v	subtype__v	classification__v	active__v
binder_template_1__c	First Binder Template	site_master_file__v			true
	Binder Template 2	trial_master_file__v			true
	Binder Template 3	central_trial_documents__vs	trial_documents__vs	protocol__vs	true
	Binder Template 4	central_trial_documents__vs	reports__vs	clinical_study_report__vs	false

In this example input, we’re creating four new binder templates in our Vault:

• We’ve only specified the name__v value for the first template and given it a different label__v value. The other templates will inherit their name__v values from the label__v values.
• We’ve specified the document type, subtype, and classification to which each binder template will be associated.

In this example:

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

Response Details

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

Create Binder Template Node

Request

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

Create nodes in an existing binder template.

Binders cannot exceed 50,000 nodes, including component binders. If a binder has reached its limit, binder nodes cannot be added to the binder or any of its component binders, even if the component binders have not reached the 50,000 node limit. If this request would result in a binder that exceeds 50,000 nodes, Vault creates as many nodes as possible and halts the transaction at 50,000.

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

Headers

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

URI Path Parameters

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

Body Parameters

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

Name	Description
idrequired	The ID of the binder node. This must be set to a unique number.
parent_id__vrequired	Enter the id of the parent section. To create a node in the top level of the binder (rootNode), leave the value blank.
node_type__vrequired	Set to section or planned_document.
label__vrequired	Label for the section or planned document. For planned documents, this corresponds to “Planned Name” in the UI.
type__voptional	The name of the document type to which the template will be associated.
subtype__voptional	The name of the document subtype to which the templates will be associated. This is only required if associating the template with a document subtype.
classification__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__voptional	Set to true or false to indicate whether or not the binder template should be set to active, i.e., available for selection when creating a binder.
order__voptional	Order of the component (planned document or section) within the binder template or within the template section. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.

Example CSV Input: Create Top-Level Section Binder Nodes

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

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

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

Example CSV Input: Create Sub-Level Section Binder Nodes

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

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

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

Example CSV Input: Create Planned Document Binder Node

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

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

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

In this example:

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

Update Binder Template

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: text/csv" \
-d "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/binders/templates/binder_template_1__c

Response

responseStatus,name,errors
SUCCESS,binder_template_1__c,

Update an existing binder template in your Vault.

By changing the document type/subtype/classification, you can move an existing binder template to a different level of the document type hierarchy, effectively reclassifying the template.

See also: Bulk Update Binder Templates below.

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

Headers

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

Body Parameters

You can update the following fields on binder templates:

Name	Description
name__voptional	Change the name of an existing binder template.
label__voptional	Change the label of an existing binder template. This is the name users will see among the available binder templates in the UI.
type__vrequired	Change the document type to which the template is associated.
subtype__voptional	Change the document subtype to which the template is associated. This is only required if associating the template with a document subtype.
classification__voptional	Change the document classification to which the template is associated. This is only required if associating the template with a document classification.
active__voptional	Set to true or false to indicate whether or not the binder template should be set to active, i.e., available for selection when creating a binder.

In this example:

• The input file format is set to application/x-www-form-urlencoded.
• The response format is set to text/csv.
• The active__v field is set to false. We’re changing the status of this binder template from “Active” to “Inactive”.

Response Details

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

Bulk Update Binder Templates

Request

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

Response

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

Update from 1-500 binder templates in your Vault.

By changing the document type/subtype/classification, you can move an existing binder template to a different level of the document type hierarchy, effectively reclassifying the template.

See also: Update [Single] Binder Template above.

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

Headers

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

Body Parameters

You can update the following fields on binder templates:

Name	Description
name__vrequired	Change the name of existing binder templates.
label__voptional	Change the label of existing binder templates. This is the name users will see among the available binder templates in the UI.
type__vrequired	Change the document type to which the templates are associated.
subtype__voptional	Change the document subtype to which the templates are associated. This is only required if associating the templates with document subtypes.
classification__voptional	Change the document classification to which the templates are associated. This is only required if associating the templates with document classifications.
active__voptional	Set to true or false to indicate whether or not the binder templates should be set to active, i.e., available for selection when creating a binder.

Example CSV Input

name__v	label__v	active__v
binder_template_2__c	Second Binder Template	true
binder_template_3__c	Binder Template 3	true
binder_template_4__c	Binder Template 4	false

In this example input, we’re updating three existing binder templates in our Vault.

• On the first template, we’re updating both the name__v and label__v values.
• On the second template, we’re updating the name__v value and setting the active__v value to true.
• On the third template, we’re updating the name__v value and setting the active__v value to false.

Including a binder field name in the input but leaving its value blank will clear existing values from the field.

In this example:

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

Response Details

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

Replace Binder Template Nodes

Request

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

Replace all binder nodes in an existing binder template. This action removes all existing nodes and replaces them with those specified in the input.

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

Headers

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

URI Path Parameters

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

Example CSV Input

See the Create Binder Template Node above for example inputs, which are the same as those used in this request.

Delete Binder Template

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

Delete an existing binder template from your Vault.

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

Headers

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

URI Path Parameters

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

Binding Rules

Learn about Version Binding in Vault Help.

Update Binding Rule

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "binding_rule__v=steady-state" \
-d "binding_rule_override__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/binding_rule

Response

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

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Body Parameters

Name	Description
binding_rule__voptional	Indicates which binding rule to apply (which document versions to link to the section). Options are: default (bind to the latest available version (assumed if binding_rule is blank)), steady-state (bind to latest version in a steady-state), or current (bind to current version).
binding_rule_override__voptional	Set to true or false to indicate if the specified binding rule should override documents or sections which already have binding rules set. If set to true, the binding rule is applied to all documents and sections within the current section. If blank or set to false, the binding rule is applied only to documents and sections within the current section that do not have a binding rule specified.

Update Binder Section Binding Rule

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "binding_rule__v=steady-state" \
-d "binding_rule_override__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/sections/1427232809771:1381853041/binding_rule

Response

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

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

Headers

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

URI Path Parameters

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

Body Parameters

Name	Description
binding_rule__voptional	Indicates which binding rule to apply (which document versions to link to the section). Options are: default (bind to the latest available version (assumed if binding_rule is blank)), steady-state (bind to latest version in a steady-state), or current (bind to current version).
binding_rule_override__voptional	Set to true or false to indicate if the specified binding rule should override documents or sections which already have binding rules set. If set to true, the binding rule is applied to all documents and sections within the current section. If blank or set to false, the binding rule is applied only to documents and sections within the current section that do not have a binding rule specified.

Response Details

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

Update Binder Document Binding Rule

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "binding_rule__v=specific" \
-d "major_version_number__v=1" \
-d "minor_version_number__v=0" \
https://myvault.veevavault.com/api/v15.0/objects/binders/566/documents/1427491342404:-1828014479/binding_rule

Response

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

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

Headers

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

URI Path Parameters

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

Body Parameters

Name	Description
binding_rule__voptional	Indicates which binding rule to apply (which document versions to link to the section). Options are: default (bind to the latest available version (assumed if binding_rule is blank)), steady-state (bind to latest version in a steady-state), current (bind to current version), or specific (bind to a specific version).
major_version_number__voptional	If binding_rule__v=specific, then this is required and indicates the major version of the document to be linked. Otherwise it is ignored.
minor_version_number__voptional	If binding_rule__v=specific, then this is required and indicates the major version of the document to be linked. Otherwise it is ignored.

Response Details

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

Vault Objects

Each Vault is configured with a set of standard objects (product__v, country__v, study__v, etc.). These vary by application and configuration.

Vault is also configured with a set of system objects (user__sys, person__sys, locale__sys, etc.) These are available for all Vault applications and configurations.

Admins may also create custom objects (region__c, agency__c, manufacturer__c, etc.).

Each object can have multiple object records. For example, the product__v object may have records for products named CholeCap, Nyaxa, and WonderDrug. All object records are user-defined.

The API supports the retrieval of Vault object records and their metadata as well as creating, updating, and deleting object records. It does not support creating or updating Vault objects. This must be done by an Admin in the UI.

Learn about Vault objects in Vault Help.

Retrieve Object Metadata

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "object": {
        "available_lifecycles": [],
        "label_plural": "Products",
        "prefix": "00P",
        "data_store": "standard",
        "description": null,
        "enable_esignatures": false,
        "source": "standard",
        "allow_attachments": false,
        "relationships": [
            {
                "relationship_name": "product_family__vr",
                "relationship_label": "Product Family",
                "field": "product_family__v",
                "relationship_type": "reference_outbound",
                "localized_data": {
                    "relationship_label": {
                        "de": "Produktfamilie",
                        "ru": "Семейство продуктов",
                        "kr": "제품군",
                        "en": "Product Family",
                        "it": "Famiglia di prodotti",
                        "pt_BR": "Família de produtos",
                        "fr": "Famille de produits",
                        "hu": "Termékcsalád",
                        "es": "Familia de productos",
                        "zh": "产品系列",
                        "zh_TW": "產品系列",
                        "th": "ตระกูลผลิตภัณฑ์",
                        "ja": "製品ファミリー",
                        "pl": "Rodzina produktów",
                        "nl": "Productgroep",
                        "tr": "Ürün Ailesi",
                        "pt_PT": "Família do produto"
                    }
                },
                "relationship_deletion": "block",
                "object": {
                    "url": "/api/v21.2/metadata/vobjects/product_family__v",
                    "label": "Product Family",
                    "name": "product_family__v",
                    "label_plural": "Product Families",
                    "prefix": "V95",
                    "localized_data": {
                        "label_plural": {
                            "de": "Produktfamilien",
                            "ru": "Семейства продуктов",
                            "kr": "제품군",
                            "en": "Product Families",
                            "it": "Famiglie di prodotti",
                            "pt_BR": "Famílias de produtos",
                            "fr": "Familles de produits",
                            "hu": "Termékcsaládok",
                            "es": "Familias de productos",
                            "zh": "产品系列",
                            "zh_TW": "產品系列",
                            "th": "ตระกูลผลิตภัณฑ์",
                            "ja": "製品ファミリー",
                            "pl": "Rodziny produktów",
                            "nl": "Productfamilies",
                            "tr": "Ürün Aileleri",
                            "pt_PT": "Famílias de produto"
                        },
                        "label": {
                            "de": "Produktfamilie",
                            "ru": "Семейство продуктов",
                            "kr": "제품군",
                            "en": "Product Family",
                            "it": "Famiglia di prodotti",
                            "pt_BR": "Família de produtos",
                            "fr": "Famille de produits",
                            "hu": "Termékcsalád",
                            "es": "Familia de productos",
                            "zh": "产品系列",
                            "zh_TW": "產品系列",
                            "th": "ตระกูลผลิตภัณฑ์",
                            "ja": "製品ファミリー",
                            "pl": "Rodzina produktów",
                            "nl": "Productgroep",
                            "tr": "Ürün Ailesi",
                            "pt_PT": "Família do produto"
                        }
                    }
                }
            }
        ],
        "urls": {
          "field": "/api/v21.2/metadata/vobjects/product__v/fields/{name}",
          "record": "/api/v21.2/vobjects/product__v/{id}",
          "list": "/api/v21.2/vobjects/product__v",
          "metadata": "/api/v21.2/metadata/vobjects/product__v"
        },
        "role_overrides": false,
        "localized_data": {
            "label_plural": {
              "de": "Produkte",
              "ru": "Продукты",
              "sv": "Produkter",
              "kr": "제품",
              "en": "Products",
              "pt_BR": "Produtos",
              "it": "Prodotti",
              "fr": "Produits",
              "hu": "Termékek",
              "es": "Productos",
              "zh": "产品",
              "zh_TW": "產品",
              "ja": "製品",
              "pl": "Produkty",
              "tr": "Ürünler",
              "nl": "Producten",
              "pt_PT": "Produtos"
            },
            "label": {
              "de": "Produkt",
              "ru": "Продукт",
              "sv": "Produkt",
              "kr": "제품",
              "en": "Product",
              "pt_BR": "Produto",
              "it": "Prodotto",
              "fr": "Produit",
              "hu": "Termék",
              "es": "Producto",
              "zh": "产品",
              "zh_TW": "產品",
              "ja": "製品",
              "pl": "Produkt",
              "tr": "Ürün",
              "nl": "Product",
              "pt_PT": "Produto"
            }
        },
        "object_class": "base",
        "order": 12,
        "allow_types": false,
        "help_content": null,
        "in_menu": true,
        "label": "Product",
        "modified_date": "2020-12-23T04:00:21.000Z",
        "created_by": 1,
        "secure_audit_trail": false,
        "secure_sharing_settings": false,
        "dynamic_security": false,
        "auditable": true,
        "name": "product__v",
        "modified_by": 1,
        "user_role_setup_object": null,
        "secure_attachments": false,
        "prevent_record_overwrite": false,
        "created_date": "2020-05-26T10:19:27.000Z",
        "system_managed": false,
        "fields": [
            {
              "help_content": null,
              "editable": false,
              "lookup_relationship_name": null,
              "description": null,
              "label": "ID",
              "source": "standard",
              "type": "ID",
              "modified_date": "2020-05-26T10:19:27.000Z",
              "created_by": 1,
              "required": false,
              "no_copy": true,
              "localized_data": {
                "label": {
                  "de": "ID",
                  "ru": "Идентификатор",
                  "sv": "ID",
                  "kr": "ID",
                  "en": "ID",
                  "pt_BR": "ID",
                  "it": "ID",
                  "fr": "ID",
                  "hu": "Azonosító",
                  "es": "ID",
                  "zh": "ID",
                  "zh_TW": "識別碼",
                  "ja": "ID",
                  "pl": "Identyfikator",
                  "tr": "Kimlik",
                  "nl": "ID",
                  "pt_PT": "ID"
                }
              },
              "name": "id",
              "list_column": false,
              "modified_by": 1,
              "facetable": false,
              "created_date": "2020-05-26T10:19:27.000Z",
              "lookup_source_field": null,
              "status": [
                "active__v"
              ],
              "order": 0
            }
          ],
          "status": [
            "active__v"
          ],
          "default_obj_type": "base__v"
  }
}

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

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value. For example, product__v, country__v, custom_object__c.

Query Parameters

Name	Description
loc	Set to true to retrieve the localized_data array, which contains the localized (translated) strings for the label and label_plural object fields. If omitted, defaults to false and localized Strings are not included.

Response Details

The response includes all metadata configured on the object, such as:

Name	Description
in_menu	When true, the object appears in the Vault UI’s Business Admin. When configuring objects in the UI, this is the Display in Business Admin setting.
source	The source of this object. For example, standard objects are Veeva-supplied objects, and custom objects are objects created by your organization.
created_by	The user ID of the user who created this object. Standard objects are created by System, which is user ID 1.
fields	An array of the fields available on this object. You can Retrieve Object Field Metadata with a field’s name value.
facetable	When true, the object is available for use as a faceted filter in the Vault UI.Learn more about faceted filters in Vault Help.

Retrieve Object Field Metadata

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.2/metadata/vobjects/product__v/fields/name__v

Response

{
    "responseStatus": "SUCCESS",
    "field": {
        "lookup_relationship_name": null,
        "description": "Do not remove from layout.",
        "start_number": null,
        "source": "standard",
        "type": "String",
        "required": true,
        "list_column": true,
        "facetable": false,
        "format_mask": null,
        "max_length": 128,
        "order": 1,
        "help_content": "The primary name of the product as you wish to see it referenced throughout the system; this may be a brand name or a generic name, but will be visible globally.",
        "editable": true,
        "label": "Product Name",
        "modified_date": "2024-05-15T21:20:44.000Z",
        "created_by": 1,
        "no_copy": false,
        "encrypted": false,
        "system_managed_name": false,
        "value_format": null,
        "unique": true,
        "name": "name__v",
        "modified_by": 133999,
        "created_date": "2023-01-20T19:05:46.000Z",
        "sequential_naming": false,
        "lookup_source_field": null,
        "status": [
            "active__v"
        ]
    }
}

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

Headers

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

URI Path Parameters

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

Query Parameters

Name	Description
loc	Set to true to retrieve the localized_data array, which contains the localized (translated) strings for the label and label_plural object fields. If omitted, defaults to false and localized Strings are not included.

Response Details

The response lists all metadata configured on the specified Vault object field. Note the following field metadata:

Metadata Field	Description
required	When true, the field value must be set when creating new object records.
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.
no_copy	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.
searchable	Boolean indicating the lookup field is searchable. When true, the field is available for filtering and ordering with VQL and in the Vault UI. Only applies to lookup fields. Learn more about lookup fields on Vault Help.
format_mask	The format mask expression if it exists on the field. Learn more about format masks in Vault Help.
rollup	When true, this field is a Roll-up field, and the response includes related metadata such as rollup_function and rollup_relationship_name. Learn more about Roll-up fields in Vault Help.

Retrieve Object Collection

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.3/metadata/vobjects?loc=true

Response

{
  "responseStatus": "SUCCESS",
  "objects": [
{
           "url": "/api/v21.3/metadata/vobjects/user__sys",
           "label": "User",
           "name": "user__sys",
           "label_plural": "Users",
           "prefix": "V0A",
           "order": 87,
           "in_menu": true,
           "source": "system",
           "status": [
               "active__v"
           ],
           "configuration_state": "STEADY_STATE",
           "localized_data": {
               "label_plural": {
                   "de": "Benutzer",
                   "ru": "Пользователи",
                   "sv": "Användare",
                   "kr": "사용자",
                   "en": "Users",
                   "pt_BR": "Usuários",
                   "it": "Utenti",
                   "fr": "Utilisateurs",
                   "hu": "Felhasználók",
                   "es": "Usuarios",
                   "zh": "用户",
                   "zh_TW": "使用者",
                   "th": "ผู้ใช้",
                   "ja": "ユーザ",
                   "pl": "Użytkownicy",
                   "tr": "Kullanıcılar",
                   "nl": "Gebruikers",
                   "pt_PT": "Utilizadores"
               },
               "label": {
                   "de": "Benutzer",
                   "ru": "Пользователь",
                   "sv": "Användare",
                   "kr": "사용자",
                   "en": "User",
                   "pt_BR": "Usuário",
                   "it": "Utente",
                   "fr": "Utilisateur",
                   "hu": "Felhasználó",
                   "es": "Usuario",
                   "zh": "用户",
                   "zh_TW": "使用者",
                   "th": "ผู้ใช้",
                   "ja": "ユーザ",
                   "pl": "Użytkownik",
                   "tr": "Kullanıcı",
                   "nl": "Gebruiker",
                   "pt_PT": "Utilizador"
               }
           }
       },
{
           "url": "/api/v21.3/metadata/vobjects/country__v",
           "label": "Country",
           "name": "country__v",
           "label_plural": "Countries",
           "prefix": "00C",
           "in_menu": true,
           "source": "standard",
           "status": [
               "active__v"
           ],
           "configuration_state": "STEADY_STATE",
           "localized_data": {
               "label_plural": {
                   "de": "Länder",
                   "ru": "Страны",
                   "sv": "Länder",
                   "kr": "국가",
                   "en": "Countries",
                   "it": "Paesi",
                   "pt_BR": "Países",
                   "fr": "Pays",
                   "hu": "Országok",
                   "es": "Países",
                   "zh": "国家/地区",
                   "zh_TW": "國家/地區",
                   "th": "ประเทศ",
                   "ja": "国",
                   "pl": "Kraje",
                   "tr": "Ülkeler",
                   "nl": "Landen",
                   "pt_PT": "Países"
               },
               "label": {
                   "de": "Land",
                   "ru": "Страна",
                   "sv": "Land",
                   "kr": "국가",
                   "en": "Country",
                   "it": "Paese",
                   "pt_BR": "País",
                   "fr": "Pays",
                   "hu": "Ország",
                   "es": "País",
                   "zh": "国家/地区",
                   "zh_TW": "國家/地區",
                   "th": "ประเทศ",
                   "ja": "国",
                   "pl": "Kraj",
                   "tr": "Ülke",
                   "nl": "Land",
                   "pt_PT": "País"
               }
           }
       }
     ]
   }

Retrieve all Vault objects in the authenticated Vault.

GET /api/{version}/metadata/vobjects

Headers

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

Query Parameters

Name	Description
loc	Set to true to retrieve localized (translated) strings for the label and label_plural object fields. If omitted, defaults to false and localized Strings are not included.

Response Details

The response includes a summary of key information (url, label, name, prefix, status, etc.) for all standard and custom Vault Objects configured in your Vault.

Name	Description
localized_data	When loc=true, this array contains translated field labels for each object. This data is only available at the object and field level, and only if localized Strings have been configured on objects in your Vault.
configuration_state	The configuration state of your raw object. STEADY_STATE: This object has no pending configuration changes. IN_DEPLOYMENT: This object has queued or in-progress configuration changes. While in this state, Vault Admins cannot make further edits to the object configuration, and Vault users continue to interact with the Active object configuration version. In this state, you may also cancel deployment.

Retrieve Object Record Collection

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 20,
        "offset": 0,
        "limit": 200,
        "url": "/api/v21.3/vobjects/product__v",
        "object": {
            "url": "/api/v21.3/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v",
            "label_plural": "Products",
            "prefix": "00P",
            "order": 1,
            "in_menu": true,
            "source": "standard",
            "status": [
                "active__v"
            ],
            "configuration_state": "STEADY_STATE"
        }
    },
    "data": [
        {
            "id": "0PR0202",
            "name__v": "CholeCap"
        },
        {
            "id": "0PR0303",
            "name__v": "Gludacta"
        },
        {
            "id": "0PR0404",
            "name__v": "Nyaxa"
        }
    ]
}

Retrieve all records for a specific Vault Object.

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value. For example,product__v, country__v, custom_object__c.

Query Parameters

Name	Description
fields	To specify fields to retrieve, include the parameter fields={FIELD_NAMES}. See Retrieve Specific Object Record Fields for details.

Response Details

The response includes the object metadata for the specified object and the id and name__v of all object records configured on the object.

Name

Description

configuration_state

The configuration state of your raw object. STEADY_STATE: This object has no pending configuration changes. IN_DEPLOYMENT: This object has queued or in-progress configuration changes. While in this state, Vault Admins cannot make further edits to the object configuration, and Vault users continue to interact with the Active object configuration version. In this state, you may also cancel deployment.

Limit, Sort, and Paginate Results

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

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

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

You can change the response to sort in descending desc or ascending asc order based on an object field. For example, to sort by the name of each product in descending order:

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

With a maximum of 200 records returned per page, you must submit a new request to see the “next page” of results (when more than 200 object records exist). Vault provides two methods to accomplish pagination: the offset operator and the next_page/previous_page URLs.

The offset operator is used in request in the same way as the limit operator above. For example, if you’re viewing the first page of 200 results (default maximum per page) out of 1000 total results found and want to see the next 200 results, enter offset=201.

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

The offset operator must be a positive integer. Values equaling to a number larger than the total number of records in the collection will not return any results.

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

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

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

Alternatively, you can use the next_page/previous_page URLs in the response to paginate results. Consider the following abridged response for an object record request:

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 1000,
        "limit": 200,
        "offset": 601,
        "previous_page": "/api/v15.0/vobjects/study__v?limit=200&offset=401",
        "next_page": "/api/v15.0/vobjects/study__v?limit=200&offset=801",
        "object": {
        }
      }
    }

There are a total of 1000 object records found. We used the default maximum of 200 records per page and offset the results to 601, meaning this response is displaying results 601-800 (page 3). Notice the next_page URL shows a limit of 200 and offset of 401 (to view page 4) and the previous_page URL shows a limit of 200 and offset of 801 (to view page 4.).

The pagination URLs are automatically provided in the response when the number of records exceeds the maximum number of results per page. These strings can be used to basically “copy and paste” your next query to paginate the entire result set. The numbers at the end of the string (?limit=200&offset=801") can also be modified with different limits and offsets before using the string to change the pagination.

Note that the next_page and previous_page strings only remain active for about 15 minutes following the query.

Vault-Owned user__sys Records

When you retrieve user__sys records, the response includes multiple system-owned user records that appear in all Vaults. These accounts are used to capture actions that are performed by Vault instead of by a user. These records are not included in license counts, are read-only, and cannot be referenced by another user or document. Learn more in Vault Help.

Retrieve Specific Object Record Fields

You can augment the request to retrieve fields other than the default object record id and name__v by using the fields parameter and a comma-delimited list of object field names.

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/product__v?fields=id,name__v,external_id__v,generic_name__c

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 3,
        "limit": 200,
        "url": "/api/v15.0/vobjects/product__v?fields=id,name__v,external_id__v,generic_name__c",
        "object": {
            "url": "/api/v15.0/metadata/vobjects/product__v",
            "label": "Product",
            "name": "product__v"
          },
    "data": [
        {
            "id": "0PR0202",
            "name__v": "CholeCap",
            "external_id__v": "CHO-PROD-0772",
            "generic_name__c": "cholepridol phosphate"
        },
        {
            "id": "0PR0303",
            "name__v": "Gludacta",
            "external_id__v": "GLU-PROD-0773",
            "generic_name__c": "glucerin sulfate"
        },
        {
            "id": "0PR0404",
            "name__v": "Nyaxa",
            "external_id__v": "NYA-PROD-0774",
            "generic_name__c": "nitroprinaline oxalate"
        }
    ]
  }
}

Retrieve Object Record

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseDetails": {
    "url": "/api/v15.0/vobjects/product__v/00PR0202",
    "object": {
      "url": "/api/v15.0/metadata/vobjects/product__v",
      "label": "Product",
      "name": "product__v",
      "label_plural": "Products",
      "prefix": "00P"
    }
  },
  "data": {
    "external_id__v": "CHO-457",
    "product_family__c": [
      "cholepriol__c"
    ],
    "compound_id__c": "CHO-55214",
    "abbreviation__c": "CHO",
    "therapeutic_area__c": [
      "endocrinology__c"
    ],
    "name__v": "CholeCap",
    "modified_by__v": 12022,
    "modified_date__v": "2016-05-10T21:06:11.000Z",
    "inn__c": null,
    "created_date__v": "2015-07-30T20:55:16.000Z",
    "id": "00PR0202",
    "internal_name__c": null,
    "generic_name__c": "cholepridol phosphate",
    "status__v": [
      "active__v"
    ],
    "created_by__v": 1
  },
  "manually_assigned_sharing_roles": {
    "owner__v": {
      "groups": null,
      "users": [
        12022
      ]
    },
    "viewer__v": {
      "groups": [
        3311303
      ],
      "users": [
        35551,
        48948,
        55002
      ]
    },
    "editor__v": {
      "groups": [
        4411606
      ],
      "users": [
        60145,
        70012,
        89546
      ]
    }
  }
}

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

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

Headers

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

URI Path Parameters

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

Response Details

On SUCCESS, the response lists all fields and values configured on the object record.

When Custom Sharing Rules have been enabled on the object ("dynamic_security": true), the response includes the following additional information:

manually_assigned_sharing_roles

• owner__v
• viewer__v
• editor__v

These are the users and groups that have been manually assigned to each role on the object record.

Not all object records will have users and groups assigned to roles. You can update object records to add or remove users and/or groups on each role.

Create & Upsert Object Records

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Object Records\create_object_records.csv" \
https://myvault.veevavault.com/api/v8.0/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "0PR0771",
                "url": "api/v8.0/vobjects/product__v/0PR0771"
            }
        },
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "0PR0772",
                "url": "api/v8.0/vobjects/product__v/0PR0772"
            }
        },
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "0PR0773",
                "url": "api/v8.0/vobjects/product__v/0PR0773"
            }
        },
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not created."
                }
            ]
        }
    ]
}

Create or upsert Vault object records in bulk.

You can use this endpoint to create User Tasks or User (user__sys) records. Learn more about User Tasks and the User & Person Objects in Vault Help.

• The maximum input file size is 50 MB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• Vault removes XML characters that fall outside of the character range from the request body.
• The maximum batch size is 500.

You can only add relationships on object fields using ID values or based on a unique field on the target object. This API does not support object lookup fields.

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

Headers

Name	Description
Content-Type	text/csv or application/json
Accept	application/json (default) or text/csv
X-VaultAPI-MigrationMode	If set to true, Vault allows you to create or update object records in a noninitial state and with minimal validation, create inactive records, and set standard and system-managed fields such as created_by__v. Does not bypass record triggers. Use the X-VaultAPI-NoTriggers header to bypass all standard and custom SDK triggers. You must have the Record Migration permission to use this header. Learn more about Record Migration Mode in Vault Help.
X-VaultAPI-NoTriggers	If set to true and Record Migration Mode is enabled, it bypasses all standard and custom SDK triggers.

URI Path Parameters

Name	Description
{object_name}	The name of the object, for example, product__v.

Body Parameters

Upload parameters as a JSON or CSV file. The following shows the required standard fields, but an Admin may set other standard or custom object fields as required in your Vault.

If an object has a field default configured, the value you use for that field overrides the default. Learn more about the order of operations for field defaults in Vault Help.

Name	Description
name__vrequired	This field is required unless it is set to system-managed. To find out if an object uses system-managed naming, retrieve its name__v field and look for the system_managed_name property set to true or false. Learn more about system-managed naming in Vault Help.
object_type__voptional	To create objects of a specific object type, add this field with the id of the object type. Requests may include either object_type__v or object_type__v.api_name__v, but not both.
object_type__v.api_name__voptional	To create objects of a specific object type, add this field with the name of the object type. Requests may include either object_type__v or object_type__v.api_name__v, but not both.
source_record_idoptional	To copy an existing object record, add this field with the id of the existing object record. Any values specified for other fields will override the copied values. To perform a deep (hierarchical) copy of a record, see the Deep Copy endpoint.
{field_name}optional	The name of the object field for which to specify a value. Use the Object Metadata API to retrieve all fields configured on objects. You can specify a value for any field with editable: true.
state__voptional	Specifies the lifecycle state of the record when X-VaultAPI-MigrationMode is set to true. For example, draft_state__c.
state_labeloptional	Specifies the lifecycle state type of the record when X-VaultAPI-MigrationMode is set to true. Use the format base:object_lifecycle: followed by the object state type. For example, base:object_lifecycle:initial_state_type. When providing both a state and state type, the state_label value must map to the provided state__v value. For example, if the state__v value is set to draft_state__c, the state_label value must already be set to draft in the destination Vault.

Add Relationships on Object Fields

Many object records have relationships with other object records. For example, the object record details for the Marketing Campaign “CholeCap Campaign” references its parent “CholeCap” Product record. When creating or upserting object records, there are instances where an object field in your input file indicates an object relationship. The API supports the use of reference relationships and parent-child relationships within fields, but not lookup fields. To refer to object relationships in an object field, set the column header in the input file to be a combination of the relationship name and a unique object field, such as name__v. For example, product__vr.name__v references the name of the related Product record.

Create Link Target Records

In PromoMats Vaults, it may sometimes be necessary to create Claim (annotation_keywords__sys) records with valid references to anchor annotations (annotation_types=anchor__sys). The Link Target (link_target__sys) object establishes relationships to documents, anchors, and permalinks and is not visible by default to users in the UI. The API allows you to create Link Target records that reference anchor annotations by providing the annotation ID of the targeted anchor and the corresponding document version ID in the body of a request. Vault then auto-populates the following anchor-related fields on the Link Target record based on the annotation ID provided:

• Anchor Id (anchor_id__sys)
• Anchor Title (anchor_title__sys)
• Anchor Page (anchor_page__sys)
• Reference (target__sys)

The response returns an error if the provided annotation ID does not exist in the authenticated Vault or does not match the provided document version.

Body Parameters

Provide the following fields in your input file to create link_target__sys records:

Name	Description
annotation_id__sysrequired	The annotation’s ID. Retrieve this value from the id__ sys returned from the Read Annotations by Document Version and Type request.
document_version_id__vrequired	The ID and version number of the document where the annotation appears, in the format {documentId}_{majorVersion}_{minorVersion}. For example, 138_2_1.

Add Attachment Fields

To specify a value for an Attachment field, provide the file path on file staging.

The maximum allowed file size for Attachment fields is 100 MB.

Upsert Object Records

Upsert is a combination of create and update. With idParam, you can identify an object record by any unique object field. This allows you to use one input file to create new object records and update existing records at the same time. If a matching record exists, Vault updates the record with the unique field values specified in the input. If no matching object record exists, Vault creates a new record using the values in the input.

Upsert does not support changing object types. Upsert requests that contain object_type__v will always fail, even when the provided value results in no changes to object type.

To upsert records in a specific state or state type, use the Migration Mode header.

Query String Parameters

Name	Description
idParam	To upsert object records, add idParam={field_name} to the request endpoint. For example, idParam=external_id__v. You can use any object field which has unique set to true in the object metadata. For example, idParam=external_id__v.

Admin may set other standard or custom object fields to required. Use the Object Metadata API to retrieve all fields configured on objects. You can add any object field with editable: true.

Vault does not update records and includes a responseStatus of WARNING for operations that result in saving a record without making any changes. Learn more about record changes that result in no operation (no-ops).

Create User Object Records

To create user__sys records, your input file must have all required fields on user__sys. You can choose to create new users in pending state and defer welcome emails by setting activation_date__sys to a future date.

Use the Retrieve Object Metadata endpoint on user__sys to retrieve a full list of fields.

This API does not support the following:

• Creating cross-domain users. To create cross-domain users, use the Create Single User endpoint.
• Adding users to a domain without assigning them to a Vault. To add users to a domain only, use the Create Single User endpoint.
• Adding VeevaID users. To add VeevaID users, use the Create Single User endpoint.
• Changing user passwords.

Body Parameters

Provide the following fields in your input file to create user__sys records:

Name	Description
email__sysrequired	The user’s email address. For example, ewoodhouse@email.com An email address is required to prevent adding duplicate users in error. For example, users John and Jane Smith may both use “jsmith” as a user name. An email address ensures adding the correct user.
first_name__sysrequired	The user’s first name.
last_name__sysrequired	The user’s last name.
username__sysrequired	The user’s Vault user name (login credential). username__sys is a multi-part field. To set the user name, provide the entire value. For example, ewoodhouse@veepharm.com.
language__sysrequired	The user’s preferred language.
locale__sysrequired	The user’s location.
timezone__sysrequired	The user’s time zone.
license_type__sysoptional	The user’s license type. If omitted, the default value is full__v. If your Vault utilizes user-based licensing, assign application licensing using the fields starting with license_ on the User (user__sys) object obtained from the Retrieve Object Metadata endpoint. For example, license_qualityqdocs__sys indicates the QualityDocs application license.
security_profile__sysrequired	The user’s security profile.
status__voptional	The status of the user.
source_person_id__voptional	The person record to be associated with this user. This field is only available in Clinical Operations Vaults. See Managing the Person & Organization Objects for more information.
activation_date__sysoptional	The date the user will first be able to access Vault in YYYY-MM-DD format. If excluded, defaults to today’s date.
send_welcome_email__sysoptional	Set to true to defer welcome email until user’s account activation date. Set to false to send no welcome email.
layout_profile__sysoptional	The ID of the layout profile to assign to the user.

Note that when you create, add, or update user__sys, Vault synchronizes those changes with users across all Vaults to which that user is a member. This includes cross-domain Vaults.

Response Details

Vault returns a responseStatus for the request:

• SUCCESS: This request executed with no warnings. Individual records may be failures.
• WARNING: When upserting records, this request executed with at least one warning on an individual record. Other individual records may be failures.
• FAILURE: This request failed to execute. For example, an invalid sessionId.

On SUCCESS or WARNING, Vault returns a responseStatus for each individual record in the same order provided in the input. The responseStatus for each record can be one of the following:

• SUCCESS: Vault successfully updated at least one field value on this record.
• WARNING: When upserting records, Vault successfully evaluated this record and reported a warning. For example, Vault returns a warning for records that process with no changes (no-op).
• FAILURE: This record could not be evaluated and Vault made no field value changes. For example, an invalid or duplicate record ID.

Note that in CTMS Vaults, if you do not specify a milestone record ID when creating a new Monitoring Event record, this call will automatically create a new Milestone record. However, the id of the new Milestone record is not returned in this response. Learn more about automated CTMS object creation in Vault Help.

Update Object Records

Request

curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-raw 'id,generic_name__vs,product_family__vs,abbreviation__vs,therapeutic_area__vs,manufacturer_name__v,regions__c
00P000000000602,Gluphosphate,gluphosphate__c,GLU,cardiology__vs,Veeva Labs,north_america__c
00P00000000K001,nitroprinaline__c,,NYA,veterinary__c,Veeva Labs,europe__c
00P00000000Q007,veniladrine sulfate,"veniladrine__c,vendolepene__c",VPR,psychiatry__vs,Veeva Labs,"north_america__c,south_america__c"' \
https://myvault.veevavault.com/api/v24.3/vobjects/product__v

Response

{
   "responseStatus": "WARNING",
   "warnings": [
       {
           "warning_type": "NO_DATA_CHANGES",
           "message": "No changes in values - one or more records not updated"
       }
   ],
   "data": [
       {
           "responseStatus": "SUCCESS",
           "data": {
               "id": "00P000000000602",
               "url": "/api/v24.3/vobjects/product__v/00P000000000602"
           }
       },
       {
           "responseStatus": "WARNING",
           "warnings": [
               {
                   "warning_type": "NO_DATA_CHANGES",
                   "message": "No changes in values - record not updated"
               }
           ],
           "data": {
               "id": "00P00000000K001",
               "url": "/api/v24.3/vobjects/product__v/00P00000000K001"
           }
       },
       {
           "responseStatus": "FAILURE",
           "errors": [
               {
                   "type": "INVALID_DATA",
                   "message": "The resource [00P00000000Q007] does not exist"
               }
           ]
       }
   ]
}

Update Object Records in bulk. You can use this endpoint to update user records (user__sys).

• The maximum input size is 50 MB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• Vault removes XML characters that fall outside of the character range from the request body.
• The maximum batch size is 500.

PUT /api/{version}/vobjects/{object_name}

Headers

Name	Description
Content-Type	text/csv or application/json
Accept	application/json (default) or text/csv
X-VaultAPI-MigrationMode	If set to true, Vault allows you to update object records in a noninitial state and with minimal validation, create inactive records, and set standard and system-managed fields such as created_by__v. Does not bypass record triggers. Use the X-VaultAPI-NoTriggers header to bypass all standard and custom SDK triggers. You must have the Record Migration permission to use this header. Learn more about Record Migration Mode in Vault Help.
X-VaultAPI-NoTriggers	If set to true and Record Migration Mode is enabled, it bypasses all standard and custom SDK triggers.

URI Path Parameters

Name	Description
{object_name}	The name of the object, for example, product__v.

Body Parameters

Include parameters as JSON or CSV. The following shows the required standard fields, but an Admin may set other standard or custom object fields as required in your Vault.

Name	Description
idrequired	The object record ID. You can only update an object record ID once per request. If you provide duplicate IDs, the bulk update skips the duplicate record. Instead of id, you can use a unique field defined by the idParam query parameter.
{field_name}optional	The field name to update on this object record. Use the Object Metadata API to retrieve all fields configured on objects. You can update any field with editable: true.
state__voptional	Specifies the lifecycle state of the record when X-VaultAPI-MigrationMode is set to true. For example, draft_state__c.
state_labeloptional	Specifies the lifecycle state type of the record when X-VaultAPI-MigrationMode is set to true. Use the format base:object_lifecycle: followed by the object state type. For example, base:object_lifecycle:initial_state_type. When providing both a state and state type, the state_label value must map to the provided state__v value. For example, if the state__v value is set to draft_state__c, the state_label value must already be set to draft in the destination Vault.

Updating Attachment Fields

To update an Attachment field type, provide the file path on file staging. You can also use Update Attachment Field File to update a single Attachment field for an existing record.

The maximum allowed file size for Attachment fields is 100 MB.

To make no changes to the field, provide the existing attachment’s file handle. To clear the field, leave the value blank.

Query Parameters

Name	Description
idParam	Optional: To identify objects in your input by a unique field, add idParam={field_name} to the request endpoint. You can use any object field that has unique set to true in the object metadata. For example, idParam=external_id__v.

Additional Notes:

• If an object is a parent in a parent-child relationship with another object, you cannot update its status__v field in bulk.
• If an object has a field default configured, the value you use for that field overrides the default. Learn more about the order of operations for field defaults in Vault Help.
• If Dynamic Security (Custom Sharing Rules) is configured on an object, you can add or remove users and groups on manually assigned roles. For example, editor__v.users. This will overwrite any users currently in the role.
• You can also use this call to complete user tasks by setting the complete__v field to true.
• The Edit permission is required on the object record when updating role assignments. This endpoint only supports updating standard roles (for example, viewer, editor, owner) and not custom roles. We recommend using the Assign Users & Groups to Roles on Object Records and the Remove Users & Groups from Roles on Object Records endpoints, which support all roles with better performance.
• When you create, add, or update user__sys, Vault synchronizes those changes with users across all Vaults to which that user is a member. This includes cross-domain Vaults.
• You can use this endpoint to update checkbox fields (Yes/No fields with the Show as checkbox setting) to a null value.

Response Details

Vault returns a responseStatus for the request:

• SUCCESS: This request executed with no warnings. Individual records may be failures.
• WARNING: This request executed with at least one warning on an individual record. Other individual records may be failures.
• FAILURE: This request failed to execute. For example, an invalid sessionId.

On SUCCESS or WARNING, Vault returns a responseStatus for each individual record in the same order provided in the input. The responseStatus for each record can be one of the following:

• SUCCESS: Vault successfully updated at least one field value on this record.
• WARNING: Vault successfully evaluated this record and reported a warning. For example, Vault returns a warning for records that process with no changes (no-op).
• FAILURE: This record could not be evaluated and Vault made no field value changes. For example, an invalid or duplicate record ID.

About No-Ops

An API call which causes no operation to occur is called a no-op. For example, a call to update values on an object record which already has all of the requested values. The call succeeds and no operation occurs.

When the API processes a record with no changes, Vault:

• does not update the record’s last_modified_date.
• does not create an entry in the object record audit history.
• does not execute SDK triggers.

Delete Object Records

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Object Records\delete_object_records.csv" \
https://myvault.veevavault.com/api/v14.0/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "00P000000000607"
            }
        },
     {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "00P00000000O048"
            }
        },
     {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "00P00000000O078"
            }
        }
    ]
}

Delete Object Records in bulk. Admins can also define special deletion rules for objects, which affects how Vault behaves when you attempt to delete an object record. Learn more about limitations on object record deletion in Vault Help.

If you need to delete a parent record along with all of its children and grandchildren, use the Cascade Delete endpoint.

Note that you cannot use this API to delete user__sys records. Use the Update Object Records endpoint to set the status__v field to inactive.

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

DELETE /api/{version}/vobjects/{object_name}

Headers

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

URI Path Parameters

Name	Description
{object_name}	The name of the object, for example, product__v.

Body Parameters

Upload parameters as a JSON or CSV file.

Name	Description
idconditional	The system-assigned object record ID 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 objects 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. For example, idParam=external_id__v.

Admin may set other standard or custom object fields to required. Use the Object Metadata API to retrieve all fields configured on objects. You can update any object field with editable: true.

Response Details

Vault returns a responseStatus for the request:

• SUCCESS: This request executed with no warnings. Individual records may be failures.
• FAILURE: This request failed to execute. For example, an invalid sessionId.

On SUCCESS, Vault returns a responseStatus and record ID for each individual record in the same order provided in the input. The responseStatus for each record can be one of the following:

• SUCCESS: Vault successfully deleted the record.
• FAILURE: This record could not be evaluated and Vault did not delete the object record. For example, an invalid or duplicate record ID.

Cascade Delete Object Record

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v16.0/vobjects/product__v/00P000000000302/actions/cascadedelete

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 27301,
  "url": "/api/v16.0/services/jobs/27404"
}

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

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

Headers

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

URI Path Parameters

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

Retrieve Results of Cascade Delete Job

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Accept: text/csv" \
https://myvault.veevavault.com/api/v16.0/vobjects/cascadedelete/results/product__v/success/27404

Response

Source Object, Record Id
product__v, OP0000146
edl__v, OE0000147
edl_item__v, EE123456

After submitting a request to cascade delete an object record, you can query Vault to determine the results of the request. Before submitting this request:

• You must have previously requested a cascade delete job (via the API) which is no longer active.
• You must have a valid job_id value, retrieved from the response of the cascade delete request.

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

Headers

Name	Description
Accept	text/csv (default)

URI Path Parameters

Name	Description
{object_name}	The name of the object which was deleted.
{job_id}	The ID of the job, retrieved from the response of the job request.
{job_status}	Possible values are success or failure. Find if your job succeeded or failed by retrieving the job status.

Merge Object Records

Duplicate records in Vault can happen due to migrations, integrations, or day-to-day activities and may be difficult to resolve. Vault provides a solution to duplicate records by allowing you to merge two records together. You can only initiate record merges through the Vault API or the Vault Java SDK, and you cannot initiate a record merge through the Vault UI.

Your organization may want to create custom Record Merge Event Handlers with the Vault Java SDK, which can execute custom logic immediately when a record merge begins or after a record merge completes. For example, directly after a merge starts, you can retrieve the field values on the duplicate record. Directly after the merge completes, you can update any desired information from the duplicate record to the main record. This overrides the default merge behavior which does not copy data between the duplicate and main record.

Learn more about merging records in Vault Help.

Initiate Record Merge

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
--data-binary @"records-to-merge.json" \
https://myvault.veevavault.com/api/v24.1/vobjects/account__v/actions/merge

Example JSON Request Body

[
   {
       "duplicate_record_id" : "0V0000000000003",
       "main_record_id" : "0V0000000000013"
   },
   {
       "duplicate_record_id" : "0V0000000000004",
       "main_record_id" : "0V0000000000013"
   },
   {
       "duplicate_record_id" : "0V0000000000005",
       "main_record_id" : "0V0000000000010"
   }
]

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "job_id": 863204
   }
}

Initiate a record merge operation in bulk. Starts a record merge job. When merging two records together, you must select one record to be the main_record_id and one record to be the duplicate_record_id. The merging process updates all inbound references (including attachments) from other objects that point to the duplicate record and moves those over to the main record. Field values on themain record are not changed, and when the process is complete, the duplicate record is deleted. Record merges do not trigger record triggers.

You can only merge two records together in a single operation, one main record and one duplicate record. This is called a merge set. If you have multiple duplicate records you wish to merge into the samemain record, you need to create multiple merge sets and execute multiple record merges.

• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 10 merge sets.

The object must have Enable Merges configured, and the initiating user must have the correct permission such as the Application: Object: Merge Records permission. Learn more about the configuration required for record merges in Vault Help.

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value. For example, account__v. This object must have Enable Merges configured.

Body Parameters

Upload parameters as a JSON or CSV file. You can merge up to 10 merge sets at once.

Name	Description
duplicate_record_idrequired	The ID of the duplicate record. Each duplicate_record_id can only be merged into one main_record_id record. When the merging process is complete, Vault deletes this record.
main_record_idrequired	The ID of the main record. The merging process updates all inbound references (including attachments) from other objects that point to the duplicate record and moves those over to the main record. Vault does not change field values on the main record.

Response Details

On SUCCESS, the job has successfully started and the response includes a job_id. On FAILURE, the job failed to start. There is no partial success.

Retrieve Record Merge Status

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.1/vobjects/merges/863301/status

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "status": "IN_PROGRESS"
    }
}

Given a job_id for a merge records job, retrieve the job status.

Before submitting this request:

• You must have previously requested a record merge job.
• You must have a valid job_id field value returned from the record merge operation.

GET /api/{version}/vobjects/merges/{job_id}/status

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 merge operation. You can start merge operations with the Initiate Record Merge API request or with the Vault Java SDK.

Response Details

On SUCCESS, the merge job may have one of the following statuses:

• IN_PROGRESS: The job is currently running
• SUCCESS: The job completed with no errors; all records were merged
• FAILURE: The job completed with errors; one or more records were not merged

Retrieve Record Merge Results

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.1/vobjects/merges/863301/results

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "merge_sets": [
           {
               "duplicate_record_id": "0V0000000000003",
               "main_record_id": "0V0000000000013",
               "status": "FAILURE",
               "error": {
                   "type": "INVALID_DATA",
                   "message": "Failed validation. Merge was not attempted."
               }
           }
]

Given a job_id for a merge records job, retrieve the job results.

Before submitting this request:

• You must have previously requested a record merge job which is no longer IN_PROGRESS.
• You must have a valid job_id field value returned from the record merge operation.

GET /api/{version}/vobjects/merges/{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 merge operation. You can start merge operations with the Initiate Record Merge API request or with the Vault Java SDK.

Response Details

On SUCCESS, Vault returns the results of the record merge_sets that attempted to merge.

For each of the merge_sets that return a status of FAILURE, Vault may return one of the following error types:

• INVALID_DATA: The merge was not attempted
• PROCESSING_ERROR: The merge was attempted, but failed during processing

Download Merge Records Job Log

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.1/vobjects/merges/873101/log

Response Headers

Content-Type: application/zip;charset=UTF-8
Content-Disposition: attachment;filename="19523-873101.zip"

Example Response File: Merge Record Job History Log

2024-03-01T00:50:01.741Z Started processing merge records job [873101]
2024-03-01T00:50:02.116Z Merge sets [Duplicate Record:[OBE000000006005], Main Record:[OBE00000000D002];Duplicate Record:[OBE000000008004], Main Record:[OBE00000000D002];Duplicate Record:[OBE000000000201], Main Record:[OBE00000000D002]] passed validation and will be merged in job [873101]
2024-03-01T00:50:02.116Z Starting distributed work for merge records job [873101]
2024-03-01T00:50:02.632Z Began processing [INBOUND_CHILD_OBJECT] relationship configured on Object [campaign_country_join__c] field [campaign__c] for job [873101]. [0] record(s) will be processed
2024-03-01T00:50:02.640Z Finished processing [INBOUND_CHILD_OBJECT] relationship for job [873101]
2024-03-01T00:50:02.924Z Began processing [INBOUND_OBJECT] relationship configured on Object [review_meeting__c] field [related_campaign__c] for job [873101]. [0] record(s) will be processed
2024-03-01T00:50:02.932Z Finished processing [INBOUND_OBJECT] relationship for job [873101]
2024-03-01T00:50:02.957Z Began processing [INBOUND_DOCUMENT] relationship configured on Document field [related_campaigns__c] for job [873101]. [0] document(s) will be processed
2024-03-01T00:50:02.964Z Finished processing [INBOUND_DOCUMENT] relationship for job [873101]
2024-03-01T00:50:02.965Z Starting to move attachments for job [873101]
2024-03-01T00:50:03.013Z Finished moving attachments for job [873101]
2024-03-01T00:50:03.197Z Completed merge records job [873101]
2024-03-01T00:50:03.197Z Merge Records job [873101] successfully merged Merge Sets: [Duplicate Record:[OBE000000006005], Main Record:[OBE00000000D002];Duplicate Record:[OBE000000008004], Main Record:[OBE00000000D002];Duplicate Record:[OBE000000000201], Main Record:[OBE00000000D002]]
2024-03-01T00:50:03.206Z
2024-03-01T00:50:03.207Z Job Title: AsyncOperation
2024-03-01T00:50:03.207Z Job Type: ASYNC_OPERATION
2024-03-01T00:50:03.207Z Job Subtype: MERGE_RECORDS_JOB
2024-03-01T00:50:03.207Z Job Schedule Time: 2024-03-01T00:50:02.000Z
2024-03-01T00:50:03.207Z Job Queue Time: 2024-03-01T00:50:02.000Z
2024-03-01T00:50:03.207Z Job Execution Time: 2024-03-01T00:50:02.000Z
2024-03-01T00:50:03.208Z Job Finish Time: 2024-03-01T00:50:03.000Z
2024-03-01T00:50:03.208Z Job Completion Status: Success (COMPLETED_WITH_SUCCESS)

Given a job_id for a merge records job, retrieve the job history log. The same log is available for download through the Vault UI from Admin > Operations > Job Status.

Before submitting this request:

• You must have previously requested a record merge job which is no longer IN_PROGRESS.
• You must have a valid job_id field value returned from the record merge operation.

GET /api/{version}/vobjects/merges/{job_id}/log

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
{job_id}	The job_id field value returned from the merge operation. You can start merge operations with the Initiate Record Merge API request or with the Vault Java SDK.

Response Details

On SUCCESS, Vault downloads the job history log for the specified merge record job. The HTTP Response Header Content-Type is set to application/zip. The HTTP Response Header Content-Disposition contains a default filename component which you can use when naming the local file. If you choose to name this file yourself, make sure you add the .zip extension. The merge record job history log contains information about the merge, such as the merge start and completion times, relationship processing start and end times, attachment processing start and end times, and more. See the Example Response File for details.

Object Types

Vault Objects can be partitioned into Object Types. For example, a Product object may have two different object types: “Pharmaceutical Product” and “Medical Device Product”. These object types may share some fields but also have fields only used in each object type. By using object types, two product groups can not only manage data specific to their business but also easily report on products in both groups.

Retrieve Details from All Object Types

Request

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

Retrieve all object types and object type fields in the authenticated Vault.

GET /api/{version}/configuration/Objecttype

Headers

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

Response

The response lists all object types and all fields configured on each object type. See the next response for details.

Retrieve Details from a Specific Object

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.1/configuration/Objecttype.bicycle__c.road_bike__c?loc=true

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "localized_data": {
           "label_plural": {
               "en": "Road Bikes",
               "fr": "Vélos de route",
               "es": "Bicicletas de carretera"
           },
           "label": {
               "en": "Road Bike",
               "fr": "Vélo de route",
               "es": "Bicicleta de carretera"
           }
       },
       "name": "road_bike__c",
       "object": "bicycle__c",
       "active": true,
       "description": "This object type is intended for model numbers 400-650. For model numbers 650-900, use the Hybrid Bike object type.",
       "additional_type_validations": [],
       "label_plural": "Road Bikes",
       "type_fields": [
           {
               "required": false,
               "name": "id",
               "source": "standard"
           },
           {
               "required": false,
               "name": "object_type__v",
               "source": "standard"
           },
           {
               "required": false,
               "name": "global_id__sys",
               "source": "system"
           },
           {
               "required": false,
               "name": "link__sys",
               "source": "system"
           },
           {
               "required": true,
               "name": "name__v",
               "source": "standard"
           },
           {
               "required": true,
               "name": "status__v",
               "source": "standard"
           },
           {
               "required": false,
               "name": "created_by__v",
               "source": "standard"
           },
           {
               "required": false,
               "name": "created_date__v",
               "source": "standard"
           },
           {
               "required": false,
               "name": "modified_by__v",
               "source": "standard"
           },
           {
               "required": false,
               "name": "modified_date__v",
               "source": "standard"
           }
       ],
       "label": "Road Bike"
   }
}

Retrieve all object types and object type fields configured on a given object.

GET /api/{version}/configuration/{object_name_and_object_type}

Headers

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

URI Path Parameters

Name	Description
{object_name_and_object_type}	The object name followed by the object type in the format Objecttype.{object_name}.{object_type}. For example, Objecttype.product__v.base__v.

Query Parameters

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

Response

The response lists all object types and all fields configured on each object type for the specific object.

Change Object Type

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: application/json" \
--data-binary @"C:\Vault\Objects\objecttypes.csv" \
https://myvault.veevavault.com/api/v24.2/vobjects/product__v/actions/changetype

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "00P07710",
                "url": "api/v24.2/vobjects/product__v/00P07710"
            }
        }
    ]
}

Change the object types assigned to object records. Any field values that exist on both the original and new object type will carry over to the new type. All other field values will be removed, as only fields on the new type are valid. You can set field values on the new object type in the CSV input.

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

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The name of the object.

Body Parameters

Upload parameters as a JSON or CSV file.

Name	Description
idrequired	The ID of the object record.
object_type__vrequired	The ID of the new object type.

Object Roles

Object records can have different roles available to them depending on their type and lifecycles. There are a set of standard roles that ship with Vault: owner__v, viewer__v, and editor__v. In addition, Admins can create custom roles defined per lifecycle. Not all object records will have users and groups assigned to roles. Learn more about roles on object records in Vault Help.

Through the object record role APIs, you can:

• Retrieve available roles on object records
• Retrieve who is currently assigned to a role
• Add additional users and groups to a role
• Remove users and groups from roles

Note that all user and group information is returned as IDs, so you need to use the Retrieve User or Retrieve Group API to determine the name.

For roles on documents or binders, see Roles.

Retrieve Object Record Roles

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.2/vobjects/campaign__c/OBE000000000412/roles

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "name": "approver__c",
            "users": [
                61583,
                61584,
                86488
            ],
            "groups": [
                3,
                1392631750101
            ],
            "assignment_type": "manual_assignment"
        }
      ]
    }

Retrieve manually assigned roles on an object record and the users and groups assigned to them.

GET /api/{version}/vobjects/{object_name}/{id}/roles{/role_name}

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name.
{id}	The id of the document, binder, or object record.
{/role_name}	Optional: Include a role name to filter for a specific role. For example, owner__v.

Response Details

Even though the owner__v role is automatically assigned when you apply Custom Sharing Rules, the assignment_type for roles on objects is always manual_assignment.

Assign Users & Groups to Roles on Object Records

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Roles\assign_object_record_roles.csv" \
https://myvault.veevavault.com/api/v17.2/vobjects/campaign__c/roles

Response

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

Example JSON Request Body

[
  {
    "id": "OBE000000000412",
    "roles": [
      {
        "role": "content_creator__c",
        "users": "61590"
      }
      ]
  }
]

Assign users and groups to roles on an object record in bulk.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

Assigning users and groups to roles is additive, and duplicate groups are ignored. For example, if groups 1 and 2 are currently assigned to a particular role and you assign groups 2 and 3 to the same role, the final list of groups assigned to the role will be 1, 2, and 3.

POST /api/{version}/vobjects/{object_name}/roles

Headers

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

URI Path Parameters

Name	Description
{object_name}	The name of the object where you want to update records.

Body Parameters

Prepare a JSON or CSV input file. User and group assignments are ignored if they are invalid, inactive, or already exist.

Name	Description
idrequired	The object record ID.
role__v.usersoptional	A string of user id values for the new role.
role__v.groupsoptional	A string of group id values for the new role.

See Example JSON Request Body in the right-hand column, or click the button below to download a sample CSV input file.

Response Details

On SUCCESS, The response includes the object record id.

Remove Users & Groups from Roles on Object Records

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Roles\remove_object_record_roles.csv" \
https://myvault.veevavault.com/api/v17.2/vobjects/campaign__c/roles

Response

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

Example JSON Request Body

[
  {
    "id": "OBE000000000412",
    "roles": [
      {
        "role": "content_creator__c",
        "users": "61590"
      }
      ]
  }
]

Remove users and groups from roles on an object record in bulk.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

DELETE /api/{version}/vobjects/{object_name}/roles

Headers

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

URI Path Parameters

Name	Description
{object_name}	The name of the object where you want to remove roles.

Body Parameters

Prepare a JSON or CSV input file. Users and groups are ignored if they are invalid or inactive.

Name	Description
idrequired	The object record ID.
role__v.usersoptional	A string of user id values to remove.
role__v.groupsoptional	A string of group id values to remove.

See Example JSON Request Body in the right-hand column, or click the button below to download a sample CSV input file.

Response Details

On SUCCESS, The response includes the object record id.

Object Record Attachments

Determine if Attachments are Enabled on an Object

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "object": {
        "created_date": "2014-02-03T20:12:29.000Z",
        "created_by": 1,
        "allow_attachments": true,
        "auditable": true,
        "modified_date": "2015-01-06T22:34:15.000Z",
        "status": [
            "active__v"
        ],
        "urls": {
            "field": "/api/v15.0/metadata/vobjects/site__v/fields/{NAME}",
            "record": "/api/v15.0/vobjects/site__v/{id}",
            "attachments": "/api/v15.0/vobjects/site__v/{id}/attachments",
            "list": "/api/v15.0/vobjects/site__v",
            "metadata": "/api/v15.0/metadata/vobjects/site__v"
        },
        "label_plural": "Study Sites",
        "role_overrides": false,
        "label": "Study Site",
        "in_menu": true,
        "help_content": null,
        "source": "standard",
        "order": null,
        "modified_by": 46916,
        "description": null,
        "name": "site__v"
    }
}

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

Headers

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

URI Path Parameters

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

Response Details

Shown above, “allow_attachments” is set to true for this object and “attachments” is included in the list of urls, indicating that attachments are enabled on the site__v object. This means that any of the object records can have attachments.

Retrieve Object Record Attachments

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 558,
            "filename__v": "Site Contact List.docx",
            "description__v": "Facilities information and contacts",
            "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "size__v": 11450,
            "md5checksum__v": "9c6f61847207898ca98431d3e9ad176d",
            "version__v": 3,
            "created_by__v": 46916,
            "created_date__v": "2015-01-07T21:42:47.772Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/3"
                }
            ]
        },
        {
            "id": 571,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 1,
            "created_by__v": 46916,
            "created_date__v": "2015-01-16T22:28:44.039Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions/1"
                }
            ]
        }
    ]
}

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

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

Headers

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

URI Path Parameters

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

Response Details

Shown above, the site__v object record has three versions of attachment id 558 and one version of attachment id 571. Attachment versioning uses integer numbers beginning with 1 and incrementing sequentially (1, 2, 3,…). There is no concept of major or minor version numbers with attachments.

Retrieve Object Record Attachment Metadata

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 558,
            "filename__v": "Site Contact List.docx",
            "description__v": "Facilities information and contacts",
            "format__v": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "size__v": 11450,
            "md5checksum__v": "9c6f61847207898ca98431d3e9ad176d",
            "version__v": 3,
            "created_by__v": 46916,
            "created_date__v": "2015-01-07T21:42:47.772Z",
            "versions": [
                {
                    "version__v": 1,
                    "url": "https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/1"
                },
                {
                    "version__v": 2,
                    "url": "https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/2"
                },
                {
                    "version__v": 3,
                    "url": "https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/558/versions/3"
                }
            ]
        }
    ]
}

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id}	The object record id field value.
{attachment_id}	The attachment id field value.

Response Details

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

Retrieve Object Record Attachment Versions

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "version__v": 1,
            "url": "https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions/1"
        }
    ]
}

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id}	The object record id field value.
{attachment_id}	The attachment id field value.

Retrieve Object Record Attachment Version Metadata

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": 571,
            "filename__v": "Site Area Map.png",
            "format__v": "image/png",
            "size__v": 109828,
            "md5checksum__v": "78b36d9602530e12051429e62558d581",
            "version__v": 1,
            "created_by__v": 46916,
            "created_date__v": "2015-01-16T22:28:44.039Z"
        }
    ]
}

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id}	The object record id field value.
{attachment_id}	The attachment id field value.
{attachment_version}	The attachment version__v field value.

Download Object Record Attachment File

Request

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

Response Headers

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

Downloads the latest version of the specified attachment from the object record.

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id}	The object record id field value.
{attachment_id}	The attachment id field value.

Response Details

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 component which can be used when naming the local file. When downloading attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachments (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Download Object Record Attachment Version File

Request

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

Response Headers

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

Downloads the specified version of the attachment from the object record.

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id}	The object record id field value.
{attachment_id}	The attachment id field value.
{attachment_version}	The attachment version__v field value.

Response Details

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

The HTTP Response Header Content-Type is set to 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 component which can be used when naming the local file. When downloading attachments with very small file size, the HTTP Response Header Content-Length is set to the size of the attachment. Note that for most attachments (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Download All Object Record Attachment Files

Request

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

Response Headers

Content-Type: application/zip;charset=UTF-8
Content-Disposition: attachment;filename="Product CholeCap - attachments.zip"

Downloads the latest version of all attachments from the specified object record.

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

Headers

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

URI Path Parameters

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

Response Details

On SUCCESS, Vault retrieves the latest version of all attachments from the object record. The attachments are packaged in a ZIP file with the file name: {object type label} {object record name} - attachments.zip.

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

Create Object Record Attachment

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data":
    [{
        "id": "558",
        "version__v": 3
    }]
}

Create a single object record attachment. 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}/vobjects/{object_name}/{object_record_id}/attachments

Headers

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

URI Path Parameters

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

File Upload

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

If an attachment is added which has the same filename as an existing attachment on a given object record, the new attachment is added as a new version of the existing attachment. If an attachment is added which is exactly the same (same MD5 checksum value) as an existing attachment on a given object record, the new attachment is not added.

The following attribute values are determined based on the file in the request: filename__v, format__v, size__v.

Create Multiple Object Record Attachments

Request

$ curl -X POST  -H 'Authorization: {SESSION_ID}\
-H 'Accept: text/csv' \
-H 'Content-Type: text/csv' \
--data-binary @"create_attachments.csv" \
https://myvault.veevavault.com/api/v19.3/vobjects/veterinary_patient__c/attachments/batch

Response

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

You can create object record attachments in bulk with a JSON or CSV input file. You must first load the attachments to file staging. If the attachment already exists in your Vault, Vault uploads it as a new version of the existing attachment. Learn more about attachment versioning in Vault Help.

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

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

Headers

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

Body Parameters

Prepare a CSV or JSON input file.

Name	Description
idrequired	The id of the object record to which to add the 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, it is added as a new version. Cannot exceed 218 bytes.
filerequired	The filepath of the attachment on file staging.
description__voptional	Description of the attachment. Maximum 1,000 characters.
external_id__voptional	The external ID value of the attachment.

Restore Object Record Attachment Version

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571/versions/2?restore=true

Response

{
    "responseStatus": "SUCCESS",
    "data":
    {
        "id": "571",
        "version__v": 2
    }
}

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id}	The object record id field value.
{attachment_id}	The attachment id field value.
{attachment_version}	The attachment version__v field value.

Update Object Record Attachment Description

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value (product__v, country__v, custom_object__c, etc.).
object_record_id}	The object record id field value.
{attachment_id}	The attachment id field value.

Body Parameters

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

Update Multiple Object Record Attachment Descriptions

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H 'Accept: text/csv' \
-H 'Content-Type: text/csv' \
--data-binary @"create_attachments.csv" \
https://myvault.veevavault.com/api/v19.3/vobjects/veterinary_patient__c/attachments/batch

Response

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

Update object record attachments in bulk with a JSON or CSV input file. You can only update the latest version of an attachment.

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

PUT /api/{version}/vobjects/{object_name}/attachments/batch

Headers

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

Body Parameters

Prepare a CSV or JSON input file.

Name	Description
idrequired	The id of the object record to which to add the attachment.
attachment_idrequired	The id of the attachment you are updating on the record.
external_id__voptional	Identify attachments by their external id. You must also add the idParam=external_id__v query parameter.
description__vrequired	Description of the attachment. 1000 characters maximum.

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.

Delete Object Record Attachment

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id}	The object record id field value.
{attachment_id}	The attachment id field value.

Delete Multiple Object Record Attachments

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
{
"id": "V15000000000305",
"attachment_id": "141"
}
]'
https://myvault.veevavault.com/api/v19.3/vobjects/veterinary_patient__c/attachments/batch

Response

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

Delete object record attachments in bulk with a JSON or CSV input file. You can only delete the latest version of an attachment.

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

DELETE /api/{version}/vobjects/{object_name}/attachments/batch

Headers

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

Body Parameters

Prepare a CSV or JSON input file.

Name	Description
idconditional	The id of the object record to which to add the attachment. Not required if providing a unique field identifier (idParam) such as external_id__v.
external_id__vconditional	Identify attachments by their external id. You must also add the idParam=external_id__v query parameter.
attachment_idrequired	The id of the attachment being updated.

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.

Delete Object Record Attachment Version

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value (product__v, country__v, custom_object__c, etc.).
{object_record_id}	The object record id field value.
{attachment_id}	The attachment id field value.
{attachment_version}	The attachment version__v field value.

Object Page Layouts

Object page layouts are defined at the object or object-type level and control the information displayed to a user on the object record detail page. Objects that include multiple object types can define a different layout for each type. Learn more about configuring object page layouts in Vault Help.

The page layout APIs consider the authenticated user’s permissions, so fields which are hidden from the authenticated user will not be included in the API response. For example, field-level security, object controls, and other object-level permissions are considered. Record-level permissions such as atomic security are not considered. Layout rules are not applied, but instead have their configurations returned as metadata. Both active and inactive fields are included in the response.

Retrieve Page Layouts

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "name": "product_detail_page_layout__c",
           "label": "Product Detail Page Layout",
           "object_type": "base__v",
           "url": "/api/v24.1/metadata/vobjects/product__v/page_layouts/product_detail_page_layout__c",
           "active": true,
           "description": "General layout for any product",
           "default_layout": true,
           "display_lifecycle_stages": false
       },
       {
           "name": "otc_product_layout__c",
           "label": "OTC Product Layout",
           "object_type": "base__v",
           "url": "/api/v24.1/metadata/vobjects/product__v/page_layouts/otc_product_layout__c",
           "active": true,
           "description": "New layout for OTC products",
           "default_layout": false,
           "display_lifecycle_stages": false
       },
       {
           "name": "generic_product_layout__c",
           "label": "Generic Product Layout",
           "object_type": "base__v",
           "url": "/api/v24.1/metadata/vobjects/product__v/page_layouts/generic_product_layout__c",
           "active": true,
           "description": "Layout for generics",
           "default_layout": false,
           "display_lifecycle_stages": false
       }
   ]
}

Given an object, retrieve all page layouts associated with that object. You can use this data to retrieve specific page layout metadata.

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The name of the object from which to retrieve page layouts.

Response Details

On SUCCESS, the response lists all layouts associated with the specified object. Each layout includes:

Name	Description
name	The name of the layout.
label	The label of the layout as it appears in the Vault UI.
object_type	The object type where the layout is available.
active	The active or inactive status of the layout.
description	A description of the layout.
default_layout	If true, this layout is assigned to all users unless another layout is specified in their assigned Layout Profile.
display_lifecycle_stages	For objects with lifecycle stages configured, if true, Vault displays the Lifecycle Stages Chevron panel on all views for the object.

Retrieve Page Layout Metadata

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.1/metadata/vobjects/my_object__c/page_layouts/my_object_detail_page_layout__c

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "my_object_detail_page_layout__c",
        "label": "My Object Detail Page Layout",
        "object": "my_object__c",
        "object_type": "base__v",
        "active": true,
        "description": "",
        "default_layout": true,
        "display_lifecycle_stages": false,
        "created_date": "2023-12-04T21:11:32.000Z",
        "last_modified_date": "2023-12-04T23:44:56.000Z",
        "layout_rules": [
            {
                "evaluation_order": 100,
                "status": "active__v",
                "fields_to_hide": [],
                "sections_to_hide": [
                    "my_related_objects__c"
                ],
                "controls_to_hide": [],
                "hide_layout": false,
                "hidden_pages": [],
                "displayed_as_readonly_fields": [
                    "link__sys"
                ],
                "displayed_as_required_fields": [
                    "my_related_object__c"
                ],
                "focus_on_layout": true,
                "expression": "IsBlank(my_related_object__c)"
            }
        ],
        "sections": [
            {
                "name": "details__c",
                "title": "Details",
                "type": "detail",
                "help_content": null,
                "show_in_lifecycle_states": [],
                "properties": {
                    "layout_type": "One-Column",
                    "items": [
                        {
                            "type": "field",
                            "reference": "name__v",
                            "status": "active__v"
                        },
                        {
                            "type": "field",
                            "reference": "status__v",
                            "status": "active__v"
                        },
                        {
                            "type": "field",
                            "reference": "created_date__v",
                            "status": "active__v"
                        }
                    ]
                }
            },
            {
                "name": "my_related_objects__c",
                "title": "My Related Objects",
                "type": "related_object",
                "help_content": null,
                "show_in_lifecycle_states": [],
                "properties": {
                    "relationship": "my_related_objects__cr",
                    "related_object": "my_related_object__c",
                    "prevent_record_create": false,
                    "modal_create_record": false,
                    "criteria_vql": null,
                    "columns": [
                        {
                            "reference": "name__v",
                            "width": "200",
                            "status": "active__v"
                        },
                        {
                            "reference": "my_object__c",
                            "width": "200",
                            "status": "active__v"
                        }
                    ]
                }
            }
        ]
    }
}

Given a page layout name, retrieve the metadata for that specific page layout.

The page layout APIs consider the authenticated user’s permissions, so fields that are hidden from the authenticated user will not be included in the API response. For example, field-level security, object controls, and other object-level permissions are considered. Record-level permissions such as atomic security are not considered. Both active and inactive fields are included in the response.

This endpoint returns metadata without layout rules applied, instead returning layout rule configurations as metadata. If a layout rule references a token, this endpoint returns the unresolved token instead of resolving it in the response.

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The name of the object from which to retrieve page layout metadata.
{layout_name}	The name of the page layout from which to retrieve metadata.

Response Details

On SUCCESS, returns metadata for the specified page layout, including the object_type, layout_rules, and sections.

Attachment Fields

Attachment fields allow you to attach a file to a field on an object record. The value of an Attachment field is the file handle for the file. Learn more about Attachment fields in Vault Help.

You must download an Attachment field file in order to view or edit its content. You can use the following endpoints to download or update Attachment field files.

Download Attachment Field File

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.3/vobjects/product__v/00P000000000202/attachment_fields/file__c/file

Response Headers

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

Download the specified Attachment field file from an object record.

GET /api/{version}/vobjects/{object_name}/{object_record_id}/attachment_fields/{attachment_field_name}/file

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value. For example, product__v.
{object_record_id}	The object record id field value.
{attachment_field_name}	The name of the Attachment field from which to retrieve the file.

Response Details

On SUCCESS, Vault retrieves the file from the specified Attachment field from the object record. The file name is the same as the Attachment field file name.

The HTTP Response Header Content-Type is set to the MIME type of the file. For example, if the file 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 component which can be used when naming the local file. When downloading files with very small file size, the HTTP Response Header Content-Length is set to the size of the file. For most Attachment fields (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Download All Attachment Field Files

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.3/vobjects/product__v/00P000000000202/attachment_fields/file

Response Headers

Content-Type: application/zip;charset=UTF-8
Content-Disposition: attachment;filename="Product - Cholecap - attachment fields.zip"

Download all Attachment field files from the specified object record.

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value. For example, product__v.
{object_record_id}	The object record id field value.

Response Details

On SUCCESS, Vault retrieves the file from the specified Attachment field from the object record. The files are packaged in a ZIP file with the file name: {object label} {object record name} - attachment fields.zip. When extracted, it will include a subfolder for each Attachment field included in the response.

The HTTP Response Header Content-Type is set to application/zip;charset=UTF-8. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. When downloading files with very small file size, the HTTP Response Header Content-Length is set to the size of the file. For most Attachment field downloads (larger file sizes), the Transfer-Encoding method is set to chunked and the Content-Length is not displayed.

Update Attachment Field File

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.3/vobjects/product__v/00P000000000202/attachment_fields/file__c/file \
--form 'file=@"Cholecap Prescribing Information.doc"'

Response Headers

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "data": {
                "id": "00P000000000202",
                "url": "/api/v24.3/vobjects/product__v/00P000000000202"
            }
        }
    ]
}

Update an Attachment field by uploading a file. If you need to update more than one Attachment field, it is best practice to update in bulk with Update Object Records.

POST /api/{version}/vobjects/{object_name}/{object_record_id}/attachment_fields/{attachment_field_name}/file

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value. For example, product__v.
{object_record_id}	The object record id field value.

Deep Copy Object Record

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
https://myvault.veevavault.com/api/v16.0/vobjects/product__v/00P000000000202/actions/deepcopy

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 26001,
  "url": "/api/v16.0/services/jobs/26001"
}

Example: Deep Copy with Override

[{"name__v":"Copied record 1","external_id__v":""}]

Deep Copy copies an object record, including all of the record’s related child and grandchild records. Each deep (hierarchical) copy can copy a maximum of 10,000 related records at a time.

See Copying Object Records for details on required access permissions.

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The name of the parent object to copy. For example, product__v.
{object_record_ID}	The ID of the specific object record to copy.

Body

In the request body, you can include field names to override field values in the source record. For example, including external_id__v removes the field value in the copy while leaving the source record unchanged.

If the input is formatted as CSV, only a single data line is accepted. If the input is formatted as JSON, only one in the list is accepted.

Retrieve Results of Deep Copy Job

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Accept: text/csv" \
https://myvault.veevavault.com/api/v16.0/vobjects/deepcopy/results/product__v/failure/26901

Response

line number,vobject,sourceRecordId,errors
1,product__v,00P000000000301,"""PARAMETER_REQUIRED|Missing required parameter [internal_name__c]"",""OPERATION_NOT_ALLOWED|Another resource already exists with [name__v=WonderDrug]"""

After submitting a request to deep copy an object record, you can query Vault to determine the results of the request. Before submitting this request:

• You must have previously requested a deep copy job (via the API) which is no longer active.
• You must have a valid job_id value, retrieved from the response of the deep copy request.

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

Headers

Name	Description
Accept	text/csv (default)

URI Path Parameters

Name	Description
object_name	The name of the deep copied object.
job_id	The ID of the job, retrieved from the response of the job request.
job_status	Possible values are success or failure. Find if your job succeeded or failed by retrieving the job status.

Retrieve Deleted Object Record ID

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v22.2/objects/deletions/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "OK",
    "responseDetails": {
        "total": 3,
        "size": 3,
        "limit": 1000,
        "offset": 0
    },
    "data": [
        {
            "id": "V29000000002001",
            "date_deleted": "2022-06-22T15:24:27Z"
        },
        {
            "id": "V29000000003001",
            "date_deleted": "2022-06-23T21:16:25Z"
        },
        {
            "id": "V29000000003002",
            "date_deleted": "2022-06-23T21:16:30Z"
        }
    ]
}

Retrieve the IDs of object records that have been deleted from your Vault within the past 30 days. After object records are deleted from a Vault, their IDs are still available for retrieval for 30 days. After that, they cannot be retrieved. You can use the optional request parameters below to narrow the results to a specific date and time range within the past 30 days.

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

Headers

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

URI Path Parameters

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

Query Parameters

Name	Description
start_date	Specify a date (no more than 30 days past) after which Vault will look for deleted object records. 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 object records. Dates must be YYYY-MM-DDTHH:MM:SSZ format, for example, 7AM on January 15, 2016 would use 2016-01-15T07:00:00Z
limit	Paginate the results by specifying the maximum number of records per page in the response. This can be any value between 0 and 5000. If omitted, defaults to 1000.
offset	Paginate the results displayed per page by specifying the amount of offset from the entry returned. For example, if you are viewing the first 50 results (page 1) and want to see the next page, set this to offset=50. If omitted, defaults to 0.

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

Retrieve Limits on Objects

Request

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

Response

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

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

GET /api/{version}/limits

Headers

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

Response Details

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

Update Corporate Currency Fields

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-d "id=00P000000000301" \
https://myvault.veevavault.com/api/v18.3/vobjects/product__v/actions/updatecorporatecurrency

Response

{
    "responseStatus": "SUCCESS",
    "job_id": 81603,
    "url": "/api/v18.3/services/jobs/81603"
}

Currency is a field type available on all Vault objects. Whenever a user populates a local currency field value, Vault automatically populates the related corporate currency field value, except in the following scenarios:

• Admins change the Corporate Currency setting for the vault
• Admins update the Rate setting for the local currency used by a record

This endpoint updates the field_corp__sys field values of an object record based on the Rate of the currency, denoted by the local_currency__sys field of the specified record. Learn more about Currency Fields in Vault Help.

PUT /api/{version}/vobjects/{object_name}/actions/updatecorporatecurrency

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value, for example, product__v.

Body Parameters

Name	Description
idoptional	The object record id field value. If you don’t provide an id, Vault updates corporate fields of all records for the object.

Document Roles

Documents and binders can have different roles available to them depending on their type and lifecycles. There are a set of standard roles that ship with Vault: owner__v, viewer__v, and editor__v. In addition, Admins can create custom roles defined per lifecycle. Learn more about Roles in Vault Help.

Through the Role APIs, you can:

• Retrieve available roles on documents and binders
• Determine who can be assigned to roles
• Retrieve default users who are assigned automatically within the Vault UI
• Retrieve who is currently assigned to a role
• Add additional users and groups to a role
• Remove users and groups from roles

Note that all user and group information is returned as IDs and you need to use the Retrieve User or Retrieve Group API to determine the name, etc.

For roles on object records, see Object Roles.

Retrieve Roles

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Document roles retrieved",
    "errorCodes": null,
    "documentRoles": [
        {
            "name": "reviewer__v",
            "label": "Reviewer",
            "assignedUsers": [
                25496,
                26231
            ],
            "assignedGroups": [
                1,
                2
            ],
            "availableUsers": [
                25496,
                26231,
                28874
            ],
            "availableGroups": [
                1,
                2,
                3
            ],
            "defaultUsers": [
                25496,
                26231
            ],
            "defaultGroups": [
                1,
                2
            ]
        }
      ]
}

Retrieve all available roles on a document or binder and the users and groups assigned to them.

GET /api/{version}/objects/{documents_or_binders}/{id}/roles{/role_name}

Headers

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

URI Path Parameters

Name	Description
{documents_or_binders}	Choose to retrieve values for documents or binders.
{id}	The id of the document, binder, or object record.
{/role_name}	Optional: Include a role name to filter for a specific role. For example, owner__v.

Response Details

In the response, document ID 245 is configured with roles. Two users (25496 & 26231) and two groups (1 & 2) are assigned to the reviewer__v role by default.

Assign Users & Groups to Roles on a Single Document

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "consumer__v.users=35565,35571" \
-d "approver__v.users-45585,45594" \
https://myvault.veevavault.com/api/v15.0/objects/documents/245/roles

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Document roles updated",
  "updatedRoles": {
    "consumer__v": {
      "users": [
        19376,18234,19456
      ]
    },
    "legal__c": {
      "groups": [
        19365,18923
      ]
    }
  }
}

Assign users and groups to roles on a single document or binder.

POST /api/{version}/objects/documents/{id}/roles

Headers

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

URI Path Parameters

Name	Description
{id}	The document or binder id field value.

Body Parameters

Include name-value pairs of all users or groups with their corresponding roles in the form {Role_name}.{USERS or GROUPS}=ID1,ID2,ID3. For example, reviewer__v.users = "3003, 4005".

Response Details

The response includes ROLE:ID pairs for the users and groups successfully assigned to roles on the document or binder.

Assign Users & Groups to Roles on Multiple Documents

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.groups": [
                3311303,
                4411606
            ],
            "reviewer__v.users": [
                12021,
                12022,
                12023,
                12124
            ]
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.groups": [
                3311303,
                4411606
            ],
            "reviewer__v.users": [
                12021,
                12022,
                12023,
                12124
            ]
        },
        {
           "responseStatus":"FAILURE",
           "id":"773",
           "errors":[
              {
                 "type":"INVALID_DATA",
                 "message":"Error message describing why the users and groups were not assigned to roles on this document.."
              }
           ]
        }
    ]
}

Assign users and groups to roles on a document or binder in bulk.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 1000.

Assigning users and groups to document roles is additive. For example, if groups 1, 2, and 3 are currently assigned to a particular role and you assign groups 3, 4, and 5 to the same role, the final list of groups assigned to the role will be 1, 2, 3, 4, and 5. Users and groups (IDs) in the input that are either invalid (not recognized) or cannot be assigned to a role due to permissions are ignored and not processed.

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

Headers

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

Body Parameters

You can add parameters in the request body, or upload them as a CSV file.

Name	Description
idrequired	The document ID.
role__v.usersoptional	A string of user id values for the new role.
role__v.groupsoptional	A string of user id values for the new group.

For example,

id	reviewer__v.users	reviewer__v.groups	approver__v.users	approver__v.groups
771	“12021,12022”	“3311303,3311404”	22124	4411606

Response Details

The response includes role:id pairs for the users and groups successfully assigned to roles.

Remove Users & Groups from Roles on a Single Document

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v23.2/objects/documents/1234/roles/consumer__v.user/1008313

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "User/group deleted from document role",
  "updatedRoles": {
    "consumer__v": {
      "users": [
        1008313
      ]
    }
  }
}

Remove users and groups from roles on a single document or binder.

DELETE /api/{version}/objects/documents/{doc_id}/roles/{role_name_and_user_or_group}/{id}

Headers

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

URI Path Parameters

Name	Description
{doc_id}	The id value of the document or binder from which to remove roles.
{role_name_and_user_or_group}	The name of the role from which to remove the user or group followed by either user or group. The format is {role_name}.{user_or_group}. For example, consumer__v.user.
{id}	The id value of the user or group to remove from the role.

Response Details

On SUCCESS, the response lists the id of the user or group removed from the document role. On FAILURE, the response returns an error message describing the reason for the failure. For example, a user or group may not be removed if the role assignment is system-managed.

Remove Users and Groups from Roles on Multiple Documents

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: application/json" \
--data-binary @"C:\Vault\Document Roles\remove_document_roles.csv" \
https://myvault.veevavault.com/api/v23.2/objects/documents/roles/batch

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 5,
            "coordinator__v.users": [
                1008313
            ],
            "consumer__v.users": [
                1006595
            ]
        }
    ]
}

Remove users and groups from roles on a document or binder in bulk.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 1000.

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

Headers

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

Body Parameters

You can add parameters in the request body, or upload them as a CSV file.

Name	Description
idrequired	The document ID.
role__v.usersoptional	A string of user id values to remove.
role__v.groupsoptional	A string of group id values to remove.

For example,

id	reviewer__v.users	reviewer__v.groups	approver__v.users	approver__v.groups
771	“12021,12022”	“3311303,3311404”	22124	4411606

Response Details

On SUCCESS, the response lists the IDs of the users or groups removed from the provided document roles. On FAILURE, the response returns an error message describing the reason for the failure. For example, a user or group may not be removed if the role assignment is system-managed.

Workflows

A workflow is a series of steps configured in Vault to align with specific business processes. The different types of steps offer a flexible way to organize a wide variety of processes for an object record, including assigning tasks to users, sending notifications, updating fields, and changing a record’s lifecycle state or sharing settings. Workflow tasks can allow users to enter comments, choose verdicts (approve, deny, etc.), populate fields, or provide eSignatures.

Object workflows are specific to a single lifecycle, meaning that one (1) workflow cannot apply to multiple object lifecycles. A single object record can only be in one (1) workflow at a time. Learn more about Object Workflows in Vault Help.

Retrieve Workflows

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/objectworkflows?object__v=product__v&record_id__v=00P07551

Response

{
  "responseStatus": "SUCCESS",
  "responseDetails": {
    "total": 2,
    "offset": 0,
    "page_size": 200,
    "object": {
      "name": "objectworkflows",
      "label": "Object Workflow",
      "url": "/api/v14.0/objects/objectworkflows?object__v=product__v&record_id__v=00P07551",
      "label_plural": "Object Workflows"
    }
  },
  "data": [
    {
      "id": 4602,
      "label__v": "Product Workflow",
      "status__v": [
        "active__v"
      ],
      "object__v": "product__v",
      "record_id__v": "00P07551",
      "initiator__v": 52212,
      "started_date__v": "2023-04-03T16:09:28.000Z"
    },
    {
      "id": 3901,
      "label__v": "Product Workflow",
      "status__v": [
        "cancelled__v"
      ],
      "object__v": "product__v",
      "record_id__v": "00P07551",
      "initiator__v": 46916,
      "started_date__v": "2022-05-17T17:22:18.000Z",
      "cancelled_date__v": "2022-05-17T17:24:08.000Z"
    }
  ]
}

Retrieve all current, cancelled, and completed workflow instances for a specific object record or all workflows available to a particular workflow participant.

GET /api/{version}/objects/objectworkflows

Headers

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

Query Parameters

Name	Description
object__v, record_id__v	To retrieve all workflows configured on an object, include the Vault object name__v and object record id field values as object__v={name__v}&record_id__v={id}. These two parameters are required when the participant parameter is not used.
participant	To retrieve all workflows available to a particular user, include the user id field value as participant={id}. To retrieve your own workflows, set this value to participant=me(). This parameter is required when the object__v and record_id__v parameters are not used.
status__v	To retrieve all workflows with specific statuses, include one or more status name__v field values. For example: status__v=active__v, status__v=active__v,completed__v. Workflows with status__v=active__v are in progress for the indicated object record. Valid statuses include: active__v completed__v cancelled__v
offset	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.
page_size	This parameter is used to paginate the results. It specifies the size number of records to display per page. Vault returns 200 records per page by default. You can set this value lower or as high as 1000 records per page. For example: page_size=1000.
loc	When localized (translated) strings are available, retrieve them by including loc=true.

Response Details

On SUCCESS, the response lists all workflows matching the query parameters. Each workflow may include the following fields:

• id - The workflow ID.
• label__v - The workflow label as seen in the UI.
• status__v - The current status of the workflow.
• object__v - The name of the object using the workflow.
• record_id__v - The ID of the object record using the workflow.
• initiator__v - The ID of the user who started the workflow. This is the workflow owner.
• started_date__v - The date and time when the workflow was started.
• completed_date__v - The date and time when the workflow was completed.
• cancelled_date__v - The date and time when the workflow was cancelled.

Retrieve Workflow Details

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseDetails": {
    "url": "/api/v14.0/objects/objectworkflows/801",
    "object": {
      "name": "objectworkflows",
      "label": "Object Workflow",
      "url": "/api/v14.0/metadata/objectworkflows",
      "label_plural": "Object Workflows"
    }
  },
  "data": [
    {
      "id": 801,
      "label__v": "Approve",
      "status__v": [
        "active__v"
      ],
      "object__v": "product__v",
      "record_id__v": "00P07551",
      "initiator__v": 46916,
      "started_date__v": "2016-05-12T19:22:15.000Z"
    }
  ]
}

Retrieve the details for a specific workflow.

GET /api/{version}/objects/objectworkflows/{workflow_id}

Headers

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

URI Path Parameters

Name	Description
{workflow_id}	The workflow idfield value.

Query Parameters

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

Response Details

On SUCCESS, the response lists the workflow details. The workflow may include the following fields:

• id - The workflow ID.
• label__v - The workflow label as seen in the UI.
• status__v - The current status of the workflow.
• object__v - The name of the object using the workflow.
• record_id__v - The ID of the object record using the workflow.
• initiator__v - The ID of the user who started the workflow. This is the workflow owner.
• started_date__v - The date and time when the workflow was started.
• completed_date__v - The date and time when the workflow was completed.
• cancelled_date__v - The date and time when the workflow was cancelled.

Retrieve Workflow Actions

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "name": "cancel",
           "label": "Cancel"
       },
       {
           "name": "replaceworkflowowner",
           "label": "Replace Workflow Owner"
       },
       {
           "name": "addparticipants",
           "label": "Add Participants"
       }
   ]
}

Retrieve all available workflow actions that can be initiated on a specific workflow.

GET /api/{version}/objects/objectworkflows/{workflow_id}/actions

Headers

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

URI Path Parameters

Name	Description
{workflow_id}	The workflow id field value.

Query Parameters

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

Response Details

On SUCCESS, the response lists all available workflow actions. Each action includes the following fields:

• name - The workflow action name used to initiate the workflow in the request below.
• label - The workflow action label as seen in the UI.

Retrieve Workflow Action Details

Request

$ curl -X GET "Authorization: {SESSION_ID}" \
  https://myvault.veevavault.com/api/v19.3/objects/objectworkflows/1801/actions/removecontent

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "name": "removecontent",
       "label": "Remove Content",
       "controls": [
           {
               "label": "Documents",
               "type": "documents",
               "prompts": [
                   {
                       "name": "documents__sys",
                       "label": "Documents",
                       "required": true
                   }
               ],
               "current_values": [
                   {
                       "document_id__v": "67"
                   },
                   {
                       "document_id__v": "41"
                   }
               ]
           }
       ]
   }
}

Retrieve details about a workflow action. For example, the prompts needed to complete a workflow action.

GET /api/{version}/objects/objectworkflows/{workflow_id}/actions/{workflow_action}

Headers

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

URI Path Parameters

Name	Description
{workflow_id}	The workflow id field value.
{workflow_action}	The name of the workflow action. To get this value, you can Retrieve Workflow Actions.

Response Details

On SUCCESS, the response lists all prompts required to complete the workflow action. If the workflow action does not require any prompts, the response will only list SUCCESS. In the example response, the removecontent workflow action requires a value for contents__sys.

Initiate Workflow Action

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
https://myvault.veevavault.com/api/v14.0/objects/objectworkflows/801/actions/cancel

Response

{
    "responseStatus": "SUCCESS"
}

Initiate a workflow action on a specific workflow.

POST /api/{version}/objects/objectworkflows/{workflow_id}/actions/{workflow_action}

Headers

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

URI Path Parameters

Name	Description
{workflow_id}	The workflow id field value.
{workflow_action}	The workflow action name retrieved from Retrieve Workflow Actions.

Body Parameters

In the body of the request, add any fields required to initiate the action. These will differ depending on your specified {workflow_action}. For more information about fields required for an action, Retrieve Workflow Action Details. The following tables show common workflow actions in Vault, but there may be other actions which are not listed here.

Replace Workflow Owner: replaceworkflowowner

Name	Description
new_workflow_ownerrequired	The id of the user who will become the new workflow owner, in the format user:{id}. For example, user:6014.

Email Workflow Participants: emailparticipants

Name	Description
email_recipientsrequired	A comma-delimited list of email recipients or groups, in the format user:{user_id} and group:{group_label}. For example, user:1082,user:4802,group:incompleteTaskOwners,user:3582. To find available {group_label}s, Retrieve Workflow Action Details for emailparticipants. If a user is not a potential recipient based on their task status, the user will not receive an email.
email_messagerequired	The body of the email message to send to users. Maximum 5,000 characters.
send_copy_to_selfoptional	Set to true to send a copy of the email to the authenticated user. If omitted, defaults to false.

Add Participants: addparticipants

Name	Description
participantsrequired	The id of the user to add as a participant, in the format user:{id}. For example, user:1006.

Remove Documents from Envelope: removecontent

Name	Description
contents__sysrequired	The id of the document to remove from the workflow. To remove multiple documents, use a comma-separated list of ids.

Update Workflow Due Date: updateworkflowduedate

This action changes the current workflow due date to a new date. Only available on workflows already configured with a workflow due date.

Name	Description
workflow_due_daterequired	The new due date for the workflow, in the format YYYY-MM-DD.

Response Details

If the {workflow_action} executes successfully, the response returns SUCCESS. For example, the cancel workflow action. On FAILURE, the response returns an error type and message describing the reason for the failure. For example, the API returns INVALID_DATA if a user or group cannot be added as a workflow participant because they are not in the appropriate role.

Workflow Tasks

Retrieve Workflow Tasks

Request

curl -L -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.2/objects/objectworkflows/tasks?assignee__v=674737

Response

{
   "responseStatus": "SUCCESS",
   "responseDetails": {
       "total": 2,
       "offset": 0,
       "page_size": 200,
       "object": {
           "name": "objectworkflow_tasks",
           "label": "Object Workflow Task",
           "url": "/api/v21.2/objects/objectworkflows/tasks?assignee__v=674737",
           "label_plural": "Object Workflow Tasks"
       }
   },
   "data": [
       {
           "id": 123101,
           "label__v": "Review",
           "status__v": [
               "available__v"
           ],
           "object__v": "envelope__sys",
           "record_id__v": "0ER00000003G001",
           "instructions__v": "Review and either Approve or Reject each document",
           "created_date__v": "2021-05-31T21:31:29.000Z",
           "workflow__v": "23001"
       },
       {
           "id": 123001,
           "label__v": "R&U WF Task New",
           "status__v": [
               "assigned__v"
           ],
           "object__v": "envelope__sys",
           "record_id__v": "0ER00000003F001",
           "instructions__v": "Complete this new task",
           "assignee__v": "674737",
           "created_date__v": "2021-05-31T18:33:34.000Z",
           "assigned_date__v": "2021-05-31T18:33:34.000Z",
           "workflow__v": "22901",
           "workflow_class__sys": "read_and_understood__sys"
       }
   ]
}

Retrieve all available tasks across all workflows.

GET /api/{version}/objects/objectworkflows/tasks

Headers

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

Query Parameters

Name	Description
object__v, record_id__v	To retrieve all workflow tasks configured on an object, include the Vault object name__v and object record id field values as object__v={name__v}&record_id__v={id}. These two parameters are required when the assignee__v parameter is not used.
assignee__v	To retrieve all workflow tasks available to a particular user, include the user id field value as assignee__v={id}. To retrieve your own workflow tasks, set this value to assignee__v=me(). This parameter is required when the object__v and record_id__v parameters are not used.
status__v	To retrieve all workflow tasks with specific statuses, include one or more status name__v field values. For example: status__v=available__v or status__v=available__v,completed__v.
offset	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.
page_size	This parameter is used to paginate the results. It specifies the size number of records to display per page. Vault returns 200 records per page by default. You can set this value lower or as high as 1000 records per page. For example: page_size=1000.
loc	When localized (translated) strings are available, retrieve them by including loc=true.

Response Details

On SUCCESS, the response lists all workflow tasks matching the query parameters. Each task may include the following fields:

• id - The task ID.
• label__v - The task label as seen in the UI.
• status__v - The current status of the task.
• object__v - The name of the object using the task.
• record_id__v - The ID of the object record using the task.
• instructions__v - Instructions for completing the task.
• assignee__v - The ID of the user assigned the task. This is the task owner.
• created_date__v - The date and time when the task was created.
• assigned_date__v - The date and time when the task was assigned.
• due_date__v - The date and time when the task is due.
• workflow__v - The workflow ID in which the task is configured.
• workflow_class__sys - Included with a value of read_and_understood__sys if the task is a Read & Understood task.

Retrieve Workflow Task Details

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.2/objects/objectworkflows/tasks/123001

Response

{
   "responseStatus": "SUCCESS",
   "responseDetails": {
       "url": "/api/v21.2/objects/objectworkflows/tasks/123001",
       "object": {
           "name": "objectworkflow_tasks",
           "label": "Object Workflow Task",
           "url": "/api/v21.2/metadata/objectworkflows/tasks",
           "label_plural": "Object Workflow Tasks"
       }
   },
   "data": [
       {
           "id": 123001,
           "label__v": "R&U WF Task New",
           "status__v": [
               "assigned__v"
           ],
           "object__v": "envelope__sys",
           "record_id__v": "0ER00000003F001",
           "instructions__v": "Complete this new task",
           "assignee__v": "674737",
           "created_date__v": "2021-05-31T18:33:34.000Z",
           "assigned_date__v": "2021-05-31T18:33:34.000Z",
           "workflow__v": "22901",
           "workflow_class__sys": "read_and_understood__sys"
       }
   ]
}

Retrieve the details of a specific workflow task.

GET /api/{version}/objects/objectworkflows/tasks/{task_id}

Headers

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

URI Path Parameters

Name	Description
{task_id}	The task id field value.

Query Parameters

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

Response Details

On SUCCESS, the response lists all workflow tasks matching the query parameters. The task may include the following fields:

• id - The task ID.
• label__v - The task label as seen in the UI.
• status__v - The current status of the task.
• object__v - The name of the object using the task.
• record_id__v - The ID of the object record using the task.
• instructions__v - Instructions for completing the task.
• assignee__v - The ID of the user assigned the task. This is the task owner.
• created_date__v - The date and time when the task was created.
• assigned_date__v - The date and time when the task was assigned.
• due_date__v - The date and time when the task is due.
• workflow__v - The workflow ID in which the task is configured.
• workflow_class__sys - Included with a value of read_and_understood__sys if the task is a Read & Understood task.

Retrieve Workflow Task Actions

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/objectworkflows/tasks/7201/actions

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
       "name": "complete",
       "label": "Complete"
    },
    {
       "name": "cancel",
       "label": "Cancel"
    }
  ]
}

Retrieve all available actions that can be initiated on a given workflow task.

GET /api/{version}/objects/objectworkflows/tasks/{task_id}/actions

Headers

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

URI Path Parameters

Name	Description
{task_id}	The task id field value.

Retrieve Workflow Task Action Details

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.2/objects/objectworkflows/tasks/5702/actions/complete

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "name": "workflow_task__c",
       "label": "Complete Review",
       "type": "task",
       "description": "Initiate the Content Module Approval flow.",
       "controls": [
           {
               "label": "Instruction",
               "type": "instructions",
               "instructions": "Please complete a review of the content within this content module and review the Content Module Asset record status as well."
           },
           {
               "label": "Verdict",
               "type": "verdict",
               "verdict": "verdict_public_key__c",
               "reason": "reason__c",
               "capacity": "capacity__c",
               "verdicts": [
                   {
                       "name": "verdict_approve_module__c",
                       "label": "Approve Module",
                       "esignature": true,
                       "prompts": [],
                       "comment": {
                           "name": "verdict_approve_module_comment__c",
                           "label": "Optional Approval Comments",
                           "type": "comment",
                           "required": false
                       },
                       "reasons": {
                           "label": "Approved",
                           "required": true,
                           "prompts": [
                               {
                                   "name": "reason_0_0__c",
                                   "label": "Passes Inspection"
                               }
                           ]
                       },
                       "capacities": {
                           "label": "Approver",
                           "required": false,
                           "prompts": [
                               {
                                   "name": "capacity_0_0__c",
                                   "label": "General Approver"
                               }
                           ]
                       }
                   },
                   {
                       "name": "verdict_return_to_draft__c",
                       "label": "Return to Draft",
                       "esignature": false,
                       "prompts": [],
                       "comment": {
                           "name": "verdict_return_to_draft_comment__c",
                           "label": "Updates Required",
                           "type": "comment",
                           "required": true
                       },
                       "reasons": {
                           "label": "Fails Inspection",
                           "required": false,
                           "prompts": [
                               {
                                   "name": "reason_1_0__c",
                                   "label": "Poor Quality"
                               },
                               {
                                   "name": "reason_1_1__c",
                                   "label": "Incorrect Data"
                               },
                               {
                                   "name": "reason_1_2__c",
                                   "label": "Other"
                               }
                           ]
                       },
                       "capacities": {
                           "label": "Rejector",
                           "required": false,
                           "prompts": [
                               {
                                   "name": "capacity_1_0__c",
                                   "label": "General Rejector"
                               }
                           ]
                       }
                   }
               ]
           }
       ]
   }
}

Retrieve the details of a specific workflow task action. The response lists the details of the task action, including all fields required to initiate the action. Note that task actions where esignature is true cannot be initiated via the API.

GET /api/{version}/objects/objectworkflows/tasks/{task_id}/actions/{task_action}

Headers

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

URI Path Parameters

Name	Description
{task_id}	The task id field value.
{task_action}	The name of the task action retrieved from Retrieve Workflow Task Actions.

Query Parameters

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

Initiate Workflow Task Action

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
--data-urlencode "verdict_public_key__c=verdict_impact_assessment_complete__c" \
--data-urlencode "capacity__c=capacity_0_0__c" \
--data-urlencode "reason__c=reason_0_0__c" \
https://myvault.veevavault.com/api/v21.1/objects/objectworkflows/tasks/502/actions/complete

Response

{
    "responseStatus": "SUCCESS"
}

Initiate a workflow task action. Note that the API does not support initiating task actions requiring eSignatures (where esignature is true).

POST /api/{version}/objects/objectworkflows/tasks/{task_id}/actions/{task_action}

Headers

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

URI Path Parameters

Name	Description
{task_id}	The task id field value.
{task_action}	The name of the task action retrieved from Retrieve Workflow Task Actions.

Body Parameters

Required parameters depend on the action being initiated. Controls marked as required in the Retrieve Workflow Task Action Details response must be provided. If a control (such as verdict) defines a set of required fields, those must also be provided.

For example, the following request parameters may apply to the complete action:

Name	Description
verdict	The verdict name returned in Retrieve Workflow Task Action Details.
reason	The reason name returned in Retrieve Workflow Task Action Details.
capacity	The capacity name returned in Retrieve Workflow Task Action Details.

The cancel action doesn’t require any parameters.

For workflows where type is set to multidocworkflow and cardinality is set to One, Vault pre-populates document field values in field prompts. If you include keys for field prompts without values, Vault submits a blank field value on the document.

Bulk Active Workflow Actions

The API allows you to retrieve actions and action details and to execute actions for up to 500 workflows at once. These can be object, document, or legacy workflows.

Retrieve Bulk Workflow Actions

Retrieve all available workflow actions that can be initiated on a workflow which:

• The authenticated user has permissions to view or initiate
• Can be initiated through the API

Request

$ curl -L -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.1/object/workflow/actions

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "name": "canceltasks",
           "label": "Cancel Tasks"
       },
       {
           "name": "cancelworkflows",
           "label": "Cancel Workflows"
       },
       {
           "name": "reassigntasks",
           "label": "Reassign Tasks"
       },
       {
           "name": "replaceworkflowowner",
           "label": "Replace Workflow Owner"
       }
   ]
}

GET /api/{version}/object/workflow/actions

Headers

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

Response Details

On SUCCESS, the response lists all available workflow actions for a Vault.

Name	Description
name	The workflow action name.
label	The workflow action label as seen in the UI.

Retrieve Bulk Workflow Action Details

Once you’ve retrieved the available workflow actions, use this request to retrieve the details for a specific workflow action.

Request

$ curl -L -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v20.2/object/workflow/actions/cancelworkflows

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "name": "cancelworkflows",
       "controls": [
           {
               "prompts": [
                   {
                       "multi_value": true,
                       "label": "Workflow Ids",
                       "required": true,
                       "name": "workflow_ids"
                   }
               ],
               "type": "field",
               "label": "Fields"
           }
       ]
   }
}

GET /api/{version}/object/workflow/actions/{action}

Headers

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

URI Path Parameters

Name	Description
action	The name of the workflow action. To get this value, Retrieve Bulk Workflow Actions.

Response Details

On SUCCESS, the response returns metadata for the specified workflow action, including the fields required to execute the action.

For each control, the following data may be returned:

Name	Description
label	UI label for the control.
type	Type of control.
prompts	The input prompts which accept values when initiating a workflow action.

For each prompt, the following data may be returned:

Name	Description
multi_value	If true, indicates that the field accepts multiple values.
label	UI label for the prompt.
required	If true, indicates that the field is required to initiate the workflow action.

Initiate Workflow Actions on Multiple Workflows

Use this request to initiate a workflow action on multiple workflows. This starts an asynchronous job whose status you can check with the Retrieve Job Status endpoint. Maximum 500 workflows per request.

Request

$ curl -L -X POST -H "Authorization: {SESSION_ID}" \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'workflow_ids=2903,2904,2905' \
https://myvault.veevavault.com/api/v20.2/object/workflow/actions/cancelworkflows

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "job_id": 93601
   }
}

POST /api/{version}/object/workflow/actions/{action}

Headers

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

URI Path Parameters

Name	Description
action	The name of the workflow action. To get this value, Retrieve Bulk Workflow Actions.

Body Parameters

In the body of the request, add any fields required to initiate the action. To find which fields are required for an action, Retrieve Bulk Workflow Action Details.

Cancel Active Workflows: cancelworkflows

Name	Description
workflow_idsrequired	Input a comma-separated list of workflow_id__v field values. Maximum 500 workflows.
cancellation_commentoptional	If this workflow requires a comment for cancellation, use this parameter to provide a comment.

Reassign Workflow Tasks: reassigntasks

Note that this action can reassign a maximum of 500 tasks.

Name	Description
current_task_assigneerequired	Input the user ID of the user whose tasks you wish to reassign. You cannot reassign specific tasks for a user, only all tasks currently assigned to a user.
new_task_assigneerequired	Input the user ID of the user who will receive the newly assigned tasks.

Cancel Workflow Tasks: canceltasks

When cancelling tasks, you can do so by user ID or task ID. Use one of the following parameters:

Name	Description
user_idsconditional	To cancel tasks by user ID, input a comma-separated list of the user IDs for the users whose tasks you wish to cancel. You cannot cancel specific tasks for a user, only all tasks currently assigned to a user. Maximum 100 user IDs per request.
task_idsconditional	To cancel tasks by task ID, input a comma-separated list of the task IDs to cancel. You cannot cancel task IDs for a specific user, only all instances of the given task IDs.

Replace Workflow Owner: replaceworkflowowner

Name	Description
new_workflow_ownerrequired	Input the ID of the user who will become the new workflow owner. For example, 54937.
current_workflow_ownerrequired	Input the ID of the user who is the current workflow owner. For example, 87944.

Response Details

On SUCCESS, the response returns the job_id for the action, and the authenticated user will receive an email notification with details of any failures that occur. On FAILURE, the response returns an error type and message describing the reason for the failure. For example, the API returns INVALID_DATA if a task cannot be reassigned because the new task assignee is not in the appropriate role.

Document Lifecycle & Workflows

Document lifecycles are the sequences of states (Draft, In Review, etc.) a document goes through during its life. A lifecycle can be simple (two states requiring users to manually move between states) or very complex (multiple states with different security and workflows that automatically move the document to another state). In Vault, lifecycles simplify the implementation of business logic that traditionally required custom coding or time-consuming manual setup.

Lifecycle states are the ordered states within a lifecycle representing the stages a document transitions through as users create, review, approve, and eventually archive or replace it. A set of business rules applies to each state and defines what happens to the document in that state. Admins define these rules for each lifecycle state and Vault automatically applies them to every document that enters the state.

Learn about Lifecycles & Workflows in Vault Help.

Document & Binder User Actions

The API supports initiation of the following user action types:

• Workflow (legacy): This action starts the specified legacy workflow. Only legacy workflows that are already configured and active for the selected lifecycle are available. To start a document workflow, see Document Workflows.
• State Change: This action allows the user to manually move a document into a different lifecycle state. Vault enforces entry criteria and entry actions for the state change.
• Controlled Copy: This action is available in QualityDocs Vaults and with the QualityOne application family. It allows the user to generate and distribute a controlled copy.
• Create Presentation: This action is only available in PromoMats and Medcomms. It creates multiple Multichannel Slide documents and a Multichannel Presentation binder from a single document. This applies to Vaults that are configured for Engage integration or CLM integration.
• Create Email Fragment: This action is only available in PromoMats and MedComms Vaults that are configured for Approved Email Integration. It creates an email fragment for a document by applying a master email fragment.

Your Vault may include other user action types, all of which cannot be initiated through the Vault API. Learn more about document user action types in Vault Help.

The API does not support initiation of user actions requiring eSignatures.

Retrieve User Actions

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "responseMessage": "Success",
   "lifecycle_actions__v": [
       {
           "name__v": "start_review__c",
           "label__v": "Start Review",
           "lifecycle_action_type__v": "workflow",
           "lifecycle__v": "general_lifecycle__c",
           "state__v": "draft__c",
           "executable__v": "false"
       },
       {
           "name__v": "start_approval__c",
           "label__v": "Start Approval",
           "lifecycle_action_type__v": "workflow",
           "lifecycle__v": "general_lifecycle__c",
           "state__v": "draft__c",
           "executable__v": "true",
           "entry_requirements__v": "https://myvault.veevavault.com/api/v19.3/objects/documents/17/versions/0/1/lifecycle_actions/start_approval__c/entry_requirements"
       },
       {
           "name__v": "approve__c",
           "label__v": "Approve",
           "lifecycle_action_type__v": "stateChange",
           "lifecycle__v": "general_lifecycle__c",
           "state__v": "draft__c",
           "executable__v": "true",
           "entry_requirements__v": "https://myvault.veevavault.com/api/v19.3/objects/documents/17/versions/0/1/lifecycle_actions/approve__c/entry_requirements"
       }
   ]
}

Retrieve all available user actions on a specific version of a document or binder which:

• The authenticated user has permissions to view or initiate.
• Can be initiated through the API. See supported user actions.
• Is not currently in an active workflow.

GET /api/{version}/objects/{documents_or_binders}/{id}/versions/{major_version}/{minor_version}/lifecycle_actions

Headers

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

URI Path Parameters

Name	Description
{documents_or_binders}	Choose to retrieve values for documents or binders.
{id}	The document or binder id field value from which to retrieve available user actions.
{major_version}	The major version number of the document or binder.
{minor_version}	The minor version number of the document or binder.

Response Details

The response lists all available user actions (lifecycle_actions__v) that can be initiated on the specified version of the document or binder.

Name	Description
name__v	The user action name (consumed by the API). These vary from Vault to Vault and may be text, numeric, or alphanumeric values.
label__v	The user action label displayed to users in the UI.
lifecycle_action_type__v	The workflow (legacy) and stateChange types are the most commonly used and are available in all Vaults. Others may exist.
lifecycle__v	The document or binder lifecycle the action belongs to. For example, general_lifecycle__c.
state__v	The state of the document or binder.
executable__v	Indicates if the currently authenticated user has Execute permission for this action. If true the user can execute the action, otherwise false.
entry_requirements__v	The endpoint to retrieve the entry requirements for each user action. If no entry criteria exist, the endpoint returns an empty list. If the authenticated user does not have permission to execute this action, entry_requirements__v does not appear in the response.

Retrieve User Actions on Multiple Documents or Binders

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIds=22:0:1,21:1:0,20:1:0" \
https://myvault.veevavault.com/api/v13.0/objects/documents/lifecycle_actions

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "lifecycle_actions__v": [
        {
            "name__v": "make_obsolete__c",
            "label__v": "Make Obsolete",
            "lifecycle_action_type__v": "stateChange",
            "lifecycle__v": "general_lifecycle__c",
            "state__v": "approved__c",
            "entry_requirements__v": "https://myvault.veevavault.com/api/v13.0/objects/documents/lifecycle_actions/make_obsolete__c/entry_requirements?lifecycle=general_lifecycle__c&state=approved__c"
        },
        {
            "name__v": "approve__c",
            "label__v": "Approve",
            "lifecycle_action_type__v": "stateChange",
            "lifecycle__v": "general_lifecycle__c",
            "state__v": "draft__c",
            "entry_requirements__v": "https://myvault.veevavault.com/api/v13.0/objects/documents/lifecycle_actions/approve__c/entry_requirements?lifecycle=general_lifecycle__c&state=draft__c"
        }
    ]
}

Retrieve all available user actions on specific versions of multiple documents or binders.

POST /api/{version}/objects/{documents_or_binders}/lifecycle_actions

Headers

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

URI Path Parameters

Name	Description
{documents_or_binders}	Choose to retrieve values for documents or binders.

Body Parameters

Name	Description
docIdsrequired	The document or binder docIds field values from which to retrieve the available user actions. Include a comma-separated list of document or binder IDs and major and minor version numbers in the format {doc_id:major_version:minor_version}. For example, 22:0:1.

Response Details

The response lists all available lifecycle actions (lifecycle_actions__v) that can be initiated on the specified versions of multiple documents or binders.

Name	Description
name__v	The lifecycle action name (consumed by the API). These vary from Vault to Vault and may be text, numeric, or alphanumeric values.
label__v	The lifecycle action label. This is the “User Action” label seen in the UI.
lifecycle_action_type__v	The workflow (legacy) and stateChange types are the most commonly used and are available in all Vaults. Others may exist.
lifecycle__v	The document or binder lifecycle the action belongs to. For example, general_lifecycle__c.
state__v	The state of the document or binder.
entry_requirements__v	The endpoint to retrieve the entry requirements for each lifecycle action. If no entry requirements exist, the endpoint returns an empty list.

Note that lifecycle actions are not returned for documents or binders which are currently in an active workflow.

Retrieve Entry Criteria

Request: Start Legacy Workflow

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

Response: Start Legacy Workflow

{
   "responseStatus": "SUCCESS",
   "responseMessage": "Success",
   "properties": [
       {
           "name": "user_control_multiple__c",
           "description": "Approver",
           "type": [
               "ObjectReference"
           ],
           "objectTypeReferenced": {
               "name": "User",
               "label": "User"
           },
           "required": true,
           "editable": true,
           "repeating": true,
           "scope": "WorkflowActivation"
       },
       {
           "name": "date_control__c",
           "description": "Approval Due Date",
           "type": [
               "Date"
           ],
           "required": true,
           "editable": true,
           "scope": "WorkflowActivation"
       }
   ]
}

Request: Change State

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

Response: Change State

{
   "responseStatus": "SUCCESS",
   "responseMessage": "Success",
   "properties": [
       {
           "name": "country__v",
           "description": "Country",
           "type": [
               "ObjectReference"
           ],
           "objectTypeReferenced": {
               "name": "country__v",
               "label": "Country",
               "url": "/api/v19.3/metadata/vobjects/country__v",
               "label_plural": "Countries"
           },
           "required": true,
           "editable": true,
           "repeating": true,
           "scope": "Document",
           "currentSetting": [
               {
                   "name": "00C000000000109",
                   "label": "United States",
                   "value": "/api/v19.3/vobjects/country__v/00C000000000109"
               }
           ],
           "records": "/api/v19.3/vobjects/country__v"
       }
   ]
}

Retrieve the entry criteria for a user action. Entry criteria are requirements the document or binder must meet before you can initiate the action. Entry criteria are dynamic and depend on the lifecycle configuration, lifecycle state, or any workflow activation requirements defined in the Start Step of the workflow. Learn more about entry criteria in Vault Help.

To retrieve entry criteria, the authenticated user must have permission to execute the action. To check permissions, Retrieve User Actions and check for actions where executable__v is true.

GET /api/{version}/objects/{documents_or_binders}/{id}/versions/{major_version}/{minor_version}/lifecycle_actions/{name__v}/entry_requirements

Headers

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

URI Path Parameters

Name	Description
{documents_or_binders}	Choose to retrieve values for documents or binders.
{id}	The document or binder id field value from which to retrieve available user actions.
{major_version}	The major version number of the document or binder.
{minor_version}	The minor version number of the document or binder.
{name__v}	The lifecycle name__v field value from which to retrieve entry criteria. Retrieve this value from Retrieve User Actions.

Response Details

The response may include the following metadata elements describing the properties for which values need to be specified:

Name	Description
name	The entry criteria name (used in the API). This value must be specified when starting the user action.
description	The entry criteria name (used in the UI).
type	The entry criteria data type. This value can be one of String, Number, Date, Boolean, Picklist, or ObjectReference.
objectTypeReferenced	When type is ObjectReference, this is the object being referenced. For example: User, Product, Country, etc.
required	Boolean value indicating whether or not the entry criteria must be specified when initiating a user action.
editable	Boolean value indicating whether or not the value can be edited by the user.
repeating	Boolean value indicating whether or not the entry criteria can have multiple values.
minValue	Indicates the minimum character length for the value.
maxValue	Indicates the maximum character length for the value.
values	When type is Picklist, this provides a list of possible values that can be used.
currentSetting	When a value has already been set, this shows the value.
scope	Indicates where the entry criteria property is defined. This value can be one of: Document: This field must be set on the document before the action can be initiated. Binder: This field must be set on the binder before the action can be initiated. WorkflowActivation: This field must be included in the body of the initiate request. ControlledCopy: This field must be included in the body of the initiate request. Additionally, this value may be EmailFragment or CreatePresentation.

Response Details: Start Legacy Workflow

This example requests entry criteria for the start_approval__c workflow on document ID 17. The properties array in the response shows there are two entry criteria:

Approver: user_control_multiple__c

Name	Description
name	The name of this entry criteria in the API is user_control_multiple__c. Use this name when referring to this field in the API.
description	The label of this entry criteria in the UI is Approver. This should tell you the intended usage of this field.
type	This field is an ObjectReference.
objectTypeReferenced	This field is an ObjectReference to a User.
repeating	This field can accept more than one value, meaning more than one user can be assigned as the approver.
scope	The scope is WorkflowActivation, which means you can include this data as a name-value pair in the initiate request.

Approval Due Date: date_control__c

Name	Description
name	The name of this entry criteria in the API is date_control__c. Use this name when referring to this field in the API.
description	The label of this entry criteria in the UI is Approval Due Date. This should tell you the intended usage of this field.
type	This field is a Date.
scope	The scope is WorkflowActivation, which means you can include this data as a name-value pair in the initiate request.

Response Details: Change State

This example requests entry criteria for the approve__c user action on document ID 17. The properties array in the response shows there is one entry criteria:

Country: country__v

Name	Description
name	The name of this entry criteria in the API is country__v.
description	The label of this entry criteria in the UI is Country.
type	This field is an ObjectReference.
objectTypeReferenced	This field is an ObjectReference to the Country object.
repeating	This field can accept more than one value, meaning the document can belong to more than one country.
scope	The scope is Document, which means this document field must have a value before you can initiate the action.
currentSetting	The field on this document is currently set to United States. If you’re okay with this setting, you can initiate the action. If this was blank, you’d need to set it first.

Initiate User Action

Request: Start Legacy Workflow

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'user_control_multiple__c=user%3A10001400&date_control__c=2019-10-31'\
https://myvault.veevavault.com/api/v19.3/objects/documents/17/versions/0/1/lifecycle_actions/start_approval__c

Response: Start Legacy Workflow

{
   "responseStatus": "SUCCESS",
   "id": 17,
   "workflow_id__v": "401"
}

Request: Change State

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v19.3/objects/documents/17/versions/0/1/lifecycle_actions/approve__vs

Response

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

Initiate a user action. Before initiating, you should retrieve any applicable entry criteria for the action.

Only some user action types can be initiated through the API. See supported user actions.

The authenticated user must have permission to initiate this action. To check permissions, Retrieve User Actions and check for actions where executable__v is true.

PUT /api/{version}/objects/{documents_or_binders}/{id}/versions/{major_version}/{minor_version}/lifecycle_actions/{name__v}

Headers

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

URI Path Parameters

Name	Description
{documents_or_binders}	Choose to initiate an action on documents or binders.
{id}	The document or binder id field value on which to initiate the user action.
{major_version}	The major version number of the document or binder.
{minor_version}	The minor version number of the document or binder.
{name__v}	The action name__v field value to initiate. Retrieve this value from Retrieve User Action.

Request Details: Start Legacy Workflow

This request is initiating a start_approval__c workflow. Retrieving the entry criteria told us what fields we need to add to initiate this action, and that the scope is WorkflowActivation. This scope means we can add the required entry criteria fields as name-value pairs in the body of this request.

• user_control_multiple__c=user%3A10001400 is an ObjectReference to a User.
• date_control__c=2019-10-31 is a Date.

Request Details: Change State

This request is initiating the approve__c user action, which changes the state of the document to Approved. Retrieving the entry criteria told us what fields we need to add or update to initiate this action, and that the scope is Document. This scope means the required entry criteria must be set on the document prior to this request, so there are no additional parameters to add to this initiate request.

Download Controlled Copy Job Results

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v18.3/objects/documents/actions/draft_to_effective_lifecycle__c.effective__c.downloadControlledCopya95fbf38/39303/results
  -OJ

Response Headers

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="Download Issued Batch Record - 2018-10-10T22-01-18.473Z.zip"

This endpoint is for Extensible Controlled Copy; controlled_copy_trace__v and controlled_copy_user_input__v objects. If your organization is not using these objects, you should use the endpoints for Legacy Controlled Copy.

After initiating a controlled copy user action, use this endpoint to download the controlled copy. To execute this request in an integration flow, Retrieve the Job Status and use the href under "rel": "artifacts". We do not recommend executing this request outside of this flow.

Before submitting this request:

• You must have previously requested an initiate controlled copy job (via the API) which is no longer active
• You must be the user who initiated the job or have the Admin: Jobs: Read permission

GET /api/{version}/objects/documents/actions/{lifecycle_and_state_and_action}/{job_id}/results

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
{lifecycle_and_state_and_action}	The name__v values for the lifecycle, state, and action in the format {lifecycle_name}.{state_name}.{action_name}. To get this value, Retrieve the Job Status and find the href under "rel": "artifacts".
{job_id}	The ID of the job, returned from the original job request. For controlled copy, you can find this ID in the Initiate User Action response.

Response Details

On SUCCESS, Vault downloads your controlled copy.

The HTTP Response Header Content-Type is set to application/octet-stream. The HTTP Response Header Content-Disposition contains a default filename component which you can use when naming the local file.

By default, your file is named in the format {user action label} - {now()}.zip, which is consistent with downloading this file through the Vault UI. If you choose to name this file yourself, make sure you add the .zip extension.

Initiate Bulk User Actions

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIds=222:0:1,223:0:1,224:0:1,225:0:1" \
-d "lifecycle=general_lifecycle__c" \
-d "state=draft__c" \
https://myvault.veevavault.com/api/v17.1/objects/documents/lifecycle_actions/approve__c

Response

{
  "responseStatus": "SUCCESS"
}

For each bulk action, you may only select a single workflow that Vault will start for all selected and valid documents.

PUT /api/{version}/objects/{documents_or_binders}/lifecycle_actions/{user_action_name}

Headers

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

URI Path Parameters

Name	Description
{documents_or_binders}	Choose to change the state of documents or binders.
{user_action_name}	The user action name__v field value. Find this value with the Retrieve User Actions on Multiple Documents or Binders endpoint.

Body Parameters

Name	Description
docIdsrequired	Include a comma-separated list of document or binder IDs and major and minor version numbers. For example, 222:0:1,223:0:1,224:0:1 specifies version 0.1 of document IDs 222, 223, and 224. The user action is only executed on document IDs in the lifecycle and state specified in the request body. Document IDs listed in this parameter which are not in the specified lifecycle and state are skipped.
lifecyclerequired	Include the name of the document or binder lifecycle.
staterequired	Include the current state of your document.

Request Details

In this request:

• The input file format is set to accept name-value pairs.
• The lifecycle is specified. These documents are assigned to the general_lifecycle__c.
• The state is specified. We’re changing the state of all four documents from draft to approved.

Response Details

On SUCCESS, the initiating user receives a summary email detailing which documents or binders succeeded and failed the requested action.

Lifecycle Role Assignment Rules

For both standard and custom roles, you can define a subset of users who are allowed in the role and define users that Vault automatically assigns to the role at document creation or when a workflow starts. You can also override the allowed users and default users settings based on standard object-type document fields like Country, Product, Study, etc.

Vault Help Resources

• Lifecycles & Workflows
• Defining Allowed & Default Users for Roles
• Users & Groups
• Fields & Objects

Note the following limitations:

• The API can only be used with active lifecycles and roles.
• If the input contains duplicate field values, only the first instance is processed. The remaining duplicate fields are ignored.
• The maximum number of roles that can be created or updated per request is 50,000.
• The lifecycle role default rule cannot be set when creating override rules.
• A role cannot be assigned more users or groups to default roles than allowed on the role.
• The default owner__v role cannot be edited.

Retrieve Lifecycle Role Assignment Rules (Default & Override)

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__c&role__v=editor__c

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "lifecycle__v": "general_lifecycle__c",
            "role__v": "editor__c",
            "allowed_users__v": [
                "ally@veepharm.com",
                "beth@veepharm.com",
                "cruz@veepharm.com",
                "dave@veepharm.com"
            ],
            "allowed_groups__v": [
                "global_products_team__c",
                "vault_products_team__c",
                "vault_doc_management__c"
            ],
            "allowed_default_users__v": [
                "ally@veepharm.com"
            ],
            "allowed_default_groups__v": [
                "global_products_team__c"
            ]
        },
        {
            "lifecycle__v": "general_lifecycle__c",
            "role__v": "editor__c",
            "product__v.name__v": "CholeCap",
            "country__v.name__v": "United States",
            "product__v": "0PR0011001",
            "country__v": "0CR0022002",
            "allowed_users__v": [
                "etta@veepharm.com",
                "finn@veepharm.com",
                "greg@veepharm.com",
                "hope@veepharm.com"
            ],
            "allowed_groups__v": [
                "cholecap_us_docs_group__c",
                "cholecap_us_research_group__c",
                "cholecap_us_compliance_group__c",
                "cholecap_us_product_management_group__c"
            ],
            "allowed_default_users__v": [
                "etta@veepharm.com"
            ],
            "allowed_default_groups__v": [
                "cholecap_us_docs_group__c"
            ]
        }
    ]
}

GET /api/{version}/configuration/role_assignment_rule

Headers

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

This endpoint alone will retrieve a list of all lifecycle role assignment rules (default & override) from all roles in all lifecycles in your Vault.

To filter the results by lifecycle or role, add one or both of the following parameters to the request endpoint:

Query Parameters

Name	Description
lifecycle__v	Include the name of the lifecycle from which to retrieve information. For example: lifecycle_v=general_lifecycle__c
role__v	Include the name of the role from which to retrieve information. For example: role__v=editor__c
product__v	Include the ID/name of a specific product to see product-based override rules to default users/allowed users for the lifecycle role. For example: product__v=0PR0011001 or product__v.name__v=CholeCap
country__v	Include the ID/name of a specific country to see country-based override rules to default users/allowed users for the lifecycle role. For example: country__v=0CR0022002 or country__v.name__v=United States
study__v	In eTMF Vaults only. Include the ID/name of a specific study to see study-based override rules to default users/allowed users for the lifecycle role. For example: study__v=0ST0021J01 or study__v.name__v=CholeCap Study
study_country__v	In eTMF Vaults only. Include the ID/name of a specific study country to see study country-based override rules to default users/allowed users for the lifecycle role. For example: study_country__v=0SC0001001 or study_country__v.name__v=Germany

The response will include:

• The default role assignments
• The override role assignments when an override condition (when configured on the role) is met
• The override conditions (when configured on the role)

If you filter the results by one or more override conditions (product__v or country__v), the response will exclude the default role assignments and role assignments for the override conditions.

Request Details

Retrieve lifecycle role assignment rules from a specific role (editor__c) in a specific lifecycle (general_lifecycle__c):

Response Details

In this example response, the editor__c role in the general_lifecycle__c lifecycle is configured with the following role assignment rules:

Default Rule

When a document is assigned this lifecycle, the following users and groups are automatically assigned to the editor__c role:

• allowed_default_users__v - The user ally@veepharm.com is automatically assigned to the role.
• allowed_users__v - The users beth@veepharm.com, cruz@veepharm.com, and dave@veepharm.com can be (optionally) assigned to the role at any time during the lifecycle.
• allowed_default_groups__v - The group global_products_team__c is automatically assigned to the role.
• allowed_groups__v - The groups vault_products_team__c and vault_doc_management__c can be (optionally) assigned to the role at any time during the lifecycle.

Override Conditions

This lifecycle role has been configured with two override conditions which state: If both the product “CholeCap” and country “United States” are assigned to a document, do not apply the default rule, but instead apply the override rule.

The API returns both the system-managed object record id and the user-defined object record name__v (via the object__v.name__v lookup) field values which define the override conditions:

• "product__v.name__v": "CholeCap" - The product object record name.
• "country__v.name__v": "United States" - The country object record name.
• "product__v": "0PR0011001" - The product object record ID.
• "country__v": "0CR0022002" - The country object record ID.

Override Rule

When both the product “CholeCap” and country “United States” are assigned (at any time) to a document in this lifecycle, the following (alternate) users and groups are automatically assigned to the editor__c role:

• allowed_default_users__v - The user etta@veepharm.com is automatically assigned to the role.
• allowed_users__v - The users finn@veepharm.com, greg@veepharm.com, and hope@veepharm.com can be (optionally) assigned to the role during its lifecycle.
• allowed_default_groups__v - The group cholecap_us_docs_group__c is automatically assigned to the role.
• allowed_groups__v - The groups cholecap_us_research_group__c, cholecap_us_compliance_group__c, and cholecap_us_product_management_group__c can be (optionally) assigned to the role during its lifecycle.

Note: If the lifecycle role has not been configured with an override rule, the response will only display the default rule.

Create Lifecycle Role Assignment Override Rules

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
--data-binary @"C:\Vault\Override Rules\create-lifecycle-role-override-rules.json" \
https://myvault.veevavault.com/api/v15.0/configuration/role_assignment_rule

Response

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

POST /api/{version}/configuration/role_assignment_rule

Headers

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

Body Parameters

Before submitting this request, prepare a JSON or CSV input file with the following information:

Name	Description
name__vrequired	The name__v field values of the lifecycle and role to which the override rule is being added.
name__voptional	The name__v field values of the allowed and default groups who will be assigned to the role when the override condition is met.
idoptional	The id or name__v field values of the object records which define the override condition.
user_name__voptional	The user_name__v field values of the allowed and default users who will be assigned to the role when the override condition is met.

Note the following scope and limitations:

• This request can only be used to specify the override rules (conditions, users, and groups). It cannot be used to create default rules.
• The input may include override rules for multiple lifecycles and roles.
• Each role may be configured with multiple override rules.

Example CSV & JSON Input Files

Create an override rule on the editor__c role of the general_lifecycle__c with the following override conditions, users, and groups:

lifecycle__v	role__v	product__v.name__v	country__v.name__v	allowed_users__v	allowed_groups__v	allowed_default_users__v	allowed_default_groups__v
general_lifecycle__c	editor__c	CholeCap	United States	“etta@veevapharm.com,finn@veevapharm.com,greg@veevapharm.com,hope@veevapharm.com”	“cholecap_us_docs_group__c,cholecap_us_research_group__c,cholecap_us_compliance_group__c,cholecap_us_product_management_group__c”	etta@veevapharm.com	cholecap_us_docs_group__c

[
{
    "lifecycle__v": "general_lifecycle__c",
    "role__v": "editor__c",
    "product__v.name__v": "CholeCap",
    "country__v.name__v": "United States",
    "allowed_users__v": [
        "etta@veepharm.com",
        "finn@veepharm.com",
        "greg@veepharm.com",
        "hope@veepharm.com"
    ],
    "allowed_groups__v": [
        "cholecap_us_docs_group__c",
        "cholecap_us_research_group__c",
        "cholecap_us_compliance_group__c",
        "cholecap_us_product_management_group__c"
    ],
    "allowed_default_users__v": [
        "etta@veepharm.com"
    ],
    "allowed_default_groups__v": [
        "cholecap_us_docs_group__c"
    ]
}
]

Request Details

In this example:

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

Response Details

For each override rule specified in the input, the response includes a SUCCESS or FAILURE message.

Update Lifecycle Role Assignment Rules (Default & Override)

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Override Rules\update-lifecycle-role-override-rules.csv" \
https://myvault.veevavault.com/api/v15.0/configuration/role_assignment_rule

Before submitting this request, prepare a JSON or CSV input file. See the Create Lifecycle Role Assignment Override Rules request above for details.

PUT /api/{version}/configuration/role_assignment_rule

Headers

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

Response Details

For each default or override rule specified in the input, the response includes a SUCCESS or FAILURE message.

Delete Lifecycle Role Assignment Override Rules

Request: Delete All Overrides

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__c&role__v=editor__c

Response: Delete All Overrides

{
  "responseStatus": "SUCCESS",
  "data": {
    "rules_deleted": 2
  }
}

Request: Delete Object-Specific Override

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__c&role__v=editor__c&product__v.name__v=CholeCap

Response: Delete Object-Specific Override

{
  "responseStatus": "SUCCESS",
  "data": {
    "rules_deleted": 1
  }
}

Delete override rules configured on a specific lifecycle role.

DELETE /api/{version}/configuration/role_assignment_rule

Headers

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

Query Parameters

Name	Description
lifecycle__v	Include the name of the lifecycle from which to delete override rules. For example, lifecycle__v=general_lifecycle__c.
role__v	Include the name of the role from which to delete override rules. For example, role__v=editor__c.
{object_name}	Optional: To delete overrides on a specific object by ID, include the object ID. For example, product__v=0PR0011001.
{object_name}.name__v	Optional: To delete overrides on a specific object by name, include the object name. For example, product__v.name__v=CholeCap.

Response Details

On SUCCESS, the example response displays the number of override rules that were deleted from the lifecycle role.

Document Workflows

Document workflows enable users to send a collection of one or more documents for review and approval using a single workflow. The API allows you to retrieve, manage, and initiate document workflows.

Learn about Document Workflows in Vault Help.

Retrieve All Document Workflows

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "name": "Objectworkflow.clinical_study_report_approval__c",
           "label": "Clinical Study Report Approval",
           "type": "multidocworkflow",
           "cardinality": "OneOrMany"
       },
       {
           "name": "Objectworkflow.medical_docs_review_and_approval__c",
           "label": "Medical Docs Review and Approval",
           "type": "multidocworkflow",
           "cardinality": "OneOrMany"
       }
   ]
}

Retrieve all available document workflows that can be initiated on a set of documents which:

• The authenticated user has permissions to view or initiate
• Can be initiated through the API

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

Headers

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

Query Parameters

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

Response Details

On SUCCESS, the response lists all available document workflows and includes the following:

Name	Description
name	The workflow name.
label	UI Label for the workflow.
type	Type of workflow.
cardinality	Indicates how many contents (One, OneOrMany) can be included in a workflow.

For users without the Workflow: Start permission, the response returns an INSUFFICIENT_ACCESS error.

Retrieve Document Workflow Details

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "name": "Objectworkflow.clinical_study_report_approval__c",
       "controls": [
           {
               "type": "instructions",
               "instructions": "Add approvers",
               "prompts": [],
               "label": "Instructions"
           },
           {
               "type": "participant",
               "prompts": [
                   {
                       "label": "Approver",
                       "name": "approver__c"
                   }
               ],
               "required": true,
               "label": "Participants"
           },
           {
               "type": "participant",
               "prompts": [
                   {
                       "label": "Exec Approver",
                       "name": "exec_approver__c"
                   }
               ],
               "required": true,
               "label": "Participants"
           },
           {
               "prompts": [
                   {
                       "label": "Documents",
                       "name": "documents__sys"
                   }
               ],
               "label": "Documents",
               "type": "documents"
           },
           {
               "prompts": [
                   {
                       "multi_value": false,
                       "label": "Description",
                       "name": "description__sys"
                   }
               ],
               "label": "Description",
               "type": "description"
           }
       ],
       "label": "Clinical Study Report Approval",
       "type": "multidocworkflow",
       "cardinality": "OneOrMany"
   }
}

Retrieves the details for a specific document workflow.

GET /api/{version}/objects/documents/actions/{workflow_name}

Headers

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

URI Path Parameters

Name	Description
workflow_name	The document workflow name value.

Query Parameters

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

Response Details

On SUCCESS, the response lists the fields that must be configured with values in order to initiate the document workflow. These are based on the controls configured in the workflow start step.

The response may include the following types of controls:

Name	Description
prompts	The input prompts which accept values when initiating the workflow.
instructions	Contains static instruction text regarding workflow initiation.
participant	Used to specify users who will be part of the workflow.
date	Date selections for the workflow, such as due date.
documents	Used to specify the documents for inclusion in the workflow.
description	The document workflow description.
variable	The variable prompts which accept values when initiating the workflow.

For each control, the following data may be returned:

Name	Description
label	UI Label for the control.
type	Type of control (instructions, participant, date, documents, description, or variable).

Additionally, the response includes following fields describing the workflow:

Name	Description
name	The workflow name.
label	UI Label for the workflow.
type	Type of workflow (multidocworkflow).
cardinality	Indicates how many contents (One, OneOrMany) can be included in a workflow.

Initiate Document Workflow

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-d "approver__c: user:83610" \
-d "exec_approver__c: user:10081" \
-d "contents__sys: 56,31,25" \
-d "description__sys: CSR Approval" \
https://myvault.veevavault.com/api/v18.3/objects/documents/actions/Objectworkflow.clinical_study_report_approval__c

Response: Success

{
    "responseStatus": "SUCCESS",
    "data": {
        "record_url": "/api/v18.3/vobjects/envelope__sys/0ER000000000501",
        "record_id__v": "0ER000000000501",
        "workflow_id": "1301"
    }
}

Response: Failure

{
    "responseStatus": "FAILURE",
    "errors": [
      {
      "type": "INVALID_DATA",
      "message": "Invalid value [94] specified for parameter [documents__sys] : documents are in invalid lifecycles"
    }
  ]
}

Initiate a document workflow on a set of documents. If any document is not in the relevant state or does not meet configured field conditions, the API returns INVALID_DATA for the invalid documents and the workflow does not start.

POST /api/{version}/objects/documents/actions/{workflow_name}

Headers

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

URI Path Parameters

Name	Description
{workflow_name}	The document workflow name value.

Body Parameters

The following parameters are required, but an Admin may set other fields as required in your Vault. To find which fields are required to start this workflow, Retrieve Document Workflow Details.

Name	Description
documents__sysrequired	Input a comma-separated list of document id field values. Maximum 100 documents.
description__sysrequired	Description of the workflow. Maximum 128 characters.

Add Participants

To add participants to a workflow, add the name of the participant control to the body of the request. The value should be a comma-separated list of user and group IDs in the format {user_or_group}:{id}. For example, approvers__c: user:123,group:234. Use Retrieve Document Workflow Details to get the names of all participant controls for the workflow.

Response Details

On SUCCESS, the response includes the following:

Name	Description
record_id__v	The id value of the envelope__sys record.
workflow_id	The workflow id field value.

Manage Document Workflow Tasks

Document workflows share some of the same capabilities as object workflows and are configured on the envelope_sys object. You can use the Workflow Task endpoints to retrieve document workflow tasks, task details, and initiate document workflow tasks.

Remove Documents from Envelope

You can remove one or more documents from an envelope__sys object using the removecontent action in the Initiate Workflow Action endpoint.

Object Lifecycle & Workflows

Object lifecycles are the sequences of states (Draft, In Review, etc.) an object record goes through. A lifecycle can be simple (two states that require users to manually move between them) or very complex (multiple states with different security and workflows that automatically move records from one state to another). In Vault, lifecycles simplify the implementation of business logic that traditionally required custom coding or time-consuming manual setup. A set of business rules applies to each state and defines what happens to object records in that state. Admins define these rules for each lifecycle state and Vault automatically applies them to every object record that enters the state.

Learn about Lifecycles & Workflows in Vault Help.

Object Record User Actions

The API supports retrieval and initiation of user actions on Vault object records.

Retrieve Object Record User Actions

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v20.1/vobjects/product__v/00P000000000301/actions

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "links": [
                {
                    "rel": "metadata",
                    "href": "/api/v20.1/vobjects/product__v/00P000000000301/actions/Objectlifecyclestateuseraction.product__v.active_state__c.start_workflow_useraction__c",
                    "accept": "application/json",
                    "method": "GET"
                },
                {
                    "rel": "execute",
                    "href": "/api/v20.1/vobjects/product__v/00P000000000301/actions/Objectlifecyclestateuseraction.product__v.active_state__c.start_workflow_useraction__c",
                    "accept": "application/json",
                    "method": "POST"
                }
            ],
            "label": "Start Workflow",
            "type": "workflow",
            "name": "Objectlifecyclestateuseraction.product__v.active_state__c.start_workflow_useraction__c"
        }
    ]
}

Retrieve all available user actions that can be initiated on a specific object record which:

• The authenticated user has permissions to view or initiate
• Can be initiated through the API

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value.
{object_record_id}	The object record id field value.

Query Parameters

Name	Description
loc	Optional: When true, retrieves localized (translated) strings for the label.

Response Details

On SUCCESS, the response lists all available user actions that can be initiated on the specified object record.

• For users with the View permission, the response includes a link to retrieve the metadata for the specified user action.
• For users without the View permission, the response returns an INSUFFICIENT_ACCESS error.
• For users with the Execute permission, the response includes a link to initiate the specified action.

Name	Description
type	The type of user action. For example, an action of the type State Change will appear as state_change. Object actions which are not attached to a lifecycle state appear as type object_action.
name	The user action name. object_action types include the Objectaction prefix. Lifecycle user action types, such as workflow, include the Objectlifecyclestateuseraction prefix.
label	The user action label as seen in the UI.

Retrieve Object User Action Details

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.3/vobjects/product_v/0PR0771/actions/Objectaction.product__v.copy_record__c

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "links": [
            {
                "rel": "metadata",
                "accept": "application/json",
                "Href": "api/v17.3/vobjects/product_v/0PR0771/actions/Objectaction.product__v.copy_record__c",
                "method": "GET"
            },
            {
                "rel": "execute",
                "accept": "application/json",
                "Href":      "api/v17.3/vobjects/product_v/0PR0771/actions/Objectaction.product__v.copy_record__c",
                "method": "POST"
            }
        ],
        "label": "Copy Record",
        "type": "object_action",
        "name": "Objectaction.product__v.copy_record__c"
    }
}

Once you’ve retrieved the available user actions, use this request to retrieve the details for a specific user action.

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

Headers

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

URI Path Parameters

Name	Description
object_name	The object name__v field value.
object_record_id	The object record id field value from which to retrieve user action details.
action_name	Either the name of the Objectaction or Objectlifecyclestateuseraction to initiate. This is obtained from the Retrieve User Actions request.

Response Details

On SUCCESS, the response returns metadata for the specified object action.

• For users with the View permission, the response includes a link to retrieve the metadata for the specified user action.
• For users without the View permission, the response returns an INSUFFICIENT_ACCESS error.
• For users with the Execute permission, the response includes a link to initiate the specified action.

Response Details

On SUCCESS, the response lists the fields that must be configured with values in order to initiate the user action. These are based on the controls configured in the workflow start step.

• For users with the View permission, the response includes a link to retrieve the metadata for the specified user action.
• For users without the View permission, the response returns an INSUFFICIENT_ACCESS error.
• For users with the Execute permission on the action, the response includes a link to initiate the specified action.

For actions with the type: workflow, the following types of controls may be returned:

Name	Description
instructions	Contains static instruction text regarding workflow initiation.
participant	Used to specify users who will be part of the workflow.
date	Date selections for the workflow, such as due date.
field	All object fields requiring values.

For each control, the following data may be returned:

Name	Description
label	UI Label for the control.
type	Type of control (instructions, participants, date, or fields).
prompts	The input prompts (if any) which accept values when initiating the workflow. Prompts of type field accept values per the metadata specified for the field in the object metadata.

Initiate Object Action on a Single Record

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'due_date__c=2020-03-01T08:00:00.000Z' \
-d 'product__v.generic_name__c=nitroprinaline oxalate' \
-d 'product__v.internal_name__c=Nyaxa' \
-d 'product__v.compound_id__c=CC-127' \
-d 'approvers__c=user:10001399' \
https://myvault.veevavault.com/api/v20.1/vobjects/product__v/00P000000000301/actions/Objectlifecyclestateuseraction.product__v.active_state__c.start_workflow_useraction__c

Response

{
    "responseStatus": "SUCCESS"
}

Use this request to initiate an action on a specific object record.

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

Headers

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

URI Path Parameters

Name	Description
object_name	The object name__v field value.
object_record_id	The object record id field value from which to retrieve user actions.
action_name	The name of the Objectaction or Objectlifecyclestateuseraction to initiate. You can retrieve this from the Retrieve User Actions request. The format for action_name is Objectaction.{vobject}.{action} or Objectlifecyclestateuseraction.{vobject}.{state}.{action}. For example, Objectlifecyclestateuseraction.country__v.active_state__c.start_wf_useraction__c.

Body Parameters

Include any parameters required to initiate the action as name-value pairs in the request body. You can retrieve the required parameters for your action by Retrieving Object User Action Details.

Name	Description
{participant_group_name}.assignment_type__cconditional	The participant group assignment type for a workflow task, either assigned or available. Required if the workflow initiator must select either Assigned to every user or Available to any user when assigning participants to a task in the workflow start step. For example, part_reviewers__c.assignment_type__c=assigned.
storyEventKeyoptional	The ID of the target Story Event object record when executing the Apply Milestone Template action. This is only applicable in Clinical Operations Vaults.

Values in Required Field Prompts

When providing values for field prompts on a start step, task step, or verdict, required fields cannot be omitted, set as blank, or defaulted to their existing value.

To preserve the existing value of a required field prompt, submit the existing value as the new value.

Initiate Object Action on Multiple Records

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "ids: 0MO0771, 0MO0772, 0MO0773" \
https://myvault.veevavault.com/api/v17.3/vobjects/monitoring_event__v/actions/Objectaction.monitoring_event__v.copy_record__v

Response

{
  "responseStatus": "SUCCESS",
  "data": [
      {
          "responseStatus": "SUCCESS",
          "id": "0MO0771"
      },
      {
          "responseStatus": "SUCCESS",
          "id": "0MO0772"
      },
      {
          "responseStatus": "FAILURE",
          "id": "0MO0773",
          "errors": [
              {
                  "type": "INSUFFICIENT_ACCESS",
                  "message": "User does not have sufficient privileges to perform the action"
              }
          ]
      }
  ]
}

Use this request to initiate an object user action on multiple records. Maximum 500 records per batch.

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

Headers

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

URI Path Parameters

Name	Description
object_name	The object name__v field value.
action_name	The name of the Objectaction or Objectlifecyclestateuseraction to initiate. This is obtained from the Retrieve User Actions request. The format for action_name is Objectaction.{vobject}.{action} or Objectlifecyclestateuseraction.{vobject}.{state}.{action}. For example, Objectlifecyclestateuseraction.country__v.active_state__c.start_wf_useraction__c.

Body Parameters

Name	Description
idsrequired	Comma-separated list of object record ids on which to initiate the action.
{participant_group_name}.assignment_type__cconditional	The participant group assignment type for a workflow task, either assigned or available. Required if the workflow initiator must select either Assigned to every user or Available to any user when assigning participants to a task in the workflow start step. For example, part_reviewers__c.assignment_type__c=assigned.

Values in Required Field Prompts

When providing values for field prompts on a start step, task step, or verdict, required fields cannot be omitted, set as blank, or defaulted to their existing value.

To preserve the existing value of a required field prompt in a workflow on a single record, submit the existing value as the new value.

For a workflow on multiple records, there is no way to preserve existing values in a field if that field is a required prompt. Setting a value for a prompt updates all records to the same single value.

Multi-Record Workflows

An object workflow is a series of steps configured in Vault to correspond with the specific business processes of your organization. These steps are actions that occur on or in relation to an individual object record or a group of object records on the same object.

Object workflows are specific to an object, meaning that a single workflow cannot apply to multiple objects. A single object record can only be in one workflow at a time.

Retrieve All Multi-Record Workflows

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "name": "Objectworkflow.approval__c",
           "label": "Review & Approval Workflow",
           "type": "multirecordworkflow",
           "cardinality": "OneOrMany"
       }
   ]
}

Retrieve all available multi-record workflows which:

• The authenticated user has permissions to view or initiate
• Can be initiated through the API

GET /api/{version}/objects/objectworkflows/actions

Headers

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

Response Details

On SUCCESS, the response includes the following:

Name	Description
name	The workflow name.
label	UI label for the workflow.
type	Type of workflow.
cardinality	Indicates how many contents (One, OneOrMany) can be included in a workflow.

For users without the Workflow: Start permission, the response returns an INSUFFICIENT_ACCESS error.

Retrieve Multi-Record Workflow Details

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
https://myvault.veevavault.com/api/v22.3/objects/objectworkflows/actions/Objectworkflow.approval__c

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "name": "Objectworkflow.approval__c",
       "controls": [
           {
               "prompts": [
                   {
                       "label": "Contents",
                       "name": "contents__sys"
                   }
               ],
               "type": "contents",
               "label": "Contents"
           },
           {
               "prompts": [
                   {
                       "multi_value": false,
                       "label": "Description",
                       "name": "description__sys"
                   }
               ],
               "type": "description",
               "label": "Description"
           }
       ],
       "label": "Multi-Object",
       "type": "multirecordworkflow",
       "cardinality": "OneOrMany"
   }
}

Retrieves the fields required to initiate a specific multi-record workflow.

GET /api/{version}/objects/objectworkflows/actions/{workflow_name}

Headers

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

URI Path Parameters

Name	Description
{workflow_name}	The multi-record workflow name value.

Response Details

On SUCCESS, the response lists the fields that must be configured with values in order to initiate the workflow. These are based on the controls configured in the workflow start step.

The response may include the following types of controls:

Name	Description
prompts	The input prompts which accept values when initiating the workflow.
instructions	Contains static instruction text regarding workflow initiation.
participant	Used to specify users who will be part of the workflow.
date	Date selections for the workflow, such as due date.
documents	Used to specify the documents for inclusion in the workflow.
description	The document workflow description.
variable	The variable prompts which accept values when initiating the workflow.

Additionally, the response includes following fields describing the workflow:

Name	Description
name	The workflow name.
label	UI Label for the workflow.
type	Type of workflow (multirecordworkflow).
cardinality	Indicates how many contents (One, OneOrMany) can be included in a workflow.

Initiate Multi-Record Workflow

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "contents__sys: Object:feature_record__c.V3O000000005001,Object:feature_record__c.V3O000000005002" \
-d "description__sys: CSR Approval" \
-d "exec_approver__c: user:10081" \
https://myvault.veevavault.com/api/v22.3/objects/objectworkflows/actions/Objectworkflow.approval__c

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "record_url": "/api/v22.3/vobjects/envelope__sys/0ER000000009003",
       "record_id__v": "0ER000000009003",
       "workflow_id": "8703"
   }
}

Initiate a multi-record workflow on a set of records. If any record is not in the relevant state or does not meet configured field conditions, the API returns INVALID_DATA for the invalid records and the workflow does not start.

POST /api/{version}/objects/objectworkflows/actions/{workflow_name}

Headers

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

URI Path Parameters

Name	Description
{workflow_name}	The workflow name value.

Body Parameters

The following parameters are required, but an Admin may set other fields as required in your Vault. To find which fields are required to start this workflow, Retrieve Multi-Record Workflow Details.

Name	Description
contents__sysrequired	Input a comma-separated list of records, in the format Object:{objectname}.{record_ID}. For example, Object:product__c.V3O000000005001. Maximum 100 records.
description__sysrequired	Description of the workflow. Maximum 128 characters.

Add Participants

To add participants to a workflow, add the name of the participant control to the body of the request. The value should be a comma-separated list of user and group IDs in the format {user_or_group}:{id}. For example, approvers__c: user:123,group:234. Use Retrieve Document Workflow Details to get the names of all participant controls for the workflow.

Values in Required Field Prompts

Required fields cannot be omitted, set as blank, or defaulted to their existing value.

To preserve the existing value of a required field prompt in a workflow on a single record, submit the existing value as the new value.

For a workflow on multiple records, there is no way to preserve existing values in a field if that field is a required prompt. Setting a value for a prompt updates all records to the same single value.

Response Details

On SUCCESS, the response includes the following:

Name	Description
record_id__v	The id value of the envelope__sys record.
workflow_id	The workflow id field value.

Manage Multi-record Workflow Tasks

Multi-record workflows are configured on the envelope_sys object. You can use the Workflow Task endpoints to retrieve workflow tasks, details, and initiate tasks.

Remove Records from Workflow

You can remove one or more records from an envelope__sys object using the removecontent action in the Initiate Workflow Action endpoint.

Users

Learn about Creating & Managing Users and Managing Users Across Vaults in Vault Help.

To update Vault Membership for multiple Vaults within the same domain, create cross-domain users, or add users to a domain without assigning Vault membership, use the Create Users endpoint.

Learn about Managing the User & Person Objects in Vault Help.

Retrieve User Metadata

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "properties": [
    {
      "name": "user_name__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_first_name__v",
      "type": "String",
      "length": 100,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_last_name__v",
      "type": "String",
      "length": 100,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "alias__v",
      "type": "String",
      "length": 40,
      "editable": true,
      "queryable": false,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_email__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_timezone__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "Pacific/Niue",
          "label": "(GMT-11:00) Niue Time (Pacific/Niue)"
        },
        {
          "value": "Pacific/Pago_Pago",
          "label": "(GMT-11:00) Samoa Standard Time (Pacific/Pago_Pago)"
        },
      ]
    },
    {
      "name": "user_locale__v",
      "type": "String",
      "length": 10,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "pt_BR",
          "label": "Brazil"
        },
        {
          "value": "es_ES",
          "label": "Spain"
        },
      ]
    },
    {
      "name": "user_title__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "office_phone__v",
      "type": "String",
      "length": 20,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "fax__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "mobile_phone__v",
      "type": "String",
      "length": 20,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "site__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "is_domain_admin__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "active__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "domain_active__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "security_policy_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "securitypolicies",
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_needs_to_change_password__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "id",
      "type": "id",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_date__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_by__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "modified_date__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "modified_by__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "domain_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "domains",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "vault_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "vaults",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": true,
      "onCreateEditable": false
    },
    {
      "name": "federated_id__v",
      "type": "String",
      "length": 100,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "salesforce_user_name__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "last_login__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "medidata_uuid__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_language__v",
      "type": "String",
      "length": 10,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "en",
          "label": "English"
        },
        {
          "value": "ja",
          "label": "Japanese"
        },
      ]
    },
    {
      "name": "company__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "group_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "groups",
      "editable": false,
      "queryable": false,
      "required": false,
      "multivalue": true,
      "onCreateEditable": false
    },
    {
      "name": "security_profile__v",
      "type": "ObjectReference",
      "length": 40,
      "object": "Securityprofile",
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "business_admin__v",
          "label": "Business Administrator"
        },
        {
          "value": "document_user__v",
          "label": "Document User"
        },
        {
          "value": "external_user__v",
          "label": "External User"
        },
        {
          "value": "read_only_user__v",
          "label": "Read-Only User"
        },
        {
          "value": "system_admin__v",
          "label": "System Administrator"
        },
        {
          "value": "vault_owner__v",
          "label": "Vault Owner"
        },
        {
          "value": "view_based_user__v",
          "label": "View-Based User"
        }
      ]
    },
    {
      "name": "license_type__v",
      "type": "Picklist",
      "length": 40,
      "picklist": "license_type__v",
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    }
  ]
}

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

Headers

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

Response Details

This response includes a full list of fields for users. Some field values are abridged to shorten this example response.

Retrieve All Users

Request

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

Request

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

Request

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

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/users?vaults=3003,4004,5005

Response

{
    "responseStatus": "SUCCESS",
    "size": 200,
    "start": 0,
    "limit": 200,
    "sort": "id asc",
    "users": [
        {
            "user": {
                "id": 25501,
                "user_name__v": "ewoodhouse@veepharm.com",
                "user_first_name__v": "Elaine",
                "user_last_name__v": "Woodhouse"
              }
        },
        {
            "user": {
                "id": 25502,
                "user_name__v": "bashton@veepharm.com",
                "user_first_name__v": "Bruce",
                "user_last_name__v": "Ashton"
              }
        },
        {
            "user": {
                "id": 25503,
                "user_name__v": "tchung@veepharm.com",
                "user_first_name__v": "Thomas",
                "user_last_name__v": "Chung"
              }
        }
      ]
    }

GET /api/{version}/objects/users

Headers

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

Query Parameters

Using the endpoint alone with no optional parameters will retrieve users assigned only to the Vault in which the request is made. For customers with multiple Vaults in their domain, users with Domain Admin, System Admin, and Vault Owner privileges can access user information across different Vaults in the domain by including the optional parameter vaults set to one of the following values:

Name	Description
vaults=all	Retrieve all users assigned to all Vaults in your domain.
vaults=-1	Retrieve all users assigned to all Vaults in your domain except for the Vault in which the request is made.
vaults={Vault IDs}	Retrieve all users assigned to Vault ID 3003, Vault ID 4004, and Vault ID 5005. Use a comma-separated list of Vault IDs to retrieve users assigned only to the specified Vaults.
exclude_vault_membership	Optional: Set to false to include vault_membership fields. If true or omitted, vault_membership fields are not included in the response.
exclude_app_licensing	Optional: Set to false to include app_licensing fields. If true or omitted, app_licensing fields are not included in the response.

System Admins and Vault Owners must have administrative access to Vault applications referenced in the vaults parameter to be able to access users from those Vault.

The response also supports pagination. By default the page limit is set to 200 records. The pagination parameters are:

Name	Description
limit	[optional, default is 200] the size of the result set in the page
start	[optional, default is 0] the starting record number
sort	[optional, default is “id asc”] the sort order for the result set (asc - ascending, desc - descending) (e.g. user_name__v asc)

Vault-Owned Users

When you retrieve legacy users, the response includes multiple system-owned user records that appear in all Vaults. These accounts are used to capture actions that are performed by Vault instead of by a user. These records are not included in license counts, are read-only, and cannot be referenced by another user or document. Learn more in Vault Help.

Retrieve User

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "users": [
       {
           "user": {
               "user_name__v": "olive@veepharm.com",
               "user_first_name__v": "Olivia",
               "user_last_name__v": "Cattington",
               "user_email__v": "olivia.cattington@veepharm.com",
               "user_timezone__v": "America/Los_Angeles",
               "user_locale__v": "en_US",
               "user_title__v": "Senior Vice President for Research & Development",
               "is_domain_admin__v": false,
               "active__v": true,
               "domain_active__v": true,
               "security_policy_id__v": 1000181,
               "user_needs_to_change_password__v": false,
               "id": 1006546,
               "created_date__v": "2022-05-23T20:49:06.000Z",
               "created_by__v": 1003079,
               "modified_date__v": "2022-06-16T17:22:49.000Z",
               "modified_by__v": 1,
               "domain_id__v": 1000076,
               "domain_name__v": "veepharm.com",
               "vault_id__v": [
                   1000660,
                   1000659
               ],
               "last_login__v": "2022-05-23T21:01:13.000Z",
               "user_language__v": "en",
               "company__v": "Veepharm",
               "group_id__v": [
                   1,
                   1394917493302,
                   6
               ],
               "security_profile__v": "vault_owner__v",
               "license_type__v": "full__v"
           }
       }
   ]
}

Retrieve information for one user. To get information for all users, see Retrieve All Users.

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

Headers

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

URI Path Parameters

Name	Description
{id}	The user id field value. To get information for the currently authenticated user, see Validate Session User.

Query Parameters

Name	Description
exclude_vault_membership	Optional: Set to false to include vault_membership fields. Including these fields may decrease performance. If omitted, vault_membership fields are not included in the response.
exclude_app_licensing	Optional: Set to false to include app_licensing fields. Including these fields may decrease performance. If omitted, app_licensing fields are not included in the response.

Create Users

Create new user accounts or add existing users as cross-domain users. Learn more about cross-domain users in Vault Help. Note that users only receive welcome emails if they are assigned to a Vault. For example, a new domain user who does not have any assigned Vaults will not receive a welcome email.

Suppressing Welcome Emails: When creating new users, you can prevent Vault from sending welcome emails to a user by setting the user_needs_to_change_password__v setting to false. This does not work for users with SSO security profiles, but you can work around this limitation by creating the users with a basic security profile and updating them to the SSO security profile with an update action.

Create Single User

Request: Add User to Domain

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "user_name__v=ewoodhouse@veepharm.com" \
-F "user_email__v=ewoodhouse@veepharm.com" \
-F "user_first_name__v=Elaine" \
-F "user_last_name__v=Woodhouse" \
-F "user_language__v=en" \
-F "user_timezone__v=America/Denver" \
-F "user_locale__v=en_US" \
-F "security_policy_id__v=821" \
-F "domain=true" \
https://myvault.veevavault.com/api/v15.0/objects/users

Request: Add User to Current Vault

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "user_name__v=ewoodhouse@veepharm.com" \
-F "user_email__v=ewoodhouse@veepharm.com" \
-F "user_first_name__v=Elaine" \
-F "user_last_name__v=Woodhouse" \
-F "user_language__v=en" \
-F "user_timezone__v=America/Denver" \
-F "user_locale__v=en_US" \
-F "security_policy_id__v=821" \
-F "security_profile__v=business_admin__v" \
-F "license_type__v=full__v" \
-F "file=@C:\Documents\Pictures\profile_image.jpg"
https://myvault.veevavault.com/api/v15.0/objects/users

Request Details: Add Cross-Domain User

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "user_name__v=ewoodhouse@veepharm.com" \
-F "security_profile__v=business_admin__v" \
-F "license_type__v=full__v" \
https://myvault.veevavault.com/api/v15.0/objects/users

Create one user at a time without the need for a CSV input file or upload profile pictures to file staging. After creation, you can assign these users to Vaults with the Update Vault Membership endpoint.

Some Vaults use multiple applications, for example, a RIM Vault with Submissions and Registrations. If your Vault utilizes user-based licensing, you must use the Create Multiple Users endpoint with the app_licensing field. After creation, you can also manually adjust the user’s application licenses through the Vault UI. Learn more about license types and application licenses in Vault Help.

POST /api/{version}/objects/users

Headers

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

Body Parameters

The following table provides the required and most common optional parameters to create a user. You may add values to any other editable user field, unless you are adding a cross-domain user or VeevaID user. See Retrieve Users for all possible values.

Name	Description
user_name__vrequired	The user’s Vault username (login credential). For example, ewoodhouse@veepharm.com
user_first_name__vrequired	The user’s first name.
user_last_name__vrequired	The user’s last name.
user_email__vrequired	The user’s email address.
user_timezone__vrequired	The user’s time zone. Retrieve values from Retrieve Users.
user_locale__vrequired	The user’s location. Retrieve values from Retrieve Users.
security_policy_id__vrequired	The user’s security policy. Retrieve values from Retrieve All Security Policies.
user_language__vrequired	The user’s preferred language. Retrieve values from Retrieve Users.
security_profile__voptional	The user’s security profile. If omitted, the default value is document_user__v.
license_type__voptional	The license type is the first level of access control that Vault applies to a user. If your Vault utilizes user-based licensing, assign application licensing using the Create Multiple Users endpoint. The license_type__v cannot be less permissive than a user’s application licensing. If omitted, the default value is full__v.
fileoptional	The file path to upload a profile picture. Must be JPG, PNG, or GIF, and less than 10MB in size. Vault automatically resizes images to 64 x 64 pixels and removes the animations in GIFs. Note that when you upload or change a user’s profile image, the change applies across the entire domain and will be visible in all Vaults where the user has membership.

Cross-Domain Users

The following are the only fields required to create a cross-domain user. All other fields are ignored.

Name	Description
user_name__vrequired	The user’s Vault username (login credential). For example, ewoodhouse@veepharm.com
security_profile__voptional	The user’s security profile. If omitted, the default value is document_user__v.
license_type__voptional	The user’s license type. If omitted, the default value is full__v. If your Vault utilizes user-based licensing, assign application licensing using the Create Multiple Users endpoint.

VeevaID Users

The following are the only fields required to add an existing VeevaID user to Vault. All other fields are ignored.

Name	Description
user_name__vrequired	The user’s Vault username (login credential). For example, ewoodhouse@veepharm.com
security_policy_id__vrequired	The name__v of your Vault’s VeevaID security policy, for example, 25285. You can retrieve this ID from the Retrieve All Security Policies endpoint.
security_profile__voptional	The user’s security profile. If omitted, the default value is document_user__v.
license_type__voptional	The user’s license type. If omitted, the default value is full__v. If your Vault utilizes user-based licensing, assign application licensing using the Create Multiple Users endpoint.

Query Parameters

Name	Description
domain	When set to true, the user will not be assigned to a Vault.

Request Details: Add User to Domain

On SUCCESS, the user account is created and set to active. The new user is not assigned a license type or security profile, nor do they have access to any Vaults in your domain. This means they will not receive a welcome email.

Request Details: Add User to Current Vault

This request adds one new user to your domain and assigns them to the Vault where the request was made. They will receive a welcome email with instructions for logging into the Vault, and they will not have access to any other Vaults in your domain. To give them access to other Vaults, see Update Vault Membership.

This example request includes all fields required to create a new user, and two optional fields (security profile and license type). If these optional fields were not included in the request, the user would be assigned the document_user__v security profile and full__v license type by default.

Request Details: Add Cross-Domain User

This request adds the user ewoodhouse.veevavault.com to your current domain as a cross-domain user.

All other metadata fields are ignored. Learn more about cross-domain users in Vault Help.

Create Multiple Users

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Users\create_users.csv" \
https://myvault.veevavault.com/api/v12.0/objects/users

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "id":"12021"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12022"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12023"
      },
      {
         "responseStatus":"FAILURE",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not created."
            }
         ]
      }
   ]
}

Create new users and assign them to Vaults in bulk. You can also add multiple existing users as cross-domain users or VeevaID users.

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.
• If you want to add profile pictures, you must upload these to file staging.

POST /api/{version}/objects/users

Headers

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

Body Parameters

Prepare a JSON or CSV input file. You may add values to any other editable user field, unless you are adding a cross-domain user or VeevaID user. See Retrieve Users for all possible values. Using only the required fields will add users to your domain but will not assign them to individual Vaults within your domain. To assign users to individual Vaults, you must also use the required Vault Membership parameters.

Name	Description
user_name__vrequired	The user’s Vault username (login credential). For example, ewoodhouse@veepharm.com
user_first_name__vrequired	The user’s first name.
user_last_name__vrequired	The user’s last name.
user_email__vrequired	The user’s email address.
user_timezone__vrequired	The user’s time zone. Retrieve values from Retrieve Users.
user_locale__vrequired	The user’s location. Retrieve values from Retrieve Users.
security_policy_id__vrequired	The user’s security policy. Retrieve values from Retrieve All Security Policies.
user_language__vrequired	The user’s preferred language. Retrieve values from Retrieve Users.
fileoptional	The file path of a profile picture from file staging. Must be JPG, PNG, or GIF, and less than 10MB in size. Vault automatically resizes images to 64 x 64 pixels and removes the animations from GIFs. Note that when you upload or change a user’s profile image, the change applies across the entire domain and will be visible in all Vaults where user has membership.
domainoptional	If you set this to true, the user will not be assigned to a Vault.
security_profile__voptional	The user’s security profile. If omitted, the default value is document_user__v.
license_type__voptional	The license type is the first level of access control that Vault applies to a user. If your Vault utilizes user-based licensing, assign application licensing using the app_licensing field.
vault_membershipoptional	Use this field to assign a user to individual Vaults within your domain. This is required to create cross-domain users or VeevaID users. Learn how to configure this parameter in the Vault Membership section.
app_licensingoptional	Use this field to assign a user to individual applications within your Vault. Learn how to configure this parameter in the Application Licensing section.

Vault Membership

To assign user permissions across Vaults, create cross-domain users,or create VeevaID users, you must include the vault_membership column configured with the following fields:

Name	Description
vault_idrequired	The Vault ID to assign the user to.
active__voptional	Set the user to active (true) or inactive (false). If not specified, default value is true.
security_profile__voptional	Set the user’s security profile, for example, read_only_user__v. If not specified, this value defaults to document_user__v.
license_type__voptional	Set the user’s license type, for example, read_only__v. If not specified, this value defaults to full__v.

For example, to add an active user to Vault ID 3003 with the system_admin__v security profile and the full__v license type:

vault_membership
3003:true:system_admin__v:full__v

Application Licensing

To add a user to specific applications within a Vault or across Vaults, you must include the app_licensing column configured with the following fields:

Name	Description
vault_idrequired	The Vault ID to assign the user to.
active__voptional	Set the user to active (true) or inactive (false). If not specified, default value is true.
application_namerequired	The application to add the user to. For example, use rimReg_v to assign a user to the RIM Registrations application.
license_type__voptional	Set the user’s license type for a specific application, for example, read_only__v. You must select a license value for at least one application. Possible values are: full__v external__v learner_user__v read_only__v Some license values may be invalid depending on the application. The license_type__v for an application cannot be more permissive than the user’s Vault-wide license type. If omitted, the default value is full__v. The request fails if you provide an invalid license_type__v value for a specific application. Learn more about valid license values by application in Vault Help.

The format for adding these fields is:

{vault_id}|{application_name}{:active__v}{:license_type__v}

To add a user to more than one application, separate the applications with a pipe. To add a user to applications in multiple Vaults, separate the Vaults with a semicolon. For example:

app_licensing
3003|rimReg_v:true:full__v|rimSubs_v:true:full__v;4112|rimSubs_v:true:full__v

This adds an active user to both RIM Registrations and RIM Submissions in Vault ID 3003, and to the RIM Submissions application in Vault ID 4112, all with the full__v license type.

Add Cross-Domain Users

The following are the only fields required to add cross-domain users. All other fields are ignored. Learn more about cross-domain users in Vault Help.

Name	Description
user_name__vrequired	The user’s Vault username (login credential). For example, ewoodhouse@veepharm.com.
vault_membershiprequired	Assign this user permissions across domains. Learn how to configure this parameter in the Vault Membership section.

Add VeevaID Users

The following are the only fields required to add an existing VeevaID user to Vault. All other fields are ignored.

Name	Description
user_name__vrequired	The user’s Vault username (login credential). For example, ewoodhouse@veepharm.com.
vault_membershiprequired	Assign this user permissions across domains. Learn how to configure this parameter in the Vault Membership section.
security_policy_id__vrequired	The name__v value of your Vault’s VeevaID security profile, for example, 25285. You can retrieve this ID from the Retrieve All Security Policies endpoint.

Query Parameters: Upsert Users

Upsert is a combination of create and update. Use one input file to create new users and update existing users at the same time. If a matching user record is found in your Vault, it is updated with the field values specified in the input. If no matching user record is found, a new user is created using values in the input.

Name	Description
operation	To upsert users, you must include operation=upsert
idParam	To upsert users, you must include either idParam=id or idParam=user_name__v to the request endpoint.

Response Details:

On SUCCESS, Vault responds will list the id of each user. The order results are displayed in the response is the same as the order of records in the input.

Update Users

Update information for a user.

System Admins and Vault Owners can update users in the Vaults where they have administrative access. System Admins who are also Domain Admins have an unrestricted access to users across all Vaults in the domain.

Note that some user fields are not available to update through the API. For example, you cannot update user profile pictures through the API. To find out which fields are available to update, you can Retrieve User Metadata and find all fields marked as "editable": true. If a field is missing from this response, it is not editable.

Update Single User

Request: Update User Profile Information

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "user_timezone__v=America/Los Angeles" \
-d "company__v=VeevaPharm" \
-d "user_title__v=Product Manager" \
-d "alias__v=Skipper" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001

Request: Disable User at Domain-Level

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

Request: Re-Enable User at Domain-Level

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

Request: Promote a User to Domain Admin

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

Request: Update User Application Licensing

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "app_licensing=25001|qualityQms_v:true:full__v" \
https://myvault.veevavault.com/api/v24.2/objects/users/25001

Response

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

Update information for a single user. To update information for multiple users, see Retrieve All Users.

PUT /api/{version}/objects/users/{id}

Headers

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

URI Path Parameters

Name	Description
{id}	The user id field value. Use the value me to update information for the currently authenticated user.

Body Parameters

In the body of the request, add any editable fields you wish to update. To remove existing field values, include the field name and set its value to null.

Example Request: Disable User at Domain-Level

Only Domain Admins may use this request.

When updating a user, domain_active__v can be (optionally) included in the input and set to either true or false to enable or disable the user at the domain-level. Disabling a user at the domain-level will disable the user in every Vault in your domain. Re-enabling a user enables them in the domain but does not re-activate them in their Vaults. After re-enabling a user, you must update their Vault membership to make them active in the individual Vaults.

This request will set the user (ID: 25001) profile to inactive in all Vaults in your domain. The user will still be a member in the Vaults and retain their license types and security profiles, but their user profile will be inactive and they will no longer have access to any Vaults in your domain.

Example Request: Re-Enable User at Domain-Level

Only Domain Admins may use this request.

This request will set the (previously inactive) user (ID: 25001) profile to active in your Vault domain. However, they will still be inactive in and unable to access your domain Vaults. Use the Update Vault Membership request below to set their status to active in the individual Vaults in your domain.

Example Request: Promote a User to Domain Admin

Only Domain Admins may use this request.

This request will promote a user to Domain Admin. To remove a user from the Domain Admin role, set the is_domain_admin__v field to false. Each domain must have at least one user in the Domain Admin role.

Example Request: Update User Application Licensing

This request updates a user’s licensing values for a specific application. As of 24R2, Vault enforces valid license values by application. When updating a user’s application licensing values, Vault corrects any invalid application license values based on the user’s initial license_type__v. For example, if a user’s initial license type is full__v and their application license value for Vault QMS is read_only__v, Vault updates the QMS application license value to full__v. If the user’s initial license type is read_only__v and their license value for Vault QMS is read_only__v, Vault clears the QMS license value because read_only__v is not a valid license value for QMS.

Some license values may be invalid depending on the application. The request fails if you provide an invalid license value for a specific application. Learn more about valid license values by application in Vault Help.

Update My User

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "user_title__v=Technical Writer" \
-d "site__v": "San Francisco",
https://myvault.veevavault.com/api/v17.1/objects/users/me

Response

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

Update information for the currently authenticated user.

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

Headers

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

Body Parameters

In the body of the request, add any editable fields you wish to update. To remove existing field values, include the field name and set its value to null.

Response Details

On SUCCESS, the specified values are updated and the request returns the id of the currently authenticated user.

Update Multiple Users

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Users\update_users.csv" \
https://myvault.veevavault.com/api/v12.0/objects/users

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "id":"12021"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12022"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12023"
      },
      {
         "responseStatus":"FAILURE",
         "id":"22124",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not updated."
            }
         ]
      }
   ]
}

Update information for multiple users at once.

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

PUT /api/{version}/objects/users

Headers

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

Body Parameters

Prepare a JSON or CSV input file. You can include any editable user field and value in the input. Note this endpoint does not support the security_profile attribute for updating profiles.

Name	Description
idrequired	The ID of the user to update.
vault_membershipoptional	See Vault Membership for how to configure.

Disable User

Request: Disable User in a Vault

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

Request: Disable User in All Domain Vaults

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001?domain=true

Response

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

Disable a user in a specific Vault or disable a user in all Vaults in the domain.

Permissions

System Admins and Vault Owners can update users in the Vaults where they have administrative access. System Admins who are also Domain Admins have an unrestricted access to users across all Vaults in the domain.

DELETE /api/{version}/objects/users/{user_id}

Headers

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

URI Path Parameters

Name	Description
{user_id}	The user id field value. See Retrieve All Users above.

Query Parameters

Name	Description
domain	When true, this disables the user account in all Vaults in the domain.

Request: Disable User in a Vault

This request will set the user (ID: 25001) profile to inactive in the Vault in which the request is made. The user will still be a member in the Vault and retain their license type and security profile, but their user profile will be inactive and they will no longer have access to the Vault.

Request: Disable User in All Domain Vaults

This request will set the user (ID: 25001) profile to inactive in all Vaults in your domain. The user will still be a member in the Vaults and retain their license types and security profiles, but their user profile will be inactive and they will no longer have access to any Vaults in your domain.

Change My Password

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "password__v=CurrentPassword" \
-d "new_password__v=NewPassword" \
https://myvault.veevavault.com/api/v17.1/objects/users/me/password

Response

{
    "responseStatus": "SUCCESS"
}

Change the password for the currently authenticated user.

POST /api/{version}/objects/users/me/password

Headers

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

Body Parameters

Name	Description
password__vrequired	Enter your current password.
new_password__vrequired	Enter your desired new password. Must be a different value than password__v.

Passwords must meet minimum requirements, which are configured by your Vault Admin. Learn about Configuring Password Requirements in Vault Help.

Response Details

On SUCCESS, your password is changed.

Update Vault Membership

Request: Add User to a Vault

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

Request: Disable User in a Vault

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "active__v=false" \
https://myvault.veevavault.com/api/v15.0/objects/users/25001/vault_membership/3003

Request: Set Security Profile & License Type

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "security_profile__v=business_admin__v" \
-d "license_type__v=full__v"
https://myvault.veevavault.com/api/v15.0/objects/users/25001/vault_membership/3003

Use this request to:

• Assign an existing user to a Vault in your domain.
• Remove (disable) an existing user from a Vault in your domain.
• Update the security profile and license type of an existing user.

You cannot use this request to:

• Create a new user. See Create Object Records.
• Update other user profile information. See Update Object Records.

Additional information:

• For a list of user fields and properties, see Retrieve Users.
• Learn about Creating & Managing Users and Managing Users Across Vaults in Vault Help.

Permissions

System Admins and Vault Owners can update users in the Vaults where they have administrative access. System Admins who are also Domain Admins have an unrestricted access to users across all Vaults in the domain.

PUT /api/{version}/objects/users/{user_id}/vault_membership/{vault_id}

Headers

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

URI Path Parameters

Name	Description
{user_id}	The user id field value. See Retrieve All Users above.
{vault_id}	The system-managed id field value assigned to each Vault in the domain.

Body Parameters

Name	Description
active__voptional	Set the user status to active (true) or inactive (false). If omitted, this value defaults to active__v.
security_profile__voptional	Assigns the user a specific security profile in the Vault. If omitted, defaults to document_user__v.
license_type__voptional	Assigns the user a specific license type in the Vault. If omitted, defaults to full__v.

See the example requests below for additional information about using these input values.

Request Details: Add User to a Vault

This request will assign the user (ID: 25001) to the Vault (ID: 3003). There are a few default settings that will be applied here:

The user’s status will be set to active in the Vault. This is the default setting; the active__v=true parameter ca be omitted and produce the same results. We’ve not included the optional security_profile__v and license_type__v in the input. Therefore, the user will be assigned a full__v license type and document_user__v security profile by default.

Request Details: Disable User in a Vault

This request will set the user (ID: 25001) profile to inactive in the Vault (ID: 3003). They will still be a member in the Vault and retain their license type and security profile, but their user profile will be inactive and they will no longer have access to the Vault.

Request Details: Set Security Profile & License Type

This request will set the user (ID: 25001) security profile and license type to specific values in the Vault (ID: 3003). If the user is already a member of the Vault, this will change their security profile and license type. If the user is not a member of the Vault, this will assign them to the Vault, set their status to active, and their security profile and license type to the specified values.

Retrieve Application License Usage

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "doc_count": {
        "licensed": 4000,
        "used": 2380
    },
    "applications": [
        {
            "application_name": "pm_promomats__v",
            "user_licensing": {
                "full__v": {
                    "licensed": 500,
                    "used": 491,
                    "shared": false
                },
                "external__v": {
                    "licensed": 100,
                    "used": 67,
                    "shared": false
                },
                "read_only__v": {
                    "licensed": 100,
                    "used": 28,
                    "shared": false
                }
            }
        },
        {
            "application_name": "pm_multichannel__v",
            "user_licensing": {
                "full__v": {
                    "licensed": 500,
                    "used": 441,
                    "shared": false
                },
                "external__v": {
                    "licensed": 0,
                    "used": 0,
                    "shared": false
                },
                "read_only__v": {
                    "licensed": 0,
                    "used": 0,
                    "shared": false
                }
            }
        }
    ]
}

Retrieve your current license usage compared to the licenses that your organization has purchased. This information is similar to the information displayed in the Vault UI from Admin > Settings > General Settings.

Some Vaults use multiple applications, for example, a RIM Vault with Submissions and Registrations. In these Vaults, users have a license value for each application they can access. Application licensing allows Vault to track available licenses at the application level, but does not control a user’s access in most Vaults. A user assigned to multiple applications will use one (1) application license per application. Learn more about Application Licenses in Vault Help.

GET /api/{version}/objects/licenses

Headers

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

Response Details

The response contains the following application license details:

Name	Description
doc_count	PromoMats and Vault Medical only: The number of document views across all users with view-based license type against a pre-purchased set of views for the Vault. Learn more about view-based user licenses in Vault Help.
application_name	The API name of this application license, for example, pm_promomats__v.
user_licensing	An array of the available application licenses for the given application_name.
user_licensing.licensed	The maximum number of users who can be assigned to this application license. For example, if the full__v application license has a licensed value of 50, you can assign this license to a maximum of 50 users.
user_licensing.used	The number of users currently assigned to this application license. To determine the number of application licenses available for assignment, subtract used from licensed. For example, if your application license has a licensed value of 50 and a used value of 40, you can assign 10 more users to this application license.
user_licensing.shared	Indicates if this user license is shared.

Retrieve User Permissions

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.1/objects/users/61579/permissions?filter=name__v::object.product__v.object_actions

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "name__v": "object.product__v.object_actions",
      "permissions": {
        "read": true,
        "edit": true,
        "create": false,
        "delete": false
      }
    }
  ]
}

Retrieve all object and object field permissions (Read, Edit, Create, Delete) assigned to a specific user.

GET /api/{version}/objects/users/{id}/permissions

Headers

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

URI Path Parameters

Name	Description
{id}	The ID of the user. Use the value me to retrieve information for the currently authenticated user.

Query Parameters

Name	Description
filter=name__v::{permission_name}	Filter the results to show only one specific name__v, which is in the format object.{object name}.{object or field}_actions. Wildcards are not supported.

Retrieve My User Permissions

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.1/objects/users/me/permissions?filter=name__v::object.user__sys.object_actions

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "name__v": "object.user__sys.object_actions",
            "permissions": {
                "read": true,
                "edit": true,
                "create": true,
                "delete": false
            }
        }
    ]
}

Retrieve all object and object field permissions (Read, Edit, Create, Delete) assigned to the currently authenticated user.

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

Headers

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

Query Parameters

Name	Description
filter=name__v::{permission_name}	Filter the results to show only one specific name__v, which is in the format object.{object name}.{object or field}_actions. Wildcards are not supported.

Validate Session User

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "users": [
       {
           "user": {
               "user_name__v": "tibanez@veepharm.com",
               "user_first_name__v": "Teresa",
               "user_last_name__v": "Ibanez",
               "user_email__v": "teresa.ibanez@veepharm.com",
               "user_timezone__v": "America/Denver",
               "user_locale__v": "en_US",
               "is_domain_admin__v": true,
               "active__v": true,
               "security_policy_id__v": 1863,
               "id": 61603,
               "created_date__v": "2018-01-09T23:07:48.000Z",
               "created_by__v": 1,
               "modified_date__v": "2024-11-13T00:17:17.000Z",
               "modified_by__v": 1,
               "domain_id__v": 3826,
               "last_login__v": "2024-12-11T00:24:12.000Z",
               "user_language__v": "en",
               "group_id__v": [
                   1392631750202,
                   1392631750402,
                   1392631748902
               ],
               "security_profile__v": "vault_owner__v",
               "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. If the session ID is not valid, this request returns an INVALID_SESSION_ID error type.

When interpreting the response, understand that the following fields are based on the Vault user, rather than the domain user:

• created_date__v
• created_by__v
• modified_date__v
• modified_by__v
• last_login__v

Delegated Sessions

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.

SCIM

System for Cross-domain Identity Management (SCIM) is designed to make managing user identities in cloud-based applications and services easier. The Vault REST API is based on SCIM 2.0.

All SCIM endpoints require a Vault session ID which can be used as Bearer tokens.

Discovery Endpoints

Retrieve SCIM Provider

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/ServiceProviderConfig

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "documentationUri": "https://developer.veevavault.com",
    "patch": {
        "supported": false
    },
    "bulk": {
        "supported": false,
        "maxOperations": 0,
        "maxPayloadSize": 0
    },
    "filter": {
        "supported": false,
        "maxResults": 1000
    },
    "changePassword": {
        "supported": false
    },
    "sort": {
        "supported": true
    },
    "etag": {
        "supported": false
    },
    "authenticationSchemes": [
        {
            "name": "OAuth Bearer Token",
            "description": "Authentication scheme using the OAuth Bearer Token Standard",
            "type": "oauthbearertoken",
            "primary": true
        }
    ],
    "meta": {
        "resourceType": "ServiceProviderConfig",
        "location": "https://promomats-template.vaultdev.com/api/v18.2/scim/v2/ServiceProviderConfig"
    }
}

Retrieve a JSON that describes the SCIM specification features available on the currently authenticated Vault.

GET /api/{version}/scim/v2/ServiceProviderConfig

Headers

Name	Description
Accept	application/json (default) or application/scim+json

Response Details

The attributes returned in the JSON object are defined in Section 5 of RFC7643.

Retrieve All SCIM Schema Information

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/Schemas

Response

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 6,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Schema"
            ],
            "id": "urn:ietf:params:scim:schemas:core:2.0:User",
            "name": "User",
            "description": "User Account",
            "attributes": [
                {
                    "name": "active",
                    "type": "boolean",
                    "multiValued": false,
                    "description": "A Boolean value indicating the User's administrative status.",
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                },
                {
                    "name": "displayName",
                    "type": "string",
                    "multiValued": false,
                    "description": "The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described if known.",
                    "required": false,
                    "caseExact": false,
                    "mutability": "readOnly",
                    "returned": "default",
                    "uniqueness": "none"
                }
            ]
        }

    ]
}

Retrieve information about all SCIM schema specifications supported by a Vault SCIM service provider.

GET /api/{version}/scim/v2/Schemas

Headers

Name	Description
Accept	application/json (default) or application/scim+json

Retrieve Single SCIM Schema Information

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/Schemas/urn:ietf:params:scim:schemas:extension:veevavault:2.0:User

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Schema"
    ],
    "id": "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
    "name": "VaultSCIMUser",
    "description": "Veeva Vault User",
    "attributes": [
        {
            "name": "createdBy",
            "type": "complex",
            "subAttributes": [
                {
                    "name": "$ref",
                    "type": "reference",
                    "multiValued": false,
                    "description": "The URI of the SCIM resource representing the User",
                    "required": true,
                    "caseExact": false,
                    "mutability": "readOnly",
                    "returned": "default",
                    "uniqueness": "none",
                    "referenceTypes": [
                        "User"
                    ]
                },
                {
                    "name": "value",
                    "type": "string",
                    "multiValued": false,
                    "description": "The id of the SCIM resource representing a User",
                    "required": true,
                    "caseExact": false,
                    "mutability": "readOnly",
                    "returned": "default",
                    "uniqueness": "none"
                }
            ],
            "multiValued": false,
            "description": "The user who has created this record.",
            "required": false,
            "caseExact": false,
            "mutability": "readOnly",
            "returned": "default",
            "uniqueness": "none"
        }
    ]
}

Retrieve information about a single SCIM schema specification supported by a Vault SCIM service provider.

GET /api/{version}/scim/v2/Schemas/{id}

Headers

Name	Description
Accept	application/json (default) or application/scim+json

URI Path Parameters

Name	Description
id	The ID of a specific schema. For example, urn:ietf:params:scim:schemas:extension:veevavault:2.0:User.

Retrieve All SCIM Resource Types

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/ResourceTypes

Response

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 4,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
            ],
            "id": "User",
            "name": "User",
            "description": "User Account",
            "endpoint": "/Users",
            "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
            "schemaExtensions": [
                {
                    "schema": "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
                    "required": true
                },
                {
                    "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
                    "required": false
                }
            ],
            "meta": {
                "resourceType": "Resource Type",
                "location": "https://promomats-template.vaultdev.com/api/v18.2/scim/v2/ResourceTypes/User"
            }
        },
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
            ],
            "id": "SecurityProfile",
            "name": "SecurityProfile",
            "description": "Security Profile",
            "endpoint": "/SecurityProfiles",
            "schema": "urn:ietf:params:scim:schemas:extension:veevavault:2.0:SecurityProfile",
            "meta": {
                "resourceType": "Resource Type",
                "location": "https://promomats-template.vaultdev.com/api/v18.2/scim/v2/ResourceTypes/SecurityProfile"
            }
}

Retrieve the types of SCIM resources available. Each resource type defines the endpoints, the core schema URI that defines the resource, and any supported schema extensions.

GET /api/{version}/scim/v2/ResourceTypes

Headers

Name	Description
Accept	application/json (default) or application/scim+json

Retrieve Single SCIM Resource Type

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/ResourceTypes/SecurityProfile

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
    ],
    "id": "SecurityProfile",
    "name": "SecurityProfile",
    "description": "Security Profile",
    "endpoint": "/SecurityProfiles",
    "schema": "urn:ietf:params:scim:schemas:extension:veevavault:2.0:SecurityProfile",
    "meta": {
        "resourceType": "Resource Type",
        "location": "https://promomats-template.vaultdev.com/api/v18.2/scim/v2/ResourceTypes/SecurityProfile"
    }
}

Retrieve a single SCIM resource type. Defines the endpoints, the core schema URI which defines this resource, and any supported schema extensions.

GET /api/{version}/scim/v2/ResourceTypes/{type}

Headers

Name	Description
Accept	application/json (default) or application/scim+json

URI Path Parameters

Name	Description
type	A specific resource type. You can retrieve all available types from the Retrieve All SCIM Resource Types endpoint, where the value for this parameter is the id value.

Users

Retrieve All Users with SCIM

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/Users

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "100084",
    "meta": {
        "created": "2018-01-24T21:28:47.000Z",
        "lastModified": "2018-05-22T04:51:21.000Z",
        "resourceType": "User",
        "location": "https://veepharm.com/api/v18.2/scim/v2/Users/100084"
    },
    "active": true,
    "displayName": "Kimathi Gills",
    "emails": [
        {
            "value": "kg@veepharm.com",
            "type": "work"
        }
    ],
    "locale": "en_US",
    "name": {
        "familyName": "Gills",
        "givenName": "Kimathi"
    },
    "preferredLanguage": "en",
    "timezone": "America/Los_Angeles",
    "userName": "kimathi@veepharm.com",
    "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User": {
        "createdBy": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/Users/1",
            "value": "1"
        },
        "domainAdmin": false,
        "favoriteDocNewComment": false,
        "favoriteDocNewContent": false,
        "favoriteDocNewStatus": false,
        "lastLogin": "2018-01-26T19:13:20.000Z",
        "lastModifiedBy": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/Users/1",
            "value": "1"
        },
        "licenseType": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/LicenseTypes/full__v",
            "value": "full__v"
        },
        "lifecycle": "vault_membership_lifecycle__sys",
        "lifecycleState": "active_state__sys",
        "productAnnouncementEmails": false,
        "securityPolicy": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/SecurityPolicies/2525",
            "value": "2525"
        },
        "securityProfile": {
            "value": "business_admin__v",
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/SecurityProfiles/business_admin__v"
        },
        "systemAvailabilityEmails": false
    },
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "manager": "61603"
    }
}

Retrieve all users with SCIM.

GET /api/{version}/scim/v2/Users

Headers

Name	Description
Accept	application/json (default) or application/scim+json

Query Parameters

Name	Description
filter	Optional: Filter for a specific attribute value. Must be in the format {attribute} eq "{value}". For example, to filter for a particular user name, userName eq "john". Complex expressions are not supported, and eq is the only supported operator.
attributes	Optional: Include specified attributes only. Enter multiple values in a comma separated list. For example, to include only user name and email in the response, attributes=userName,emails. Note that the schemas and id attributes are always returned.
excludedAttributes	Optional: Exclude specific attributes from the response. Enter multiple values in a comma separated list. For example, to exclude user name and email from the response, excludedAttributes=userName,emails. Note that the schemas and id attributes are always returned and cannot be excluded.
sortBy	Optional: Specify an attribute or sub-attribute to order the response. For example, you can sort by the displayName attribute, or the name.familyName sub-attribute. If omitted, the response is sorted by id. Note that the following attributes are not supported: securityPolicy securityProfile locale preferredLanguage
sortOrder	Optional: Specify the order in which the sortBy parameter is applied. Allowed values are ascending or descending. If omitted, defaults to ascending.
count	Optional: Specify the number of query results per page, for example, 10. Negative values are treated as 0, and 0 returns no results except for totalResults. If omitted, defaults to 1000.
startIndex	Optional: Specify the index of the first result. For example, 10 would omit the first 9 results and begin on result 10. Omission, negative values, and 0 is treated as 1.

Retrieve Single User with SCIM

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/Users/61579?attributes=userName,emails

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "61579",
    "emails": [
        {
            "value": "mmurray@veepharm.com",
            "type": "work"
        }
    ],
    "userName": "mmurray@veepharm.com"
}

Retrieve a specific user with SCIM.

GET /api/{version}/scim/v2/Users/{id}

Headers

Name	Description
Accept	application/json (default) or application/scim+json

URI Path Parameters

Name	Description
id	The ID of a specific user.

Query Parameters

Name	Description
filter	Optional: Filter for a specific attribute value. Must be in the format {attribute} eq "{value}". For example, to filter for a particular user name, userName eq "john". Complex expressions are not supported, and eq is the only supported operator.
attributes	Optional: Include specified attributes only. Enter multiple values in a comma separated list. For example, to include only user name and email in the response, attributes=userName,emails. Note that the schemas and id attributes are always returned.
excludedAttributes	Optional: Exclude specific attributes from the response. Enter multiple values in a comma separated list. For example, to exclude user name and email from the response, excludedAttributes=userName,emails. Note that the schemas and id attributes are always returned and cannot be excluded.

Retrieve Current User with SCIM

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/Me?attributes=userName,emails,meta

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "61579",
    "meta": {
        "created": "2018-01-09T23:07:46.000Z",
        "lastModified": "2018-06-19T22:48:30.000Z",
        "resourceType": "User",
        "location": "https://veepharm.com/api/v18.2/scim/v2/Users/61579"
    },
    "emails": [
        {
            "value": "mmurray@veepharm.com",
            "type": "work"
        }
    ],
    "userName": "mmurray@veepharm.com"
}

Retrieve the currently authenticated user with SCIM.

GET /api/{version}/scim/v2/Me

Headers

Name	Description
Accept	application/json (default) or application/scim+json

Query Parameters

Name	Description
attributes	Optional: Include specified attributes only. Enter multiple values in a comma separated list. For example, to include only user name and email in the response, attributes=userName,emails. Note that the schemas and id attributes are always returned.
excludedAttributes	Optional: Exclude specific attributes from the response. Enter multiple values in a comma separated list. For example, to exclude user name and email from the response, excludedAttributes=userName,emails. Note that the schemas and id attributes are always returned and cannot be excluded.

Update Current User with SCIM

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/Me?attributes=userName,name

Body

{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "name": {
                "familyName": "Murray",
                "givenName": "Megan"
    }
}

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "61579",
    "name": {
        "familyName": "Murray",
        "givenName": "Megan"
    },
    "userName": "mmurray@veepharm.com"
}

Update the currently authenticated user with SCIM.

PUT /api/{version}/scim/v2/Me

Headers

Name	Description
Accept	application/json (default) or application/scim+json

Query Parameters

Name	Description
attributes	Optional: Include specified attributes only. Enter multiple values in a comma separated list. For example, to include only user name and email in the response, attributes=userName,emails. Note that the schemas and id attributes are always returned.
excludedAttributes	Optional: Exclude specific attributes from the response. Enter multiple values in a comma separated list. For example, to exclude user name and email from the response, excludedAttributes=userName,emails. Note that the schemas and id attributes are always returned and cannot be excluded.

Body Parameters

The body of your request should be a JSON file with the information you want to update for your user. You can include any editable attribute. Invalid attributes are ignored. You can set single-valued attributes to blank using null, or an empty array [] for multi-valued attributes.

You can determine which of the core attributes are editable based on schemas. If the mutability is readWrite, the attribute is editable.

Create User with SCIM

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/scim+json" \
--data-binary @"C:\Vault\Users\create_users_scim.json" \
https://veepharm.com/api/v18.2/scim/v2/Users

Body

{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "AbigailSmith@veepharm.com",
    "emails": [
        {
            "value": "abigail.smith@veepharm.com",
             "type": "work"
        }
    ],
    "name": {
                "familyName": "Smith",
                "givenName": "Abigail"
            },
    "preferredLanguage": "en",
    "locale": "en_US",
    "timezone": "America/Los_Angeles",
    "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User": {
    "securityProfile": {
                    "value": "system_admin__v"
                }
  }
}

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "114055",
    "meta": {
        "created": "2018-05-29T23:44:08.000Z",
        "lastModified": "2018-05-29T23:44:08.000Z",
        "resourceType": "User",
        "location": "https://veepharm.com/api/v18.2/scim/v2/Users/114055"
    },
    "active": true,
    "displayName": "Abigail Smith",
    "emails": [
        {
            "value": "abigail.smith@veepharm.com",
            "type": "work"
        }
    ],
    "locale": "en_US",
    "name": {
        "familyName": "Smith",
        "givenName": "Abigail"
    },
    "preferredLanguage": "en",
    "timezone": "America/Los_Angeles",
    "userName": "AbigailSmith@veepharm.com",
    "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User": {
        "createdBy": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/Users/61579",
            "value": "61579"
        },
        "extendedAttributes": [
            {
                "name": "is_asset_portal_user__sys",
                "value": "false"
            }
        ],
        "lastModifiedBy": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/Users/61579",
            "value": "61579"
        },
        "licenseType": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/LicenseTypes/full__v",
            "value": "full__v"
        },
        "lifecycle": "vault_membership_lifecycle__sys",
        "lifecycleState": "active_state__sys",
        "securityPolicy": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/SecurityPolicies/2525",
            "value": "2525"
        },
        "securityProfile": {
            "value": "system_admin__v",
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/SecurityProfiles/system_admin__v"
        }
    }
}

Create a user with SCIM.

POST /api/{version}/scim/v2/Users

Headers

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

Body Parameters

The body of your request should be a JSON file with the required information for your new user. The following fields are required, but you can add any other editable field in the request. Note that an Admin may set additional fields as required in your Vault.

Name	Description
schemasrequired	A JSON array of the schemas required to create this user. These may differ depending on the fields you wish to set for this user.
userNamerequired	The user name for the new user. Must be in the format name@domain.com, and the domain must match the Vault.
emailsrequired	A JSON array with the email information for a user. The array must include the following sub-attributes: value: The email address in the format name@domain.com. type:The email type, which is work. Other types are not supported. Note that the primary sub-attribute is ignored.
namerequired	A JSON object for the user’s first name (givenName) and last name (familyName).
preferredLanguagerequired	The language for the user. Value is the language abbreviation, for example, en.
localerequired	The user’s locale, in the format language_country. For example, en_US.
timezonerequired	The user’s timezone, for example, America/Los_Angeles.
securityProfilerequired	A JSON object with the user’s security profile, set with the value sub-attribute. For example, "securityProfile": { "value": "system_admin__v"}.
securityPolicyoptional	A JSON object with the user’s security policy, set with the value sub-attribute. If omitted, defaults to Basic.
licenseTypeoptional	A JSON object with the user’s license type, set with the value sub-attribute. If omitted, defaults to full__v.

Response Details

On SUCCESS, the response includes the full details of the newly created user.

Update User with SCIM

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/scim+json" \
--data-binary @"C:\Vault\Users\update_user_scim.json" \
https://veepharm.com/api/v18.2/scim/v2/Users/56798

Body

{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "AbigailSmith@veepharm.com",
    "name": {
                "familyName": "Smith",
                "givenName": "Abigail"
            },
    "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User": {
    "securityProfile": {
                    "value": "system_admin__v"
                }
  }
}

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User",
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "93521",
    "meta": {
        "created": "2018-01-09T23:07:43.000Z",
        "lastModified": "2018-05-30T22:21:18.000Z",
        "resourceType": "User",
        "location": "https://veepharm.com/api/v18.2/scim/v2/Users/93521"
    },
    "active": true,
    "displayName": "Abigail Smith",
    "emails": [
        {
            "value": "abigail.smith@veepharm.com",
            "type": "work"
        }
    ],
    "locale": "en_US",
    "name": {
        "familyName": "Smith",
        "givenName": "Abigail"
    },
    "preferredLanguage": "en",
    "timezone": "America/Los_Angeles",
    "userName": "a.smithn@veepharm.com",
    "urn:ietf:params:scim:schemas:extension:veevavault:2.0:User": {
        "createdBy": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/Users/1",
            "value": "1"
        },
        "domainAdmin": true,
        "favoriteDocNewComment": false,
        "favoriteDocNewContent": false,
        "favoriteDocNewStatus": false,
        "lastLogin": "2018-05-30T20:53:10.000Z",
        "lastModifiedBy": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/Users/61579",
            "value": "61579"
        },
        "licenseType": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/LicenseTypes/full__v",
            "value": "full__v"
        },
        "lifecycle": "vault_membership_lifecycle__sys",
        "lifecycleState": "active_state__sys",
        "productAnnouncementEmails": false,
        "securityPolicy": {
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/SecurityPolicies/2525",
            "value": "2525"
        },
        "securityProfile": {
            "value": "system_admin__v",
            "$ref": "https://veepharm.com/api/v18.2/scim/v2/SecurityProfiles/system_admin__v"
        },
        "systemAvailabilityEmails": false
    }
}

Update fields values on a single user with SCIM.

PUT /api/{version}/scim/v2/Users/{id}

Headers

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

URI Path Parameters

Name	Description
id	The id of the user you wish to update.

Body Parameters

The body of your request should be a JSON file with the information you want to update for your user. You can include any editable attribute. Invalid attributes are ignored. You can set single-valued attributes to blank using null, or an empty array [] for multi-valued attributes.

You can determine which of the core attributes are editable based on schemas. If the mutability is readWrite, the attribute is editable.

Response Details

On SUCCESS, the reponse contains the new information for the updated user.

Retrieve SCIM Resources

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/SecurityProfiles

Response

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 20,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:extension:veevavault:2.0:SecurityProfile"
            ],
            "id": "business_admin__v",
            "meta": {
                "created": "2018-02-09T09:41:14.000Z",
                "lastModified": "2018-02-09T09:41:14.000Z",
                "resourceType": "SecurityProfile",
                "location": "https://promomats-template.vaultdev.com/api/v18.2/scim/v2/SecurityProfiles/business_admin__v"
            },
            "active": true,
            "displayName": "Business Administrator"
        },
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:extension:veevavault:2.0:SecurityProfile"
            ],
            "id": "document_user__v",
            "meta": {
                "created": "2018-02-09T09:41:14.000Z",
                "lastModified": "2018-02-09T09:41:14.000Z",
                "resourceType": "SecurityProfile",
                "location": "https://promomats-template.vaultdev.com/api/v18.2/scim/v2/SecurityProfiles/document_user__v"
            },
            "active": true,
            "displayName": "Document User"
        }
    ]

}

Retrieve a single SCIM resource type. Defines the endpoints, the core schema URI which defines this resource, and any supported schema extensions.

GET /api/{version}/scim/v2/{type}

Headers

Name	Description
Accept	application/json (default) or application/scim+json

URI Path Parameters

Name	Description
type	The resource type to retrieve. You can retrieve all available types from the Retrieve All SCIM Resource Types endpoint, where the value for this parameter is the endpoint value.

Query Parameters

Name	Description
filter	Optional: Filter for a specific attribute value. Must be in the format {attribute} eq "{value}". For example, to filter for a particular user name, userName eq "john". Complex expressions are not supported, and eq is the only supported operator.
attributes	Optional: Include specified attributes only. Enter multiple values in a comma separated list. For example, to include only user name and email in the response, attributes=userName,emails. Note that the schemas and id attributes are always returned.
excludedAttributes	Optional: Exclude specific attributes from the response. Enter multiple values in a comma separated list. For example, to exclude user name and email from the response, excludedAttributes=userName,emails. Note that the schemas and id attributes are always returned and cannot be excluded.
sortBy	Optional: Specify an attribute or sub-attribute to order the response. For example, you can sort by the displayName attribute, or the name.familyName sub-attribute. If omitted, the response is sorted by id. Note that the following attributes are not supported: securityPolicy securityProfile locale preferredLanguage
sortOrder	Optional: Specify the order in which the sortBy parameter is applied. Allowed values are ascending or descending. If omitted, defaults to ascending.
count	Optional: Specify the number of query results per page, for example, 10. Negative values are treated as 0, and 0 returns no results except for totalResults. If omitted, defaults to 1000.
startIndex	Optional: Specify the index of the first result. For example, 10 would omit the first 9 results and begin on result 10. Omission, negative values, and 0 is treated as 1.

Retrieve Single SCIM Resource

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.com/api/v18.2/scim/v2/SecurityProfiles/business_admin__v

Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:extension:veevavault:2.0:SecurityProfile"
    ],
    "id": "business_admin__v",
    "meta": {
        "created": "2018-02-09T09:41:14.000Z",
        "lastModified": "2018-02-09T09:41:14.000Z",
        "resourceType": "SecurityProfile",
        "location": "https://veepharm.com/api/v18.2/scim/v2/SecurityProfiles/business_admin__v"
    },
    "active": true,
    "displayName": "Business Administrator"
}

Retrieve a single SCIM resource.

GET /api/{version}/scim/v2/{type}/{id}

Headers

Name	Description
Accept	application/json (default) or application/scim+json

URI Path Parameters

Name	Description
type	The resource type to retrieve. You can retrieve all available types from the Retrieve All SCIM Resource Types endpoint, where the value for this parameter is the endpoint value.
id	The ID of the resource to retrieve. You can retrieve all resource IDs from a particular resource type with the Retrieve SCIM Resources endpoint. For example, business_admin__v.

Query Parameters

Name	Description
attributes	Optional: Include specified attributes only. Enter multiple values in a comma separated list. For example, to include only user name and email in the response, attributes=userName,emails. Note that the schemas and id attributes are always returned.
excludedAttributes	Optional: Exclude specific attributes from the response. Enter multiple values in a comma separated list. For example, to exclude user name and email from the response, excludedAttributes=userName,emails. Note that the schemas and id attributes are always returned and cannot be excluded.

Groups

Groups are key to managing user access in Vault. A group is simply a named list of users. By defining groups which reflect the teams and roles in your company, and then assigning those groups to document roles, you can manage document access more easily and efficiently. In Vaults using Dynamic Access Control (DAC) for documents, Vault also automatically creates groups that correspond to one lifecycle role and additional document field criteria. These are called Auto Managed Groups.

Learn about Groups in Vault Help.

Retrieve Group Metadata

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "properties": [
    {
      "name": "id",
      "type": "id",
      "length": 20,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "label__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "allow_delegation_among_members__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
     },
    {
      "name": "group_description__v",
      "type": "String",
      "length": 200,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    }
  ]
}

GET /api/{version}/metadata/objects/groups

Headers

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

Retrieve All Groups

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "groups": [
    {
      "group": {
        "members__v": [
          25496,
          25513,
          25514,
          25515,
          25519,
          25524,
          25525,
          25526,
          25527,
          25528,
          25532
        ],
        "active__v": true,
        "security_profiles__v": [
          "document_user__v",
          "business_admin__v",
          "system_admin__v",
          "vault_owner__v"
        ],
        "name__v": "all_internal_users__v",
        "modified_by__v": 25524,
        "editable__v": true,
        "allow_delegation_among_members__v": true,
        "modified_date__v": "2016-03-08T21:13:49.000Z",
        "group_description__v": "All Internal Vault Users (System Provided Group)",
        "system_group__v": true,
        "label__v": "All Internal Users",
        "created_date__v": "2014-02-17T10:09:03.000Z",
        "type__v": "System Provided Group",
        "id": 1,
        "created_by__v": 1
      }
    }
  ]
}

Retrieve all groups except Auto Managed groups. You can retrieve Auto Managed groups using the Retrieve Auto Managed Groups endpoint.

GET /api/{version}/objects/groups

Headers

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

Query Parameters

Name	Description
includeImplied	Optional: When true, the response includes the implied_members__v field. These users are automatically added to the group when their security_profiles__v are added to the group. If omitted, the response includes only the members__v field. These users are individually added to a group by an Admin.

Retrieve Auto Managed Groups

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "group": {
                "members__v": [],
                "active__v": true,
                "security_profiles__v": [],
                "name__v": "msg1394917493801__c",
                "modified_by__v": 1,
                "editable__v": false,
                "allow_delegation_among_members__v": false,
                "modified_date__v": "2019-06-25T19:17:01.000Z",
                "group_description__v": "Periodic Review-Consumer (Auto Managed Group)",
                "system_group__v": false,
                "label__v": "Periodic Review-Consumer",
                "created_date__v": "2019-06-25T19:02:18.000Z",
                "type__v": "Auto Managed Group",
                "id": 1394917493801,
                "created_by__v": 1
            }
        },
        {
            "group": {
                "members__v": [
                    1003079
                ],
                "active__v": true,
                "security_profiles__v": [],
                "name__v": "msg1394917494202__c",
                "modified_by__v": 1003079,
                "editable__v": false,
                "allow_delegation_among_members__v": false,
                "modified_date__v": "2021-10-04T20:43:30.000Z",
                "group_description__v": "Periodic Review-Editor (Auto Managed Group)",
                "system_group__v": false,
                "label__v": "Periodic Review-Editor",
                "created_date__v": "2021-10-04T20:43:30.000Z",
                "type__v": "Auto Managed Group",
                "id": 1394917494202,
                "created_by__v": 1003079
            }
        },
        {
            "group": {
                "members__v": [
                    1003079
                ],
                "active__v": true,
                "security_profiles__v": [],
                "name__v": "msg1394917494201__c",
                "modified_by__v": 1003079,
                "editable__v": false,
                "allow_delegation_among_members__v": false,
                "modified_date__v": "2021-10-04T20:42:35.000Z",
                "group_description__v": "Periodic Review-Viewer (Auto Managed Group)",
                "system_group__v": false,
                "label__v": "Periodic Review-Technical Writer",
                "created_date__v": "2021-10-04T20:42:36.000Z",
                "type__v": "Auto Managed Group",
                "id": 1394917494201,
                "created_by__v": 1003079
            }
        }
    ],
    "responseDetails": {
        "offset": 0,
        "limit": 1000,
        "size": 3,
        "total": 3
    }
}

Retrieve all Auto Managed groups. Learn more about Auto Managed groups in Vault Help.

GET /api/{version}/objects/groups/auto

Headers

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

Query Parameters

Name	Description
limit	Paginate the results by specifying the maximum number of records per page in the response. This can be any value between 1 and 1000. If omitted, defaults to 1000.
offset	Paginate the results displayed per page by specifying the amount of offset from the entry returned. For example, if you are viewing the first 50 results (page 1) and want to see the next page, set this to offset=51. If omitted, defaults to 0.

Retrieve Group

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "groups": [
    {
      "group": {
        "members__v": [
          25518,
          25519,
          25520
        ],
        "active__v": true,
        "security_profiles__v": [],
        "name__v": "cholecap_editors_group__c",
        "modified_by__v": 46916,
        "editable__v": true,
        "allow_delegation_among_members__v": true,
        "modified_date__v": "2015-06-24T20:11:17.000Z",
        "group_description__v": null,
        "system_group__v": false,
        "label__v": "Cholecap Editors Group",
        "created_date__v": "2015-06-24T20:11:17.000Z",
        "type__v": "User Managed Group",
        "id": 1435176677013,
        "created_by__v": 46916
      }
    }
  ]
}

GET /api/{version}/objects/groups/{group_id}

Headers

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

URI Path Parameters

Name	Description
{group_id}	The group id field value.

Query Parameters

Name	Description
includeImplied	When true, the response includes the implied_members__v field. These users are automatically added to the group when their security_profiles__v are added to the group. When not used, the response includes only the members__v field. These users are individually added to a group by Admin.

Create Group

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "label__v=Cholecap Team US Compliance" \
-d "members__v=45501,45002" \
-d "security_profiles__v=document_user__v"
https://myvault.veevavault.com/api/v15.0/objects/groups

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Group successfully created.",
  "id": 1358979070034
}

POST /api/{version}/objects/groups

Headers

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

Body Parameters

Name	Description
label__vrequired	Enter a group label. Vault uses this to create the group name__v value.
members__voptional	Add a comma-separated list of user IDs. This manually assigns individual users to the group.
security_profiles__voptional	Add a comma-separated list of security profiles. This automatically adds all users with the security profile to the group. These are implied_members__v.
active__voptional	By default, the new group will be created as active. To set the group to inactive, set this value to false
group_description__voptional	Add a description of the group.
allow_delegation_among_members__voptional	When set to true, members of this group will only be allowed to delegate access to other members of the same group. You can set this field for user and system managed groups, with the exception of the Vault Owners group. If omitted, defaults to false. Learn more about Delegate Access

Update Group

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "label__v=Cholecap Team" \
-d "members__v=45501,45502,45503,45004" \
https://myvault.veevavault.com/api/v15.0/objects/groups/1358979070034

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Group successfully updated.",
  "id": 1358979070034
}

Update editable group field values. Add or remove group members and security profiles.

PUT /api/{version}/objects/groups/{group_id}

Headers

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

URI Path Parameters

Name	Description
{group_id}	The group id field value.

Body Parameters

In the body of the request, add any editable fields you wish to update.

Name	Description
label__voptional	Updates the label of the group.
members__voptional	Add a comma-separated list of user IDs. This manually assigns individual users to the group.
security_profiles__voptional	Add a comma-separated list of security profiles.
active__voptional	To set the group to inactive, set this value to false.
group_description__voptional	Updates the description of the group.
allow_delegation_among_members__voptional	When set to true, members of this group will only be allowed to delegate access to other members of the same group. You can set this field for user and system managed groups, with the exception of the Vault Owners group. If omitted, defaults to false. Learn more about Delegate Access

Request Details

You may change the values of any editable group field. Changing the security_profiles__v will automatically replace all previous implied users assigned via the previous security profile.

Add or Remove Users

To add or remove group members, add a comma-separated list of user IDs in members__v. This replaces all previous users who were manually assigned. This action is not additive.

Alternatively, you can add or remove group members without replacing previous users in the following ways:

• To add users, set the value of members__v to add followed by a comma-separated list of user IDs enclosed in parenthesis. For example add (userID1, userID2). This only adds the specified users to the group.

• To delete users, set the value of members__v to delete followed by a comma-separated list of user IDs enclosed in parenthesis. For example delete (userID1, userID2) This only removes the specified users from the group.

Delete Group

Request

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

Response

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

Delete a user-defined group. You cannot delete system-managed groups.

DELETE /api/{version}/objects/groups/{group_id}

Headers

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

URI Path Parameters

Name	Description
{group_id}	The group id field value.

Picklists

Picklists allow users to select a value for a field from a range of predefined options. A single picklist may contain up to 2,000 options (values). The API supports retrieving picklists and picklist values, creating and deleting picklist values, and updating picklist value labels and names. The API does not support creating, updating, or deleting the picklists themselves; this must be done in the Admin UI.

Learn about managing picklists in Vault Help.

Retrieve All Picklists

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "errorCodes": null,
  "picklists": [
    {
      "name": "asset_type__c",
      "label": "Asset Type",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__c:advertisement__c:web__c",
          "propertyName": "assetType_pm"
        },
        {
          "documentTypeName": "claim__c",
          "propertyName": "assetType_pm"
        }
      ]
    },
    {
      "name": "audience__c",
      "label": "Audience",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__c",
          "propertyName": "audience_pm"
        }
      ]
    },
    {
      "name": "branding__c",
      "label": "Branding",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__c",
          "propertyName": "brandingStatus_pm"
        }
      ]
    },
    {
      "name": "campaign_name__c",
      "label": "Campaign",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__c",
          "propertyName": "campaign_pm"
        }
      ]
    },
    {
      "name": "claim_category__c",
      "label": "Claim Category",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "claim__c",
          "propertyName": "claimCategory_pm"
        }
      ]
    },
    {
      "name": "email_template_type__v",
      "label": "Email Template Type",
      "kind": "global",
      "system": true,
      "usedIn": [
        {
          "documentTypeName": "email_template__v",
          "propertyName": "emailTemplateType_b"
        }
      ]
    },
    {
      "name": "language__v",
      "label": "Language",
      "kind": "global",
      "system": true,
      "usedIn": [
        {
          "documentTypeName": "base_document__v",
          "propertyName": "language__v"
        }
      ]
    }
  ]
  "errorType": null
}

GET /api/{version}/objects/picklists

Headers

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

Response Details

Metadata Field	Description
name	Picklist name. This is used only in the API and displayed in the Admin UI.
label	Picklist label. This is used in the API and UI. Users see the label on document and object picklist fields.
kind	There are two kinds of picklists: global picklists apply to documents and objects; user picklists apply to Vault users.
system	Indicates if the picklist is system-managed. If true, the picklist values cannot be added, edited, or removed.
usedIn	The document type or object in which the picklist is defined.
documentTypeName	For document picklists, this the document type name in which the picklist is defined.
objectName	For object picklists, this is the object name in which the picklist is defined.
propertyName	For document picklists, this is the document field name using the picklist. For object picklists, this is the object field name using the picklist.

Retrieve Picklist Values

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "picklistValues": [
    {
      "name": "full__v",
      "label": "Full User"
    },
    {
      "name": "read_only__v",
      "label": "Read-only User"
    },
    {
      "name": "external__v",
      "label": "External User"
    },
    {
      "name": "view_based__v",
      "label": "View-Based User"
    }
  ]
}

Retrieve all available values configured on a picklist.

GET /api/{version}/objects/picklists/{picklist_name}

Headers

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

URI Path Parameters

Name	Description
{picklist_name}	The picklist name field value (license_type__v, product_family__c, region__c, etc.)

Response Details

On SUCCESS, the response returns the available values on a picklist in ascending order, designated by the picklists’ order attribute. Picklist values that share the same order value are returned in the order they were configured. Retrieve the order of the picklist values with the Retrieve Component Record (XML/JSON) endpoint on the Picklist component.

The response includes the following information for each picklist value:

Name	Description
name	The picklist value name. This is used only in the API and displayed in the Admin UI.
label	The picklist value label. This is used in the API and UI. Users see the label when selecting picklist values.

Create Picklist Values

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "value_1=North America" \
-d "value_2=Central America" \
-d "value_3=South America" \
https://myvault.veevavault.com/api/v15.0/objects/picklists/regions__c

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Created picklist value(s).",
  "picklistValues": [
    {
      "name": "north_america__c",
      "label": "North America"
    },
    {
      "name": "central_america__c",
      "label": "Central America"
    },
    {
      "name": "south_america__c",
      "label": "South America"
    }
  ]
}

Add new values to a picklist. You can add up to 2,000 values to any picklist.

POST /api/{version}/objects/picklists/{picklist_name}

Headers

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

URI Path Parameters

Name	Description
{picklist_name}	The picklist name field value (license_type__v, product_family__c, region__c, etc.)

Request Details

To add new values, use value_1, value_2, etc., set to alphanumeric values. Enter each new picklist value label as they will be displayed in the UI. Vault uses the label to create the picklist value name.

Response Details

Metadata Field	Description
name	The picklist value name. This is used to reference this value in the API, and displayed to Vault Admins in the UI.
label	The picklist value label. Users see this label when selecting picklist values. Maximum 128 characters.

Update Picklist Value Label

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "north_america__c=North America/United States" \
https://myvault.veevavault.com/api/v15.0/objects/picklists/regions__c

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Updated picklist value(s).",
  "picklistValues": [
    {
      "name": "north_america__c",
      "label": "North America/United States"
    }
  ]
}

Change a picklist value label (only). To change a picklist value name, see the next section below.

Use caution when editing picklist labels or names. When these attributes are changed, they affect all existing document and object metadata that refer to the picklist. For users in the UI who are accustomed to seeing a particular selection, the changes may cause confusion. This may also break existing integrations that access picklist values via the API.

PUT /api/{version}/objects/picklists/{picklist_name}

Headers

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

URI Path Parameters

Name	Description
{picklist_name}	The picklist name field value (license_type__v, product_family__c, region__c, etc.)

Request Details

To change an existing picklist value label, use its picklist value name set to a new label. The picklist value name will remain unchanged. For example, to change the label of the existing "north_america__c=North America", enter "north_america__c=North America/United States". You may include one or more picklist values in the request.

Response Details

As shown above, only the picklist value label has changed. The picklist value name remains the same. The new label will be automatically updated on all documents and objects in which it is used. In the UI, users will see the new label when selecting values for the picklist. In the UI, Admins will see the new name in Business Admin > Picklists > {Picklist}.

Update Picklist Value

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name=north_america_united_states" \
https://myvault.veevavault.com/api/v15.0/objects/picklists/regions__c/north_america__c

Response

{
  "responseStatus": "SUCCESS"
}

Change a picklist value name or status. To change a picklist value label, see Update Picklist Value Label.

Use caution when editing picklist value names. When you change a picklist value name, it may affect existing document and object metadata that refer to the picklist. This may also break existing integrations that access picklist values via the API.

PUT /api/{version}/objects/picklists/{picklist_name}/{picklist_value_name}

Headers

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

URI Path Parameters

Name	Description
{picklist_name}	The picklist name field value (license_type__v, product_family__c, region__c, etc.)
{picklist_value_name}	The picklist value name field value (north_america__c, south_america__c, etc.)

Body Parameters

At least one of the following parameters is required:

Name	Description
nameconditional	The new name for a picklist value. This does not affect the label. Vault adds __c after processing. Special characters and double underscores __ are not allowed.
statusconditional	The new status for a picklist value. Valid values are active or inactive.

Response Details

Only the picklist value name is changed. The picklist value label remains the same. In the UI, Admins will see the new name in Business Admin > Picklists > {Picklist}.

Inactivate Picklist Value

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Deleted picklist value.",
  "name": "north_america_united_states__c"
}

Inactivate a value from a picklist. This does not affect picklist values that are already in use.

DELETE /api/{version}/objects/picklists/{picklist_name}/{picklist_value_name}

Headers

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

URI Path Parameters

Name	Description
{picklist_name}	The picklist name field value (license_type__v, product_family__c, region__c, etc.)
{picklist_value_name}	The picklist value name field value (north_america__c, south_america__c, etc.)

Expected Document Lists

Expected Document Lists (EDLs) help you to measure the completeness of projects. Learn about EDLs in Vault Help. Note that if your Vault is configured to set milestone values by EDL item, the following EDL endpoints may trigger updates to a document’s milestone fields. Learn about milestones in Vault Help.

Create a Placeholder from an EDL Item

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "edlItemIds=00EI000000000127, 0EI000000000128" \
https://myvault.veevavault.com/api/v18.2/vobjects/edl_item__v/actions/createplaceholder \

Response

{
   "responseStatus": "SUCCESS",
    "job_id": 84201,
    "url": "/api/v18.2/services/jobs/84201"
}

Create a placeholder from an EDL item. Learn about working with Content Placeholders in Vault Help.

POST /api/{version}/vobjects/edl_item__v/actions/createplaceholder

Headers

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

Body Parameters

Name	Description
edlItemIdsrequired	Comma separated list of EDL Item ids on which to initiate the action.

Response Details

On SUCCESS, the response includes the following information:

• url - The URL to retrieve the current status of the export job.
• job_id - The Job ID value is used to retrieve the status and results of the request.

Retrieve All Root Nodes

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v16.0/composites/trees/edl_hierarchy__v

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "id": "0000000000000JIT",
      "order__v": 1,
      "ref_type__v": "edl__v",
      "ref_name__v": "NewEDL",
      "url": "/vobjects/edl__v/0EL000000001901",
      "ref_id__v": "0EL000000001901",
      "parent_id__v": null
    }
  ]
}

Retrieves all root EDL nodes and node metadata. Learn more about EDL hierarchies in Vault Help.

GET /api/{version}/composites/trees/{edl_hierarchy_or_template}

Headers

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

URI Path Parameters

Name	Description
edl_hierarchy_or_template	Choose to retrieve nodes for either edl_hierarchy__v or edl_template__v.

Retrieve Specific Root Nodes

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
--header 'Content-Type: application/json' \
--data-raw '[
{
  "ref_id__v": "0EL000000000401"
}
]' \
https:myvault.veevavault.com/api/v20.2/composites/trees/edl_hierarchy__v/actions/listnodes

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": "0000000000000IR1",
            "ref_id__v": "0EL000000000401"
        }
    ]
}

Retrieves the root node ID for the given EDL record IDs.

POST /api/{version}/composites/trees/{edl_hierarchy_or_template}/actions/listnodes

Headers

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

URI Path Parameters

Name	Description
edl_hierarchy_or_template	Choose to retrieve nodes for either edl_hierarchy__v or edl_template__v.

Body Parameters

In the body of the request, include a raw JSON object with the following information:

Name	Description
ref_id__vrequired	The ID of the EDL record whose root node you’d like to retrieve. Maximum 1,000 IDs per request.

Retrieve a Node’s Children

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v16.0/composites/trees/edl_hierarchy__v/0000000000000JIT/children

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "id": "0000000000000JLL",
      "order__v": 1,
      "ref_type__v": "edl_item__v",
      "ref_name__v": "NewEDL Child",
      "url": "/vobjects/edl_item__v/0EI000000009401",
      "ref_id__v": "0EI000000009401",
      "parent_id__v": "0000000000000JIT"
    }
  ]
}

Given an EDL node ID, retrieves immediate children (not grandchildren) of that node. Learn more about EDL hierarchies in Vault Help.

GET /api/{version}/composites/trees/{edl_hierarchy_or_template}/{parent_node_id}/children

Headers

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

URI Path Parameters

Name	Description
edl_hierarchy_or_template	Choose to retrieve node children for either edl_hierarchy__v or edl_template__v.
parent_node_id	The ID of a parent node in the hierarchy.

Update Node Order

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-d '{"id": "0000000000000JLL","order__v": "2"}'
https://myvault.veevavault.com/api/v16.0/composites/trees/edl_hierarchy__v/0000000000000JIT/children

Response

{
  "responseStatus": "SUCCESS"
}

Given an EDL parent node, update the order of its children.

PUT /api/{version}/composites/trees/{edl_hierarchy_or_template}/{parent_node_id}/children

Headers

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

URI Path Parameters

Name	Description
edl_hierarchy_or_template	Choose to update node order for either edl_hierarchy__v or edl_template__v.
parent_node_id	The ID of a parent node in the hierarchy.

Body Parameters

Expressed as a JSON or a CSV.

Name	Description
idrequired	The ID of the child node to update.
order__vrequired	The new order for the node in the hierarchy, such as “1”, “2”, etc.

Add EDL Matched Documents

Request

$ curl -L -X POST -H 'Authorization: {SESSION_ID}' \
-H 'Content-Type: application/json' \
--data-raw '[
   {
       "id": "0EI000000003001",
       "document_id": "21",
       "major_version_number__v": 1,
       "minor_version_number__v": 0,
       "lock": true
   }
]'
'https://myvault.veevavault.com/api/v20.3/objects/edl_matched_documents/batch/actions/add' \

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "responseStatus": "SUCCESS",
           "id": "0EI000000003001",
           "document_id": "21",
           "major_version_number__v": "1",
           "minor_version_number__v": "0",
           "lock": "true"
       }
   ]
}

Add matched documents to EDL Items. You must have a security profile that grants the Application: EDL Matching: Edit Document Matches permission, and EDL Matched Document APIs must be enabled in your Vault. To enable this feature, contact Veeva Support.

POST /api/{version}/objects/edl_matched_documents/batch/actions/add

Headers

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

Body Parameters

Expressed as JSON or CSV.

Name	Description
idrequired	The EDL Item id to match to documents. EDL Item records and their parent records must have a status__v of active__v.
document_idrequired	The document id to match to an EDL Item.
major_version_number__voptional	The major version number of a document. You must also include minor_version_number__v to use this parameter.
minor_version_number__voptional	The minor version number of a document. You must also include major_version_number__v to use this parameter.
lockoptional	If set to true, locks the EDL Item to match a specific steady state document version or, if version numbers are omitted, the latest steady state document version. If set to false or omitted, and version numbers are omitted, Vault matches the latest version of the document without regard to state.

Response Details

On SUCCESS, the response includes a SUCCESS or FAILURE status and any applicable error messages for each EDL Item to document match in the body of your request.

Remove EDL Matched Documents

Request

curl -L -X POST -H 'Authorization: {SESSION_ID}' \
-H 'Content-Type: application/json' \
--data-raw '[
  {
      "id": "0EI000000003001",
      "document_id": "21",
      "major_version_number__v": 1,
      "minor_version_number__v": 0,
      "remove_locked": true
  },
    {
      "id": "0EI000000003001",
      "document_id": "22",
      "major_version_number__v": 0,
      "minor_version_number__v": 1,
      "remove_locked": true
  }
]'
'https://myvault.veevavault.com/api/v20.3/objects/edl_matched_documents/batch/actions/remove' \

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "responseStatus": "FAILURE",
           "errors": [
               {
                   "type": "INVALID_DATA",
                   "message": "Can not remove an automatically matched Document"
               }
           ],
           "id": "0EI000000003001",
           "document_id": "22",
           "major_version_number__v": "0",
           "minor_version_number__v": "1",
           "lock": "true"
       },
       {
           "responseStatus": "SUCCESS",
           "id": "0EI000000003001",
           "document_id": "21",
           "major_version_number__v": "1",
           "minor_version_number__v": "0",
           "lock": "true"
       }
   ]
}

Remove manually matched documents from EDL Items. You must have a security profile that grants the Application: EDL Matching: Edit Document Matches permission, and EDL Matched Document APIs must be enabled in your Vault. To enable this feature, contact Veeva Support.

POST /api/{version}/objects/edl_matched_documents/batch/actions/remove

Headers

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

Body Parameters

Expressed as JSON or CSV.

Name	Description
idrequired	The EDL Item id to match to documents. EDL Item records and their parent records must have a status__v of active__v.
document_idrequired	The document id to match to an EDL Item.
major_version_number__voptional	The major version number of a document. You must also include minor_version_number__v to use this parameter.
minor_version_number__voptional	The minor version number of a document. You must also include major_version_number__v to use this parameter.
remove_lockedoptional	If set to true, removes a matched document from the EDL Item even if the EDL Item is locked to a specific steady state document version.

Response Details

On SUCCESS, the response includes a SUCCESS or FAILURE status and any applicable error messages for each matched document to remove from an EDL Item in the body of your request.

Security Policies

Vault security policies allow you to create and manage password policies for users. These settings control password requirements, expiration period, reuse policy, security question policy, and delegated authentication via Salesforce.com™. Security policies apply across all Vaults in a multi-Vault domain.

Learn more about security policies in Vault Help.

Retrieve Security Policy Metadata

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "responseMessage": "Success",
   "metadata": {
       "name": "security_policy",
       "description": "Security Policy",
       "properties": [
           {
               "name": "policy_details__v",
               "type": [
                   "CompleteObject"
               ],
               "description": "Details",
               "objectTypeReferenced": [
                   {
                       "type": "policy_details"
                   }
               ]
           },
           {
               "name": "policy_security_settings__v",
               "type": [
                   "CompleteObject"
               ],
               "description": "Security Settings",
               "objectTypeReferenced": [
                   {
                       "type": "policy_security_settings"
                   }
               ]
           }
       ],
       "objects": [
           {
               "name": "policy_details",
               "description": "Details",
               "properties": [
                   {
                       "name": "name__v",
                       "type": [
                           "string"
                       ],
                       "description": "Public Key"
                   },
                   {
                       "name": "label__v",
                       "type": [
                           "string"
                       ],
                       "description": "Policy Name",
                       "required": true,
                       "maxValue": 60,
                       "minValue": 1,
                       "editable": true,
                       "onCreateEditable": true
                   }
               ]
           },
           {
               "name": "policy_security_settings",
               "description": "Security Policy",
               "properties": [
                   {
                       "name": "authentication_type__v",
                       "type": [
                           "SummaryObject"
                       ],
                       "description": "Authentication Type",
                       "required": true,
                       "editable": true,
                       "onCreateEditable": true
                   },
                   {
                       "name": "passwords_require_number__v",
                       "type": [
                           "boolean"
                       ],
                       "description": "Passwords require a number",
                       "required": true,
                       "editable": true,
                       "onCreateEditable": true
                   },
                   {
                       "name": "passwords_require_uppercase_letter__v",
                       "type": [
                           "boolean"
                       ],
                       "description": "Passwords require an upper-case letter",
                       "required": true,
                       "editable": true,
                       "onCreateEditable": true
                   }
               ]
           }
       ]
   }
}

Retrieve the metadata associated with the security policy object.

GET /api/{version}/metadata/objects/securitypolicies

Headers

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

Retrieve All Security Policies

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "security_policies__v": [
    {
      "name__v": "821",
      "label__v": "Basic",
      "value__v": "https://myvault.veevavault.com/api/v15.0/objects/securitypolicies/821"
    },
    {
      "name__v": "958",
      "label__v": "Default",
      "value__v": "https://myvault.veevavault.com/api/v15.0/objects/securitypolicies/958"
    },
    {
      "name__v": "957",
      "label__v": "High Security",
      "value__v": "https://myvault.veevavault.com/api/v15.0/objects/securitypolicies/957"
    },
    {
      "name__v": "1909",
      "label__v": "Single Sign-on Okta",
      "value__v": "https://myvault.veevavault.com/api/v15.0/objects/securitypolicies/1909"
    }
  ]
}

GET /api/{version}/objects/securitypolicies

Headers

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

Response Details

The response lists all security_policies__v in the Vault:

Name	Description
name__v	System-managed value automatically assigned to security policies. This is typically a numeric value.
label__v	Security policy label displayed in Admin UI.
value__v	URL value to retrieve security policy metadata.

Retrieve Security Policy

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "security_policy__v": {
    "policy_details__v": {
      "name__v": "958",
      "label__v": "Default",
      "is_active__v": true
    },
    "policy_security_settings__v": {
      "authentication_type__v": {
        "name__v": "Password",
        "label__v": "Password"
      },
      "passwords_require_number__v": true,
      "passwords_require_uppercase_letter__v": true,
      "min_password_length__v": 8,
      "password_expiration__v": 0,
      "password_history_reuse__v": 0
    }
  }
}

GET /api/{version}/objects/securitypolicies/{security_policy_name}

Headers

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

URI Path Parameters

Name	Description
{security_policy_name}	Security policy name__v field value (retrieved from previous request). This is typically a numeric value.

Response Details

Depending on the configuration, the response may include some or all of the following security_policy__v fields:

Name	Description
policy_details__v	Policy Details
name__v	Security Policy ID
label__v	Security Policy Label
description__v	Security Policy Description
is_active__v	Active (true/false)
policy_security_settings__v	Policy Security Settings
authentication_type__v	Authentication Type
name__v	Authentication Type Name
label__v	Authentication Type Label
passwords_require_number__v	Passwords Require Number (true/false)
passwords_require_uppercase_letter__v	Passwords Require Upper-Case Letter (true/false)
passwords_require_nonalpha_char__v	Passwords Require Non-Alphanumeric Character (true/false)
min_password_length__v	Minimum Password Length (7, 8, 10, or 12 characters)
password_expiration__v	Password Expiration (90 days, 180 days, or no expiration)
password_history_reuse__v	Password History Reuse (prevent reuse of the last 3 passwords, 5 passwords, or no limitations)
require_question_on_password_reset__v	Require Security Question on Password Reset (true/false)
allow_delegated_auth_sfdc__v	Allow Salesforce™ Delegated Authentication (true/false)
sfdc_org_id__v	Salesforce™ Org ID

Note: Boolean fields are only returned when the value is set to true.

Configuration Migration

The following endpoints allow you to export, import, validate, and deploy Vault Packages (VPKs). These packages allow you to migrate configuration changes between two Vaults. Learn more about Configuration Migration in Vault Help.

Export Package

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "packageName=PKG-0001" \
--output "myVPK.vpk" \
https://myvault.veevavault.com/api/v18.2/services/package

Response

{
    "responseStatus": "SUCCESS",
    "url": "/api/v18.2/services/jobs/60905",
    "job_id": 60905
}

POST /api/{version}/services/package

Headers

Name	Description
Content-Type	application/x-www-form-urlencoded

Body Parameters

Name	Description
packageNamerequired	The name of the Outbound Package you would like to export.

Response Details

On SUCCESS, the response includes the following information:

• url - The URL to retrieve the current status of the export job.
• job_id - The Job ID value is used to retrieve the status and results of the request.
• A separate email with a link to download the .vpk file.

Import Package

Request

$ curl -L -X PUT -H 'Authorization: {Session_ID}' \
-H 'Accept: application/json' \
-F 'file=myFile.vpk'\
https://myvault.veevavault.com/api/v20.2/services/package

Response

{
    "responseStatus": "SUCCESS",
    "url": "/api/v20.2/services/jobs/88717",
    "job_id": 88717
}

Asynchronously import and validate a VPK package attached to this request. On completion, Vault sends an email notification which includes a link to the validation log. For packages that include Vault Java SDK code, this checks code compilation and restrictions in use of the JDK. For example, new is not allowed for non-allowlisted classes. Learn more about Vault Java SDK limits and restrictions.

PUT /api/{version}/services/package

Headers

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

Body Parameters

Name	Description
filerequired	The .vpk file. See Export Package above.

Response Details

On SUCCESS, the response includes the following information: url - The URL to retrieve the current status of the import job. job_id - The Job ID value is used to retrieve the status and results of the request. A separate email with a link to download the validation log.

Deploy Package

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://myvault.veevavault.com/api/v16.0/vobject/vault_package__v/0PI000000000101/actions/deploy

Response

{
  "responseStatus": "SUCCESS",
  "url": "/api/v16.0/services/jobs/23301",
  "job_id": 23301
}

POST /api/{version}/vobject/vault_package__v/{package_id}/actions/deploy

Headers

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

URI Path Parameters

Name	Description
package_id	The id field value of the vault_package__v object record used for deployment. See Import Package.

Response Details

On SUCCESS, the response includes the following information:

• url - The URL to retrieve the current status of the export job.
• job_id - The Job ID value is used to retrieve the status and results of the request.

Retrieve Package Deploy Results

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v20.1/vobject/vault_package__v/0PI000000000101/actions/deploy/results

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total_steps": 1,
        "deployed": 1,
        "deployed_with_warnings": 0,
        "deployed_with_failures": 1,
        "deployed_with_error": 0,
        "failed": 0,
        "skipped": 0,
        "package_status__v": "deployed_with_failures__v",
        "deployment_log": [
            {
                "filename": "PKG-0002-Validation.log",
                "url": "https://myvault.veevavault.com/api/v25.1/vobjects/vault_package__v/0PI000000000101/attachments/1208/versions/1/file",
                "created_date__v": "2024-12-04 14:50:17.699"
            },
            {
                "filename": "PKG-0002-Deployment.log",
                "url": "https://myvault.veevavault.com/api/v25.1/vobjects/vault_package__v/0PI000000000101/attachments/1305/versions/1/file",
                "created_date__v": "2024-12-04 14:52:02.149"
            }
        ],
        "data_deployment_log": [
            {
                "filename": "19523_PKG-0002_2024-12-04_14_52_02_Success_Failure_logs.zip",
                "url": "https://myvault.veevavault.com/api/v25.1/services/package/actions/deploy/data_results/966404/19523_PKG-0002_2024-12-04_14_52_02_Success_Failure_logs.zip"
            }
        ]
    },
    "package_steps": [
        {
            "id": "0IS00000000E011",
            "name__v": "00010",
            "step_type__v": "Data",
            "step_name__v": "product__v",
            "type__v": "Object",
            "deployment_status__v": "deployed_with_failures__v",
            "step_label__v": "DSET-00002-product__v",
            "package_components": [],
            "package_data": [
                {
                    "id": "0PT000000003001",
                    "name__v": "DSET-00002-product__v",
                    "object__v": "product__v",
                    "data_type__v": "Object",
                    "data_action__v": "Create",
                    "record_migration_mode__sys": false,
                    "record_count__sys": "21",
                    "checksum__v": "28cebd01b7b76ccd6bac382f614c8827"
                }
            ],
            "package_code": []
        }
    ]
}

After Vault has finished processing the deploy job, use this request to retrieve the results of the completed deployment.

GET /api/{version}/vobject/vault_package__v/{package_id}/actions/deploy/results

Headers

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

URI Path Parameters

Name	Description
package_id	The id field value of the vault_package__v object record used for deployment. See Deploy Package.

Response Details

The deployment_log provides a URL to download the latest version of the deployment log. If the deployed package includes datasets, the response also provides the data_deployment_log with a URL to download the data deployment log.

Learn more about the possible response values for deployment_status__v in Vault Help.

Retrieve Outbound Package Dependencies

Request: Retrieve Dependencies

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v22.2/vobjects/outbound_package__v/0PO000000001001/dependencies

Response: Retrieve Dependencies

{
  "responseStatus": "SUCCESS",
   "responseDetails": {
       "total_dependencies": 1,
       "target_vault_id": 1000486,
       "package_name": "PKG-0001",
       "package_id": "0PO000000001001",
       "package_summary": "Outbound Package",
       "package_description": "Package for deployment",
       "url": "https://myvault.veevavault.com/api/v22.2/vobjects/package_component__v"
   },
   "package_dependencies": [
       {
           "id": "0CD000000000M70",
           "name__v": "Product Label",
           "component_name__v": "product_label__c",
           "component_type__v": "Object",
           "referenced_component_name": "product__v",
           "referenced_component_type": "Object"
        }
    ]
}

Request: Add Dependencies

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v22.2/vobjects/package_component__v

Example JSON Request Body: Add Dependencies

[
   {
       "outbound_package__v": "0PO000000001001",
       "vault_component__v": "0CD000000002810"
   }
]

Outbound packages only include configuration details for the included components. Sometimes, a configuration for one component depends on another component which you may not have explicitly specified.

With this API, you can retrieve all outstanding component dependencies for an outbound package. You can then add these missing dependencies to the package with the Create Object Records API.

GET /api/{version}/vobjects/outbound_package__v/{package_id}/dependencies

Headers

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

URI Path Parameters

Name	Description
{package_id}	The ID of the outbound_package__v record from which to retrieve dependencies.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
total_dependencies	The total number of outstanding component dependencies.
target_vault_id	The ID of the target Vault for the outbound package.
package_name	The name__v value of the outbound package.
package_id	The ID of the outbound_package__v record with these outstanding dependencies.
url	The Vault REST API request to add missing dependencies to this outbound package. Learn more about adding dependencies.
package_dependencies	This array contains information about each of the total_dependencies. If there are no outstanding dependencies, this array is not returned.

Adding Dependencies

From the url in the response, you can add missing dependencies using the Create Object Records API with the following body parameters:

Name	Description
outbound_package__v	The ID of the outbound_package__v record with these outstanding dependencies. In the retrieve dependencies response body, this is the package_id value.
vault_component__v	The ID of the component to add. This is the value returned for the dependency in the array. In the retrieve dependencies response body, this is the id value of the component within the package_dependencies array.

Vault Compare

Request

Curl -X POST -H "Authorization: {SESSION_ID}" \
- H "Content-Type: application/x-www-form-urlencoded" \
- d "vault_id=1234" \
- d "results_type=Complete" \
https://myveevavault.com/api/v17.2/objects/vault/actions/compare

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 16202,
  "url": "/api/v17.2/services/jobs/16202"
}

Compare the configuration of two different Vaults. The Vault you make the request in is the source Vault, and the target Vault for the comparison is listed in the body. Learn more about Vault Compare in Vault Help.

The user who makes the request must be a cross-domain user and must have access to the vault_component__v in both Vaults. Learn more about cross-domain users in Vault Help.

POST /api/{version}/objects/vault/actions/compare

Headers

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

Body Parameters

Name	Description
vault_idrequired	The target Vault id for the comparison.
results_typeoptional	To include all configuration values, set this to complete. To only see the differences between Vaults, set to differences. If omitted, this defaults to differences.
details_typeoptional	To show component level details only, set to none. To include simple attribute-level details, set to simple. To show all attribute-level details, set to complex. If omitted, this defaults to simple.
include_doc_binder_templatesoptional	To exclude Document and Binder Templates for comparison, set to false. If omitted, this defaults to true and templates are included.
include_vault_settingsoptional	To exclude Vault Settings for comparison, set to false. If omitted, this defaults to true and Vault Settings are included.
component_typesoptional	Add a comma separated list of component types to include. For example, Doclifecycle, Doctype, Workflow. To exclude all component types, set to none. If omitted, this defaults to include all components.
generate_outbound_packagesoptional	If set to true, Vault automatically generates an Outbound Package based on differences between the source Vault and target Vault. If omitted, the default value is false.

Response Details

On SUCCESS, the response includes the url and job_id of the new Comparison Report job. You can use these to find the Job Status, and using the links from the job status response, download your report. The download is an Excel™ file. If Vault encounters any MDL component or configuration issues, the job status response also includes a link to download an error log as a CSV file. The authenticated user will also receive an in-app notification with these download links. If there are pending component updates, Vault places the report request in a queue and sends you a notification. Once component update processing is complete, Vault generates the report and sends another notification.

Vault Configuration Report

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
- H "Content-Type: application/x-www-form-urlencoded" \
- d "include_components_modified_since=2017-01-01" \
https://myveevavault.com/api/v17.3/objects/vault/actions/configreport

Response

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

Generate an Excel™ report containing configuration information for a Vault. Users must have the Vault Configuration Report permission to use this API.

POST /api/{version}/objects/vault/actions/configreport

Headers

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

Body Parameters

Name	Description
include_vault_settingsoptional	To exclude Vault Settings for comparison, set to false. If omitted, this defaults to true and Vault Settings are included.
include_inactive_componentsoptional	If set to true, inactive components and subcomponents are included in the report. If omitted, defaults to false and only active components and subcomponents are included. See details for inactive workflows.
include_components_modified_sinceoptional	Only include components modified since the specified date. Provide the date in the format yyyy-mm-dd. If omitted, includes all components. This option is not available for subcomponents.
include_doc_binder_templatesoptional	To exclude document and binder templates, set to false. If omitted, this defaults to true and document and binder templates are included.
suppress_empty_resultsoptional	If set to true, Vault excludes tabs with only header rows from the report.
component_typesoptional	Add a comma-separated list of component types to include. For example, Doclifecycle,Doctype,Workflow. If omitted, this defaults to include all components and Vault includes an Excel™ object data report in the ZIP file output.
output_formatoptional	Output report as either an Excel (XSLX) or Excel_Macro_Enabled (XLSM) file. If omitted, defaults to Excel_Macro_Enabled.

Inactive Document Workflows

Vault ignores the setting include_inactive_components for document workflows. If a workflow was active, but is currently in “editing” state, the report shows the latest active version of it. If a workflow has never been active, the report does not include it.

Inactive Object Workflows

Vault respects the include_inactive_components setting for object workflows. If set to true, the report includes all inactive workflows, including those that have never been active. If set to false, the report does not include any workflows that are currently in “editing” state, including those that have an active version.

Response Details

On SUCCESS, the response includes the url and job_id of the new Configuration Report job. You can use these to find the Job Status, and using the link from the job status response, download your report. The download is a ZIP file. If Vault encounters any MDL component or configuration issues, the job status response also includes a link to download an error log as a CSV file. The authenticated user will also receive an in-app notification with these download links. If there are pending component updates, Vault places the report request in a queue and sends you a notification. Once component update processing is complete, Vault generates the report and sends another notification.

Component Modified Date values in the report only refer to component-level modifications and do not reflect modifications to subcomponents. For example, modifying an object field does not change the Component Modified Date value for an object, but modifying the object label does. See the Component Type referenece for more information about components and their subcomponents.

Validate Package

Request

$ curl -L -X POST  -H 'Authorization: {Session_ID}' \
-H 'Accept: application/json' \
-F 'file=myFile.vpk' \
https://myvault.veevavault.com/api/v20.2/services/package/actions/validate

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "summary": "Auto Claims Linking Config",
        "author": "jennie@veepharm.com",
        "package_name": "PKG-0004-2",
        "package_id": "N/A",
        "source_vault": "51577",
        "package_status": "Blocked",
        "total_steps": 2,
        "total_steps_blocked": 1,
        "start_time": "07:05:2020 06:24:15",
        "end_time": "07:05:2020 06:24:15",
        "package_error": "",
        "package_steps": [
            {
                "name__v": "00010",
                "step_type__v": "Component",
                "step_label__v": "Claim Targets",
                "step_name__v": "annotation_keyword_targets__sys",
                "type__v": "Object",
                "deployment_status__v": "Verified",
                "deployment_action": "Update",
                "dependencies": [
                    {
                        "component_name": "annotation_keyword_targets__sys.base__v",
                        "component_type": "Objecttype",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    },
                    {
                        "component_name": "default_status__v",
                        "component_type": "Picklist",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    }
                ]
            },
            {
                "name__v": "00020",
                "step_type__v": "Component",
                "step_label__v": "Claims Document",
                "step_name__v": "claims_document__c",
                "type__v": "Doctype",
                "deployment_status__v": "Blocked",
                "deployment_action": "Add (missing in Vault)",
                "dependencies": [
                    {
                        "component_name": "document_creation_date__v",
                        "component_type": "Docfield",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    },
                    {
                        "component_name": "reference_documents__c",
                        "component_type": "Doclifecycle",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    },
                    {
                        "component_name": "product__v",
                        "component_type": "Docfield",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    },
                    {
                        "component_name": "air_bulk_03__c",
                        "component_type": "Renditiontype",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "Missing - Block"
                    },
                    {
                        "component_name": "country__v",
                        "component_type": "Docfield",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    }
                ]
            }
        ]
    }
}

Validate a VPK package attached to this request. The validation response will include the same information on dependent components as validation logs generated through the UI. For packages that include Vault Java SDK code, this checks checks code compilation and restrictions in use of the JDK. For example, new is not allowed for non-allowlisted classes. Learn more about Vault Java SDK limits and restrictions.

This endpoint does not import your package.

POST /api/{version}/services/package/actions/validate

Headers

Name	Description
Accept	application/json (default)

Body Parameters

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

Validate Inbound Package

Request

 $ curl -L -X POST -H 'Authorization: {Session_ID}' \
-H 'Accept: application/json' \
https://myvault.veevavault.com/api/v20.2/services/vobject/vault_package__v/0PI000000000301/actions/validate

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "summary": "Auto Claims Linking Config",
        "author": "jennie@veepharm.com",
        "package_name": "PKG-0004-1",
        "package_id": "0PI000000000301",
        "source_vault": "51577",
        "package_status": "Blocked",
        "total_steps": 2,
        "total_component_steps_blocked": 1,
        "start_time": "07:05:2020 06:29:25",
        "end_time": "07:05:2020 06:29:26",
        "package_error": "",
        "package_steps": [
            {
                "id": "0IS000000000301",
                "name__v": "00010",
                "step_type__v": "Component",
                "step_label__v": "Claim Targets",
                "step_name__v": "annotation_keyword_targets__sys",
                "type__v": "Object",
                "deployment_status__v": "Verified",
                "deployment_action": "Update",
                "dependencies": [
                    {
                        "component_name": "annotation_keyword_targets__sys.base__v",
                        "component_type": "Objecttype",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    },
                    {
                        "component_name": "default_status__v",
                        "component_type": "Picklist",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    }
                ]
            },
            {
                "id": "0IS000000000302",
                "name__v": "00020",
                "step_type__v": "Component",
                "step_label__v": "Claims Document",
                "step_name__v": "claims_document__c",
                "type__v": "Doctype",
                "deployment_status__v": "Blocked",
                "deployment_action": "Add (missing in Vault)",
                "dependencies": [
                    {
                        "component_name": "document_creation_date__v",
                        "component_type": "Docfield",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    },
                    {
                        "component_name": "reference_documents__c",
                        "component_type": "Doclifecycle",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    },
                    {
                        "component_name": "product__v",
                        "component_type": "Docfield",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    },
                    {
                        "component_name": "air_bulk_03__c",
                        "component_type": "Renditiontype",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "Missing - Block"
                    },
                    {
                        "component_name": "country__v",
                        "component_type": "Docfield",
                        "subcomponent_name": "",
                        "subcomponent_type": "",
                        "status": "In Target"
                    }
                ]
            }
        ]
    }
}

Validate an imported VPK package before deploying it to your Vault. The validation response includes information on dependent components and whether they exist in the package or in your Vault. You can then add missing dependencies to the package in the source Vault before re-importing and deploying it to your target Vault. Learn more about validation logs in Vault Help.

POST /api/{version}/services/vobject/vault_package__v/{package_id}/actions/validate

Headers

Name	Description
Accept	application/json(default)

URI Path Parameters

Name	Description
package_id	The id field value of the vault_package__v object record to validate.

Enable Configuration Mode

Request

$ curl -X POST -H 'Authorization: {Session_ID}' \
-H 'Accept: application/json' \
https://myvault.veevavault.com/api/v24.3/services/configuration_mode/actions/enable

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Configuration Mode Active enabled."
}

Enable Configuration Mode in the currently authenticated Vault. When enabled, Configuration Mode locks non-Admin users out of the Vault. Vault Owners and System Admins can still access the Vault to deploy configuration migration packages or set up Dynamic Access Control (DAC).

Users with access to multiple Vaults can log in if at least one (1) Vault in the domain is not in Configuration Mode.

Learn more about Configuration Mode in Vault Help.

POST /api/{version}/services/configuration_mode/actions/enable

Headers

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

Response Details

On SUCCESS, this endpoint enables Configuration Mode in the currently authenticated Vault, terminates sessions for any non-Admin users currently logged in, and prevents other non-Admin users from logging in. Sessions can take up to five (5) minutes to terminate for users accessing the Vault UI and up to 15 minutes for users accessing the API.

Disable Configuration Mode

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H 'Accept: application/json' \
https://myvault.veevavault.com/api/v24.3/services/configuration_mode/actions/disable

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Configuration Mode Active disabled."
}

Disable Configuration Mode in the currently authenticated Vault. When you disable Configuration Mode, non-Admin users can now access the Vault.

Learn more about Configuration Mode in Vault Help.

POST /api/{version}/services/configuration_mode/actions/disable

Headers

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

Response Details

On SUCCESS, this endpoint disables Configuration Mode in the currently authenticated Vault. Vault allows non-Admin users to log back in.

Sandbox Vaults

Sandbox Vaults provide environments for testing, including development, UAT, and validation testing. Learn more about sandbox Vaults in Vault Help.

Retrieve Sandboxes

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "entitlements": [
            {
                "size": "Small",
                "available": 3,
                "allowed": 4,
                "temporary": 0
            },
            {
                "size": "Large",
                "available": 2,
                "allowed": 2,
                "temporary": 0
            },
            {
                "size": "Full",
                "available": 0,
                "allowed": 1,
                "temporary": 0
            }
        ],
        "active": [
            {
                "pod": "DS0",
                "vault_id": 1001054,
                "name": "Testing Sandbox",
                "type": "config",
                "size": "Full",
                "status": "active",
                "domain": "veepharm.com",
                "dns": "myvault.veevavault.com",
                "source_vault_id": 1000660,
                "refresh_available": "2022-12-03T18:25:51.000Z",
                "created_date": "2022-12-02T18:25:51.000Z",
                "created_by": 1,
                "modified_date": "2023-11-01T01:44:40.000Z",
                "modified_by": 1,
                "entitlements": [],
                "release": "limited",
                "expiration_date": "NULL"
            },
            {
                "pod": "DS0",
                "vault_id": 1001074,
                "name": "VeePharm Sandbox",
                "type": "config",
                "size": "Small",
                "status": "active",
                "domain": "veepharm.com",
                "dns": "veepharm-veepharm-sandbox.vaultdev.com",
                "source_vault_id": 1000660,
                "refresh_available": "2022-12-09T16:56:15.000Z",
                "created_date": "2022-12-09T16:56:15.000Z",
                "created_by": 1,
                "modified_date": "2023-11-01T01:44:45.000Z",
                "modified_by": 1,
                "entitlements": [],
                "release": "limited",
                "expiration_date": "NULL"
            }
        ]
    }
}

Retrieve information about the sandbox Vaults for the authenticated Vault.

GET /api/{version}/objects/sandbox

Headers

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

Response Details

The response contains information about the sandbox Vaults for the authenticated Vault.

Name	Description
pod	The name of the POD the sandbox is on.
vault_id	The sandbox ID number.
name	The name of the sandbox.
type	The type of sandbox, such as configuration (config).
size	The size of the sandbox: Small, Medium, Large, Very Large, Extra Large, or Full. Learn more about sandbox sizes and their limits in Vault Help.
status	The current status of the sandbox: building: A new or recently refreshed sandbox active: Sandbox is accessible inactive: Sandbox is not accessible deleting: Sandbox is being deleted
domain	The sandbox domain.
dns	The sandbox domain name.
source_vault_id	The Vault ID of the sandbox’s parent Vault.
refresh_available	The date and time when this sandbox can be refreshed. You can refresh a sandbox once every 24 hours.
release	The type of release. This can be general, limited, or prerelease. Learn more about Vault releases in Vault Help.
entitlements	The sandbox entitlements, including type, availability, and allowed information. The temporary entitlement shows only when a temporary entitlement is active.
expiration_date	The expiration date of the sandbox Vault. May be NULL if the sandbox never expires. Learn more about sandbox expiration in Vault Help.

Retrieve Sandbox Details by ID

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "pod": "DS0",
        "vault_id": 1001074,
        "name": "VeePharm Sandbox",
        "type": "config",
        "size": "Small",
        "status": "active",
        "domain": "veepharm.com",
        "dns": "veepharm-veepharm-sandbox.vaultdev.com",
        "source_vault_id": 1000660,
        "refresh_available": "2022-12-09T16:56:15.000Z",
        "created_date": "2022-12-09T16:56:15.000Z",
        "created_by": 1,
        "modified_date": "2023-11-01T01:44:45.000Z",
        "modified_by": 1,
        "limits": [
            {
                "name": "total_object_records",
                "used": "43",
                "allowed": "100000"
            },
            {
                "name": "document_versions",
                "used": "1",
                "allowed": "10000"
            }
        ],
        "entitlements": [],
        "release": "limited",
        "expiration_date": "NULL"
    }
}

Retrieve information about the sandbox for the given Vault ID.

GET /api/{version}/objects/sandbox/{vault_id}

Headers

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

URI Path Parameters

Name	Description
vault_id	The Vault ID of the sandbox.

Response Details

The response contains information about the sandbox Vaults for the authenticated Vault.

Name	Description
pod	The name of the POD the sandbox is on.
vault_id	The sandbox ID number.
name	The name of the sandbox.
type	The type of sandbox, such as configuration (config).
size	The size of the sandbox: Small, Medium, Large, Very Large, Extra Large, or Full. Learn more about sandbox sizes and their limits in Vault Help.
status	The current status of the sandbox: building: A new or recently refreshed sandbox active: Sandbox is accessible inactive: Sandbox is not accessible deleting: Sandbox is being deleted
domain	The sandbox domain.
dns	The sandbox domain name.
source_vault_id	The Vault ID of the sandbox’s parent Vault.
refresh_available	The date and time when this sandbox can be refreshed. You can refresh a sandbox once every 24 hours.
limits	Sandbox limits, such as total_object_records. Note that sandbox usage is updated once every 24 hours, and new/recently refreshed sandboxes initially show 0 usage.
entitlements	The sandbox entitlements, including type, availability, and allowed information. The temporary entitlement shows only when a temporary entitlement is active.
release	The type of release. This can be general, limited, or prerelease. Learn more about Vault releases in Vault Help.
expiration_date	The expiration date of the sandbox Vault. May be NULL if the sandbox never expires. Learn more about sandbox expiration in Vault Help.

Recheck Sandbox Usage Limit

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://myvault.veevavault.com/api/v22.3/objects/sandbox/actions/recheckusage

Response

{
    "responseStatus": "SUCCESS"
}

Recalculate the usage values of the sandbox Vaults for the authenticated Vault. This action can be initiated up to three (3) times in a 24-hour period. In the UI, this information is available in Admin > Settings. Learn more about viewing usage details in Vault Help.

POST /api/{version}/objects/sandbox/actions/recheckusage

Headers

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

Change Sandbox Size

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-d "[
{
    “name”: “SandboxA”,
    “size”: “Full”
}
]” \
https://myvault.veevavault.com/api/v22.3/objects/sandbox/batch/changesize

Response

{
   "responseStatus": "SUCCESS",
   "responseMessage": null,
   "errorCodes": null,
   "errorType": null
}

Change the size of a sandbox Vault for the authenticated Vault. You can initiate this action if there are sufficient allowances and the current sandbox meets the data and user limits of the requested size. Learn more about sandbox sizes in Vault Help.

POST /api/{version}/objects/sandbox/batch/changesize

Headers

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

Body Parameters

In the body of the request, include a raw JSON object with the following information:

Name	Description
namerequired	The name of the sandbox Vault.
sizerequired	The requested size of the sandbox: Small, Medium, Large, Very Large, Extra Large, or Full. Learn more about sandbox sizes and their limits in Vault Help.

Response Details

On SUCCESS, the response includes the responseStatus and lists any errors encountered.

Set Sandbox Entitlements

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
'https://myvault.veevavault.com/api/v20.3/objects/sandbox/entitlements/set' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'name=VeePharm Sandbox' \
-d 'size=Small' \
-d 'allowance=1' \
-d 'grant=true'

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "entitlements": [
            {
                "size": "Small",
                "available": 2,
                "allowed": 4,
                "temporary": 0
            },
            {
                "size": "Large",
                "available": 2,
                "allowed": 2,
                "temporary": 0
            },
            {
                "size": "Full",
                "available": 0,
                "allowed": 1,
                "temporary": 0
            }
        ]
    }
}

Set new sandbox entitlements, including granting and revoking allowances, for the given sandbox name.

POST /api/{version}/objects/sandbox/entitlements/set

Headers

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

Body Parameters

Name	Description
namerequired	The name of the sandbox Vault, which appears on the My Vaults page. Providing a new name creates a new sandbox, whereas providing an existing name refreshes the existing sandbox. How often you can refresh a Vault depends on its size. Learn more about refreshing sandboxes in Vault Help.
sizerequired	The size of the sandbox: Small, Medium, Large, Very Large, Extra Large, or Full. Learn more about sandbox sizes and their limits in Vault Help.
allowancerequired	The number of entitlements to grant or revoke.
grantrequired	Allowed values true and false. True grants allowances and false revokes them.
temporary_allowanceoptional	The number of temporary sandbox allowances to grant or revoke.

Create or Refresh Sandbox

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "type=config" \
-d "size=Small" \
-d "domain=veepharm.com" \
-d "name=Sandbox" \
https://myvault.veevavault.com/api/v18.2/objects/sandbox

Response

{
    "responseStatus": "SUCCESS",
    "job_id": 70701,
    "url": "/api/v18.2/services/jobs/70701"
}

Create a new sandbox for the currently authenticated Vault. Include the source_snapshot parameter in the request body to create a new sandbox from an existing snapshot.

Providing a name which already exists will refresh the existing sandbox Vault. You can also refresh a sandbox from a snapshot.

POST /api/{version}/objects/sandbox

Headers

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

Body Parameters

Name	Description
sourceoptional	The source to refresh the sandbox from: vault snapshot
source_snapshotoptional	If the source is a snapshot, provide the api_name of the snapshot to create the sandbox from. You can obtain the api_name using the Retrieve Sandbox Snapshots request.
typeoptional	The type of sandbox, such as config.
sizerequired	The size of the sandbox: Small, Medium, Large, Very Large, Extra Large, or Full. Learn more about sandbox sizes and their limits in Vault Help.
domainrequired	The domain to use for the new sandbox. Must be a valid domain. You can retrieve valid domains from the Retrieve Domains endpoint. Only domains of type: Sandbox are allowed. Must be lower-case, and must include the domain extension.
namerequired	The name of the sandbox Vault, which appears on the My Vaults page. Providing a new name creates a new sandbox, whereas providing an existing name refreshes the existing sandbox. How often you can refresh a Vault depends on its size. Learn more about refreshing sandboxes in Vault Help.
add_requesteroptional	This boolean field adds the currently authenticated user as a Vault Owner in the new sandbox. If set to false, the Domain Admin users in the sandbox domain will become Vault Owners in the sandbox Vault. If omitted, defaults to true.
releaseoptional	The type of release. This can be general, limited, or prerelease. If omitted, defaults to the release level of the source Vault. Learn more about Vault releases in Vault Help.

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 the sandbox creation request.
url	URL to retrieve the current status of the sandbox creation request.

Refresh Sandbox from Snapshot

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "source_snapshot=Sandbox1 Snapshot" \
https://myvault.veevavault.com/api/v22.3/objects/sandbox/1001055/actions/refresh

Response

{
    "responseStatus": "SUCCESS",
    "job_id": 165954,
    "url": "/api/v22.3/services/jobs/165954"
}

Refresh a sandbox Vault in the currently authenticated Vault from an existing snapshot.

POST /api/{version}/objects/sandbox/{vault_id}/actions/refresh

Headers

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

URI Path Parameters

Name	Description
vault_id	The Vault ID of the sandbox to be refreshed.

Body Parameters

Name	Description
source_snapshotrequired	Provide the api_name of the snapshot to refresh the sandbox from. You can obtain the api_name using the Retrieve Sandbox Snapshots request.

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 the sandbox refresh request.
url	URL to retrieve the current status of the sandbox refresh request.

Delete Sandbox

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v18.2/objects/sandbox/My Configuration Sandbox

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Sandbox '[My Configuration Sandbox]' submitted for deletion, sandbox Vault id [24143] and parent Vault id [19523]"
}

Delete a sandbox Vault. How often you can delete a Vault depends on its size. Learn more about deleting sandboxes in Vault Help.

DELETE /api/{version}/objects/sandbox/{name}

Headers

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

URI Path Parameters

Name	Description
name	The name of the sandbox Vault to delete. This is the name which appears on the My Vaults page.

Sandbox Snapshots

Snapshots allow your organization to store the configuration and data of sandbox Vaults at a given point in time. You can use snapshots to create and refresh sandbox Vaults. Learn more about administering sandbox snapshots in Vault Help.

Create Sandbox Snapshot

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "source_sandbox=Sandbox1" \
-d "name=Snapshot1" \
-d "description=First snapshot of a sandbox." \
-d "include_data=false" \
https://myvault.veevavault.com/api/v22.3/objects/sandbox/snapshot

Response

{
    "responseStatus": "SUCCESS",
    "job_id": 165944,
    "url": "/api/v22.3/services/jobs/165944"
}

Create a new sandbox snapshot for the indicated sandbox Vault.

POST /api/{version}/objects/sandbox/snapshot

Headers

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

Body Parameters

Name	Description
source_sandboxrequired	The name of the sandbox Vault to take a snapshot of.
namerequired	The name of the new snapshot.
descriptionoptional	The description of the new snapshot.
include_dataoptional	Set to true to include data as part of the snapshot. Set to false to include only configuration.

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 the snapshot creation request.
url	URL to retrieve the current status of the snapshot creation request.

Retrieve Sandbox Snapshots

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "available": 3,
       "snapshots": [
           {
               "name": "Sandbox A Snapshot",
               "api_name": "sandbox_a_snapshot__c",
               "type": "configuration",
               "description": "New snapshot of a sandbox.",
               "status": "active",
               "upgrade_status": "Good",
               "source_sandbox": "SandboxA",
               "total_object_records": 82,
               "document_versions": 0,
               "vault_version": "22R3.2",
               "update_available": "2022-12-03T00:04:59.000Z",
               "created_date": "2022-12-02T00:04:59.000Z",
               "expiration_date": "2023-04-25T05:00:00.000Z",
               "domain": "veepharm.com",
               "created_by": 1006595
           }
       ]
   }
}

Retrieve information about sandbox snapshots managed by the authenticated Vault.

GET /api/{version}/objects/sandbox/snapshot

Headers

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

Response Details

The response contains information about the snapshots managed by the authenticated Vault.

Name	Description
name	The name of the snapshot.
api_name	The API name of the snapshot.
type	The type of the source sandbox, such as configuration.
description	The description of the snapshot.
status	The current status of the snapshot: building: Snapshot is being created or updated active: Snapshot is accessible for use maintenance: Snapshot is being upgraded deleted: Snapshot is expired
upgrade_status	The current upgrade status of the snapshot: Good: No upgrade is required for the snapshot Upgrade Required: An upgrade is required for the snapshot Upgrade Available: An upgrade is available for the snapshot Expired: Snapshot has expired
source_sandbox	The name of the sandbox Vault the snapshot was created from.
total_object_records	The total number of object records in the snapshot.
document_versions	The total number of document versions in the snapshot.
vault_version	The release version of the source sandbox Vault when the snapshot was created.
update_available	The date and time when the snapshot can next be updated. Learn more about updating snapshots in Vault Help.
expiration_date	The date and time when the snapshot will expire.
domain	The domain of the source sandbox Vault.

Delete Sandbox Snapshot

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v22.3/objects/sandbox/snapshot/sandbox_a_snapshot__c

Response

{
   "responseStatus": "SUCCESS"
}

Delete a sandbox snapshot managed by the authenticated Vault. Deleted snapshots cannot be recovered. Learn more about deleting sandbox snapshots in Vault Help.

DELETE /api/{version}/objects/sandbox/snapshot/{api_name}

Headers

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

URI Path Parameters

Name	Description
api_name	The API name of the snapshot. Obtain this from the Retrieve Sandbox Snapshots request.

Response Details

On SUCCESS, the response only includes the responseStatus.

Update Sandbox Snapshot

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v22.3/objects/sandbox/snapshot/veepharm_snapshot__c/actions/update

Response

{
   "responseStatus": "SUCCESS",
   "job_id": 165949,
   "url": "/api/v22.3/services/jobs/165949"
}

Recreate a sandbox snapshot for the same source sandbox Vault. This request replaces the existing snapshot with the newly created one. Learn more about updating snapshots in Vault Help.

POST /api/{version}/objects/sandbox/snapshot/{api_name}/actions/update

Headers

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

URI Path Parameters

Name	Description
api_name	The API name of the snapshot. Obtain this from the Retrieve Sandbox Snapshots request.

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 the snapshot update request.
url	URL to retrieve the current status of the snapshot update request.

Upgrade Sandbox Snapshot

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v23.1/objects/sandbox/snapshot/veepharm_snapshot__c/actions/upgrade

Response

{
   "responseStatus": "SUCCESS",
   "job_id": 172303,
   "url": "/api/v23.1/services/jobs/172303"
}

Upgrade a sandbox snapshot to match the release version of the source sandbox Vault.

Your request to upgrade a snapshot is only valid if the upgrade_status=Upgrade Available or Upgrade Required. Use the Retrieve Sandbox Snapshots request to obtain the upgrade_status of a snapshot.

POST /api/{version}/objects/sandbox/snapshot/{api_name}/actions/upgrade

Headers

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

URI Path Parameters

Name	Description
api_name	The API name of the snapshot. Obtain this from the Retrieve Sandbox Snapshots request.

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 the snapshot upgrade request.
url	URL to retrieve the current status of the snapshot upgrade request.

Pre-Production Vaults

Pre-production Vaults allow your organization to fully manage a Vault’s lifecycle from initial to go-live. When ready, Vault Admins can promote the pre-production Vault to a production Vault through the Admin UI or API. Learn more about pre-production Vaults in Vault Help.

Build Production Vault

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "source=UAT"
https://myvault.veevavault.com/api/v21.2/objects/sandbox/actions/buildproduction

Response

{
    "responseStatus": "SUCCESS",
    "job_id": 111507,
    "url": "/api/v21.2/services/jobs/111507"
}

Given a pre-production Vault, build a production Vault. This is analogous to the Build action in the Vault UI. After building your Vault, you can promote it to production.

You can build or rebuild the source Vault for a given pre-production Vault no more than three times in a 24 hour period.

POST /api/{version}/objects/sandbox/actions/buildproduction

Headers

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

Body Parameters

Name	Description
sourcerequired	The name of the source Vault to build. This can be the current pre-production Vault or a sandbox Vault. Sandboxes must be active and match the release type (General or Limited) of the pre-production Vault.

Promote to Production

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name=VeePharm"
https://myvault.veevavault.com/api/v21.2/objects/sandbox/actions/promoteproduction

Response

{
    "responseStatus": "SUCCESS"
}

Given a built pre-production Vault, promote it to a production Vault. This is analogous to the Promote action in the Vault UI.

You must build your pre-production Vault before you can promote it to production.

POST /api/{version}/objects/sandbox/actions/promoteproduction

Headers

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

Body Parameters

Name	Description
namerequired	The name of the pre-production Vault to promote.

Logs

Vault provides several APIs to track actions performed in the system. The Audit APIs retrieve information about audits and audit types. Use the Audit History APIs to retrieve the audit history for specific document or object records. Download Daily API Usage retrieves the API Usage Logs for a specified date.

Audit

Vault provides robust audit trail and audit logs of all actions performed in the system. These include actions on the documents, objects, the system, logins, and domain levels.

Through the Audit APIs, you can:

• Retrieve audit types you have access to
• Retrieve all fields and their metadata for a specific audit type
• Retrieve all records in the specified audit type

Learn about Audit Trails & Audit Logs in Vault Help.

Retrieve Audit Types

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "audittrails": [
        {
            "name": "document_audit_trail",
            "label": "Document Audit Trail",
            "url": "/api/v17.3/metadata/audittrail/document_audit_trail"
        },
        {
            "name": "object_audit_trail",
            "label": "Object Audit Trail",
            "url": "/api/v17.3/metadata/audittrail/object_audit_trail"
        },
        {
            "name": "system_audit_trail",
            "label": "System Audit Trail",
            "url": "/api/v17.3/metadata/audittrail/system_audit_trail"
        },
        {
            "name": "domain_audit_trail",
            "label": "Domain Audit Trail",
            "url": "/api/v17.3/metadata/audittrail/domain_audit_trail"
        },
        {
            "name": "login_audit_trail",
            "label": "Login Audit Trail",
            "url": "/api/v17.3/metadata/audittrail/login_audit_trail"
        }
    ]
}

Retrieve all available audit types you have permission to access.

GET /api/{version}/metadata/audittrail

Headers

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

Response Details

Name	Description
name	Name of the audit type.
label	Label of the audit type as seen in the API and UI.
url	URL to retrieve the metadata associated with the audit type.

Retrieve Audit Metadata

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "login_audit_trail",
        "label": "Login Audit Trail",
        "fields": [
            {
                "name": "id",
                "label": "ID",
                "type": "Number"
            },
            {
                "name": "timestamp",
                "label": "Timestamp",
                "type": "DateTime"
            },
            {
                "name": "user_name",
                "label": "User Name",
                "type": "String"
            },
            {
                "name": "full_name",
                "label": "Full Name",
                "type": "String"
            },
            {
                "name": "source_ip",
                "label": "Source IP",
                "type": "String"
            }
        ]
    }
}

Retrieve all fields and their metadata for a specified audit trail or log type.

GET /api/{version}/metadata/audittrail/{audit_trail_type}

Headers

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

URI Path Parameters

Name	Description
{audit_trail_type}	The name of the specified audit type (document_audit_trail, object_audit_trail, etc).

Retrieve Audit Details

Request

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

Response

{
    "responseDetails": {
        "offset": 0,
        "limit": 200,
        "size": 7,
        "total": 7,
        "object": {
            "name": "login_audit_trail",
            "label": "Login Audit Trail",
            "url": "/api/v17.3/metadata/audittrail/login_audit_trail"
        }
    },
    "data": [
        {
            "id": "152515375538",
            "timestamp": "2017-09-15T16:07:25Z",
            "user_name": "lgills@veepharm.com",
            "full_name": "Lateef Gills",
            "source_ip": "209.136.227.195",
            "type": "User Login",
            "status": "Success",
            "browser": "Unknown",
            "platform": "Unknown"
        },
        {
            "id": "152515371157",
            "timestamp": "2017-09-14T14:19:05Z",
            "user_name": "c.brandon@veepharm.com",
            "full_name": "Cody Brandon",
            "source_ip": "162.218.77.23",
            "type": "Enterprise Home Authentication",
            "status": "Success",
            "browser": "Chrome 60.0.3112.113",
            "platform": "Intel Mac OS X 10.12.6"
        }
    ],
    "responseStatus": "SUCCESS"
}

Retrieve all audit details for a specific audit type. This request supports optional parameters to narrow the results to a specified date and time within the past 30 days.

You can run a full audit export with the same formatting as exports you initiate in the UI once per day per audit type. To execute a full audit export, set all_dates to true, leave start_date and end_date blank, and set format_result to csv. When the job is complete, you will receive an email containing links to a zipped file for each year.

GET /api/{version}/audittrail/{audit_trail_type}

Headers

Name	Description
Accept	application/json (default)

URI Path Parameters

Name	Description
{audit_trail_type}	The name of the specified audit type (document_audit_trail, object_audit_trail, etc.). Use the Retrieve Audit Types API to retrieve types available in your Vault. Requests for login_audit_trail only accept one request per user at a time.

Query Parameters

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

Name	Description
start_date	Specify a start date to retrieve audit information. This date cannot be more than 30 days ago. Dates must be YYYY-MM-DDTHH:MM:SSZ format, for example, 7AM on January 15, 2016 would use 2016-01-15T07:00:00Z. If omitted, defaults to the start of the previous day.
end_date	Specify an end date to retrieve audit information. This date cannot be more than 30 days ago. Dates must be YYYY-MM-DDTHH:MM:SSZ format, for example, 7AM on January 15, 2016 would use 2016-01-15T07:00:00Z. If omitted, defaults to the current date and time.
all_dates	Set to true to request audit information for all dates. You must leave start_date and end_date blank when requesting an export of a full audit trail. You can only run a full audit export (all_dates = true) on each audit type once every 24 hours.
format_result	To request a downloadable CSV file of your audit details, use csv. The response contains a jobId to retrieve the job status, which contains a link to download the CSV file. If omitted, the API returns a JSON response and does not start a job. If all_dates is true, this parameter is required.
limit	Paginate the results by specifying the maximum number of histories per page in the response. This can be any value between 1 and 1000. If omitted, defaults to 200.
offset	Paginate the results displayed per page by specifying the amount of offset from the entry returned. For example, if you are viewing the first 50 results (page 1) and want to see the next page, set this to offset=51. If omitted, defaults to 0.
objects	This is an optional parameter when specifying object_audit_trail as the {audit_trail_type}. Provide a comma-separated list of one or more object names to retrieve their audit details. For example, objects=product__v,country__v. If omitted, defaults to all objects.
events	This is an optional parameter when specifying object_audit_trail or document_audit_trail as the {audit_trail_type}. Provide a comma-separated list of one or more audit events to retrieve their audit details. For example, events=Edit,Delete,TaskAssignment. If omitted, defaults to all audit events. See Vault Help for full lists of object audit events and document audit events.

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

On SUCCESS, the response lists all rows and fields for the specified audit trail type. For example:

Name	Description
id	The unique audit trail ID.
timestamp	Date and time that the action was performed.
user_name	Login name for the user who performed the action. This may show “System” to indicate the action was completed by Vault.
full_name	The full name of the user who performed the action.
on_behalf_of	If the action completed by user_name was representing a different user (such as through delegated access), this field is the delegating user’s user name. For example, in the case of “tibanez@veepharm.com on behalf of mmurray@veepharm.com,” the user_name is tibanez@veepharm.com who completed the action on_behalf_of mmurray@veepharm.com.

Note that Vault returns additional fields based on the specified audit type. For example, if the audit type is object_audit_trail, Vault returns the action field denoting the audit event.

Requesting a CSV file generates a job to prepare the file for download. On SUCCESS, the response includes the jobId with a link to the CSV file.

When you export a full audit trail (all_dates = true and format_result = csv,) the response does not include a link to the CSV file. You will instead receive an email when the job is complete. The email contains a download link for each year to Excel™ files (one file per month for the current year, one file per year for each previous year) of the audit trail.

Name	Description
url	The URL to retrieve the current status of the CSV job.
jobId	The job ID value is used to retrieve the status and results of the audit trail CSV request.

Audit History

With this API, you can retrieve the complete audit history of all actions performed for a specified document or object record. For other audit histories, see Retrieve Audit Details.

Retrieve Complete Audit History for a Single Document

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.2/objects/documents/42/audittrail?start_date=2021-04-22T23:00:00Z&end_date=2021-04-24T23:00:00Z

Response

{
   "responseStatus": "SUCCESS",
   "responseDetails": {
       "offset": 0,
       "limit": 200,
       "size": 2,
       "total": 2,
       "object": {
           "name": "document_audit_trail",
           "label": "Document Audit Trail",
           "url": "/api/v21.2/metadata/audittrail/document_audit_trail"
       }
   },
   "data": [
       {
           "id": "404",
           "timestamp": "2021-04-23T23:28:38Z",
           "user_name": "olive@veepharm.com",
           "full_name": "Olivia Cattington",
           "action": "EditDocRelationships",
           "item": "VV-00016",
           "field_name": "Supporting Documents",
           "old_value": null,
           "new_value": "VV-00003",
           "workflow_name": null,
           "task_name": null,
           "signature_meaning": null,
           "view_license": null,
           "job_instance_id": null,
           "doc_id": "42",
           "version": "0.1",
           "document_url": "/ui/#doc_info/42/0/1",
           "event_description": "\"VV-00003\" was added as a \"Supporting Documents\" relation"
       },
       {
           "id": "403",
           "timestamp": "2021-04-23T23:28:04Z",
           "user_name": "olive@veepharm.com",
           "full_name": "Olivia Cattington",
           "action": "GetDocumentVersion",
           "item": "VV-00016",
           "field_name": null,
           "old_value": null,
           "new_value": null,
           "workflow_name": null,
           "task_name": null,
           "signature_meaning": null,
           "view_license": null,
           "job_instance_id": null,
           "doc_id": "42",
           "version": "0.1",
           "document_url": "/ui/#doc_info/42/0/1",
           "event_description": "Viewed Document"
       }
   ]
}

Retrieve complete audit history for a single document.

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

Headers

Name	Description
Accept	application/json (default)

URI Path Parameters

Name	Description
{doc_id}	The document ID for which to retrieve audit history.

Query Parameters

Name	Description
start_date	Specify a start date to retrieve audit history. Dates must be YYYY-MM-DDTHH:MM:SSZ format, for example, 7AM on January 15, 2018 would use 2018-01-15T07:00:00Z. If omitted, defaults to the Vault’s creation date.
end_date	Specify an end date to retrieve audit history. Dates must be YYYY-MM-DDTHH:MM:SSZ format, for example, 7AM on January 15, 2018 would use 2018-01-15T07:00:00Z. If omitted, defaults to today’s date.
format_result	To request a CSV file of your audit history, use csv. The CSV file ignores the start_date and end_date.
limit	Paginate the results by specifying the maximum number of histories per page in the response. This can be any value between 1 and 1000. If omitted, defaults to 200.
offset	Paginate the results displayed per page by specifying the amount of offset from the entry returned. For example, if you are viewing the first 50 results (page 1) and want to see the next page, set this to offset=51. If omitted, defaults to 0.
events	Provide a comma-separated list of one or more audit events to retrieve their audit history. See Vault Help for a full list of document audit events. The values passed to this parameter are case sensitive. For example, events=WorkflowCompletion,TaskAssignment. If omitted, defaults to all audit events.

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

On SUCCESS, the response includes some of the following metadata:

Name	Description
action	The name of the action performed on the document. For example, EditDocRelationships.
item	The document number field value.
signature_meaning	The reason a signature was required for any manifested signature.
view_license	Returns a value of View-Based User only when the user is assigned that license type. Otherwise, returns an empty string.
event_description	Description of the action that occurred, for example, “Viewed Document”. Note that when data changes, the description shows both the previous value and the new value.

Retrieve Complete Audit History for a Single Object Record

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.2/vobjects/product__v/00P000000000119/audittrail?start_date=2021-04-22T23:00:00Z&end_date=2021-04-23T23:43:00Z

Response

{
   "responseStatus": "SUCCESS",
   "responseDetails": {
       "offset": 200,
       "limit": 200,
       "size": 1,
       "total": 1,
       "object": {
           "name": "object_audit_trail",
           "label": "Object Audit Trail",
           "url": "/api/v21.2/metadata/audittrail/object_audit_trail"
       },
       "previous_page": "/api/v21.2/vobjects/product__v/00P000000000119/audittrail?offset=0&limit=200&uuid=dcff7510-0143-4487-bafe-77d7e63059a2"
   },
   "data": [
       {
           "id": "1807",
           "timestamp": "2021-04-23T23:41:43Z",
           "user_name": "olive@veepharm.com",
           "full_name": "Olivia Cattington",
           "action": "Edit",
           "item": "Product : Gludacta",
           "field_label": "Compound ID",
           "field_name": "compound_id__v",
           "old_value": null,
           "new_value": "null",
           "old_display_value": null,
           "new_display_value": "751789",
           "record_id": "00P000000000119",
           "object_label": "Product",
           "object_name": "product__v",
           "workflow_name": null,
           "task_name": null,
           "verdict": null,
           "reason": null,
           "capacity": null,
           "event_description": "\"Compound ID\" set to \"751789\" "
       }
   ]
}

Retrieve complete audit history for a single object record.

Vault does not audit individual field values for newly created records. For example, the audit trail for a new Product record would only include a single entry, and the Event Description would be “Product: CholeCap created”. We recommend exporting the current record along with the audit trail to ensure a complete export of all values. When a user deletes an object record, the audit trail captures all field values.

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

Headers

Name	Description
Accept	application/json (default)

URI Path Parameters

Name	Description
{object_name}	The name__v of the object for which to retrieve audit history.
{object_record_id}	The object record ID for which to retrieve audit history.

Query Parameters

Name	Description
start_date	Specify a start date to retrieve audit history. Dates must be YYYY-MM-DDTHH:MM:SSZ format, for example, 7AM on January 15, 2018 would use 2018-01-15T07:00:00Z. If omitted, defaults to the Vault’s creation date.
end_date	Specify an end date to retrieve audit history. Dates must be YYYY-MM-DDTHH:MM:SSZ format, for example, 7AM on January 15, 2018 would use 2018-01-15T07:00:00Z. If omitted, defaults to today’s date.
format_result	To request a CSV file of your audit history, use csv.
limit	Paginate the results by specifying the maximum number of histories per page in the response. This can be any value between 1 and 1000. If omitted, defaults to 200.
offset	Paginate the results displayed per page by specifying the amount of offset from the entry returned. For example, if you are viewing the first 50 results (page 1) and want to see the next page, set this to offset=51. If omitted, defaults to 0.
events	Provide a comma-separated list of one or more audit events to retrieve their audit history. See Vault Help for a full list of object audit events. The values passed to this parameter are case sensitive. For example, events=Copy,Edit,Delete. If omitted, defaults to all audit events.

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

On SUCCESS, the response includes some of the following metadata:

Name	Description
action	The name of the action performed on the object record.
item	The name of the object and record.
event_description	Description of the action that occurred.
migration_mode	Indicates that the object record was created using the X-VaultAPI-MigrationMode header. When creating or updating records in migration mode, Vault bypasses entry criteria, entry actions, event actions, validation rules, and reference constraints and allows you to create or update object records in a specific state or state type.

SDK Debug Log

From the Logs tab in Vault (Admin > Logs > Vault Java SDK Logs), you can view the Debug Log. The debug log captures custom Vault Java SDK code execution details and Vault messages at the user-level. This log is not always on by default. To capture data in the debug log, a Vault Admin must set up a debug log session for a particular user. A user can have only one (1) debug log configured for them at a time, and a Vault can have up to 20 users with debug log sessions configured.

Debug logs expire after 30 days. At the end of 30 days, Vault deletes the debug log and all log files.

By default, the Vault Owner and System Admin security profiles have permission to view the debug log and set up debug log sessions for a particular user.

Learn more about the Debug Log.

Retrieve All Debug Logs

Request

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v25.1/logs/code/debug

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "id": "0LS000000003006",
            "name": "Record Trigger Troubleshooting",
            "user_id": 61603,
            "log_level": "all__sys",
            "expiration_date": "2025-01-11T03:09:47.000Z",
            "class_filters": [
                {
                    "name": "com.veeva.vault.custom.triggers.HelloWorld",
                    "code_type": "Recordtrigger"
                }
            ],
            "status": "active__sys",
            "created_date": "2024-12-12T03:09:47.000Z"
        }
    ]
}

Retrieve all debug log sessions in the authenticated Vault.

GET /api/{version}/logs/code/debug

Headers

Name	Description
Accept	application/json

Query String Parameters

Name	Description
user_idoptional	Filter results to retrieve the debug log for this user ID only. If omitted, this request retrieves debug logs for all users in the Vault.
include_inactiveoptional	Set to true to include debug log sessions with a status of inactive__sys in the response. If omitted, defaults to false and inactive sessions are not included in the response.

Response Details

On SUCCESS, the response includes the following data for each debug log:

Name	Description
id	The numerical ID of this debug log.
name	The UI name of this debug log.
user_id	The ID of the user associated with this debug log.
log_level	The level of error messages captured in this debug log. Learn more about the log level types in Vault Help.
expiration_date	The date this session will expire, in the format YYYY-MM-DDTHH:MM:SS.000Z. Once expired, Vault deletes the debug log and all log data.
class_filters	Class filters applied to this debug log, if any. Class filters allow you to restrict debug log entries to only include entries for specific classes.
status	The status of this debug log, either active or inactive. By default, only active logs are included in the response. To include inactive logs, set the include_inactive query parameter to true.
created_date	The date this session was created, in the format YYYY-MM-DDTHH:MM:SS.000Z.

Retrieve Single Debug Log

Request

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v25.1/logs/code/debug/0LS000000003006

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "id": "0LS000000003006",
        "name": "Record Trigger Troubleshooting",
        "user_id": 61603,
        "log_level": "all__sys",
        "expiration_date": "2025-01-11T03:09:47.000Z",
        "class_filters": [
            {
                "name": "com.veeva.vault.custom.HelloWorld",
                "code_type": "Pagecontroller"
            },
            {
                "name": "com.veeva.vault.custom.triggers.HelloWorld",
                "code_type": "Recordtrigger"
            }
        ],
        "status": "active__sys",
        "created_date": "2024-12-12T03:09:47.000Z"
    }
}

Given a debug log ID, retrieve details about this debug log.

GET /api/{version}/logs/code/debug/{id}

Headers

Name	Description
Accept	application/json

URI Path Parameters

Name	Description
{id}	The ID of the debug log to retrieve.

Download Debug Log Files

Request

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v25.1/logs/code/debug/0LS000000003006/files

Response Headers

Content-Type: application/zip;charset=UTF-8
Content-Disposition: attachment;filename="vaultjavasdk_61603_debuglogs_12-18-2024.zip"

Given a debug log ID, download all of this debug log’s files.

GET /api/{version}/logs/code/debug/{id}/files

Headers

Name	Description
Accept	application/json

URI Path Parameters

Name	Description
{id}	The ID of the debug log to download.

Response Details

On SUCCESS, Vault begins a download of the files for the specified debug log. The files are packaged in a ZIP file with the file name: vaultjavasdk_{user_id}_debuglogs_{MM-DD-YYYY}.zip.

The HTTP Response Header Content-Type is set to application/zip;charset=UTF-8. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file.

Create Debug Log

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
-d "name=Record Trigger Troubleshooting." \
-d "user_id=12345" \
-d "class_filters=com.veeva.vault.custom.triggers.HelloWorld,com.veeva.vault.custom.triggers.Approval" \
https://myvault.veevavault.com/api/v25.1/logs/code/debug

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "id": "0LS000000003001"
    }
}

Create a new debug log session for a user.

Debug logs have the following limits:

• Maximum one (1) debug log per user
• Maximum 20 debug logs per Vault

POST /api/{version}/logs/code/debug

Headers

Name	Description
Accept	application/json
Content-Type	multipart/form-data

Body Parameters

Name	Description
namerequired	The UI-friendly name for this debug log, visible to Admins in the Vault UI. Maximum 128 characters.
user_idrequired	The user who will trigger entries into this debug log.
log_leveloptional	The level of error messages to capture in this log. Choose one of the following: all__sys (default) exception__sys error__sys warn__sys info__sys debug__sys Learn more about the log level types in Vault Help.
class_filtersoptional	Class filters allow you to restrict debug log entries to only include entries for specific classes. To include class filters for this debug log, include an array or comma-separated list of fully-qualified class names. For example, com.veeva.vault.custom.triggers.HelloWorld.

Reset Debug Log

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v25.1/logs/code/debug/0LS000000006003/actions/reset

Response

{
   "responseStatus": "SUCCESS"
}

Given a debug log ID, delete all existing log files and reset the expiration date to 30 days from today.

POST /api/{version}/logs/code/debug/{id}/actions/reset

Headers

Name	Description
Accept	application/json

URI Path Parameters

Name	Description
{id}	The ID of the debug log to reset.

Delete Debug Log

Request

curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v25.1/logs/code/debug/0LS000000003001

Response

{
   "responseStatus": "SUCCESS"
}

Given a debug log ID, delete this debug log and all log files.

DELETE /api/{version}/logs/code/debug/{id}

Headers

Name	Description
Accept	application/json

URI Path Parameters

Name	Description
{id}	The ID of the debug log to delete.

SDK Request Profiler

The Profiler Log allows developers to create SDK request profiling sessions, which allow developers to troubleshoot and improve custom SDK code quality by analyzing results at the SDK request level. The Profiler Log is also available in the Vault UI from Admin > Logs > Vault Java SDK Logs. Learn more about the Profiler Log in Vault Help.

The authenticated user must have the Admin: Logs: Vault Java SDK permission to perform CRUD operations on profiling sessions.

Retrieve All Profiling Sessions

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "id": "0LS000000003002",
           "label": "Baseline",
           "name": "baseline__c",
           "description": null,
           "status": "processing__sys",
           "user_id": null,
           "created_date": "2024-08-23T23:22:00.000Z",
           "expiration_date": "2024-09-22T23:22:00.000Z"
       },
       {
           "id": "0LS000000002001",
           "label": "Hotfix Dry Run 02",
           "name": "hotfix_dry_run_02__c",
           "description": null,
           "status": "complete__sys",
           "user_id": 123456789,
           "created_date": "2024-08-20T02:21:21.000Z",
           "expiration_date": "2024-09-19T02:31:47.000Z"
       },
       {
           "id": "0LS000000001001",
           "label": "Hotfix Dry Run 01",
           "name": "hotfix_dry_run_01__c",
           "description": null,
           "status": "complete__sys",
           "user_id": null,
           "created_date": "2024-08-20T01:42:02.000Z",
           "expiration_date": "2024-09-19T02:11:25.000Z"
       }
   ]
}

List all SDK request profiling sessions in the currently authenticated Vault.

GET /api/{version}/code/profiler

Headers

Name	Description
Accept	application/json

Response Details

On SUCCESS, the response includes the following data for each profiling session:

Name	Description
id	The numerical ID of this profiling session.
label	The UI label of this profiling session. For example, “Baseline”.
name	The API name of this profiling session. For example, baseline__c. You can use this value to end the profiling session early, download the results, or delete the session.
description	The description of this profiling session.
status	The status of this session, either: in_progress__sys: The session is actively running and collecting SDK request data. processing__sys: The session is no longer running, but the session is still active as Vault processes the data. The results are not yet available for download. complete__sys: The session is over, and the results are available for download. This session is inactive.
user_id	The ID of the user associated with this session. If null, this session applies to all users.
created_date	The date this session was created, in the format YYYY-MM-DDTHH:MM:SS.000Z.
expiration_date	The date this session will expire, in the format YYYY-MM-DDTHH:MM:SS.000Z. Once expired, Vault deletes the session and all session data.

Retrieve Profiling Session

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "id": "0LS000000003002",
       "label": "Baseline",
       "name": "baseline__c",
       "description": null,
       "status": "complete__sys",
       "user_id": null,
       "created_date": "2024-08-23T23:22:00.000Z",
       "expiration_date": "2024-09-22T23:36:21.000Z"
   }
}

Retrieve details about a specific SDK request profiling session.

GET /api/{version}/code/profiler/{session_name}

Headers

Name	Description
Accept	application/json

URI Path Parameters

Name	Description
{session_name}	The name of the session, for example, baseline__c.

Response Details

On SUCCESS, the response includes the following data for each profiling session:

Name	Description
id	The numerical ID of this profiling session.
label	The UI label of this profiling session. For example, “Baseline”.
name	The API name of this profiling session. For example, baseline__c. You can use this value to end the profiling session early, download the results, or delete the session.
description	The description of this profiling session.
status	The status of this session, either: in_progress__sys: The session is actively running and collecting SDK request data. processing__sys: The session is no longer running, but the session is still active as Vault processes the data. The results are not yet available for download. complete__sys: The session is over, and the results are available for download. This session is inactive.
user_id	The ID of the user associated with this session. If null, this session applies to all users.
created_date	The date this session was created, in the format YYYY-MM-DDTHH:MM:SS.000Z.
expiration_date	The date this session will expire, in the format YYYY-MM-DDTHH:MM:SS.000Z. Once expired, Vault deletes the session and all session data.

Create Profiling Session

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "label=Integration User Dry Run" \
https://myvault.veevavault.com/api/v24.3/code/profiler

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "id": "0LS000000003003",
       "name": "hotfix_dry_run_01__c"
   }
}

Create a new SDK request profiling session. Profiling sessions allow developers to troubleshoot custom code and improve code quality by analyzing results at the SDK request level.

Vault starts the profiling session immediately on creation. Profiling sessions run for either 20 minutes or up to 10,000 SDK requests, whichever comes first. To end a session early, use the End Profiling Session endpoint. Once ended, a session’s status is processing__sys while Vault prepares the data, which may take about 15 minutes. Once the status is complete__sys, the data is available for download with the Download Profiling Session Results endpoint.

Only one profiling session can be active at a time. Because sessions begin immediately on creation, you cannot create a new session until the current session becomes inactive. Additionally, each Vault can only retain profiling session data for up to 10 sessions. If your Vault already has 10 profiling sessions, you must Delete a Profiling Session before creating a new one.

POST /api/{version}/code/profiler

Headers

Name	Description
Content-Type	application/x-www-form-urlencoded
Accept	application/json

Body Parameters

Name	Description
labelrequired	The UI label for this request.
user_idoptional	The user ID of the user to associate with this session. When specified, this SDK profiling session runs only for this user. If omitted, defaults to null which runs the session for all users.
descriptionoptional	An Admin-facing description of the session.

Response Details

On SUCCESS, Vault starts the profiling session immediately and returns the session id and name.

End Profiling Session

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.3/code/profiler/baseline__c/actions/end

Response

{
   "responseStatus": "SUCCESS"
}

Terminate a profiling session early. By default, profiling sessions run for either 20 minutes or up to 10,000 SDK requests, whichever comes first.

Once ended, a session’s status is processing__sys while Vault prepares the data, which may take about 15 minutes. Once the status is complete__sys, the data is available for download with the Download Profiling Session Results endpoint.

POST /api/{version}/code/profiler/{session_name}/actions/end

Headers

Name	Description
Accept	application/json

URI Path Parameters

Name	Description
{session_name}	The name of the session, for example, baseline__c.

Response Details

On SUCCESS, the Vault ends the profiling session. The session’s status becomes processing__sys while Vault prepares the data, which may take about 15 minutes.

Delete Profiling Session

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.3/code/profiler/baseline__c

Response

{
   "responseStatus": "SUCCESS"
}

Delete an inactive profiling session, which deletes the session and all data associated with the session. Inactive sessions have a status of complete__sys.

DELETE /api/{version}/code/profiler/{session_name}

Headers

Name	Description
Accept	application/json

URI Path Parameters

Name	Description
{session_name}	The name of the session, for example, baseline__c.

Response Details

On SUCCESS, the Vault deletes the specified profiling session and deletes all data associated with the session.

Download Profiling Session Results

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.3/code/profiler/baseline__c/results > file

Response Headers

Content-Type: application/zip;charset=UTF-8
Content-Disposition: attachment;filename="baseline__c.zip"

Download the Profiler Log for a specific profiling session. A profiling session log is a CSV which contains one row for each SDK request, with a maximum of 100,000 rows.

GET /api/{version}/code/profiler/{session_name}/results

Headers

Name	Description
Accept	application/json

URI Path Parameters

Name	Description
{session_name}	The name of the session, for example, baseline__c.

Response Details

On SUCCESS, Vault downloads the results of the specified profiling session. The HTTP Response Header Content-Type is set to application/zip. The HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file.

The log is a CSV file with the following information for each SDK request:

Name	Description
timestamp	The time this SDK request began executing.
user_id	The ID of the user who initiated this request.
user_name	The user name of the user who initiated this request.
execution_id	This SDK request’s execution ID.
sdk_request_id	The ID of this SDK request.
sdk_count	The number of SDK entry points evoked during this request.
sdk_cpu_time	The CPU time, in nanoseconds.
sdk_elapsed_time	The total elapsed time, in milliseconds.
sdk_gross_memory	The memory consumed, in bytes.

Retrieve Email Notification Histories

Request: 30 Days

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v22.3/notifications/histories?start_date=2022-09-10&end_date=2022-10-09

Response: 30 Days

{
   "responseStatus": "SUCCESS",
   "responseDetails": {
       "offset": 0,
       "limit": 200,
       "size": 3,
       "total": 3
   },
   "data": [
       {
           "send_date": "2022-09-13T06:44:18.000Z",
           "recipient_name": "Teresa Ibanez",
           "recipient_id": 995595,
           "recipient_email": "tibanez@veepharm.com",
           "status": "delivered__sys",
           "error_message": null,
           "subject": "Notification: Review completed, changes not required",
           "workflow_id": 1502,
           "task_id": null,
           "document_id": null,
           "major_version": null,
           "minor_version": null,
           "object_name": "envelope__sys",
           "object_record_id": "0ER00000000E002",
           "sender_name": "Justine Lo",
           "sender_id": 694695,
           "notification_id": 107,
           "included_notification_ids": null,
           "status_date": "2022-09-13T06:44:18.000Z",
           "template_name": "basereviewedapproved__v"
       },
       {
           "send_date": "2022-09-13T06:41:02.000Z",
           "recipient_name": "Teresa Ibanez",
           "recipient_id": 995595,
           "recipient_email": "tibanez@veepharm.com",
           "status": "delivered__sys",
           "error_message": null,
           "subject": "Notification: Documents not approved, changes required",
           "workflow_id": 1501,
           "task_id": null,
           "document_id": null,
           "major_version": null,
           "minor_version": null,
           "object_name": "envelope__sys",
           "object_record_id": "0ER00000000E001",
           "sender_name": "Megan Murray",
           "sender_id": 1083287,
           "notification_id": 106,
           "included_notification_ids": null,
           "status_date": "2022-09-13T06:41:03.000Z",
           "template_name": "baseapprovedwithchangesmdw__v"
       },
       {
           "send_date": "2022-09-13T06:37:18.000Z",
           "recipient_name": "Teresa Ibanez",
           "recipient_id": 1083287,
           "recipient_email": "tibanez@veepharm.com",
           "status": "delivered__sys",
           "error_message": null,
           "subject": "Notification: Mentioned in comment on sample.",
           "workflow_id": null,
           "task_id": null,
           "document_id": 6,
           "major_version": 0,
           "minor_version": 1,
           "object_name": null,
           "object_record_id": null,
           "sender_name": "Olivia Cattington",
           "sender_id": 995595,
           "notification_id": 104,
           "included_notification_ids": null,
           "status_date": "2022-09-13T06:37:18.000Z",
           "template_name": "usermentionnotifications__v"
       }
    ]
}

Request: All Dates

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v22.3/notifications/histories?all_dates=true&format_result=csv

Response: All Dates

{
   "responseStatus": "SUCCESS",
   "jobId": "639014",
   "url": "/api/v22.3/services/jobs/639014"
}

Retrieve details about the email notifications sent by Vault. Details include the notification date, recipient, subject, and delivery status. In the UI, this information is available in Admin > Operations > Email Notification Status. Learn more about Email Notification Status in Vault Help.

GET /api/{version}/notifications/histories

Headers

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

Query Parameters

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

Name	Description
start_date	Specify a start date to retrieve notification history. This date cannot be more than 3 months ago. To retrieve older email notifications, use the all_dates parameter instead. Dates must be in YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ format. If time is omitted (THH:mm:ssZ), defaults to the start of the day. If start_date is omitted entirely, defaults to the start of the previous day. If you’ve specified a start_date, you must also specify an end_date.
end_date	Specify an end date to retrieve notification history. This date cannot be more than 30 days away from the specified start_date. Dates must be in YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ format. If time is omitted (THH:mm:ssZ), defaults to the time of the API request. If you’ve specified an end_date, you must also specify a start_date.
all_dates	Set to true to request notification history for all dates. This request starts a job to prepare a downloadable .zip of CSV files of the entire notification history by year. This is similar to requesting Export Full History from the Vault UI. When requesting a full notification history, you must leave start_date and end_date blank and set format_result to csv. You can request an export of notification history for all_dates once every 24 hours. Emails sent before 22R3 may have data in the status column only, and may have blank values in some columns.
format_result	To request a downloadable CSV file of your notification history, set this parameter to csv. The response contains a jobId to retrieve the job status, which provides a link to download the CSV file. If omitted, the API returns a JSON response with notification history and does not start a job. If all_dates is true, this parameter must be csv.
limit	Paginate the results by specifying the maximum number of histories per page in the response. This can be any value between 1 and 1000. If omitted, defaults to 200.
offset	Paginate the results displayed per page by specifying the amount of offset from the entry returned. If omitted, defaults to 0.

Download Daily API Usage

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v18.1/logs/api_usage?date=2018-01-31 > file

Response Headers

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

Retrieve the API Usage Log for a single day, up to 30 days in the past. The log contains information such as user name, user ID, remaining burst limit, and the endpoint called. Users with the Admin: Logs: API Usage Logs permission can access these logs.

Note that the daily logs may have a delay of about 15 minutes. If your log does not include appropriate data, know that your data is not lost; it is just not yet populated.

The logs are designed for troubleshooting burst limits and discovering which of your integrations are causing you to hit the limit. These logs should not be used for auditing, as they are not designed with the appropriate level of restrictions. For example, if an API request fails to enter the usage log, the API call is not prevented from executing, which would be required if this log was designed for auditing. In rare cases an API call may not show up as an entry in the log, but know that all calls are accurately reflected in your burst limit counts.

GET /api/{version}/logs/api_usage?date=YYYY-MM-DD

Headers

Note that this Accept header only changes the format of the response in the case of an error. This does not change the file format of the download.

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

Query Parameters

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

Name	Description
date	The day to retrieve the API Usage log. Date is in UTC and follows the format YYYY-MM-DD. Date cannot be more than 30 days in the past.
log_format	Optional: Specify the format to download. Possible values are csv or logfile. If omitted, defaults to csv. Note that this call always downloads a ZIP file. This parameter only changes the format of the file contained within the ZIP.

Response Details

On SUCCESS, Vault retrieves the log from the specified date as a .ZIP file. The HTTP Response Header Content-Type is set to application/octet-stream. The returned CSV or Logfile includes the following data:

Name	Description
timestamp	The date and time of this API request, in UTC.
session_id	The Session ID of the user who made the request.
user_id	The ID of the user who made the request.
username	The Vault user name (login credentials) of the user who made the request.
http_method	The REST HTTP Method of the request, for example, POST.
endpoint	The Vault REST API endpoint used for this request.
http_response_status	The HTTP response status of the request, for example, 200.
api_version	The Vault REST API version used for this request, for example, v18.1. This value is blank for endpoints which do not have an API version.
api_response_status	The API response status, for example, SUCCESS. This column may be blank for requests where the response contains binary content, such as files.
api_response_error_type	The API response error type, for example, INSUFFICIENT_ACCESS.
execution_id	Unique ID generated by Vault for each API request. Returned in the response header X-VaultAPI-ExecutionId.
client_id	The client ID passed with this request. If the API request did not include a client ID, this value is unknown. If the API received a client_id which was incorrectly formatted, this value is invalid_client_id. Learn more about Client ID in the REST API Documentation.
client_ip	The IP address of the client, which is where the call originated.
burst_limit_remaining	The number of API calls remaining in your burst limit. Learn more about API Limits.
duration	The time it takes an API request to execute in Vault, measured in milliseconds. Note the duration does not include transport times between Vault and the client.
response_delay	This column is populated whenever API calls are throttled and indicates the length of the delay in milliseconds.
sdk_count	This column is populated if the API request invoked custom Vault Java SDK code, and indicates the total number of SDK entry points executed in this request. Learn more about Vault Java SDK performance metrics.
sdk_cpu_time	This column is populated if the API request invoked custom Vault Java SDK code, and indicates the total CPU processing time required for this request in nanoseconds. Learn more about Vault Java SDK performance metrics.
sdk_elasped_time	This column is populated if the API request invoked custom Vault Java SDK code, and indicates the total elapsed time for this request in milliseconds. Learn more about Vault Java SDK performance metrics.
sdk_gross_memory	This column is populated if the API request invoked custom Vault Java SDK code, and indicates the total gross memory required for this request in bytes. Learn more about Vault Java SDK performance metrics.
connection	The api_name__sys of the matching Connection record associated with this request. If this is a trusted Veeva connection, such as Vault Loader, Vault Mobile, or Station Manager, this value is vault__sys. If there is no associated connection, this value is blank.
api_resource	The API resource for the request. For example, the primary query object for a VQL request.
api_response_warning_type	The API request warning type. For example, DUPLICATE.
api_response_warning_message	The API request warning message. For example, “Duplicate query execution detected. Consider caching commonly required data.”
api_response_error_message	The API request error message. For example, “product__b is not a queryable object; please refer to api documentation”.
reference_id	The X-VaultAPI-ReferenceIdheader value. If this header was not included in the request, this value is blank.

Download SDK Runtime Log

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v22.1/logs/api_usage?date=2022-01-25 > file

Response Headers

application/octet-stream;charset=UTF-8
attachment;filename*=UTF-8''44795-SdkLog-2022-01-25.zip

Retrieve the Runtime Log for a single day, up to 30 days in the past. Users with the Admin: Logs: Vault Java SDK Logs permission can access these logs.

The runtime logs create entries 15 minutes after the Vault Java SDK transaction completes. If you’ve recently encountered an error which is not captured in the runtime log, wait for the transaction to finish and check again. If your log does not include appropriate data, know that your data is not lost; it is just not yet populated.

Learn more about the Vault Java SDK runtime log.

GET /api/{version}/logs/code/runtime?date=YYYY-MM-DD

Headers

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

Query Parameters

Name	Description
date	The day to retrieve the runtime log. Date is in UTC and follows the format YYYY-MM-DD. Date cannot be more than 30 days in the past.
log_format	Optional: Specify the format to download. Possible values are csv or logfile. If omitted, defaults to csv. This request always downloads a ZIP file; this parameter only changes the format of the file contained within the ZIP.

Response Details

On SUCCESS, Vault retrieves the log from the specified date as a .ZIP file. The HTTP Response Header Content-Type is set to application/octet-stream.

File Staging

The following endpoints allow you to create and manage files and folders in your Vault’s file staging. Learn more about file staging in Vault Help. To upload files larger than 50MB, see Resumable Upload Sessions. You must have the Application: File Staging: Access permission to use the File Staging API.

List Items at a Path

Return a list of files and folders for the specified path. Paths are different for Admin users (Vault Owners and System Admins) and non-Admin users. Learn more about paths in the REST API Documentation.

Request

$ curl -L -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v25.1/services/file_staging/items/CholeCap_2025

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "kind": "file",
           "path": "/CholeCap_2025/About_CholeCap",
           "name": "About_CholeCap",
           "size": 55762,
           "file_content_md5": "c5e7eaafc39af8ba42081a213a68f781",
           "modified_date": "2024-12-13T00:59:57.000Z"
       },
       {
           "kind": "file",
           "path": "/CholeCap_2025/Cholesterol_From_You",
           "name": "Cholesterol_From_You",
           "size": 369574,
           "file_content_md5": "404a65da6acf6a8ba59fc73b0afe08ef",
           "modified_date": "2024-12-13T01:00:22.000Z"
       },
       {
           "kind": "folder",
           "path": "/CholeCap_2025/Supporting_Documents",
           "name": "Supporting_Documents"
       }
   ]
}

GET /api/{version}/services/file_staging/items/{item}

Headers

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

URI Path Parameters

Name	Description
item	The absolute path to a file or folder. This path is specific to the authenticated user. Admin users can access the root directory. All other users can only access their own user directory.

Query Parameters

Name	Description
recursive	If true, the response will contain the contents of all subfolders. If not specified, the default value is false.
limit	Optional: The maximum number of items per page in the response. This can be any value between 1 and 1000. If omitted, the default value is 1000.
format_result	If set to csv, the response includes a job_id. Use the Job ID value to retrieve the status and results of the request.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
kind	The kind of item. This can be either file or folder.
path	The absolute path, including file or folder name, to the item on file staging.
name	The name of the file or folder.
size	The size of the file in bytes. Not applicable to folders.
modified_date	The timestamp of when the file was last modified. Not applicable to folders.
next_page	The pagination URL to navigate to the next page of results if the number of results exceeds the number defined by a request’s limit. This URL contains a cursor query parameter, which is valid for 30 minutes from the time of the original query.
item	The path root for the query. Included in responses where format_result = csv.
file_content_md5	The MD5 checksum of the file.

Download Item Content

Retrieve the content of a specified file from file staging. Use the Range header to create resumable downloads for large files, or to continue downloading a file if your session is interrupted.

Request

$ curl -L -X GET -H "Authorization: {SESSION_ID}" \
-H "Range: bytes=0-1000" \
https://myvault.veevavault.com/api/v20.3/services/file_staging/items/content/u10001400/Wonder Drug Survey.docx

Response Headers

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment;filename="Wonder Drug Survey.docx"
Content-Range: bytes 0-1000/11737

GET /api/{version}/services/file_staging/items/content/{item}

Headers

Name	Description
Range	Optional: Specifies a partial range of bytes to include in the download. Maximum 50 MB. Must be in the format bytes={min}-{max}. For example, bytes=0-1000.

URI Path Parameters

Name	Description
item	The absolute path to a file. This path is specific to the authenticated user. Admin users can access the root directory. All other users can only access their own user directory.

Response Details

On SUCCESS, Vault retrieves the content of the specified file. The HTTP Response Header Content-Type is set to application/octet-stream and the HTTP Response Header Content-Disposition contains a filename component which can be used when naming the local file. If a range header was specified in the request, the response also includes the Content-Range HTTP Response Header, which specifies the bytes downloaded, as well as the total for the file. In the example above, the Content-Range specifies a download of bytes 1-1000 of 11737 total bytes.

Create Folder or File

Upload files or folders up to 50MB to file staging. To upload files larger than 50MB, see Resumable Upload Sessions. You can only create one file or folder per request.

Request: Create a File

$ curl -L -X POST -H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
-H "Content-Type: multipart/form-data" \
-F "path=/Wonder Drug Reference.docx" \
-F "kind=file" \
-F "overwrite=true" \
-F "file=@/Wonder Drug Reference.docx"\
https://myvault.veevavault.com/api/v20.3/services/file_staging/items

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "kind": "file",
       "path": "/Wonder Drug Reference.docx",
       "name": "Wonder Drug Reference.docx",
       "size": 11922,
       "file_content_md5": "3b2130fbfa377c733532f108b5e50411"
   }
}

Request: Create a Folder

$ curl -L -X POST -H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
-H "Content-Type: multipart/form-data" \
-F "path=/u10001400/cholecap2021" \
-F "kind=folder" \
https://myvault.veevavault.com/api/v20.3/services/file_staging/items

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "kind": "folder",
       "path": "/u10001400/cholecap2021/",
       "name": "cholecap2021"
   }
}

POST /api/{version}/services/file_staging/items

Headers

Name	Description
Content-Type	multipart/form-data
Accept	application/json (default) or application/xml
Content-MD5	Optional: The MD5 checksum of the file being uploaded.

Body Parameters

Name	Description
kindrequired	The kind of item to create. This can be either file or folder.
pathrequired	The absolute path, including file or folder name, to place the item in file staging. This path is specific to the authenticated user. Admin users can access the root directory. All other users can only access their own user directory.
overwriteoptional	If set to true, Vault will overwrite any existing files with the same name at the specified destination. For folders, this is always false.

File Upload

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

Uploading Files to the Inbox Directory

You can create Staged documents by uploading files to the Inbox directory on your Vault’s file staging. Learn more in Vault Help.

Update Folder or File

Move or rename a folder or file on file staging. You can move and rename an item in the same request.

Request

$ curl -L -X PUT -H "Authorization: {SESSION_ID}"\
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "parent=/u10001400/cholecap-2021" \
--data-urlencode "name=cholecap-2021-brochure" \
https://myvault.veevavault.com/api/v20.3/services/file_staging/items/Cholecap-References/cholecap-brochure

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "job_id": 100949,
       "url": "/api/v20.3/services/jobs/100949"
   }
}

PUT /api/{version}/services/file_staging/items/{item}

Headers

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

URI Path Parameters

Name	Description
item	The absolute path to a file or folder. This path is specific to the authenticated user. Admin users can access the root directory. All other users can only access their own user directory.

Body Parameters

At least one of the following parameters is required:

Name	Description
parentconditional	When moving a file or folder, specifies the absolute path to the parent directory in which to place the file.
nameconditional	When renaming a file or folder, specifies the new name.

Response Details

On SUCCESS, the response contains the following information:

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

Updating Files in the Inbox Directory

Renaming a file in your Vault’s Inbox directory creates a new Staged document in your Vault and does not rename, remove, or update the previously created corresponding Staged document. Learn more in Vault Help.

Delete File or Folder

Delete an individual file or folder from file staging.

Request

$ curl -L -X DELETE -H "Authorization:{SESSION_ID}"" \
-H "Accept: application/json" \
https://myvault.veevavault.com/api/v20.3/services/file_staging/items/u10001400/promotional2021?recursive=true

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "job_id": 100953,
       "url": "/api/v20.3/services/jobs/100953"
   }
}

DELETE /api/{version}/services/file_staging/items/{item}

Headers

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

URI Path Parameters

Name	Description
item	The absolute path to the file or folder to delete. This path is specific to the authenticated user. Admin users can access the root directory. All other users can only access their own user directory.

Query Parameters

Name	Description
recursive	Applicable to deleting folders only. If true, the request will delete the contents of a folder and all subfolders. The default is false.

Response Details

On SUCCESS, the response contains the following information:

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

Deleting Files in the Inbox Directory

Deleting files from your Vault’s Inbox directory does not delete corresponding Staged documents Vault created when the files were uploaded. Learn more in Vault Help.

Resumable Upload Sessions

Use resumable upload sessions to upload files larger than 50MB to file staging in three steps:

1. Create Resumable Upload Session: Generate an upload_session_id, which you can use to upload file parts, resume an interrupted session, retrieve information about a session, and, if necessary, abort a session.
2. Upload File Parts: Use the upload_session_id from step 1 to upload parts of a file to an upload session. File parts can be from 5-50MB by default, although limits for your Vault may vary.
3. Commit Upload Session: After you upload all file parts, use this endpoint to end the session and make the completed, reassembled file available in file staging.

Use the additional helper endpoints in this section to manage upload sessions. Each Vault allows up to 50 active upload sessions at a time. By default, upload sessions remain active for 72 hours after creation. If a session expires before it is committed, Vault will auto-purge all parts of the upload.

Create Resumable Upload Session

Initiate a multipart upload session and return an upload session ID.

Request

$ curl -L -X POST -H "Authorization: {SESSION_ID}" \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'path=Cholecap-Commercial-2021.mp4' \
--data-urlencode 'size=32862312' \
--data-urlencode 'overwrite=true'\
https://myvault.veevavault.com/api/v21.1/services/file_staging/upload

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "path": "/Cholecap-Commercial-2021.mp4",
        "name": "Cholecap-Commercial-2021.mp4",
        "id": "31a6aba21bf6e0005b718407a78739e6",
        "expiration_date": "2020-12-14T23:30:43.000Z",
        "created_date": "2020-12-11T23:30:43.000Z",
        "last_uploaded_date": "2020-12-11T23:30:43.000Z",
        "owner": 275657,
        "uploaded_parts": 0,
        "size": 32862312,
        "uploaded": 0,
        "overwrite": true
    }
}

POST /api/{version}/services/file_staging/upload

Headers

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

Body Parameters

Name	Description
pathrequired	The absolute path, including file name, to place the file in the staging server. This path is specific to the authenticated user. Admin users can access the root directory. All other users can only access their own user directory.
sizerequired	The size of the file in bytes. The maximum file size is 500GB.
overwriteoptional	If set to true, Vault will overwrite any existing files with the same name at the specified destination.

Response Details

Upon SUCCESS, the response includes the following information:

Name	Description
path	The path to the file as specified in the request.
id	The upload session ID.
expiration_date	The timestamp of when the upload session will expire.
created_date	The timestamp of when the session was created.
last_uploaded_date	The timestamp of the last upload in this session. Because the session was just created, this will be the same as the created_date.
owner	The user ID of the Vault user who initiated the upload session.
uploaded_parts	The number of parts uploaded to the session so far. Because the session was just created, this will be 0.
size	The size of the file in bytes as specified in the request.
uploaded	The total size, in bytes, uploaded so far in the session. Because the session was just created, this will be 0.

Upload to a Session

The session owner can upload parts of a file to an active upload session. By default, you can upload up to 2000 parts per upload session, and each part can be up to 50MB. Use the Range header to specify the range of bytes for each upload, or split files into parts and add each part as a separate file. Each part must be the same size, except for the last part in the upload session.

Request

$ curl -L -X PUT -H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
-H "Content-Type: application/octet-stream" \
-H "Content-Length: 5242880" \
-H "X-VaultAPI-FilePartNumber: 2" \
--data-binary "@/chunk-ab." \
https://myvault.veevavault.com/api/v20.3/services/file_staging/upload/.lqX6rv1jbu5vABJoy5XoSZmQXTTJV_jwxO.kFuS.qISxQJDiFm0s_kfb8oRS9DBDGg--

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "size": 5242880,
       "part_number": 2,
       "part_content_md5": "d6762077325b9ec3b75ada3b269e17d3"
   }
}

PUT /api/{version}/services/file_staging/upload/{upload_session_id}

Headers

Name	Description
Accept	application/json (default) or application/xml
Content-Type	application/octet-stream
Content-Length	The size of the file part in bytes. Parts must be at least 5MB in size, except for the last part uploaded in a session.
Content-MD5	Optional: The MD5 checksum of the file part being uploaded.
X-VaultAPI-FilePartNumber	The part number, which uniquely identifies a file part and defines its position within the file as a whole. If a part is uploaded using a part number that has already been used, Vault overwrites the previously uploaded file part. You must upload parts in numerical order. For example, you cannot upload part 3 without first uploading parts 1 and 2.

URI Path Parameters

Name	Description
upload_session_id	The upload session ID.

Response Details

Upon SUCCESS, the response includes the size, part_number, and part_content_MD5 for the file part.

Commit Upload Session

Mark an upload session as complete and assemble all previously uploaded parts to create a file.

Request

$ curl -L -X POST -H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
https://myvault.veevavault.com/api/v20.3/services/file_staging/upload/.lqX6rv1jbu5vABJoy5XoSZmQXTTJV_jwxO.kFuS.qISxQJDiFm0s_kfb8oRS9DBDGg--

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "job_id": 100954
   }
}

POST /api/{version}/services/file_staging/upload/{upload_session_id}

Headers

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

URI Path Parameters

Name	Description
upload_session_id	The upload session ID.

Response Details

On SUCCESS, Vault returns the job_id for the commit. Use the Job Status API to retrieve the job results. Upon successful completion of the job, the file will be available on the staging server.

List Upload Sessions

Return a list of active upload sessions.

Request

$ curl -L -X GET -H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
https://myvault.veevavault.com/api/v20.3/services/file_staging/upload

Response

{
   "responseStatus": "SUCCESS",
   "data": [
       {
           "path": "/u10001400/Gludacta-2021/Gludacta-Flyer.docx",
           "id": "yYFg7jN_fZBmUD9Tj98RkL2yqtbTdIh17iy02nd5pby62oqVJLXv.R.ea1jSr786rgwpf7Vx3RmmQ--",
           "expiration_date": "2020-10-10T18:32:55.000Z",
           "created_date": "2020-10-07T18:32:55.000Z",
           "last_uploaded_date": "2020-10-07T19:27:07.000Z",
           "owner": 10001400,
           "uploaded_parts": 1,
           "size": 1273267,
           "uploaded": 1273267
       },
       {
           "path": "/u10001400/Gludacta-2021/GludactaPackageBrochure.pdf",
           "id": "JEtOyUb9i.DXVbtW7xZT7jWr2rNLWtdWrV7IPCo9aILqd.k8nlNNlG3SbplEVDJulPijrFwnelJw--",
           "expiration_date": "2020-10-10T19:11:57.000Z",
           "created_date": "2020-10-07T19:11:57.000Z",
           "last_uploaded_date": "2020-10-07T19:11:57.000Z",
           "owner": 10001400,
           "uploaded_parts": 0,
           "size": 1438827,
           "uploaded": 0
       },
       {
           "path": "/u10001400/cholecap-2021/Cholecap-Commercial-2021.mp4",
           "id": "TpE_3roGfhpCppmk9ltKaEAbb8.kWbZEe6xDuW3lNa42801RbIEPJaWG07xvwrITJgVmXDw3UVL1w--",
           "expiration_date": "2020-10-10T19:30:18.000Z",
           "created_date": "2020-10-07T19:30:18.000Z",
           "last_uploaded_date": "2020-10-07T19:38:29.000Z",
           "owner": 10001400,
           "uploaded_parts": 2,
           "size": 32862312,
           "uploaded": 10485760
       }
        ]
}

GET /api/{version}/services/file_staging/upload

Headers

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

Response Details

On SUCCESS, Vault lists all active upload sessions for a Vault, along with their fields and field values. Admin users will see upload sessions for the entire Vault, while non-Admin users will see their own sessions only.

Name	Description
path	The absolute path, including file name, to place the file in the staging server. This path is specific to the authenticated user. Admin users can access the root directory. All other users can only access their own user directory.
id	The upload session ID.
expiration_date	The timestamp of when the upload session will expire.
created_date	The timestamp of when the session was created.
last_uploaded_date	The timestamp of the last upload in this session. Because the session was just created, this will be the same as the created_date.
owner	The user ID of the Vault user who initiated the upload session.
uploaded_parts	The number of file parts uploaded so far.
size	The total size, in bytes, of the file when complete.
uploaded	The total number of bytes uploaded so far in the session.

Get Upload Session Details

Retrieve the details of an active upload session. Admin users can get details for all sessions, while non-Admin users can only get details for sessions if they are the owner.

Request

$ curl -L -X GET -H "Authorization: {SESSION_ID}"\
-H "Accept: application/json" \
https://myvault.veevevault.com/api/v20.3/services/file_staging/upload/TpE_3roGfhpCppmk9ltKaEAbb8.kWbZEe6xDuW3lNa42801RbIEPJaWG07xvwrITJgVmXDw3UVL1w--

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "path": "/u10001400/cholecap-2021/Cholecap-Commercial-2021.mp4",
       "id": "TpE_3roGfhpCppmk9ltKaEAbb8.kWbZEe6xDuW3lNa42801RbIEPJaWG07xvwrITJgVmXDw3UVL1w--",
       "expiration_date": "2020-10-10T19:30:18.000Z",
       "created_date": "2020-10-07T19:30:18.000Z",
       "last_uploaded_date": "2020-10-07T19:38:29.000Z",
       "owner": 10001400,
       "uploaded_parts": 2,
       "size": 32862312,
       "uploaded": 10485760
   }
}

GET /api/{version}/services/file_staging/upload/{upload_session_id}

Headers

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

URI Path Parameters

Name	Description
upload_session_id	The upload session ID.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
path	The absolute path, including file name, to place the file in the staging server. This path is specific to the authenticated user. Admin users can access the root directory. All other users can only access their own user directory.
id	The upload session ID.
expiration_date	The timestamp of when the upload session will expire.
created_date	The timestamp of when the session was created.
last_uploaded_date	The timestamp of the last upload in this session.
owner	The user ID of the Vault user who initiated the upload session.
uploaded_parts	The total number of file parts uploaded so far.
size	The total size, in bytes, of the file when complete.
uploaded	The total number of bytes uploaded so far in the session.

List File Parts Uploaded to Session

Return a list of parts uploaded in a session. You must be an Admin user or the session owner.

Request

$ curl -L -X GET -H "Authorization: {SESSION_ID}"\
-H "Accept: application/json" \
https://myvault.veevavault.com/api/v21.1/services/file_staging/upload/98f46c04fa7a65ff2e5eaf90fdf613ab/parts?limit=2

Response

{
   "responseStatus": "SUCCESS",
   "responseDetails": {
       "next_page": "https://myvault.veevavault.com/api/v21.1/services/file_staging/upload/98f46c04fa7a65ff2e5eaf90fdf613ab/parts?cursor=%2BMTykDOd3PrccDRP%2F254mQ%3D%3D%3A%2BkGnLUB6M9iDNUZeJ6BgOdWKpFQ%2BC7Q0B8UHdPxfJ7U%3D&limit=2"
   },
   "data": [
       {
           "size": 5242880,
           "part_number": 1,
           "part_content_md5": "c24a2d4b1c4e03a9f4113903edac6f47"
       },
       {
           "size": 5242880,
           "part_number": 2,
           "part_content_md5": "d6762077325b9ec3b75ada3b269e17d3"
       }
   ]
}

GET /api/{version}/services/file_staging/upload/{upload_session_id}/parts

Headers

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

URI Path Parameters

Name	Description
upload_session_id	The upload session ID.

Query Parameters

Name	Description
limit	Optional: The maximum number of items per page in the response. This can be any value between 1 and 1000. If omitted, the default value is 1000.

Response Details

On SUCCESS, the response includes the size and part_number of each file part uploaded to the session so far. If the number of parts returned exceeds 1000 or the number defined by the limit, Vault includes pagination links in the response.

Abort Upload Session

Abort an active upload session and purge all uploaded file parts. Admin users can see and abort all upload sessions, while non-Admin users can only see and abort sessions where they are the owner.

Request

$ curl -L -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
https://myvault.veevavault.com/api/v20.3/services/file_staging/upload/TpE_3roGfhpCppmk9ltKaEAbb8.kWbZEe6xDuW3lNa42801RbIEPJaWG07xvwrITJgVmXDw3UVL1w--

Response

{
   "responseStatus": "SUCCESS"
}

DELETE /api/{version}/services/file_staging/upload/{upload_session_id}

Headers

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

URI Path Parameters

Name	Description
upload_session_id	The upload session ID.

Vault Loader

The following endpoints allow you to leverage Loader Services to load a set of data objects to your Vault or extract one or more data files from your Vault. Learn more about Vault Loader in Vault Help

Multi-File Extract

Extract Data Files

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
--data-binary @"C:\Vault\Loader\extract_objects.json" \
https://myvault.veevavault.com/api/v19.2/services/loader/extract

Body

[
{
  "object_type": "documents__v",
  "extract_options": "include_renditions__v",
  "fields":[
    "id",
    "name__v",
    "type__v"
    ],
    "vql_criteria__v":"site__v=123 MAXROWS 500 SKIP 100"
},
{   "object_type": "vobjects__v",
  "object": "product__v",
  "fields":[
    "id",
    "name__v",
    "object_type__v"
    ],
    "vql_criteria__v":"site__v=123 MAXROWS 500 SKIP 100"
    },
    {
  "object_type": "groups__v",
  "fields":[
    "id",
    "name__v"
    ]
    }
]

Response

{
    "responseStatus": "SUCCESS",
    "url": "/api/v19.2/services/jobs/61907",
    "job_id": 61907,
    "tasks": [
        {
            "task_id": "1",
            "object_type": "documents__v",
            "fields": [
                "id",
                "name__v",
                "type__v"
            ],
            "vql_criteria__v": "site__v=123 MAXROWS 500 SKIP 100",
            "extract_options": "include_renditions__v"
        },
        {
            "task_id": "2",
            "object_type": "vobjects__v",
            "object": "product__v",
            "fields": [
                "id",
                "name__v",
                "object_type__v"
            ],
            "vql_criteria__v": "site__v=123 MAXROWS 500 SKIP 100"
        },
        {
            "task_id": "3",
            "object_type": "groups__v",
            "fields": [
                "id",
                "name__v"
            ]
        }
    ]
}

Create a Loader job to extract one or more data files. Learn more about extracting data files with Vault Loader in Vault Help. You can extract a maximum of 10 data objects per request.

POST /api/{version}/services/loader/extract

Headers

Name	Description
Accept	application/json
Content-Type	application/json

Body Parameters

The body of your request should be a JSON file containing the set of data objects to extract.

Name	Description
object_typerequired	The type of data object to extract. The following values are allowed: vobjects__v documents__v document_versions__v document_relationships__v groups__v
objectconditional	If object_type=vobjects__v, include the object name. For example, product__v.
extract_optionsoptional	Include to specify whether or not to extract renditions and/or source files for the documents__v and document_versions__v object types. The following values are allowed: include_source__v include_renditions__v If omitted, Vault returns all document properties in the Retrieve Loader Results endpoint.
fieldsrequired	A JSON array with the field information for the specified object type. For example, id, name__v, descriptions__v, etc.
vql_criteria__voptional	A VQL-like expression used to optionally filter the data set to only those records that meet a specified criterion. Learn more about Criteria VQL.

Query Parameters

Name	Description
sendNotification	To send a Vault notification when the job completes, set to true. If omitted, this defaults to false and Vault does not send a notification when the job completes.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
job_id	The Job ID value to retrieve the status of the loader extract request.
tasks	A set of tasks with a task_id for each extract request.

Retrieve Loader Extract Results

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v19.2/services/loader/61907/tasks/2/results

Response

file,rendition_type__v,id,name__v,type__v
/61915/50/0_1/renditions/viewable_rendition__v.pdf,viewable_rendition__v,50,Facts about High Cholesterol Spring 2016,Promotional Material
/61915/8/0_1/renditions/viewable_rendition__v.pdf,viewable_rendition__v,8,ashley-harvey,Personnel

After submitting a request to extract data files from your Vault, you can query Vault to retrieve the results of a specified job task.

GET /api/{version}/services/loader/{job_id}/tasks/{task_id}/results

Headers

Name	Description
Accept	text/csv

URI Path Parameters

Name	Description
job_id	The id value of the requested extract job. Obtain this from the Extract Data Files request.
task_id	The id value of the requested extract task. Obtain this from the Extract Data Files request.

Response Details

On SUCCESS:

• If the Loader job task was successful, the response includes CSV output containing the results of a specific extract job task.
• If the Loader job task was unsuccessful, the response is blank. To view the failure log, log into your Vault, go to Admin > Operations > Job Status, and select the Job ID from the History section.

If the extract includes document or document version renditions, the CSV output contains paths to rendition files on your Vault’s file staging. When an export includes multiple rendition types for a document or document version, the CSV output includes a separate row for each rendition type.

Retrieve Loader Extract Renditions Results

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v19.2/services/loader/61907/tasks/1/results/renditions

Response

file,rendition_type__v,id,name__v,type__v
/61915/50/0_1/renditions/viewable_rendition__v.pdf,viewable_rendition__v,50,Facts about High Cholesterol Spring 2016,Promotional Material
/61915/8/0_1/renditions/viewable_rendition__v.pdf,viewable_rendition__v,8,ashley-harvey,Personnel

After submitting a request to extract object types from your Vault, you can query Vault to retrieve results of a specified job task that includes renditions requested with documents.

GET /api/{version}/services/loader/{job_id}/tasks/{task_id}/results/renditions

Headers

Name	Description
Accept	text/csv

URI Path Parameters

Name	Description
job_id	The id value of the requested extract job.
task_id	The id value of the requested extract task.

Response Details

On SUCCESS, the response includes CSV output containing paths to rendition files for documents or document versions on your Vault’s file staging. When an export includes multiple rendition types for a document or document version, the CSV output includes a separate row for each rendition type.

Multi-File Load

Load Data Objects

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
- H "Content-Type: application/json" \
--data-binary @"filename.json" \
https://myvault.veevavault.com/api/v20.2/services/loader/load

Body

[
  {
    "object_type": "documents__v",
    "action": "create",
    "file": "documents.csv",
    "documentmigrationmode": true,
    "order": 1
  },
  {
    "object_type": "vobjects__v",
    "object": "veterinary_patient__c",
    "action": "create",
    "file": "patients.csv",
    "recordmigrationmode": true,
    "order": 2
  },
  {
    "object_type": "vobjects__v",
    "object": "product__v",
    "action": "upsert",
    "file": "products.csv",
    "order": 3,
    "idparam": "external_id__v"
  },
  {
    "object_type": "groups__v",
    "action": "update",
    "file": "groups.csv",
    "order": 4
  }
]

Response

{
    "responseStatus": "SUCCESS",
    "url": "/api/v20.2/services/jobs/92201",
    "job_id": 92201,
    "tasks": [
        {
            "task_id": "1",
            "object_type": "documents__v",
            "action": "create",
            "documentmigrationmode": true,
            "file": "documents.csv"
        },
        {
            "task_id": "2",
            "object_type": "vobjects__v",
            "object": "veterinary_patient__c",
            "action": "create",
            "recordmigrationmode": true,
            "file": "patients.csv"
        },
        {
            "task_id": "3",
            "object_type": "vobjects__v",
            "object": "product__v",
            "action": "upsert",
            "idparam": "external_id__v",
            "file": "products.csv"
        },
        {
            "task_id": "4",
            "object_type": "groups__v",
            "action": "update",
            "file": "groups.csv"
        }
    ]
}

Create a loader job and load a set of data files. You can load a maximum of 10 data objects per request.

POST /api/{version}/services/loader/load

Headers

Name	Description
Content-Type	application/json
Accept	application/json

Body Parameters

The body of your request should be a JSON file containing the set of data objects to load.

Name	Description
object_typerequired	The type of data object to load. The following values are allowed: vobjects__v documents__v document_versions__v document_relationships__v groups__v document_roles__v document_versions_roles__v document_renditions__v document_attachments__v
objectconditional	If the object_type = vobjects__v, include the object name. For example, product__v.
actionrequired	The action type to create, update, upsert, or delete data objects. If the object_type=vobjects__v, the action types create_attachments, delete_attachments, assign_roles, and remove_roles are also available.
filerequired	Include the filepath to reference the CSV load file on file staging.
orderoptional	Specifies the order of the load task.
idparamoptional	Identify object records by any unique field value. Can only be used if object_type is vobjects__v and action is upsert, update, or delete. You can use any object field which has unique set to true in the object metadata. For example, idParam=external_id__v.
recordmigrationmodeoptional	Set to true to create or update object records in a noninitial state and with minimal validation, bypass rules such as entry criteria, create inactive records, and set system-managed fields such as created_by__v. Does not bypass record triggers. Use notriggers to bypass triggers. The recordmigrationmode parameter can only be used if object_type is vobjects__v and action is create, update, or upsert. You must have the Record Migration permission to use this parameter. Learn more about Record Migration Mode in Vault Help.
notriggersoptional	If set to true, Record Migration Mode bypasses record triggers.
documentmigrationmodeoptional	Set to true to create documents, document versions, document version roles, or document renditions in a specific state or state type. Also allows you to set the name, document number, and version number. For update actions, only allows you to manually reset document numbers. You must have the Document Migration permission to use this parameter. Learn more about Document Migration Mode in Vault Help.

Query Parameters

Name	Description
sendNotification	To send a Vault notification when the job completes, set to true. If omitted, this defaults to false and Vault does not send a notification when the job completes.

About File Validation

Vault evaluates header rows in CSV load files to ensure they include all required fields. Required fields vary depending on the object_type and action. Learn more about Vault Loader input files for documents, document roles, document attachments, objects, and object attachments in Vault Help.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
job_id	The Job ID value to retrieve the status of the loader extract request.
tasks	The task_id for each load request.

Retrieve Load Success Log Results

Request

curl -X GET -H "Authorization: {SESSION_ID}" \
- H "Content-Type: application/json" \
https://myveevavault.com/api/v19.2/services/loader/load/61907/tasks/1/successlog

Response

responseStatus,id,name__v,external_id__v,errors,rowId
SUCCESS,00P000000000807,,,,1
SUCCESS,00P000000000808,,,,2
SUCCESS,00P000000000809,,,,3

Retrieve success logs of the loader results.

GET /api/{version}/services/loader/{job_id}/tasks/{task_id}/successlog

Headers

Name	Description
Accept	text/csv

URI Path Parameters

Name	Description
job_id	The id value of the requested extract job.
task_id	The id value of the requested extract task.

Response Details

On SUCCESS, the response includes a CSV file that includes the success log of the loader results.

Retrieve Load Failure Log Results

Request

curl -X GET -H "Authorization: {SESSION_ID}" \
- H "Content-Type: application/json" \
https://myveevavault.com/api/v19.2/services/loader/load/61907/tasks/1/failurelog

Response

responseStatus,name__v
FAILURE/Versioning Documents

Retrieve failure logs of the loader results.

GET /api/{version}/services/loader/{job_id}/tasks/{task_id}/failurelog

Headers

Name	Description
Accept	text/csv

URI Path Parameters

Name	Description
job_id	The id value of the requested extract job.
task_id	The id value of the requested extract task.

Response Details

On SUCCESS, the response includes a CSV file that includes the failure log of the loader results.

Bulk Translation

The Bulk Translation API allows you to translate messages in your Vault in bulk. These APIs allow you to quickly compile a list of messages for translation. The exported bulk translation file is editable in Excel, any text editor, or translation software. Learn more about bulk translation in Vault Help.

There are four (4) types of message translation files:

• Field Labels
• System Messages
• Notification Templates
• User Account Emails

You must have the Admin: Language: Edit permission to use these endpoints.

Export Bulk Translation File

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.2/messages/field_labels__sys/language/en/actions/export

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "jobId": "902101",
        "url": "/api/v24.2/services/jobs/902101"
    }
}

Response: Retrieve Job Status

{
   "responseStatus": "SUCCESS",
   "data": {
       "id": 902101,
       "status": "SUCCESS",
       "links": [
           {
               "rel": "self",
               "href": "/api/v24.2/services/jobs/902101",
               "method": "GET",
               "accept": "application/json"
           },
           {
               "rel": "file",
               "href": "/api/v24.2/services/file_staging/items/PromoMats_English_Field-Labels_5-29-24_15-34-10.csv",
               "method": "GET",
               "accept": "application/json"
           },
           {
               "rel": "content",
               "href": "/api/v24.2/services/file_staging/items/content/PromoMats_English_Field-Labels_5-29-24_15-34-10.csv",
               "method": "GET",
               "accept": "application/octet-stream;charset=UTF-8"
           }
       ],
       "created_by": 61603,
       "created_date": "2024-05-29T21:34:11.000Z",
       "run_start_date": "2024-05-29T21:34:11.000Z",
       "run_end_date": "2024-05-29T21:34:20.000Z"
   }
}

Export a bulk translation file from your Vault. The exported bulk translation file is a CSV editable in any text editor or translation software. You can request one (1) message type in one (1) language per request. Learn more about the translation file schema in Vault Help.

This request starts an asynchronous job that exports the translation file to your Vault’s file staging. You can then download this file with the Download Item Content request.

You must have the Admin: Language: Read permission to export a bulk translation file from Vault.

POST /api/{version}/messages/{message_type}/language/{lang}/actions/export

Headers

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

URI Path Parameters

Name	Description
{message_type}	The message type name: field_labels__sys, system_messages__sys, notification_template_messages__sys, or user_account_messages__sys.
{lang}	A valid language code value, for example, en. Retrieve available values from the Admin Key (admin_key__sys) field on the Language (language__sys) object. Active and Inactive languages are both valid.

Response Details

On SUCCESS, the response includes the url and job_id of the job. You can use this to retrieve the status and results of the request.

When the job is complete, the translation files are available on your Vault’s file staging. Retrieving the job status of this completed job provides the href to download the CSV from file staging.

Import Bulk Translation File

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-d "file_path=PromoMats_English_Field-Labels_5-29-24_15-34-10.csv" \
https://myvault.veevavault.com/api/v24.2/messages/field_labels__sys/actions/import

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "url": "/api/v24.2/services/jobs/902601",
        "jobId": "902601"
    }
}

Import a bulk translation file into Vault. While an exported bulk translation file can contain only one (1) language, your import file may include multiple languages. Vault reads the language value separately for each row and applies any new translations immediately. Vault ignores any rows without changes. Learn more about the translation file schema in Vault Help.

You must have the Admin: Language: Edit permission to import a bulk translation file to Vault.

Upload the CSV file to your Vault’s file staging before making this request.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.

POST /api/{version}/messages/{message_type}/actions/import

Headers

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

URI Path Parameters

Name	Description
{message_type}	The message type name: field_labels__sys, system_messages__sys, notification_template_messages__sys, or user_account_messages__sys.

Body Parameters

Name	Description
file_path	The file path of the CSV file on file staging. Cannot contain ../ or any other path traversal directives.

Response Details

On SUCCESS, the response includes the job_id which allows you to:

• Retrieve the job status, which specifies if the import job has completed with SUCCESS
• Retrieve the job summary, which provides details of a successful job
• Retrieve the job errors, which provides details about the errors encountered in the job (if any)

Retrieve Import Bulk Translation File Job Summary

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.2/services/jobs/902601/summary

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "ignored": 14057,
       "updated": 14,
       "failed": 179,
       "added": 0
   }
}

After submitting a request to import a bulk translation file, you can query Vault to determine the results of the request.

Before submitting this request:

• You must have previously requested an Import Bulk Translation File job (via the API) which is no longer active
• You must be the user who initiated the job or have the Admin: Jobs: Read permission

GET /api/{version}/services/jobs/{job_id}/summary

Headers

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

URI Path Parameters

Name	Description
{job_id}	The id value of the requested import job. This was returned from the Import Bulk Translation File request.

Response Details

On SUCCESS, the response includes the following data:

• ignored: The number of rows that were ignored. For example, Vault ignores any rows without changes.
• updated: The number of existing rows that were updated successfully.
• failed: The number of rows that attempted an update but failed. Use the Retrieve Import Bulk Translation File Job Errors endpoint to retrieve details about these rows.
• added: The number of new rows that were added.

Retrieve Import Bulk Translation File Job Errors

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v24.2/services/jobs/902601/errors

Response

"Line Number","Error Message"
"3760","line 3,760: Translation of ""objectStateBehavior.glossary_definition_lifecycle__sys#approved_state__sys#change_state_to_draft_useraction1__sys.label"" not supported"
"3762","line 3,762: Translation of ""objectStateBehavior.glossary_definition_lifecycle__sys#approved_state__sys#change_state_to_withdrawn_useraction__sys.label"" not supported"
"3764","line 3,764: Translation of ""objectStateBehavior.glossary_definition_lifecycle__sys#draft_state__sys#change_state_to_in_review_useraction__sys.label"" not supported"
"3766","line 3,766: Translation of ""objectStateBehavior.glossary_definition_lifecycle__sys#in_review_state__sys#change_state_to_approved_useraction__sys.label"" not supported"
"3768","line 3,768: Translation of ""objectStateBehavior.glossary_definition_lifecycle__sys#in_review_state__sys#change_state_to_draft_useraction__sys.label"" not supported"
"3770","line 3,770: Translation of ""objectStateBehavior.glossary_definition_lifecycle__sys#withdrawn_state__sys#change_state_to_draft_useraction2__sys.label"" not supported"

After submitting a request to import a bulk translation file, you can query Vault to determine the errors from the request (if any).

Before submitting this request:

• You must have previously requested an Import Bulk Translation File job (via the API) which is no longer active
• You must be the user who initiated the job or have the Admin: Jobs: Read permission

GET /api/{version}/services/jobs/{job_id}/errors

Headers

Name	Description
Accept	text/csv

URI Path Parameters

Name	Description
{job_id}	The id value of the requested import job. This was returned from the Import Bulk Translation File request.

Response Details

On SUCCESS, the response includes the line number and error message for any errors encountered in the job.

Jobs

Retrieve Job Status

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "OK",
  "data": {
    "id": 1201,
    "status": "SUCCESS",
    "method": "POST",
    "links": [
      {
        "rel": "self",
        "href": "/api/v15.0/services/jobs/1601",
        "method": "GET",
        "accept": "application/json"
      }
    ],
    "created_by": 44533,
    "created_date": "2016-04-20T18:14:42.000Z",
    "run_start_date": "2016-04-20T18:14:43.000Z",
    "run_end_date": "2016-04-20T18:14:44.000Z"
  }
}

After submitting a request, you can query your Vault to determine the status of the request. To do this, you must have a valid job_id for a job previously requested through the API.

Example Jobs:

• Binder Export
• Import Submission
• Export Submission
• Create EDL
• Deploy Package
• Deep Copy Object Record
• Cascade Delete Object Record
• Export Documents

GET /api/{version}/services/jobs/{job_id}

Headers

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

URI Path Parameters

Name	Description
{job_id}	The ID of the job, returned from the original job request.

Response Details

On SUCCESS, the response includes the following information. All DateTime values for scheduled jobs are in the Vault time zone for the currently authenticated user. Learn more about the Vault time zone in Vault Help.

Metadata Field	Description
id	The job_id field value for the job.
status	The status of the job. Possible statuses include SCHEDULED, QUEUED, RUNNING, SUCCESS, ERRORS_ENCOUNTERED, QUEUEING, CANCELLED, and MISSED_SCHEDULE.
method	The HTTP method used in the request.
links	Once the job is finished, use these endpoints and methods to retrieve other job details. Note that for Controlled Copy jobs, the artifacts link will only work with API v18.3+.
progress	If the retrieved job is a custom job created with the Vault Java SDK, this array contains a summary of the number of job tasks (size) and their status.
created_by	The id field value of the user who started the job.
created_date	The date and time when the job was requested.
run_start_date	The date and time when the export job started.
run_end_date	The date and time when the export job finished.

Retrieve Job Tasks

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.1/services/jobs/72408/tasks

Response

{
   "responseStatus": "SUCCESS",
   "url": "/api/v21.1/services/jobs/72408/tasks?limit=50&offset=0",
   "responseDetails": {
       "total": 1,
       "limit": 50,
       "offset": 0
   },
   "job_id": 72408,
   "tasks": [
       {
           "id": "Task1",
           "state": "SUCCESS"
       }
   ]
}

Retrieve the tasks associated with an SDK job.

GET /api/{version}/services/jobs/{job_id}/tasks

Headers

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

URI Path Parameters

Name	Description
{job_id}	The ID of the job, returned from the original job request.

Retrieve Job Histories

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "responseMessage": "OK",
   "url": "/api/v21.1/services/jobs/histories?limit=50&offset=0",
   "responseDetails": {
       "total": 2753,
       "limit": 50,
       "offset": 0,
       "next_page": "/api/v21.1/services/jobs/histories?limit=50&offset=50"
   },
   "jobs": [
      {
           "job_id": 361402,
           "title": "User Account Activation",
           "status": "SUCCESS",
           "created_by": 1,
           "created_date": "2020-12-15T07:00:31.000Z",
           "modified_by": 1,
           "modified_date": "2020-12-16T07:05:06.000Z",
           "run_start_date": "2020-12-16T07:00:00.000Z",
           "run_end_date": "2020-12-16T07:06:07.000Z"
       },
       {
           "job_id": 361401,
           "title": "Synchronize Portal Assets",
           "status": "SUCCESS",
           "created_by": 1,
           "created_date": "2020-12-15T05:01:24.000Z",
           "modified_by": 1,
           "modified_date": "2020-12-16T05:00:09.000Z",
           "run_start_date": "2020-12-16T05:00:00.000Z",
           "run_end_date": "2020-12-16T05:01:12.000Z"
       }
   ]
}

Retrieve a history of all completed jobs in the authenticated Vault. A completed job is any job which has started and finished running, including jobs which did not complete successfully. In-progress or queued jobs do not appear here.

GET /api/{version}/services/jobs/histories

Headers

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

Query Parameters

Name	Description
start_date	Sets the date to start retrieving completed jobs, in the format YYYY-MM-DDTHH:MM:SSZ. For example, for 7AM on January 15, 2016, use 2016-01-15T07:00:00Z. If omitted, defaults to the first completed job.
end_date	Sets the date to end retrieving completed jobs, in the format YYYY-MM-DDTHH:MM:SSZ. For example, for 7AM on January 15, 2016, use 2016-01-15T07:00:00Z. If omitted, defaults to the current date and time.
status	Filter to only retrieve jobs in a certain status. Allowed values are success, errors_encountered, failed_to_run, missed_schedule, cancelled. If omitted, retrieves all statuses.
limit	Paginate the results by specifying the maximum number of histories per page in the response. This can be any value between 1 and 200. If omitted, defaults to 50.
offset	Paginate the results displayed per page by specifying the amount of offset from the first job history returned. If omitted, defaults to 0. If you are viewing the first 50 results (page 1) and want to see the next page, set this to offset=51.

Retrieve Job Monitors

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "responseMessage": "OK",
   "url": "/api/v21.1/services/jobs/monitors?limit=50&offset=0",
   "responseDetails": {
       "total": 3,
       "limit": 50,
       "offset": 0
   },
   "jobs": [
       {
           "job_id": 72505,
           "title": "User Account Activation",
           "status": "SCHEDULED",
           "created_by": 1,
           "created_date": "2021-02-03T04:01:29.000Z",
           "modified_by": 1,
           "modified_date": "2021-02-03T04:01:29.000Z",
           "run_start_date": "2021-02-04T04:00:00.000Z"
       },
       {
           "job_id": 72518,
           "title": "Task Reminder Notification",
           "status": "SCHEDULED",
           "created_by": 1,
           "created_date": "2021-02-03T09:01:53.000Z",
           "modified_by": 1,
           "modified_date": "2021-02-03T09:01:53.000Z",
           "run_start_date": "2021-02-04T09:00:00.000Z"
       }
   ]
}

Retrieve monitors for jobs which have not yet completed in the authenticated Vault. An uncompleted job is any job which has not finished running, such as scheduled, queued, or actively running jobs. Completed jobs do not appear here.

GET /api/{version}/services/jobs/monitors

Headers

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

Query Parameters

Name	Description
start_date	Sets the date to start retrieving uncompleted jobs, based on the date and time the job instance was created. Value must be in the format YYYY-MM-DDTHH:MM:SSZ. For example, for 7AM on January 15, 2016, use 2016-01-15T07:00:00Z. If omitted, defaults to the first completed job.
end_date	Sets the date to end retrieving uncompleted jobs, based on the date and time the job instance was created. Value must be in the format YYYY-MM-DDTHH:MM:SSZ. For example, for 7AM on January 15, 2016, use 2016-01-15T07:00:00Z. If omitted, defaults to the current date and time.
status	Filter to only retrieve jobs in a certain status. Allowed values are scheduled, queued, running. If omitted, retrieves all statuses.
limit	Paginate the results by specifying the maximum number of jobs per page in the response. This can be any value between 1 and 200. If omitted, defaults to 50.
offset	Paginate the results displayed per page by specifying the amount of offset from the first job instance returned. If omitted, defaults to 0. If you are viewing the first 50 results (page 1) and want to see the next page, set this to offset=51.

Start Job

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "url": "/api/v21.1/services/jobs/72505",
   "job_id": 72505
}

Moves up a scheduled job instance to start immediately. Each time a user calls this API, Vault cancels the scheduled instance of the specified job for the current interval. For example, if a job is scheduled to run daily at 11PM PST, calling this API against it at 4PM PST will cause the job to not run as scheduled at 11PM PST the same day. Vault will resume running the job at 11PM PST the next day regardless of how many times this API is called before 11PM PST the previous day.

This is analogous to the Start Now option in the Vault UI.

POST /api/{version}/services/jobs/start_now/{job_id}

Headers

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

URI Path Parameters

Name	Description
{job_id}	The ID of the scheduled job instance to start.

Managing Vault Java SDK

After you’ve deployed Vault Java SDK code, you may need to perform actions on your code besides additional deployment with a VPK. For example, you may need to download source code or disable a single file.

You also may need to delete a single file rather than all files. However, we do not recommend using the following methods to deploy code as you may introduce or delete code which breaks existing deployed code. For best practices, use the VPK Deploy method.

Retrieve Single Source Code File

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://veepharm.veevavault.com/api/v18.3/code/com.veeva.vault.custom.actions.FindPartners

Response

package com.veeva.vault.custom.actions;
import com.veeva.vault.sdk.api.core.*;
import com.veeva.vault.sdk.api.action.RecordAction;
import com.veeva.vault.sdk.api.action.RecordActionContext;
import com.veeva.vault.sdk.api.action.RecordActionInfo;
import com.veeva.vault.sdk.api.data.Record;
import com.veeva.vault.sdk.api.data.RecordService;
import java.util.List;

@RecordActionInfo(name="get_partners__c", label="Find Partners", object="company__c")
  public class FindPartners implements RecordAction {
    //[...]
  }
}

Retrieve a single source code file from the currently authenticated Vault.

GET /api/{version}/code/{class_name}

Headers

Name	Description
Accept	application/json (default)

URI Path Parameters

Name	Description
class_name	The fully qualified class name of your file.

Enable or Disable Vault Extension

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://veepharm.veevavault.com/api/v18.3/code/com.veeva.vault.custom.actions.MyCustomAction/enable

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Enabled"
}

Enable or disable a deployed Vault extension in the currently authenticated Vault. Only available on entry-point classes, such as triggers and actions.

PUT /api/{version}/code/{class_name}/{enable || disable}

Headers

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

URI Path Parameters

Name	Description
class_name	The fully qualified class name of your file.
enable || disable	Choose to either enable or disable this extension.

Add or Replace Single Source Code File

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://veepharm.veevavault.com/api/v18.3/code
-F "file=@C:\Vault\Extensions\com\veeva\vault\custom\actions\MyCustomAction.java" \

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Modified file",
    "url": "/api/v18.3/code/com.veeva.vault.custom.actions.MyCustomAction"
}

Add or replace a single .java file in the currently authenticated Vault. If the given file does not already exist in the Vault, it is added. If the file already exists in the Vault, the file is updated.

PUT /api/{version}/code

Headers

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

Body Parameters

Name	Description
filerequired	The .java file you wish to add. Maximum allowed size is 1MB.

Delete Single Source Code File

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://veepharm.veevavault.com/api/v18.3/code/com.veeva.vault.custom.actions.MyCustomAction

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Deleted file"
}

Delete a single source code file from the currently authenticated Vault. You cannot delete a code component currently in-use.

DELETE /api/{version}/code

Headers

Name	Description
Accept	application/json (default)

URI Path Parameters

Name	Description
class_name	The fully qualified class name of your file.

Validate Imported Package

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://veepharm.veevavault.com/api/v18.3/services/vobject/vault_package__v/0PI000000000401/actions/validate

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "summary": "Configuration and components (document fields, lifecycles, and workflows) for Documentation Review and Approval process.",
        "author": "lgills@veepharm.com",
        "package_name": "PKG-0031",
        "package_id": "0PI000000000401",
        "source_vault": "13135",
        "package_status": "Error",
        "total_steps": 21,
        "start_time": "18:09:2018 06:31:11",
        "end_time": "18:09:2018 06:31:13",
        "package_error": "",
        "package_steps": [
            {
                "id": "0IS000000000401",
                "name__v": "00010",
                "step_type__v": "Component",
                "step_label__v": "Writer",
                "step_name__v": "writer__c",
                "type__v": "Picklist",
                "deployment_status__v": "Skipped",
                "deployment_action": "No Change (same as Vault)"
            },
            {
                "id": "0IS000000000404",
                "name__v": "00040",
                "step_type__v": "Component",
                "step_label__v": "Vault Help Content",
                "step_name__v": "help_documents__c",
                "type__v": "Doctype",
                "deployment_status__v": "Deployed with warnings",
                "deployment_action": "Update"
            },
            {
                "id": "0IS000000000420",
                "name__v": "00210",
                "step_type__v": "Component",
                "step_label__v": "documentation_review_and_approval__c.submit_for_annual_review__c",
                "step_name__v": "documentation_review_and_approval__c.submit_for_annual_review__c",
                "type__v": "Workflow",
                "deployment_status__v": "Verified",
                "deployment_action": "Add (missing in Vault)"
            }
        ]
    }
}

Validate a previously imported VPK package with Vault Java SDK code. Note that this endpoint does not validate component dependencies for Configuration Migration packages.

POST /api/{version}/services/vobject/vault_package__v/{package_id}/actions/validate

Headers

Name	Description
Accept	application/json (default)

URI Path Parameters

Name	Description
package_id	The ID of the package to validate. You can find this in the API response of a package import, or in the URL of package in the Vault UI.

Retrieve Signing Certificate

Request

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

The following endpoint allows you to retrieve a signing certificate included in a Spark message header to verify that the received message came from Vault.

GET /api/{version}/services/certificate/{cert_id}

Headers

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

URI Path Parameters

Name	Description
{cert_id}	The cert_id is provided in each Spark message in the X-VaultAPISignature-CertificateId header.

Response Details

On SUCCESS, the response includes the public key certificate (.pem) file used for Message Verification.

Queues

Vault Spark is a message queue system that enables applications to send and receive messages to and from durable queues using a First-in, First-Out (FIFO) method.

The following endpoints allow you to manage queues for Spark Messaging and SDK job queues.

The current user must have the relevant Admin: Spark Queues or Admin: SDK Job Queues to perform actions on each queue type. For example, if the API user does not have access to SDK job queues, Retrieve All Queues only returns available Spark messaging queues.

Retrieve All Queues

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "name": "new_study_queue__c",
            "status": "active",
            "type": "outbound",
            "url": "https://myvault.veevavault.com/api/v19.1/services/queues/new_study_queue__c"
        },
        {
            "name": "qms_change_queue__c",
            "status": "active",
            "type": "inbound",
            "url": "https://myvault.veevavault.com/api/v19.1/services/queues/qms_change_queue__c"
        }
    ]
}

Retrieve all queues in a Vault.

GET /api/{version}/services/queues

Headers

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

Response Details

On SUCCESS, the response lists all available queues and their operational statuses.

Retrieve Queue Status

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "name": "new_study_queue__c",
            "status": "active",
            "type": "outbound",
            "delivery": "enabled",
            "messages_in_queue": 365,
            "connections": [
              {
                "name": "aws_study_integration",
                "last_message_delivered": "error"
                "error" {
                    "message_id": "834798hof83998",
                    "date_time": "2012-04-25T21:49:27.719Z",
                    "message": "no response"
                }
              }
    ]
}

Retrieve the status of a specific queue.

GET /api/{version}/services/queues/{queue_name}

Headers

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

URI Path Parameters

Name	Description
{queue_name}	The name of a specific queue. For example, queue__c.

Response Details

On SUCCESS, the response includes the following:

Name	Description
delivery	Indicates whether the delivery status is enabled or disabled.
messages_in_queue	Displays the number of messages in the queue.
last_message_delivered	Indicates if the last message delivered was successful or encountered an error. If ok, the message was delivered successfully. If the message encounters an error, the response includes the message_id, date_time, and the message text.

Disable Delivery

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v19.1/services/queues/new_study_queue__c/actions/disable_delivery

Response

{
    "responseStatus": "SUCCESS"
}

The following endpoint allows you to disable the delivery of messages in an outbound Spark messaging queue, or an SDK job queue. This stop messages from exiting the queue. For example, disabling delivery on an SDK job queue stops messages from being delivered to the processor.

This endpoint is not available for inbound Spark messaging queues. There is no way to stop received messages from processing in an inbound Spark queue.

PUT /api/{version}/services/queues/{queue_name}/actions/disable_delivery

Headers

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

URI Path Parameters

Name	Description
{queue_name}	The name of a specific Queue.

Enable Delivery

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v19.1/services/queues/new_study_queue__c/actions/enable_delivery

Response

{
    "responseStatus": "SUCCESS"
}

The following endpoint allows you to enable the delivery of messages in an outbound Spark messaging queue, or an SDK job queue. This allows messages to exit the queue. For example, enabling delivery on an SDK job queue allows messages to be delivered to the processor.

PUT /api/{version}/services/queues/{queue_name}/actions/enable_delivery

Headers

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

URI Path Parameters

Name	Description
{queue_name}	The name of a specific Queue.

Reset Queue

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v19.1/services/queues/new_study_queue__c/actions/reset

Response

{
 "responseStatus": "SUCCESS",
 "responseMessage": "Deleted messages in queue."
}

Delete all messages in a specific queue. This action is final and cannot be undone.

PUT /api/{version}/services/queues/{queue_name}/actions/reset

Headers

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

URI Path Parameters

Name	Description
{queue_name}	The name of a specific queue.

Custom Pages

The Custom Pages APIs allow you to manage the client code for Custom Pages using a client code distribution. The client code distribution contains:

• The client code that defines how Custom Pages display in the Vault UI
• Metadata that describes the distribution. This metadata must be placed in a manifest file (distribution-manifest.json) in the distribution’s root directory.

Client code distributions are uploaded to and downloaded from Vault as a ZIP file. Learn more about creating a client code distribution for Custom Pages.

When creating Custom Pages, you can also use the Vault REST API to:

• Create a Page component using MDL. Learn more in the Custom Pages documentation.
• Upload and deploy Vault Java SDK server code to Vault. However, we do not recommend using the Vault REST API to deploy server code. Learn more about the recommended way to deploy Custom Pages server code to Vault.

Retrieve All Client Code Distribution Metadata

Request

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v25.1/uicode/distributions

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "name": "hello_world__c",
            "checksum": "997e9213cfe8e87e8527e850e1c0f7d4",
            "size": 2633285
        },
        {
            "name": "data_grid__c",
            "checksum": "aef4acfadc4b50a0324f792e217befd3",
            "size": 493836
        },
        {
            "name": "data_form__c",
            "checksum": "edb0125dd7ac83e66159b25fbdd7172b",
            "size": 2633511
        }
    ]
}

Retrieves a list of all client code distributions in the Vault and their metadata.

This endpoint does not retrieve the contents of distribution manifest files.

GET /api/{version}/uicode/distributions

Headers

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

Response Details

The response lists all client code distributions in the Vault and the following metadata for each distribution:

Field Name	Description
name	The name of the client code distribution.
checksum	A unique string used to identify the distribution.
size	The size of the unzipped client code distribution in bytes.

Retrieve Single Client Code Distribution Metadata

Request

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v25.1/uicode/distributions/custom_pages__c

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "custom_pages__c",
        "checksum": "aef4acfadc4b50a0324f792e217befd3",
        "size": 493836
    }
}

Retrieve metadata for a specific client code distribution, including its name and size.

This endpoint does not retrieve the contents of the distribution manifest file.

GET /api/{version}/uicode/distributions/{distribution_name}

Headers

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

URI Path Parameters

Name	Description
{distribution_name}	The name attribute of the client code distribution to retrieve.

Response Details

The response contains the following metadata:

Field Name	Description
name	The name of the client code distribution.
checksum	A unique string used to identify the distribution.
size	The size of the unzipped client code distribution in bytes.

Download Single Client Code Distribution

Request

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v25.1/uicode/distributions/custom_page__c/code

Download a ZIP file containing the client code distribution directory, including the client code files and the distribution manifest (distribution-manifest.json).

GET /api/{version}/uicode/distributions/{distribution_name}/code

Headers

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

URI Path Parameters

Name	Description
{distribution_name}	The name attribute of the client code distribution to download.

Response Details

On SUCCESS, Vault packages and returns the client code distribution directory as a ZIP file. The HTTP Response Header Content-Type is set to application/zip;charset=UTF-8.

Add or Replace Single Client Code Distribution

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F "file=@custom-page.zip" \
https://myvault.veevavault.com/api/v25.1/uicode/distributions/

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "custom_page__c",
        "updateType": "ADDED",
        "checksum": "5e7db21710fc4cddfaf5ad5eafdf7052"
    }
}

Add or replace client code in Vault by uploading a ZIP file of the client code distribution. Vault unpacks and compares the uploaded distribution with other distributions in the Vault and:

• Adds the distribution if the distribution name is new.
• Replaces a distribution if it has the same name and the client code filenames or contents are different.
• Makes no changes if the distribution name exists and the code is the same.

POST /api/{version}/uicode/distributions/

Headers

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

File Upload

To upload the file, use the multi-part attachment with the file component "file={file_name}". The maximum allowed total file size for all distributions in a Vault is 50 MB.

Response Details

Name	Description
name	The name of the distribution as specified in the manifest file.
updateType	Whether the distribution was added (ADDED), replaced (MODIFIED), or left unchanged (NO_CHANGE).
checksum	A unique string used to identify the distribution and whether the contents have changed.

Delete Single Client Code Distribution

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v25.1/uicode/distributions/custom_page__c

Response

{
"responseStatus": "SUCCESS"
}

Delete a specific client code distribution. To delete a distribution, you must first remove all Page components associated with it from your Vault.

To delete a single file from an existing distribution, re-package the distribution without the file and re-upload the distribution to Vault.

DELETE /api/{version}/uicode/distributions/{distribution_name}

Headers

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

URI Path Parameters

Name	Description
{distribution_name}	The name attribute of the client code distribution to delete.

Direct Data

The Direct Data API provides high-speed read-only data access to Vault. The following endpoints allow you to retrieve available Direct Data files and download them. Learn more about the Direct Data API.

To use the Direct Data API endpoints, your Vault integration user’s security profile and permission set must grant the following permissions:

• Application: API: Access API
• Application: API: Direct Data or Application: API: All API
• Application: All Object Records: All Object Record Read
• Application: Workflow: Query
• Admin: Logs: System Audit
• Admin: Logs: Login Audit
• Admin: Logs: Object Record Audit

Additionally, if your Vault uses documents, your Vault integration user’s security profile and permission set must also grant the following permissions:

• Application: All Documents: All Document Read
• Admin: Logs: Document Audit

Retrieve Available Direct Data Files

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
https://myvault.veevavault.com/api/v24.1/services/directdata/files

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 1042
    },
    "data": [
        {
            "name": "146478-20240213-0000-F",
            "filename": "146478-20240213-0000-F.tar.gz",
            "extract_type": "full_directdata",
            "start_time": "2000-01-01T00:00Z",
            "stop_time": "2024-02-13T00:00Z",
            "record_count": 2085,
            "size": 319078,
            "fileparts": 1,
            "filepart_details": [
                {
                    "name": "146478-20240213-0000-F.001",
                    "filename": "146478-20240213-0000-F.tar.gz.001",
                    "filepart": 1,
                    "size": 319078,
                    "url": "https://myvault.veevavault.com/api/v24.1/services/directdata/files/146478-20240213-0000-F.001"
                }
            ]
        },
        {
            "name": "146478-20240214-0000-F",
            "filename": "146478-20240214-0000-F.tar.gz",
            "extract_type": "full_directdata",
            "start_time": "2000-01-01T00:00Z",
            "stop_time": "2024-02-14T00:00Z",
            "record_count": 76256,
            "size": 2634210,
            "fileparts": 1,
            "filepart_details": [
                {
                    "name": "146478-20240214-0000-F.001",
                    "filename": "146478-20240214-0000-F.tar.gz.001",
                    "filepart": 1,
                    "size": 2634210,
                    "url": "https://myvault.veevavault.com/api/v24.1/services/directdata/files/146478-20240214-0000-F.001"
                }
            ]
        },
        {
            "name": "146478-20240215-0000-F",
            "filename": "146478-20240215-0000-F.tar.gz",
            "extract_type": "full_directdata",
            "start_time": "2000-01-01T00:00Z",
            "stop_time": "2024-02-15T00:00Z",
            "record_count": 76500,
            "size": 2640221,
            "fileparts": 1,
            "filepart_details": [
                {
                    "name": "146478-20240215-0000-F.001",
                    "filename": "146478-20240215-0000-F.tar.gz.001",
                    "filepart": 1,
                    "size": 2640221,
                    "url": "https://myvault.veevavault.com/api/v24.1/services/directdata/files/146478-20240215-0000-F.001"
                }
            ]
        }
  ]
}

Retrieve a list of all Direct Data files available for download.

GET /api/{version}/services/directdata/files

Headers

Name	Description
Accept	application/json (default)

Query Parameters

Name	Description
extract_type	The Direct Data file type: incremental_directdata, full_directdata, or log_directdata. If omitted, returns all files. Learn more about Direct Data file types.
start_time	Specify a time in YYYY-MM-DDTHH:MM:SSZ format. For example, 7AM on January 15, 2024 would use 2024-01-15T07:00:00Z. If omitted, defaults to the Vault’s creation date and time.
stop_time	Specify a time in YYYY-MM-DDTHH:MM:SSZ format. For example, 9AM on January 15, 2024 would use 2024-01-15T09:00:00Z. If omitted, defaults to today’s date and current time.

Response Details

On SUCCESS, Vault lists all Direct Data files available for download. The response includes the following metadata:

Metadata Field	Description
name	The name of the Direct Data file, excluding the .gzip extension.
filename	The name of the Direct Data .gzip file.
extract_type	The Direct Data file type: incremental_directdata, full_directdata, or log_directdata.
start_time	The start time in YYYY-MM-DDTHH:MM:SSZ format. If this query parameter is not provided in the request, the start time defaults to the Vault’s creation date and time.
stop_time	The stop time in YYYY-MM-DDTHH:MM:SSZ format. If the query parameter is not provided in the request, the stop time defaults to today’s date and current time.
record_count	The number of records for a given extract. This may show as zero records if there is no data for the given time period.
size	The size of the Direct Data file in bytes.
fileparts	The number of file parts for a given Direct Data file. Extract files greater than 1 GB in size are split into multiple file parts.
filepart_details	A list of all file parts and their metadata.

Download Direct Data File

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
https://myvault.veevavault.com/api/v24.1/services/directdata/files/146478-20240211-0000-N.001

Response Headers

Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: attachment; filename="146478-20240211-0000-N.tar.gz.001"

Download a Direct Data file.

GET /api/{version}/services/directdata/files/{name}

Headers

Name	Description
Accept	application/json (default)

URI Path Parameters

Name	Description
{name}	The name of the Direct Data file part. Obtain this from the Retrieve Available Direct Data Files request. For example, 146478-20240213-0000-F.001.

Response Details

On SUCCESS, Vault downloads the requested Direct Data file. The file is named according to the following format: {vaultid}-{date}-{stoptime}-{type}.tar.gz.{filepart}.

Until the first Full file is generated, no Incremental files are available for download. The API may return the following standard error if an Incremental file is unavailable for download:

FAILURE: Initial file being generated. Please check again later.

Clinical Operations

To use this API, you must have the appropriate Clinical application. Learn more about Clinical Operations in Vault Help.

Create EDLs

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
https://myvault.veevavault.com/api/v16.0/vobjects/study__v/00S07710/actions/etmfcreateedl

Response

{
  "responseStatus": "SUCCESS",
  "url": "https://myvault.veevavault.com/api/v15.0/services/jobs/1201",
  "job_id": 1201
}

Create a new Expected Document List.

POST /api/{version}/vobjects/study__v/{study_id}/actions/etmfcreateedl

Headers

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

URI Path Parameters

Name	Description
{study_id}	The ID of the study.

Query Parameters

Name	Description
applyWhereEdlItemsExist	Optional: If set to true, the Create EDL job is applied to existing EDLs. If omitted, defaults to false. This is analogous to the Apply template where expected documents already exist option in the Vault UI.

Recalculate Milestone Document Field

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"recalculate_milestones.csv" \
https://myvault.veevavault.com/api/v21.3/objects/documents/milestones/actions/recalculate

Example CSV Input File

id
7652
9875
541

Response

{
   "responseStatus": "SUCCESS",
   "responseMessage": "SUCCESS"
}

Recalculate themilestone__v field on a specified set of documents.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

POST /api/{version}/objects/documents/milestones/actions/recalculate

Headers

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

Body Parameters

Prepare a CSV input file with document id values in an id column. Invalid values or invalid columns are ignored.

Apply EDL Template to a Milestone

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "edl_id=0EL000000000105" \
https://myvault.veevavault.com/api/v16.0/vobjects/milestone__v/0M0007710/actions/etmfcreateedl

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 9901,
  "url": "/api/v16.0/services/jobs/9901"
}

Apply an EDL template to a Milestone object record.

POST /api/{version}/vobjects/milestone__v/{milestone_id}/actions/etmfcreateedl

Headers

Name	Description
Content-Type	application/x-www-form-urlencoded
Accept	application/json

URI Path Parameters

Name	Description
{milestone_id}	The ID of the milestone.

Body Parameters

Field Name	Description
edl_id	The ID of the EDL template to apply to this milestone.

Create Milestones from Template

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://myvault.veevavault.com/api/v19.1/vobjects/study__v/0ST000000000202/actions/createmilestones

Response

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

Use this request to initiate the Create Milestones from Template user action on a study, study country, or site.

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value. This endpoint only works with the study__v, study_country__v, or site__v objects.
{object_record_id}	The object record ID field value.

Response Details

Name	Description
job_id	The ID value for the job.
url	URL to retrieve the current status of the job.

Execute Milestone Story Events

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Clinical_Operations\story_events.csv" \
https://myvault.veevavault.com/api/v23.1/app/clinical/milestone/study_country__v/actions/applytemplate

Response

"id","story_event__v","status","Job id/Error"
"0SC000000001001","OOV000000000102","SUCCESS","327801"

Use this request to create Milestones based on specific Story Events for multiple studies, study countries, or sites. You can include up to 500 rows in the CSV input.

POST /api/{version}/app/clinical/milestone/{object_name}/actions/applytemplate

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name__v field value. This endpoint only works with the study__v, study_country__v, or site__v objects.

Body Parameters

The CSV file must have the following columns:

Name	Description
id	The object record ID for which to create a milestone. This record must be of the same object indicated in the {object_name} path parameter. Instead of id, you can use a unique field defined by the idParam query parameter.
story_event__v	Include the name or ID of a single story event to define the milestone sets to create. For example, story_event__v=OOV000000000705 or story_event__v.name__v=Candidate Country.
external_id__v	Instead of id, you can use this user-defined object external ID.

Query Parameters

Name	Description
idParam	If you’re identifying objects 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.

Response Details

On SUCCESS, Vault returns the job ID.

Generate Milestone Documents

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
"https://myvault.veevavault.com/api/v24.1/app/clinical/milestone/actions/generatemilestonedocuments"

Response

{
    "responseStatus": "SUCCESS",
    "SUCCESS": "Successfully generated milestone documents"
}

Generate Milestone Document records for up to 500 milestones. Milestone Document records are used to display matched document details in the Milestone Workspace.

Learn more about the Milestone Workplace in Vault Help.

POST /api/{version}/app/clinical/milestone/actions/generatemilestonedocuments

Headers

Name	Description
Content-Type	text/csv

Body Parameters

The CSV file must have a single column with the header id. List each milestone ID on a separate row below. Including more than 500 rows results in an error.

Response

On SUCCESS, Vault starts an Add Expected Documents job to create the Milestone Document records. On completion, Vault sends an email notification containing a link to download a list in CSV format of successfully created records.

Veeva Site Connect: Distribute to Sites

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://myvault.veevavault.com/api/v22.2/app/clinical/safety_distributions/V56000000001004/actions/send

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "job_id": 93601,
        "message": "Distributing documents. You will receive a notification when processing is complete."
   }
}

This API allows sponsors and CROs to send Safety reports and letters to Sites. Learn more about Safety Distributions in Vault Help.

POST /api/{version}/app/clinical/safety_distributions/{id}/actions/send

Headers

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

URI Path Parameters

Name	Description
{id}	The record ID of the Safety Distribution record to send. Must be in a Ready or Distributed state.

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.

Populate Site Fee Definitions

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-d '{ "target_study": "0ST000000006004", "source_study": [ "0ST000000006002", "0ST000000006003" ] }'
https://myvault.veevavault.com/api/v23.1/app/clinical/payments/populate-site-fee-definitions

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "data": {
    "status": "SUCCESS",
    "source": "study__v",
    "num_site_fee_defs_created": 2,
    "num_site_fee_defs_duplicates": 2,
    "num_errors": 0
  }
}

Given an existing study with Site Fee Definitions or an eligible Site Fee Template, automatically generate Site Fee Definitions for a new target study. This endpoint is only available in CTMS Vaults with the Vault Payments add-on.

POST /api/{version}/app/clinical/payments/populate-site-fee-definitions

Headers

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

Body Parameters

Name	Description
target_study	The new study to populate with Site Fee Definitions.
source_study	Optional: To copy the Site Fee Definitions from studies, include an array with the study IDs. You must choose either source_study or source_template.
source_template	Optional: To copy the Site Fee Definitions from Site Fee Templates, include an array with the template IDs. You must choose either source_study or source_template.

Populate Procedure Definitions

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
- d '[
{
        "source_holder_object_name" : "study__v",
        "source_holder_object_ids" : ["0ST000000001001"],
        "destination_holder_object_name" : "study__v",
        "destination_holder_object_id" : "0ST000000003001"
}
]'
https://myvault.veevavault.com/api/v25.1/app/clinical/ctms/populate-procedure-definitions

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "data": {
        "status": "SUCCESS",
        "source": "study__v",
        "numProcedureDefsCreated": 2,
        "numProcedureDefsDuplicates": 0,
        "numErrors": 0
    }
}

Use this request to initiate the Populate Procedure Definitions user action. This action creates Procedure Definitions for a target study from a source study or an existing Procedure Template.

Learn more about Procedure Definitions in Vault Help.

POST /api/{version}/app/clinical/ctms/populate-procedure-definitions

Headers

Name	Description
Content-Type	application/json
Accept	application/json

Body Parameters

Name	Description
source_holder_object_namerequired	The name of the object to create Procedure Definitions from. Possible values are study__v or procedure_template__v.
source_holder_object_idsrequired	An array of study or Procedure Template IDs to copy Procedure Definitions from.
destination_holder_object_namerequired	The name of the object to create Procedure Definitions for. This must always be study__v.
destination_holder_object_idrequired	The ID of the study to populate with Procedure Definitions.

Response Details

On SUCCESS, the response returns the number of Procedure Definitions created, the number of duplicate Procedure Definitions that exist for the indicated study, and the number of errors encountered.

QualityDocs

To use this API, you must have Vault QualityDocs. Learn more about QualityDocs in Vault Help.

Document Role Check for Document Change Control

Request

$ curl -X POST
https://myvault.veevavault.com/api/v19.2/vobjects/document_change_control__v/00S000000000101/actions/documentrolecheck \
-H "Authorization: {SESSION_ID}" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'application_role: approver__c'

Response

{
  "responseStatus": "SUCCESS",
  "data": {
    "check_result": true
  }
}

Check if any document added to a Document Change Control (DCC) record has one or more users in a specified Application Role. This API only checks documents added to the standard Documents to be Released and Documents to be Made Obsolete sections.

POST /api/{version}/vobjects/document_change_control__v/{object_record_id}/actions/documentrolecheck

Headers

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

URI Path Parameters

Name	Description
{object_record_id}	The {id} field value of the document_change_control__v object record.

Body Parameters

Name	Description
{application_role}	The name of the application_role__v.

Response Details

On SUCCESS, the response includes the Boolean check_result field. A value of true indicates that the given Application Role is in use on at least one document in the given Document Change Control record.

QMS

To use this API, you must have Vault QMS. Learn more about QMS in Vault Help.

Manage Quality Team Assignments

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\QMS\update_quality_team_members.csv" \
https://myvault.veevavault.com/api/v23.2/app/quality/qms/teams/vobjects/quality_event__qdm/actions/manageassignments

Response

{
    "responseStatus": "SUCCESS",
    "jobId": "243001"
}

Manage Quality Team members on existing records. This endpoint does not support initial Quality Team record migrations or the creation of new Quality Teams on existing process records. Vault performs updates to Quality Team assignments asynchronously on behalf of the user. Learn more about Quality Teams in Vault Help.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

This operation respects the following configurations which impact business logic:

• Minimum required and maximum users
• Constraining application roles and user assignment eligibility
• Object records in locked states
• New assignments for active users
• Exclusive role membership restrictions
• Moving object records to a destination state upon membership completion
• Task assignment for new and removed users

POST /api/{version}/app/quality/qms/teams/vobjects/:{object_name}/actions/manageassignments

Headers

Name	Description
Content-Type	text/csv
Accept	text/csv

URI Path Parameters

Name	Description
{object_name}	The object name__v field value for the team-enabled object. For example, risk_event__v, investigation__qdm, quality_event__qdm.

Body Parameters

Upload parameters as a CSV file.

Name	Description
record_id	The object record’s id field value. This record must belong to the object indicated in the {object_name} path parameter.
user_id	The id value of the Vault user whose assignment you wish to manage for the Quality Team.
application_role	The name of the application_role__v of the Quality Team Role to which to assign the user on the Quality Team. For example, record_owner__c.
operation	Indicate whether to ADD or REMOVE the provided user from the Quality Team. The value of this parameter is case-sensitive.

Response Details

On SUCCESS, the response returns the job_id for the action, and the authenticated user will receive an email notification with details of any failures that occur.

QualityOne

To use this API, you must have Vault QualityOne. Learn more about QualityOne in Vault Help.

Manage Team Assignments

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\QMS\manage_team_assignments.csv" \
https://myvault.veevavault.com/api/v24.3/app/qualityone/qms/teams/vobjects/car__v/actions/manageassignments

Example CSV Request Body

record_id,user_id,operation,application_role
VC400000001001,1962069,ADD,approver__c

Response

{
    "responseStatus": "SUCCESS",
    "jobId": "251801"
}

Manage Team assignments by adding users to Team Roles and removing users from Team Roles in batches on one or more existing records. Vault performs updates to Team assignments asynchronously on behalf of the user. When the job completes, Vault returns the job_id and an email notification with a CSV file containing the results of the job. This endpoint does not support initial Team record migrations or the creation of new Teams or Team Roles. Learn more about QualityOne Teams in Vault Help.

• The maximum CSV input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard RFC 4180 format, with some exceptions.
• The maximum batch size is 500.

This operation respects the following configurations which impact business logic:

• Minimum required and maximum users
• Constraining application roles and user assignment eligibility
• Object records in locked states
• New assignments for active users
• Exclusive role membership restrictions
• Moving object records to a destination state upon membership completion
• Task assignment for new and removed users

POST /api/{version}/app/qualityone/qms/teams/vobjects/:{object_name}/actions/manageassignments

Headers

Name	Description
Content-Type	text/csv
Accept	text/csv

URI Path Parameters

Name	Description
{object_name}	The object name__v field value for the team-enabled object. For example, risk_event__v, investigation__qdm, audit__qdm.

Body Parameters

Upload parameters as a CSV file.

Name	Description
record_id	The object record’s id field value. This record must belong to the object indicated in the {object_name} path parameter.
user_id	The id value of the Vault user whose assignment you wish to manage.
application_role	The name__v value of the application_role__v specified on the target Team Role. For example, record_owner__c.
operation	Indicate whether to ADD or REMOVE the provided user from the Team. The value of this parameter is case-sensitive. REMOVE executes before ADD.

Response Details

On a responseStatus of SUCCESS, the response returns the job_id for the action. The authenticated user receives a Vault notification and email with the job results and a CSV file containing the IDs of the records updated, the results, and details about any failures.

RIM Submissions Archive

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

Import Submission

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "file=/nda123456/0000" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/import

Response

{
  "responseStatus": "SUCCESS",
  "warnings": [
    {
      "type": "APPLICATION_MISMATCH",
      "message": "Application folder name does not match the Application record name."
    },
    {
      "type": "SUBMISSION_MISMATCH",
      "message": "Submission folder name does not match the Submission record name."
    }
  ],
  "job_id": 1301,
  "url": "/api/v15.0/services/jobs/1301"
}

Import a submission into your Vault.

Before submitting this request:

• You must be assigned permissions to use the API and have permissions to view and edit the specified submission__v object record.
• You must create the corresponding object records for the Submission and Application objects in your Vault.
• You must create and upload a valid submission import file or folder to file staging. The submission to import must be in a specific location and format.

Submission Import File Location & Structure

The submission import file must be located in one of the following places, and must be in a specific folder structure.

At the Root

If your submission import is located at the file staging root, it must follow the following structure:

/SubmissionsArchive/{application_folder}/{submission_file_or_folder}

• {application_folder}: This required folder can have any name you wish.
• {submission_file_or_folder}: If this is a file containing your submission, it must be a .zip or .tar.gz. If this is a folder, it must contain your submission to import. This required folder can have any name you wish.

For example, /SubmissionsArchive/nda654321/0001.zip.

Within a User Folder

In some cases, your Vault user permissions may prevent you from uploading directly to the file staging root. In these cases, you must upload to your user folder using the following structure:

/u[ID]/Submissions Archive Import/{application_folder}/{submission_folder}

• {application_folder}: This required folder can have any name you wish.
• {submission_folder}: The folder containing your submission to import. This required folder can have any name you wish. Vault does not support importing .zip or .tar.gz files from user folders.

For example, /u5678/Submissions Archive Import/nda123456/0013.

Endpoint

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

Headers

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

URI Path Parameters

Name	Description
{submission_id}	The id field value of the submission__v object record. To get this value, you can Retrieve Object Record Collection for submission__v.

Body Parameters

Name

Description

file

Use the file parameter to specify the location of the submission folder or ZIP file previously uploaded to file staging. In the request, add the file parameter to your input and enter the path to the submission folder relative to the file staging root, for example, /SubmissionsArchive/nda123456/0000, or to the path to your user file staging folder, for example, /u5678/Submissions Archive Import/nda123456/0000. Vault does not support importing .zip or .tar.gz files from user folders.

Response Details

On SUCCESS, the response includes the following information:

• job_id - The Job ID value is used to retrieve the status and results of the binder export request.
• url - The URL to retrieve the current status of the import request.

You may also receive one or more warnings. The warnings shown above indicate that the folders being imported do not match the object records in our Vault. To fix this warning, we can change the folder name or object record name. However, warnings are not fatal and you may choose to take no action.

Before submitting this request, we created a submission__v object record and application__v object record in our Vault. We also created submissions ZIP file containing a “Submission” folder and “Application” folder. This was loaded to file staging awaiting import. Ideally, we would have named and structured the folders to match that of the submission that was sent to the health authority and which we are now archiving. However, this is not critical to the import process.

Retrieve Submission Import Results

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/import/1301/results

Response

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

After Vault has finished processing the submission import job, use this request to retrieve the results of the completed submission binder.

Before submitting this request:

• You must be assigned permissions to use the API and permissions to view the specified submission__v object record.
• There must be a previously submitted and completed submission import request, i.e., the status of the import job must be no longer active.

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

Headers

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

URI Path Parameters

Name	Description
{submission_id}	The id field value of the submission__v object record. See Retrieve Object Record Collection above.
{job_id}	The jobId field value returned from the Import Submission request above.

Response Details

On SUCCESS, the response includes the following information:

Field Name	Description
id	The id field value of the submission binder which was created by the imported files.
major_version_number__v	The major version number of the binder.
minor_version_number__v	The minor version number of the binder.

To retrieve the metadata from the newly created submission binder, send GET to /api/{version}/objects/binders/{id}.

Retrieve Submission Metadata Mapping

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/ectdmapping

Response

{
 "responseStatus": "SUCCESS",
    "responseDetails": {
    "total": 2
    },
    "data": [
    {
      "name__v": "1675_00S000000000802",
      "external_id__v": null,
      "drug_substance__v":"Ethyl Alcohol",
      "drug_substance__v.name__v": "",
      "xml_id": "m2-3-s-drug-substance",
      "manufacturer__v":"Veeva",
      "manufacturer__v.name__v": ""
    },
    {
      "name__v": "1681_00S000000000802",
      "external_id__v": null,
      "nonclinical_study__v":"Study001",
      "nonclinical_study__v.name__v": "",
      "xml_id": "S001"
    }
  ]
}

Retrieve the metadata mapping values of an eCTD submission package.

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

Headers

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

URI Path Parameters

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

Response Details

On SUCCESS, the response includes the following information for each XML metadata node which requires mapping:

Field Name	Description
name__v	The name of the metadata mapping record in the submission metadata.
external_id__v	The external ID of the metadata mapping record. This value is only available if the mappings were created or updated externally.
xml_id	The XML ID (leaf_id) of the section being mapped. This is an identifier from the imported XML of the XML node. This is analogous to the submission_metadata__v.tag_id__v.

Mapping Fields:

Possible mappings include: clinical_site__v, clinical_study__v, drug_product__v, drug_substance__v, indication__v, manufacturer__v, and nonclinical_study__v.

Mapping fields are returned as a pair of properties: a source property that has the mapping identifier from the imported XML and a second property as [mapping].name__v which specifies the target object record. If the second property is empty, the mapping has not been completed. See Update Submission Metadata Mapping below.

Update Submission Metadata Mapping

Response

[
    {
      "external_id__v": null,
      "drug_substance__v.name__v": "ethyl alcohol",
      "name__v": "1675_00S000000000802",
      "xml_id": "m2-3-s-drug-substance",
      "manufacturer__v.name__v": "Veeva Chemical"
    },
    {
      "external_id__v": null,
      "drug_substance__v.name__v": "ethyl alcohol",
      "name__v": "1677_00S000000000802",
      "xml_id": "m3-2-s-drug-substance",
      "manufacturer__v.name__v": "Veeva Chemical"
    },
    {
      "external_id__v": null,
      "nonclinical_study__v.name__v": "S001",
      "name__v": "1681_00S000000000802",
      "xml_id": "S001"
    },
    {
      "external_id__v": null,
      "clinical_study__v.name__v": "S001",
      "name__v": "1693_00S000000000802",
      "xml_id": "S001"
    }
]

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/ectdmapping

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "name__v": "1675_00S000000000802",
            "responseStatus": "SUCCESS"
        },
        {
            "name__v": "1677_00S000000000802",
            "responseStatus": "SUCCESS"
        },
        {
            "name__v": "1681_00S000000000802",
            "responseStatus": "SUCCESS"
        },
        {
            "name__v": "1693_00S000000000802",
            "responseStatus": "SUCCESS"
        }
    ],
    "responseDetails": {
        "total": 4
    }
}

Update the mapping values of a submission.

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

Headers

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

URI Path Parameters

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

Note that XML identifiers are read-only and cannot be updated via the API. If including XML identifiers in the request, the values will be ignored.

Remove Submission

Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/import

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 15002,
  "url": "/api/v15.0/services/jobs/15002"
}

Delete a previously imported submission from your Vault.

By removing a submission, you delete any sections created in the archive binder as part of the submission import. This will also remove any documents in the submission from the archive binder. This does not delete the documents from Vault, but does mean that they no longer appear in the Viewer tab and users will not be able to access them using cross-document navigation. You must re-import the submission to make it available.

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

Headers

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

URI Path Parameters

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

Cancel Submission

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/import?cancel=true

Response

{
  "responseStatus": "SUCCESS"
}

You can use this request on a submission object record that has a Submissions Archive Status (archive_status__v) of:

Name	Description
IMPORT_IN_PROGRESS	This will terminate the import job and set the archive_status__v field on the submission__v object record to “Error”. The submission must be removed before a re-import can be done. See Remove Submission above.
REMOVAL_IN_PROGRESS	This will terminate the import removal job and set the archive_status__v field on the submission__v object record to “Error”. The submission must be removed before a re-import can be done. See Remove Submission above.
IMPORT_IN_QUEUE	This will remove the import from the job queue and set the archive_status__v field on the submission__v object record to “Null”. See Import Submission above.
REMOVAL_IN_QUEUE	This will remove the import removal from the job queue and set the archive_status__v field on the submission__v object record to “Error”. See Import Submission above.

To retrieve the archive_status__v, GET /api/{version}/vobjects/submission__v/{submission_id}. See Retrieve Object Record above.

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

Headers

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

URI Path Parameters

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

Query Parameters

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

Export Submission

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "URL": "https://myvault.veevavault.com/api/v15.0/services/jobs/1201",
  "job_id": 1201
}

Use the following requests to export the latest or most recent version of a Submissions Archive binder. These endpoints do not support the export of submissions binders published by RIM Submissions Publishing. Learn more about RIM Submissions Publishing in Vault Help.

To export the latest version of a Submissions Archive binder:

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

To export a specific version of a Submissions Archive binder:

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value. See Retrieve Binders above.
{major_version}	The major_version_number__v field value of the binder.
{minor_version}	The minor_version_number__v field value of the binder.
{submission_id}	The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Response Details

On SUCCESS, the response includes the following information:

• URL - The URL to retrieve the current status of the export job.
• job_id - The Job ID value is used to retrieve the status and results of the request.

Export Partial Submission

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Binders\export-submissions-binder-sections.csv" \
https://myvault.veevavault.com/api/v15.0/objects/binders/454/1/0/actions/export?submission=00S000000000101

Response

{
  "responseStatus": "SUCCESS",
  "URL": "https://myvault.veevavault.com/api/v15.0/services/jobs/1201",
  "job_id": 1201
}

Use this request to export only specific sections and documents from the latest version of a submissions binder in your Vault. This will export only parts of the binder, not the complete binder. Exporting a binder section node will automatically include all of its subsections and documents therein.

Before submitting this request:

• The Export Binder feature must be enabled in your Vault.
• You must be assigned permissions to use the API.
• You must have the Export Binder permission.
• You must have the View Document permission for the binder. Only documents in the binder which you have the View Document permission are available to export.

To export the latest version of a submissions binder:

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

To export a specific version of a submissions binder:

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value. See Retrieve Binders above.
{major_version}	The major_version_number__v field value of the binder.
{minor_version}	The minor_version_number__v field value of the binder.
{submission_id}	The id field value of the submission__v object record. See Retrieve Object Record Collection above.

Body

Create a CSV or JSON input file with the id values of the binder sections and/or documents to be exported. You may include any number of valid nodes. Vault will ignore id values which are invalid.

Response Details

On SUCCESS, the response includes the following information:

• URL - The URL to retrieve the current status of the export job.
• job_id - The job_id field value is used to retrieve the results of the export request.

Retrieve Submission Export Results

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "job_id": 1201,
  "id": 454,
  "major_version_number__v": 1,
  "minor_version_number__v": 0,
  "file": "/1201/454/1_0/RIM Submission Packet.zip",
  "user_id__v": 44533
}

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

Before submitting this request:

• You must have previously requested a submission export job (via the API) which is no longer active.
• You must have a valid job_id field value returned from the Export Submission request above.

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

Headers

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

URI Path Parameters

Name	Description
{job_id}	The jobId field value returned from the Export Submission request above.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
job_id	The job_id field value of the submission export request.
id	The id field value of the exported submission.
major_version_number__v	The major version number of the exported submission.
minor_version_number__v	The minor version number of the exported submission.
file	The path/location of the exported submission. This is packaged in a ZIP file on file staging.
user_id__v	The id field value of the Vault user who initiated the submission export job.

Download Exported Submission Files via File Staging

Once your submission export job has been successfully completed, you can download the files from file staging.

Prerequisites

Before downloading the files, the following conditions must be met:

• The submission export job must have been successfully completed.
• The API user must have a permission set which allows the Application: File Staging: Access permission.

Downloading the Files

The exported submission is packaged in a ZIP file on file staging. Learn more.

Copy into Content Plan

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
https://myvault.veevavault.com/api/v21.3/app/rim/content_plans/actions/copyinto

Response: Content Plan

{
   "responseStatus": "WARNING",
   "warnings": [
       {
           "type": "TEMPLATE_MISMATCH",
           "message": "The templates of the source and target do not align."
       },
       {
           "type": "LEVEL_MISMATCH",
           "message": "Level of the source record does not match the level of the target location."
       }
   ],
   "job_id": 104448
}

Response: Content Plan Item

{
   "responseStatus": "WARNING",
   "warnings": [
       {
           "type": "LEVEL_MISMATCH",
           "message": "Level of the source record does not match the level of the target location."
       },
       {
           "type": "TEMPLATE_MISMATCH",
           "message": "The templates of the source and target do not align."
       }
   ],
   "createdCPIRecordId": "0EI000000004001"
}

This API allows you to copy a content plan section or item to reuse existing content and prevent duplicate work. For example, you may want to copy a clinical study or quality section and its matched documents for a similar submission to a different application.

This API functionality has the same behavior and limitations as copying through the Content Plan Hierarchy Viewer in the Vault UI. Learn more about copying into content plans in Vault Help.

POST /api/{version}/app/rim/content_plans/actions/copyinto

Headers

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

Body Parameters

Name	Description
source_id	The ID of the content plan or content plan item to copy.
target_id	The ID of the parent content plan, which is where the source content plan will be copied under. Cannot be inactive.
order	An integer indicating the position in the target content plan where the source content plan will be copied. A value of 1 indicates the first position in the target content plan.
copy_documents	If true, matched documents are included in the copy. If false, matched documents are not included in the copy. Cannot be omitted.

Response Details

Copying a content plan is an asynchronous process which provides a job_id. When the copy is complete, you’ll receive an email notification.

Copying a content plan item is a synchronous process which provides the createdCPIRecordId of the newly copied content plan item.

Safety

To use this API, you must have Vault Safety. Learn more about Vault Safety in Vault Safety Help.

Intake

Intake Inbox Item

Request

curl --location --request POST 'https://myvault.veevavault.com/api/v20.2/app/safety/intake/inbox-item' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: {SESSION_ID}' \
--form 'file=@"/directory/labrinone_literature_case.xml"' \
--form 'origin-organization="vertio_biopharma__c"' \
--form 'format="e2br3__v"' \
--form 'organization="vault_customer__v"'

Response

{
    "responseStatus": "SUCCESS",
    "url": "/api/v21.2/app/safety/intake/status?inbound_id=V29000000004001",
    "intake_id": "V29000000004001"
}

Use the following endpoint to import an Inbox Item from an E2B (R2) or E2B (R3) file containing one or more Individual Case Safety Reports (ICSRs):

POST /api/{version}/app/safety/intake/inbox-item

Headers

Name	Description
Content-Type	multipart/form-data

Body Parameters

Name	Description
file	The filepath of the E2B file to be imported.
origin-organization	(Optional) The Vault API Name for the Organization sending the E2B file. This parameter sets the Origin Organization on the Inbound Transmission. If no value is provided, the Origin Organization is left blank.
format	The format of the file being imported. This must match the Vault API Name of the Inbound Transmission Format picklist value. Must be an E2B format.
organization	(Optional) To specify which organization to send the Case to, enter the Vault API Name for the Organization record. If no value is provided, the Organization is set to vault_customer__v. Note that the Organization record type must be Sponsor.
transmission-profile	(Optional) The Vault API Name of the Transmission Profile to be used for E2B Intake. These parameters are used for Narrative Template Override and Inbox Item Auto-Promotion. The Transmission Profile record type must be Connection. This parameter is required for Automated Case Promotion (see Vault Safety Help for more information). If no transmission-profile is specified, Vault will use the parameters on the general_api_profile__v.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
url	The URL to retrieve the current status of the import request.
intake_id	The Inbound Transmission ID of the E2B import.

On FAILURE, the response returns a message describing the reason for the failure.

Intake Imported Case

Request

curl --location --request POST 'https://myvault.veevavault.com/api/v20.2/app/safety/intake/imported-case' \
--header 'Authorization: {SESSION_ID}' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@"/directory/cholecap_vaers_literature_case.xml"' \
--form 'format="e2br3__v"' \
--form 'organization="verteo_biopharma__c"' \
--form 'origin-organization="fda__v"'

Response

{
    "responseStatus": "SUCCESS",
    "url": "/api/v21.2/app/safety/intake/status?inbound_id=V29000000005001",
    "intake_id": "V29000000005001"
}

Use the following endpoint to import an Imported Case from an E2B (R2) or E2B (R3) file containing one or more Individual Case Safety Reports (ICSRs):

POST /api/{version}/app/safety/intake/imported-case

Headers

Name	Description
Content-Type	multipart/form-data

Body Parameters

Name	Description
file	The filepath of the E2B file to be imported.
origin-organization	(Optional) The Vault API Name for the Organization sending the E2B file. This parameter sets the Origin Organization on the Inbound Transmission. If no value is provided, the Origin Organization is left blank.
format	The format of the file being imported. This must match the Vault API Name of the Inbound Transmission Format picklist value. Must be an E2B format or other__v. If other__v, the system does not attempt E2B import or forms processing and instead creates an empty Inbox Item linked to the source document.
organization	(Optional) To specify which organization to send the Case to, enter the Vault API Name for the Organization record. If no value is provided, the Organization is set to vault_customer__v. Note that the Organization record type must be Sponsor.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
url	The URL to retrieve the current status of the import request.
intake_id	The Inbound Transmission ID of the E2B import.

On FAILURE, the response returns a message describing the reason for the failure.

Retrieve Intake Status

Request

curl --location --request GET 'https://myvault.veevavault.com/api/v20.2/app/safety/intake/status?inbound_id=V29000000005001' \
--header 'Authorization: {SESSION_ID}' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@"/directory/e2b_r3_restolar.xml"' \
--form 'format="e2br3__v"'

Response

{
    "status": "complete",
    "ack-retrieval": "/api/v21.2/app/safety/intake/ack?inbound_id=V29000000005001",
    "inbound-transmission": "V29000000005001",
    "inbound-document": "7_0_1",
    "number-of-icsrs": 1,
    "number-success/warning": 1,
    "number-failures": 0,
    "icsr-details": [
        {
            "icsr": "V2B000000005001",
            "inbound-transmission": "V29000000005001",
            "inbound-document": "7_0_1",
            "ack-retrieval": "/api/v21.2/app/safety/intake/ack?inbound_id=V29000000005001",
            "status": "Success"
        }
    ]
}

Use the following endpoint to retrieve the status of an intake API call:

GET /api/{version}/app/safety/intake/status

The Retrieve Intake Status endpoint can be used with the following Safety intake endpoints:

• Intake Inbox Item
• Intake Imported Case

Headers

Name	Description
Accept	application/json

URL Parameters

Name	Description
inbound_id	The Inbound Transmission ID for the ICSR intake job.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
status	Processing status for the intake job.
ack-retrieval	URL to retrieve the ACK. This parameter only applies to E2B intake file types.
inbound-transmission	ID or link to the Inbound Transmission for the entire intake job.
inbound-document	ID or link to the Vault document created from E2B file for the entire intake job.
number-cases	Total number of cases found in the intake file, including both successes and failures.
number-successes	Number of cases that were imported successfully, including those with warnings.
number-failures	Number of cases that failed to import.
icsr-details	An array containing details for each individual case within the file. This will be populated with a single entry for single E2B files.
icsr-details.case	ID of the Imported Case record. Present only for Imported Case intake jobs.
icsr-details.inbox-item	ID of the Inbox Item record. Present only for Inbox Item intake jobs.
icsr-details.inbound-transmission	ID of the Inbound Transmission for this case.
icsr-details.inbound-document	ID of the Vault document for the case. For multi-case E2B files, the E2B for individual cases is split out into separate documents.
icsr-details.ack-retrieval	URL for the ACK for the case. This parameter only applies to E2B intake file types.
icsr-details.status	Status of the Imported Case or Inbox Item.

On FAILURE, the response returns a message describing the reason for the failure.

Retrieve ACK

Request

curl --location --request GET 'https://myvault.veevavault.com/api/v20.2/app/safety/intake/ack?inbound_id=V29000000005001' \
--header 'Authorization: {SESSION_ID}' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@"/directory/e2b_r3_restolar.xml"' \
--form 'format="e2br3__v"'

Response

<?xml version="1.0" encoding="utf-8"?>
<MCCI_IN200101UV01 xmlns="urn:hl7-org:v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:hl7-org:v3 http://eudravigilance.ema.europa.eu/xsd/multicacheschemas/MCCI_IN200101UV01.xsd" ITSVersion="XML_1.0">
    <!--ACK.M.1 - Acknowledgement Batch Number-->
    <id root="2.16.840.1.113883.3.989.2.1.3.20" extension="b4e413b2-7263-48b5-b957-839fea7c7edc"/>
    <!--ACK.M.4 - Date of Message-->
    <creationTime value="20210618154357-0400"/>
    <!--Mandatory element-->
    <responseModeCode code="D"/>
    <interactionId extension="MCCI_IN200101UV01" root="2.16.840.1.113883.1.6"/>
    <MCCI_IN000002UV01>
        <!--ACK.B.r.2 - Local Report Number-->
        <id root="2.16.840.1.113883.3.989.2.1.3.19" extension="VERN-123-123-123"/>
        <!--ACK.M.4 - ACK Date of Batch Transmission-->
        <creationTime value="20210618154357-0400"/>
        <interactionId root="2.16.840.1.113883.1.18" extension="MCCI_IN000002UV01"/>
        <processingCode code="P"/>
        <processingModeCode code="T"/>
        <acceptAckCode code="NE"/>
        <receiver typeCode="RCV">
            <device determinerCode="INSTANCE" classCode="DEV">
                <!--ACK.B.r.3: ICSR Message Receiver Identifier-->
                <id root="2.16.840.1.113883.3.989.2.1.3.16" extension="ICHTEST"/>
            </device>
        </receiver>
        <sender typeCode="SND">
            <device determinerCode="INSTANCE" classCode="DEV">
                <!--ACK.B.r.4: ICSR Message Sender Identifier-->
                <id root="2.16.840.1.113883.3.989.2.1.3.15" extension="DSJP"/>
            </device>
        </sender>
        <attentionLine>
            <!--ACK.B.r.5 - Receipt date-->
            <keyWordText codeSystemVersion="2.0" codeSystem="2.16.840.1.113883.3.989.2.1.1.24" code="1"/>
            <value value="20120720100001+09" xsi:type="TS"/>
        </attentionLine>
        <!--ACK.B.r.6 - Acknowledgement Report Code-->
        <acknowledgement typeCode="CA">
            <targetMessage>
                <!--ACK.B.r.1 - Safety Report ID ICSR Message Number-->
                <id root="2.16.840.1.113883.3.989.2.1.3.1" extension="VERN-123-123-123"/>
            </targetMessage>
            <acknowledgementDetail>
                <!--ACK.B.r.7 - Error/Warning message / comment-->
                <text>[F.r.5 Normal High Value (Unit), mg/dl] inconsistent_unit; [C.5.3, 0105798/01] unable_to_link_study_for_wrong_type; [C.5.1.r.1, 2004-09102-03] unable_to_link_study_for_wrong_type; [C.5.1.r.2, EU] unable_to_link_study_for_wrong_type; [C.5.1.r.1, NL...</text>
            </acknowledgementDetail>
        </acknowledgement>
    </MCCI_IN000002UV01>
    <receiver typeCode="RCV">
        <device determinerCode="INSTANCE" classCode="DEV">
            <!--ACK.M.3 - Acknowledgement Batch Receiver Identifier-->
            <id root="2.16.840.1.113883.3.989.2.1.3.18" extension="DSJP"/>
        </device>
    </receiver>
    <sender typeCode="SND">
        <device determinerCode="INSTANCE" classCode="DEV">
            <!--ACK.M.2 - Acknowledgement Batch Sender Identifier-->
            <id root="2.16.840.1.113883.3.989.2.1.3.17" extension="ICHTEST"/>
        </device>
    </sender>
    <attentionLine>
        <!--ACK.A.2 - Local Message Number-->
        <keyWordText codeSystemVersion="2.0" codeSystem="2.16.840.1.113883.3.989.2.1.1.24" code="2"/>
        <value root="2.16.840.1.113883.3.989.2.1.3.21" extension="TR-000006_b4e413b2-7263-48b5-b957-839fea7c7edc_20210618194357" xsi:type="II"/>
    </attentionLine>
    <attentionLine>
        <!--ACK.A.3 - Date of ICSR Batch Transmission-->
        <keyWordText codeSystemVersion="2.0" codeSystem="2.16.840.1.113883.3.989.2.1.1.24" code="3"/>
        <value value="20120720100000" xsi:type="TS"/>
    </attentionLine>
    <!--ACK.A.4- Transmission Acknowledgment Code-->
    <acknowledgement typeCode="AE">
        <targetBatch>
            <!--ACK.A.1 - ICSR Batch Number -->
            <id root="2.16.840.1.113883.3.989.2.1.3.22" extension="DSJP-B0123456"/>
        </targetBatch>
        <!--ACK.A.5 - Batch Validation Error-->
        <acknowledgementDetail>
            <text>[F.r.5 Normal High Value (Unit), mg/dl] inconsistent_unit; [C.5.3, 0105798/01] unable_to… See B.r.7</text>
        </acknowledgementDetail>
    </acknowledgement>
</MCCI_IN200101UV01>

Use the following endpoint to retrieve the E2B acknowledgement message (ACK) after sending an intake call:

GET /api/{version}/app/safety/intake/ack

The Retrieve ACK endpoint can be used with the following Safety intake endpoints:

• Intake Inbox Item
• Intake Imported Case

Headers

Name	Description
Accept	application/json

URL Parameters

Name	Description
inbound_id	The Inbound Transmission ID for the ICSR intake job.

Response Details

On SUCCESS, the response returns the ACK XML. The ACK is returned in the same E2B format as the intake file.

On FAILURE, the response returns a message describing the reason for the failure.

Intake JSON

Request

$ curl --location --request POST 'https://safety.veevavault.com/api/v20.1/app/safety/ai/intake?API_Name=verteo_biopharma' \
--header 'Authorization: {SESSION_ID} '  \
--header ‘Content-Type: application/json’ \
--form 'intake_json=@/C:/Users/Vern/Documents/intake.json'

Response SUCCESS

{
     “responseStatus” :  “SUCCESS”,
     “jobId” : “69813”,
    “transmissionRecordId”: “V29000000000E09”
}

Response FAILURE

{
    "responseStatus": "FAILURE",
    "reason": "Invalid AI intake section object. Field \"height_value__v\" \
    with value \"999999\" in section \"patient\" is not valid. Error: \"The \
    input is outside of the supported range limits\". Please refer to documentation."
}

Use the following endpoint to send JSON to Vault Safety, which will be imported to a single Inbox Item:

POST /api/{version}/app/safety/ai/intake

Before submitting this request:

• The User record for the API user must link to the Organization receiving the report in the Organization field. Edit User records in Admin > Users & Groups.
• The API user must have the Access API Vault Action permission in their permission set.

Headers

Name	Description
Content-Type	multipart/form-data: Use to pass a JSON file or JSON text in the intake_json parameter when passing another document in the intake_form parameter. application/json: Use to pass JSON text as raw content.

Body

Name	Description
intake_json	The filepath for the JSON intake file, or the raw JSON text. Vault Safety creates an Inbox Item using the JSON passed through this parameter. Note that Vault Safety does not support bulk intake with this endpoint. A single API call is required for each Inbox Item. Ensure to use the correct JSON format.
intake_form	The filepath for a source intake document. Vault Safety attaches the file passed through intake_form to the Inbox Item and Inbound Transmission. The Content-Type must be multipart/form-data to use this parameter.

Query Parameters

Name	Description
{API_Name}	(Optional) To specify which organization to send the Inbox Item to, enter the Vault API Name for the Organization record. The default value is vault_customer. Note that the Organization record type must be Sponsor.

Response Details

On SUCCESS, the response includes the jobID, which you can use to retrieve the job status, and the transmissionRecordId, which you can use to find the Inbound Transmission record in your Vault.

On FAILURE, check the reason text in the response against your Vault configuration and JSON file format and content. To view detailed logs for a job, log into your Vault and go to Admin > Operations > Job Status, where you can view your job history and download logs.

You can track the job status using the Retrieve Job Status endpoint.

Import Narrative

Note: To bulk import multiple narratives, use the Bulk Import Narrative endpoint.

Request

$ curl -X POST \
https://myvault.veevavault.com/api/v20.1/app/safety/import-narrative \
-H 'Authorization: {SESSION_ID}' \
-H 'caseId: V2B000000000201' \
-H 'narrativeType: primary' \
-H 'narrativeLanguage: eng' \
-H 'Content-Type: text/plain' \
-d 'The patient took 500 mg cholecap at 2pm and started experiencing heart palpitations at 2:30pm...'

Response

{
"responseStatus": "SUCCESS",
}

Use the following endpoint to import narrative text into a Case narrative.

POST /api/{version}/app/safety/import-narrative

The request creates a narrative document for the destination Case, in the format of the E2B import narrative template. The narrative text sent in the body of this call is appended to the template content.

If a Case narrative document already exists for the given language, the request creates a new version of the document and appends the narrative text sent in the body of this call to the existing content.

Before submitting this request:

• You must be assigned permissions to use the API and have the Edit Document permission for the draft__v state of the narrative_lifecycle__v object.
• The destination Case must exist.

Headers

Name	Description
caseId	Destination Case or Adverse Event Report ID.
narrativeType	For the main narrative, enter primary. For a narrative translation, enter translation. The primary narrative must exist before you can add a translation.
narrativeLanguage	Three-letter ISO 639-2 language code. Currently, the primary narrative must be English (eng).
link_translation_to_primary	Set to true to add the localized narrative document as a supporting document to the global (English) narrative document. This parameter only applies when the narrativeType is set to translation and the localized narrative document does not already exist. If omitted, defaults to false.
Content-Type	text/plain

Body

In the body of the request, enter the narrative text. You can import up to 100,000 characters of narrative text.

Response Details

On SUCCESS, the response only includes the responseStatus.

On FAILURE, the response also returns a message describing the reason for the failure.

Bulk Import Narrative

Request

curl --location --request POST 'https://myvault.veevavault.com/api/v22.1/app/safety/import-narrative/batch'
--header 'Content-Type: multipart/form-data'
--header 'Accept: text/csv'
--header 'Authorization: {SESSION_ID}'
--form 'narratives=@"/directory/bulk-narrative-import.csv"'

Response

{
    "responseStatus": "success__v",
    "responseDetails":
    {
        "import_id": "dc2daf9d-8549-4701-805a-c3f62a2aefa5",
        "result_uri": "/api/v21.3/app/safety/import-narrative/batch/dc2daf9d-8549-4701-805a-c3f62a2aefa5"
    }
}

Use the following endpoint to bulk import case narratives into Vault Safety:

POST /api/{version}/app/safety/import-narrative/batch/

This request imports text to create multiple narrative documents, in the format of the E2B import narrative template. This request can import primary narratives as well as narrative translations. Narrative translations can optionally be imported to a Localized Case in addition to the global Case.

If a Case narrative or translation already exists for the given language, the request creates a new version of the document populated with the text sent through the request.

This endpoint is asynchronous. The following limits apply to this endpoint:

• The maximum batch size is 500
• The maximum CSV input file size is 100 MB
• Maximum characters per narrative is 200k
• The CSV file cannot contain duplicate rows with the same caseId and narrativeLanguage

Headers

Name	Description
content-type	multipart/form-data
accept	text/csv
X-VaultAPI-IntegrityCheck	Optional: Set to true to perform additional integrity checks on the CSV file. If omitted, defaults to false.
X-VaultAPI-MigrationMode	Optional: Set to true to perform additional verifications on the localizedCaseId, including checking that the caseId refers to the related global Case and the narrativeLanguage matches the language on the Localized Case. If omitted, defaults to false.
X-VaultAPI-ArchiveDocument	Optional: If the Vault Document Archive feature is enabled, set to true to send the imported narrative documents directly to the document archive, or false to create the imported documents as active narratives. If omitted and the Vault Document Archive feature is enabled, the imported narrative documents are sent directly to the document archive.

Body Parameter

The request is sent through a CSV file.

Name	Description
narratives	The CSV file containing the narratives to be imported.

Click the button below to download a sample CSV file:

Consider the following requirements when preparing the CSV file:

• The values in the input file must be UTF-8 encoded.
• CSVs must follow the standard format.
• The file must use a comma (,) as the delimiter
• If the narrative text contains commas, enclose each comma within double-quotation marks (“,”)
• If the narrative text contains double-quotation marks, they must be escaped (\”example\“)

The CSV file must have the following columns:

Column	Description
caseId	The Case record ID.
localizedCaseId	Optional: If you are importing a localized narrative, specify the Localized Case record ID. The narrative document will be linked to both the global Case ( caseId) and Localized Case. The following requirements apply: narrativeType must be translation narrativeLanguage must match the language on the destination Localized Case. caseId must match the global Case Note: The localizedCaseId column is required, even when empty.
narrativeType	The following types are accepted: primary: The primary Case narrative, used to populate the Narrative Text and Narrative Preview fields on the Case. translation: A narrative Translation.
narrativeLanguage	The three-letter ISO language code for the narrative language. For example, eng is english.
narrative	Text of the narrative document.

Response Details

On SUCCESS, the response includes the following information:

Name	Description
import_id	The ID of the import request, which you can use along with the Retrieve Bulk Import Status endpoint to check the status of the operation.
result_uri	The URI path to retrieve the status of the operation with the Retrieve Bulk Import Status endpoint.

On FAILURE, the response returns an error message describing the reason for the failure.

Retrieve Bulk Import Status

Request

curl --location --request GET 'https://myvault.veevavault.com/api/v22.1/app/safety/import-narrative/batch/dc2daf9d-8549-4701-805a-c3f62a2aefa5' \
--header 'Authorization: {SESSION_ID}'

Response: Completed

{
    "responseStatus": "completed__v",
    "responseDetails" : {
        "import_id": "dc2daf9d-8549-4701-805a-c3f62a2aefa5",
        "job_id": "203715",
        "start_time": "2021-11-30T19:17:38.669Z[GMT]",
        "end_time": "2021-11-30T19:17:47.996Z[GMT]",
        "total_narratives": 3,
        "completed_narratives": 3
    },
    "data": [
        {
            "status": "SUCCESS",
            "case_id": "V2B000000002001",
            "narrative_document_version": "12_0_2"
        },
        {
            "status": "SUCCESS",
            "case_id": "V2B000000002002",
            "narrative_document_version": "1_0_1"
        },
        {
            "status": "FAILED",
            "case_id": "V2B000000002003",
            "errors": [ { "type": "INVALID_DATA", "message": "Error message describing why this document version was not added." } ]
        }
    ]
}

Response: In Progress

{
    "responseStatus": "in_progress__v",
    "responseDetails" : {
        "import_id" : "db1e69cc-171b-11ec-9621-0242ac130002",
        "start_time" : "2021-09-16 00:00:00.0",
        "total_narratives": 3,
        "completed_narratives": 1
    }
}

Use the following endpoint to retrieve the status of a bulk narrative import:

GET /api/{version}/app/safety/import-narrative/batch/{importId}

URI Path Parameters

Name	Description
importId	The import_id of the bulk narrative import job, retrieved from the job request response details.

Response Details

If a bulk import job is complete, the response returns details of each narrative document.

If a bulk import job is incomplete, the response returns details of the job in progress.

SiteVault

Users

The Create and Edit APIs are defined to be as consistent as possible. Both Create and Edit accept the same JSON, which has several shapes depending on which data you are creating/editing. For more information on SiteVault User Administration, see SiteVault Help.

Guidelines

• A Person record is referencing person__sys.
• A User record is referencing user__sys.
• A “user” object (create) or a “username” referencing an existing user (edit) must be specified. All other API references are consistent.
• Only a single user per API call is supported.
• APIs build on each other and appear in a nested format.
• If a site, organization, or study is specified, you must complete all the site, organization, or study parameters. For example, if you edit a user with an existing add-on permission and do not include it in your call, the user will no longer have that add-on permission.
• You must be in the organization context to add study assignments for other sites within the organization.
• It is possible to make an existing Person/User active if Vault finds an existing Person/User who is currently inactive.
• A person is made inactive in an organization when all access within that organization has been removed.

Create User

Create a new user in SiteVault. Bulk creation of users is not supported. You must be in the organization context to add study assignments for other sites within the organization.

POST /api/{version}/app/sitevault/useradmin/persons

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
--data-binary @"users_create.json" \
https://myvault.veevavault.com/api/v24.2/app/sitevault/useradmin/persons

Example JSON Request Body

[
    {
        "user": {
            "email": "jerry.cotter@company.com",
            "first_name": "Jerry",
            "last_name": "Cotter",
            "security_policy_id": "VeevaID",
            "person_type": "staff__v",
            "language":"en"
        },
        "person_type": "staff__v",
        "is_investigator": false,
        "assignments": {
            "org_assignment": {
                "org_id": "V42000000001001",
                "system_role_id": "org_admin__v"
            },
            "site_assignments": [
                {
                    "site_usn": "US-NC-0001",
                    "system_role_id": "regulatory__v"
                }
            ]
        }
    }
]

Response

{
   "responseStatus": "SUCCESS",
   "data": {
       "response": [
           {
               "status": "Success",
               "email": "jerry.cotter@company.com",
               "person_id": "V0B000000001001",
               "record_status": "active__v"
           }
       ]
   }
}

Headers

Name	Description
Content-Type	application/json
Accept	application/json

Body Parameters

In the body of the request, upload parameters as a JSON file. The following tables provide the required and most common optional parameters for creating a user.

User Creation

The following table lists the fields required to create a user.

Name	Description
userrequired	This is an object definition of the User being created. This represents the user__sys record in the Vault.
user.emailrequired	The user’s email.
user.usernamerequired	The username of the user being created, with the domain name. This is always required unless security policy is VeevaID.
user.first_namerequired	The user’s first name.
user.last_namerequired	The user’s last name.
user.security_policy_idrequired	The name__v value of the Security Policy for this user. The standard is VeevaID. However, Enterprise SiteVaults may utilize custom policies. When creating a Staff user who will not require an account to log in, set as noUser.
user.person_typerequired	Defines the type of the person__sys record. Select from staff__v or external__v.
user.languageoptional	The 2-letter system code for the user language. If omitted, defaults to en for English.
is_investigatorrequired	Indicates if the user is an investigator. External users must be set as false.

Organization Assignment

The following table lists the fields required to include an organization assignment when creating a user.

Name	Description
assignmentsrequired	This object defines the user’s permissions.
assignments.org_assignmentrequired	This object defines the user’s organization-level permissions. Required when creating a user. Content sent in this call will overwrite any existing organization assignments with the same organization ID.
assignments.org_assignment.org_idrequired	The ID of the organization.
assignments.org_assignment.system_role_idrequired	The system ID of the organization-level system role for the user. Select from org_admin__v, org_full__v, or org_external__v. When creating a Staff user who will not require an account to log in, set as org_cant_login__v.
assignments.org_assignment.addonsoptional	The system ID for the organization-level add-on permissions assigned to the user. Add-on permissions must be valid for the specified system role. Add-on permissions are not available for the Site Viewer or External User roles. Select org_patients__v. Do not include if not applicable.

Site Assignment

The following table lists the fields required to include a site assignment when creating a user.

Name	Description
site_assignmentsrequired	This object defines the user’s site-level permissions.
site_assignments.site_USNrequired	The Universal Site Number (USN) assigned to the Site.
site_assignments.system_role_idrequired	The system ID for the user’s site-level system role. Select from regulatory__v, study_team__v, site_viewer__v, or external__v. When creating a Staff user who will not require an account to log in, set as site_cant_login__v`.
site_assignments.addonsoptional	The system ID for the site-level add-on permissions assigned to the user. Add-on permissions must be valid for the specified system role. Add-on permissions are not available for the Site Viewer or External User roles. Select from site_budgets__v, site_patients__v, and site_profiles__v. Use a comma to separate when selecting multiple add-on permissions (ex. ["site_budgets__v", "site_patients__v"]). Do not include if not applicable.

Study Assignment

The following table lists the fields required to include a study assignment when creating a user.

Name	Description
study_assignmentsrequired	This object defines the user’s study-level permissions.
study_assignments.idrequired	The Study ID.
study_assignments.study_rolerequired	The study-level role for the user. Select from sponsor_cro__v or auditor_inspector__v for external users. Select from clinical_research_coordinator__v, data_coordinator__v, principal_investigator__v, regulatory_coordinator__v, research_nurse__v, subinvestigator__v, pharmacist__v, or other__v, for site staff.

Edit User

Edit an existing user in SiteVault. Bulk editing is not supported. You must be in the organization context to add study assignments for other sites within the organization.

PUT /api/{version}/app/sitevault/useradmin/persons/{personId}

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
--data-binary @"users_edit.json" \
https://myvault.veevavault.com/api/v24.2/app/sitevault/useradmin/persons/V0B000000001001

Example JSON Request Body

{
    "is_investigator": false,
    "assignments": {
        "org_assignment": {
            "org_id": "V42000000001001",
            "system_role_id": "org_no_access__v"
        },
        "site_assignments": [
            {
                "site_usn": "US-NC-0002",
                "system_role_id": "no_access__v"
            }
        ]
    }
}

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "response": {
            "status": "Success",
            "email": "jerry.cotter@company.com",
            "username": "jerry.cotter@company.com",
            "person_id": "V0B000000001001",
            "record_status": "active__v"
        }
    }
}

Headers

Name	Description
Content-Type	application/json
Accept	application/json

URI Path Parameters

Name	Description
{personid}	The ID of the person_sys to edit.

Body Parameters

In the body of the request, upload parameters as a JSON file. The following tables provide the required and most common optional parameters for editing a user.

Edit Existing User

The following table lists the fields required to edit an existing user.

Name	Description
usernameconditional	The username associated with the existing User account. Must include the domain name. Only required when editing a person record to associate with an existing user record.
is_investigatorrequired	Indicates if the user is an investigator. External users must be noted as false.

Organization Assignment

The following table lists the fields required to include an organization assignment when editing a user.

Name	Description
assignmentsrequired	This object defines the user’s permissions.
assignments.org_assignmentrequired	This object defines the user’s organization-level permissions. Not required when editing if the organization assignment isn’t changing. Content sent in this call will overwrite any existing orgAssignments with the same orgID.
assignments.org_idrequired	The ID of the organization.
assignments.system_role_idrequired	The system ID of the organization-level system role for the user. Select from org_admin__v, org_full__v, or org_external__v. When removing access to an organization, select org_no_access__v.
assignments.addonsoptional	The system ID for the organization-level add-on permissions assigned to the user. Add-on permissions must be valid for the specified system role. Add-on permissions are not available for the Site Viewer or External User roles. Select org_patients__v. Do not include if not applicable.

Site Assignment

The following table lists the fields required to include a site assignment when editing a user.

Name	Description
site_assignmentsrequired	This object defines the user’s site-level permissions.
site_assignments.site_USNrequired	The Universal Site Number (USN) assigned to the Site.
site_assignments.system_role_idrequired	The system ID for the site-level system role for the user. Select from regulatory__v, study_team__v, site_viewer__v, or external__v. When removing access to a site, set to no_access__v.
site_assignments.addonsrequired	The system ID for the site-level add-on permissions assigned to the user. Add-on permissions must be valid for the specified system role. Add-on permissions are not available for the Site Viewer or External User roles. Select from site_budgets__v, site_patients__v, and site_profiles__v. Use a comma to separate when selecting multiple add-on permissions (ex. ["site_budgets__v", "site_patients__v"]). Do not include if not applicable.

Study Assignment

The following table lists the fields required to include a study assignment when editing a user.

Name	Description
study_assignmentsrequired	This object defines the user’s study-level permissions.
study_assignments.idrequired	The Study ID.
study_assignments.study_rolerequired	The study-level role for the user. Select from sponsor_cro__v or auditor_inspector__v for external users. Select from clinical_research_coordinator__v, data_coordinator__v, principal_investigator__v, regulatory_coordinator__v, research_nurse__v, subinvestigator__v, pharmacist__v, or other__v, for site staff.

Veeva eConsent

Veeva eConsent enables study participants, signatories, and site staff to sign informed consent forms (ICFs) electronically, eliminating the need to print the forms and speeding up the consenting process. Participants and their signatories can review the forms at home on a familiar device, can read at their own pace, and can easily download and share the forms with their family and care team. Additionally, participants with accessibility requirements can zoom in and utilize screen readers. See the Veeva eConsent help on the SiteVault Help website to learn more.

This API enables you to send eConsent forms to participants to review and complete in bulk.

Retrieve Documents and Signatories

Request

curl --location --request GET 'https://myvault.veevavault.com/api/v21.2/app/sitevault/econsent/participant/V0X000000002001' \ --header 'Authorization: {SESSION_ID}'

Response

[
   {
       "subject__v.id": "V0X000000002001",
       "documents": [
           {
               "document.version_id__v": "40_1_0",
               "signatory__v": [
                   {
                       "signatory__v.id": "V5A000000004002"
                   }
               ]
           }

       ]
   }
]

Retrieve the valid blank ICFs and signatories for a participant.

GET /api/{version}/app/sitevault/econsent/participant/{participant_id}

URI Path Parameters

Name	Description
participant_id	The SiteVault ID of the participant. You can use the /query REST interface to query the Participant (subject__v) object for the participant ID.

Response Details

The response lists the valid blank ICFs and signatories for the participant. Valid blank ICFs are those that are not already sent or in a workflow.

Send Documents to Signatories

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
-d "documents.version_id__v=40_1_0" \
-d "signatory__v.id=V5A000000004002" \
-d "signatory__v.role__v=participant__v" \
-d "subject__v.id=V0X000000002001" \
https://myvault.veevavault.com/api/v22.1/app/sitevault/econsent/send

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "data": [
        {
            "status": "SUCCESS",
            "message": "Send EConsent action began successfully with job id {job_id}",
            "data": {
                "subject__v.id": "V0X000000002001",
                "documents": [
                    {
                        "document.version_id__v": "40_1_0",
                        "signatory__v": [
                            {
                                "signatory__v.id": "V5A000000004002",
                                "signatory__v.role__v": "participant__v"
                            }
                        ]
                    }

                ]
            }
        }
    ]
}

Send documents to signatories for signature.

POST /api/{version}/app/sitevault/econsent/send

Body Parameters

Name	Description
documents.version_id__v	The ID of the blank ICF.
signatory__v.id	The ID of the signatory.
signatory__v.role__v	The role of the signatory.
subject__v.id	The ID of the participant.

Response Details

The response lists the participant, the blank ICF, any signatories, and a job ID. You can use the Retrieve Job Status endpoint to query the status of the request using the job ID.

Errors

Example: Failed Authentication

{
    "responseStatus": "FAILURE",
    "errors": [
        {
            "type": "NO_PASSWORD_PROVIDED",
            "message": "No password was provided for the login call."
        }
    ],
    "errorType": "AUTHENTICATION_FAILED"
}

The response of every API call includes a field called responseStatus. Possible values are:

• SUCCESS - The API request was successfully processed.
• WARNING - The API request was successfully processed, but with warnings.
• FAILURE - The API request could not be processed because of user error.
• EXCEPTION - The API request could not be processed because of system error.

For a responseStatus other than SUCCESS, users can inspect the errors field in the response. Each error includes the following fields:

• type - The specific type of error, e.g., INVALID_DATA, PARAMETER_REQUIRED, etc. See below for a full list of types. These values are not subject to change for a given version of the API, even when newer versions of the API are available.

• message - The message accompanying each error type, e.g., Missing required parameter [{field_name}]. When available, the error message includes the specific reason, e.g., the {field_name} for the error. These messages are subject to change and are not contractual parts for error handling. Developers should consider error messages for debugging and troubleshooting purposes only and should not implement application logic which relies on specific error strings or formatting.

When Vault processes an API request, it returns an HTTP response status code of 200. If Vault returns a response status code other than 200, it is likely due to connectivity problems, and we recommend contacting your network team. We recommend basing your logic on the responseStatus field and error types, not on the HTTP response status codes.

Error Types

Type	Description
UNEXPECTED_ERROR	General error catch-all when there is no specific error, or an unidentified error.
MALFORMED_URL	The specified resource cannot be found.
METHOD_NOT_SUPPORTED	The specified resource does not support the (POST, PUT, GET, DELETE) method. Or, the API request is not supported by this version of API.
INACTIVE_USER	User is inactive or not found.
NO_PASSWORD_PROVIDED	No password was provided for the login call.
USERNAME_OR_PASSWORD_INCORRECT	Authentication failed because an invalid username or password was provided.
USER_LOCKED_OUT	The user is locked out. Learn more about user account lockout in Vault Help.
PASSWORD_CHANGE_REQUIRED	Password change required.
INVALID_SESSION_ID	Invalid session ID provided.
PARAMETER_REQUIRED	Missing required parameters in the API call.
INVALID_DATA	Invalid data provided in the API call.
INSUFFICIENT_ACCESS	User does not have sufficient privileges to perform the action. Additionally, the /actions endpoints may return this error in cases where the user attempts to access a resource which does not exist.
OPERATION_NOT_ALLOWED	Certain rules that must be met to perform this operation have not been met.
ATTRIBUTE_NOT_SUPPORTED	The specified resource does not recognize provided attributes.
INVALID_FILTER	Provided a non-existent filter to Retrieve Documents.
INCORRECT_QUERY_SYNTAX_ERROR	Query string used with VQL has an incorrect query syntax.
RACE_CONDITION	A rare condition where the same record is being simultaneously updated by another API call.
EXCEEDS_FILE_MAX_SIZE	The size of uploaded file exceeds the maximum size allowed (4 GB).
API_LIMIT_EXCEEDED	The Job Status endpoint can only be requested once every 10 seconds for each job_id. When this limit is reached, this error message is returned and no further calls will be processed until the next 10-second period begins. Learn more about API Limits.
CONFIGURATION_MODE_ENABLED	Non-Admins cannot access a Vault in Configuration Mode. Learn more about Configuration Mode in Vault Help.
SDK_ERROR	An error caused by the Vault Java SDK. This error may also include a custom subtype. For more information about this error, check the Debug Log.
OPERATION_IN_PROGRESS	There is already an operation running on the item specified in the request.
ITEM_NAME_EXISTS	When creating an item, this error indicates that an item with the same name already exists in the specified location.
USER_NOT_FOUND	The specified user cannot be found.
FEDERATED_ID_ALREADY_EXISTS	When creating or updating a user, this error indicates that a user with the same Federated ID already exists in the authenticated Vault. Learn more about user ID types in Vault Help.