Authentication

Authenticate your account using one of the methods outlined below. The response returns a session ID that you can use in subsequent API calls. Session IDs time out after a period of inactivity, which varies by Vault. Learn more about session duration and management.

Every Vault API must include the following header:

Basic Auth Header

Name	Description
Authorization	{sessionId}

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

Basic

Request

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

Response

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

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.

OAuth2 / OIDC

Request

$ curl -X POST \
-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": 1778,
      "name": "MedComms",
      "url": "https://medcomms-veevapharm.veevavault.com/api"
    },
    {
      "id": 1779,
      "name": "QualityDocs",
      "url": "https://qualitydocs-veevapharm.veevavault.com/api"
    }
  ],
  "vaultId": 1776
}

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

POST /auth/oauth/session/{oath_oidc_profile_id}

Headers

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

URI Path Parameters

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

Body Parameters

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

Salesforce Delegated Requests

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 matching username must exist in Salesforce.com Org ID.

Headers

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

Query Parameters

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

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

Retrieve API Versions

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.

Discovery

Request

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

Response

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

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

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

Headers

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

Query Parameters

Name	Description
username	The user’s Vault username.

Response Details

The response specifies the user’s auth_type, either:

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

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

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

Domain Information

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.

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" \
https://myvault.veevavault.com/api/v14.0/query?q=SELECT id FROM documents

Response

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

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

/api/{version}/query

Headers

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

Response Details

On SUCCESS, the response includes the following information:

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

About the X-VaultAPI-DescribeQuery Header

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

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

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

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

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/v15.0/metadata/objects/documents/properties

Response

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

Retrieve all standard and custom document fields and field properties.

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

Headers

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

Response Details

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

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

Retrieve Common Document Fields

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
docIds	Input a comma-separated list of document id field values.

Response Details

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

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

Note the following field metadata:

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

Retrieve Document Types

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

Retrieve All Document Types

Request

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

Response

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

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

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

Headers

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

Response Details

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

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

The response includes the following information:

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

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

Retrieve Document Type

Request

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

Response

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

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

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

Headers

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

URI Path Parameters

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

Response Details

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

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

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

Retrieve Document Subtype

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	Various properties of the subtype, such as required, maxLength, queryable, and so on.
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	Various properties of the subtype, such as required, maxLength, queryable, and so on.
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 response above, document id:534 has 8 different versions. Version 2.0 is the latest steady state version. Version 2.3 is the latest version. This document also has two different renditions: The viewable_rendition__v and a veeva_distribution_package__c rendition.

Retrieve Document Version

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 response above shows information for document id:534 version 2.3.

Download Document File

Request

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

Response

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

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

Headers

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

URI Path Parameters

Name	Description
{doc_id}	The document id field value.

Query Parameters

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

Response Details

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

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.

POST /api/{version}/objects/documents

Headers

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

Body Parameters

There are multiple ways to create a document.

Create Document from Uploaded File

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

Name	Description
file	The filepath of the source document. The maximum allowed file size is 4GB.
type__v	The name of the document type to assign to the new document.
subtype__v	The name of the document subtype (if one exists on the document type).
classification__v	The name of the document classification (if one exists on the document subtype).
lifecycle__v	The name of the document lifecycle to assign to the new document.
major_version_number__v	The major version number to assign to the new document.
minor_version_number__v	The minor version number to assign to the new document.

Create Document from Template

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

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

Create Content Placeholder Document

Creating a content placeholder document is just like creating a document from an uploaded file, but the file parameter is not included in the request. Learn about Content Placeholders in Vault Help. Admin may set other standard or custom document fields to required in your Vault.

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

Create Unclassified Document

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

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

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

• product__v
• study__v
• study_country__v
• site__v

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

Create CrossLink Document

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

Name	Description
name__v	The name of the new CrossLink document.
type__v	The name of the document type to assign to the new CrossLink document.
subtype__v	The name of the document subtype (if one exists on the document type).
classification__v	The name of the document classification (if one exists on the document subtype).
lifecycle__v	The name of the document lifecycle to assign to the new CrossLink document.
major_version_number__v	The major version number to assign to the new CrossLink document
minor_version_number__v	The minor version number to assign to the new CrossLink document.
source_vault_id__v	The Vault id field value of the Vault containing the source document that will be bound to the new CrossLink document. Learn more.
source_document_id__v	The document id field value of the source document that will be bound to the new CrossLink document.
source_binding_rule__v	Optional: Possible values are Latest version, Latest Steady State version, or Specific Document version. These define which version of the source document will be bound to the CrossLink document. If not specified, this defaults to the Latest Steady State version.
bound_source_major_version__v	Optional: When the source_binding_rule__v is set to Specific Document version, you must specify the major version number of the source document to bind to the CrossLink document.
bound_source_minor_version__v	Optional: When the source_binding_rule__v is set to Specific Document version, you must specify the minor version number of the source document to bind to the CrossLink document.

Response Details

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

Create Multiple Documents

Request

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

Response

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

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

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

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

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

Headers

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

Body Parameters

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

Create Documents from Uploaded Files

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

Name	Description
file	The filepath of the source document. The maximum allowed file size is 4GB.
name__v	The name of the new document.
type__v	The name of the document type to assign to the new document.
subtype__v	The name of the document subtype (if one exists on the document type).
classification__v	The name of the document classification (if one exists on the document subtype).
lifecycle__v	The name of the document lifecycle to assign to the new document.
major_version_number__v	The major version number to assign to the new document
minor_version_number__v	The minor version number to assign to the new document.
suppressRendition	Optional: false by default. Set to true to suppress generation of viewable renditions.
product__v	Example: This is an example object reference field. To assign value for this field type, include either the document field name product__v or the document field name plus the name field on the object product__v.name__v.

Create Documents from Templates

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

Name	Description
fromTemplate	The template to apply to the document.
name__v	The name of the new document.
type__v	The name of the document type to assign to the new document.
subtype__v	The name of the document subtype (if one exists on the document type).
classification__v	The name of the document classification (if one exists on the document subtype).
lifecycle__v	The name of the document lifecycle to assign to the new document.
major_version_number__v	The major version number to assign to the new document
minor_version_number__v	The minor version number to assign to the new document.
product__v	Example: This is an example object reference field. To assign value for this field type, include either the document field name product__v or the document field name plus the name field on the object product__v.name__v.

Create Content Placeholder Documents

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

Name	Description
file	Include this column in your input, but leave the values blank.
name__v	The name of the new document.
type__v	The name of the document type to assign to the new document.
subtype__v	The name of the document subtype (if one exists on the document type).
classification__v	The name of the document classification (if one exists on the document subtype).
lifecycle__v	The name of the document lifecycle to assign to the new document.
major_version_number__v	The major version number to assign to the new document
minor_version_number__v	The minor version number to assign to the new document.

Create Unclassified Documents

Unclassified documents are documents which have a source file, but no document type. The following fields are required, but you can include any editable document field.

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

Update Documents

Update Single Document

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

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 @"C:\Vault\Documents\update_documents.csv" \
https://myvault.veevavault.com/api/v9.0/objects/documents/batch

Response

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

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

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

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

Headers

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

Body Parameters

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

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

Reclassify Document

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. A document “type” is the combination of the type__v, subtype__v, and classification__v fields on a document. When you reclassify, Vault may add or remove certain fields on the document. You can only reclassify the latest version of a document and only one document at a time. The API does not currently support bulk reclassify.

Learn more about reclassifying documents in Vault Help.

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

Headers

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

URI Path Parameters

Name	Description
{doc_id}	The document id field value.

Body Parameters

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

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

Update Document Version

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

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 @"C:\Vault\Documents\add_document_versions.csv" \
https://myvault.veevavault.com/api/v10.0/objects/documents/versions/batch

Response

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

Create or add document versions in bulk.

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

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

Headers

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

Body Parameters

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

Query Parameters

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

Create Single Document Version

Request: Copy file from current version

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

Request: Upload a new file & Suppress rendition

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

Response

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

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

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

Headers

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

URI Path Parameters

Name	Description
{doc_id}	The document id field value.

Body Parameters

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

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

Headers

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

Body Parameters

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

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

Query Parameters

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

Delete Single Document Version

Request

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

Response

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

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

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

Headers

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

URI Path Parameters

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

Delete Multiple Document Versions

Request

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

Response

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

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

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

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

Headers

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

Body Parameters

Create a CSV or JSON input file.

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

Query Parameters

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

Retrieve Deleted Document IDs

Request

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

Response (abridged)

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

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

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

        },
        {
            "id": 690,

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

        },
        {
            "id": 691,

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

        },
        {
            "id": 692,

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

        }
      ]
    }

Retrieve IDs of documents deleted within the past 30 days.

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

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

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

Headers

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

Query Parameters

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

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

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

Response Details

The abridged response shows that a total of 88 documents were deleted from this Vault in the past 30 days. Two versions (0.1 and 0.2) were deleted for Document ID 690. Version 0.1 was deleted for both Document ID 691 and Document ID 692. The response includes the date and time when each document was deleted. Date and time display in UTC, not in the user’s time zone.

Document Locks

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

Learn about Document Checkout (Locks) in Vault Help.

Retrieve Document Lock Metadata

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.
hidden	Boolean (true/false) field which indicates if the field is “hidden” (not available).

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.

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

URI Path Parameters

Name	Description
{doc_id}	The document id field value.

Response Details

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

Document Renditions

Learn about Document Renditions in Vault Help.

Note that requests to retrieve renditions might return an UNEXPECTED_ERROR. If this occurs, please 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.

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

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

Headers

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

URI Path Parameters

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

Response Details

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

Add Multiple Document Renditions

Request

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

Response

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

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

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

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

Headers

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

Body Parameters

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

Query Parameters

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

Add Single Document Rendition

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.

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 format.
• The maximum batch size is 500.

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

Headers

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

Body Parameters

Create a CSV or JSON input file.

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

Query Parameters

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

Delete Single Document Rendition

Request

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

Response

{
    "responseStatus": "SUCCESS"
}

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 (abridged)

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

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 format.
• The maximum batch size is 500.

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

Headers

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

Body Parameters

Prepare a CSV or JSON input file.

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

Response Details

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

Create Document Attachment

Request

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

Response

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

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

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

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

Headers

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

URI Path Parameters

Name	Description
{doc_id}	The document id field value.

File Upload

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

Response Details

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

Create Multiple Document Attachments

Request

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

Response

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

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

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

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

Headers

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

Body Parameters

Prepare a CSV or JSON input file.

Name	Description
document_id__v	The document ID to add this attachment.
filename__v	The name for the new attachment. 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. Cannot exceed 218 bytes.
file	The filepath of the attachment on the FTP server.
description__v	Optional: Description of the attachment. Maximum 1000 characters.
major_version_number__v	Optional: The major version of the source document.
minor_version_number__v	Optional: The minor version of the source document.
external_id__v	Optional: Set an external ID value on the attachment.

Response Details

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

Restore Document Attachment Version

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__v	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 format.
• The maximum batch size is 500.

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

Headers

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

Body Parameters

Prepare a CSV or JSON input file.

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

Response Details

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

Document Annotations

Learn about Document Annotations in Vault Help.

Download Document Annotations

Request

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

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

Headers

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

URI Path Parameters

Name	Description
{doc_id}	The document id field value.

Response

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

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

Download Document Version Annotations

Request

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

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

Headers

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

URI Path Parameters

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

Response

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

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

Retrieve Video Annotations

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

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

## END

Retrieve annotations on a video document.

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

Headers

Name	Description
Accept	text/csv (default)

URI Path Parameters

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

Response Details

On SUCCESS, Vault includes the following information:

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

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

Upload Document Annotations

Request

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

Response

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

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

Headers

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

File Upload

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

URI Path Parameters

Name	Description
{doc_id}	The document id field value.

Response Details

On SUCCESS, Vault uploads the file and its annotations.

Upload Document Version Annotations

Request

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

Response

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

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

File Upload

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

Headers

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

URI Path Parameters

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

Response Details

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

Document Relationships

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

Retrieve Document Type Relationships

Request

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

Response (abridged)

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

Retrieve all relationships from a document type.

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

Headers

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

URI Path Parameters

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

Response Details

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

Relationship Fields

The relationships object includes the following fields:

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

Relationship Type Properties

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

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

Relationships

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

Retrieve Document Relationships

Request

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

Response

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

Retrieve all relationships from a document.

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

Headers

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

URI Path Parameters

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

Response Details

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

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

Create Single Document Relationship

Request

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

Response

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

Create a new relationship on a document.

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

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

Headers

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

URI Path Parameters

Name	Description
{document_id}	The document id field value.
{major_version_number__v}	The document major_version_number__v field value.
{minor_version_number__v}	The document minor_version_number__v field value.

Body Parameters

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

Response Details

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

