TOC Navbar
shell

Getting Started

Run in Postman™

Starting with v21.1, Vault provides a Postman™ collection for each GA release of the Veeva Vault REST API. Note that this collection represents the point in time when the API became GA, and will not receive additional updates. For the most up-to-date documentation, developers should reference the REST API reference.

Install Postman™, then click the button below to import the CDMS API collection.

To use this collection effectively, set the following environment variables:

Understanding the Structure of Vault CDMS

At the highest level, Vault CDMS is organized by Study. Within each Study, there are multiple Sites, grouped by Study Country. Sites contain the Subjects involved with a Study at that Site. Each Subject has a Casebook, which contains all collected data about that Subject in Events (visits) and Forms.

Site users enter collected data into Forms (eCRFs) in a subject's casebook. Each Form has several Items. An Item is the question or field for an individual data point. These Items are grouped into Item Groups.

Depending on your study design, Casebooks may allow for cycles, or repeating Event Groups. Repeating Event Groups allow you to add an Event Group to a Casebook multiple times. Each time you add that Event Group, it contains the same collection of Events and Forms as the previous. Each new Event Group may have a customized label, and often incremented labels, such as Visit 1, Visit 2, Visit 3, etc. You can use the Create Event Group API to add a new instance of a repeating Event Group.

In addition to cycles, CDMS also allows for repeating Forms and Item Groups. These allow for the collection of a data set multiple times within the context of a single Event or Form. Common forms are a special type of repeating Form that aren't associated with a specific event, such as an Adverse Events or Concomitant Medications form.

API Access

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

To access the CDMS API, your Study Role must grant the API Access permission. Then, you must have the appropriate permissions for the action you want to perform via the API. For example, for the Set Item Value endpoint, you must have the View Casebook and Data Entry permissions, in addition to API Access. In the REST API Reference, each endpoint lists which permissions are required.

The CDMS API Read Write role must have All Sites access in your Study.

To be able to use all CDMS APIs, you must have the following permissions:

Permission Controls
API Access Ability to access and use the Vault CDMS API
View Casebook Ability to view information about and from subject Casebooks
Add Casebook Ability to create new Casebooks
Data Entry Ability to enter study data into Casebooks, including entering Event Dates, setting Item values, and submitting Forms
View Code Ability to view coding progress on Code Requests and related records
Open Query Ability to open (create new) queries or reopen a closed query
Answer Query Ability to answer (comment on or respond to) queries
Close Query Ability to close queries
Manage Users Ability to create and edit user accounts and assign users their Study Roles.

See Managing User Access in Vault CDMS Help for detailed instructions on account creation and role assignment.

Read vs Write Access

For read-only access to the CDMS API, only the API Access, View Casebook, and View Code permissions are required. To retrieve Users, the Manage Users permission is also required. These permissions allow you to use all GET APIs to retrieve and view information from CDMS.

To have both read and write access, additional permissions are required. For example, to have write access on Casebooks, the Add Casebook and Data Entry permissions are required, in addition to the API Access and View Casebook 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 were 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

Request

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

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
}

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

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

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 multiple types of rate limits:

For example, a vault might allow 2,000 API requests within a 5-minute window. Between 4:00 and 4:03, your vault has received 2,000 requests. On request 2,001 at 4:04, the server slows down all requests until the next window begins at 4:05.

As of v21.1, Vault no longer enforces daily API limits, includes the daily_limit_remaining in API usage logs, or sends notifications to users when API transaction limits are partially reached or exceeded.

API Rate Limit Headers

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 v21.1, Vault APIs no longer return the X-VaultAPI-DailyLimit or X-VaultAPI-DailyLimitRemaining headers. To ensure backwards compatibility, Vault APIs v20.3 and below still return the headers with a value of 999,999. Vault does not deduct from this value with each request.

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.

Authentication API Rate Limit Headers

As of v20.1, calls to /api/{version}/auth return two rate limit headers in every response showing you the total limits allowed for your vault and how many /api/{version}/auth calls you have remaining. These calls also count towards your burst and daily limits.

Developing with Rate Limits

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

  1. Avoid unnecessary auth calls. A session ID with a timeout of 20 minutes only expires if it is not used within 20 minutes after the last request finishes executing.

  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 bulk/batch APIs. You can drastically reduce your API request count if you take advantage of the many bulk APIs available. For example, a single API request can create 500 object records using the Create Multiple Object Records API. Find opportunities to replace single API calls with their bulk counterparts. Note that bulk 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 calledX-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

Recommended Client ID Format

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

Example: Vault Loader Team Client ID

veeva-vault-tools-server-loader

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 you use our recommended Client ID format.

Errors

The response of every API call includes a field called responseStatus. Possible values are:

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.

We recommend basing your logic on the responseStatus field and error types, not on the HTTP response status codes.

Standard Error Types

Example: Failed Authentication

{
    "responseStatus" : "FAILURE",
    "errors" : [
        {
            "type" : "NO_PASSWORD_PROVIDED",
            "message" : "No password was provided for the login call."
        }
    ],
    "errorType" : "AUTHENTICATION_FAILED"
}

Example: Down for Maintenance

{
    "responseStatus": "FAILURE",
    "responseMessage": "Authentication failed for user [chunter@verteopharma.com]",
    "errors": [
        {
            "type": "DOWN_FOR_MAINTENANCE",
            "message": "Vault is currently down for maintenance"
        }
    ],
    "errorType": "AUTHENTICATION_FAILED"
}
Type Description
UNEXPECTED_ERROR General error catch-all when there is no specific error, or an unidentified error.
MALFORMED_URL The specified resource cannot be found.
METHOD_NOT_SUPPORTED The specified resource does not support the (POST, PUT, GET, DELETE) method. Or, the API request is not supported by this version of API.
INACTIVE_USER User is inactive or not found.
NO_PASSWORD_PROVIDED No password was provided for the login call.
USERNAME_OR_PASSWORD_INCORRECT Authentication failed because an invalid username or password was provided.
USER_LOCKED_OUT The user is locked out. Learn more about user account lockout in Vault Help.
PASSWORD_CHANGE_REQUIRED Password change required.
INVALID_SESSION_ID Invalid session ID provided.
DOWN_FOR_MAINTENANCE The vault is currently down for maintenance.
PARAMETER_REQUIRED Missing required parameters in the API call.
INVALID_DATA Invalid data provided in the API call.
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. Additionally, the /actions endpoints may return this error in cases where the user attempts to access a resource which does not exist.
OPERATION_NOT_ALLOWED Certain rules that must be met to perform this operation have not been met.
ATTRIBUTE_NOT_SUPPORTED The specified resource does not recognize provided attributes.
INVALID_FILTER Provided a non-existent filter to Retrieve Documents.
INCORRECT_QUERY_SYNTAX_ERROR Query string used with VQL has an incorrect query syntax.
RACE_CONDITION A rare condition where the same record is being simultaneously updated by another API call.
EXCEEDS_FILE_MAX_SIZE The size of uploaded file exceeds the maximum size allowed (4 GB).
API_LIMIT_EXCEEDED 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.

Vault CDMS Errors

Example: Incorrect study_name for Create Casebook

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Study] with name [Cholecap_DEV2] not found",
            "site": "101"
        }
    ]
}

Example: Using Set Event Date on a Frozen Subject

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "FAILURE",
            "errorMessage": "Subject is frozen",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0001",
            "eventgroup_name": "enrollment",
            "eventgroup_sequence": 1,
            "event_name": "enrollment_visit",
            "event_sequence": 1
        }
    ]
}

These errors are specific to Vault CDMS:

