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:

• vaultDNS: Enter the DNS of the vault you're using. For example, "myvault.veevavault.com" or "verteopharma.veevavault.com". Do not include a trailing slash (/).
• username: Enter your user name, including the domain, for example, "chunter@verteopharma.com".
• password: Enter your password.
• version: Enter the version of the API that you want to use, for example, "v21.1". See the Versioning section below for details.

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.

• {server} is the domain name of your vault. You can find this by logging into your vault via the UI. Once you log in, you’ll see a URL like this: https://promo-vee.veevavault.com/ui/. In API calls, replace the {server} variable with the "promo-vee.veevavault.com" portion of the URL. If you have access to multiple vaults on a single domain, the domain name will be different for each vault.
• {version} is the API version. Replace it with a version number, such as v16.0.

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.

Session Management

When you log into Vault through the UI or the Authentication endpoint, you generate a session for that user. While a session is active, the authenticated user can perform actions in the UI, make REST API calls, and so on.

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.

Session Duration

A session is considered “active” as long as some activity (either through the UI or API) happens within the maximum inactive session duration. This maximum inactive session duration varies by Vault, and is configured by your Vault Admin. For example, a Vault configured with a session duration of 10 minutes means a session will expire 10 minutes after the last API request finishes executing. As long as an API request is active, the session that made that API call will continue to be valid until the request finishes executing. If you are a Vault Admin, learn more about configuring Session Duration in Vault Help.

The maximum session duration is 48 hours, which is not configurable. This means that even if you keep your session active through activity, it cannot remain active for longer than 48 hours. To keep sessions valid in a long-running integration, see our best practices.

In addition, a session could be invalidated based on major security changes. For example, a password change or account deactivation.

Best Practices

We recommend reusing the sessionId obtained after login to execute as many API requests as possible. To keep your session active, use the Session Keep Alive endpoint. This avoids unnecessary auth calls, which helps your integration stay within the API rate limits.

Make sure your integration catches invalid session exceptions and obtains a new session as needed. Your integration should also include a hard expiration at 48 hours, which is the maximum session duration.

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:

• Burst Limit is the number of API calls that your vault can receive within a fixed 5-minute period. When you reach the burst limit, the server delays responses for the remainder of the burst-limit period. To determine the length of delay for a throttled response, check the X-VaultAPI-ResponseDelay response header or the API Usage Logs.

• Auth API Burst Limit is the number of calls that your vault can make to /api/{version}/auth in a one (1) minute period. When you reach 50% of the burst limit, the server delays responses for the remainder of the burst-limit period. This limit is tracked by the username and vaultDNS parameters and does not apply to SAML/SSO or OAuth authentication. To determine the burst limit for your vault or the length of delay for a throttled response, check the response headers or the API Usage Logs.

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.

• X-VaultAPI-BurstLimit: Indicates the maximum number of calls allowed in a 5-minute burst window. For example, 2000. (Included in v19.2+)
• X-VaultAPI-BurstLimitRemaining: Indicates the number of API calls remaining for the current 5-minute burst window. For example, 1945. (Included in v14.0+)
• X-VaultAPI-ResponseDelay: Indicates the delay, in milliseconds, of a throttled response. Only included for delayed responses. For example, 500ms. See How Does Vault Calculate Limits?. (Included in v14.0+)

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.

• X-VaultAPI-BurstLimitRemaining: Indicates the number of API calls remaining for the current 1-minute burst window. For example, 19.

• X-VaultAPI-BurstLimit: Indicates the maximum number of calls allowed in a 1-minute burst window. For example, 20.

• X-VaultAPI-ResponseDelay: Indicates the length of delay for a throttled response in milliseconds. For example, 2000.

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:

• SUCCESS - The API request was successfully processed.
• FAILURE - The API request could not be processed because of user error.
• EXCEPTION - The API request could not be processed because of system error.

For a responseStatus other than SUCCESS, users can inspect the errors field in the response. Each error includes the following fields:

type - The specific type of error, e.g., INVALID_DATA, PARAMETER_REQUIRED, etc. See below for a full list of types. These values are not subject to change for a given version of the API, even when newer versions of the API are available.