Create Multiple Document Relationships

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 format.
• The maximum batch size is 1000.

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

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

Headers

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

Body Parameters

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

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

Create Source Version-Specific Relationships

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

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

Create Target Version-Specific Relationships

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

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

Query Parameters

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

Response Details

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

Retrieve Document Relationship

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.

Send DELETE to /api/{version}/objects/documents/{document\_id}/versions/{major\_version\_number\_\_v}/{minor\_version\_number\_\_v}/relationships/{relationship\_id}

Headers

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

URI Path Parameters

Name	Description
{document_id}	The document id field value.
{major_version_number__v}	The document major_version_number__v field value.
{minor_version_number__v}	The document minor_version_number__v field value.
{relationship_id}	The relationship id field value. See Retrieve Document Relationships.

Response Details

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

Delete Multiple Document Relationships

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 format.
• The maximum batch size is 1000.

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

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

Headers

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

Body Parameters

Create a CSV or JSON input file.

Name	Description
id	The ID of the relationship to delete.

Response Details

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

Export Documents

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

• Source document
• Renditions
• All versions or latest version

This API does not support the following:

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

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

Export Documents

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

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

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

Headers

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

Body Parameters

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

Query Parameters

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

Response Details

On SUCCESS, the response includes the following information:

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

Export Document Version

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 FTP staging server. The files you export go to the u{userID} folder, regardless of your security profile.

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

Headers

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

Body Parameters

Prepare a JSON input file with the following body parameters:

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

Query Parameters

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

Response Details

On SUCCESS, the response includes the following information:

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

Retrieve Document Export Results

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

Before submitting this request:

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

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

Headers

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

URI Path Parameters

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

Response Details

On SUCCESS, the response includes the following information:

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

Document Events

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

Retrieve Document Event Types and Subtypes

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

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

Response

{
    "responseStatus": "SUCCESS"
}

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

Headers

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

URI Path Parameters

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

Response Details

On SUCCESS, Vault logs the document event.

Retrieve Document Events

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/{document_id}/events

Headers

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

URI Path Parameters

Name	Description
{document_id}	The document id field value.

Response Details

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

Document Templates

Learn about Document Templates in Vault Help.

Retrieve Document Template Metadata

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 Bulk Create Document Templates.

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

Headers

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

Body Parameters: Basic Document Template

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

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

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__v	The name of the new document template. If not included, Vault will use the specified label__v value to generate a value for the name__v field.
label__v	The label of the new document template. This is the name users will see among the available binder templates in the UI.
type__v	The name of the document type to which the template will be associated.
subtype__v	The name of the document subtype to which the template will be associated. This is only required if associating the template with a document subtype.
classification__v	The name of the document classification to which the template will be associated. This is only required if associating the template with a document classification.
active__v	Set to true or false to indicate whether or not the new document template should be set to active, i.e., available for selection when creating a document.
file	The filepath of the file for this document template, from the FTP Staging Server. 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__v	The name of the new document template. If not included, Vault will use the specified label__v value to generate a value for the name__v field.
label__v	The label of the new document template. This is the name users will see among the available binder templates in the UI.
active__v	Set to true or false to indicate whether or not the new document template should be set to active, i.e., available for selection when creating a document.
is_controlled__v	Set to true to indicate this template is a controlled document template.
template_doc_id__v	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: text/csv" \
-d "name__v=promo_ad_web_document_template__c" \
-d "label__v=Promo Ad Web Document Template" \
-d "active__v=true" \
https://myvault.veevavault.com/api/v15.0/objects/documents/templates/promo_ad_print_document_template__c

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__v	The name of an existing document template. This is required.
new_name	Change the name of an existing document template.
label__v	Change the label of an existing document template. This is the name users will see among the available document templates in the UI.
active__v	Set to true or false to indicate whether or not the document template should be set to active, i.e., available for selection when creating a document.

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__v	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 uo 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__v	Include the name of an existing document template.
new_name	Change the name of an existing document template.
label__v	Change the label of an existing document template. This is the name users will see among the available binder templates in the UI.
active__v	Set to true or false to indicate whether or not the document templates should be set to active, i.e., available for selection when creating a document.

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__v	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 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
docIds	Required: Include the docIds request parameter with a comma-separated string of document id values. This will generate tokens for each document. For example: docIds=101,102,103,104
expiryDateOffset	Optional: Include the expiryDateOffset request parameter set to the number of days after which the tokens will expire and the documents will no longer be available in the viewer. If not specified, the tokens will expire after 10 years by default.
downloadOption	Optional: Include the downloadOption request parameter set to PDF, source, both, or none. These allow users viewing the document to be able to download a PDF version or source version (Word, PPT, etc.) of the document. If not specified, the download options default to those set on each document.
channel	Optional: Include the channel request parameter set to the website object record id value that corresponds to the distribution channel where the document is being made available.
tokenGroup	Include the tokenGroup request parameter. This only required if you want to group together generated tokens for multiple documents in order to display the documents being referenced in the same viewer. This value accepts strings of alphanumeric characters (a-z, A-Z, 0-9, and single consecutive underscores) up to 255 characters in length. The token that is passed as a URL parameter to the External Viewer is the primary token and the document it references will be displayed normally. However, any additional documents that have tokens generated with the same case-sensitive tokenGroup string will be displayed in a sidebar of the viewer. The order of documents in the sidebar depends on the order in which the tokens are generated. If multiple tokens are generated with one request, the documents will be ordered top-to-bottom based on the order they are passed to the docIds parameter. For example: If passing the parameters docIds=101,102,103,104 and tokenGroup=group_1 with the request, the top-to-bottom order in the sidebar will be documents 101, 102, 103, 104. If a new request is then made with the parameters docIds=105 and tokenGroup=group_1, document 105 will be added below document 104 in the previous list.

Response Details

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

Binders

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

Learn about Documents & Binders in Vault Help.

Retrieve Binders

Retrieve All Binders

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 documents WHERE binder__v=true. See VQL documentation for details.

GET /api/{version}/objects/documents

Headers

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

Response Details

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

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

Retrieve Binder

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.

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

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

Query Parameters

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

Response Details

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

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

Response Details

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

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

Retrieve All Binder Versions

Retrieve all versions of a binder.

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/v15.0/objects/binders/566/versions/0/3

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

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

Headers

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

URI Path Parameters

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

Create Binders

Create Binder

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

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

Response Details

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

Create Binder Version

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
}

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
reclassify	Set to true. Without this, a standard binder update action is performed.
type__v	The name of the document type being assigned to the binder.
subtype__v	The name of the document subtype (if one exists on the type).
classification__v	The name of the document classification (if one exists on the subtype).
lifecycle__v	The name of the lifecycle.

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

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

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

Update Binder Version

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.

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 FTP

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

Prerequisites

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

• The binder export job must have been successfully completed.
• The API user must have a permission set which allows them FTP download permissions.

Downloading the Files

The exported binder is packaged in a ZIP file on your FTP Staging Server. Learn more.

Binder Relationships

Learn about Binder Relationships in Vault Help.

Retrieve Binder Relationship

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__v	Set the target_doc_id__v to the document id of the “target document” to which a relationship will be established with the binder.
relationship_type__v	Set the relationship_type__v to the field value of one of the desired relationshipTypes from the “Documents Relationships Metadata” call.
target_major_version__v	If you’re creating a relationship with a specific version of the target document, set the target_major_version__v to the major version number of the target document.
target_minor_version__v	If you’re creating a relationship with a specific version of the target document, set the target_minor_version__v to the minor version number of the target document.

Delete Binder Relationship

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

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.

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Body Parameters

Field Name	Description
name__v	[Required] Specify a name for the new section.
section_number__v	[Optional] Enter a numerical value for the new section.
parent_id__v	[Optional] If the new section is going to be a subsection, enter the Node ID of the parent section. If left blank, the new section will become a top-level section in the binder.
order__v	[Optional] Enter a number reflecting the position of the section within the binder or parent section. By default, new components appear below existing components. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.

Response Details

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

Update Binder Section

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.

Body Parameters

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

Field Name	Description
name__v	Change the name of the binder section.
section_number__v	Update the section number value.
order__v	[Optional] Enter a number reflecting the position of the section within the binder or parent section. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.
parent_id__v	To move the section to a different section in the binder, include the value of the parent node where it will be moved.

Response Details

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

Delete Binder Section

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.

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

Headers

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

URI Path Parameters

Name	Description
{binder_id}	The binder id field value.

Body Parameters

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

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__v	[Optional] Enter a number reflecting the new position of the document within the binder or section. Note: There is a known issue affecting this parameter. The values you enter may not work as expected.
parent_id__v	[Optional] To move the document to a different section or from a section to the binder’s root node, enter the value of the new parent node.

Response Details

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

Remove Document from Binder

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

In this example:

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

Response Details

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

Bulk Create Binder Templates

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__v	The name of the new binder templates. If not included, Vault will use the specified label__v value to generate a value for the name__v field.
label__v	The label of the new binder templates. This is the name users will see among the available binder templates in the UI.
type__v	The name of the document type to which the templates will be associated.
subtype__v	The name of the document subtype to which the templates will be associated. This is only required if associating the templates with document subtypes.
classification__v	The name of the document classification to which the templates will be associated. This is only required if associating the templates with document classifications.
active__v	Set to true or false to indicate whether or not the new binder templates should be set to active, i.e., available for selection when creating a binder.

Example CSV Input

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

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

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

In this example:

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

Response Details

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

Create Binder Template Node

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.

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

Headers

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

URI Path Parameters

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

Body Parameters

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

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

Example CSV Input: Create Top-Level Section Binder Nodes

id	node_type__v	label__v	order__v	number__v	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 (CSV)

responseStatus,name,errors
SUCCESS,binder_template_1__c,

Update an existing binder template in your Vault.

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

See also: Bulk Update Binder Templates below.

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

Headers

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

Body Parameters

You can update the following fields on binder templates:

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

In this example:

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

Response Details

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

Bulk Update Binder Templates

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 (CSV)

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

Update from 1-500 binder templates in your Vault.

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

See also: Update [Single] Binder Template above.

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

Headers

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

Body Parameters

You can update the following fields on binder templates:

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

Example CSV Input

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

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

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

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

In this example:

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

Response Details

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

Replace Binder Template Nodes

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__v	[Required] Indicates which binding rule to apply (which document versions to link to the section). Options are: default (bind to the latest available version (assumed if binding_rule is blank)), steady-state (bind to latest version in a steady-state), or current (bind to current version).
binding_rule_override__v	[Required] Set to true or false to indicate if the specified binding rule should override documents or sections which already have binding rules set. If set to true, the binding rule is applied to all documents and sections within the current section. If blank or set to false, the binding rule is applied only to documents and sections within the current section that do not have a binding rule specified.

Update Binder Section Binding Rule

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__v	[Required] Indicates which binding rule to apply (which document versions to link to the section). Options are: default (bind to the latest available version (assumed if binding_rule is blank)), steady-state (bind to latest version in a steady-state), or current (bind to current version).
binding_rule_override__v	[Required] Set to true or false to indicate if the specified binding rule should override documents or sections which already have binding rules set. If set to true, the binding rule is applied to all documents and sections within the current section. If blank or set to false, the binding rule is applied only to documents and sections within the current section that do not have a binding rule specified.

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__v	[Optional] Indicates which binding rule to apply (which document versions to link to the section). Options are: default (bind to the latest available version (assumed if binding_rule is blank)), steady-state (bind to latest version in a steady-state), current (bind to current version), or specific (bind to a specific version).
major_version_number__v	If the binding_rule is specific, then this is required and indicates the major version of the document to be linked. Otherwise it is ignored.
minor_version_number__v	If the binding_rule is specific, then this is required and indicates the major version of the document to be linked. Otherwise it is ignored.

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.). Vault limits the total number of custom objects that Admins can create in a single Vault. By default, the limit is 20.

• The API supports retrieval of Vault Objects and their metadata.
• The API does not support creating or updating Vault Objects. This must be done by Admin in the UI.

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

• The API supports retrieval of Vault Object Records and their metadata.
• The API supports creating, updating, and deleting object records.

Learn about Vault Objects & Fields in Vault Help.

