TOC Navbar

REST API

Getting Started

This tutorial talks about how to set up a Vault user account that has API access and walks through the basics of uploading a document to Vault.

Authentication

To make API calls against Vault, you need a Vault user account with API access. Once you have this, you can authenticate to get a session ID.

Vault User Account & Permissions

Your security profile and permission set may grant the following permissions:

Insufficient Access

If you do not have API access, your authentication request will succeed, but any other API calls you make will return the following error:

INSUFFICIENT_ACCESS: User [ID] not licensed for permission [VaultActions_API_Access].

If you do not have API access, contact your Vault administrator to adjust your security profile and permission set.

Structuring the Endpoint

As we talk about API calls, you’ll see the following variables in every endpoint. You’ll need to replace these with the correct values.

Versioning

The only version of the Vault REST API subject to change is the newest version, labelled as Beta. The newest version of the API which is not subject to change is the General Availability version, labelled as GA. All older versions of the API (all versions besides Beta) do not change, which ensures your integration will continue to work. However, this means many new APIs and API features are not backwards compatible, and you will need to use a newer version of the API to access new functionality. To view the new APIs, features, and fixed issues for each API version, you can check the Release Notes.

Naming

Veeva Vault releases three new API versions each year, coinciding with Vault General Releases. As of 2017, REST API versions follow the pattern YY.1, YY.2, YY.3 where YY is the last two digits of the current year. For example, the first Vault General Release of 2017 is 17R1. The API version which coincides with this release is API v17.1. The third Vault General Release of 2018 is 18R3, which coincides with REST API v18.3.

Prior to 2017, Vault versions and API versions do not coincide with the current year. For example, REST API v12.0 includes features from Vault 11.5.2, 11.5.3, and 12.0.0, all of which released in 2015. Each General Release is made up of multiple limited releases. For example, Vault release 18R1 includes all features released in 17R3.2, 17R3.3, 17R3.4, and 17R3.5. The REST API versioning does not have limited release numbering. Instead, the latest version (in this example, v18.1) is labelled as Beta and all limited release features are added to the Beta API. For example, REST API v18.1 contains all features released in 17R3.2, 17R3.3, 17R3.4, and 17R3.5.

Get a Session ID

Your first API call will be an authentication request, which provides your session ID for other API calls. To do this, call the auth endpoint.

The auth endpoint (/api/{version}/auth) expects two URL-encoded form parameters (x-www-form-urlencoded): username and password.

Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d 'username={username}&password={password}' \
"https://{server}/api/{version}/auth"

This call returns a JSON response that contains the session ID.

Response

{
  "responseStatus": "SUCCESS",
  "sessionId": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 1776,
      "name": "PromoMats",
      "url": "https://promo-vee.veevavault.com/api"
    },
    {
      "id": 1782,
      "name": "Platform",
      "url": "https://platform-vee.veevavault.com/api"
    }
  ],
  "vaultId": 1776
}

Note: The vaultIds collection in the response is a list of available vaults. The vaultId field under this list tells you which vault you’ve authenticated against. Rarely, you can authenticate against the wrong vault if the intended vault is inactive. In this situation, you’ll authenticate against the last vault you accessed or the oldest vault in your domain. Check the vaultId against the information in the list to ensure that it’s the vault you intended.

Upload a Document

Now that you have a session ID, you can upload a document to your vault using the Documents API. In this example, you will create an unclassified document.

Assign the session ID to the header parameter Authorization. Specify the source file in the file body parameter. Since you will upload the document as unclassified assign the values Undefined and Unclassified to the body parameters type__v and lifecycle__v respectively.

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F file=@document.txt \
-F "name__v=myDocument" \
-F "type__v=Undefined" \
-F "lifecycle__v=Unclassified" \
https://{server}/api/{version}/objects/documents

If your request contains all the required metadata and your session ID is valid, the response includes a unique document ID. Note, the file document.txt resides in the directory from which the curl command is being executed.

Response

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

Note: On some application vaults you may have to set other parameters aside from type__v and lifecycle__v to successfully upload an unclassified document. If this is the case the API call will throw an exception and prompt you for the required fields.

Next Steps

Congratulations! You’ve successfully created your first document using Vault’s APIs. Once you’re ready, you can move on to the next tutorial where you’ll learn about object fields.

Understanding Metadata of Object Fields

This tutorial covers how document and object fields work and how to use them when making API calls. We’ll also take a close look at some example fields and explain the semantics of their metadata attributes.

Vault Objects

In Vault, an “object” is a kind of data entity, which also has a set of fields. Individual “object records” are instances of that data entity type with values assigned to the various fields. If you think of an object as a database table, each field is a column and each object record is a table row.

Learn more about vault objects.

Object Fields

When creating an object record, there are some fields that you must specify and others that Vault itself populates. For example, you must specify a value for the Name field (name__v), but Vault itself generates a value for the id field. There are also fields that are editable and not required: you can create documents or object records without populating these.