message - The message accompanying each error type, e.g., Missing required parameter [{field_name}]. When available, the error message includes the specific reason, e.g., the {field_name} for the error. These messages are subject to change and are not contractual parts for error handling. Developers should consider error messages for debugging and troubleshooting purposes only and should not implement application logic which relies on specific error strings or formatting.

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 Country is provided, but Study Name is not	To use the study_country parameter, you must provide a value for the study_name parameter.
[Study Site] with name [site] not found	Vault couldn't find a Site with the Site Number (site__v.name__v) provided in site.
Site is provided, but Study Country is not	To use the site parameter, you must provide values for the study_name and study_country parameters.
[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.
Subject is provided, but Site and Study Country are not	To use the subject parameter, you must provide values for study_name, study_country, and study_site.
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.
Derived field update is not allowed	You can't set the value for 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.
Unsupported value provided for [Job Type] parameter, valid types are [event_progress_listing_v, subject_progress_listingv, form_progress_listingv, data_and_definition_exportv, study_data_extractv, core_listingv, query_detail_listing_v]	The value you provided for the job_type parameter was invalid. Update the value for this parameter to one of the valid job types: event_progress_listing__v subject_progress_listing__v form_progress_listing__v data_and_definition_export__v study_data_extract__v core_listing__v query_detail_listing__v
A job of the same type is already running	You can only have one in progress Study Data Extract job at any given time. If you receive this error, wait until the current job finishes before starting a new job.
[File Name] with name [Cholecap Study_Data_Extract] invalid. File names may only include the characters a-z, A-Z, 0-9, -, _ and no double underscores	The file name you provided in file_name contained an invalid character. Provide a new value for file_name that only uses a-z, A-Z, 0-9, dashes (-), and underscores (_), and does not use spaces or double underscores (__).
[File Name] should be entered without the .zip extension	The file name you provided in file_name included the extension (.zip). Remove the extension from file_name.
[External Connection with name [external_connection] not found	Vault could not locate an External Connection with the Name that you provided in the external_connection parameter.
Error writing to destination directory, please check your FTP connection and directory permissions.	Vault encountered an error when attempting to send the output file to the FTP connection specified in the external_connection parameter.
[Forms] with name [forms] not found	Vault could not find a Form Definition with the Name you provided in the forms parameter.
[forms] is a required parameter	The all_forms parameter was set to false, but you didn't include the forms parameter to specify a list of Forms.
[all_forms] or [forms] are required	You must provide the all_forms parameter, and then either set it to true or provide a list of Forms in the forms parameter.
[Export File Type] with [export_file_type] not found	The export_file_type you provided doesn't match one of the accepted values for the parameter: "CSV" or "SAS with XPT and CSV".
[Job] with [job_id] not found	Vault did not find a job with the provided job_id.
[Job] with status [status] is not cancellable	You can only cancel jobs that are in the In Progress status.
[Job] with status [status] is not able to return a log file	Vault can only return the log file when the job is no longer in the In Progress status.
[Job] with status [status] is not able to return an export file	Job output files aren't available until the job is in the Completed status.
Derived field cannot be set	You can't set the value for an Item that is populated by a Set Item Value rule (derived item).
Query ID not found	Vault couldn't find a Query with the ID you provided in the id parameter. For this error, Vault returns SUCCESS but with an empty query list.
Limit is 25000 queries. Please use optional parameters [Study Country], [Study Site], and [Subject] to filter results.	Vault can only return 25000 queries. Provide values for the study_country, site, and subject parameters to filter the results to reduce the number of queries returned.
Last Modified Date must have the following format: yyyy-MM-dd'T'HH:mm:ss'Z'	You must use the yyyy-MM-dd'T'HH:mm:ss'Z' format for the last_modified_date parameter.
No restricted data permission	You are attempting to request restricted data, but you don't have the Restricted Data Access permission. Update include_restricted_data to false.
SDE Version is invalid	The version of the Study Data Extract job you requested in the version parameter is invalid or unavailable. The available versions are v21.2 and v21.3.

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:

• Authentication: User Name & Password
• Create Casebook
• Set Item Values
• Submit Form

Required Permissions

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

• API Access
• Add Casebook
• View Casebook
• Data Entry

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:

• itemgroup_name: creation_criteria
• item_name: subject_initials
• value: DPN

DOB Item:

• itemgroup_name: creation_criteria
• item_name: subject_date_of_birth
• value: 1981-11-14

Gender Item:

• itemgroup_name: creation_criteria
• item_name: subject_gender
• value: F

Race Item:

• itemgroup_name: creation_criteria
• item_name: subject_race
• value: CAUCASIAN

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

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

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:

• An OAuth 2.0 / OpenID Connect profile, the response will also contain the Authentication Server metadata (as_metadata).
• A SAML profile, the auth_profiles array will be empty.

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:

• Vault only returns Studies to which the logged in user has access to, even if more Studies exist.
• Vault returns a maximum of 200 studies per page. You can lower this number using the limit query parameter.

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

Required Permissions:

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

• API Access

Headers

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

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)

Sites

A Site record represents a single clinical research site. A given Study may have any number of Sites. Sites contain metadata about the site itself and group Subjects together for data collection. Learn more about Sites in CDMS Help.

Retrieve Sites

Request

curl -L -X GET 'https://myvault.veevavault.com/api/v21.2/app/cdm/sites?study_name=Cholecap&study_country=United%20States' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
   "responseStatus": "SUCCESS",
   "sites": [
       {
           "site": "0101",
           "site_name": "Pleasanton General Hospital",
           "site_status": "active__v",
           "site_closeout_status": "site_unlocked__v",
           "study_country": "United States",
           "principal_investigator": "Lacey Tiedman",
           "casebook_version": 2,
           "timezone": "(GMT-08:00) Pacific Standard Time (America/Los_Angeles)"
       },
       {
           "site": "0102",
           "site_name": "Radnor Specialty Care",
           "site_status": "active__v",
           "site_closeout_status": "",
           "study_country": "United States",
           "principal_investigator": "Wilma Nguyen",
           "casebook_version": 2,
           "timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)"
       }
   ]
}

Retrieve a list of Sites in your Study. You can filter this list by Study Country.

Vault returns a maximum of 200 sites per page. You can lower this number using the limit query parameter.

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

Required Permissions

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

• API Access
• View Study Sites

Headers

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

Query Parameters

Name	Description
study_name	The Name (Study Number) of the Study (study__v.name__v, returned as study_name by the Retrieve Studies API).
study_country	Optional Provide a Study Country (site__v.study_country__v) to return only Sites associated with that Study Country. If omitted, Vault returns all Sites for the Study.

Response Details

In the RESPONSE, Vault returns the following details about each Site:

Field	Description
site	The Site Number of the Site (site__v.name__v)
site_name	The Name of the Site (site__v.site_name__v)
site_status	The Site Status of the Site (site__v.site_status__v). This is one of the following possible statuses: qualifying__v (Qualifying) initiating__v (Initiating) active__v (Active) closed__v (Closed) enrollment_complete__v (Enrollment Complete) terminated__v (Terminated) withdrew__v (Withdrew) archived__v (Archived) did_not_participate__v (Did Not Participate) candidate__v (Candidate)
site_closeout_status	The Site Closeout Status of the Site (site__v.site_closeout__vr.site_closeout_status__v). If the closeout process hasn't started for the Site, this value is blank ("").This is one of the following possible statuses: generating_closeout_pdfs__v (Generating Closeout PDFs) generation_failed__v (Generation Failed) ready_for_site__v (Ready for Site) awaiting_site_response__v (Awaiting Site Response) downloaded_by_site__v (Downloaded by Site) accepted_by_site__v (Accepted by Site) rejected_by_site__v (Rejected by Site) site_unlocked__v (Site Unlocked) Learn more about closeout.
study_country	The Study Country of the Site (site__v.study_country__v)
principal_investigator	The Principal Investigator assigned to the Site (site__v.principal_investigator__v)
casebook_version	The Casebook Version of the Site (site__v.casebook_def_site__vr.casebook_def__vr.version__v). This is the Active Version assigned by the lead data manager in EDC Tools.
timezone	The Timezone of the Site (site__v.timezone__v).

If the Study does not yet contain any Sites, Vault returns an empty array:

Response - No Sites

{
    "responseStatus": "SUCCESS",
    "sites": []
}

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:

• Pre Screen
• In screening
• Screen Failure
• Enrolled
• Randomized
• End of Treatment
• Withdrawn
• Complete

Notes on using Set Subject Status:

• Vault records any changes to a subject's status in the Subject Status History object (subject_status_history__v).
• If the Subject is already in the status specified in your request, Vault doesn't change the Subject.
• If the Subject status is more advanced than the one specified in your request, Vault will only move the Subject into the lower status if that status is the prior one (most recent record in the Subject Status History). Otherwise, the request fails.

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• Add Casebook
• View Casebook

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook
• Data Entry

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_sequence": 1,
            "event_externalid": "screening_visit",
            "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_sequence": 1,
                    "itemgroup_externalid": "creation_criteria",
                    "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:

• API Access
• View Casebook

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Casebook
• Data Entry

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:

• API Access
• View Code

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://edcdev14-1.vaultdev.com/api/v21.3/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"
                }
            ]
        }
    ]
}

Request: Retrieve All Study Queries with Last Modified Date

curl -L -X GET 'https://myvault.veevavault.com/api/v21.3/app/cdm/queries?study_name=Cholecap&last_modified_date=2020-10-31T12:00:00Z' \
-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:

• API Access
• View Casebook
• View Query (if this feature is enabled in your vault)

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)
id	Optional The ID of the Query, if you want to retrieve only a specific query, or a comma-separated list of query IDs to return multiple queries. This parameter overrides all other parameters, except for study_name.
study_country	Optional The Name of the Study Country containing the Site (site__v.study_country__v)
site	Optional The Site Number of the Site (site__v.name__v). To specify a Site, you must include the study_country parameter.
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 a comma-separated list. 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)
last_modified_date	Optional Retrieve only Queries modified after this datetime. Use the format "yyyy-MM-ddTHH:mm:ssZ". The time must be specified to the second.

Response Details

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

If you used last_modified_date, the response includes a message_date. The message_date acts as a last modified date. The value returned changes when the query message is updated or new.

Retrieve Queries by ID

Request

curl -L -X GET 'https://myvault.veevavault.com/api/v21.3/app/cdm/queries?study_name=Cholecap&id=OPW000000003001' \
-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"
               }
           ]
       }
   ]
}

Retrieve details about a specific Queries by their IDs.

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

Required Permissions

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

• API Access
• View Casebook
• View Query (if this feature is enabled in your vault)

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)
id	The ID of the Query, if you want to retrieve only a specific query, or a comma-separated list of query IDs to return multiple queries.
last_modified_date	Optional Retrieve only query messages modified after this datetime. Use the format "yyyy-MM-ddTHH:mm:ssZ". The time must be specified to the second.

Response Details

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

If the ID for the Query that you provide in the id query parameter is incorrect, Vault returns SUCCESS with an empty query list.

If you used last_modified_date, the response includes a message_date. The message_date acts as a last modified date. The value returned changes when the query message is updated or new.

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 by providing study context to uniquely identify it (Site, Subject, Event Group, Event, and so on).

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

Required Permissions

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

• API Access
• Open Query

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.

Open Query by Event ID

Request

curl -L -g -X POST 'https://myvault.veevavault.com/21.2/app/cdm/events/actions/openquery' \
-H 'Authorization: {SESSION_ID}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "study_name": "Cholecap",
    "queries": [
                 {
                   "id": "V57000000005002",
                   "message": "We ran screening at this site on Saturday, July 31."
                 }
               ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000003001",
            "query_status": "open__v",
            "event_id": "OPS00000000C003"
        }
    ]
}

Open a Query on an Event Date by providing the event's ID.

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

Required Permissions

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

• API Access
• Open Query

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: id: The ID (id) of the Event (event__v) that you want to open a query on. message: Enter the query message text.

Response Details

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

Open Query by Item ID

Request

curl -L -g -X POST 'https://myvault.veevavault.com/21.2/app/cdm/items/actions/openquery' \
-H 'Authorization: {SESSION_ID}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "study_name": "Cholecap",
    "queries": [
                 {
                   "id": "OPW000000004001",
                   "message": "This Item is out of range."
                 }
               ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000004001",
            "query_status": "open__v",
            "item_id": "OPV000000000641"
        }
    ]
}

Open a Query on an Item by providing the item's ID.

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

Required Permissions

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

• API Access
• Open Query

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: id: The ID (id) of the Item (item__v) that you want to open a query on. 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:

• API Access
• Answer Query

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:

• API Access
• Close Query

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:

• API Access
• Open Query

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.

Jobs