Retrieve Object Metadata

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "object": {
    "available_lifecycles": [],
    "label_plural": "Products",
    "help_content": null,
    "prefix": "00P",
    "in_menu": true,
    "description": null,
    "label": "Product",
    "source": "standard",
    "modified_date": "2015-07-30T20:55:16.000Z",
    "created_by": 1,
    "allow_attachments": false,
    "dynamic_security": false,
    "relationships": [
      {
        "relationship_name": "user_role_setup__cr",
        "relationship_label": "User Role Setup",
        "field": "product__c",
        "relationship_type": "reference_inbound",
        "relationship_deletion": "block",
        "object": {
          "url": "/api/v15.0/metadata/vobjects/user_role_setup__v",
          "label": "User Role Setup",
          "name": "user_role_setup__v",
          "label_plural": "User Role Setup",
          "prefix": "0MY"
        }
      }
    ],
    "urls": {
      "field": "/api/v15.0/metadata/vobjects/product__v/fields/{name}",
      "record": "/api/v15.0/vobjects/product__v/{id}",
      "list": "/api/v15.0/vobjects/product__v",
      "metadata": "/api/v15.0/metadata/vobjects/product__v"
    },
    "role_overrides": false,
    "auditable": true,
    "name": "product__v",
    "modified_by": 1,
    "created_date": "2015-07-30T20:55:16.000Z",
    "system_managed": false,
    "fields": [
      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "label": "ID",
        "source": "standard",
        "type": "ID",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "name": "id",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 0
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "start_number": null,
        "label": "Product Name",
        "source": "standard",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": true,
        "system_managed_name": false,
        "value_format": null,
        "unique": true,
        "name": "name__v",
        "list_column": true,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 128,
        "order": 1
      },
      {
        "help_content": null,
        "multi_value": false,
        "editable": true,
        "lookup_relationship_name": null,
        "picklist": "default_status__v",
        "label": "Status",
        "source": "standard",
        "type": "Picklist",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": true,
        "unique": false,
        "name": "status__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 2
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "Product Abbreviation",
        "source": "sample",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "abbreviation__c",
        "list_column": true,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 10,
        "order": 3
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "Generic Name",
        "source": "sample",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "generic_name__c",
        "list_column": true,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 100,
        "order": 4
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "Internal Name",
        "source": "sample",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "internal_name__c",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 100,
        "order": 5
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "Compound ID",
        "source": "sample",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "compound_id__c",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 100,
        "order": 6
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "INN",
        "source": "sample",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "inn__c",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 100,
        "order": 7
      },
      {
        "help_content": null,
        "multi_value": false,
        "editable": true,
        "lookup_relationship_name": null,
        "picklist": "therapeutic_area__c",
        "label": "Therapeutic Area",
        "source": "sample",
        "type": "Picklist",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "therapeutic_area__c",
        "list_column": true,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 8
      },
      {
        "help_content": null,
        "multi_value": true,
        "editable": true,
        "lookup_relationship_name": null,
        "picklist": "product_family__c",
        "label": "Product Family",
        "source": "sample",
        "type": "Picklist",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": false,
        "name": "product_family__c",
        "list_column": true,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 9
      },
      {
        "help_content": null,
        "editable": true,
        "lookup_relationship_name": null,
        "label": "External ID",
        "source": "standard",
        "type": "String",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "unique": true,
        "name": "external_id__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "max_length": 50,
        "order": 10
      },
      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "label": "Created By",
        "source": "standard",
        "type": "Object",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "relationship_type": "reference",
        "unique": false,
        "name": "created_by__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "object": {
          "name": "users"
        },
        "order": 11
      },
      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "label": "Created Date",
        "source": "standard",
        "type": "DateTime",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "name": "created_date__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 12
      },
      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "label": "Last Modified By",
        "source": "standard",
        "type": "Object",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "relationship_type": "reference",
        "unique": false,
        "name": "modified_by__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "object": {
          "name": "users"
        },
        "order": 13
      },
      {
        "help_content": null,
        "editable": false,
        "lookup_relationship_name": null,
        "label": "Last Modified Date",
        "source": "standard",
        "type": "DateTime",
        "modified_date": "2015-07-30T20:55:16.000Z",
        "created_by": 1,
        "required": false,
        "name": "modified_date__v",
        "list_column": false,
        "modified_by": 1,
        "created_date": "2015-07-30T20:55:16.000Z",
        "lookup_source_field": null,
        "status": [
          "active__v"
        ],
        "order": 14
      }
    ],
    "object_class": "base",
    "status": [
      "active__v"
    ],
    "order": 1
  }
}

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

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

Headers

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

URI Path Parameters

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

Query Parameters

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

The response includes all metadata configured on the object.

Retrieve Localized Strings

Request

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

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "object": {
    "available_lifecycles": [],
    "label_plural": "Products",
    "prefix": "00P",
    "description": null,
    "source": "standard",
    "allow_attachments": false,
    "relationships": [
      {
        "relationship_name": "user_role_setup__cr",
        "relationship_label": "User Role Setup",
        "field": "product__c",
        "relationship_type": "reference_inbound",
        "localized_data": {
          "relationship_label": {
            "en": "User Role Setup"
          }
        },
        "relationship_deletion": "block",
        "object": {
          "url": "/api/v15.0/metadata/vobjects/user_role_setup__v",
          "label": "User Role Setup",
          "name": "user_role_setup__v",
          "label_plural": "User Role Setup",
          "prefix": "0MY",
          "localized_data": {
            "label_plural": {
              "de": "Benutzerrollenkonfiguration",
              "ru": "Настройки функции пользователя",
              "kr": "사용자 역할 설정",
              "en": "User Role Setup",
              "it": "Configurazione ruolo utente",
              "pt_BR": "Configuração da função de usuário",
              "fr": "Configuration du rôle utilisateur",
              "zh": "用户角色设置",
              "es": "Configuración de cargos de usuario",
              "zh_TW": "使用者角色設定",
              "ja": "ユーザロール設定",
              "pl": "Konfiguracja roli użytkownika",
              "tr": "Kullanıcı Rolü Ayarı",
              "pt_PT": "Configuração da função de utilizador"
            },
            "label": {
              "de": "Benutzerrollenkonfiguration",
              "ru": "Настройки функции пользователя",
              "kr": "사용자 역할 설정",
              "en": "User Role Setup",
              "it": "Configurazione ruolo utente",
              "pt_BR": "Configuração da função de usuário",
              "fr": "Configuration du rôle utilisateur",
              "zh": "用户角色设置",
              "es": "Configuración de cargos de usuario",
              "zh_TW": "使用者角色設定",
              "ja": "ユーザロール設定",
              "pl": "Konfiguracja roli użytkownika",
              "tr": "Kullanıcı Rolü Ayarı",
              "pt_PT": "Configuração da função de utilizador"
            }
          }
        }
      }
    ],
    "urls": {
      "field": "/api/v15.0/metadata/vobjects/product__v/fields/{name}",
      "record": "/api/v15.0/vobjects/product__v/{id}",
      "list": "/api/v15.0/vobjects/product__v",
      "metadata": "/api/v15.0/metadata/vobjects/product__v"
    },
    "role_overrides": false,
    "localized_data": {
      "label_plural": {
        "de": "Produkte",
        "ru": "Продукты",
        "kr": "제품",
        "en": "Products",
        "pt_BR": "Produtos",
        "it": "Prodotti",
        "fr": "Produits",
        "es": "Productos",
        "zh": "产品",
        "zh_TW": "產品",
        "ja": "製品",
        "pl": "Produkty",
        "tr": "Ürünler",
        "pt_PT": "Produtos"
      },
      "label": {
        "de": "Produkt",
        "ru": "Продукт",
        "kr": "제품",
        "en": "Product",
        "pt_BR": "Produto",
        "it": "Prodotto",
        "fr": "Produit",
        "es": "Producto",
        "zh": "产品",
        "zh_TW": "產品",
        "ja": "製品",
        "pl": "Produkt",
        "tr": "Ürün",
        "pt_PT": "Produto"
      }
    }
  }
}

Query Parameters

Name	Description
loc	Set to true to retrieve localized (translated) strings for the label, label_plural, and help_content object fields.

Response Details

When localized data is requested, the response includes an additional localized_data field. This contains translated fields and field values on each object field for which localized strings have been configured. This data is only available at the object and field level and only if localized strings have been configured on objects in your Vault.

Retrieve Object Field Metadata

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "field": {
    "help_content": null,
    "editable": true,
    "lookup_relationship_name": null,
    "start_number": null,
    "label": "Product Name",
    "source": "standard",
    "type": "String",
    "modified_date": "2015-07-30T20:55:16.000Z",
    "created_by": 1,
    "required": true,
    "system_managed_name": false,
    "value_format": null,
    "unique": true,
    "name": "name__v",
    "list_column": true,
    "modified_by": 1,
    "created_date": "2015-07-30T20:55:16.000Z",
    "lookup_source_field": null,
    "status": [
      "active__v"
    ],
    "max_length": 128,
    "order": 1
  }
}

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	To retrieve localized (translated) strings, include the parameter loc=true. See the next request below for details.

The response includes all metadata configured on the specific Vault Object field.

Retrieve Localized Strings

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "field": {
    "help_content": null,
    "editable": true,
    "lookup_relationship_name": null,
    "start_number": null,
    "label": "Product Name",
    "source": "standard",
    "type": "String",
    "modified_date": "2015-07-30T20:55:16.000Z",
    "created_by": 1,
    "required": true,
    "localized_data": {
      "label": {
        "de": "Produktbezeichnung",
        "ru": "Название продукта",
        "kr": "제품 이름",
        "en": "Product Name",
        "pt_BR": "Nome do produto",
        "it": "Nome prodotto",
        "fr": "Nom de produit",
        "es": "Nombre de producto",
        "zh": "产品名称",
        "zh_TW": "產品名稱",
        "ja": "製品名",
        "pl": "Nazwa produktu",
        "tr": "Ürün Adı",
        "pt_PT": "Nome do produto"
      }
    },
    "system_managed_name": false,
    "value_format": null,
    "unique": true,
    "name": "name__v",
    "list_column": true,
    "modified_by": 1,
    "created_date": "2015-07-30T20:55:16.000Z",
    "lookup_source_field": null,
    "status": [
      "active__v"
    ],
    "max_length": 128,
    "order": 1
  }
}

Query Parameters

Name	Description
loc	Set to true to retrieve localized (translated) strings for the label and help_content object fields.

Response Details

When localized data is requested, the response includes an additional localized_data field. This contains translated fields and field values on each object field for which localized strings have been configured. This data is only available at the object and field level and only if localized strings have been configured on objects in your Vault.

Retrieve Object Collection

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "objects": [
    {
      "url": "/api/v15.0/metadata/vobjects/product__v",
      "label": "Product",
      "name": "product__v",
      "label_plural": "Products",
      "prefix": "00P",
      "order": 1,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/country__v",
      "label": "Country",
      "name": "country__v",
      "label_plural": "Countries",
      "prefix": "00C",
      "order": 2,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/application_role__v",
      "label": "Application Role",
      "name": "application_role__v",
      "label_plural": "Application Role",
      "prefix": "0AR",
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/doc_type_group__v",
      "label": "Document Type Group",
      "name": "doc_type_group__v",
      "label_plural": "Document Type Groups",
      "prefix": "0DG",
      "order": 3,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/doc_type_detail__v",
      "label": "Document Type Detail",
      "name": "doc_type_detail__v",
      "label_plural": "Document Type Details",
      "prefix": "0DT",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/user_role_setup__v",
      "label": "User Role Setup",
      "name": "user_role_setup__v",
      "label_plural": "User Role Setup",
      "prefix": "0MY",
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/binder_metadata__v",
      "label": "Binder Section Metadata",
      "name": "binder_metadata__v",
      "label_plural": "Binder Sections Metadata",
      "prefix": "OBD",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/vault_component__v",
      "label": "Vault Component",
      "name": "vault_component__v",
      "label_plural": "Vault Components",
      "prefix": "0CD",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/outbound_package__v",
      "label": "Outbound Package",
      "name": "outbound_package__v",
      "label_plural": "Outbound Packages",
      "prefix": "0PO",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/package_component__v",
      "label": "Package Component",
      "name": "package_component__v",
      "label_plural": "Package Components",
      "prefix": "0CP",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/directory__v",
      "label": "Directory",
      "name": "directory__v",
      "label_plural": "Directories",
      "prefix": "0DI",
      "order": 4,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/survey__v",
      "label": "Survey",
      "name": "survey__v",
      "label_plural": "Surveys",
      "prefix": "0SV",
      "order": 5,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/distribution__v",
      "label": "Distribution",
      "name": "distribution__v",
      "label_plural": "Distributions",
      "prefix": "0DS",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    },
    {
      "url": "/api/v15.0/metadata/vobjects/crm_org__v",
      "label": "CRM Org",
      "name": "crm_org__v",
      "label_plural": "CRM Orgs",
      "prefix": "0CO",
      "in_menu": false,
      "source": "standard",
      "status": [
        "active__v"
      ]
    }
  ]
}

GET /api/{version}/metadata/vobjects

Headers

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

Query Parameters

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

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.

Retrieve Localized Strings

