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

• To use the EDC API, you first need a Vault user account. That account must be assigned a Study Role that grants at least the API Access permission.
• The role permissions for the API user (via its role) typically match those required to perform the same action in the EDC UI. For example, to use the Combination Update Form Data endpoint, you must have the View Casebook (view Subject) and Data Entry permissions, in addition to the API Access permission.
• Vault CDMS has two template or standard roles for API users: CDMS API Read Write and CDMS API Read Only.
• The CDMS API Read Write template role can perform all actions. For example, adding queries, closing queries, creating subjects, updating form data, managing users, etc.
  
• Due to some of the endpoints requiring full access in a study, a user using the template role CDMS API Read Write must have All Sites access in a Study. This is not the case for users using the lesser role CDMS API Read Only.

Custom Roles

• To lessen the actions of an API user, a custom role is necessary.
  
• Start with a new role that is a copy of CDMS API Read Write, and refer to the table below for which permissions to remove, i.e. the actions you do not want that API user to be able to perform.
• For an API user that will have access to some but not all Sites in the study, the custom role must exclude the permissions noted in the table where User Must Have All Sites Access? is YES.
• Your organization may have configured your Vault with custom roles, based on the standard ones, so discuss with your organization's administrator what permissions your API-level accounts require.

For more information on the setup of custom roles, standard roles, and user accounts, see Managing Study Roles and Managing User Access in CDMS Help.

Permission in Role Management Grid	Description	User Must Have All Sites Access?
API Access	Ability to access and use the Vault EDC API	No
View Casebook	Ability to view information about Subjects (their Casebooks). Generally, every user should have this permission.	No
Add Casebook	Ability to create new Subjects / Casebooks	No
Data Entry	Ability to enter study data into Casebooks, including entering Event Dates, setting Item values, and submitting Forms	No
Assign Code	Ability to view set suggestions and/or coding on Medical Coding Requests	YES
Open Query	Ability to open (create new) queries or reopen a closed Query	No
Answer Query	Ability to answer (comment on or respond to) queries	No
Close Query	Ability to close queries	No
Manage Users	Ability to create and edit user accounts and assign users their Study Roles	YES
Manage Email Group Assignment	Ability to manage memberships of users in email groups of a study (part of user management)	YES
Edit Study Sites	Ability to create and edit Sites in the Study	YES
Design Study	Ability to create studies, setup the study schedule, copy forms to the new study, etc.	YES
Design Library	Ability to create library studies, copy forms to the new library study, etc.	YES
Manage Safety Configuration	Relates to the Design Study permission	YES

Insufficient Access

If you don't have API access, your authentication request might succeed, but any other API calls you make will return the following error (one example):

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

Contact your Vault administrator to adjust your study account(s) or role(s) for API access.

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.

Get a Session ID

Request

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

Response

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

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

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

API Rate Limits

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

What Are Rate Limits?

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

How Does Vault Calculate Limits?

Vault enforces multiple types of rate limits:

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

Tutorial: Create a Casebook & Submit Data

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

This tutorial uses the following APIs:

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

Response Details

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

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

Subjects

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

Set Subject Status

Request

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

Response

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

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

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

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

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

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

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

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

Required Permissions

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

• 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://myvault.veevavault.com/api/v21.1/app/cdm/queries?study_name=Cholecap_DEV1&study_country=United States&site=0101' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \

Response

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

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

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

Required Permissions

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

• API Access
• View Casebook

Headers

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

Query String Parameters

Include the following parameters to filter the results:

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

Response Details

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

Open Query

Request

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

Response

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

Open a Query on an Item or Event Date.

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

Required Permissions

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

• API Access
• View Casebook
• 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.

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

Users

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

Learn more about study user access in Vault CDMS Help.

Retrieve Users

Request

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

Response

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

Retrieve a list of Users in your Study.

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

Required Permissions

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

• API Access
• Manage 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
• Manage 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.