Error Description
[Event Definition] with [event_name] not found Vault couldn't find an Event Definition with the Name provided in event_name.
[Event Group Definition] with [eventgroup_name] not found Vault couldn't find an Event Group Definition with the Name provided in eventgroup_name.
[Form Definition] with name [form_name] not found Vault couldn't find a Form Definition with the Name provided in form_name.
[id] with name [id] not found Vault couldn't find a Query with the ID provided in id.
[Item Group Definition] with name [itemgroup_name] not found Vault couldn't find an Item Group Definition with the Name provided in itemgroup_name.
[Item Definition] with name [item_name] not found Vault couldn't find an Item Definition with the Name provided in item_name.
[Study] with name [study_name] not found Vault couldn't find a Study with the Name provided in study_name.
[Study Country] with name [study_country] not found Vault couldn't find a Study Country with the Name provided in study_country.
[Study Site] with name [site] not found Vault couldn't find a Site with the Site Number (site__v.name__v) provided in site.
[Subject] with name [subject] not found Vault couldn't find a Subject with the Name (Subject ID) provided in subject.
[Subject] with name [subject] exists A Subject with the Name (Subject ID) provided in subject already exists.
Casebook is frozen The Casebook is frozen, and so the action isn't allowed.
Casebook is locked The Casebook is locked, and so the action isn't allowed.
Change reason is required You didn't provide a value for change_reason, which is required for this API.
Change reason too long The change_reason you provided exceeds the maximum character limit.
Country [country] does not exist The country you provided is invalid.
Date passed was empty or invalid format. Must use YYY-MM-DD. You passed an invalid parameter for the date, meaning that it was empty, not ISO format, or otherwise invalid.
Duplicate A user with this user_name already exists.
Email needs to be of valid format The email you provided isn't in a valid format.
Event Date is frozen The Event Date is frozen because either the Subject or Event is frozen, and so this action is not allowed.
Event Date is locked The Event Date is locked because either the Subject or Event is locked, and so this action is not allowed.
Form is already submitted The Form is already in the Submitted status, and you can't submit a Form that is already submitted, marked as intentionally left blank, or signed.
Form is frozen The Form is frozen, and so this action is not allowed.
Form is locked The Form is locked, and so this action is not allowed.
Form is not submitted The Form is not in the Submitted status, and so you can't use the Edit Submitted Form API to move it to the In Progress status.
Item is locked The Item is locked, and so this action is not allowed.
Item value is not in correct format for setting the item The value you provided isn't in the correct format for the Item.
Items on submitted forms cannot be edited The Item is on a Form that is in the Submitted status, and so you can't edit the Item. Use the Edit Submitted Form API to return the Form to the In Progress status.
Language [language] does not exist The language you provided doesn't exist in Vault or is otherwise invalid.
Last name must be no greater than 100 characters The last_name provided exceeds the maximum character limit of 100 characters.
Locale [locale] does not exist The locale you provided doesn't exist in Vault or is otherwise invalid.
Message is required The message parameter is required for this API.
Message is too long The message provided exceeds the maximum character limit.
No permission for this action You don't have the permissions required to use this API.
Query ID not found Vault couldn't find a Query with the id provided.
Query is already in the Closed status You can't answer or close a Query that is already in the Closed status.
Query is already in the Reopened status You can't reopen a Query that is already in the Reopened status.
Query not in Closed status You can't reopen a Query that isn't in the Closed status.
Read only or derived field update is not allowed You can't set the value for a read-only Item or an Item that is populated by a Set Item Value rule (derived).
Site is locked The Site is locked, and so this action is not allowed.
Study is locked The Study is locked, and so this action is not allowed.
Subject is locked The Subject is locked, and so this action is not allowed.
Unique event/item cannot be found with the specified keys` Vault couldn't find the Event Date or Item for a repeating Event Group, Form, or Item Group with the matching sequence_number.
Unique item cannot be found with the specified keys Vault couldn't find the Form for this Item.
Unique query cannot be found with the specified keys The Query is on an Event Date within a repeating Event Group or an Item on a repeating Form or Item Group, and Vault couldn't find the sequence with the matching sequence_number. Otherwise, Vault couldn't find the Query because the provided definitions were incorrect.

Tutorial: Create a Casebook & Submit Data

In this short tutorial, we will create a new Casebook in our example study, Cholecap, enter data on the Demographics form, and then submit the form.

This tutorial uses the following APIs:

Required Permissions

The following permissions are required to use the APIs in this tutorial:

Authenticate

Authentication Request

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

Authentication Response

{
  "responseStatus": "SUCCESS",
  "sessionId": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 2596,
      "name": "PromoMats",
      "url": "https://cdms.veevavault.com/api"
    }
  ]
}

Authenticate your account using your Vault user name and password to obtain Vault Session ID. If you're using Postman, add your sessionId as an environment variable.

POST /api/{version}/auth

Headers
Name Description
Content-Type multipart/form-data or application/x-www-form-urlencoded
Accept application/json (default) or application/xml
Body Parameters
Name Description
username Your Vault user name assigned by your administrator.
password Your Vault password associated with your assigned vault user name.
vaultDNS Optional The DNS of the vault for which you want to generate a session. If omitted, generates a session for the user’s default vault.

Create a Casebook

Create Casebook Request

curl -X POST  https://myvault.veevavault.com/api/v19.3/app/cdm/subjects \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "subjects": [
        {
            "site": "101",
            "study_country": "United States"
        }
    ]
}'

Create Casebook Response

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001"
        }
    ]
}

Now, you'll create a new Casebook. This also adds a Subject to your Study. The Casebook contains all of the visits and forms for the subject throughout the study.

POST /api/{version}/app/cdm/subjects

Headers
Name Description
Accept application/json (default)
Content-Type application/json
Body Parameters

This table includes the values used in the example requests and responses in this tutorial. These will be different for your Study.

Name Tutorial Value Description
study_name Cholecap The Study Number (Name) of the Study to contain the Casebook (study__v.name__v)
site 101 The Site Number (Name) of the Site you want to create the Casebook in (site__v.name__v)
study_country United States The Name of the Study Country you want to create the Casebook in (site__v.study_country__v)

Because we're creating a Casebook for a new Subject, we don't need to include the subject parameter.

Set Item Values

Set Item Values Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/items \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "event_name": "screening-visit",
            "form_name": "demographics",
            "items": [
                {
                    "itemgroup_name": "creation_criteria",
                    "item_name": "subject_initials",
                    "value": "DPN"
                },
                {
                    "itemgroup_name": "creation_criteria",
                    "item_name": "subject_date_of_birth",
                    "value": "1981-11-14"
                },
                {
                    "itemgroup_name": "creation_criteria",
                    "item_name": "subject_gender",
                    "value": "F"
                },
                {
                    "itemgroup_name": "creation_criteria",
                    "item_name": "subject_race",
                    "value": "CAUCASIAN"
                }
            ]
        }
    ]
}'

Set Item Values Response

{
    "responseStatus": "SUCCESS",
    "items": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening-visit",
            "event_sequence": 1,
            "form_name": "demographics",
            "form_sequence": 1,
            "itemgroup_name": "creation_criteria",
            "itemgroup_sequence": 1,
            "item_name": "subject_initials"
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening-visit",
            "event_sequence": 1,
            "form_name": "demographics",
            "form_sequence": 1,
            "itemgroup_name": "creation_criteria",
            "itemgroup_sequence": 1,
            "item_name": "subject_date_of_birth"
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening-visit",
            "event_sequence": 1,
            "form_name": "demographics",
            "form_sequence": 1,
            "itemgroup_name": "creation_criteria",
            "itemgroup_sequence": 1,
            "item_name": "subject_gender"
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening-visit",
            "event_sequence": 1,
            "form_name": "demographics",
            "form_sequence": 1,
            "itemgroup_name": "creation_criteria",
            "itemgroup_sequence": 1,
            "item_name": "subject_race"
        }
    ]
}

Now that we've created a Casebook, we will use the Set Item Values API to enter data for each Item on the Demographics form.

Headers
Name Description
Accept application/json (default)
Content-Type application/json
Body Parameters

This table includes the values used in the example requests and responses in this tutorial. These will be different for your Study.

Name Tutorial Values Description
study_name Cholecap The Study Number (Name) of the Study containing the Item (study__v.name__v)
site 101 The Site Number of the Site containing the Item (site__v.name__v)
study_country United States The Name of the Study Country containing the Item (site__v.study_country__v)
subject SCR-0001 The Subject ID of the Subject for the Casebook containing the Item (subject__v.name__v)
eventgroup_name screening The Name of the Event Group Definition containing the Item (event_group_def__v.name__v)
event_name screening-visit The Name of the Event Definition for the Item (event_def__v.name__v)
form_name demographics The Name of the Form Definition for the Item (form_def__v.name__v)
items See list below A JSON array with the information for each Item value to be set. The array must include the following sub-attributes for each Item:
  • itemgroup_name: The Name of the Item Group Definition for the Item Group containing the Item (item_group_def__v.name__v)
  • item_name: The Name of the Item's Item Definition (item_def__v.name__v)
  • value: Enter the value for this Item

For the items parameter, include a JSON array with the information for each of these Items on our Demographics form:

Initials Item:

DOB Item:

Gender Item:

Race Item:

Submit Form

Submit Form Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/forms/actions/submit \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "event_name": "screening-visit",
            "form_name": "demographics"
        }
    ]
}'

Submit Form Response

{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "event_name": "screening-visit",
            "form_name": "demographics"
        }
    ]
}

Now that we've set the item value for all Items on the Demographics form, we can submit the Form. This moves the Form into the Submitted status and sends it for SDV and DMR. This will also add other Event Groups into the casebook's schedule.

POST /api/{version}/app/cdm/forms/actions/submit

Headers
Name Description
Accept application/json (default)
Content-Type application/json
Body Parameters

This table includes the values used in the example requests and responses in this tutorial. These will be different for your Study.

Name Tutorial Value Description
study_name Cholecap The Study Number (Name) of the Study containing the Event (study__v.name__v)
site 101 The Site Number of the Site containing the Event (site__v.name__v)
study_country United States The Name of the Study Country containing the Event (site__v.study_country__v)
subject SCR-0001 The Subject ID of the Subject for the Casebook containing the Event (subject__v.name__v)
eventgroup_name screening The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
event_name screening-visit The Name of the Event Definition for the Event (event_def__v.name__v)
form_name demographics The Name of the Form Definition for the Form (form_def__v.name__v)

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. The period varies by vault.

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

Basic Authorization

Name Description
Authorization {sessionId}

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

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

Bearer Token Authorization

Name Description
Authorization Bearer {sessionId}

User Name & Password

Request

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

Response

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

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

POST /api/{version}/auth

Headers

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

Body Parameters

Name Description
username Your Vault user name assigned by your administrator.
password Your Vault password associated with your assigned vault user name.
vaultDNS The DNS of the vault for which you want to generate a session. If omitted, generates a session for the user’s default vault.

OAuth 2.0 / OpenID Connect

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": 1779,
      "name": "QualityDocs",
      "url": "https://qualitydocs-veevapharm.veevavault.com/api"
    }
  ],
  "vaultId": 1776
}

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

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

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

Headers

Name Description
Authorization Bearer {access_token}
Accept application/json (default)

URI Path Parameters

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

Body Parameters

Name Description
vaultDNS Optional The DNS of the vault for which you want to generate a session. If omitted, the session is generated for user’s default vault.
client_id Optional The ID of the client application at the Authorization server.

Authentication Type Discovery

Request

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

Response: Password User

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

Response: SSO User

{
    "responseStatus": "SUCCESS",
    "data": {
        "auth_type": "sso",
        "auth_profiles": [
            {
                "id": "_9ad0a091-cbd6-4z59-ab5a-d4f35789918c",
                "label": "VeePharm",
                "description": "",
                "vault_session_endpoint": "https://veepharm.com/auth/oauth/session/_9ad0a091-cbd6-4z59-ab5a-d4f35789918c",
                "use_adal": false,
                "as_client_id":"34524523452345234523452345098098234",
                "as_metadata": {
                    "issuer": "https://veevaintrospection.com/oauth2/asdf123",
                    "authorization_endpoint": "https://veevintrospection.com/oauth2/asdf123/v1/authorize",
                    "token_endpoint": "https://veevaintrospection.com/oauth2/asdf123/v1/token",
                    "registration_endpoint": "https://veevaintrospection.com/oauth2/v1/clients",
                    "jwks_uri": "https://veevaintrospection.com/oauth2/asdf123/v1/keys",
                    "response_types_supported": [
                        "code",
                        "token",
                        "code token"
                    ],
                    "response_modes_supported": [
                        "query"
                    ],
                    "introspection_endpoint": "https://veevatintrospection.com/oauth2/asdf1234/v1/introspect",
                    "introspection_endpoint_auth_methods_supported": [
                        "client_secret_basic",
                    ],
                    "revocation_endpoint": "https://veevaintrospection.com/oauth2/asdf123/v1/revoke",
                    "revocation_endpoint_auth_methods_supported": [
                        "client_secret_basic",
                    ],
                    "end_session_endpoint": "https://veevaintrospection.com/oauth2/asdf123/v1/logout"
                }
            }
        ]
    }
}

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

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

Headers

Name Description
Accept application/json (default)

Query String Parameters

Name Description
username The user’s Vault user name.
client_id Optional The user's mapped Authorization Server client_id. This only applies the SSO auth_type.

Response Details

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

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

If the Authorization Server Provider is set to use ADFS, the use_adal field will appear in the response as true. If the Authorization Server Provider is set to anything else, this field is false.

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

Studies

Vault CDMS uses the Study object (study__v) to group together all study-related data in vault.

Retrieve Studies

Request

$ curl -X GET \
-H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
https://myvault.veevavault.com/api/v19.3/app/cdm/studies

Response

{
    "responseStatus": "SUCCESS",
    "studies": [
        {
            "study_name": "CHOLECAP_DEV",
            "external_id": "S.CHOLECAP",
            "study_phase": "Phase I",
            "study_status": "Execution"
        },
        {
            "study_name": "CHOLECAP_PROD",
            "external_id": "S.CHOLECAP_PROD",
            "study_phase": "Phase I",
            "study_status": "Planning"
        },
        {
            "study_name": "DEETOZA_DEV1",
            "external_id": "DEETOZA_DEV1",
            "study_phase": "Phase I",
            "study_status": "Planning"
        },
        {
            "study_name": "WONDERDRUG_DEV1",
            "external_id": "WONDERDRUG_DEV1",
            "study_phase": "Phase I",
            "study_status": "Execution"
        },
        {
            "study_name": "CHOLECAP_UAT1",
            "external_id": "S.CHOLECAP",
            "study_phase": "Phase I",
            "study_status": "Planning"
        }
    ]
}

Retrieve a list of all Studies in your vault that you have permission to view.

The following rules govern study retrieval:

GET /api/{version}/app/cdm/studies

Required Permissions:

The following permissions are required to use the Retrieve Studies API:

Headers

Name Description
Accept application/json (default)

Response Details

On SUCCESS, Vault returns a list of Studies that you have permission to view.

Metadata Field Description
name The Name (Study Number) field value from the Study record (study__v.name__v)
external_id The External ID field value from the Study record (study__v.oid__v)
study_status The Study Status field value from the Study record (study__v.study_status__v)
study_phase The Study Phase field value from the Study record (study__v.study_phase__v)

Subjects

Vault EDC uses two objects to manage participants in a study: Subject and Casebook. A Subject record represents an individual subject participating in a Study. This is where Vault tracks the Status of a Subject. That subject’s Casebook object contains all other records, such as visits and form data, related to the Subject for that Study.

Set Subject Status

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v20.1/app/cdm/subjects/actions/setstatus' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "Cholecap",
    "subjects": [
            {
                "site": "0101",
                "study_country": "United States",
                "subject": "0101-0010",
                "subject_status": "randomized__v",
                "date": "2020-03-03"
            }
        ]
    }'

Response

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "site": "0101",
            "subject": "0101-0010",
            "subject_status": "randomized__v"
        }
    ]
}

Set the Subject Status for a Subject and record the status change date in the appropriate field. Note that you can only use Set Subject Status on one Subject per request.

POST /api/{version}/app/cdm/subjects/actions/setstatus

A Subject must move through the different statuses in a certain order:

Notes on using Set Subject Status:

You can undo any changes made with this API using Unset Subject Status.

Required Permissions

The following permissions are required to use the Set Subject Status API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Subject (study__v.name__v)
subjects The Subjects (subject__v) you want to change the status of. As an array, provide the following for each Subject:
  • site: The Site Number (site__v.name__v) of the subject's assigned site
  • study_country
  • study_country: The Study Country (site__v.study_country__v) of the assigned site
  • subject_status: The Subject Status you're moving the Subject into. You must use the API Name of the status. See the list below.
  • date: The date to associate with the status change This date is recorded in different fields on the Subject record, depending on the target status. See the list below Use the "yyyy-mm-dd" format. Vault processes this date as UTC.

Subject Statuses

Status API Name Status Change Date Field
Pre Screen pre_screen__v Vault doesn't record a date for the initial status.
In screening in_screening__v screened_date__v
Screen Failure screen_failure__v screen_failed_date__v
Enrolled enrolled__v enrolled_date__v
Randomized randomized__v randomized_date__v
End of Treatment end_of_treatment__v end_of_treatment_date__v
Withdrawn withdrawn__v withdrawn_date__v
Complete complete__v end_of_study_date__v

Unset Subject Status

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v20.1/app/cdm/subjects/actions/unsetstatus' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID' \
-d '{
    "study_name": "Cholecap",
    "subjects": [
            {
                "site": "0101",
                "study_country": "United States",
                "subject": "0101-0010",
                "subject_status": "enrolled__v"
            }
        ]
    }'

Response

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "site": "0101",
            "subject": "0101-0010",
            "set_subject_status": "in_screening__v"
        }
    ]
}

You can use Unset Subject Status to clear a Status from a Subject. This sets the chosen status's field to No and clears the status change date (see the list above for a list of statuses and their date fields). The Subject will remain in the highest possible status. If you use this endpoint to remove the subject's current status, Vault moves the Subject into the last held status.

POST /api/{version}/app/cdm/subjects/actions/unsetstatus

Note that you can only use Unset Subject Status on one Subject per request.

Required Permissions

The following permissions are required to use the Unset Subject Status API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Subject (study__v.name__v)
subjects The Subjects (subject__v) you want to change the status of. As an array, provide the following for each Subject:
  • site: The Site Number (site__v.name__v) of the subject's assigned site
  • study_country
  • study_country: The Study Country (site__v.study_country__v) of the assigned site
  • subject_status: The Status you want to clear from the Subject. The Subject will remain in the highest possible status. See the list above.

Casebooks

Vault stores all data collected for a Subject in a Casebook (eCRF). Note that the Subject ID is defined during study design and can change as the study progresses. Learn more about subject IDs in Vault CDMS Help.

Create Casebooks

Request

curl -X POST  https://myvault.veevavault.com/api/v19.3/app/cdm/subjects \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "subjects": [
        {
            "site": "101",
            "study_country": "United States"
        },
        {
            "site": "102",
            "study_country": "United States"
        }
    ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0004"
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "102",
            "subject": "SCR-0001"
        }
    ]
}

Create a new subject Casebook. Creating a Casebook automatically creates a new Subject, as well as Events, Forms, and Items related to the Study. Learn more about Casebooks in Vault CDMS Help.

POST /api/{version}/app/cdm/subjects

Required Permissions

The following permissions are required to use the Create Casebooks API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study to contain the Casebook (study__v.name__v)
site The Site Number (Name) of the Site you want to create the Casebook in (site__v.name__v)
study_country The Name of the Study Country you want to create the Casebook in (site__v.study_country__v)
subject Optional The Subject ID (subject__v.name__v) of the Subject you want to create the Casebook for. If you don’t include a subject, Vault creates a subject for the casebook.

Event Groups

Vault EDC groups related Events (visits) together in Event Groups.

Create Event Groups

Request

curl -X POST https://myvault.veevavault.com/api/v20.1/app/cdm/eventgroups \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "Cholecap",
    "eventgroups": [
      {
        "site": "0101",
        "study_country": "United States",
        "subject": "0101-0001",
        "eventgroup_name": "unscheduled_treatment_visits",
        "date": "2020-03-03"
      }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
                {
                    "responseStatus": "SUCCESS",
                    "site": "0101",
                    "study_country": "United States",
                    "subject": "0101-0001",
                    "eventgroup_name": "unscheduled_treatment_visits"
                }
              ]
}

Create an Event Group. An Event Group is a container for multiple events, or visits, in a subject's casebook.

Depending on your study design, Casebooks may allow for cycles, or repeating Event Groups. Repeating Event Groups allow you to add an Event Group to a Casebook multiple times. The repeating Event Groups, or cycles, contain the same collection of Events and Forms for each sequence (repetition) of the Event Group. Each new Event Group may have a customized label, and often incremented labels, such as Visit 1, Visit 2, Visit 3, etc.

To create new Event Groups and update existing ones in a single request, use Upsert Event Groups.

POST /api/{version}/app/cdm/eventgroups

Required Permissions

The following permissions are required to use the Create Event Groups API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Casebook you're adding an Event Group to (study__v.name__v)
eventgroups For each Event Group that you want to create, provide the following as an array:
  • site: The Site Number (Name) of the Site containing the Casebook you're adding an Event Group to (site__v.name__v)
  • study_country: The Study Country of the Site specified in the site parameter (site__v.study_country__v)
  • subject: The Subject ID (Name) of the Subject whose Casebook you're adding an Event Group to (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition (event_group_def__v.name__v) for the Event Group that you want to create
  • date: (Optional) Enter a Date to associate with the Event Group. Use "yyyy-mm-dd" format. This is for use with unscheduled event groups. If omitted, Vault sets the date to the current date.

Upsert Event Groups

Request

curl -X PUT https://myvault.veevavault.com/api/v20.3/app/cdm/eventgroups \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "Cholecap",
    "eventgroups": [
      {
        "site": "0101",
        "study_country": "United States",
        "subject": "0101-0001",
        "eventgroup_name": "treatment_visits",
        "eventgroup_sequence": "3"
        "date": "2020-03-03"
      }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
      {
          "responseStatus": "SUCCESS",
          "site": "0101",
          "study_country": "United States",
          "subject": "0101-0001",
          "eventgroup_name": "treatment_visits",
          "eventgroup_sequence": "3"
      }
   ]
}

Create new Event Groups and update existing ones in a single request. Vault identifies Event Groups for updating by unique Subject and Event Group Sequence. If there is an existing Event Group for the specified Subject and Event Group Sequence, then Vault updates that Event Group. If there isn't a matching Event Group, Vault creates a new _Event Group.

PUT /api/{version}/app/cdm/eventgroups

Required Permissions

The following permissions are required to use the Upsert Event Groups API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Casebook you're adding an Event Group to (study__v.name__v)
eventgroups For each Event Group that you want to create or update, provide the following as an array:
  • site: The Site Number (Name) of the Site containing the Casebook you're adding an Event Group to (site__v.name__v)
  • study_country: The Study Country of the Site specified in the site parameter (site__v.study_country__v)
  • subject: The Subject ID (Name) of the Subject whose Casebook you're adding an Event Group to (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition (event_group_def__v.name__v) for the Event Group that you want to create
  • eventgroup_sequence: The Sequence Number of the Event Group that you want to create or update.
  • date: (Optional) Enter a Date to associate with the Event Group. Use "yyyy-mm-dd" format. This is for use with unscheduled event groups. If omitted, Vault sets the date to the current date.

Events

Vault EDC tracks visits in your study with the Event object. Each Event contains the Forms collected during that visit.

Retrieve Events

Request

curl -L -X GET 'https://myvault.veevavault.com/api/v20.2/app/cdm/events?study_name=Veepharm&study_country=United%20States&site=0101&subject=SCR-0001' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "study_country": "United States",
            "site": "0101",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening_visit",
            "event_sequence": 1,
            "event_date": "2020-06-15",
            "forms": [
                {
                    "form_name": "demographics",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "locked": false,
                    "frozen": false,
                    "intentionally_left_blank": false,
                    "intentionally_left_blank_reason": null
                },
                {
                    "form_name": "exclusion_criteria",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "locked": false,
                    "frozen": false,
                    "intentionally_left_blank": false,
                    "intentionally_left_blank_reason": null
                },
                {
                    "form_name": "inclusion_criteria",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "locked": false,
                    "frozen": false,
                    "intentionally_left_blank": false,
                    "intentionally_left_blank_reason": null
                }
            ]
        },
        {
            "study_country": "United States",
            "site": "0101",
            "subject": "SCR-0001",
            "eventgroup_name": "enrollment",
            "eventgroup_sequence": 1,
            "event_name": "enrollment_visit",
            "event_sequence": 1,
            "event_date": "2020-07-17",
            "forms": [
                {
                    "form_name": "randomization",
                    "form_sequence": 1,
                    "form_status": "blank__v",
                    "locked": false,
                    "frozen": false,
                    "intentionally_left_blank": false,
                    "intentionally_left_blank_reason": null
                }
            ]
        }
    ]
}

Retrieve a list of Events in a subject's Casebook. For each Event, Vault returns a list of Forms within it. You can restrict this to only retrieve Events in a certain Event Group.

Vault only returns details about Forms that you have permission to view. If the Event contains restricted (blinded) forms, and you do not have the Restricted Data Access permission, Vault will not return the restricted Form.

GET /api/{version}/app/cdm/events

Required Permissions

The following permissions are required to use the Retrieve Events API:

Headers

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

Query Parameters

Name Description
study_name The Name of the Study _(`studyv.name_v`) containing the subject's casebook.
site The Site Number (Name) of the Site (site__v.name__v) of the Site containing the subject's casebook.
study_country The Name of the Study Country (site__v.study_country__v) of the Study Country containing the subject's Site.
subject The Subject ID (Name) of the Subject (subject__v.name__v).
eventgroup_name Optional: The Name of the Event Group Definition (event_group_def__v.name__v) that you want to retrieve the events of. If omitted, Vault returns all Events within the Casebook. If you use event_name, this parameter is required.
eventgroup_sequence Optional: The Sequence Number of the Event Group (event_group__v.seq__v) that you want to retrieve the events of. If omitted, Vault returns Events for every instance of the Event Group, or, if eventgroup_name is also omitted, all Events within the Casebook.
event_name Optional: The Name of the Event Definition (event_def__v.name__v) for the Event that you want to retrieve metadata for. To filter by event_name, you must include eventgroup_name. If omitted, Vault returns all Events within the Event Group (if eventgroup_name) is provided, otherwise, Vault returns all Events in the Casebook.

Response Details

On SUCCESS, Vault returns a list of Events within a casebook with the following metadata:

Name Description
event_name The Name of the Event Definition for the Event
event_sequence The Sequence Number of the Event, for Events that are within a repeating Event Group. If the event group isn't repeating, this defaults to "1".
event_date The Event Date of the Event.
event_status The Status of the Event (frozen, locked, signed, etc.)
forms For each Form within the Event, Vault returns the following information:
  • form_name: Name of the Form Definition (form_def__v.name__v)
  • form_sequence: For repeating forms, the Sequence Number of the Form (form__v.form_seq__v)
  • locked: True/False, is the Form currently locked
  • frozen: True/False, is the Form currently frozen
  • intentionally_left_blank: True/False, is the Form marked as Intentionally Left Blank
  • intentionally_left_blank_reason: For intentionally left blank forms, the Reason selected.
Note that you can request information about specific forms using Retrieve Forms.

Create Events

Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/events \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Labrinone",
    "events": [
        {
            "site": "US101",
            "study_country": "United States",
            "subject": "SCR001",
            "eventgroup_name": "EG.RANDOMIZATION",
            "event_name": "Subject.Information"
        },
        {
            "site": "US101",
            "study_country": "United States",
            "subject": "SCR002",
            "eventgroup_name": "EG.SCREENING",
            "event_name": "Demographics"
        }
    ]
}

Response

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "SUCCESS",
            "site": "US101",
            "study_country": "United States",
            "subject": "SCR001",
            "eventgroup_name": "EG.RANDOMIZATION",
            "eventgroup_sequence": 1,
            "event_name": "Subject.Enrollment"
        },
        {
            "responseStatus": "SUCCESS",
            "site": "US101",
            "study_country": "United States",
            "subject": "SCR002",
            "eventgroup_name": "EG.SCREENING",
            "eventgroup_sequence": 1,
            "event_name": "Subject.ScreeningVisit"
        }
    ]
}

Create a new Event (visit). Creating an Event creates all of the Forms, Item Groups, and Items used for data collection within that visit.

POST /api/{version}/app/cdm/events

Required Permissions

The following permissions are required to use the Create Events API:

Headers

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

Body Parameters

After study_name, include all other parameters as an array within event for each Event that you want to create.

Name Description
study_name The Study Number (Name) of the Study to contain the Event (study__v.name__v)
site The Site Number (Name) of the Site to contain the Event (site__v.name__v)
study_country The Name of the Study Country containing the Site (site__v.study_country__v)
subject The Subject ID (Name) of the Subject for the Casebook to contain the Event (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition for the Event Group that contains the Event (event_group_def__v.name__v)
eventgroup_sequence Optional For repeating Event Groups (cycles), the Sequence of the Event Group containing the Event (event_group__v.seq__v). If omitted, the default value is 1.
event_name The Name of the Event Definition for the Event (event_def__v.name__v)

Set Event Date

Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/events/actions/setdate \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "S.CHOLECAP",
    "events": [
          {
          "site": "101",
          "study_country": "United States",
          "subject": "SCR-0002",
          "eventgroup_name": "Screening-Visit",
          "event_name": "Screening-Visit",
          "date": "2019-11-21"
          }
      ]
    }'

Response

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0002",
            "eventgroup_name": "Screening-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Screening-Visit",
            "event_sequence": 1
        }
    ]
}

Set the Event Date (Actual Date) for an Event.

POST /api/{version}/app/cdm/events/actions/setdate

Required Permissions

The following permissions are required to use the Set Event Date API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Event (study__v.name__v)
site The Site Number (Name) of the Site containing the Event (site__v.name__v)
study_country The Name of the Study Country containing the Event (site__v.study_country__v)
subject The Subject ID (Name) of the Subject for the Casebook containing the Event (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
eventgroup_sequence Optional For repeating Event Groups, the Sequence of the Event Group containing the Event (event_group__v.seq__v). If omitted, the default value is 1.
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
date Enter the Event Date, using "yyyy-mm-dd" format
change_reason Optional If an Event Date already exists for this event, enter a Reason for Change, for example, "Date updated by remote system"
allow_planneddate_override Optional Set this to true to set the Event Date to a date that falls outside of the event's planned date range. When true, Vault accepts the Event Date even if it falls outside of the planned date range. When false, Vault only accepts dates within range. If omitted, the default value is false.

Mark Event as Did Not Occur

Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/events/actions/didnotoccur \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Labrinone",
    "events": [
     {
         "site": "101",
            "study_country": "United States",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND",
            "change_reason": "missed appointment"
        },
        {
            "site": "101",
            "study_country": "United States",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND2",
            "change_reason": "missed appointment"
        },
        {
            "site": "101",
            "study_country": "United States",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND3",
            "change_reason": "missed appointment"
        }
    ]
}

Response

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "SUCCESS",
            "site": "101",
            "study_country": "United States",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND",
            "event_sequence": 1
        },
        {
            "responseStatus": "FAILURE",
            "error_message": "Event is already marked as did not occur",
            "site": "101",
            "study_country": "United States",
            "subject": "101001",
            "eventgroup_name": "EG.RAND2",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND"
        },
        {
            "responseStatus": "FAILURE",
            "error_message": "Unique event cannot be found with specified keys",
            "site": "101",
            "study_country": "United States",
            "subject": "101001",
            "eventgroup_name": "EG.RAND3",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND"
        }
    ]
}

Mark an Event as Did Not Occur. The Did Not Occur event status indicates that data was intentionally not collected for this visit, for example, if a subject missed the visit. Vault will not create any queries for missing data within this event. For Events within repeating Event Groups or Unscheduled Events, you can't set the mark the Event as Did Not Occur until the Event has been created from the Vault CDMS user interface. Learn more in Vault CDMS Help.

POST /api/{version}/app/cdm/events/actions/didnotoccur

Required Permissions

The following permissions are required to use the Mark Event as Did Not Occur API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Event (study__v.name__v)
site The Site Number (Name) of the Site containing the Event (site__v.name__v)
study_country The Name of the Study Country containing the Event (site__v.study_country__v)
subject The Subject ID (Name) of the Subject for the Casebook containing the Event (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
eventgroup_sequence Optional For repeating Event Groups, the Sequence of the Event Group containing the Event (event_group__v.seq__v). If omitted, the default value is 1.
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
change_reason If an Event Date already exists for this event, enter a Reason for Change, for example, "Date updated by remote system"

Forms

Vault CDMS uses forms (form__v) to represent case report forms. Forms contain groups of data collection Items (item__v). Learn more about forms in Vault CDMS Help.

Retrieve Forms

Request

curl -L -X GET 'https://myvault.veevavault.com/api/v20.2/app/cdm/forms?study_name=Cholecap&site=0101&study_country=United%20States&subject=0101-0001&eventgroup_name=screening&event_name=screening_visit' \
-H 'Authorization:{SESSION_ID}'

Response


{
    "responseStatus": "SUCCESS",
    "forms": [
        {
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening_visit",
            "event_externalid": "screening_visit",
            "event_sequence": 1,
            "form_name": "demographics",
            "form_sequence": 1,
            "form_status": "submitted__v",
            "locked": false,
            "frozen": false,
            "intentionally_left_blank": false,
            "intentionally_left_blank_reason": null,
            "itemgroups": [
                {
                    "itemgroup_name": "creation_criteria",
                    "itemgroup_externalid": "creation_criteria",
                    "itemgroup_sequence": 1,
                    "items": [
                        {
                            "item_name": "subject_date_of_birth",
                            "value": "17-Jun-1978",
                            "unit_value": null
                        },
                        {
                            "item_name": "subject_gender",
                            "value": "F",
                            "unit_value": null
                        },
                        {
                            "item_name": "subject_initials",
                            "value": "QGT",
                            "unit_value": null
                        },
                        {
                            "item_name": "subject_race",
                            "value": "Caucasian",
                            "unit_value": null
                        }
                    ]
                }
            ]
        },
        {
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening_visit",
            "event_sequence": 1,
            "event_externalid": "screening_visit",
            "form_name": "exclusion_criteria",
            "form_sequence": 1,
            "form_status": "submitted__v",
            "locked": false,
            "frozen": false,
            "intentionally_left_blank": false,
            "intentionally_left_blank_reason": null,
            "itemgroups": [
                {
                    "itemgroup_name": "exclusion_criteria",
                    "itemgroup_sequence": 1,
                    "itemgroup_externalid": "exclusion_criteria",
                    "items": [
                        {
                            "item_name": "exclusion_hypersensitivity_constituents",
                            "value": "N",
                            "unit_value": null
                        },
                        {
                            "item_name": "exclusion_study_calendar",
                            "value": "N",
                            "unit_value": null
                        },
                        {
                            "item_name": "exclusion_pregnant_or_nursing",
                            "value": "N",
                            "unit_value": null
                        },
                        {
                            "item_name": "exclusion_chronic_medical_condition",
                            "value": "N",
                            "unit_value": null
                        }
                    ]
                }
            ]
        },
        {
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening_visit",
            "event_sequence": 1,
            "event_externalid": "screening_visit",
            "form_name": "inclusion_criteria",
            "form_sequence": 1,
            "form_status": "submitted__v",
            "locked": false,
            "frozen": false,
            "intentionally_left_blank": false,
            "intentionally_left_blank_reason": null,
            "itemgroups": [
                {
                    "itemgroup_name": "inclusion_criteria",
                    "itemgroup_sequence": 1,
                    "itemgroup_externalid": "inclusion_criteria",
                    "items": [
                        {
                            "item_name": "inclusion_negative_pregnancy_test",
                            "value": "Y",
                            "unit_value": null
                        },
                        {
                            "item_name": "inclusion_normal_healthy",
                            "value": "Y",
                            "unit_value": null
                        },
                        {
                            "item_name": "inclusion_age_18",
                            "value": "Y",
                            "unit_value": null
                        },
                        {
                            "item_name": "inclusion_informed_consent",
                            "value": "Y",
                            "unit_value": null
                        }
                    ]
                }
            ]
        }
    ]
}

Retrieve a list of Forms in an Event. For each Form, Vault returns a list of Item Groups within it.

Vault only returns details about Forms that you have permission to view. If the Form is restricted (blinded) forms, and you do not have the Restricted Data Access permission, Vault will not return the restricted Form.

GET /api/{version}/app/cdm/forms

Required Permissions

The following permissions are required to use the Retrieve Forms API:

Headers

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

Query Parameters

Name Description
study_name The Name of the Study (study__v.name__v) containing the subject casebook
site The Site Number (name) of the Site (site__v.name__v) containing the subject casebook
study_country The Name of the Study Country (site__v.study_country__v) of the subject's site. If your country name includes a space ( ), escape it with %20.
subject The Subject ID (name) of the Subject (subject__v.name__v).
eventgroup_name The Name of the Event Group Definition (event_group_def__v.name__v) containing the Event you're retrieving_ Forms_ for.
eventgroup_sequence Optional For repeating Event Groups, the Sequence Number (event_group__v.seq__v). If omitted, and for non-repeating Event Groups, this defaults to "1".
event_name The Name of the Event Definition (event_def__v.name__v) for the Event you're retrieving Forms for.
form_name Optional To retrieve a single_ Form_ within an Event, provide the Name of the Form Definition (form_def__v.name__v) you want to retrieve. If omitted, Vault returns all Forms in the Event.
form_sequence Optional To retrieve a single instance of a repeating Form, provide the Sequence Number (form__v.seq__v). If omitted, and for non-repeating Forms, this defaults to "1".

Response Details

On SUCCESS, Vault returns a list of Forms within the Event with the following metadata:

Name Description
form_name The Name of the Form Definition (form_def__v.name__v)for the Form. This is the value you provide for the form_name body parameter of other form- and item-related endpoints.
form_sequence The Sequence Number of the Form (form__v.seq__v), for repeating forms. For non-repeating Forms, this defaults to "1".
form_status The Form Status for the Form (form__v.form_status__v), for example, submitted__v or in_progress__v
locked True/False, is the Form currently Locked (Review for Locked, form__v.rev_locked__v).
frozen True/False, is the Form currently Frozen (Review for Frozen, form__v.rev_frozen__v).
intentionally_left_blank True/False, is the Form marked as Intentionally Left Blank (form__v.intentionally_left_blank__v).
intentionally_left_blank_reason If intentionally_left_blank is true, the reason the form was left blank (form__v.intentionally_left_blank_reason__v)
item_groups The Item Groups within the Form. For each Item Group, Vault returns the Name of the Item Group Definition (item_group_def__v.name__v), the item group's Sequence Number (item_group__v.itemgroup_seq__v), and the External ID of the Item Group Definition (item_group_def__v.oid__v), along with the Items in the group. For each Item, Vault returns the Name of the Item Definition (item_def__v.name__v), Value of the item (item__v.value__v), and the Unit Value (item__v.unit_value__v).

Create Forms

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v20.1/cdm/forms' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "Cholecap",
    "forms": [
            {
                "site": "0101",
                "study_country": "United States",
                "subject": "0101-0001",
                "eventgroup_name": "baseline",
                "event_name": "baseline_visit",
                "form_name": "medical_history"
            }
        ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "forms": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0001",
            "eventgroup_name": "baseline",
            "eventgroup_sequence": 1,
            "event_name": "baseline_visit",
            "event_sequence": 1,
            "form_name": "medical_history",
            "form_sequence": 1
        }
    ]
}

Create a new instance of a repeating Form. Learn more about repeating forms in Vault CDMS Help. To create instances of Forms and specify the Sequence Number, use Upsert Forms.

POST /api/{version}/app/cdm/forms

Required Permissions

The following permissions are required to use the Create Forms API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Item (study__v.name__v)
forms A JSON array with the information for each Form to create. The array must include the following sub-attributes for each Form:
  • site: The Site Number of the Site containing the Form (site__v.name__v)
  • study_country: The Name of the Study Country containing the Form (site__v.study_country__v)
  • subject: The Subject ID (Name) of the Subject for the Casebook containing the Form (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition containing the Form (event_group_def__v.name__v)
  • eventgroup_sequence: (Optional) If your Form is within a repeating Event Group, enter the Sequence Number (event_group__v.event_group_seq__v) of the Event Group containing your Form. If omitted, the default is "1".
  • event_name: The Name of the Event Definition for the Event containing the Form (event_def__v.name__v)
  • form_name: The Name of the Form Definition for the Form (form_def__v.name__v)

Upsert Forms

Request

curl -L -X PUT 'https://myvault.veevavault.com/api/v20.3/cdm/forms' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "Cholecap",
    "forms": [
            {
                "site": "0101",
                "study_country": "United States",
                "subject": "0101-0001",
                "eventgroup_name": "baseline",
                "event_name": "baseline_visit",
                "form_name": "medical_history",
                "form_sequence": "3"
            }
        ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "forms": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0001",
            "eventgroup_name": "baseline",
            "eventgroup_sequence": 1,
            "event_name": "baseline_visit",
            "event_sequence": 1,
            "form_name": "medical_history",
            "form_sequence": 3
        }
    ]
}

Create a new instance of a repeating Form. Repeating forms are forms that you can use multiple times during a study. Common forms are repeating forms that span across study events, such as a Concomitant Medication or Adverse Event form. Common forms are associated to the casebook, rather than an event. These forms allow users to capture data for the same set of questions multiple times during a single event or study. Learn more about repeating forms in Vault CDMS Help.

PUT /api/{version}/app/cdm/forms

Required Permissions

The following permissions are required to use the Upsert Forms API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Item (study__v.name__v)
forms A JSON array with the information for each Form to create. The array must include the following sub-attributes for each Form:
  • site: The Site Number of the Site containing the Form (site__v.name__v)
  • study_country: The Name of the Study Country containing the Form (site__v.study_country__v)
  • subject: The Subject ID (Name) of the Subject for the Casebook containing the Form (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition containing the Form (event_group_def__v.name__v)
  • eventgroup_sequence: (Optional) If your Form is within a repeating Event Group, enter the Sequence Number (event_group__v.event_group_seq__v) of the Event Group containing your Form. If omitted, the default is "1".
  • event_name: The Name of the Event Definition for the Event containing the Form (event_def__v.name__v)
  • form_name: The Name of the Form Definition for the Form (form_def__v.name__v)
  • form_sequence: The Sequence Number of the Form (form__v.form_seq__v)

Create Item Group

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v20.1/cdm/itemgroups' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "Cholecap",
    "itemgroups": [
            {
                "site": "0101",
                "study_country": "United States",
                "subject": "0101-0001",
                "eventgroup_name": "baseline",
                "event_name": "baseline_visit",
                "form_name": "physical_exam",
                "itemgroup_name": "physical_exam"
            }
        ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "itemgroups": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0001",
            "eventgroup_name": "baseline",
            "eventgroup_sequence": 1,
            "event_name": "baseline_visit",
            "event_sequence": 1,
            "form_name": "physical_exam",
            "form_sequence": 1,
            "itemgroup_name": "physical_exam",
            "itemgroup_sequence": 7
        }
    ]
}

Create a new instance of a repeating Item Group. In addition to repeating forms, your study may also include repeating item groups, which allow you to answer the same set of questions multiple times on a given form. For example, your study may use a repeating item group for a physical exam. Repeating item groups can be used in both repeating and standard forms. Learn more about repeating item groups in Vault CDMS Help.

POST /api/{version}/app/cdm/itemgroups

Required Permissions

The following permissions are required to use the Create Item Groups API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Item (study__v.name__v)
itemgroups A JSON array with the information for each Item Group to create. The array must include the following sub-attributes for each Item Group:
  • site: The Site Number of the Site containing the Item Group (site__v.name__v)
  • study_country: The Name of the Study Country containing the Item Group (site__v.study_country__v)
  • subject: The Subject ID (Name) of the Subject for the Casebook containing the Item Group (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition containing the Item Group (event_group_def__v.name__v)
  • eventgroup_sequence: (Optional) If your Item Group is within a repeating Event Group, enter the Sequence Number (event_group__v.event_group_seq__v) of the Event Group containing your Item Group. If omitted, the default is "1".
  • event_name: The Name of the Event Definition for the Event containing the Item Group (event_def__v.name__v)
  • form_name: The Name of the Form Definition for the Item Group (item_group_def__v.name__v)
  • form_sequence: (Optional) If the Item Group is within a repeating Form, provide the Sequence Number of the Form (form__v.form_sequence__v) you want to add the Item Group to. If omitted, the default is "1".
  • itemgroup_name: The Name of the Item Group Definition (item_group_def__v.name__v) that you want to add.

Upsert Item Groups

curl -L -X PUT 'https://myvault.veevavault.com/api/v20.3/cdm/itemgroups' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
        "study_name": "Labrinone",
        "itemgroups": [
            {
                "site": "101",
                "study_country": "United States",
                "subject": "101001",
                "eventgroup_name": "EG.RAND",
                "eventgroup_sequence": 1,
                "event_name": "EV.RAND",
                "form_name": "F.VISIT2",
                "form_sequence": 1,
                "itemgroup_name": "IG.DSICDAT",
                "itemgroup_sequence": 1
            },
            {
                "site": "101",
                "study_country": "United States",
                "subject": "101001",
                "eventgroup_name": "EG.RAND",
                "eventgroup_sequence": 1,
                "event_name": "EV.RAND",
                "form_name": "F.VISIT2",
                "form_sequence": 1,
                "itemgroup_name": "IG.DSICTIM",
                "itemgroup_sequence": 3
            },
            {
                "site": "101",
                "study_country": "United States",
                "subject": "101001",
                "eventgroup_name": "EG.RAND",
                "eventgroup_sequence": 1,
                "event_name": "EV.RAND",
                "form_name": "F.VISIT2",
                "form_sequence": 1,
                "itemgroup_name": "IG.DSICALG",
                "itemgroup_sequence": 2
            }
        ]
    }

Response

{
    "responseStatus": "SUCCESS",
    "itemgroups": [
        {
            "responseStatus": "SUCCESS:UPDATED",
            "site": "101",
            "study_country": "United States",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND",
            "event_sequence": 1,
            "form_name": "F.VISIT2",
            "form_sequence": 1,
            "itemgroup_name": "IG.DSICDAT",
            "itemgroup_sequence": 1
        },
        {
            "responseStatus": "SUCCESS:CREATED",
            "site": "101",
            "study_country": "United States",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND",
            "event_sequence": 1,
            "form_name": "F.VISIT2",
            "form_sequence": 1,
            "itemgroup_name": "IG.DSICTIM",
            "itemgroup_sequence": 3
        },
        {
            "response": "SUCCESS:UPDATED",
            "site": "101",
            "study_country": "United States",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND",
            "event_sequence": 1,
            "form_name": "F.VISIT2",
            "form_sequence": 1,
            "itemgroup_name": "IG.DSICALG",
            "itemgroup_sequence": 2
        }
    ]
}

Upsert instances of a repeating Item Group. If you specify an itemgroup_sequence (Sequence Number for the Item Group instance) that doesn't exist, the API automatically creates the instance for you. For example, if you specify "3" for itemgroup_sequence, and "2" and "3" don't already exist, the API creates both of those instances for you.

For repeating item groups, if you specify an itemgroup_sequence that does not exist, the API will automatically create the instances for you. For example, if you specify itemgroup_sequence = 3, and itemgroup_sequence #2 and #3 do not exist already, the API will create those for you.

PUT /api/{version}/app/cdm/itemgroups

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Item (study__v.name__v)
itemgroups A JSON array with the information for each Item Group to create. The array must include the following sub-attributes for each Item Group:
  • site: The Site Number of the Site containing the Item Group (site__v.name__v)
  • study_country: The Name of the Study Country containing the Item Group (site__v.study_country__v)
  • subject: The Subject ID (Name) of the Subject for the Casebook containing the Item Group (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition containing the Item Group (event_group_def__v.name__v)
  • eventgroup_sequence: (Optional) If your Item Group is within a repeating Event Group, enter the Sequence Number (event_group__v.event_group_seq__v) of the Event Group containing your Item Group. If omitted, the default is "1".
  • event_name: The Name of the Event Definition for the Event containing the Item Group (event_def__v.name__v)
  • form_name: The Name of the Form Definition for the Item Group (item_group_def__v.name__v)
  • form_sequence: (Optional) If the Item Group is within a repeating Form, provide the Sequence Number of the Form (form__v.form_sequence__v) you want to add the Item Group to. If omitted, the default is "1".
  • itemgroup_name: The Name of the Item Group Definition (item_group_def__v.name__v) that you want to add.
  • itemgroup_sequence: The Sequence Number of the Item Group (itemgroup__v.itemgroup_seq__v or itemgroup2__v.itemgroup_seq__v for Data Model 2.0 studies).

Set Item Value

Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/items \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "0101-0001",
            "eventgroup_name": "Enrollment-Visit",
            "event_name": "Enrollment-Visit",
            "form_name": "Randomization",
            "items": [
                {
                    "itemgroup_name": "Randomization",
                    "item_name": "Randomization-number",
                    "value": "42957928309475"
                },
                {
                    "itemgroup_name": "Randomization",
                    "item_name": "Date-of-randomization",
                    "value": "2019-11-21"
                }
            ]
        }
    ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "items": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "0101-0001",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Randomization-number"
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "0101-0001",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization"
        }
    ]
}

Set the value for a data collection Item. Note that you can't use this API to set the value of derived Items.

POST /api/{version}/app/cdm/items

Required Permissions

The following permissions are required to use the Set Item Value API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Item (study__v.name__v)
site The Site Number of the Site containing the Item (site__v.name__v)
study_country The Name of the Study Country containing the Item (site__v.study_country__v)
subject The Subject ID of the Subject for the Casebook containing the Item (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Item (event_group_def__v.name__v)
eventgroup_sequence Optional: For repeating Event Groups, the sequence of the Event Group containing the Item (event_group__v.seq__v)
event_name The Name of the Event Definition for the Item (event_def__v.name__v)
form_name The Name of the Form Definition for the Item (form_def__v.name__v)
form_sequence Optional: For repeating Forms, the sequence of the Form (form__v.seq__v)
items A JSON array with the information for each Item value to be set. The array must include the following sub-attributes for each Item:
  • itemgroup_name: The Name of the Item Group Definition for the Item Group containing the Item (item_group_def__v.name__v)
  • itemgroup_sequence: Optional: For repeating Item Groups, the sequence of the Item Group (itemgroup__v.itemgroup_seq__v or itemgroup2__v.itemgroup_seq__v for Data Model 2.0 studies)
  • item_name: The Name of the Item's Item Definition (item_def__v.name__v)
  • value: Enter the value for this Item
  • unit_value: Optional: For unit-type Items, enter the name of the unit (item__v.unit_value__v)
  • change_reason: If the Item already had a value, enter a reason for change. This is not required if the Item doesn't yet have a value.

Upsert Items

Request

curl -X PUT https://myvault.veevavault.com/api/v20.3/app/cdm/items \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
          "study_name": "Labrinone",
          "forms": [
              {
                  "site": "101",
                  "study_country": "United States",
                  "subject": "101001",
                  "eventgroup_name": "EG.RAND",
                  "eventgroup_sequence": 1,
                  "event_name": "EV.RAND",
                  "form_name": "F.VISIT2",
                  "form_sequence": 1,
                  "items": [
                      {
                          "itemgroup_name": "IG.Screening",
                          "itemgroup_sequence": 1,
                          "item_name": "height",
                          "value": "160",
                          "unit_value": "cm",
                      },
                      {
                          "itemgroup_name": "IG.Screening",
                          "itemgroup_sequence": 1,
                          "item_name": "height",
                          "value": "160",
                          "unit_value": "cm",
                      },
                      {
                          "itemgroup_name": "IG.Screening",
                          "itemgroup_sequence": 1,
                          "item_name": "eligible",
                          "value": true
                      },
                      {
                          "itemgroup_name": "IG.Prescriptions",
                          "itemgroup_sequence": 1,
                          "item_name": "drugs_taken",
                          "value": "Advil, Restolar"
                      }
                  ]
              }
          ]
      }'

Response

{
    "responseStatus": "SUCCESS",
    "items": [
        {
            "responseStatus": "FAILURE",
            "errorMessage": "Item group sequence number must be greater than 0",
            "study_country": "United States",
            "site": "101",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND",
            "event_sequence": 1,
            "form_name": "F.VISIT2",
            "form_sequence": 1,
            "itemgroup_name": "IG.Screening",
            "itemgroup_sequence": 1,
            "item_name": "height"
        },
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND",
            "event_sequence": 1,
            "form_name": "F.VISIT2",
            "form_sequence": 1,
            "itemgroup_name": "IG.Screening",
            "itemgroup_sequence": 1,
            "item_name": "height"
        },
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND",
            "event_sequence": 1,
            "form_name": "F.VISIT2",
            "form_sequence": 1,
            "itemgroup_name": "IG.Screening",
            "item_name": "eligible"
        },
        {
            "responseStatus": "SUCCESS:CREATED",
            "study_country": "United States",
            "site": "101",
            "subject": "101001",
            "eventgroup_name": "EG.RAND",
            "eventgroup_sequence": 1,
            "event_name": "EV.RAND",
            "event_sequence": 1,
            "form_name": "F.VISIT2",
            "form_sequence": 1,
            "itemgroup_name": "IG.Prescriptions",
            "itemgroup_sequence": 1,
            "item_name": "drugs_taken"
        }
    ]
}

Upsert values for data collection Items. Note that you can't use this API to set the value of derived Items.

PUT /api/{version}/app/cdm/items

Required Permissions

The following permissions are required to use the Upsert Items API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Item (study__v.name__v)
site The Site Number of the Site containing the Item (site__v.name__v)
study_country The Name of the Study Country containing the Item (site__v.study_country__v)
subject The Subject ID of the Subject for the Casebook containing the Item (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Item (event_group_def__v.name__v)
eventgroup_sequence Optional: For repeating Event Groups, the sequence of the Event Group containing the Item (event_group__v.seq__v)
event_name The Name of the Event Definition for the Item (event_def__v.name__v)
form_name The Name of the Form Definition for the Item (form_def__v.name__v)
form_sequence Optional: For repeating Forms, the sequence of the Form (form__v.seq__v)
items A JSON array with the information for each Item value to be set. The array must include the following sub-attributes for each Item:
  • itemgroup_name: The Name of the Item Group Definition for the Item Group containing the Item (item_group_def__v.name__v)
  • itemgroup_sequence: For repeating Item Groups, the sequence of the Item Group ((itemgroup_v.itemgroup_seqv or itemgroup2v.itemgroup_seqv for Data Model 2.0 studies))
  • item_name: The Name of the Item's Item Definition (`item_defv.namev)</li><li>value: Enter the value for this Item</li><li>unit_value: Optional: For unit-type Items, enter the name of the unit (itemv.unit_valuev)</li><li>change_reason`: (Optional) If the _Item already had a value, enter a reason for change.

Submit Form

Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/forms/actions/submit \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "0101-0001",
            "eventgroup_name": "Enrollment-Visit",
            "event_name": "Enrollment-Visit",
            "form_name": "Randomization"
        }
    ]
}'

Response

{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "0101-0001",
            "eventgroup_name": "Enrollment-Visit",
            "event_name": "Enrollment-Visit",
            "form_name": "Randomization"
        }
    ]
}

Submit a Form.

POST /api/{version}/app/cdm/forms/actions/submit

Required Permissions

The following permissions are required to use the Submit Form API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Event (study__v.name__v)
site The Site Number of the Site containing the Event (site__v.name__v)
study_country The Name of the Study Country containing the Event (site__v.study_country__v)
subject The Subject ID of the Subject for the Casebook containing the Event (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
eventgroup_sequence Optional For repeating Event Groups, the sequence of the Event Group containing the Event (event_group__v.seq__v)
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
form_name The Name of the Form Definition for the Form (form_def__v.name__v)
form_sequence Optional For repeating Forms, the sequence of the Form (form__v.seq__v)

Edit Submitted Form

Request

curl -X POST https://cdms.vaultdev.com/api/v19.3/app/cdm/forms/actions/edit \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "event_name": "Enrollment-Visit",
            "form_name": "Randomization",
            "change_reason": "Transcription error"
        }
    ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "forms": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Enrollment-Visit",
            "form_sequence": 1,
            "change_reason": "Transcription error"
        }
    ]
}

Make a submitted Form editable and enter a reason for change. Learn more about editing Forms in Vault CDMS Help.

POST /api/{version}/app/cdm/forms/actions/edit

Required Permissions

The following permissions are required to use the Edit Submitted Form API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
study_country The Name of the Study Country (site__v.study_country__v)
site The Site Number of the Site (site__v.name__v)
subject Optional Enter the Subject ID of the subject for the Casebook containing the Form (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Form (event_group_def__v.name__v)
eventgroup_sequence Optional For repeating Event Groups, the sequence of the Event Group containing the Form (event_group__v.seq__v)
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
form_name The Name of the Form Definition for the Form (form_def__v.name__v)
form_sequence Optional For repeating Forms, the sequence of the Form (form__v.seq__v)
change_reason Enter a reason for change.

Coding

If your vault contains the Vault Coder application, and your Study is configured for coding, you can use these endpoints to retrieve information about Code Requests and Forms used for coding in your Study.

A Code Request represents an instance of a coding Form, for example, an Adverse Event, that a data entry user has submitted.

Retrieve Code Requests

Request

curl --location --request GET 'https://myvault.veevavault.com/api/v21.1/app/cdm/coder/codingrequests?study_name=Cholecap&coding_item_definition=VV-000001' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "codingrequests": [
        {
            "coding_item_definition": "V0S000000000101",
            "form_status": "Active",
            "form_type": "AE",
            "dictionary_definition": "MedDRA",
            "requests": [
                {
                    "id": "V0U000000002001",
                    "site": 101,
                    "subject": "0101-0001",
                    "verbatim": "Migraine",
                    "start_date": "2020-02-11T15:45:00Z",
                    "stop_date": "2020-02-13T18:00:00Z",
                    "event": "Common Logs",
                    "event_sequence": 1,
                    "form": "Adverse Event",
                    "form_sequence": 1,
                    "item_group": "Adverse Event Term",
                    "item_group_sequence": 1,
                    "item": "What was the verbatim term of the adverse event?",
                    "coding_status": "Pending Approval",
                    "last_coded_by_third_party": "",
                    "last_coded_date": "2021-02-03T22:30:30Z",
                    "assigned_to_third_party": "",
                    "last_modified_date": "2021-02-03T22:30:30Z",
                    "created_date": "2020-09-21T23:04:05Z",
                    "created_by": "System",
                    "other_properties": {},
                    "seriousness": "No",
                    "severity": "Moderate",
                    "llt_code": "10027599",
                    "llt": "Migraine",
                    "pt_code": "10027599",
                    "pt": "Migraine",
                    "hlt_code": "10027603",
                    "hlt": "Migraine headaches",
                    "hlgt_code": "10019231",
                    "hlgt": "Headaches",
                    "soc": "Nervous system disorders",
                    "soc_code": "10029205",
                    "primary_path": "Y"
                },
                {
                    "id": "V0U000000002003",
                    "site": 101,
                    "subject": "0101-0001",
                    "verbatim": "Nausea",
                    "start_date": "2020-09-14T14:30:00Z",
                    "stop_date": "",
                    "event": "Common Logs",
                    "event_sequence": 1,
                    "form": "Adverse Event",
                    "form_sequence": 2,
                    "item_group": "Adverse Event Term",
                    "item_group_sequence": 1,
                    "item": "What was the verbatim term of the adverse event?",
                    "coding_status": "Open",
                    "last_coded_by_third_party": "",
                    "last_coded_date": "",
                    "assigned_to_third_party": "",
                    "last_modified_date": "2020-10-19T17:02:06Z",
                    "created_date": "2020-09-21T23:06:50Z",
                    "created_by": "System",
                    "other_properties": {},
                    "seriousness": "No",
                    "severity": "Moderate",
                    "llt_code": "",
                    "llt": "",
                    "pt_code": "",
                    "pt": "",
                    "hlt_code": "",
                    "hlt": "",
                    "hlgt_code": "",
                    "hlgt": "",
                    "soc": "",
                    "soc_code": "",
                    "primary_path": ""
                }
            ]
        }
    ]
}

Retrieve a list of Code Requests for a Form. For each Code Request, Vault returns details about the Form, the coding status, and the assigned code (if any).

GET /api/{version}/app/cdm/coder/codingrequests

Required Permissions

The following permissions are required to use this endpoint:

Headers

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

Query Parameters

Include the following parameters to filter the results:

Name Description
study_name The Name of the Study (study__v.name__v)
coding_item_definition The Name of the Medical Coding Item Definition (mc_item_definition__v.name__v). You can get this value from Admin > Business Admin > Medical Coding Item Definitions.
subject Optional Provide the Subject ID of the Subject (casebook__v.name__v) to retrieve only Code Requests for that Subject.
To use subject, you must also use the site and study_country paramaters:
  • site: The Site Number (Name) of the Site (site__v.name__v) containing the Subject.
  • study_country: The Name of the Study Country (site__v.study_country__v) containing the subject's site.
If omitted, Vault retrieves all Code Requests for the Study and Medical Coding Item Definition.
last_modified_date Optional Retrieve only Code Requests modified after the specified datetime. Use the format: "yyyy-MM-ddTHH:mm:ssZ". If omitted, Vault retrieves all Code Requests.

Queries

Queries are a method of questioning entered data. There are two types of queries: system and manual.

A system query is an edit check, run by Vault EDC. Vault creates system queries based on configured data validation rules in your Study. For example, the system would create a query on a value that was outside of the defined acceptable range. If you update your data to a value that’s in range, Vault automatically closes the query for you.

A manual query is a Query record that a CRA or Data Manager creates, or that you create via the Open Query API.

Learn more about queries in Vault CDMS Help.

Retrieve Queries

Request

curl -L -X GET 'https://myvault.veevavault.com/api/v21.1/app/cdm/queries?study_name=Cholecap_DEV1&study_country=United States&site=0101' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "id": "OPW000000003001",
            "query_name": "VV-000003",
            "manual": true,
            "query_status": "open__v",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "enrollment",
            "eventgroup_sequence": 1,
            "event_name": "enrollment_visit",
            "event_sequence": 1,
            "created_date": "2021-09-27T23:29:51Z",
            "created_by": "Cordelia Hunter",
            "messages": [
                {
                    "id": "OPY000000005001",
                    "activity": "open__v",
                    "message": "Open query on Event",
                    "message_date": "2021-09-27T23:29:52Z",
                    "message_by": "Cordelia Hunter"
                }
            ]
        },
        {
            "id": "OPW000000004001",
            "query_name": "VV-000004",
            "manual": true,
            "query_status": "open__v",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0001",
            "eventgroup_name": "common_forms",
            "eventgroup_sequence": 1,
            "event_name": "log_event",
            "event_sequence": 1,
            "form_name": "adverse_event",
            "form_sequence": 1,
            "itemgroup_name": "adverse_event_duration",
            "itemgroup_sequence": 1,
            "item_name": "aestart",
            "created_date": "2021-09-27T23:33:30Z",
            "created_by": "Cordelia Hunter",
            "messages": [
                {
                    "id": "OPY000000006001",
                    "activity": "open__v",
                    "message": "Open query on item",
                    "message_date": "2021-09-27T23:33:31Z",
                    "message_by": "Cordelia Hunter"
                }
            ]
        }
    ]
}

Retrieve a list of all queries for a Site, a Subject, or a Form. You can also retrieve only queries in a certain Query Status.

GET /api/{version}/app/cdm/queries?study_name={study_name}&site={site}&study_country={study_country}

Required Permissions

The following permissions are required to use the Retrieve Queries API:

Headers

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

Query String Parameters

Include the following parameters to filter the results:

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
study_country The Name of the Study Country containing the Site (site__v.study_country__v)
site The Site Number of the Site (site__v.name__v)
subject Optional Enter a subject's Subject ID to retrieve queries only for that Subject (subject__v.name__v). If omitted, the endpoint retrieves queries for all subjects at the site.
form_name Optional The Name of the Form Definition (form_def__v.name__v). Include this parameter to return only queries on the chosen Form. If omitted, the endpoint retrieves queries for all forms.
query_status Optional The Query Statuses to include, as an array. Include this parameter to return only queries with the chosen statuses. If omitted, the endpoint retrieves all queries. Available statuses:
  • open__v (Open)
  • answered__v (Answered)
  • closed__v (Closed)

Response Details

On SUCCESS, Vault returns a list of queries meeting your filter criteria.

Open Query

Request

curl -X POST \
  https://myvault.veevavault.com/api/v19.3/app/cdm/queries \
  -H "Authorization: {SESSION_ID}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "study_name": "Labrinone",
    "queries": [
            {
                "site": "101",
                "study_country": "United States",
                "subject": "101001",
                "query_global_id": 284536,
                "eventgroup_name": "EG.SCR",
                "eventgroup_sequence": 1,
                "event_name": "EV.SCR",
                "form_name": "F.DM",
                "form_sequence": 1
                "itemgroup_name": "IG.DEMOG",
                "itemgroup_sequence": 1,
                "item_name": "DOB",
                "message": "This date does not match our records."
            },
                :
                :
            ]
  }'

Response


{
    "responseStatus": "SUCCESS",
    "queries": [
                {
                    "responseStatus": "SUCCESS",
                    "id": "OPW000000006001",
                    "query_name": "VV-000091",
                    "query_status": "open__v",
                    "site": "101",
                    "study_country": "United States",
                    "subject": "101-001",
                    "eventgroup_name": "EG.SCR",
                    "eventgroup_sequence": 1,
                    "event_name": "EV.SCR",
                    "form_name": "F.DM",
                    "form_sequence": 1,
                    "itemgroup_name": "IG.DM",
                    "itemgroup_sequence": 1,
                    "item_name": "DOB"
                },
                :
                :
              ]
}

Open a Query on an Item or Event Date.

POST /api/{version}/app/cdm/queries

Required Permissions

The following permissions are required to use the Open Query API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
queries For each Query that you want to open, include the following as an array:
  • site: The Site Number of the Site(site__v.name__v)
  • study_country: The Name of the Study Country for the Site (site__v.study_country__v)
  • subject: The Subject ID of the Subject for the Casebook (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
  • eventgroup_sequence: Optional For repeating Event Groups, the sequence of the Event Group containing the Event (event_group__v.seq__v). If omitted, this defaults to "1".
  • event_name: The Name of the Event Definition for the Event (event_def__v.name__v)
  • form_name: (For Item-level queries) The Name of the Form Definition for the Form (form_def__v.name__v)
  • form_sequence: (For Item-level queries) Optional For repeating Forms, the sequence of the Form (form__v.seq__v). If omitted, this defaults to "1".
  • itemgroup_name: (For Item-level queries) The Name of the Item Group Definition for the Item Group (item_group_def__v.name__v)
  • itemgroup_sequence: (For Item-level queries) The Item Group Sequence (sequence number) of the Item Group containing the Item (item_group__v.itemgroup_seq__v). If omitted, this defaults to "1".
  • item_name: (For Item-level queries) The Name of the Item Definition for the Item (item_def__v.name__v)
  • message: Enter the query message text.

Response Details

On SUCCESS, Vault opens a new query on either the Item or the Event Date.

Answer Query

Request

curl -X POST  https://myvault.veevavault.com/api/v19.3/app/cdm/queries/actions/answer \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "queries": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization",
            "message": "This subject was enrolled late."
        }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000000201",
            "query_name": "VV-000002",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "101",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization"
        }
    ]
}

Request (By ID)

curl -L -X POST 'https://myvault.veevavault.com/api/v20.3/app/cdm/queries/actions/answer' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
--data-raw '{
    "study_name": "Cholecap",
    "queries": [
        {
           "id": "OPW000000001001",
           "message": "The screening date is correct."
        }
    ]
  }'

Response (By ID)

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000001001",
            "query_name": "VV-000001",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "0101",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening_visit",
            "event_sequence": 1
        }
    ]
}

Answer an open query with a comment. This moves the query from the Open status into the Answered status. You can identify which query you're answering by its ID or by providing study context to uniquely identify it (Site, Subject, Event Group, Event and so on).

POST /api/{version}/app/cdm/queries/actions/answer

Required Permissions

The following permissions are required to use the Answer Queries API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the query (study__v.name__v)
queries For each Query that you want to answer, include the following as an array:
  • site: The Site Number of the Site(site__v.name__v)
  • study_country: The Name of the Study Country for the Site (site__v.study_country__v)
  • subject: The Subject ID of the Subject for the Casebook (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
  • eventgroup_sequence: Optional For repeating Event Groups, the sequence of the Event Group containing the Event (event_group__v.seq__v). If omitted, this defaults to "1".
  • event_name: The Name of the Event Definition for the Event (event_def__v.name__v)
  • form_name: (For Item-level queries) The Name of the Form Definition for the Form (form_def__v.name__v)
  • form_sequence: (For Item-level queries) Optional For repeating Forms, the sequence of the Form (form__v.seq__v). If omitted, this defaults to "1".
  • itemgroup_name: (For Item-level queries) The Name of the Item Group Definition for the Item Group (item_group_def__v.name__v)
  • itemgroup_sequence: (For Item-level queries) The Item Group Sequence (sequence number) of the Item Group containing the Item (item_group__v.itemgroup_seq__v). If omitted, this defaults to "1".
  • item_name: (For Item-level queries) The Name of the Item Definition for the Item (item_def__v.name__v)
  • message: Enter the comment that you want to answer the query with.

Body Parameters (By ID)

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
queries For each Query that you want to close, provide the following as an array:
  • id: The id of the Query (query__v.id) that you want to close. You can retrieve query IDs with Retrieve Queries.
  • message: Optional Enter a comment to add to the query as you close it.

Close Query

Request

curl -X POST  https://myvault.veevavault.com/api/v19.3/app/cdm/queries/actions/close \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "queries": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization",
            "message": "This issue is now resolved. Query closed."
        }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000000201",
            "query_name": "VV-000002",
            "query_status": "closed__v",
            "study_country": "United States",
            "site": "101",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization"
        }
    ]
}

Request (By ID)

curl -L -X POST 'https://myvault.veevavault.com/api/v20.3/app/cdm/queries/actions/close' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
--data-raw '{
    "study_name": "Cholecap",
    "queries": [
        {
           "id": "OPW000000001001",
           "message": "Closing query - verified that screening date is correct."
        }
    ]
  }'

Response (By ID)

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000001001",
            "query_name": "VV-000001",
            "query_status": "closed__v",
            "study_country": "United States",
            "site": "0101",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening_visit",
            "event_sequence": 1
        }
    ]
}

Close a query. Closing a query indicates that the issue has been fully resolved and no additional action is required, moving the query from the Answered status into the Closed status. You can identify which query you're closing by its ID or by providing study context to uniquely identify it (Site, Subject, Event Group, Event and so on).

POST /api/{version}/app/cdm/queries/actions/close

Required Permissions

The following permissions are required to use the Close Queries API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
queries For each Query that you want to close, include the following as an array:
  • site: The Site Number of the Site(site__v.name__v)
  • study_country: The Name of the Study Country for the Site (site__v.study_country__v)
  • subject: The Subject ID of the Subject for the Casebook (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
  • eventgroup_sequence: Optional For repeating Event Groups, the sequence of the Event Group containing the Event (event_group__v.seq__v). If omitted, this defaults to "1".
  • event_name: The Name of the Event Definition for the Event (event_def__v.name__v)
  • form_name: (For Item-level queries) The Name of the Form Definition for the Form (form_def__v.name__v)
  • form_sequence: (For Item-level queries) Optional For repeating Forms, the sequence of the Form (form__v.seq__v). If omitted, this defaults to "1".
  • itemgroup_name: (For Item-level queries) The Name of the Item Group Definition for the Item Group (item_group_def__v.name__v)
  • itemgroup_sequence: (For Item-level queries) The Item Group Sequence (sequence number) of the Item Group containing the Item (item_group__v.itemgroup_seq__v). If omitted, this defaults to "1".
  • item_name: (For Item-level queries) The Name of the Item Definition for the Item (item_def__v.name__v)
  • message: Optional Enter a comment to add to the query as you close it.

Body Parameters (By ID)

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
queries For each Query that you want to close, provide the following as an array:
  • id: The id of the Query (query__v.id) that you want to close. You can retrieve query IDs with Retrieve Queries.
  • message: Optional Enter a comment to add to the query as you close it.

Reopen Query

Request

curl -X POST  https://myvault.veevavault.com/api/v19.3/app/cdm/queries/actions/reopen \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "queries": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization",
            "message": "Sign-in logs indicate that this subject was actually enrolled on the 20th. Reopening the query."
        }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000000201",
            "query_name": "VV-000002",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "101",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization"
        }
    ]
}

Request (By ID)

curl -L -X POST 'https://myvault.veevavault.com/api/v20.3/app/cdm/queries/actions/reopen' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
--data-raw '{
    "study_name": "Cholecap",
    "queries": [
        {
            "id": "OPW000000001001",
            "message": "Reopening query: Received new information."
        }
    ]
  }'

Response (By ID)

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000001001",
            "query_name": "VV-000001",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "0101",
            "subject": "SCR-0001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening_visit",
            "event_sequence": 1
        }
    ]
}

Reopen a closed query. This moves the query from the Closed status into the Open status, displaying it to site users. You can identify which query you're reopening by its ID or by providing study context to uniquely identify it (Site, Subject, Event Group, Event and so on).

POST /api/{version}/app/cdm/queries/actions/reopen

Required Permissions

The following permissions are required to use the Reopen Queries API:

Headers

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

Body Parameters

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
queries For each Query that you want to reopen, include the following as an array:
  • site: The Site Number of the Site(site__v.name__v)
  • study_country: The Name of the Study Country for the Site (site__v.study_country__v)
  • subject: The Subject ID of the Subject for the Casebook (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
  • eventgroup_sequence: Optional For repeating Event Groups, the sequence of the Event Group containing the Event (event_group__v.seq__v). If omitted, this defaults to "1".
  • event_name: The Name of the Event Definition for the Event (event_def__v.name__v)
  • form_name: (For Item-level queries) The Name of the Form Definition for the Form (form_def__v.name__v)
  • form_sequence: (For Item-level queries) Optional For repeating Forms, the sequence of the Form (form__v.seq__v). If omitted, this defaults to "1".
  • itemgroup_name: (For Item-level queries) The Name of the Item Group Definition for the Item Group (item_group_def__v.name__v)
  • itemgroup_sequence: (For Item-level queries) The Item Group Sequence (sequence number) of the Item Group containing the Item (item_group__v.itemgroup_seq__v). If omitted, this defaults to "1".
  • item_name: (For Item-level queries) The Name of the Item Definition for the Item (item_def__v.name__v)
  • message: Optional Enter a comment to add to the query as you reopen it.

Body Parameters (By ID)

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
queries For each Query that you want to close, provide the following as an array:
  • id: The id of the Query (query__v.id) that you want to close. You can retrieve query IDs with Retrieve Queries.
  • message: Optional Enter a comment to add to the query as you close it.

Users

You can create user accounts and assign users a role in your Study.

Learn more about study user access in Vault CDMS Help.

Retrieve Users

Request

$ curl -X GET \
https://myvault.veevavault.com/api/v19.3/app/cdm/users
  -H "Authorization: {SESSION_ID}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
         "study_name": "Labrinone",
         "user_names": ["olivia.eva@labrinonepharma.com"]
   }'

Response

{
    "responseStatus": "SUCCESS",
    "users": [
                {
                "study_instance": "Labrinone_UAT1"
                "user_name": "olivia.eva@labrinonepharma.com",
                "user_first_name": "Olivia",
                "user_last_name": "Ava",
                "user_email": "olivia.eva@email.com",
                "user_timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)",
                "user_title": "Clinical Research Associate",
                "study_access": "Enabled",
                "security_policy": "Basic",
                "user_language": "en",
                "user_locale": "en_US",
                "company": "VeevaPharm",
                "security_profile": "Data Entry",
                "site_access": "All Sites",
                "country_access": "Mexico, Australia",
                "study_role": "CDMS Lead Data Manager"
                }
              ]
}

Retrieve a list of Users in your Study.

GET /api/{version}/app/cdm/users

Required Permissions

The following permissions are required to use the Retrieve Users API:

Headers

Name Description
Accept application/json (default)

Body Parameters

Name Description
study_name The Study Number (Name) of the Study (study_master__v.name__v for automatic deployment studies, study__v.label__v for manual deployment studies)
user_names Optional Include a list of user names (user__v.user_name__v) to retrieve information about specific users. If omitted, Vault returns all Users for the specified Study.

Response Details

On SUCCESS, Vault returns a list of users currently in your Study, or, if you provided a User Name, information for that user.

Create Users

Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/users \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "users": [
        {
            "study_environment": "CHOLECAP_DEV",
            "user_name": "olivia.eva@verteopharma.com",
            "user_first_name": "Olivia",
            "user_last_name": "Eva",
            "user_email": "oliva-eva@verteopharma.com",
            "user_timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)",
            "user_title": "Clinical Research Associate",
            "study_access": "Enabled",
            "user_language": "en",
            "user_locale": "en_US",
            "company": "Verteo Pharma",
            "security_profile": "Data Review",
            "site_access": "All Sites",
            "country_access": "",
            "study_role": "CDMS Clinical Research Associate",
            "federated_id": "",
            "security_policy": "Basic"
        }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "users": [
        {
            "email__sys": "oliva-eva@verteopharma.com",
            "study_access__v": "Enabled",
            "sites__v": "All Sites",
            "study_instance__v": "CHOLECAP_DEV",
            "security_policy__sys": "Basic",
            "locale__sys": "en_US",
            "bulk_import_status": "Warning: Adding Cross Vault User",
            "role__v": "CDMS Clinical Research Associate",
            "language__sys": "en",
            "countries__v": "",
            "timezone__sys": "(GMT-05:00) Eastern Standard Time (America/New_York)",
            "username__sys": "olivia.eva@verteopharma.com",
            "first_name__sys": "Olivia",
            "last_name__sys": "Eva",
            "errors": []
        }
    ]
}

Create a new user and assign them to your study.

POST /api/{version}/app/cdm/users

Required Permissions

The following permissions are required to use the Create Users API:

Headers

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

Body Parameters

Name Description
study_name For automated deployment studies, the Name of the Study Master (study_master__v.name__v) you want to assign the user to. For manual deployment studies, the Name of the Study (study__v.name__v).
study_environment For automated deployment studies, the Name field value from the Study Instance record (study_instance__v.name__v). For manual deployment studies, exclude this parameter.
user_name The user's vault username (login credential). For example, ewoodhouse@veepharm.com
user_first_name The user's first name
user_last_name The user's last name
user_email The user's email address
company Optional The user's company
user_title Optional The user's title
user_timezone The user's time zone. See a list of available timezones and their appropriate entry format here
user_locale The user's location. See a list of available locales and their appropriate entry format here
user_language The user's preferred language. See a list of available languages and their appropriate entry format here.
study_role The Label of the Study Role (Application Role) for this user (application_role_v.label_v).
study_access Enter "Disabled" or "Enabled". If "Disabled", this user will not have access to the Study in their vault.
site_access Enter a Site or list of Sites (comma separated) to allow the User to access. To give the user access to all sites in your study, enter "all sites".
country_access Enter a Study Country or list of Study Countries (comma separated) to allow the User to access. If you provided access to "all sites" in the site_access parameter, don't include this parameter in your request.
security_profile The Name of the Security Profile for this user (security_profile__sys.name__v)
license_type Optional The user's license type. If omitted, the default value is full__v.
federated_id Optional A Federated ID for the user. Vault uses the Federated ID to map enterprise user names to Vault user names for SSO.
security_policy Optional The user's security policy. If omitted, the default value is basic__v.

Response Details

On SUCCESS, Vault creates the user's Vault account and assigns the user to the specified Study.