Request

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

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "objects": [
    {
      "url": "/api/v15.0/metadata/vobjects/product__v",
      "label": "Product",
      "name": "product__v",
      "label_plural": "Products",
      "prefix": "00P",
      "order": 1,
      "in_menu": true,
      "source": "standard",
      "status": [
        "active__v"
      ],
      "localized_data": {
        "label_plural": {
          "de": "Produkte",
          "ru": "Продукты",
          "kr": "제품",
          "en": "Products",
          "pt_BR": "Produtos",
          "it": "Prodotti",
          "fr": "Produits",
          "es": "Productos",
          "zh": "产品",
          "zh_TW": "產品",
          "ja": "製品",
          "pl": "Produkty",
          "tr": "Ürünler",
          "pt_PT": "Produtos"
        },
        "label": {
          "de": "Produkt",
          "ru": "Продукт",
          "kr": "제품",
          "en": "Product",
          "pt_BR": "Produto",
          "it": "Prodotto",
          "fr": "Produit",
          "es": "Producto",
          "zh": "产品",
          "zh_TW": "產品",
          "ja": "製品",
          "pl": "Produkt",
          "tr": "Ürün",
          "pt_PT": "Produto"
        }
      }
    },
  ]
}

Query Parameters

Name	Description
loc	Set to true to retrieve localized (translated) strings for the label and label_plural object fields.

Response Details

When localized data is requested, the response includes an additional localized_data field. This contains translated fields and field values on each object field for which localized strings have been configured. This data is only available at the object and field level and only if localized strings have been configured on objects in your Vault.

Retrieve Object Record Collection

Request

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

Response

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

Retrieve all records for a specific Vault Object.

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

Headers

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

URI Path Parameters

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

Query Parameters

Name	Description
fields	To specify fields to retrieve, include the parameter fields={FIELD_NAMES}. See the next request below 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.

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.

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

Request

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

Response

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

Create Object Records in bulk.

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 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard format.
• The maximum batch size is 500.

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

URI Path Parameters

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

Body Parameters

Upload parameters as a JSON or CSV file.

Name	Description
name__v	This field is required unless it is set to system-managed. To find out if an object uses system-managed naming, retrieve its name__v field and look for the system_managed_name property set to true or false. Learn more about system-managed naming in Vault Help.
object_type__v	Optional: To create objects of a specific object type, add this field with the id of the object type.
object_type__v.api_name__v	Optional: To create objects of a specific object type, add this field with the name of the object type.
source_record_id	Optional: To copy an existing object record, add this field with the id of the existing object record. Any values specified for other fields will override the copied values. If you want to make a deep copy of a record, see the Deep Copy endpoint.

Note that if object_type__v and object_type__v.api_name__v are both included, Vault creates the object with the type specified in object_type__v.

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

Name	Description
idParam	To upsert object records, add idParam={field_name} to the request endpoint. For example, idParam=external_id__v. Note that the specified object field must have unique set to true in the object metadata.

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.

Create User Object Records

To create user__sys records, your input file must have all required fields on user__sys. 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.
• Changing user passwords.

The following fields are required when creating user__sys records.

Name	Description
email__sys	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__sys	The user’s first name.
last_name__sys	The user’s last name.
username__sys	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__sys	The user’s preferred language.
locale__sys	The user’s location.
timezone__sys	The user’s time zone.
license_type__sys	Optional: The user’s license type. If omitted, default value is full__v.
security_profile__sys	The user’s security profile.
status__v	The status of 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

On SUCCESS, Vault returns the id and url of each new record.

Note that if an object has a field default configured, the value you use for that field overrides the default.

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-binary @"C:\Vault\Object Records\update_object_records.csv" \
https://myvault.veevavault.com/api/v8.0/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        },
        {
            "responseStatus": "SUCCESS"
        },
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not updated."
                }
            ]
        }
    ]
}

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

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

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

Headers

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

URI Path Parameters

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

Body Parameters

Upload parameters as a JSON or CSV file.

Name	Description
id	The object record ID.

Additional Notes:

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

Delete Object Record

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        },
        {
            "responseStatus": "SUCCESS"
        },
        {
            "responseStatus": "FAILURE",
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not deleted."
                }
            ]
        }
    ]
}

Delete Object Records in bulk. 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 format.
• The maximum batch size is 500.

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

Headers

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

URI Path Parameters

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

Body Parameters

Upload parameters as a JSON or CSV file.

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

Query Parameters

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

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

Cascade Delete Object Record

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.

Object Types

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

Retrieve Details from All Object Types

Request

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

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/v15.0/configuration/Objecttype.product__v.base__v

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The object name.
{object_type}	The object type name.

Response

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

Change Object Type

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/v15.0/vobjects/product__v/actions/changetype

Response

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

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

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The name of the object.

Body Parameters

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

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.0/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 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 format.
• The maximum batch size is 500.

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

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.

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
id	The object record ID.
role__v.users	A string of user id values for the new role.
role__v.groups	A string of user id values for the new group.

See Example JSON 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 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 format.
• 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
id	The object record ID.
role__v.users	A string of user id values to remove.
role__v.groups	A string of group id values to remove.

See Example JSON 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.

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

Deep Copy copies an object record, including all of the record’s related child and grandchild records. A single deep copy cannot copy more than 10,000 records at a time.

See Copying Object Records for details on required access permissions.

You can perform a regular copy an object record using the create object endpoint with the source_record_id field.

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

Headers

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

URI Path Parameters

Name	Description
{object_name}	The name of the parent object to copy. For example, product__v.
{object_record_ID}	The ID of the specific object record to copy.

Body

In the body, pass in any fields to override the copied fields. For example, add the abbreviation__c field to override the copied value for abbreviation.

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/v15.0/objects/deletions/vobjects/product__v

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "total": 35,
        "limit": 200,
        "size": 35,
        "offset": 0
    },
    "data": [
        {
            "id": "0PR0202",
            "deleted_date": "2016-01-20T05:24:20Z"
        },
        {
            "id": "0PR0303",
            "deleted_date": "2016-01-20T04:23:21Z"
        },
        {
            "id": "0PR0404",
            "deleted_date": "2016-01-20T03:22:22Z"
        },
    ]
}

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

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

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 (abridged)

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

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

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

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

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

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

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

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

Create Object Record Attachment

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.

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 POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "description__v=This is my description for this attachment." \
https://myvault.veevavault.com/api/v15.0/vobjects/site__v/1357752909483/attachments/571

Response

{
    "responseStatus": "SUCCESS"
}

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

Headers

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

URI Path Parameters

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

Body Parameters

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

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

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 automatically sends a notification to all users with system notifications enabled whenever the API limit is exceeded. Admins can also set up “threshold” limits to notify users when the daily API count is close to the limit. Learn more in Vault Help.

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

GET /api/{version}/limits

Headers

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

Response Details

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

RIM Submissions 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/objects/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 your FTP staging server. The submission to be imported must be located in a folder called “SubmissionsArchive” at the root of your FTP server. In the request, add the file column to your input and enter the path/name of each file relative to the FTP root.

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

Headers

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

URI Path Parameters

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

Body Parameters

Name	Description
file	Use the file parameter to specify the location of the submission folder and files or ZIP file previously uploaded to your FTP staging server.

Response Details

• The Content-Type header is set to accept a name-value pair input.
• The file parameter specifies the location/name of the folder or ZIP file to be imported. The file must be located in the “SubmissionsArchive” folder on your FTP staging server.

On SUCCESS, the response includes the following information:

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

You may also receive one or more warnings. The warnings shown above indicate that the folders being imported do not match the object records in our Vault. We can either change the names in either location or simply ignore the warnings.

Additional notes:

Before submitting this request, we created a submission__v object record and application__v object record in our Vault. We also created submissions ZIP file containing a “Submission” folder and “Application” folder. This was loaded to our FTP staging server awaiting import. Ideally, we would have named and structured the folders to match that of the submission that was sent to the health authority and which we are now archiving. However, this is not critical to the import process.

Retrieve Submission Import Results

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 SubmissionsArchive status (archive_status__v) of:

Name	Description
IMPORT_IN_PROGRESS	This will terminate the import job and set the archive_status__v field on the submission__v object record to “Error”. The submission must be removed before a re-import can be done. See Remove Submission above.
REMOVAL_IN_PROGRESS	This will terminate the import removal job and set the archive_status__v field on the submission__v object record to “Error”. The submission must be removed before a re-import can be done. See Remove Submission above.
IMPORT_IN_QUEUE	This will remove the import from the job queue and set the archive_status__v field on the submission__v object record to “Null”. See Import Submission above.
REMOVAL_IN_QUEUE	This will remove the import removal from the job queue and set the archive_status__v field on the submission__v object record to “Error”. See Import Submission above.

To retrieve the archive_status__v, GET /api/{version}/vobjects/submission__v/{submission_id}. See Retrieve Object Record above.

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

Headers

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

URI Path Parameters

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

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

To export the latest version of a SubmissionsArchive binder:

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

To export a specific version of a SubmissionsArchive binder:

POST /api/{version}/objects/binders/{binder_id}/versions/{major_version}/{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. See Retrieve SubmissionsArchive Binder for how to get node values.

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

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/vobjects/submission__v/00S000000000101/actions/viewer

Response

{
    "responseStatus": "SUCCESS",
    "document": {
        "id": 454,
        "binder__v": true,
        "major_version_number__v": 1,
        "minor_version_number__v": 0,
        "status__v": "Final",
        "Applications__v": [
            "00A000000000101"
        ],
        "name__v": "nda123456",
        "lifecycle__v": "SubmissionsArchive Lifecycle",
        "type__v": "SubmissionsArchive",
        "subtype__v": "Structure"
    },
    "versions": [
        {
            "number": "1.0",
            "value": "https://myvault.veevavault.com/api/v15.0/objects/binders/454/versions/1/0"
        }
    ],
    "binder": {
        "nodes": [
        {
        "properties": {
          "section_number__v": "1",
          "name__v": "m1-administrative-information-and-prescribing-information",
          "order__v": 1,
          "type__v": "section",
          "id": "1458077095468:-826390827",
          "parent_id__v": "rootNode",
          "sa_title": "Module 1 Administrative Information"
        }
        },
        {
        "properties": {
          "name__v": "m1-1-forms",
          "order__v": 1,
          "type__v": "section",
          "id": "1458077095654:-1282798513",
          "parent_id__v": "1458077095468:-826390827",
          "sa_title": "1.1 Forms"
        }
        },
        {
        "properties": {
          "name__v": "m1-1-2-form-356h",
          "order__v": 1,
          "type__v": "section",
          "id": "1458077095823:-61354986",
          "parent_id__v": "1458077095654:-1282798513",
          "sa_title": "1.12 Application form: FDA form 356h"
        }
        },
        {
        "properties": {
          "document_id__v": 2318,
          "name__v": "1-1-2-form-356h",
          "order__v": 1,
          "type__v": "document",
          "id": "1458077095823:-61354986",
          "parent_id__v": "1458077095823:-61354986",
          "sa_title": "FDA Form 356h",
          "sa_id": "veeva10923",
          "sa_operation": "New",
          "sa_xlinkhref": "1-1-2-form-356h.pdf",
          "sa_xlinktype": "simple",
          "sa_checksum_type": "md5",
          "sa_checksum": "96b3eb46bfa348c0c798943e78381ca6",
          "sa_application_version": "PDF 1.4"
        }
        },
        {
        "properties": {
          "name__v": "m3-quality",
          "order__v": 2,
          "type__v": "section",
          "id": "1458079746774:-718199953",
          "parent_id__v": "rootNode",
          "sa_title": "Module 3 Quality"
        }
        },
        {
        "properties": {
          "name__v": "m3-2-body-of-data",
          "order__v": 1,
          "type__v": "section",
          "id": "1458079747018:182443898",
          "parent_id__v": "1458079746774:-718199953",
          "sa_title": "3.2 Body of Data"
        }
        },
        {
        "properties": {
          "name__v": "m3-2-s-drug-substance",
          "order__v": 1,
          "type__v": "section",
          "id": "1458079747401:1533319790",
          "parent_id__v": "1458079747018:182443898",
          "sa_title": "3.2.S Drug substance",
          "drug_substance_xml": "cholepridol",
          "drug_substance__v": "0DS000000000101",
          "manufacturer_xml": "Veeva Labs",
          "manufacturer__v": "00M000000000101"
        }
        },
        {
        "properties": {
          "name__v": "m3-2-s-4-control-of-drug-substance",
          "order__v": 1,
          "type__v": "section",
          "id": "1458079747664:-30973505",
          "parent_id__v": "1458079747401:1533319790",
          "sa_title": "3.2.S.4 Control of drug substance",
          "drug_substance_xml": "cholepridol",
          "drug_substance__v": "0DS000000000101",
          "manufacturer_xml": "Veeva Labs",
          "manufacturer__v": "00M000000000101"
        }
        },
        {
        "properties": {
          "name__v": "m3-2-s-4-2-analytical-procedures",
          "order__v": 1,
          "type__v": "section",
          "id": "1458079747892:2036125551",
          "parent_id__v": "1458079747664:-30973505",
          "sa_title": "3.2.S.4.2 Analytical Procedures",
          "drug_substance_xml": "cholepridol",
          "drug_substance__v": "0DS000000000101",
          "manufacturer_xml": "Veeva Labs",
          "manufacturer__v": "00M000000000101"
        }
        },
        {
        "properties": {
          "document_id__v": 1016,
          "name__v": "32s42-m062sf220-analytical-method",
          "order__v": 1,
          "type__v": "document",
          "id": "1458077095823:1029339123",
          "parent_id__v": "1458079747664:-30973505",
          "sa_title": "Analytical Method M-062-SF220",
          "sa_id": "veeva1543",
          "sa_operation": "New",
          "sa_xlinkhref": "m3/32-body-data/32s-drug-sub/cholepridol-veeva-labs/32s4-contr-drug-sub/32s42-analyt-proc/32s42-m062sf220-analytical-method.pdf",
          "sa_xlinktype": "simple",
          "sa_checksum_type": "md5",
          "sa_checksum": "0022dea54ca0dfb309f49ff22dcf1c46",
          "sa_application_version": "PDF 1.4",
          "drug_substance_xml": "cholepridol",
          "drug_substance__v": "0DS000000000101",
          "manufacturer_xml": "Veeva Labs",
          "manufacturer__v": "00M000000000101"
        }
      }
    ]
  }
}

Before submitting this request:

• You must be assigned permissions to use the API.
• You must have the View Document permission for the binder. Only documents in the binder which you have the View Document permission will be returned.

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

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

Headers

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

URI Path Parameters

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

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 your FTP staging server.
user_id__v	The id field value of the Vault user who initiated the submission export job.

Download Exported Submission Files via FTP

Once your submission export job has been successfully completed, you can download the files from your FTP staging server.

Prerequisites

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

• The submission export job must have been successfully completed.
• The API user must have a permission set which allows them FTP download permissions.

Downloading the Files

The exported submission is packaged in a ZIP file on your FTP staging server. Learn more.

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. The single document API does not support assigning users and groups to roles with Dynamic Access Control (DAC) enabled.

POST /api/{version}/objects/documents/{id}/roles

Headers

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

URI Path Parameters

Name	Description
{id}	The document or binder id field value.

Body Parameters

Include name-value pairs of all users or groups with their corresponding roles in the form {Role_name}.{USERS or GROUPS}=ID1,ID2,ID3. For example, reviewer__v.users = "3003, 4005".

Response Details

The response includes ROLE:ID pairs for the users and groups successfully assigned to roles on the document or binder.

Assign Users & Groups to Roles on Multiple Documents

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.groups": [
                3311303,
                4411606
            ],
            "reviewer__v.users": [
                12021,
                12022,
                12023,
                12124
            ]
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.groups": [
                3311303,
                4411606
            ],
            "reviewer__v.users": [
                12021,
                12022,
                12023,
                12124
            ]
        },
        {
           "responseStatus":"FAILURE",
           "id":"773",
           "errors":[
              {
                 "type":"INVALID_DATA",
                 "message":"Error message describing why the users and groups were not assigned to roles on this document.."
              }
           ]
        }
    ]
}