In CDMS, a job represents a bulk evaluation or action upon collected study data. For example, the Study Data Extract job exports selected study data in CSV or SAS format.

You can access the following job types via the CDMS API:

• Data and Definition Export: Exports a ZIP file of CSVs representing collected data in your Study
• Study Data Extract: Generates CSV or SAS files for clinical datasets, system datasets, coding datasets, and study definitions
• Core Listings: Generates a simplified CSV for each Form included, listing the data collected for that Form
• Form Progress Listing: Generates a CSV listing all Forms within the Study with status details and operational information
• Query Detail Listing: Generates a list of all Queries in a Study with status details and operational information
• Subject Progress Listing: Generates a list of all Subjects in a Study with status details and operational information
• Event Progress Listing: Generates a list of all Events in a Study with status details and operational information

You can monitor the status of a Job using Retrieve Job Status or by accessing the job history from EDC Tools. To download the output files for a Job, use Retrieve Job Output File or download from EDC Tools.

Learn more about managing jobs in CDMS Help.

Start Core Listings Job

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "Cholecap",
   "request": {
       "job_type": "core_listing__v",
       "all_sites": true,
       "sites": [],
       "all_forms": true,
       "forms": []
   }
}'

Response

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "core_listing__v",
       "job_id": 522516,
       "created_by": "chunter@verteopharma.com",
       "created_date": "2021-10-18T17:45:52Z",
       "all_sites": true,
       "sites": null,
       "all_forms": true,
       "forms": null
   }
}

The Core Listing job generates a simplified CSV for each Form included, listing the data collected for that Form.

POST /api/{version}/app/cdm/jobs/start_now

Required Permissions

The following permissions are required to use the Start Core Listings Job API:

• API Access
• Manage Jobs

Headers

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

Body Parameters

Name	Description
study_name	The Label (study__v.label__v) of the Study in which you want to run the job.
request	Enter the following as an array for request: job_type: Enter core_listing__v. all_sites: Enter true to include data from all Sites in your Study. Otherwise, to include data from specific Sites, enter false. sites: As an array, provide a list of Sites by Site Number (site__v.name__v) that you want to include data from. If you entered true for all_sites, use an empty array. all_forms: Enter true to include data from all Forms in your Study. Otherwise, to include data from specific Forms, enter false. forms: As an array, provide a list of Forms by Form Definition Name (form_def__v.name__v) that you want to include data from. If you entered true for all_forms, use an empty array.

Response Details

On SUCCESS, Vault returns the following job metadata:

Field	Description
job_id	The numerical Job ID for the job, used to Retrieve Job Status and Retrieve Output File.
job_type	The provided job type: core_listing__v
created_by	The User Name of the user who started the job.
created_date	The date and time the job was started.
all_sites	The value provided for the all_sites parameter in the request.
sites	The value provided for the sites parameter in the request.
all_forms	The value provided for the all_forms parameter in the request.
forms	The value provided for the forms parameter in the request.

Start Data and Definition Export Job

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: 511E5C4ADBA98A18E5B48618F9CD7FDBE7E8451CCA2344EB62629FC9743C0AC4469A666DF1C28DF16D3290D4496B20A04B33055A4CE6A424C128CC731C04F4DD' \
--data-raw '{
   "study_name": "Cholecap",
   "request": {
       "job_type": "data_and_definition_export__v",
       "include_restricted_data": true
   }
}'

Response

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "data_and_definition_export__v",
       "job_id": 522417,
       "created_by": "chunter@verteopharma.com",
       "created_date": "2021-10-18T18:10:01Z",
       "include_restricted_data": true
   }
}

The Data and Definition Export job (formerly known as the JReview job) exports a ZIP file of CSVs representing collected data in your Study. This job output is intended for use with the JReview® Integration.

POST /api/{version}/app/cdm/jobs/start_now

Required Permissions

The following permissions are required to use the Start Data and Definition Export Job API:

• API Access
• Manage Jobs OR Manage Data and Definition Export

To include restricted data in the job output, you must also have the Restricted Data Access permission.

Headers

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

Body Parameters

Name	Description
study_name	The Label (study__v.label__v) of the Study in which you want to run the job.
request	Enter the following as an array for request: job_type: Enter data_and_definition_export__v. include_restricted_data: Optional Enter true to include data from all Forms in your Study, including restricted Forms. Otherwise, to exclude restricted Forms, enter false. Note that you may only include restricted data if you have the Restricted Data Access permission.

Response Details

On SUCCESS, Vault returns the following job metadata:

Field	Description
job_id	The numerical Job ID for the job, used to Retrieve Job Status and Retrieve Output File.
job_type	The provided job type: data_and_definition_export__v
created_by	The User Name of the user who started the job.
created_date	The date and time the job was started.
include_restricted_data	The value provided for the include_restricted_data parameter (either true or false)

Start Study Data Extract Job

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: 511E5C4ADBA98A18E5B48618F9CD7FDBE7E8451CCA2344EB62629FC9743C0AC4469A666DF1C28DF16D3290D4496B20A04B33055A4CE6A424C128CC731C04F4DD' \
--data-raw '{
   "study_name": "Cholecap",
   "request": {
       "job_type": "study_data_extract__v",
       "include_restricted_data": true,
       "version": "v21.3",
       "export_file_type": "CSV",
       "file_name": "Cholecap_Study_Data_Extract",
       "use_external_ids": true,
       "include_formilb": true,
       "split_datetime": true,
       "exclude_blank_forms": true   
    }
}'

Response

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "study_data_extract__v",
       "job_id": 522518,
       "created_by": "chunter@verteopharma.com",
       "created_date": "2021-10-18T18:18:54Z",
       "include_restricted_data": true,
       "version": "v21.3",
       "export_file_type": "CSV",
       "file_name": "Cholecap_Study_Data_Extract",
       "external_connections": null,
       "use_external_ids": true,
       "include_formilb": true,
       "split_datetime": true,
       "exclude_blank_forms": true
   }
}