Fields like id are known as “system-managed” fields and are often hidden in the UI. The id field is particularly important when using the API because you’ll use it to identify documents, object records, and other resources.

Note these APIs will return blank values, but not null values. For example, when retrieving users, you may notice the last login field: "last_login__v": "2015-02-02T16:52:21.000Z". However, if a user never logged in, this field would be null and would not show up in the response at all. Fields with blank values, for example "office_phone__v": "", do appear in the response, showing the user has entered nothing for their office phone number.

When creating documents or object records through the API, the same field requirements and validation rules apply as when working through the UI.

Configuration Differences & Field Naming

Many fields defined on documents and objects for a given vault are unique to that vault’s configuration, meaning that the set of fields can be different between vaults. Some standard fields like name__v and id are common across all vaults. API requests use the field names, not labels. For example, the standard Product document field would be product__v.

The suffix on a field name indicates whether it’s standard or custom:

API Rate Limits

API rate limits are a common way to guarantee a high quality service by preventing servers from becoming overloaded and the web service itself from becoming unusable. Web services are a fundamental resource to any developer application or integration. We enforce rate limits to ensure that each application or integration gets its fair share of this resource. Learn more about API rate limits in Vault Help.

What Are Rate Limits?

Rate limits constrain the number of API calls a user can make during a given time period. Once you reach your API quota, the server will reject your subsequent API requests until the next window.

How Does Vault Calculate Limits?

Vault enforces two types of rate limits:

For example, a vault might allow 500 API requests within a 5-minute window. Between 4:00 and 4:03, your vault has received 500 requests. On request 501 at 4:04, the server rejects your request. The server will continue to reject requests until the next window begins at 4:05.

When you exceed these limits, the server throws an API_LIMIT_EXCEEDED error. It is important to be able to handle this error, even if you’ve followed the API rate limit best practices discussed below. Note that the Job Status endpoint will return this error if requested more than once in 10 seconds, which does not mean you've exceeded your burst or daily limits.

API Rate Limit Headers

As of v14.0, Vault APIs return rate limiting headers to help you monitor how many API calls you have remaining as well as possible response throttling.

As of v19.2, Vault APIs return two additional rate limit headers in every response showing the total limits allowed for your vault.

API calls to auth never return rate limit headers, but these calls still count towards your burst and daily limits.

Note that the Job Status endpoint will return the API_LIMIT_EXCEEDED error if requested more than once in 10 seconds, and these headers are not relevant when this happens.

Developing with Rate Limits

Here are some best practices for reducing the number of API requests:

  1. Avoid unnecessary auth calls. A session ID stays alive as long as it is active. A session ID with a timeout of 20 minutes only expires if it has not been used within the past 20 minutes.

  2. Cache configuration data. Configuration data does not change often. Retrieve it once and store it locally in a database like SQLite or serialized in a file.

  3. Optimize your code to eliminate unnecessary API requests. Are you retrieving data that isn’t being used in your application? Are you updating data that hasn’t changed? Eliminate these calls.

  4. Regulate the API request rate. If you are frequently approaching or reaching the API rate limit, consider implementing a throttling process in your application to distribute your requests more uniformly over time. For example, observe the above mentioned response headers and monitor your request rate. Throttle requests when your rate reaches a certain threshold.

  5. Use the batch/bulk APIs. You can drastically reduce your API request count if you take advantage of the many batch/bulk APIs available. For example, a single API request can create 500 object records using the Batch Object Create API. Find opportunities to replace single API calls with their batch counterparts. Note: Batch APIs are not currently available on all resources.

Client ID

For additional tracking purposes, every Vault REST API call will accept an optional client ID to represent an external integration client. You can provide this data via a query parameter called client_id or HTTP Header called X-VaultAPI-ClientID. If client ID is included as both a HTTP Header and query parameter, the query parameter is ignored.

The Vault API will record the client ID value for each API call. This ID appears in the API Usage Logs, which is downloadable through the UI and API. If an API request does not include a client ID, the value will appear as unknown in the API Usage Log. The API Usage Log is only available in v18.1+, but client ID can be included in requests for all versions of the API.

Format

A valid client ID must be an alphanumeric string with a maximum of 100 characters. A client ID can be mixed-case and the only special characters allowed are underscores _ and hyphens -. If an API request includes an invalid client ID, the value will appear as invalid_client_id in the API Usage Log.

To avoid clashing with other integrations or client applications running on Vault, we recommend that you format your client ID as follows:

{company}-{organization}-{component/team}-{server | client}-{program}

For example, the Vault Loader team client ID could be:

veeva-vault-tools-server-loader

Cross-Origin Requests

Cross-Origin Resource Sharing (CORS) and JSONP are currently unsupported. If you want to integrate your web application directly with the Vault API, you must route API requests through your own backend and not directly from the browser via AJAX.