Assign users and groups to roles on a document or binder in bulk.

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

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

Assigning users and groups to document roles is additive. For example, if groups 1, 2, and 3 are currently assigned to a particular role and you assign groups 3, 4, and 5 to the same role, the final list of groups assigned to the role will be 1, 2, 3, 4, and 5. Users and groups (IDs) in the input that are either invalid (not recognized) or cannot be assigned to a role due to permissions are ignored and not processed.

Headers

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

Body Parameters

You can add parameters in the request body, or upload them as a CSV file.

Name	Description
id	The document ID.
role__v.users	A string of user id values for the new role.
role__v.groups	A string of user id values for the new group.

For example,

id	reviewer__v.users	reviewer__v.groups	approver__v.users	approver__v.groups
771	“12021,12022”	“3311303,3311404”	22124	4411606

Response Details

The response includes role:id pairs for the users and groups successfully assigned to roles.

Remove Users & Groups from Roles on a Single Document

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "User/group deleted from document role",
  "updatedRoles": {
    "consumer__v": {
      "users": [
        19376
      ]
    }
  }
}

Remove users and groups from roles on a single document or binder.

DELETE /api/{version}/objects/documents/{doc_id}/roles/{role_name}.{user_or_group}/{id}

Headers

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

URI Path Parameters

Name	Description
{doc_id}	The id value of the document or binder from which to remove roles.
{role_name}	The name of the role to remove the users or groups from.
{user_or_group}	Choose to remove a user or a group from a role. Possible values for this parameter are either user or group.
{id}	The id value of the user or group to remove from the role.

Remove Users and Groups from Roles on Multiple Documents

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.groups": [
                4411606
            ],
            "reviewer__v.users": [
                12124
            ]
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.groups": [
                4411606
            ],
            "reviewer__v.users": [
                12124
            ]
        },
        {
           "responseStatus":"FAILURE",
           "id":"773",
           "errors":[
              {
                 "type":"INVALID_DATA",
                 "message":"Error message describing why the users and groups were not removed from roles on this document."
              }
           ]
        }
    ]
}

Remove users and groups 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 format.
• The maximum batch size is 1000.

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

Headers

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

Body Parameters

You can add parameters in the request body, or upload them as a CSV file.

Name	Description
id	The document ID.
role__v.users	A string of user id values to remove.
role__v.groups	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

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 (abridged)

{
  "responseStatus": "SUCCESS",
  "properties": [
    {
      "name": "user_name__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_first_name__v",
      "type": "String",
      "length": 100,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_last_name__v",
      "type": "String",
      "length": 100,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "alias__v",
      "type": "String",
      "length": 40,
      "editable": true,
      "queryable": false,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_email__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_timezone__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "Pacific/Niue",
          "label": "(GMT-11:00) Niue Time (Pacific/Niue)"
        },
        {
          "value": "Pacific/Pago_Pago",
          "label": "(GMT-11:00) Samoa Standard Time (Pacific/Pago_Pago)"
        },
      ]
    },
    {
      "name": "user_locale__v",
      "type": "String",
      "length": 10,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "pt_BR",
          "label": "Brazil"
        },
        {
          "value": "es_ES",
          "label": "Spain"
        },
      ]
    },
    {
      "name": "user_title__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "office_phone__v",
      "type": "String",
      "length": 20,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "fax__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "mobile_phone__v",
      "type": "String",
      "length": 20,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "site__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "is_domain_admin__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "active__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "domain_active__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "security_policy_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "securitypolicies",
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_needs_to_change_password__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "id",
      "type": "id",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_date__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_by__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "modified_date__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "modified_by__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "domain_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "domains",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "vault_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "vaults",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": true,
      "onCreateEditable": false
    },
    {
      "name": "federated_id__v",
      "type": "String",
      "length": 100,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "salesforce_user_name__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "last_login__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "medidata_uuid__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "user_language__v",
      "type": "String",
      "length": 10,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "en",
          "label": "English"
        },
        {
          "value": "ja",
          "label": "Japanese"
        },
      ]
    },
    {
      "name": "company__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "group_id__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "groups",
      "editable": false,
      "queryable": false,
      "required": false,
      "multivalue": true,
      "onCreateEditable": false
    },
    {
      "name": "security_profile__v",
      "type": "ObjectReference",
      "length": 40,
      "object": "Securityprofile",
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true,
      "values": [
        {
          "value": "business_admin__v",
          "label": "Business Administrator"
        },
        {
          "value": "document_user__v",
          "label": "Document User"
        },
        {
          "value": "external_user__v",
          "label": "External User"
        },
        {
          "value": "read_only_user__v",
          "label": "Read-Only User"
        },
        {
          "value": "system_admin__v",
          "label": "System Administrator"
        },
        {
          "value": "vault_owner__v",
          "label": "Vault Owner"
        },
        {
          "value": "view_based_user__v",
          "label": "View-Based User"
        }
      ]
    },
    {
      "name": "license_type__v",
      "type": "Picklist",
      "length": 40,
      "picklist": "license_type__v",
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    }
  ]
}

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 (abridged)

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

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. Use the value me to get information for the currently authenticated 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 the FTP staging server. After creation, you can assign these users to Vaults with the Update Vault Membership endpoint.

POST /api/{version}/objects/users

Headers

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

Body Parameters

Name	Description
user_name__v	The user’s Vault username (login credential). For example, ewoodhouse@veepharm.com
user_first_name__v	The user’s first name.
user_last_name__v	The user’s last name.
user_email__v	The user’s email address.
user_timezone__v	The user’s time zone. Retrieve values from Retrieve Users.
user_locale__v	The user’s location. Retrieve values from Retrieve Users.
security_policy_id__v	The user’s security policy. Retrieve values from Retrieve All Security Policies.
user_language__v	The user’s preferred language. Retrieve values from Retrieve Users.
security_profile__v	Optional: The user’s security profile. If omitted, the default value is document_user__v.
license_type__v	Optional: The user’s license type. If omitted, default value is full__v.
file	Optional: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.

You may add values to any other editable user field, unless you are are adding a cross-domain user (see below). See Retrieve Users for all possible values.

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__v	The user’s Vault username (login credential). For example, ewoodhouse@veepharm.com
security_profile__v	Optional: The user’s security profile. If omitted, default value is document_user__v.
license_type__v	Optional: The user’s license type. If omitted, default value is full__v.

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.

• The maximum input file size is 1GB.
• The values in the input must be UTF-8 encoded.
• CSVs must follow the standard format.
• The maximum batch size is 500.
• If you want to add profile pictures, you must upload these to the FTP staging server.

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 are adding a cross-domain 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. See Vault Membership below.

Name	Description
user_name__v	The user’s Vault username (login credential). For example, ewoodhouse@veepharm.com
user_first_name__v	The user’s first name.
user_last_name__v	The user’s last name.
user_email__v	The user’s email address.
user_timezone__v	The user’s time zone. Retrieve values from Retrieve Users.
user_locale__v	The user’s location. Retrieve values from Retrieve Users.
security_policy_id__v	The user’s security policy. Retrieve values from Retrieve All Security Policies.
user_language__v	The user’s preferred language. Retrieve values from Retrieve Users.
file	Optional: The file path of a profile picture from the FTP. Must be JPG, PNG, or GIF, and less than 10MB in size. Vault automatically resizes images to 64 x 64 pixels and removes the animations from GIFs.
domain	Optional: If you set this to true, the user will not be assigned to a Vault.
security_profile__v	Optional: The user’s security profile. If omitted, default value is document_user__v.
license_type__v	Optional: The user’s license type. If omitted, default value is full__v.
vault_membership	Optional: Use this field to assign a user to individual Vaults within your domain. This is required to create cross-domain users. See below for how to configure.
app_licensing	Optional: Use this field to assign a user to individual applications within your Vault. See below for how to configure.

Vault Membership

To assign user permissions across Vaults or create cross-domain users, you must include the vault_membership column configured with the following fields:

Name	Description
vault_id	The Vault ID to assign the user to.
active__v	Optional: Set the user to active (true) or inactive (false). If not specified, default value is true.
security_profile__v	Optional: Set the user’s security profile, for example, read_only_user__v. If not specified, this value defaults to document_user__v.
license_type__v	Optional: Set the user’s license type, for example, read_only__v. If not specified, this value defaults to full__v.

For example, to add an active user to Vault ID 3003 with the system_admin__vsecurity profile and the full__v license type:

vault_membership
3003:true:system_admin__v:full__v

Application Licensing

To add a user to specific applications within a Vault or across Vaults, you must include the app_licensing column configured with the following fields:

Name	Description
vault_id	The Vault ID to assign the user to.
active__v	Optional: Set the user to active (true) or inactive (false). If not specified, default value is true.
application_name	The application to add the user to. Possible values are: rimSubsArch_v rimSubs_v rimReg_v qualityQms_v qualityQdocs_v qOneQdocs_v qOneQms_v
license_type__v	Optional: Set the user’s license type, for example, read_only__v.

The format for adding these fields is:

{vault_id}|{application_name}{:active__v}{:license_type__v}

To add a user to more than one application, separate the applications with a pipe. To add a user to applications in multiple Vaults, separate the Vaults with a semicolon. For example:

app_licensing
3003|rimReg_v:true:full__v|rimSubs_v:true:full__v;4112|rimSubs_v:true:full__v

This adds an active user to both RIM Registrations and RIM Submissions in Vault ID 3003, and to the RIM Submissions application in Vault ID 4112, all with the full__v license type.

Add Cross-Domain Users

The only required fields for cross-domain users are user_name__v and vault_membership. All other metadata fields are ignored. Learn more about cross-domain users in Vault Help.