The Study Data Extract job allows the extract of study execution data from Vault, in either CSV (UTF-8) or SAS format.

The Study Data Extract job's output includes the following datasets, in addition to a definitions file:

• SYS_SITE: Lists all Sites.
• SYS_SUB: Lists all Subjects.
• SYS_EVT: Lists all Events (visits) with the Event Date and Status.
• SYS_FORM: Lists all Forms, including any Forms marked as intentionally left blank, with the Review Status, Freeze Status, Lock Status, and some additional metrics.
• SYS_Q: Lists all Queries, along with some query metrics. Only the first query message is listed in this dataset. The full list of query messages (first message, answers, etc.) is included in the SYS_QT dataset.
• SYS_QT: Lists all Query Messages.
• SYS_ILB: Lists all Items that are marked as intentionally left blank.
• SYS_LINKS: Lists all Forms that belong to a Form Link.
• SYS_ASM: Lists all Assessments that exist in the Study, if Assessments are configured in the study design.
• SYS_ASMR: Lists all Questions and Answers for all Assessments, if Assessments are configured in the study design.
• SYS_PD: Lists all Protocol Deviations, if this feature is enabled in the study.
• SYS_RAND: Lists randomization details, if Randomization is enabled for the study.
• SYS_LABRANGES: Lists Normal Ranges, if Labs is enabled for the study.
• SYS_LABLOC: Lists Lab Locations, if Labs is enabled for the study.
• SYS_ANALYTES: Lists Analytes, if Labs is enabled for the study.

See CDMS Help for a detailed list of all columns in the Study Data Extract output.

POST /api/{version}/app/cdm/jobs/start_now

Required Permissions

The following permissions are required to use the Start Study Data Extract Job API:

• API Access
• Manage Jobs

To include restricted data in the job output, you must also have the Restricted Data Access permission.

Headers

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

Body Parameters

Name	Description
study_name	The Label (study__v.label__v) of the Study in which you want to run the job.
request	Enter the following in the JSON object for request: job_type: Enter study_data_extract__v. include_restricted_data: OptionalEnter true to include restricted data, otherwise enter false. If omitted, Vault doesn't include restricted data. version: Enter the Version that you want to use for SDE generation. Available versions: v21.2, v21.3. export_file_type: Enter the Export File Type to use when generating the SDE. The following file types are available: CSV, SAS with XPT and CSV file_name: Optional: Enter a File Name (up to 200 characters) for the output ZIP file without the extension. File names may only include alphanumeric characters, dashes (-), and underscores(), and they may not include double underscores (). If omitted, Vault names the ZIP file with "{Study_Name}_Study_Data_Extract{DATETIME}{TIMEZONE}". external_connections: Optional: To send the output file to a configured FTP destination, enter the Name of the Connection as an array. If omitted, Vault doesn't send the output file to any FTP destination, and you must download it manually. use_external_ids: Optional: Enter true to use the External ID for the Item Definition (item_def__v.external_id__v) to label Items. If set to false or omitted, Vault uses the Name of the Item Definition (item_def__v.name__v). include_formilb: Optional Enter true to include Forms marked as Intentionally Left Blank. If set to false or omitted, Vault doesn't include intentionally left blank Forms. split_datetime: Optional: Enter true to include separate date and time columns for clinical datetime Items. If set to false or omitted, Vault uses a single datetime column. exclude_blank_forms: Optional: Enter true to exclude any blank forms (Forms where the Form Status is Blank) from the SDE. If set to false or omitted, Vault includes blank forms.

Response Details

On SUCCESS, Vault returns the following job metadata:

Field	Description
job_type	The provided job type: study_data_extract__v
job_id	The numerical Job ID for the job, used to Retrieve Job Status and Retrieve Output File.
created_by	The User Name of the user who started the job.
created_date	The date and time the job was started.
include_restricted_data	The value provided for the include_restricted_data parameter (either true or false).
version	The value provided for the version parameter.
export_file_type	The value provided for the export_file_type parameter.
file_name	The value provided for the file_name parameter.
external_connections	The value provided for the external_connections parameter.
use_external_ids	The value provided for the use_external_ids parameter.
use_formilb	The value provided for the use_form_ilb parameter.
split_datetime	The value provided for the split_datetime parameter.
exclude_blank_forms	The value provided for the exclude_blank_forms parameter.

Start Form Progress Listing Job

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "Cholecap",
   "request": {
       "job_type": "form_progress_listing__v",
       "include_restricted_data": true
   }
}'

Response

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "form_progress_listing__v",
       "job_id": 525105,
       "created_by": "chunter@verteopharma.com",
       "created_date": "2021-10-22T00:14:29Z",
       "include_restricted_data": true
   }
}

The Form Progress Listing job generates a CSV listing all Forms within the Study with status details and operational information.

POST /api/{version}/app/cdm/jobs/start_now

Required Permissions

The following permissions are required to use the Start Form Progress Listing Job API:

• API Access
• Manage Jobs

To include restricted data in the job output, you must also have the Restricted Data Access permission.

Headers

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

Body Parameters

Name	Description
study_name	The Label (study__v.label__v) of the Study in which you want to run the job.
request	Enter the following as an array for request: job_type: Enter form_progress_listing__v. include_restricted_data: Optional Enter true to include restricted data, otherwise enter false. If omitted, Vault doesn't include restricted data.

Response Details

On SUCCESS, Vault returns the following job metadata:

Field	Description
job_type	The provided job type: form_progress_listing__v
job_id	The numerical Job ID for the job, used to Retrieve Job Status and Retrieve Output File.
created_by	The User Name of the user who started the job.
created_date	The date and time the job was started.
include_restricted_data	The value provided for the include_restricted_data parameter (either true or false).

Start Query Detail Listing Job

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "Cholecap",
   "request": {
       "job_type": "query_detail_listing__v",
       "include_restricted_data": true
   }
}'

Response

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "query_detail_listing__v",
       "job_id": 525006,
       "created_by": "chunter@verteopharma.com",
       "created_date": "2021-10-22T00:09:06Z",
       "include_restricted_data": true
   }
}

The Query Detail Listing job generates a list of all Queries in a Study with status details and operational information.

POST /api/{version}/app/cdm/jobs/start_now

Required Permissions

The following permissions are required to use the Start Query Detail Listing Job API:

• API Access
• Manage Jobs

To include restricted data in the job output, you must also have the Restricted Data Access permission.

Headers

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

Body Parameters

Name	Description
study_name	The Label (study__v.label__v) of the Study in which you want to run the job.
request	Enter the following as an array for request: job_type: Enter query_detail_listing__v. include_restricted_data: Optional Enter true to include restricted data, otherwise enter false. If omitted, Vault doesn't include restricted data.

Response Details

On SUCCESS, Vault returns the following job metadata:

Field	Description
job_type	The provided job type: query_detail_listing__v
job_id	The numerical Job ID for the job, used to Retrieve Job Status and Retrieve Output File.
created_by	The User Name of the user who started the job.
created_date	The date and time the job was started.
include_restricted_data	The value provided for the include_restricted_data parameter (either true or false).

Start Subject Progress Listing Job

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "Cholecap",
   "request": {
       "job_type": "subject_progress_listing__v",
       "include_restricted_data": true
   }
}'

Response

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "subject_progress_listing__v",
       "job_id": 525007,
       "created_by": "chunter@verteopharma.com",
       "created_date": "2021-10-22T00:09:54Z",
       "include_restricted_data": true
   }
}

The Subject Progress Listing job generates a list of all Subjects in a Study with status details and operational information.

POST /api/{version}/app/cdm/jobs/start_now

Required Permissions

The following permissions are required to use the Start Subject Progress Listing Job API:

• API Access
• Manage Jobs

To include restricted data in the job output, you must also have the Restricted Data Access permission.

Headers

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

Body Parameters

Name	Description
study_name	The Label (study__v.label__v) of the Study in which you want to run the job.
request	Enter the following as an array for request: job_type: Enter subject_progress_listing__v. include_restricted_data: Optional Enter true to include restricted data, otherwise enter false. If omitted, Vault doesn't include restricted data.

Response Details

On SUCCESS, Vault returns the following job metadata:

Field	Description
job_type	The provided job type: subject_progress_listing__v
job_id	The numerical Job ID for the job, used to Retrieve Job Status and Retrieve Output File.
created_by	The User Name of the user who started the job.
created_date	The date and time the job was started.
include_restricted_data	The value provided for the include_restricted_data parameter (either true or false).

Start Event Progress Listing

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "Cholecap",
   "request": {
       "job_type": "event_progress_listing__v",
       "include_restricted_data": true
   }
}'

Response

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "event_progress_listing__v",
       "job_id": 525008,
       "created_by": "chunter@verteopharma.com",
       "created_date": "2021-10-22T00:11:35Z",
       "include_restricted_data": true
   }
}

The Event Progress Listing job generates a CSV listing all Events within the Study with status details and operational information.

POST /api/{version}/app/cdm/jobs/start_now

Required Permissions

The following permissions are required to use the Start Event Progress Listing Job API:

• API Access
• Manage Jobs

To include restricted data in the job output, you must also have the Restricted Data Access permission.

Headers

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

Body Parameters

Name	Description
study_name	The Label (study__v.label__v) of the Study in which you want to run the job.
request	Enter the following as an array for request: job_type: Enter event_progress_listing__v. include_restricted_data: Optional Enter true to include restricted data, otherwise enter false. If omitted, Vault doesn't include restricted data.

Response Details

On SUCCESS, Vault returns the following job metadata:

Field	Description
job_type	The provided job type: event_progress_listing__v
job_id	The numerical Job ID for the job, used to Retrieve Job Status and Retrieve Output File.
created_by	The User Name of the user who started the job.
created_date	The date and time the job was started.
include_restricted_data	The value provided for the include_restricted_data parameter (either true or false).

Cancel Job

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/525010/cancel_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "study_data_extract__v",
       "job_id": 525010,
       "study_name": "Cholecap_DEV1"
   }
}

You can cancel a job that is in the In Progress status. Vault stops the job and moves it into the Canceled status. If you cancel the run of a scheduled job, that job continues to follow the configured schedule.

POST /api/{version}/app/cdm/jobs/{job_id}/cancel_now

Required Permissions

The following permissions are required to use the Start Event Progress Listing Job API:

• API Access
• Manage Jobs

To include restricted data in the job output, you must also have the Restricted Data Access permission.

Headers

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

URI Path Parameters

Name	Description
job_id	The ID of the Job. This is returned in the response for the Start Job endpoint and can also be found in the EDC UI.

Retrieve Job Status

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/525010' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' 

Response

{
    "responseStatus": "SUCCESS",
    "job_type": "form_progress_listing__v",
    "response": {
                  "job_id": 525010,
                  "study_name": "Cholecap",
                  "status": "in_progress__v",
                  "created_by": "chunter@verteopharma.com",
                  "created_date": "2021-10-20T12:14:42Z",
                  "last_modified_date": "2021-10-20T12:20:42Z"
                }
}

You can retrieve the current Status of a job using its Job ID.

GET /api/{version}/app/cdm/jobs/{job_id}

Required Permissions

The following permissions are required to use the Retrieve Job Status API:

• API Access
• Manage Jobs

Headers

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

URI Path Parameters

Name	Description
job_id	The ID of the Job. This is returned in the response for the Start Job endpoint and can also be found in the EDC UI.

Retrieve Job Output File

Request

curl -L -X GET 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/525105/file/content' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \

You can retrieve the output file of a job (ZIP file for the Study Data Extract, Data and Definition Export, and Core Listing, CSV file for Form Progress Listing, Query Detail Listing, Subject Progress Listing, and Event Progress Listing) using its Job ID for up to thirty (30) days after a job is completed.

GET /api/{version}/app/cdm/jobs/{job_id}/file/content

Required Permissions

The following permissions are required to use the Retrieve Job Output File API:

• API Access
• Manage Jobs

Headers

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

URI Path Parameters

Name	Description
job_id	The ID of the Job. This is returned in the response for the Start Job endpoint and can also be found in the EDC UI.

Retrieve Job Log

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v21.3/app/cdm/jobs/525105/file/log' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

2021-10-22T00:14:30.655Z Starting execution for job 525105
2021-10-22T00:14:30.723Z Splitting job into chunks for parallel processing.
2021-10-22T00:14:31.438Z 1 chunk(s) created and ready for processing; submitting to queue.
2021-10-22T00:14:32.603Z Processing chunk 4c118fdb-f781-4ada-8f13-68be3779cd2d.
2021-10-22T00:14:33.612Z Successfully processed chunk 4c118fdb-f781-4ada-8f13-68be3779cd2d; marking as completed.
2021-10-22T00:14:34.602Z Received 4c118fdb-f781-4ada-8f13-68be3779cd2d chunk for aggregation; marking as aggregated.
2021-10-22T00:14:34.638Z All chunks for job 525105 processed; beginning aggregation.
2021-10-22T00:14:34.799Z Successfully aggregated completed results for job 525105.
2021-10-22T00:14:34.814Z All chunks and aggregation were completed successfully, marking job as successful.
2021-10-22T00:14:34.944Z 
2021-10-22T00:14:34.944Z Job Title: AsyncOperation
2021-10-22T00:14:34.944Z Job Type: ASYNC_OPERATION
2021-10-22T00:14:34.944Z Job Subtype: FORM_PROGRESS_LISTING
2021-10-22T00:14:34.944Z Job Schedule Time: 2021-10-22T00:14:30.000Z
2021-10-22T00:14:34.945Z Job Queue Time: 2021-10-22T00:14:30.000Z
2021-10-22T00:14:34.945Z Job Execution Time: 2021-10-22T00:14:31.000Z
2021-10-22T00:14:34.945Z Job Finish Time: 2021-10-22T00:14:35.000Z
2021-10-22T00:14:34.945Z Job Completion Status: Success (COMPLETED_WITH_SUCCESS)

You can retrieve the log file of a job (TXT) using its Job ID for up to thirty (30) days after a job is completed.

GET /api/{version}/app/cdm/jobs/{job_id}/file/log

Required Permissions

The following permissions are required to use the Retrieve Job Log API:

• API Access
• Manage Jobs

Headers

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

URI Path Parameters