Name	Description
user_name__v	The user’s Vault username (login credential). For example, ewoodhouse@veepharm.com.
vault_membership	Assign this user permissions across domains. See Vault Membership Fields above for description.

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.

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

Response

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

Update information for a single user. To update information for multiuple 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.

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.

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. The following are the only required fields. You can include any editable user field and value in the input.

Name	Description
id	The ID of the user to update.

Disable User

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 Your 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/v15.0/objects/users/25496/password

Response

{
    "responseStatus": "SUCCESS"
}

Change the password for the currently authenticated user.

POST /api/{version}/objects/users/{user_id}/password

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. You can also use the value me to change your password.

Body Parameters

Name	Description
password__v	Enter the current password.
new_password__v	Enter the new password.

Passwords must meet minimum requirements. Learn about Password Requirements in Vault Help.

Response Details

On SUCCESS, the password will be 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__v	Set the user status to active (true) or inactive (false). If omitted, this value defaults to active__v.
security_profile__v	Optional: Assigns the user a specific security profile in the Vault. If omitted, defaults to document_user__v.
license_type__v	Optional: 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 User Permissions

Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.1/objects/me/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. See example below.

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/v15.0/metadata/objects/groups

Response

{
  "responseStatus": "SUCCESS",
  "properties": [
    {
      "name": "id",
      "type": "id",
      "length": 20,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "label__v",
      "type": "String",
      "length": 255,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "group_description__v",
      "type": "String",
      "length": 200,
      "editable": true,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": true
    },
    {
      "name": "system_group__v",
      "type": "Boolean",
      "length": 1,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_date__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "created_by__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "modified_date__v",
      "type": "Calendar",
      "length": 0,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "modified_by__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "members__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": true,
      "queryable": false,
      "required": true,
      "multivalue": true,
      "onCreateEditable": true
    },
    {
      "name": "implied_members__v",
      "type": "ObjectReference",
      "length": 20,
      "object": "users",
      "editable": false,
      "queryable": false,
      "required": false,
      "multivalue": true,
      "onCreateEditable": false
    },
    {
      "name": "security_profiles__v",
      "type": "ObjectReference",
      "length": 40,
      "object": "Securityprofile",
      "editable": true,
      "queryable": false,
      "required": false,
      "multivalue": true,
      "onCreateEditable": true
    },
    {
      "name": "active__v",
      "type": "Boolean",
      "length": 1,
      "editable": true,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "name__v",
      "type": "String",
      "length": 40,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "editable__v",
      "type": "Boolean",
      "length": 1,
      "editable": false,
      "queryable": true,
      "required": false,
      "multivalue": false,
      "onCreateEditable": false
    },
    {
      "name": "type__v",
      "type": "String",
      "length": 40,
      "editable": false,
      "queryable": true,
      "required": true,
      "multivalue": false,
      "onCreateEditable": false
    }
  ]
}

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/v15.0/objects/groups

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "groups": [
    {
      "group": {
        "members__v": [
          25496,
          25513,
          25514,
          25515,
          25519,
          25524,
          25525,
          25526,
          25527,
          25528,
          25532
        ],
        "active__v": true,
        "security_profiles__v": [
          "document_user__v",
          "business_admin__v",
          "system_admin__v",
          "vault_owner__v"
        ],
        "name__v": "all_internal_users__v",
        "modified_by__v": 25524,
        "editable__v": true,
        "modified_date__v": "2016-03-08T21:13:49.000Z",
        "group_description__v": "All Internal Vault Users (System Provided Group)",
        "system_group__v": true,
        "label__v": "All Internal Users",
        "created_date__v": "2014-02-17T10:09:03.000Z",
        "type__v": "System Provided Group",
        "id": 1,
        "created_by__v": 1
      }
    }
  ]
}

Retrieve all groups except Auto Managed groups.

GET /api/{version}/objects/groups

Retrieve all Auto Managed groups.

GET /api/{version}/objects/groups/auto

Headers

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

URI Path Parameters

Name	Description
/auto	Optional: Add /auto to this endpoint to retrieve Auto Managed groups. Learn more about Auto Managed groups in Vault Help.

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 Group

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "groups": [
    {
      "group": {
        "members__v": [
          25518,
          25519,
          25520
        ],
        "active__v": true,
        "security_profiles__v": [],
        "name__v": "cholecap_editors_group__c",
        "modified_by__v": 46916,
        "editable__v": true,
        "modified_date__v": "2015-06-24T20:11:17.000Z",
        "group_description__v": null,
        "system_group__v": false,
        "label__v": "Cholecap Editors Group",
        "created_date__v": "2015-06-24T20:11:17.000Z",
        "type__v": "User Managed Group",
        "id": 1435176677013,
        "created_by__v": 46916
      }
    }
  ]
}

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__v	[Required] Enter a group label. Vault uses this to create the group name__v value.
members__v	[Optional] Add a comma-separated list of user IDs. This manually assigns individual users to the group.
security_profiles__v	[Optional] Add a comma-separated list of security profiles. This automatically adds all users with the security profile to the group. These are implied_members__v.
active__v	[Optional] By default, the new group will be created as active. To set the group to inactive, set this value to false
group_description__v	[Optional] Add a description of the group.

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 your wish to update.

Name	Description
label__v	Updates the label of the group.
members__v	Add a comma-separated list of user IDs. This manually assigns individual users to the group.
security_profiles__v	Add a comma-separated list of security profiles.
active__v	To set the group to inactive, set this value to false.
group_description__v	Updates the description of the group.

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 1024 options (values). The API supports retrieving picklists and picklist values, creating and deleting picklist values, and updating picklist value labels and names. The API does not support creating, updating, or deleting the picklists themselves; this must be done in the Admin UI.

Learn about Picklists in Vault Help.

Retrieve All Picklists

Request

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

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "errorCodes": null,
  "picklists": [
    {
      "name": "agency_name1__c",
      "label": "Agency Name",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__c",
          "propertyName": "otherAgencies_pm"
        }
      ]
    },
    {
      "name": "agency_name__c",
      "label": "Agency Name",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__c",
          "propertyName": "creativeAgency_pm"
        }
      ]
    },
    {
      "name": "application_type__c",
      "label": "Application Type",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "compliance_package__v",
          "propertyName": "applicationType_pm"
        }
      ]
    },
    {
      "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"
        }
      ]
    },
    {
      "name": "material_type__c",
      "label": "Material Type",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__c",
          "propertyName": "materialType_pm"
        }
      ]
    },
    {
      "name": "media_type__c",
      "label": "Media Type",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__c",
          "propertyName": "mediaType_pm"
        }
      ]
    },
    {
      "name": "method_of_delivery__c",
      "label": "Method of Delivery",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__c",
          "propertyName": "methodOfDelivery"
        }
      ]
    },
    {
      "name": "mlr_type__c",
      "label": "MLR Type",
      "kind": "global",
      "usedIn": [
        {
          "documentTypeName": "promotional_piece__c",
          "propertyName": "mlrType_pm"
        }
      ]
    },
    {
      "name": "product_family__c",
      "label": "Product Family",
      "kind": "global",
      "usedIn": [
        {
          "objectName": "product__v",
          "propertyName": "product_family__c"
        }
      ]
    },
    {
      "name": "therapeutic_area__c",
      "label": "Therapeutic Area",
      "kind": "global",
      "usedIn": [
        {
          "objectName": "product__v",
          "propertyName": "therapeutic_area__c"
        }
      ]
    },
    {
      "name": "license_type__v",
      "label": "License Type",
      "kind": "user",
      "system": true
    },
  ],
  "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

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

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 Admin > Business Admin > Picklists > {Picklist}.

Update Picklist Value Name

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 (only). To change a picklist value label, see the previous section above.

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}/{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.)

Request Details

To change an existing picklist value name, use name set to a new value. The picklist value label will remain unchanged. For example, to change the picklist value name north_america__c, enter "name=north_america_united_states". Values may only contain a-z, 0-9, and single consecutive underscores; cannot start or end with an underscore; cannot contain spaces (use underscores). Do not append the name with __v, __c, or __c. Vault will add __c after processing.

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 Admin > Business Admin > Picklists > {Picklist}.

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

Remove a value from a picklist.

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.

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

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 represent the stages a document transitions through as users create, review, approve and eventually archive or replace it. A set of business rules applies to each state and defines what happens to the document in that state. Admins define these rules for each lifecycle state and Vault automatically applies them to every document that enters the state.

Business Rules: Each state has the following configuration options:

• User Actions: Actions that end users can perform on a document.
• Security Settings: Permissions that users in each role have for a document.
• Entry Criteria: Conditions that a document must meet before transitioning into this state.
• Entry Actions: Actions that Vault performs automatically when a document enters this state.

Learn about Lifecycles & Workflows in Vault Help.

Document & Binder User Actions

The API supports initiation of the following user action types:

• Workflow
• State Change
• Controlled Copy
• Create Presentation

Your Vault may include other user action types, all of which cannot be initiated through the Vault API.

Entry Criteria

Before users can initiate a user action, the document or binder must satisfy certain entry criteria. Entry requirements are dynamic and depend on the lifecycle configuration, entry criteria defined for the lifecycle state, and/or the workflow activation requirements defined in the Start Step of the workflow.

Property Scope

The API specifies the scope for the each requirement:

• Document scope means that the property is document-level and must be updated on the document before initiating the user action.
• Binder scope means that the property is binder-level and must be updated on the binder before initiating the user action.
• Workflow scope means that the property is workflow-level and must be specified at the time of action initiation.
• Controlled Copy scope means that the property is controlled copy specific and must be specified at the time of action initiation.

Typical Implementation

In a typical implementation, the client requests the available user actions using the Get User Actions endpoint. The response to this call lists user actions that the current user can initiate on a document or a binder specified by its ID and version.

Overview of Steps

Step 1: Retrieve User Actions

• Retrieve a list of available user actions on a specific version of a document or binder.
• The response includes the name of each user action used to initiate the action and the endpoint to retrieve the entry criteria.

Step 2: Retrieve Entry Criteria

• Before initiating a user action, you need to ensure that the document or binder meets certain conditions (required fields are populated, etc.).
• For example, you don’t need to assign a user to the “Approver” role when the document is first uploaded, but you do need to when initiating the “Start Approval” workflow.
• Not all user actions have entry criteria. In these cases, you can simply proceed with initiation of the user action.
• When the entry criteria "scope": "WorkflowActivation", the values can be specified as name-value pairs with the lifecycle initiation request.
• When the entry criteria "scope": "Document" or "scope": "Binder" the values must first be updated on the document or binder before initiating the request.

Step 3: Initiate User Action

• Once you’ve determined the entry criteria and completed those which must be configured separately, you can initiate the user action.
• Vault will evaluate whether all the entry criteria have been met and, if so, will initiate the user action on the specified version of the document or binder.

Retrieve User Actions

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "lifecycle_actions__v": [
    {
      "name__v": "startApproval",
      "label__v": "Start Approval",
      "lifecycle_action_type__v": "workflow",
      "entry_requirements__v": "https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval/entry_requirements"
    },
    {
      "name__v": "approve",
      "label__v": "Approve",
      "lifecycle_action_type__v": "stateChange",
      "entry_requirements__v": "https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions/approve/entry_requirements"
    }
  ]
}

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

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__v - The user action name (consumed by the API). These vary from Vault to Vault and may be text, numeric, or alphanumeric values.
• label__v - The user action label.
• lifecycle_action_type__v - The workflow and stateChange types are the most commonly used and are available in all Vaults. Others may exist.
• entry_requirements__v - The endpoint to retrieve the entry criteria for each user action. If no entry criteria exist, this will be excluded from the response.

Note that user actions are not returned for documents or binders which are currently in an active workflow.

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://vpharm-rim.vaultdev.com/api/v13.0/objects/documents/lifecycle_actions

Response

{
    "responseStatus": "SUCCESS",
    "responseMessage": "Success",
    "lifecycle_actions__v": [
        {
            "name__v": "make_obsolete__vs",
            "label__v": "Make Obsolete",
            "lifecycle_action_type__v": "stateChange",
            "lifecycle__v": "general_lifecycle__c",
            "state__v": "approved__c",
            "entry_requirements__v": "https://vpharm-rim.vaultdev.com/api/v13.0/objects/documents/lifecycle_actions/make_obsolete__vs/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://vpharm-rim.vaultdev.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
docIds	Include a comma-separated list of document or binder IDs, major and minor version numbers.The document or binder docIds field values from which to retrieve the available user actions.

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__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 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, this will be excluded from the response.

Note that lifecycle actions are not returned for documents or binders which are currently in an active workflow.

Retrieve Entry Criteria

Request

In this request, we’ll retrieve the entry criteria for the “Start Approval” workflow.

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "properties": [
    {
      "name": "dueDate",
      "description": "Approval Due Date",
      "type": [
        "Date"
      ],
      "required": true,
      "editable": true,
      "scope": "WorkflowActivation"
    },
    {
      "name": "Approver",
      "description": "Approver",
      "type": [
        "ObjectReference"
      ],
      "objectTypeReferenced": {
        "name": "User",
        "label": "User"
      },
      "required": true,
      "editable": true,
      "repeating": true,
      "scope": "WorkflowActivation"
    }
  ]
}

Request

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

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "properties": [
    {
      "name": "country__v",
      "description": "Country",
      "type": [
        "ObjectReference"
      ],
      "objectTypeReferenced": {
        "name": "country__v",
        "label": "Country",
        "url": "/api/v15.0/metadata/vobjects/country__v",
        "label_plural": "Countries"
      },
      "editable": true,
      "repeating": true,
      "scope": "Document",
      "records": "/api/v15.0/vobjects/country__v"
    }
  ]
}

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. This is retrieved from the Retrieve User Action request above.

Response Details

The response above shows two entry criteria to start the approval workflow on this document: dueDate and Approver.

• You must assign an Approval Due Date and users/groups to the Approver role on the document when initiating the user action.
• Unlike the response from the next example, the Scope for these fields is set to WorkflowActivation ("scope": "WorkflowActivation").
• This scope means that you can initiate the user action by including these entry criteria as name-value pairs with the request.

See the Initiate User Action section below for more information.

Response Details

The response above shows one entry criteria to change the state of this document from “Draft” to “Approved”: country__v.

• You must assign a value to the Country document field before initiating the user action.
• Unlike the response from the previous example, the Scope for this field is set to Document ("scope": "Document").
• This scope means that you must first update this field on the document before initiating the user action.

See the Initiate User Action section below for more information.

The response may include the following metadata elements describing the properties for which values need to be specified:

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 reference. For example: User, Product, Country, etc.
required	Boolean value indicating whether or not the entry criteria must be specified when initiating a user action.
editable	Boolean value indicating whether or not the value can be edited by the user.
repeating	Boolean value indicating whether or not the entry criteria can have multiple values.
minValue	Indicates the minimum character length for the value.
maxValue	Indicates the maximum character length for the value.
values	When type is Picklist, this provides a list of possible values that can be used.
currentSetting	When a value has already been set, this shows the value.
scope	Indicates where the property is defined. This value can be one of Document, Binder, WorkflowActivation, EmailFragment, ControlledCopy, or CreatePresentation.

Initiate User Action

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "dueDate=2015-12-25" \
-d "Approver=user:12021,user:12022,group:10030003" \
https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval

Response

{
  "responseStatus": "SUCCESS",
  "id": 222,
  "workflow_id__v": "115"
}

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v15.0/objects/documents/222/versions/0/1/lifecycle_actions/approve

Response

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

Once you’ve identified the entry criteria, you can initiate the user action.

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 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. This is retrieved from the Retrieve User Action request above.

Request Details

This request is initiating a workflow activation user action on the document. We’re initiating the “Start Approval” workflow.

• Recall from the discussion in the previous section that the two entry criteria are to assign a values to the dueDate and Approver fields.
• The entry criteria Scope is set to WorkflowActivation ("scope": "WorkflowActivation"), meaning the values can be included as a name-value pairs with the request.
• Format the dueDate value as shown above. To assign users and/or groups to the Approver role, include a comma-separated list of user and group id field values.

On submitting this request, Vault will evaluate whether all the entry criteria have been met and, if so, initiate the user action.

Response Details

On SUCCESS, Vault returns the document id field value of the document on which the user action has been initiated and the workflow workflow_id__v field value of the workflow. This document ("id": 222) is now in the “Start Approval” workflow ("workflow_id__v": "115"). On FAILURE, Vault returns an error type and message describing the reason for the error. The user action will not be initiated until all errors have been corrected.

Request Details

This request is initiating a state change user action on the document. We’re changing the state from “Draft” to “Approved”.

• Recall from the discussion in the previous section that the only entry criteria is to assign a value to the document’s country__v field.
• The entry criteria Scope is set to Document ("scope": "Document"), meaning the country field value cannot be included as a name-value pair with the request.
• Instead, before submitting this request, we used a separate Update Document request to update the country field on the document. This fulfilled the entry criteria.
• Therefore, we do not need to specify the input format (there is no input requirement) and the request can be submitted as shown in this example.

Response Details

On SUCCESS, Vault returns the document id field value of the document on which the user action has been initiated. This document ("id": 222) was previously version 0.1 (Draft State). It is now version 1.0 (Approved/Steady State). On FAILURE, Vault returns an error type and message describing the reason for the error. The user action will not be initiated until all errors have been corrected.

Bulk Document State Change

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
docIds	Include a comma-separated list of document or binder IDs, major and minor version numbers, as shown below.
lifecycle	Include the name of the document or binder lifecycle.
state	Include the current state of your document.

In this request:

• The input file format is set to accept name-value pairs.
• The documents and versions are specified. We’re changing the state of version 0.1 of document IDs 222, 223, 224, and 225.
• The lifecycle is specified. These documents are assigned to the general_lifecycle__c.
• The state is specified. We’re changing the state of all four documents from draft to approved.

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

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.

Create 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__v	The name__v field values of the lifecycle and role to which the override rule is being added.
name__v	The name__v field values of the allowed and default groups who will be assigned to the role when the override condition is met.
id	The id or name__v field values of the object records which define the override condition.
user_name__v	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 configure the default rules.
• The input may include override rules for multiple lifecycles and roles.
• Each role may be configured with multiple override rules.

Example CSV & JSON Input Files

Create an override rule on the editor__c role of the general_lifecycle__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 Override Rules

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

Request Details

For each override rule specified in the input, the response includes a SUCCESS or FAILURE message.

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

Retrieve Document Workflow Metadata

Request

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

Response (abridged)

{
  "responseStatus": "SUCCESS",
  "properties": [
    {
      "name": "workflow_document_id__v",
      "type": "id",
      "multivalue": false
    },
    {
      "name": "workflow_initiator_name__v",
      "type": "String",
      "length": 255,
      "multivalue": false
    },
    {
      "name": "workflow_process_version__v",
      "type": "Number",
      "multivalue": false
    },
    {
      "name": "workflow_id__v",
      "type": "id",
      "multivalue": false
    },
    {
      "name": "workflow_name__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Approval"
        },
        {
          "label": "Distribute"
        },
        {
          "label": "MLR Approval"
        },
        {
          "label": "MLR Review"
        },
      ]
    },
    {
      "name": "workflow_initiator__v",
      "type": "ObjectReference",
      "object": "User",
      "multivalue": false
    },
    {
      "name": "workflow_status__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Active"
        },
        {
          "label": "Cancelled"
        },
        {
          "label": "Complete"
        },
        {
          "label": "Error"
        }
      ]
    },
    {
      "name": "workflow_startDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "workflow_completionDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "workflow_cancelationDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "workflow_duration__v",
      "type": "Number",
      "multivalue": false
    },
    {
      "name": "workflow_dueDate__v",
      "type": "Date",
      "multivalue": false
    },
    {
      "name": "workflow_type__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Read and Understood"
        },
        {
          "label": "Standard"
        }
      ]
    },
    {
      "name": "workflow_document_major_version_number__v",
      "type": "Number",
      "multivalue": false
    },
    {
      "name": "workflow_document_minor_version_number__v",
      "type": "Number",
      "multivalue": false
    },
    {
      "name": "workflow_process_instance_group__v",
      "type": "String",
      "length": 255,
      "multivalue": false
    },
    {
      "name": "task_assignee_name__v",
      "type": "String",
      "length": 255,
      "multivalue": false
    },
    {
      "name": "task_id__v",
      "type": "id",
      "multivalue": false
    },
    {
      "name": "task_name__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Approve"
        },
        {
          "label": "Assess Outcome"
        },
        {
          "label": "Legal Approval"
        },
        {
          "label": "Medical Approval"
        },
        {
          "label": "Regulatory Approval"
        },
        {
          "label": "Legal Review"
        },
        {
          "label": "Medical Review"
        },
        {
          "label": "Regulatory Review"
        },
      ]
    },
    {
      "name": "task_assignee__v",
      "type": "ObjectReference",
      "object": "User",
      "multivalue": false
    },
    {
      "name": "task_delegate__v",
      "type": "ObjectReference",
      "object": "User",
      "multivalue": false
    },
    {
      "name": "task_queueGroup__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Approver"
        },
        {
          "label": "Coordinator"
        },
        {
          "label": "Reviewer"
        },
      ]
    },
    {
      "name": "task_status__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Created"
        },
        {
          "label": "Available"
        },
        {
          "label": "Cancelled"
        },
        {
          "label": "Assigned"
        },
        {
          "label": "Completed"
        }
      ]
    },
    {
      "name": "task_verdict__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false,
      "values": [
        {
          "label": "Approved"
        },
        {
          "label": "Not Approved"
        },
        {
          "label": "Approved for Production"
        },
        {
          "label": "Approved with Changes"
        },
      ]
    },
    {
      "name": "task_capacity__v",
      "type": "Picklist",
      "length": 255,
      "multivalue": false
    },
    {
      "name": "task_creationDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "task_assignmentDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "task_completionDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "task_cancelationDate__v",
      "type": "DateTime",
      "multivalue": false
    },
    {
      "name": "task_duration__v",
      "type": "Number",
      "multivalue": false
    },
    {
      "name": "task_dueDate__v",
      "type": "Date",
      "multivalue": false
    },
    {
      "name": "task_comment__v",
      "type": "String",
      "length": 4000,
      "multivalue": false
    }
  ]
}

GET /api/{version}/metadata/objects/workflows

Headers

Name	Description
Accept	application/json (default)

Object Lifecycle & Workflows

Object lifecycles are the sequences of states (Draft, In Review, etc.) an object record 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 records to another state). 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 an object record in each 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/17.3/vobjects/product__v/0PR0771/actions

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "links": [
                {
                    "rel": "metadata",
                    "accept": "application/json",
                    "href": "/api/v17.3/vobjects/alsobject_lfc__c/0PR0771/actions/Objectlifecyclestateuseraction.product__v.change_state_to_inactive_useraction__c",
                    "method": "GET"
                },
                {
                    "rel": "execute",
                    "accept": "application/json",
                    "href": "/api/v17.3/vobjects/alsobject_lfc__c/0PR0771/actions/Objectlifecyclestateuseraction.product__v.change_state_to_inactive_useraction__c",
                    "method": "POST"
                }
            ],
            "label": "Change State to Inactive",
            "type": "state_change",
            "name": "Objectlifecyclestateuseraction.product_v.change_state_to_inactive_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/v17.3/vobjects/product__v/00P000000000301/actions/Objectlifecyclestateuseraction.product__v.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.action.

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
storyEventKey	Optional: The ID of the target Story Event object record when executing the Apply Milestone Template action. This is only applicable in Clinical Operations Vaults.

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	Either the name of the Objectaction or Objectlifecyclestateuseraction to initiate. This is obtained from the Retrieve User Actions request.

Body Parameters

Name	Description
ids	Comma separated list of object record ids on which to initiate the action.

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, and changing a record’s status. Workflow tasks can allow users to enter comments, choose verdicts (approve, deny, etc.), update required fields, or provide eSignatures.

Object workflows a 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 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": 1,
    "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": 701,
      "label__v": "Review",
      "status__v": [
        "active__v"
      ],
      "object__v": "product__v",
      "record_id__v": "00P07551",
      "initiator__v": 52212,
      "started_date__v": "2016-04-28T15:07:52.000Z",
      "due_date__v": "2016-05-12T10:00:00.000Z",
      "completed_date__v": "2016-05-10T14:01:17.000Z"
    },
    {
      "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 all workflows for a specific object and object record or from a specific 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.
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 object 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 object 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 object 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

Retrieve all available workflow actions that can be initiated on a specific object workflow.

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/objectworkflows/801/actions

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "name": "startApproval",
      "label": "Start Approval"
    },
    {
      "name": "cancel",
      "label": "Cancel"
    }
  ]
}

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 that can be initiated on the object record. 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.

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

Workflow Tasks

Retrieve Object Workflow Tasks

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/objectworkflows/tasks?object__v=product__v&record_id__v=00P07551

Response