Name	Description
job_id	The ID of the Job. This is returned in the response for the Start Job endpoint and can also be found in the EDC UI.

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 -L -X GET 'https://myvault.veevavault.com/api/v21.2/app/cdm/users?study_name=Cholecap_DEV1' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "vault_id": 50720,
    "users": [
        {
            "user_id": "171781",
            "user_name": "amir.darzi@verteopharma.com",
            "user_email": "claire.lundeby@veeva.com",
            "user_title": "Lead Study Designer",
            "user_last_name": "Darzi",
            "user_first_name": "Amir",
            "company": "Verteo Pharma",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-08:00) Pacific Standard Time (America/Los_Angeles)",
            "security_policy": "Basic",
            "activation_date": "2020-02-06",
            "created_date": "2020-02-06T19:08:45Z",
            "last_modified_date": "2021-07-16T19:00:54Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "studies": [
                {
                    "study_environment": "Cholecap_DEV1",
                    "study_role": "CDMS Study Designer",
                    "study_access": "Enabled",
                    "all_sites_access": true,
                    "lms_training_status": "trained__v",
                    "ignore_lms_training_status": true
                }
            ]
        },
        {
            "user_id": "151125",
            "user_name": "chunter@verteopharma.com",
            "user_email": "chunter@verteopharma.com",
            "user_title": "",
            "user_last_name": "Hunter",
            "user_first_name": "Cordelia",
            "company": "",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-08:00) Pacific Standard Time (America/Los_Angeles)",
            "security_policy": "Basic",
            "activation_date": "2020-01-23",
            "created_date": "2020-01-23T22:09:12Z",
            "last_modified_date": "2021-04-05T21:47:05Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": true,
            "all_studies_access": false
        },
        {
            "user_id": "175781",
            "user_name": "gustavo.coleman@verteopharma.com",
            "user_email": "gustavo.coleman@verteopharma.com",
            "user_title": "Coder Administrator",
            "user_last_name": "Coleman",
            "user_first_name": "Gustavo",
            "company": "Verteo Pharma",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-08:00) Pacific Standard Time (America/Los_Angeles)",
            "security_policy": "Basic",
            "activation_date": "2020-02-06",
            "created_date": "2020-02-06T19:27:08Z",
            "last_modified_date": "2021-07-16T19:00:54Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "studies": [
                {
                    "study_environment": "Cholecap_DEV1",
                    "study_role": "CDMS Clinical Coder Administrator",
                    "study_access": "Enabled",
                    "all_sites_access": true,
                    "lms_training_status": "trained__v",
                    "ignore_lms_training_status": true
                }
            ]
        },
        {
            "user_id": "151131",
            "user_name": "lacey.tiedman@verteopharma.com",
            "user_email": "lacey.tiedman@verteopharma.com",
            "user_title": "Principal Investigator",
            "user_last_name": "Tiedman",
            "user_first_name": "Lacey",
            "company": "Verteo Pharma",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-08:00) Pacific Standard Time (America/Los_Angeles)",
            "security_policy": "Basic",
            "activation_date": "2020-01-28",
            "created_date": "2020-01-28T23:44:07Z",
            "last_modified_date": "2021-07-16T18:18:21Z",
            "principal_investigator": true,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "studies": [
                {
                    "access_to_all_environments": true,
                    "study": "Cholecap",
                    "study_role": "Verteo Investigator",
                    "study_access": "Enabled",
                    "lms_training_status": "",
                    "ignore_lms_training_status": false
                }
            ]
        },
        {
            "user_id": "175793",
            "user_name": "peggy.norris@verteopharma.com",
            "user_email": "peggy.norris@verteopharma.com",
            "user_title": "Study Designer",
            "user_last_name": "Norris",
            "user_first_name": "Peggy",
            "company": "Verteo Pharma",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-08:00) Pacific Standard Time (America/Los_Angeles)",
            "security_policy": "Basic",
            "activation_date": "2020-02-06",
            "created_date": "2020-02-06T19:23:29Z",
            "last_modified_date": "2021-07-16T19:00:54Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "studies": [
                {
                    "study_environment": "Cholecap_DEV1",
                    "study_role": "CDMS Study Designer",
                    "study_access": "Enabled",
                    "all_sites_access": true,
                    "lms_training_status": "trained__v",
                    "ignore_lms_training_status": true
                }
            ]
        },
        {
            "user_id": "175777",
            "user_name": "ruth.greene@verteopharma.com",
            "user_email": "ruth.greene@verteopharma.com",
            "user_title": "Clinical Coder",
            "user_last_name": "Greene",
            "user_first_name": "Ruth",
            "company": "Verteo Pharma",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-08:00) Pacific Standard Time (America/Los_Angeles)",
            "security_policy": "Basic",
            "activation_date": "2020-02-06",
            "created_date": "2020-02-06T19:24:54Z",
            "last_modified_date": "2021-07-16T18:18:21Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "studies": [
                {
                    "access_to_all_environments": true,
                    "study": "Cholecap",
                    "study_role": "CDMS Deployment Administrator",
                    "study_access": "Enabled",
                    "lms_training_status": "",
                    "ignore_lms_training_status": false
                }
            ]
        }
    ]
}

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:

• API Access
• View Users

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:

• API Access
• View Users
• Edit Users

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.

Inactivate User

Request: Inactivate User in a Vault

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.2/objects/users/25001

Request: Inactivate User in All Domain Vaults

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v21.2/objects/users/25001?domain=true

Response

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

Inactivate a user in a specific vault or inactivate a user in all vaults in the domain. Vault doesn't allow you to delete user accounts entirely. Instead, you can inactivate any user accounts that are no longer in use. This prevents that account from accessing Vault, but it doesn't remove the account from the system. If needed, you can later activate that user account.

DELETE /api/{version}/objects/users/{user_id}

Required Permissions

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

• API Access
• View Users
• Edit Users

Note that to inactivate a user across a domain, you must be a domain admin.

Headers

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

URI Path Parameters

Name	Description
{user_id}	The user id field value. See Retrieve All Users above.

Query String Parameters

Name	Description
domain	When true, this disables the user account in all vaults in the domain.

Request: Inactivate User in a Vault

This request will set the user (ID: 25001) profile to inactive in the vault in which the request is made. The user will still be a member in the vault and retain their license type and security profile, but their user profile will be inactive and they will no longer have access to the vault.

Request: Inactivate User in All Domain Vaults

This request will set the user (ID: 25001) profile to inactive in all vaults in your domain. The user will still be a member in the vaults and retain their license types and security profiles, but their user profile will be inactive and they will no longer have access to any vaults in your domain.

Activate Users

Update information for a user.

Required Permissions

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

• API Access
• View Users
• Edit Users

Note that to activate a user across a domain, you must be a domain admin.

Request: Activate User at Domain-Level

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "domain_active__v=false" \
https://myvault.veevavault.com/api/v21.2/objects/users/25001

Activate a user.

PUT /api/{version}/objects/users/{id}

Headers

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

URI Path Parameters

Name	Description
{id}	The user id field value. Use the value me to update information for the currently authenticated user.

Body Parameters

In the body of the request, add any editable fields you wish to update. To remove existing field values, include the field name and set its value to null.

Example Request: Activate User at Domain-Level

Only Domain Admins may use this request.

This request will set the (previously inactive) user (ID: 25001) profile to active in your vault domain. However, they will still be inactive in and unable to access your domain vaults. Use the Update Vault Membership request below to set their status to active in the individual vaults in your domain.

Activate Multiple Users

Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Users\update_users.csv" \
https://myvault.veevavault.com/api/v21.2/objects/users

Response

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "id":"12021"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12022"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12023"
      },
      {
         "responseStatus":"FAILURE",
         "id":"22124",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not updated."
            }
         ]
      }
   ]
}

Activate multiple users at once.

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

PUT /api/{version}/objects/users

Headers

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

Body Parameters

Prepare a JSON or CSV input file. You can include any editable user field and value in the input. Note this endpoint does not support the security_profile attribute for updating profiles.

Name	Description
id	The ID of the user to update.
vault_membership	Optional: See Vault Membership for how to configure.