{
  "responseStatus": "SUCCESS",
  "responseDetails": {
    "total": 1,
    "offset": 0,
    "page_size": 200,
    "object": {
      "name": "objectworkflow_tasks",
      "label": "Object Workflow Task",
      "url": "/api/v15.0/objects/objectworkflows/tasks?object__v=product__v&record_id__v=00P07551",
      "label_plural": "Object Workflow Tasks"
    }
  },
  "data": [
    {
      "id": 5885,
      "label__v": "Review",
      "status__v": [
        "assigned__v"
      ],
      "object__v": "product__v",
      "record_id__v": "00P07551",
      "instructions__v": "Review and provide feedback.",
      "assignee__v": "25524",
      "created_date__v": "2016-05-04T17:25:17.000Z",
      "assigned_date__v": "2016-05-04T17:25:17.000Z",
      "due_date__v": "2016-05-12T10:00:00.000Z",
      "workflow__v": "801"
    },
    {
      "id": 7201,
      "label__v": "Approve",
      "status__v": [
        "available__v"
      ],
      "object__v": "product__v",
      "record_id__v": "00P07551",
      "instructions__v": "Approve or reject.",
      "created_date__v": "2016-05-04T17:25:17.000Z",
      "workflow__v": "801"
    }
  ]
}

Retrieve available tasks across all single-object 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 object 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.

Retrieve Workflow Task Details

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v14.0/objects/objectworkflows/tasks/7201

Response

{
  "responseStatus": "SUCCESS",
  "responseDetails": {
    "total": 1,
    "offset": 0,
    "page_size": 200,
    "object": {
      "name": "objectworkflow_tasks",
      "label": "Object Workflow Task",
      "url": "/api/v15.0/objects/objectworkflows/tasks?object__v=product__v&record_id__v=00P07551",
      "label_plural": "Object Workflow Tasks"
    }
  },
  "data": [
    {
      "id": 7201,
      "label__v": "Approve",
      "status__v": [
        "available__v"
      ],
      "object__v": "product__v",
      "record_id__v": "00P07551",
      "instructions__v": "Approve or reject.",
      "created_date__v": "2016-05-04T17:25:17.000Z",
      "workflow__v": "801"
    }
  ]
}

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

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 object 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/v14.0/objects/objectworkflows/tasks/801/actions/complete

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "name":"user_task__v",
            "label":"Approver Verdict(s)",
            "type": "task",
            "description": "Approver must select a verdict.",
            "controls": [
                {
                    "label": "Instructions",
                    "type": "instructions",
                    "instructions": "Specify a verdict giving your views.",
                    "prompts": []
                },
                {
                    "label": "Date",
                    "type": "date",
                    "prompts": [
                        {
                            "name": "due_date__c",
                            "label": "Due Date"
                        }
                    ]
                },
                {
                    "label": "Fields",
                    "type": "field",
                    "prompts": [
                        {
                            "name": "product__v.generic_name__c",
                            "label": "Generic Name",
                            "required": true,
                            "multi_value": false,
                            "current_value":
                            [
                               "00P07551"
                            ]
                        },
                        {
                            "name": "product__v.internal_name__c",
                            "label": "Internal Name",
                            "required": false,
                            "multi_value": false,
                            "current_value":
                            [
                               "00P07551"
                            ]
                        },
                        {
                            "name": "product__v.compound_id__c",
                            "label": "Compound Id",
                            "required": false,
                            "multi_value": false,
                            "current_value":
                            [
                               "00P07551"
                            ]
                        }
                    ]
                },
                {
                    "label": "Verdict",
                    "type": "verdict",
                    "verdict": "verdict_field__c",
                    "reason": "reason_field__c",
                    "prompts": [],
                    "verdicts": [
                        {
                            "name": "approve__c",
                            "label": "Approve",
                            "prompts": [],
                            "reasons":[]
                        },
                        {
                            "name": "approved_with_changes__c",
                            "label": "Approved with Changes",
                            "prompts": [
                                {
                                    "name": "product__v.generic_name__c",
                                    "label": "Generic Name",
                                    "type": "field",
                                    "required": true,
                                    "multi_value": false,
                                    "current_value":
                                    [
                                    "00P07551"
                                    ]
                                },
                                {
                                    "name": "product__v.internal_name__c",
                                    "label": "Internal Name",
                                    "type": "field",
                                    "required": false,
                                    "multi_value": false,
                                    "current_value":
                                    [
                                    "00P07551"
                                    ]
                                },
                                {
                                    "name": "product__v.compound_id__c",
                                    "label": "Compound Id",
                                    "type": "field",
                                    "required": false,
                                    "multi_value": false,
                                    "current_value":
                                    [
                                    "00P07551"
                                    ]
                                }
                            ],
                            "reasons": [
                                {
                                    "name": "safety__c",
                                    "label": "Safety",
                                    "required": true
                                },
                                {
                                    "name": "reg_affairs__c",
                                    "label": "Regulatory Affairs",
                                    "required": true
                                },
                                {
                                    "name": "procurement__c",
                                    "label": "Procurement",
                                    "required": true
                                }
                            ]
                        },
                        {
                            "name": "reject__c",
                            "label": "Reject",
                            "reasons": [
                                {
                                    "name": "safety__c",
                                    "label": "Safety",
                                    "required": true
                                },
                                {
                                    "name": "reg_affairs__c",
                                    "label": "Regulatory Affairs",
                                    "required": true
                                },
                                {
                                    "name": "procurement__c",
                                    "label": "Procurement",
                                    "required": true
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Retrieve the details of a specific object workflow task action. The response lists the details of the task action, including all fields required to initiate the action.

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/xml" \
-d "verdict__v=reject__c" \
-d "reason__v=reg_affairs__c" \
https://myvault.veevavault.com/api/v14.0/objects/objectworkflows/tasks/7201/actions/complete

Response

{
    "responseStatus": "SUCCESS"
}

Initiate an object workflow task action on a specific object record. On SUCCESS, the specified object workflow task action is initiated on the object record.

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

The cancel action doesn’t require any parameters.

Expected Document Lists

Expected Document Lists (EDLs) help you to measure the completeness of projects. Learn about EDLs in Vault Help. Note that if your Vault is configured to set milestone values by EDL item, the following EDL endpoints may trigger updates to a document’s milestone fields. Learn about milestones in Vault Help.

Create EDLs

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. Note that this API is for Clinical Operations only.

Learn more about Clinical Operations in Vault Help.

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.

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. Note that this API is for Clinical Operations only.

Learn more about Clinical Operations in Vault Help.

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.

Retrieve 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 EDL hierarchies in Vault Help.

GET /api/{version}/composites/trees/edl_hierarchy__v

Headers

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

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 EDL hierarchies in Vault Help.

GET /api/{version}/composites/trees/edl_hierarchy__v/{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
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 it’s children.

PUT /api/{version}/composites/trees/edl_hierarchy__v/{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
parent_node_id	The ID of a parent node in the hierarchy.

Body Parameters

Expressed as a JSON or a CSV.

Name	Description
id	The ID of the child node to update.
order__v	The new order for the node in the hierarchy, such as “1”, “2”, etc.

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

Configuration Migration

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/v16.0/services/package

POST /api/{version}/services/package

Headers

Name	Description
Content-Type	application/x-www-form-urlencoded

Body Parameters

Name	Description
packageName	The name of the Outbound Package you would like to export.

Response Details

The response body is the binary .vpk file.

Import Package

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-F "file=my_package.vpk" \
https://myvault.veevavault.com/api/v16.0/services/package

Response

{
 "responseStatus": "SUCCESS",
  "responseMessage": "Package with name [PKG-0001] already exists, it is renamed to [PKG-0001-2].",
  "vaultPackage": {
    "id": "0PI000000000703",
    "name": "PKG-0001-2",
    "status": "Active",
    "components": [
      {
        "id": "0VP000000000705",
        "name": "User Role Setup",
        "status": "Verified",
        "step": "00010",
        "stepId": "0IS000000000405",
        "componentName": "user_role_setup__v",
        "componentType": "Object"
      }
    ],
    "renamed": true,
    "oldName": "PKG-0001"
  }
}

PUT /api/{version}/services/package

Headers

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

Body Parameters

Name	Description
file	The .vpk file. See Export Package above.

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 deploy. See Import Package 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.

Retrieve Package Deploy Results

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v16.0/vobject/vault_package__v/0PI000000000101/actions/deploy/results

Response

{
 "responseStatus": "SUCCESS",
 "responseDetails": {
   "warnings": 0,
   "total_components": 8,
   "deployed_components": 8,
   "skipped_components": 0,
   "error_components": 0,
   "deployment_status__v": "deployed__v",
   "deployment_log": [
     {
       "filename": "PKG-0005-7101.log",
       "url": "https://my4.vaultdev.com:8443/api/v17.2/vobjects/vault_package__v/0PI000000000101/attachments/2/versions/1/file",
       "created_date__v": "2017-05-19 18:21:34.057"
     }
   ]
 },
 "package_components": [
   {
     "external_id__v": null,
     "component_type__v": "Doctype",
     "checksum__v": "bc7cf7551023d926e9920bc6afa0e598",
    "stepId": "0IS000000000101",
     "name__v": "Doctype.design_and_configuration__c",
     "step": "00010",
     "id": "0VP000000000101",
     "component_name__v": "design_and_configuration__c",
     "deployment_status__v": "deployed__v"
   }
 ]
}

After Vault has finished processing the deploy job, use this request to retrieve the results of the completed deploy.

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 deploy. See Deploy Package above.

Response Details

Learn more about the possible response values for deployment_status__v in Vault Help.

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_id	The target Vault id for the the comparison.
results_type	Optional: 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_type	Optional: 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.
component_types	Optional: Add a comma separated list of component types to include. For example, Doclifecycle,Doctype,Workflow. If omitted, this defaults to include all components.

Response Details

On SUCCESS, Vault returns the job_id of the comparison job. You can then Retrieve the Job Status. Once complete, you will receive an email with a download link to an Excel file of the comparison.

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_inactive_components	Optional: 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_since	Optional: Only include components modified since the specified date. Provide the date in the format yyyy-mm-dd. If omitted, includes all components.
suppress_empty_results	Optional: If set to true, Vault excludes tabs with only header rows from the report.

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 url from the job status response, download your report. The download is a ZIP file. Your Vault user will also receive a notification with a download link.

Logs

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 within the last 30 days

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.

GET /api/{version}/audittrail/{audit_trail_type}

Headers

Name	Description
Accept	application/json (default)

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

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. Each audit type includes the following fields:

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 sometimes shows “System” to indicate the action was complete by Vault.
full_name	The full name of the user who performed the action.

Note that Vault returns additional fields based on the specified audit type. 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.

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.

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

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 and daily limits, and the endpoint called. Users with the Admin > Logs > API Usage Logs permission can access these logs.

Note that the daily API Usage logs may have a delay of about 10 minutes. If your log does not include appropriate data, know that your data is not lost, it is just not yet populated.

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, and this parameter will change the format of the file contained within the ZIP.

Response Details

On SUCCESS, Vault retrieves the API Usage 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.
api_response_error_type	The API response error type, for example, INSUFFICIENT_ACCESS.
transaction_id	The request transaction ID, which includes the Vault ID.
client_id	The client ID passed with this request. If the API request did not include a client ID, this value will be unknown. If the API received a client_id which was incorrectly formatted, this value will be 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.
daily_limit_remaining	The number of API calls remaining in your daily 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.

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

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:

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, QUEUING, 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.
created_by	The id field value of the user who started the job.
created_date	The date and time when the job was requested.
run_start_date	The date and time when the export job started.
run_end_date	The date and time when the export job finished.

Errors

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

Error Types

Type	Description
UNEXPECTED_ERROR	General error catch-all when there is no specific error, or an unidentified error.
MALFORMED_URL	The specified resource cannot be found.
METHOD_NOT_SUPPORTED	The specified resource does not support the (POST, PUT, GET, DELETE) method. Or, the API request is not supported by this version of API.
INACTIVE_USER	User is inactive or not found.
NO_PASSWORD_PROVIDED	No password was provided for the login call.
USERNAME_OR_PASSWORD_INCORRECT	Authentication failed because an invalid username or password was provided.
USER_LOCKED_OUT	The user is locked out.
PASSWORD_CHANGE_REQUIRED	Password change required.
INVALID_SESSION_ID	Invalid session id provided.
PARAMETER_REQUIRED	Missing required parameters in the API call.
INVALID_DATA	Invalid data provided in the API call.
INSUFFICIENT_ACCESS	User does not have sufficient privileges to perform the action.
OPERATION_NOT_ALLOWED	Certain rules that must be met to perform this operation have not been met.
ATTRIBUTE_NOT_SUPPORTED	The specified resource does not recognize provided attributes.
INVALID_FILTER	Provided a non-existent filter to Retrieve Documents.
INCORRECT_QUERY_SYNTAX_ERROR	Query string used with 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	Vault limits the number of API calls that can be made every 5 minutes and every 24 hours. Additionally, the Job Status endpoint can only be requested once every 10 seconds. When either of these limits are reached, this error message is returned and no further calls will be processed until the next 5 minute or 24 hour period begins. Learn more about API Limits.
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. To inquire about Vault Java SDK Solutions, contact Veeva Services.