Getting Started

Run in Postman™

Below is a collection with all examples from this API release. You can use this collection locally in the Postman™ application or in a Postman™ for Web workspace.

For local Postman, use the Get App link in the collection import dialog, or visit the Postman™ website Once you click the Run in Postman button to download the collection, you can choose which workspace to import it into.

If successfully imported, the collection displays (example below) with folders, each containing example API. The folders follow the naming / navigation of this reference page.

To use this collection effectively, use environments to setup a series of variables. The following environment variables are embedded in the collection endpoints:

vaultDNS: DNS of the Vault. Do not include a trailing slash (/), or the prefix of the URL (https://)
username: your Vault username
password: your password to that Vault account
version: API version

The screenshot below shows environment variables for the following Vault setup:

Vault DNS: https://myvault.veevavault.com
User Name: jsmith@verteopharma.com
Vault Version: 24.1

IMPORTANT: The screenshot above includes a sessionId variable. The Postman™ collection includes a Basic Authorization endpoint, which returns the session ID with each successful login, and sets that variable with this value. See the Login / Session section below for details.

CDMS Overview

Data Organization

Data for a CDMS Study follows a model similar to CDISC ODM, e.g. Visits / Forms / Item Groups / Items. CDMS, however, terms a Visit instead an Event, and Event Groups can group a series of Events.

Data Level	Notes
`Study`	Main component of CDMS. A single Vault typically contains many Studies
`Study Country`	Collection of Sites in the Study
`Site`	Collection of Subjects in the Study at that location
`Subject`	A patient in the Study, their data collected across all visits in the Study
`Event Group`	Collection of Events, possibly repeating. Examples Screening Period, Treatment Cycle, Unscheduled Visit
`Event`	One to one with a visit for a Subject, the data collected at that visit. Examples - Screening, Visit 1, Visit 2
`Form`	Organized data for the Subject at an Event, possibly repeating. Examples - Vitals, Demography, PK, etc.
`Item Group`	Organized set of Items on a Form, possibly repeating.
`Item`	A single data point for the Subject. Examples - Date of Birth, Weight, Adverse Event Description

Study Design and Operations

Study design work originates in a Development Vault, with subsequent deployments to Test/UAT Vault, and eventually a Production Vault.
Study design can involve dynamic Rules, who will add appropriate Event Groups, Events and/or Forms, on the submit of Forms that satisfy specific conditions. The API can also add new Event Groups, Events, Forms, perhaps exclusively, or it can also submit existing Forms to execute the dynamic Rules.
Access within a Study follows the Study Country -> Site hierarchy, i.e. which Sites a user can see. A Data Manager might have access to all, a regional CRA some countries but not all, and site users just their specific Site.
Common Forms (also known as Log Forms) are a special type of repeating Form that aren't associated within a specific Event. Examples include Adverse Events and Concomitant Medications.
Given this example Study:

Study = CSM Demo Study_DEV1
Study Country = (not pictured, United Status, a relationship to the site)
Site = 002
Subject = SCR-0004
Event Group = (not pictured). A group of Events (aka visits) are organized into an Event Group to better facilitate repeating cycles and unscheduled Events.
Event = Screening
Form = Vital Signs (details, right side of pictured)
Item Group = Vital Signs (group of fields on a CRF, used for repeating when necessary)
Items = Date of Assessment (date field), Weight (unit codelist field), etc.

CDMS API Overview

The CDMS API is based on the platform Vault API and designed for English locale users.
The GA label of this reference refers to the most recent major/general release
The Beta label sections of this reference refer to the coming major/general release.
Execution of Beta API(s) will only work on either (i) Pre Release Vaults (available approximately 4 weeks from general releases), or (ii) Limited Release Vaults (releases approximately every month, in between general releases).
Veeva Vault releases three new API versions each year, coinciding with Vault general releases. The release cycle is YY.1 (April), YY.2 (August), and YY.3 (December) of each year. For example, the first Vault General Release of 2024 is 24R1. The API version which coincides with this release is API v24.1. The third Vault General Release of 2023 is 23R3, which coincides with REST API v23.3.
The CDMS API was first available at the Vault / Vault CDMS 19R3 release.
Other Vault applications (Safety, Clinical Operations, etc.) have application specific APIs, just as Vault CDMS does.
To view the new APIs, features, and fixed issues for each API version, you can check the Developer Release Notes.
Integrations written on specific versions do NOT have to necessarily move forward with a new release of the API. The downside is that new features and enhanced abilities of existing APIs won't be available in those older releases.
If you plan to move an integration forward regarding its API release, always perform appropriate testing in pre release and/or limited release Vaults prior to applying to general release / production Vaults.

Structuring the Endpoint

The following variable notation is used in the endpoint examples throughout this page:

{vaultDNS} : the domain name of your Vault. You can find this by logging into your Vault through the user interface. For example, upon logging in, if the URL is https://my-vault.veevavault.com/ui/ the {vaultDNS} value is my-vault.veevavault.com. If you have access to multiple Vaults on a single domain, the user account and login endpoint are the same, but the {vaultDNS} part will be different for interacting with each of the specific Vaults (after API login).
{version} : API version. Replace it with a version number, such as v24.1. For example, https://my-vault.veevavault.com/api/v24.1. The older versions of the API can continue to be used on later versions of the overall Vault Release.

API Access

To make API calls against Vault, you first need a Vault user account. That account must be assigned a Study Role that grants the API Access permission. Then, you must have the appropriate permissions for the actions you want to perform via the API. These permissions typically match those required to perform the same action in the CDMS 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 API Access. In this reference, each endpoint lists which permissions are required.

To simplify the granular nature of the permissions required for specific actions, CDMS contains two standard (template) roles for API users: CDMS API Read Write and CDMS API Read Only. Your organization may have configured your Vault with custom roles, based on the standard ones, so discuss with your organization's user administrator what permissions your API-level accounts require.

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

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

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

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

Read vs. Write Access

For read-only access to the CDMS API, we recommend the standard CDMS API Read Only study role, which contains all necessary permissions. This role allows the user access to all GET APIs to retrieve and view information from CDMS.

For read and write access, we recommend the standard CDMS API Read Write study role, which grants all necessary permissions. This includes all permissions from the CDMS API Read Only role, as well as the ability to add or update various study data.

If your organization uses custom Study Roles, your user administrator should model those roles after these two standard API roles.

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

If you do not have API access, contact your Vault administrator to adjust your study account(s) / role(s).

Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d "username={username}&password={password}" \
"https://my-vault.veevavault.com/api/v24.1/auth"

Response

{
    "responseStatus": "SUCCESS",
    "sessionId": "802E62F765575BEB70642BE7A822A419F48B41312ECCAF4767D8DD956873DEE90D677F053A5DAB00B37E2C6B42FA6B15FCE6147C6120F56A638D911EBDFA007B",
    "userId": 92677,
    "vaultIds": [
        {
            "id": 1004329,
            "name": "My Vault",
            "url": "https://my-vault.veevavault.com/api"
        },
        {
            "id": 1004330,
            "name": "My Vault 2",
            "url": "https://my-vault2.veevavault.com/api"
        }
    ],
    "vaultId": 1004329
}

Your first API call will be an authentication request, which is the same endpoint for the access of any Vault. Successful login provides back a session ID for other API calls to include. In the response example to the right, this is the value 802E62F76557....BDFA007B.

For username/password style login, which is the most common, the endpoint /api/{version}/auth expects a POST attempt with two URL-encoded form parameters (x-www-form-urlencoded): username and password. GET / URL style parameters to the authentication are specifically disallowed.
The vaultIds collection in the response is a list of available Vaults for which the user has access into.
The vaultId field under the list of available Vaults tells you which Vault you’ve authenticated against. Rarely, can you authenticate against the wrong Vault if the intended Vault is inactive. In this situation, you’ll authenticate against the last Vault you accessed or the oldest Vault in your domain. Check the vaultId against the information in the list to ensure that it’s the Vault you intended, as you begin other requests.
If the specified Vault is invalid or inactive, a session ID may be returned for an alternate default Vault. It’s important to verify that the currently authenticated Vault shown by the vaultId field is the expected one.

Session Duration

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

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

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

Best Practices

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

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

Pagination

Request - Retrieve Queries (1750 in the study) with default page size of 1000

$ curl -X GET -H "Authorization: {SESSION_ID} \
https://my-vault.veevavault.com/api/v24.1/app/cdm/queries/?study_name=ABCP-2022-01_DEV1

Response - 1st Page (Results 0-999)

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,  
        "offset": 0,    
        "size": 1000,   
        "total": 1750,  
        "next_page": "/api/{version}/app/cdm/queries?resource_locator=4db7ac7f-aa08-486a-99e1-9acb5cdda80e&limit=1000&offset=1000",
        "resource_locator": "4db7ac7f-aa08-486a-99e1-9acb5cdda80e"
    },
    "queries": [
        :
        :
        (1000 entries are here, one per query)
        :
        :   
    ]
}

Request - Retrieve Queries, 2nd Page

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://my-vault.veevavault.com/api/v24.1/app/cdm/queries/resource_locator=4db7ac7f-aa08-486a-99e1-9acb5cdda80e&limit=1000&offset=1000"

Response: 2nd Page (Results 1000 - 1749)

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,  
        "offset": 1000, 
        "size": 750,    
        "total": 1750,  
        "previous_page": "/api/{version}/app/cdm/queries?resource_locator=4db7ac7f-aa08-486a-99e1-9acb5cdda80e&limit=0&offset=0", 
        "resource_locator": "4db7ac7f-aa08-486a-99e1-9acb5cdda80e"
    },
    "queries": [
        :
        :   
    ]
}

By default, Vault returns a maximum of 1000 results per page. This means that for a paginating API, if there are more than 1000 results to be retrieved, you must send multiple API requests to retrieve all data.

Paginating APIs return a json node called responseDetails, which contains the current limit, offset, size, and total.

limit = maximum page size (defaults to 1000)
offset = offset into result set (first result is offset 0)
size = size of current page
total = total # of results to be returned across ALL pages

If additional pages are available, the responseDetails node includes a next_page and resource_locator (an identifier of the overall query) fields. Whenever the next_page field is present in the API response, this indicates that additional page(s) are still available and must be separately retrieved. When fetching a next_page, there is no need to provide any of the original API parameters (like study_name, study_country, etc.). The only required parameters when using next_page are the limit, offset, and resource_locator, which are automatically included in the next_page value.

To recap, next_page requests must contain an offset (positive integer or zero), a limit (positive integer less than 1000), and a resource_locator, all of which are included in the next_page URL returned by a paginating API.

Note that the next_page and previous_page strings only remain active for about 10 minutes following the request, and they can only be used by the same user who made the original request.

For the example on the right (a call to the retrieve queries endpoint, for all queries in the study, 1750 in total):

The initial API request would result in 1000 total queries being returned
We can see this because the limit in the response is set to the default value of 1000
The size (indicating the current page size) is also 1000, yet the total number of results to be returned is 1750 (across all pages)
Additionally, we see that the next_page response field is present.

Users can also set their own limit and offset by providing limit and offset parameters along with the initial API request. In this case, the next_page and previous_page fields returned will reflect the user desired values

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 application or integration. Vault enforces 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.

How Does Vault Calculate Limits?

Vault enforces multiple types of rate limits:

Burst Limit: 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 value.
Auth Burst Limit: 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 API Usage Logs (available in the Admin UI of Vault). WARNING: The limit for logins via the API in any one calendar minute is 20.
Job Status: The Job Status endpoint will return the API_LIMIT_EXCEEDED error if requested more than once in 10 seconds. When polling for a job's state, be sure to throttle your requests.

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, including the daily_limit_remaining in API usage logs, or sends notifications to users when API transaction limits are partially reached or exceeded.

APU 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, i.e., 55 have been used of 2000 in the current 5-minute interval. (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 returns 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.

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

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

Client ID

Recommended Client ID Format

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

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.

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

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@abcpharma.com]",
    "errors": [
        {
            "type": "DOWN_FOR_MAINTENANCE",
            "message": "Vault is currently down for maintenance"
        }
    ],
    "errorType": "AUTHENTICATION_FAILED"
}

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

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

For a responseStatus other than SUCCESS, users can inspect the errors field in the response. If the errors are returned in an errors JSON array (depends on the level of fail, CDMS or Vault), each 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.

Do not use HTTP response status codes for success / failure. Parse for all levels of responseStatus within the response received.

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 found, but not active.
`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. The only way to unlock a user account is for another administrator to perform the Reset Password operation on the user.
`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, generally a low-level trigger in the Vault platform. This could be a trigger that is part of the core application or custom trigger in a specific Vault. For more information about this error, check logs at the Admin -> Logs -> Vault Java SDK Logs area.

Errors - CDMS

Example: Outer vs. Inner responseStatus - Single subject add, fails...

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Study Country] with name [Germany] not found"
            "study_country": "Germany",
            "site": "101",
            "subject": "101-021",
        }
    ]
}

Example: Outer vs Inner responseStatus - Add event groups, one succeeds, one fails...

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States", 
            "site": "101",
            "subject": "101-001",
            "eventgroup_name": "egIRT_INFO",
            "eventgroup_sequence": 1
        },
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Subject] with name [101-021] not found"
            "study_country": "United States",
            "site": "101",
            "subject": "101-021",
            "eventgroup_name": "egIRT_INFO"
        }
    ]
}

CDMS API requests for pushing data into the system allow for multiple actions in a single call. As such, a status per entry is provided in the responses. This is true even if the call only performs a single action.

Always inspect all levels of errors. The outer responseStatus is most often simply a general confirmation that you reached the server, and an action (or actions) were attempted. More importantly, inner statuses (depending upon the endpoint's response format) indicate the actual outcomes of those submitted. Refer to specific endpoints in this reference for response formats, as reporting of errors can differ from endpoint to endpoint. See examples to the right.

Example: Incorrect study_name for Create Subject / Casebook

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Study] with name [ABCP-2022-01_DEV2] not found",
            "study_country": "United States",
            "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": "101",
            "subject": "101-001",
            "eventgroup_name": "enrollment",
            "eventgroup_sequence": 1,
            "event_name": "enrollment_visit",
            "event_sequence": 1
        }
    ]
}

The table below lists common errors for CDMS APIs:

Area	Error	Description
Study	[Study] with name [study_name] not found	Vault couldn't find a Study with the Name provided in `study_name`.
Study	[Study Country] with name [study_country] not found	Vault couldn't find a Study Country with the Name provided in `study_country`.
Study	Study Country is provided, but Study Name is not	To use the `study_country` parameter, you must provide a value for the `study_name` parameter.
Study	[Study Site] with name [site] not found	Vault couldn't find a Site with the Site Number (`site__v.name__v`) provided in `site`.
Study	Site is provided, but Study Country is not	To use the `site` parameter, you must provide values for the `study_name` and `study_country` parameters.
Study	[Subject] with name [subject] not found	Vault couldn't find a Subject with the Name (Subject ID) provided in `subject`.
Study	[Subject] with name [subject] exists	A Subject with the Name (Subject ID) provided in `subject` already exists.
Study	Study is locked	The Study is locked, and so this action is not allowed.
Study	Site is locked	The Site is locked, and so this action is not allowed.
Study	Subject is provided, but Site and Study Country are not	To use the `subject` parameter, you must provide values for `study_name`, `study_country`, and `study_site`.
Study	Subject is frozen	The Subject is frozen, and so the action isn't allowed.
Study	Subject is locked	The Subject is locked, and so the action isn't allowed.
Study	[Event Definition] with [event_name] not found	Vault couldn't find an Event Definition with the Name provided in `event_name`.
Study	[Event Group Definition] with [eventgroup_name] not found	Vault couldn't find an Event Group Definition with the Name provided in `eventgroup_name`.
Study	[Form Definition] with name [form_name] not found	Vault couldn't find a Form Definition with the Name provided in `form_name`.
Study	[Item Group Definition] with name [itemgroup_name] not found	Vault couldn't find an Item Group Definition with the Name provided in `itemgroup_name`.
Study	[Item Definition] with name [item_name] not found	Vault couldn't find an Item Definition with the Name provided in `item_name`.
Study	Change reason is required	You didn't provide a value for `change_reason`, which is required for this API.
Study	Change reason too long	The `change_reason` you provided exceeds the maximum character limit.
Study	Country [country] does not exist	The `country` you provided is invalid.
Study	Event Date is frozen	The Event Date is frozen because either the Subject or Event is frozen, and so this action is not allowed.
Study	Event Date is locked	The Event Date is locked because either the Subject or Event is locked, and so this action is not allowed.
Study	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.
Study	Form is frozen	The Form is frozen, and so this action is not allowed.
Study	Form is locked	The Form is locked, and so this action is not allowed.
Study	Form is not submitted	The Form is not in the Submitted status, and so you can't use the Reopen Submitted Forms API to move it to the In Progress status.
Study	Item is locked	The Item is locked, and so this action is not allowed.
Study	Item value is not in correct format for setting the item	The `value` you provided isn't in the correct format for the Item.
Study	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 Reopen Submitted Forms API to return the Form to the In Progress status.
Study	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`.
Study	Unique item cannot be found with the specified keys	Vault couldn't find the Form for this Item.
Queries	Query ID not found	Vault couldn't find a Query with the `id` provided.
Queries	Query is already in the Closed status	You can't answer or close a Query that is already in the Closed status.
Queries	Query is already in the Reopened status	You can't reopen a Query that is already in the Reopened status.
Queries	Query not in Closed status	You can't reopen a Query that isn't in the Closed status.
Queries	Query ID not found	Vault couldn't find a Query with the ID you provided in the `id` parameter. For this error, Vault returns `SUCCESS` but with an empty query list.
Queries	Derived field cannot be set	You can't set the value for an Item that is populated by a Set Item Value rule (derived item).
Queries	Message is required	The `message` parameter is required for this API.
Queries	Message is too long	The `message` provided exceeds the maximum character limit.
Queries	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.
Jobs	Unsupported value provided for [Job Type] parameter, valid types are [event_progress_listing_v, subject_progress_listingv, form_progress_listingv, data_and_definition_exportv, study_data_extractv, core_listingv, query_detail_listing_v]	The value you provided for the job_type parameter was invalid. Valid job types can be found at: Job Summary / Types
Jobs	A job of the same type is already running	You can only have one in progress Study Data Extract job at any given time. If you receive this error, wait until the current job finishes before starting a new job.
Jobs	[Job] with [job_id] not found	Vault did not find a job with the provided `job_id`.
Jobs	[Job] with status [status] is not cancellable	You can only cancel jobs that are in the In Progress status.
Jobs	[Job] with status [status] is not able to return a log file	Vault can only return the log file when the job is no longer in the In Progress status.
Jobs	[Job] with status [status] is not able to return an export file	Job output files aren't available until the job is in the Completed status.
Jobs	[File Name] with name [...value...] invalid. File names may only include the characters a-z, A-Z, 0-9, -, _ and no double underscores	The file name you provided in `file_name` contained an invalid character. Provide a new value for `file_name` that only uses `a-z`, `A-Z`, `0-9`, dashes (`-`), and underscores (`_`), and does not use spaces or double underscores (`__`).
Jobs	[File Name] should be entered without the .zip extension	The file name you provided in `file_name` included the extension (.zip). Remove the extension from `file_name`.
Jobs	[External Connection with name [external_connection] not found	Vault could not locate an External Connection with the Name that you provided in the `external_connection` parameter.
Jobs	[Forms] with name [forms] not found	Vault could not find a Form Definition with the Name you provided in the `forms` parameter.
Jobs	[forms] is a required parameter	The `all_forms` parameter was set to `false`, but you didn't include the `forms` parameter to specify a list of Forms.
Jobs	[all_forms] or [forms] are required	You must provide the `all_forms` parameter, and then either set it to `true` or provide a list of Forms in the `forms` parameter.
Jobs	[Export File Type] with [export_file_type] not found	The `export_file_type` you provided does not match one of the accepted values for the parameter: "CSV" or "SAS with XPT and CSV".
Jobs	SDE Version is invalid	The version of the Study Data Extract job you requested in the `version` parameter is invalid or unavailable. The available versions are ... (versions listed)
Medical Coding	Coding Request not found	The `coding_request` parameter is invalid or does not match an existing Code Request record.
Medical Coding	Coding Request is null	The `coding_request` parameter is required.
Medical Coding	Coding Request is blank	The `coding_request` parameter must have a value.
Subject / Casebook	Casebook cannot be added. [Study Site] with name [value] does not have an active casebook version.	The Site you are attempting to create a Casebook within does not have an Active Casebook Version assigned.
Users	Language [language] does not exist	The `language` you provided does not exist in Vault or is otherwise invalid.
Users	Last name must be no greater than 100 characters	The `last_name` provided exceeds the maximum character limit of 100 characters.
Users	Duplicate	A user with this `user_name` already exists.
Users	Locale [locale] does not exist	The `locale` you provided does not exist in Vault or is otherwise invalid.
Users	Email needs to be of valid format	The `email` you provided isn't in a valid format.
General	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.
General	Last Modified Date must have the following format: yyyy-MM-dd'T'HH:mm:ss'Z'	You must use the yyyy-MM-dd'T'HH:mm:ss'Z' format for the `last_modified_date` parameter.
General	No permission for this action	You don't have the permissions required to use this API.
General	Error writing to destination directory, please check your FTP connection and directory permissions.	Vault encountered an error when attempting to send the output file to the FTP connection specified in the `external_connection` parameter.
General	No restricted data permission	You are attempting to request restricted data, but you don't have the Restricted Data Access permission. Update `include_restricted_data` to `false`.
General	The allowed maximum value for [limit] parameter is: 1000	The maximum allowed value for the `limit` is 1000. Enter a number lower than 1000.
General	Expecting integer value for parameter [limit] but received [1a]	The `limit` operator requires a positive integer.
General	Expecting integer value for parameter [offset] but received [1a]	The `offset` operator requires a positive integer.
General	No results found using the resource_locator [offset]	A different user than the one who made the original request attempted to use the resource_locator (`next_page`/`previous_page` URLs) to paginate. The resource_locator request must be made by the same user who made the original request.

Authentication

Authenticate your account using one of the methods outlined below. The response returns a session ID that you then use in subsequent API calls, inside the Authorization HTTP request header. Session IDs time out after a period of inactivity. The period varies by Vault.

User Name & Password

Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d "username={username}&password={password}" \
"https://my-vault.veevavault.com/api/v24.1/auth"

Response

{
    "responseStatus": "SUCCESS",
    "sessionId": "802E62F765575BEB70642BE7A822A419F48B41312ECCAF4767D8DD956873DEE90D677F053A5DAB00B37E2C6B42FA6B15FCE6147C6120F56A638D911EBDFA007B",
    "userId": 92677,
    "vaultIds": [
        {
            "id": 1004329,
            "name": "My Vault",
            "url": "https://my-vault.veevavault.com/api"
        },
        {
            "id": 1004330,
            "name": "My Vault 2",
            "url": "https://my-vault2.veevavault.com/api"
        }
    ],
    "vaultId": 1004329
}

Authenticate your account using your Vault username and password to obtain a Vault Session ID.

For a username and password style login (the most common style) the endpoint (/api/{version}/auth) expects a POST attempt with two URL-encoded form parameters (x-www-form-urlencoded): username and password. GET / URL style parameters to the authentication are specifically disallowed.

Endpoint

POST https://{vault_subdomain}/api/{version}/auth

Headers

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

URI Path Parameters

Name	Description
`vault_subdomain`	The DNS of the Vault for which you want to generate a session. If this domain is invalid or inactive, Vault executes logic to authenticate the user to their most relevant available Vault. The term invalid applies to any Vault where the requesting user is unable to authenticate. Learn more about default Vaults.
`version`	The Vault REST API version. Your authentication version does not need to match the version in subsequent calls. For example, you can authenticate with v22.2 and run your integrations with v22.3.

Body Parameters

Name	Description
`username`	The username of your Vault account
`password`	The password of your Vault account
`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.

Authentication servers are not Vault or domain specific, so any valid URL can be used to access the authentication servers. Authentication only inspects the username and password. The authentication endpoints authenticate the user to the Vault specified in the vault_subdomain. For example, https://{vault_subdomain}/api/{version}/auth. You can also override this domain with the vaultDNS parameter, which generates a session for the subdomain specified.

Response Details

On SUCCESS, this request returns a valid sessionId for any Vault DNS where the user has access.

The Vault DNS for the returned session is calculated in the following order:

Generates a session for the DNS in the optional vaultDNS body parameter. If this vaultDNS is invalid, generates a session for the user’s most relevant available Vault:

Generates a session for the Vault where the user last logged in
If the user has never logged in, or if the last logged-in Vault is inactive, generates a session for the oldest active Vault where that user is a member
If the user is not a member of any active Vaults, the user cannot authenticate, and the API returns FAILURE

If the optional vaultDNS body parameter is omitted, generates a session for the DNS specified in the vaultDNS URI parameter.
If this vaultDNS is invalid, generates a session for the user’s most relevant available Vault:

Generates a session for the Vault where the user last logged in
If the user has never logged in, or if the last logged-in Vault is inactive, generates a session for the oldest active Vault where that user is a member
If the user is not a member of any active Vaults, the user cannot authenticate, and the API returns FAILURE

An invalid DNS is any DNS that the specified user cannot access, for example, if the DNS does not exist, if the user does not exist in that DNS, or if all Vaults in that DNS are inactive.

It is best practice to inspect the response, compare the desired Vault ID with the list of returned vaultIds, and confirm the DNS matches the expected login. This API only returns FAILURE if it is unable to return a valid sessionIdfor any Vault the user can access.

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 the Bearer keyword to send Vault session IDs as bearer tokens.

Bearer Token Authorization

Name	Description
`Authorization`	Bearer {`sessionId`}

OAuth 2.0 / OpenID Connect

Request

$ curl -X POST \
-H "Authorization: Bearer 1C29326C3DF" \
-H "Host: Bearer 1C29326C3DF" \
"https://my-vault.veevavault.com/auth/oauth/session/_9ad0a091-cbd6-4c59-ab5a-d4f2870f218c"

Response

{
    "responseStatus": "SUCCESS",
    "sessionId": "802E62F765575BEB70642BE7A822A419F48B41312ECCAF4767D8DD956873DEE90D677F053A5DAB00B37E2C6B42FA6B15FCE6147C6120F56A638D911EBDFA007B",
    "userId": 92677,
    "vaultIds": [
        {
            "id": 1004329,
            "name": "My Vault",
            "url": "https://my-vault.veevavault.com/api"
        },
        {
            "id": 1004330,
            "name": "My Vault 2",
            "url": "https://my-vault2.veevavault.com/api"
        }
    ],
    "vaultId": 1004329
}

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. More information on client_id found in a previous section.

Endpoint

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.

Endpoint

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

Headers

Name	Description
`Accept`	`application/json` (default)

Query String Parameters

Name	Description
`username`	The user’s Vault username
`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 as the main organization of data for a trial. Components that exist under a Study include Study Countries, Sites, Subjects (also known as Casebooks), Queries, Medical Coding Requests, Study Jobs, and Form data.

Retrieve Studies

Request

curl -L -X GET 'https://myvault.veevavault.com/api/v24.1/app/cdm/studies' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response


{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "studies": [
        {
            "study": "Labrinone_DEV1",
            "study_name": "Labrinone_DEV1",
            "study_label": "Labrinone_DEV1",
            "external_id": "Labrinone",
            "study_phase": "phase_ii__v",
            "study_status": "planning__v",
            "locked": true, 
            "last_locked_date": "2023-06-02T12:00:00Z",
            "connect_to_vault_ctms": true,
            "organization": "ABC Pharma",
            "environment_type": "development__v",
            "build_number": 14,
            "casebook_versions": [
                {
                    "casebook_version": 1,
                    "version_name": "Initial Version",
                    "external_id": "1",
                    "previous_version_name": null,
                    "description": null,
                    "change_reason": null,
                    "casebook_status": "in_progress__v",
                    "created_by": "Eric Emerton",
                    "created_date": "2023-02-12T22:32:21Z",
                    "last_modified_date": "2023-03-04T14:16:20Z"
                }
            ]
        },
        {
            "study_name": "ABCP-2022-01_DEV1",
            "external_id": "ABCP-2022-01",
            "study_phase": "phase_i__v",
            "study_status": "execution__v",
            "locked": false, 
            "last_locked_date": null,
            "connect_to_vault_ctms": false,
            "organization": "ABC Pharma",
            "environment_type": "development__v",
            "build_number": 43,
            "casebook_versions": [
                {
                    "casebook_version": 2,
                    "version_name": "Version2",
                    "external_id": "Version2",
                    "previous_version_name": "Initial Version",
                    "description": "Casebook Definition with changes  for the ABCP-2022-01_DEV1 study" ,
                    "change_reason": "Layout changes",
                    "casebook_status": "in_progress__v",
                    "created_by": "Maisha Muddaththir",
                    "created_date": "2023-06-28T14:26:34Z",
                    "last_modified_date": "2023-06-28T14:26:34Z"
                },
                {
                    "casebook_version": 1,
                    "version_name": "Initial Version",
                    "external_id": "Initial Version",
                    "previous_version_name": null,
                    "description": "Initial casebook definition version for the ABCP-2022-01_DEV1 study" ,
                    "change_reason": null,
                    "casebook_status": "published__v",
                    "created_by": "Maisha Muddaththir",
                    "created_date": "2023-06-09T13:26:34Z",
                    "last_modified_date": "2023-06-09T13:26:34Z"
                }
            ]
        }
    ]
}

Notes

Used to retrieve the list of Studies in the Vault.
The casebook_versions array within each studies entry indicates design casebook versions for the Study.
Versions are assigned at add Subject per the active version at that Site. Later, during amendments, a Subject / Site / entire Study can transition from one version to the next.
ONLY the Studies the user has permissions and are indicated as trained appear in responses from the API. Contact an administrator on the Vault to have an override set regarding training.
A coming release of the API will allow for usage of either study (match on Study label) or study_name. For clarity on this change, this endpoint (at 23R3) includes all four of these values: study_name, study_label, study_external_id, and the study (always matches study_label)
At 23R3 - the study_phase and study_status were changed to picklist name where it used to be picklist label. (picklist name is the Vault standard)

Endpoint

GET https://my-vault.veevavault.com/api/v24.1/app/cdm/studies

Required Permissions

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

API Access

Both the CDMS API Read Only and CDMS API Read Write roles grant this permission.

Headers

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

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

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

Array	Name	Description
`studies`	`study`	This value is always the same as `study_label`
`studies`	`study_name`	Name of the Study. Although very rare, this may differ from the Study label seen on screen
`studies`	`study_label`	Label of the Study. This is the Study identification through the UI, reports, exports. It can - on rare occasion - differ from `study_name` (e.g. relabel).
`studies`	`external_id`	External ID field value from the Study record
`studies`	`study_phase`	Study Phase picklist name (not label) from the Study record
`studies`	`study_status`	Study Status picklist name (not label) from the Study record
`studies`	`locked`	Whether the Study is currently locked, or not (true/false)
`studies`	`last_locked_date`	The date/time of the last locking of the Study
`studies`	`connect_to_vault_ctms`	Whether the Study is currently connected to a Vault CTMS (true/false)
`studies`	`organization`	Name of the organization in the Vault that the Study is grouped under
`studies`	`environment_type`	The type of environment for the Study - picklist name (not label)
`studies`	`build_number`	For the Study its build number from Study design. Design and other information can be retrieved in further detail via Retrieve Study Masters when using the main development Vault
`studies`	`casebook_versions`	For each Casebook Version associated with the Study, Vault returns the following as an array: `study_name` `casebook_version` `version_name` `external_id` `previous_version_name` `description` `change_reason` `casebook_status` `created_by` `created_date` `last_modified_by`
`studies/casebook_versions`	`casebook_version`	The version number (integer) of the casebook definition
`studies/casebook_versions`	`version_name`	The version name of the casebook definition
`studies/casebook_versions`	`external_id`	The external ID of the casebook definition
`studies/casebook_versions`	`previous_version_name`	Not in use, return is null
`studies/casebook_versions`	`description`	The descripition of the casebook definition
`studies/casebook_versions`	`change_reason`	A reason for the casebook version (if set)
`studies/casebook_versions`	`casebook_status`	The status of the casebook version, e.g. `published__v`, `validated__v`, etc. (Vault picklist values)
`studies/casebook_versions`	`created_by`	The name of the user that added (or deployed to) the casebook version
`studies/casebook_versions`	`created_date`	The creation date/time of the add (or deployment)
`studies/casebook_versions`	`last_modified_by`	The name of the user that last modified the casebook definition

Study Countries

Vault CDMS uses a Study Country to group together Sites.

Retrieve Study Countries

Request

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/sites?study_name=ABCP-2022-01_DEV1' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 3,
        "total": 3
    },
    "study_countries": [
        {
            "study_country": "United States",
            "country": "United States",
            "country_abbreviation": "USA",
            "created_by": "Eric Emerton",
            "created_date": "2022-05-23T17:17:24Z",
            "last_modified_date": "2022-05-23T17:17:24Z"
        },
        {
            "study_country": "Austria",
            "country": "Austria",
            "country_abbreviation": "AUT",
            "created_by": "Eric Emerton",
            "created_date": "2022-05-23T17:22:45Z",
            "last_modified_date": "2022-05-23T17:22:45Z"
        },
        {
            "study_country": "Canada",
            "country": "Canada",
            "country_abbreviation": "CAN",
            "created_by": "Eric Emerton",
            "created_date": "2022-05-23T17:22:53Z",
            "last_modified_date": "2022-05-23T17:22:53Z"
        }
    ]
}

Notes

Used to get the Study Countries of a Study.
Each are activated into a Study from the Vault master country list (country__v object).
Study Country information is also returned in most endpoint responses.

Endpoint

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

Required Permissions

The following permissions are required to use the Retrieve Study Countries API:

API Access

Vault only returns Study Countries to which the logged in user has access, even if more Study Countries exist.

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 (Study Number) of the Study (`study__v.name__v`) that you want to retrieve the study countries for, returned as `study_name` by the Retrieve Studies API.

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer). If omitted, the default is 1. For example, if the `limit` is set to "100", and there are 150 possible records, use "101" as the `offset` to show results 101 through 150.

Response Details

Vault returns the following details about each Study Country:

Array	Name	Description
`study_countries`	`study_country`	The Name of the Study Country (`study_country__v.name__v`)
`study_countries`	`country`	The Name of the Country for the Study Country (`study_country__vr.country__v.name__v`)
`study_countries`	`abbreviation`	The Abbreviation of the Country for the Study Country (`study_country__vr.country__v.abbreviation__v`)
`study_countries`	`created_by`	The User Name of the User who created the Study Country (`study_country__v.created_by__v`)
`study_countries`	`created_date`	The Created Date for the Study Country (`study_country__v.created_date__v`)
`study_countries`	`last_modified_by`	The Last Modified Date for the Study Country (`study_country__v.last_modified_date__v`)

If the Study does not yet contain any Study Countries, Vault returns an empty array (example to the right)

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

Sites

A Site in Vault CDMS represents a single clinical research location. A given Study may have any number of Sites, under which are the Subjects of the Site. Properties for a Site include status, assigned Casebook version for newly added Subjects, principal investigator, Review Plans, and the Study Country to which they belong. Learn more about Sites in CDMS Help.

Retrieve Sites

Request - All sites in the study

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/sites?study_name=ABCP-2022-01_DEV1' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - All sites in the study

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 4,
        "total": 4
    },
    "sites": [
        {
            "site": "101",
            "site_name": "Cary Hospital",
            "site_status": "active__v",
            "site_closeout_status": "",
            "study_country": "United States",
            "principal_investigator": "Linda Johnson",
            "casebook_version": 1,
            "timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)"
        },
        {
            "site": "102",
            "site_name": "Raleigh Hospital",
            "site_status": "active__v",
            "site_closeout_status": "",
            "study_country": "United States",
            "principal_investigator": "Mary Peters",
            "casebook_version": 1,
            "timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)"
        },
        {
            "site": "201",
            "site_name": "Montreal General",
            "site_status": "active__v",
            "site_closeout_status": "",
            "study_country": "Canada",
            "principal_investigator": "Jim Jones",
            "casebook_version": 1,
            "timezone": "(GMT-06:00) Central Standard Time (America/Chicago)"
        },
        {
            "site": "202",
            "site_name": "No Active CB Version",
            "site_status": "active__v",
            "site_closeout_status": "",
            "study_country": "United States",
            "principal_investigator": "Mary Smith",
            "casebook_version": null,
            "timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)"
        }
    ]
}

Request - No sites in study yet

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/sites?study_name=ABCP-2022-01_DEV1' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - No sites in study yet

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

Notes

Used to get the Sites of a Study
Optionally, get the Sites of only one Study Country
Casebook version (i.e. what new Subjects added to the site will receive) is returned with other attributes

Endpoint

GET https://my-vault.veevavault.com/api/v24.1/app/cdm/sites

Required Permissions

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

API Access
View Study Sites

Both the CDMS API Read Only and CDMS API Read Write roles grant this permission.

Headers

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

Query String Parameters

Name	Description
`study_name`	Name of the Study).
`study_country`	Optional Name of Study Country to filter on. If omitted, Vault returns all Sites.

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

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

Array	Name	Description
`sites`	`site`	Site Number of the Site e.g. 101, 102, 201, or however the study defines Site numbering
`sites`	`site_name`	Name of the Site. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`sites`	`site_status`	Status of the Site. This is one of the following possible statuses: `qualifying__v` (Qualifying) `initiating__v` (Initiating) `active__v` (Active) `closed__v` (Closed) `enrollment_complete__v` (Enrollment Complete) `terminated__v` (Terminated) `withdrew__v` (Withdrew) `archived__v` (Archived) `did_not_participate__v` (Did Not Participate) `candidate__v` (Candidate)
`sites`	`site_closeout_status`	Closeout Status of the Site. If the closeout process hasn't started for the Site, this value is blank (`""`).This is one of the following possible statuses: `generating_closeout_pdfs__v` (Generating Closeout PDFs) `generation_failed__v` (Generation Failed) `ready_for_site__v` (Ready for Site) `awaiting_site_response__v` (Awaiting Site Response) `downloaded_by_site__v` (Downloaded by Site) `accepted_by_site__v` (Accepted by Site) `rejected_by_site__v` (Rejected by Site) `site_unlocked__v` (Site Unlocked) Learn more about closeout.
`sites`	`study_country`	Name of the Study Country of the Site
`sites`	`principal_investigator`	The Principal Investigator assigned to the Site
`sites`	`casebook_version`	Casebook Version of the Site. This is the version of the Study scheduled of Events / Forms newly created Subjects will receive. Some Sites might be on different versions of the design (all Sites do not have to be on the same version at once). This important version is assigned by a user via the UI, at Tools -> EDC Tools. Learn more about Sites in CDMS Help
`sites`	`timezone`	The Timezone of the Site (`site__v.timezone__v`)

Subjects / Casebooks

Vault CDMS uses two objects to manage participants in a Study: Subject and Casebook. For the purposes of the CDMS API, these are synonyms. A Subject record represents an individual participating in a Study. This object is where Vault tracks the Subject's status as they progress through the Study. A Subject's Casebook object record contains all other information, including visits and form data, for that Subject in the given Study.

Retrieve Subjects

Request - By Study Context

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects?study_name=ABCP-2022-01_DEV1' \
-H 'Authorization: {SESSION_ID}'

Response - By Study Context

{
   "responseStatus": "SUCCESS",
   "responseDetails": {
       "limit": 1000,
       "offset": 0,
       "size": 7,
       "total": 7
   },
   "subjects": [
       {
           "id": "OPP00000000I001",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "101",           
           "subject": "SCR-0006",
           "status": "pre_screen__v",
           "created_date": "2022-02-04T20:11:46Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2022-02-04T20:11:46Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000000I001&tab_name=data_entry__v"           
       },
       {
           "id": "OPP00000000H001",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "101",                      
           "subject": "SCR-0005",
           "status": "pre_screen__v",
           "created_date": "2022-02-04T20:11:32Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2022-02-04T20:11:32Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000000H001&tab_name=data_entry__v"           
       },
       {
           "id": "OPP00000000A001",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "102",
           "subject": "102-001",
           "status": "in_screening__v",
           "created_date": "2021-09-21T23:12:55Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2021-09-21T23:13:42Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000000A001&tab_name=data_entry__v"           
       },
       {
           "id": "OPP000000009002",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "101",
           "subject": "101-003",
           "status": "in_screening__v",
           "created_date": "2021-09-21T23:08:00Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2021-09-21T23:12:44Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000009002&tab_name=data_entry__v"           
       },
       {
           "id": "OPP000000009001",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "101",
           "subject": "101-002",
           "status": "in_screening__v",
           "created_date": "2021-09-21T23:07:07Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2021-09-21T23:07:50Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000009001&tab_name=data_entry__v"           
       },
       {
           "id": "OPP000000000501",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "101",
           "subject": "101-001",
           "status": "enrolled__v",
           "created_date": "2021-02-12T18:51:53Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2021-03-11T20:23:56Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000000501&tab_name=data_entry__v"           
       },
       {
           "id": "OPP000000000502",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "103",
           "subject": "103-001",
           "status": "enrolled__v",
           "created_date": "2020-02-12T18:51:53Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2022-08-11T20:23:56Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000000502&tab_name=data_entry__v"           
       }       
   ]
}

Request - By IDs (two specific)

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects?study_name=ABCP-2022-01_DEV1&id=OPP00000000I001,OPP00000000H001' \
-H 'Authorization: {SESSION_ID}'

Response - By IDs (two specific)

{
   "responseStatus": "SUCCESS",
   "responseDetails": {
       "limit": 1000,
       "offset": 0,
       "size": 2,
       "total": 2
   },
   "subjects": [
       {
           "id": "OPP00000000I001",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "101",           
           "subject": "SCR-0006",
           "status": "pre_screen__v",
           "created_date": "2022-02-04T20:11:46Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2022-02-04T20:11:46Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000000I001&tab_name=data_entry__v"
       },
       {
           "id": "OPP00000000H001",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "101",                      
           "subject": "SCR-0005",
           "status": "pre_screen__v",
           "created_date": "2022-02-04T20:11:32Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2022-02-04T20:11:32Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000000H001&tab_name=data_entry__v"                     
       }
   ]
}

Request - By Multiple Sites

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects?study_name=ABCP-2022-01_DEV1&site=102,103' \
-H 'Authorization: {SESSION_ID}'

Response - By Multiple Sites

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 4,
        "total": 4
    },
    "subjects": [
        {
           "id": "OPP00000001U002",
           "study_name": "ABCP-2022-01_DEV1",
           "site": "102",
           "site_name": "Raleigh Hospital",
           "study_country": "United States",
           "subject": "102-001",
           "status": "pre_screen__v",
           "casebook_version": 1,
           "created_date": "2022-07-07T16:40:24Z",
           "created_by": "Eric Emerton",
           "last_modified_date": "2022-07-07T16:40:25Z",
           "casebook_version": 1,           
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000001U002&tab_name=data_entry__v"           
        },
        {
           "id": "OPP00000001I004",
           "study_name": "ABCP-2022-01_DEV1",
           "site": "102",
           "site_name": "Raleigh Hospital",
           "study_country": "United States",
           "subject": "SCR-0001",
           "status": "in_screening__v",
           "casebook_version": 1,
           "created_date": "2022-05-23T18:36:00Z",
           "created_by": "Eric Emerton",
           "screened_date": "2022-01-03",
           "last_modified_date": "2022-07-05T13:04:00Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000001I004&tab_name=data_entry__v"
        },
        {
           "id": "OPP00000001Q003",
           "study_name": "ABCP-2022-01_DEV1",
           "site": "102",
           "site_name": "Raleigh Hospital",
           "study_country": "United States",
           "subject": "SCR-0002",
           "status": "complete__v",
           "casebook_version": 1,
           "created_date": "2022-06-22T20:53:42Z",
           "created_by": "Eric Emerton",
           "initial_consent_date": "2022-06-02",
           "screened_date": "2022-06-01",
           "screen_failed_date": "2022-06-02",
           "enrolled_date": "2022-06-04",
           "randomized_date": "2022-06-03",
           "start_treatment_date": "2022-06-21",
           "end_treatment_date": "2022-06-06",
           "withdrawn_date": "2022-06-05",
           "started_follow_up_date": "2022-06-28",
           "lost_to_follow_up_date": "2022-06-30",
           "end_study_date": "2022-06-07",
           "last_modified_date": "2022-06-23T17:20:06Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000001Q003&tab_name=data_entry__v"
        },
        {
           "id": "OPP000000000502",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "103",
           "subject": "103-001",
           "status": "enrolled__v",
           "created_date": "2022-02-12T18:51:53Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2022-08-11T20:23:56Z",
           "casebook_version": 1,
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000000502&tab_name=data_entry__v"
       }
    ]
}

Request - Where Subjects have IXRS IDs

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects?study_name=ABCP-2022-01_DEV1&site=103' \
-H 'Authorization: {SESSION_ID}'

Response - Where Subjects have IXRS IDs

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "subjects": [
        {
           "id": "OPP000000000502",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "103",
           "subject": "103-001",
           "status": "enrolled__v",
           "created_date": "2022-02-12T18:51:53Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2022-08-11T20:23:56Z",
           "casebook_version": 1,
           "ixrs_id": "1234-ABCDE-456",
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000000502&tab_name=data_entry__v"
       },
       {
           "id": "OPP000000000503",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "103",
           "subject": "103-001",
           "status": "enrolled__v",
           "created_date": "2022-02-12T18:51:53Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2022-08-11T20:23:56Z",
           "casebook_version": 1,
           "ixrs_id": "1234-ABCDE-479",
           "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000000503&tab_name=data_entry__v"
       }
    ]
}

Notes

Used to get the Subjects of a Study
The response returned includes additional dates for milestones of the Subject. These only appear when there is a date value, and are omitted from response when not set. Milestone dates are set by either study design configuration rules, or through the Set Subject Status endpoint.
In addition to the response examples to the right, consider a Study with these Sites - United States (101, 102), Canada (201, 202), United Kingdom (301,302), and filtering examples:

Style	Example	Results / Notes
Study Context	`.../subjects?study_name={..}`	All subjects
Study Context	`.../subjects?study_name={..}&study_country=Canada&site=101`	Site 101 subjects
Study Context	`.../subjects?study_name={..}&site=101`	Site 101 subjects (with/without country, same)
Study Context	`.../subjects?study_name={..}&site=101,102`	Site 101 and Site 102 subjects
Study Context	`.../subjects?study_name={..}&site=101,102,501`	Site 101 and Site 102 subjects (same, 501 does not exist)
Study Context	`.../subjects?study_name={..}&site=501,502`	ERROR - Neither exists, error return (not empty array), that is, no valid sites
Study Context	`.../subjects?study_name={..}&study_country=Canada&site=101,102`	ERROR - Multi site search is not allowed when including a study country, even if both reside at that country
Study Context	`.../subjects?study_name={..}&last_modified_date=2023-07-01T12:00:00Z`	Subjects modified since July 1st, 12:00 UTC
By ID	`.../subjects?study_name={..}&id=OPP00000001V002`	Just the one subject with matching Vault ID, assuming valid
By ID	`.../subjects?study_name={..}&id=OPP00000001V002,OPP00000001V003`	The two subjects, assuming both are valid Vault IDs
By ID	`.../subjects?study_name={..}&id=OPP00000001V077,OPP00000001V088`	Assuming neither exists, an empty JSON Array (not an error)

Endpoint

GET https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects

Required Permissions

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

API Access
View Casebook

Both the CDMS API Read Only and CDMS API Read Write roles grant this permission.

Headers

Name	Description
`Accept`	`application/json` (default)

Query String Parameters (by Study Context)

Name	Description
`study_name`	Name of the Study
`study_country`	Optional Name of the Study Country to filter on. If omitted, Vault returns all Subjects for the given Study.
`site`	Optional Name of the Sites to filter on (comma-separated). If omitted, Vault returns all Subjects for the Study. If multiple is provided, Study Country must by omitted, even if the multiple listed are all from the same Study Country
`last_modified_date`	Optional Filter to only Subjects modified after the specified datetime. Use the format: "yyyy-MM-ddTHH:mm:ssZ". If omitted, Vault retrieves all Subjects for the Study with respect to last modified date.

Query String Parameters (by ID)

Name	Description
`study_name`	Name of the Study
`id`	The Vault internal ID of the Subject, or multiple in a comma-separated list. The `id` value can be found from Retrieve Subjects. This parameter cannot be used in conjunction with Study Country or Site or last modified filters

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

On SUCCESS, Vault returns a list of Subjects meeting your filter criteria. If there are no Subjects meeting your filter criteria, Vault returns an empty array.

Array	Name	Description
`subjects`	`study_name`	Name of the Study
`subjects`	`id`	Vault internal ID for the Subject (will never change, whereas `subject` name might)
`subjects`	`site`	Name of the Site assigned to the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subjects`	`study_country`	Name of the Study Country assigned to the Subject
`subjects`	`subject`	Subject ID (Name) of the Subject
`subjects`	`status`	Subject Status assigned to the Subject. Common statuses include: `pre_screen__v` `in_screening__v` `screen_failure__v` `enrolled__v` `withdrawn__v` `complete__v` `randomized__v` `end_of_treatment__v` `consented__v` `started_treatment__v` `started_follow_up__v` `lost_to_follow_up__v`
`subjects`	`created_date`	The datetime that the Subject was first created
`subjects`	`created_by`	Name (Firstname Lastname) of the User who created the Subject
`subjects`	`initial_consent_date`*	Initial Consent Date for the Subject (only present when a non-empty value)
`subjects`	`screened_date`*	Screened Date for the Subject (only present when a non-empty value)
`subjects`	`screen_failed_date`*	Screen Failed Date for the Subject (only present when a non-empty value)
`subjects`	`enrolled_date`*	Enrolled Date for the Subject (only present when a non-empty value)
`subjects`	`randomized_date`*	Randomized Date for the Subject (only present when a non-empty value)
`subjects`	`start_treatment_date`*	Start Treatment Date for the Subject (only present when a non-empty value)
`subjects`	`end_treatment_date`*	End Treatment Date for the Subject (only present when a non-empty value)
`subjects`	`withdrawn_date`*	Withdrawn Date for the Subject (only present when a non-empty value)
`subjects`	`started_follow_up_date`*	Started Follow Up Date for the Subject (only present when a non-empty value)
`subjects`	`lost_to_follow_up_date`*	Lost to Follow Up Date for the Subject (only present when a non-empty value)
`subjects`	`end_study_date`*	End Study Date for the Subject (only present when a non-empty value)
`subjects`	`last_modified_date`	The datetime that the Subject was last updated
`subjects`	`casebook_version`	The study design casebook version of the Subject, currently
`subjects`	`ixrs_id`	An external ID, typically from IXRS/IRT upstream system. The value would have been set at creation of the Subject (only present when a non-empty value)
`subjects`	`cdms_url`	Relative URL to the Subject, at the Data Entry tab

Create Subjects (Casebooks)

Request - Two subjects created at once

curl -X POST  https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "subjects": [
        {
            "study_country": "United States"
            "site": "101"            
        },
        {
            "study_country": "United States",
            "site": "102"            
        }
    ]
}'

Response - Two subjects created at once

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0003",
            "id": "OPP00000001V002",
            "ixrs_id": "",
            "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000001V002&tab_name=data_entry__v"
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "102",
            "subject": "SCR-0004",
            "id": "OPP00000001V003",
            "ixrs_id": "",
            "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000001V003&tab_name=data_entry__v"            
        }
    ]
}

Request - Two subjects attempted, with specific numbering, one fails

curl -X POST  https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "subjects": [
        {
            "study_country": "United States"
            "site": "101" ,
            "subject": "101-001"
        },
        {
            "study_country": "Belgium",
            "site": "103" ,
            "subject": "103-001"
        }
    ]
}'

Response - Two subjects attempted, with specific numbering, one fails

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States"
            "site": "101",
            "subject": "101-001",
            "id": "OPP00000001V005",
            "ixrs_id": "",
            "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000001V005&tab_name=data_entry__v"                        
        },
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Study Country] with name [Belgium] not found"
            "study_country": "Belgium"
            "site": "103",
            "subject": "103-001"            
        }
    ]
}

Request - Two subjects, with IXRS IDs

curl -X POST  https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "subjects": [
        {
            "study_country": "United States"
            "site": "101" ,
            "subject": "101-001",
            "ixrs_id": "ABC-123123-56"
        },
        {
            "study_country": "Belgium",
            "site": "103" ,
            "subject": "103-001",
            "ixrs_id": "ABC-123123-78"
        }
    ]
}'

Response - Two subjects, with IXRS IDs

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States"
            "site": "101",
            "subject": "101-001",
            "id": "OPP00000001V005",
            "ixrs_id": "ABC-123123-56",
            "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000001V005&tab_name=data_entry__v"                        
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States"
            "site": "101",
            "subject": "101-001",
            "id": "OPP00000001V006",
            "ixrs_id": "ABC-123123-78",
            "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP00000001V006&tab_name=data_entry__v"                        
        }
    ]
}

Notes

Used to add a Subject (also known as Casebook) into the Study.
The subject parameter is optional. When omitted, the next auto screening number is assigned, which follows the pattern SCR-0001, SCR-0002, SCR-0003 (although configurable) within each Site.
Vault also creates the first Event Group for the Subject and the first Event (visit) within that group. The action does not set any Event dates.
To set the Event's date, you must use Set Event Date. Learn more about Casebooks in Vault CDMS Help.
The limit for actions in one request is 100.

The style of Subject numbering (e.g. 101-001, 1st subject at site 101) is defined within each study design. If your study is using the API to create Subjects with specific Subject numbers/identifiers, then only the external__v or manual__v study setting can be used.

Endpoint

POST https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects

Required Permissions

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

API Access
Add Casebook
View Casebook

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study to contain the Subject/Casebook (`study__v.name__v`)
`study_country`	`subjects`	Name of the Study Country for the site of Subject/Casebook
`site`	`subjects`	Name of the Site for the Subject/Casebook. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`subjects`	Optional The Subject ID (`subject__v.name__v`) on create of the Subject. If you don’t include a subject, Vault creates a screening number for the Subject. (e.g. SCR-000X, depending on study design).
`ixrs_id`	`subjects`	Optional The value in an IRT/IXRS system who adds the Subject, i.e. the ID it identifies the Subject with.

Set Subject Status

Request

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects/actions/setstatus' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "subjects": [
        {
            "study_country": "United States",
            "site": "101",
            "subject": "101-0010",
            "subject_status": "randomized__v",
            "date": "2020-03-03"
        }
    ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States"
            "site": "101",
            "subject": "101-0010",
            "subject_status": "randomized__v"
        }
    ]
}

Notes

Used to set the status of a Study
Often done as a 2nd step, right after adding of a new Subject to advance past Pre-Screening default status to Screening, Enrolled, or other.
That subject_status value must be the API name, not the label (e.g. enrolled__v).
The set of a milestone date, i.e., the date the Subject took on that status is required.
The action is the equivalent of a Studio design rule, which can also set the milestone date and change status for the Subject.
Refer to the table below for order of precedence of Subject statuses, when setting or removing.
Currently, the set of multiple Subjects, or multiple statuses for one Subject (in one API call) is not allowed. The format used is still of batch style like other endpoints, but multiple in one request is future release.
A Subject does not have to go through each Subject status. Study design requirements dictate which statuses a Subject transitions through.
If the Subject is already in the Status specified in your request, Vault does not change the Status or update the status's milestone date.
If the Subject's current status is more advanced than the one specified in your request, Vault only moves the Subject into the lower status if that status is the previous in precedence. Otherwise, the request fails.
You can undo any changes made with this API using Unset Subject Status.
The various status / milestone dates are found in Retrieve Subjects.

Order	Subject Status	API Value	Return in Retrieve Subjects
1	Pre Screen
2	Consented	`consented__v`	`initial_consent_date`
3	In Screening	`in_screening__v`	`screened_date`
4	Screen Failure	`screen_failure__v`	`screen_failed_date`
5	Enrolled	`enrolled__v`	`enrolled_date`
6	Randomized	`randomized__v`	`randomized_date`
7	Started Treatment	`started_treatment__v`	`started_treatment_date`
8	End Of Treatment	`end_of_treatment__v`	`end_of_treatment_date`
9	Withdrawn	`withdrawn__v`	`withdrawn_date`
10	Started Follow Up	`started_follow_up__v`	`started_follow_up_date`
11	Lost to Follow Up	`lost_to_follow_up__v`	`lost_to_follow_up_date`
12	Complete	`complete__v`	`end_of_study_date`

Endpoint

POST https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects/actions/setstatus

Required Permissions

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

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`subjects`	Name of the Study Country of the Subject
`site`	`subjects`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`subjects`	Name of the Subject (ID / number)
`subject_status`	`subjects`	The status to set for the Subject. As of this release only one entry in the `subjects` array is allowed per request.
`date`	`subjects`	The date to set for the status milestone for the Subject. Use yyyy-MM-dd format for the status milestone date.

Unset Subject Status

Request

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects/actions/unsetstatus' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "subjects": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "101-0010",
            "subject_status": "enrolled__v"
        }
    ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States"
            "site": "101",
            "subject": "101-0010",
            "subject_status": "in_screening__v"
        }
    ]
}

Notes

Used to unset the status of a Subject.
The action will also remove the milestone date previously set.
As an example, suppose a Subject has progressed In Screening -> Enrolled -> Randomized. If the endpoint is used to unset Enrolled, this results in BOTH the Enrolled and Randomized milestone dates being removed.
See the section above for an order of precedence of Subject statuses.
Currently, the unset of multiple Subjects, or multiple for one Subject (in one API call) is not allowed. The format used is still of batch style like other endpoints, but multiple in one request is future release.
The response includes the Subject status that was in the request body, not the current status of the Subject after the action.

Endpoint

POST https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects/actions/unsetstatus

Required Permissions

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

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`subjects`	Name of the Study Country of the Subject
`site`	`subjects`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`subjects`	Name of the Subject (ID / number)
`subject_status`	`subjects`	The status to unset for the Subject. As of this release only one entry in the `subjects` array is allowed per request. The Subject will remain in the highest possible status. See the list above.

Update Subject

Request - Set new subject number

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects/actions/update' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "subjects": [
            {
                "study_country": "United States",
                "site": "101",               
                "subject": "101-002",
                "subject_new": "101-005"
            }
        ]
}'

Response - Set new subject number

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPP000000000501",
            "study_country": "United States",
            "site": "101",
            "subject": "101-002",
            "subject_new": "101-005",
            "ixrs_id": "234-23_ABC",
            "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000000501&tab_name=data_entry__v"
        }
    ]
}

Request - Update an IXRS id

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects/actions/update' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "subjects": [
            {                 
                "study_country": "United States",
                "site": "101",               
                "subject": "101-002",
                "ixrs_id": "234-23_ABC_v2"
            }
        ]
}'

Response - Update an IXRS id

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPP000000000501",
            "study_country": "United States",
            "site": "101",
            "subject": "101-002",
            "subject_new": null,
            "ixrs_id": "234-23_ABC_v2",
            "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000000501&tab_name=data_entry__v"
        }
    ]
}

Notes

Used to update the Subject number and/or IXRS id value.
This endpoint uses the Study context (Study Country / Site / Subject) for identification.

Endpoint

POST https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects/actions/update

Required Permissions

The following permissions are required to use the Update Subject API:

API Access
View Casebook
Create Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`subjects`	Name of the Study Country of the Subject
`site`	`subjects`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`subjects`	Name of the Subject (ID / number) now
`subject_new`	`subjects`	Optional Name of the Subject (ID / number) to change to
`ixrs_id`	`subjects`	Optional IXRS id value to update to

Update Subject by ID

Request - Set new subject number

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects/actions/updatebyid' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "subjects": [
            {
                "id": "OPP000000000501",
                "subject_new": "101-005"                
            }
        ]
}'

Response - Set new subject number

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPP000000000501",
            "subject_new": "101-005",
            "ixrs_id": "234-23_ABC",
            "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000000501&tab_name=data_entry__v"
        }
    ]
}

Request - Update an IXRS id

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects/actions/updatebyid' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "subjects": [
            {                 
                "id": "OPP000000000501",
                "ixrs_id": "234-23_ABC_v2"
            }
        ]
}'

Response - Update an IXRS id

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPP000000000501",
            "subject_new": null,
            "ixrs_id": "234-23_ABC_v2",
            "cdms_url": "/ui/#app/page/object-redirect?object_type=subject__v&object_id=114107_OPP000000000501&tab_name=data_entry__v"
        }
    ]
}

Notes

Used to update the Subject number and/or IXRS id value.
This endpoint uses the internal Vault id for identification, which can be found using Retrieve Subjects

Endpoint

POST https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects/actions/updatebyid

Required Permissions

The following permissions are required to use the Update Subject by ID API:

API Access
View Casebook
Create Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`id`	`subjects`	ID of the Subject
`subject_new`	`subjects`	Optional Name of the Subject (ID / number) to change to
`ixrs_id`	`subjects`	Optional IXRS id value to update to

Event Groups

Vault CDMS groups related Events - oftern referred to as visits - together in Event Groups. The group can contain one Event (e.g. unscheduled visit, screening visit), or many (e.g. treatment period). An Event Group can also repeat (e.g. cycles for a Study).

Create Event Groups

Request - Create Scheduled Event Group

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/eventgroups \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "ABCP-2022-01_DEV1",
    "eventgroups": [
      {
        "study_country": "United States",
        "site": "101",        
        "subject": "101-001",
        "eventgroup_name": "main_visits"
      }
    ]
  }'

Response - Create Scheduled Event Group

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
        {
            "responseStatus": "SUCCESS",                    
                "study_country": "United States",
                "site": "101",
                "subject": "101-001",                    
                "eventgroup_name": "main_visits"
        }
    ]
}

Request - Create Unscheduled Event Group (requires a date)

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/eventgroups \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "ABCP-2022-01_DEV1",
    "eventgroups": [
      {
        "study_country": "United States"
        "site": "101",
        "subject": "101-001",
        "eventgroup_name": "unscheduled_treatment_visits",
        "date": "2022-03-03"
      }
    ]
  }'

Response - Create Unscheduled Event Group (requires a date)

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
        {
            "responseStatus": "SUCCESS",                    
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",                    
            "eventgroup_name": "unscheduled_treatment_visits",
            "date": "2022-03-03",
            "externally_owned_date": true
        }
     ]
}

Notes

Used to add an Event Group for a Subject in the Study.
This action will add the 'next' group, in sequence if the Event Group repeats. Example - for a repeating Event Group with two existing, the action will add another with sequence = 3.
Use the Upsert Event Groups (PUT, next section), for conditional add at a specific sequence. Example - for a repeating Event Group with three existing, the attempt to add sequence = 3 will take no action.
For Event Group types NOT Unscheduled, the date is not set in this API call. Instead, Set Event Date or Update Event are used.
The limit for actions in one request is 100.

Use Case	Description
Integration Only	Add of an area for integration data, that only the integration should control (not an end user).
Unscheduled	Unscheduled Event, which requires a date (format: yyyy-MM-dd) for the action. `externally_owned_date` = `true` will be set as a property on the date.
Cycles	These repeating Event Groups contain the same collection of Events and Forms for each sequence (repetition) of the Event Group, e.g. Day 1, Day 8, Day 15 visits (each cycle). Each new Event Group may have a customized label, such as Cycle 1, Cycle 2, Cycle 3, and so on.

Endpoint

POST https://my-vault.veevavault.com/api/v24.1/app/cdm/eventgroups

Required Permissions

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

API Access View Casebook Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`eventgroups`	Name of the Study Country of the Subject
`site`	`eventgroups`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`eventgroups`	Name of the Subject (ID / number) where the Event Group is added
`eventgroup_name`	`eventgroups`	Study design name of the Event Group
`date`	`eventgroups`	Optional Date for the Event of the Event Group. Use "yyyy-mm-dd" format. This is only applicable to unscheduled type Event Groups. If omitted and an unscheduled Event Group, Vault sets the date to the current date.

Upsert Event Groups

Request - Attempt when Event does not exist

curl -X PUT https://my-vault.veevavault.com/api/v24.1/app/cdm/eventgroups \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "ABCP-2022-01_DEV1",
    "eventgroups": [
      {
        "study_country": "United States",
        "site": "101",        
        "subject": "101-001",
        "eventgroup_name": "unscheduled_treatment_visits",
        "eventgroup_sequence": 1,
        "date": "2022-03-03"        
      }
    ]
  }'

Response - Attempt when Event does not exist

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
      {
          "responseStatus": "SUCCESS:CREATED",
          "study_country": "United States",
          "site": "101",          
          "subject": "101-001",
          "eventgroup_name": "unscheduled_treatment_visits",
          "eventgroup_sequence": 1,
          "date": "2022-03-03",
          "externally_owned_date": true          
      }
   ]
}

Request - Attempt to create sequence 2 and 3, with 2 already existing

curl -X PUT https://my-vault.veevavault.com/api/v24.1/app/cdm/eventgroups \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "ABCP-2022-01_DEV1",
    "eventgroups": [
      {
        "study_country": "United States",
        "site": "101",
        "subject": "101-001",
        "eventgroup_name": "unscheduled_treatment_visits",
        "eventgroup_sequence": 2,
        "date": "2022-04-03"
      },
      {
        "study_country": "United States",
        "site": "101",
        "subject": "101-001",
        "eventgroup_name": "unscheduled_treatment_visits",
        "eventgroup_sequence": 3,
        "date": "2022-05-03"
      }
    ]
  }'

Response - Attempt to create sequence 2 and 3, with 2 already existing

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
      {
          "responseStatus": "SUCCESS:UPDATED",
          "study_country": "United States",
          "site": "101",          
          "subject": "101-001",
          "eventgroup_name": "unscheduled_treatment_visits",
          "eventgroup_sequence": 2,
          "date": "2022-04-03",
          "externally_owned_date": true          
      },
      {
          "responseStatus": "SUCCESS:CREATED",
          "study_country": "United States",
          "site": "101",          
          "subject": "101-001",
          "eventgroup_name": "unscheduled_treatment_visits",
          "eventgroup_sequence": 3,
          "date": "2022-05-03",
          "externally_owned_date": true          
      }      
   ]
}

Notes

Used to upset an Event Group for a Subject in the Study.
This action will add the 'next' group, in sequence if the Event Group does not yet exist, otherwise will skip the action. Example - for a repeating Event Group with two existing, the action will add another with sequence = 3.
For cases where the Event Group already exists for the given sequence, the response will indicate SUCCESS:UPDATED despite no action having taken place.
The Create Event Groups (POST, previous section) will return an error when used where the Event Group already exists for that Subject at that sequence.
For Event Group types NOT Unscheduled, the date is not set in this API call. Instead, Set Event Date or Update Event are used.
The limit for actions in one request is 100.

Use Case	Description
Integration Only	Add of an area for integration data, that only the integration should control (not an end user).
Unscheduled	Unscheduled Event, which requires a date (format: yyyy-MM-dd) for the action. `externally_owned_date` = `true` will be set as a property on the date.
Cycles	Studies with Cycles - these repeating Event Groups contain the same collection of Events and Forms for each sequence (repetition) of the Event Group, e.g. Day 1, Day 8, Day 15 visits (each cycle). Each new Event Group may have a customized label, such as Cycle 1, Cycle 2, Cycle 3, and so on.

Endpoint

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

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`eventgroups`	Name of the Study Country of the Subject
`site`	`eventgroups`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`eventgroups`	Name of the Subject (ID / number) where the Event Group is added
`eventgroup_name`	`eventgroups`	Study design name of the Event Group
`eventgroup_sequence`	`eventgroups`	Sequence of the Event Group that should be added (if does not exist), otherwise skipped
`date`	`eventgroups`	Optional Date for the Event Group. Use "yyyy-mm-dd" format. This is only applicable to unscheduled type Event Groups. If omitted and an unscheduled Event Group, Vault sets the date to the current date.

Events

Vault CDMS tracks visits as an Event. Each Event contains the Forms collected during that visit. The parent container of an Event is an Event Group. When an Event repeats, it is because the Event Group it resides within repeats. The sequence number in the hierarchy for a repeating Event is at the Event Group level.

Retrieve Events / Forms

Request

curl -L -X GET 'https://myvault.veevavault.com/api/v24.1/app/cdm/events?study_name=ABCP-2022-01_DEV1&study_country=United%20States&site=0101&subject=0101-0003' \
-H 'Authorization: [SESSION_ID]' \
-H 'Content-Type: application/json'

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 5,
        "total": 5
    },
    "events": [
        {
            "id": "OPS00000001M006",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening_visit",
            "event_sequence": 1,
            "locked": false,
            "frozen": false,
            "event_date": "2020-02-03",
            "externally_owned_date": true,
            "event_did_not_occur": false,
            "method": "on_site_visit__v",
            "externally_owned_method": false, 
            "forms": [
                {
                    "id": "OPT00000001M002",
                    "form_name": "demographics",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "locked": false,
                    "frozen": false,
                    "first_submit_date": "2023-07-11T17:38:15Z",     
                    "last_submit_date": "2023-07-11T17:38:15Z",                     
                    "intentionally_left_blank": false
                },
                {
                    "id": "OPT00000001M003",
                    "form_name": "exclusion_criteria",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "locked": false,
                    "frozen": false,
                    "first_submit_date": "2023-07-11T17:38:15Z",     
                    "last_submit_date": "2023-07-14T12:11:33Z",                     
                    "intentionally_left_blank": false
                },
                {
                    "id": "OPT00000001M004",
                    "form_name": "inclusion_criteria",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "first_submit_date": "2023-08-25T15:22:33Z",     
                    "last_submit_date": "2023-08-25T15:22:33Z",     
                    "locked": false,
                    "frozen": false,
                    "intentionally_left_blank": true,
                    "intentionally_left_blank_reason": "Information not available"
                }
            ]
        },
        {
            "id": "OPS00000001M009",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "re_screen",
            "eventgroup_sequence": 1,
            "event_name": "baseline_visit",
            "event_sequence": 1,
            "locked": false,
            "frozen": false,
            "event_date": "",
            "externally_owned_date": false,
            "event_did_not_occur": true,
            "event_did_not_occur_reason": "Subject passed screening initially",
            "method": null,
            "externally_owned_method": false,
            "forms": []
        },
        {
            "id": "OPS00000001M011",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "enrollment",
            "eventgroup_sequence": 1,
            "event_name": "enrollment_visit",
            "event_sequence": 1,
            "locked": false,
            "frozen": false,
            "event_date": "2020-02-07",
            "externally_owned_date": false,            
            "event_did_not_occur": false,
            "method": "on_site_visit__v",
            "externally_owned_method": true,             
            "forms": [
                {
                    "id": "OPT00000001M007",
                    "form_name": "randomization",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "locked": false,
                    "frozen": false,
                    "first_submit_date": "2023-08-29T15:22:33Z",     
                    "last_submit_date": "2023-08-29T15:22:33Z",                         
                    "intentionally_left_blank": false
                }
            ]
        },
        {
            "id": "OPS00000001M008",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "treatment_visit",
            "eventgroup_sequence": 1,
            "event_name": "treatment_visit",
            "event_sequence": 1,
            "locked": false,
            "frozen": false,
            "event_date": "",
            "externally_owned_date": false,            
            "event_did_not_occur": false,
            "method": null,
            "externally_owned_method": false,            
            "forms": []
        },        
        {
            "id": "OPS00000001M007",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "common_forms",
            "eventgroup_sequence": 1,
            "event_name": "common_forms",
            "event_sequence": 1,
            "locked": false,
            "frozen": false,
            "event_date": "",
            "externally_owned_date": false,            
            "event_did_not_occur": false,
            "method": null,
            "externally_owned_method": false,
            "forms": []
        }        
    ]
}

Notes

Retrieve a list of Events, and the Forms within, for a specific Subject. At current release, request is limited to one Subject. Filtering is available down to the Event level. For retrieval of more than one Subject (or many Subjects), see the various export options at the Job Summary / Types section.
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.
Event method is a property of Events that depends on the Study design, both whether the Event uses methods and which values are valid at that Event.
The return array forms within each Event can be empty for several reasons:
- The Event was specifically set as Did Not Occur by a site user, with reason
- The Event is still in planned state, i.e., no Event date is yet set.
- The Event is of type log, and the Forms within it are all part of Study rules, none of which have evaluated as true for the Subject yet.

Endpoint

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

Required Permissions

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

API Access
View Casebook

The CDMS API Read Write and CDMS API Read Only roles grant these permissions.

Headers

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

Query String Parameters

Name	Description
`study_name`	Name of the Study
`study_country`	Name of the Study Country for the site of the Subject
`site`	Name of the Site for the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	Name (ID/number) of the Subject
`eventgroup_name`	Optional Study design name for a specific Event Group to filter the return on
`eventgroup_sequence`	Optional Specific sequence to filter the return on
`event_name`	Optional Study design name for a specific Event to filter the return on

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

On SUCCESS, Vault returns a list of Events and Forms within for a single Subject. Details of the response:

Array	Name	Description
`events`	`id`	Vault internal ID for the Event (will never change)
`events`	`study_country`	Name of the Study Country for the site of the Subject
`events`	`site`	Name of the Site for the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`events`	`subject`	Name (ID/number) of the Subject
`events`	`eventgroup_name`	Study design name for the Event Group
`events`	`eventgroup_sequence`	Sequence of the Event Group of the Event. If its a repeating Event Group, the value increments for each instance, starting at "1", then "2", and so on. If the Event Group isn't repeating, Vault returns "1".
`events`	`event_name`	Study design name for a the Event
`events`	`event_sequence`	Currently, always a 1. If the Event within a repeating Event Group the sequence increments at the `evengroup_sequence` level
`events`	`event_date`	Event date of the Event. yyyy-MM-dd format is returned.
`events`	`externally_owned_date`	Whether the date is owned by an external system, i.e. read only to the site users.
`events`	`event_did_not_occur`	Whether the event has been marked as not having occurred by a site user. (true/false)
`events`	`event_did_not_occur_reason`	Only when `event_did_not_occur` is true, otherwise this is omitted.
`events`	`method`	The method of the event/visit, e.g. `on_site_visit__v`. Methods are configured at specific Events and with specific choices at those Events. Consult the Study Design for when/if they apply at any of the Events for the Study
`events`	`externally_owned_method`	Whether the visit method is owned by an external system, i.e. read only to the site users.
`events/forms`	`id`	Vault internal ID for the Form (will never change)
`events/forms`	`form_name`	Study design name for a Form in the Event (entry per form)
`events/forms`	`form_sequence`	If its a repeating Form, the value increments for each instance, starting at "1", then "2", and so on. If the Form isn't repeating, Vault returns "1".
`events/forms`	`form_status`	The status (picklist name) of that form (e.g. blank__v, submitted__v, etc. See the table below for possible form statuses.
`events/forms`	`locked`	Whether the form is locked (true/false). Locked Forms cannot be updated, nor the queries on them
`events/forms`	`frozen`	Whether the form is locked (true/false). Frozen Forms cannot be updated (data wise), queries can be updated / added.
`events/forms`	`first_submit_date`	The first time the form was submitted.
`events/forms`	`last_submit_date`	The most recent time the form was submitted.
`events/forms`	`intentionally_left_blank`	Whether the Form has been marked intentionally left blank (ILB) by a site user. (true/false)
`events/forms`	`intentionally_left_blank_reason`	When `intentionally_left_blank` is true for the Form, the reason. Otherwise, omitted.

Form Statuses

Status	API Value	Notes
Blank	`blank__v`	The form is not yet visited (no data points / items), or is visited but all fields are their initial blank status. The form can also take on this status after a reset action
In Progress	`in_progress__v`	At least one data point (item) on the form has its first value.
Submitted	`submitted__v`	The form is in submitted/completed state. No updates (UI or API) can occur until the form is opened for edit. NOTE: A form can be in submitted status and be additionally marked Intentionally Left Blank. (i.e., reasons for not having the data)
In Progress Post Submit	`in_progress_post_submit__v`	Like `in_progress__v`, but the form has been submitted (then reopened) at least once.

Create Events

Request - Create two events, different subjects

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/events \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "events": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "EG.RANDOMIZATION",
            "event_name": "Subject.Information"
        },
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-002",
            "eventgroup_name": "EG.SCREENING",
            "event_name": "Demographics"
        }
    ]
}

Response - Create two events, different subjects

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "EG.RANDOMIZATION",
            "eventgroup_sequence": 1,
            "event_name": "Subject.Enrollment",
            "event_sequence": 1
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",            
            "subject": "101-002",
            "eventgroup_name": "EG.SCREENING",
            "eventgroup_sequence": 1,
            "event_name": "Subject.ScreeningVisit",
            "event_sequence": 1
        }
    ]
}

Request - Create event inside a repeating event group

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/events \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "events": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "EG.CYCLE_EVENTS",
            "eventgroup_sequence": 3,
            "event_name": "evDAY15"
        }
    ]
}

Response - Create event inside a repeating event group

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "EG.CYCLE_EVENTS",
            "eventgroup_sequence": 3,
            "event_name": "evDAY15"
            "event_sequence": 1
        }
    ]
}

Notes

Used to create an Event inside an existing Event Group,typically for a dynamic or ‘integration only’) reasons.
The action does not add a non-existent Event Group where the Event otherwise is to reside. See Create Event Groups / Upsert Event Groups for the addition on a non-existent Event Group prior to creating the Event.
The action does not set the Event date or visit method. Instead, Set Event Date or Update Event are used.
The limit for actions in one request is 100.

Endpoint

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

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`events`	Name of the Study Country of the Subject
`site`	`events`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`events`	Name of the Subject (ID / number) where the Event is added
`eventgroup_name`	`events`	Study design name of the Event Group
`eventgroup_sequence`	`events`	Optional If omitted, 1 is assumed. Use this parameter to specify an Event of a repeating Event Group
`event_name`	`events`	Study design name of the Event to add

Set Event Date

Request - Set one event date

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/events/actions/setdate \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "events": [
          {
          "study_country": "United States",
          "site": "101",          
          "subject": "101-001",
          "eventgroup_name": "Screening-Visit",
          "event_name": "Screening-Visit",
          "date": "2022-05-21"
          }
      ]
    }'

Response - Set one event date

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPS00000001M006",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "eventgroup_name": "Screening-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Screening-Visit",
            "event_sequence": 1,
            "date": "2022-05-21",
            "externally_owned_date": true,
            "allow_planneddate_override": false,
            "change_reason": "Action performed via the API"                        
        }
    ]
}

Request - Change one event date

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/events/actions/setdate \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "events": [
          {
          "study_country": "United States",
          "site": "101",          
          "subject": "101-001",
          "eventgroup_name": "Screening-Visit",
          "event_name": "Screening-Visit",
          "date": "2022-05-22",
          "change_reason": "Updated by integration - my reason"
          }
      ]
    }'

Response - Change one event date

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPS00000001M006",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0002",
            "eventgroup_name": "Screening-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Screening-Visit",
            "event_sequence": 1,
            "date": "2022-05-22",
            "externally_owned_date": true,
            "allow_planneddate_override": false,                        
            "change_reason": "Updated by integration - my reason"
        }
    ]
}

Notes

Used to set an Event date to an existing Event.
Vault CDMS use an Event date above all Forms within it, i.e., the date applies to each Form. This is as opposed to having visit/event dates inside each Form of an Event. The Event date will be automatically available in data exports.
The action does not add the Event or Event Group the Event otherwise resides
Date format is yyyy-MM-dd
The endpoint call (as POST) is used for both setting a date when no value currently exists, plus updating an existing value. (PUT is not used for update)
For an Unscheduled type Event Group, the date of the first Event of the group is set at the time of create / upsert of the Event Group.
For updating of an Event method see the next section - Update Event - where both the date and method can be updated.
The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`events`	Name of the Study Country of the Subject
`site`	`events`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`events`	Name of the Subject (ID / number)
`eventgroup_name`	`events`	Study design name of the Event Group
`eventgroup_sequence`	`events`	Optional If omitted, 1 is assumed. Use this parameter to specify an Event of a repeating Event Group
`event_name`	`events`	Study design name of the Event to add.
`date`	`events`	The Event date to set, using yyyy-MM-dd format
`change_reason`	`events`	Optional The reason for change of an Event's date, where there is already a value. For example, "Date updated by remote system". When not provided and a reason is required, the system will use a default reason of `Action performed via the API`
`allow_planneddate_override`	`events`	Optional Set this to true to bypass checking on the Event planned schedule (window/range). Otherwise, an attempt with date outside the planned range will return an error. When omitted, false is assumed.
`externally_owned_date`	`events`	Optional When omitted true is used, i.e. the site user cannot then further edit the date. Pass a false to re-enable the ability for a user to edit a previously read only Event date.

Update Event

Request - Update one event date (no method)

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/events/actions/update \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "events": [
          {
          "study_country": "United States",
          "site": "101",          
          "subject": "101-001",
          "eventgroup_name": "Screening-Visit",
          "event_name": "Screening-Visit",
          "date": "2023-12-21"
          }
      ]
    }'

Response - Update one event date (no method)

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPS00000001M006",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "eventgroup_name": "Screening-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Screening-Visit",
            "event_sequence": 1,
            "date": "2023-12-21",
            "method": null,
            "allow_planneddate_override": false,
            "externally_owned_date": true,            
            "externally_owned_method": false
            "change_reason": "Action performed via the API"                        
        }
    ]
}

Request - Update date and method

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/events/actions/update \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "events": [
          {
          "study_country": "United States",
          "site": "101",          
          "subject": "101-001",
          "eventgroup_name": "Screening-Visit",
          "event_name": "Screening-Visit",
          "date": "2023-12-22",
          "method": "on_site_visit__v",
          "change_reason": "Updated by integration - my reason"
          }
      ]
    }'

Response - Update date and method

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPS00000001M006",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0002",
            "eventgroup_name": "Screening-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Screening-Visit",
            "event_sequence": 1,
            "date": "2023-23-22",
            "method": "on_site_visit__v",
            "allow_planneddate_override": false,
            "externally_owned_date": true,
            "externally_owned_method": true,
            "change_reason": "Updated by integration - my reason"
        }
    ]
}

Notes

Used to set an Event date and optionally set a method to an existing Event.
Vault CDMS uses an Event date above all Forms within it, i.e., the date applies to each Form. This is as opposed to having visit/event dates inside each Form of an Event. The Event date will be automatically available in data exports.
Event method is a property of Events that depends on the Study design, both whether the Event uses methods and which values are valid at that Event.
The action does not add the Event or Event Group the Event otherwise resides
Date format is yyyy-MM-dd
The endpoint call (as POST) is used for both setting a date when no value currently exists, plus updating an existing value. (PUT is not used for update)
For method, updates from no value to a value or existing value to no value are both allowed. This is as opposed to the date, which most always be given, even if the intent is just to update a method. Special situations with method are shown in the table below.
For an Unscheduled type Event Group, the date of the first Event of the group is set at the time of create / upsert of the Event Group.
The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`events`	Name of the Study Country of the Subject
`site`	`events`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`events`	Name of the Subject (ID / number)
`eventgroup_name`	`events`	Study design name of the Event Group
`eventgroup_sequence`	`events`	Optional If omitted, 1 is assumed. Use this parameter to specify an Event of a repeating Event Group
`event_name`	`events`	Study design name of the Event to add.
`date`	`events`	The Event date to set, using yyyy-MM-dd format
`method`	`events`	The method to set, or use *null to unset a previously set value. The value used is dependent on the Study Design, both if allowed at the Event and which values are valid.
`change_reason`	`events`	Optional The reason for change of an Event's date, where there is already a value. For example, "Date updated by remote system". When not provided and a reason is required, the system will use a default reason of `Action performed via the API`
`allow_planneddate_override`	`events`	Optional Set this to true to bypass checking on the Event planned schedule (window/range). Otherwise, an attempt with date outside the planned range will return an error. When omitted, false is assumed.
`externally_owned_date`	`events`	Optional When omitted true is used, i.e. the site user cannot then further edit the date. Pass a false to re-enable the ability for a user to edit a previously read only Event date.
`externally_owned_method`	`events`	Optional When omitted true is used if the update includes setting of a `method`. The site user cannot then further edit the value. Pass a false to re-enable the ability for a user to edit a previously read only method.

Set Event as Did Not Occur

Request - Set two events as did not occur

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/events/actions/didnotoccur \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "events": [
     {
        "study_country": "United States",       
        "site": "101",      
        "subject": "101-001",
        "eventgroup_name": "EG.MAIN",
        "eventgroup_sequence": 1,
        "event_name": "EV.V7",
        "change_reason": "missed visit"
     },
     {
        "study_country": "United States",       
        "site": "101",      
        "subject": "101-001",
        "eventgroup_name": "EG.MAIN",
        "eventgroup_sequence": 1,
        "event_name": "EV.V8",
        "change_reason": "missed visit"
     }     
    ]
}

Response - Set two events as did not occur

{
    "responseStatus": "SUCCESS",
    "events": [
    {
        "responseStatus": "SUCCESS",
        "study_country": "United States",
        "site": "101",            
        "subject": "101-001",
        "eventgroup_name": "EG.MAIN",
        "eventgroup_sequence": 1,
        "event_name": "EV.V7",
        "event_sequence": 1
    },
    {
        "responseStatus": "SUCCESS",
        "study_country": "United States",
        "site": "101",            
        "subject": "101-001",
        "eventgroup_name": "EG.MAIN",
        "eventgroup_sequence": 1,
        "event_name": "EV.V8",
        "event_sequence": 1
    }
    ]
}

Notes

Used to mark an entire Event with status = Did Not Occur (did_not_occur__v)
Change of reason can be any text, although certainly consider being consistent verbiage on API requests.
Example: Subject missed the visit, Subject discontinued from the study, etc.
A reason for this action is required.
The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`events`	Name of the Study Country of the Subject
`site`	`events`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`events`	Name of the Subject (ID / number)
`eventgroup_name`	`events`	Study design name of the Event Group
`eventgroup_sequence`	`events`	Optional If omitted, 1 is assumed. Use this parameter to specify an Event of a repeating Event Group
`event_name`	`events`	Study design name of the Event to add.
`change_reason`	`events`	Optional The specific reason to set when marking the Event as Did Not Occur. For example: "Update by integration, subject missed the event."

Forms

Vault CDMS uses Forms to hold like data. Inside the Form are Item Groups (grouping of fields/controls) and Items (fields for a single data point). An Item Group can repeat inside a single form, as per study design needs. Learn more about data entry into Forms in Vault CDMS Help.

Retrieve Forms / Item Data

Request

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/forms?study_name=ABCP-2022-01_DEV1&site=0101&study_country=United%20States&subject=101-001&eventgroup_name=screening&event_name=screening_visit' \
-H 'Authorization:{SESSION_ID}'

Response


{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 4,
        "total": 4
    },    
    "forms": [
        {
            "id": "OPT00000001M002",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening_visit",
            "event_sequence": 1,
            "event_external_id": "screening_visit",
            "form_name": "demographics",
            "form_sequence": 1,
            "form_status": "submitted__v",
            "locked": false,
            "frozen": false,
            "first_submit_date": "2023-07-11T17:38:15Z",     
            "last_submit_date": "2023-07-14T12:11:33Z", 
            "intentionally_left_blank": false,
            "itemgroups": [
                {
                    "id": "V5C00000000B007",
                    "itemgroup_name": "creation_criteria",
                    "itemgroup_sequence": 1,
                    "itemgroup_external_id": "creation_criteria",
                    "items": [
                        {
                            "id": "V5D00000000B031",
                            "item_name": "subject_date_of_birth",
                            "value": "17-Jun-1978",
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false
                        },
                        {
                            "id": "V5D00000000B032",
                            "item_name": "subject_gender",
                            "value": "F",
                            "intentionally_left_blank": false,
                            "externally_owned": true,
                            "frozen": false,
                            "locked": false
                        },
                        {
                            "id": "V5D00000000B033",
                            "item_name": "subject_initials",
                            "value": "QGT",
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        },
                        {
                            "id": "V5D00000000B034",
                            "item_name": "subject_race",
                            "value": "Caucasian",
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        },
                        {
                            "id": "V5D00000000B035",
                            "item_name": "weight",
                            "value": "150.2",
                            "unit_value": "lbs",
                            "translated_value": "68.129574",
                            "translated_unit_value": "kg",
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        }
                    ]
                }
            ]
        },
        {
            "id": "OPT00000001M003",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "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,
            "first_submit_date": "2023-07-28T12:11:33Z",     
            "last_submit_date": "2023-07-28T12:11:33Z",             
            "intentionally_left_blank": false,
            "itemgroups": [
                {
                    "id": "V5C00000000B008",
                    "itemgroup_name": "exclusion_criteria",
                    "itemgroup_sequence": 1,
                    "itemgroup_externalid": "exclusion_criteria",
                    "items": [
                        {
                            "id": "V5D00000000B017",
                            "item_name": "exclusion_hypersensitivity",
                            "value": "N",
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        },
                        {
                            "id": "V5D00000000B018",
                            "item_name": "exclusion_study_calendar",
                            "value": "N",
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        },
                        {
                            "id": "V5D00000000B019",
                            "item_name": "exclusion_pregnant_or_nursing",
                            "value": "N",
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        },
                        {
                            "id": "V5D00000000B020",
                            "item_name": "exclusion_chronic_medical_condition",
                            "value": "N"
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        }
                    ]
                }
            ]
        },
        {
            "id": "OPT00000001M004",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "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,
            "first_submit_date": "2023-08-02T17:38:15Z",     
            "last_submit_date": "2023-08-02T17:38:15Z",             
            "intentionally_left_blank": false,
            "itemgroups": [
                {
                    "id": "V5C00000000B009",
                    "itemgroup_name": "inclusion_criteria",
                    "itemgroup_sequence": 1,
                    "itemgroup_externalid": "inclusion_criteria",
                    "items": [
                        {
                            "id": "V5D00000000B021",
                            "item_name": "inclusion_negative_pregnancy_test",
                            "value": "Y",
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        },
                        {
                            "id": "V5D00000000B022",
                            "item_name": "inclusion_normal_healthy",
                            "value": "Y",
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        },
                        {
                            "id": "V5D00000000B023",
                            "item_name": "inclusion_age_18",
                            "value": "Y",
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        },
                        {
                            "id": "V5D00000000B024",
                            "item_name": "inclusion_informed_consent",
                            "value": "Y".
                            "intentionally_left_blank": false,
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        }
                    ]
                }
            ]
        },
        {
            "id": "OPT00000001M005",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "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,
            "first_submit_date": "2023-07-11T19:38:15Z",     
            "last_submit_date": "2023-07-11T19:38:33Z",             
            "intentionally_left_blank": true,
            "intentionally_left_blank_reason": "Did not complete",
            "itemgroups": [
                {
                    "id": "V5C00000000B010",
                    "itemgroup_name": "pk_1",
                    "itemgroup_sequence": 1,
                    "itemgroup_externalid": "pk_1",
                    "items": [
                        {
                            "id": "V5D00000000B045",
                            "item_name": "pk_date",
                            "value": null,
                            "intentionally_left_blank": true,
                            "intentionally_left_blank_reason": "Did not complete",
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        },
                        {
                            "id": "V5D00000000B046",
                            "item_name": "pk_result",
                            "value": null,
                            "intentionally_left_blank": true,
                            "intentionally_left_blank_reason": "Did not complete",
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        },
                        {
                            "id": "V5D00000000B047",
                            "item_name": "pk_not_done_reason",
                            "value": null,
                            "intentionally_left_blank": true,
                            "intentionally_left_blank_reason": "Did not complete",
                            "externally_owned": false,
                            "frozen": false,
                            "locked": false                            
                        }
                    ]
                }
            ]
        }        
    ]
}

Notes

Use this API to retrieve existing Forms and their data (Items, Item Groups). Details of the Form status, frozen/locked/ILB are also returned.
Typically used for specific inspection of a Form (with data on it), prior to updating the Form using other endpoints.
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.
The largest scope of the retrieval is one Subject, and one Event of the Subject
For retrieval of more than one Event or many Subjects, see the various export options at the Job Summary / Types section.
The externally_owned property for each item will return true when the Item was set via the API. This prevents updates of the field by the Site users.

Endpoint

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

Required Permissions

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

API Access
View Casebook

The CDMS API Read Only and CDMS API Read Write roles grant these permissions.

Headers

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

Query String Parameters

Name	Description
`study_name`	Name of the Study
`study_country`	Name of the Study Country for the site of the Subject
`site`	Name of the Site for the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	Name (ID/number) of the Subject
`eventgroup_name`	Study design name for an Event Group
`eventgroup_sequence`	Optional Specific sequence to filter the Event Group on. If omitted, 1 is assumed.
`event_name`	Study design name for an Event (of that Event Group)
`form_name`	Optional Study design name of a Form (in the Event) to filter on
`form_sequence`	Optional Specific sequence to filter on, that is, form of a specific sequence. If omitted, 1 is assumed.

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

On SUCCESS, Vault returns a list of Forms within the Subject / Event provided, with the following information:

Array	Name	Description
`forms`	`id`	Vault internal ID for the Form (will never change)
`forms`	`study_country`	Name of the Study Country for the site of the Subject
`forms`	`site`	Name of the Site for the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`forms`	`subject`	Name (ID/number) of the Subject
`forms`	`eventgroup_name`	Study design name for the Event Group
`forms`	`eventgroup_sequence`	Sequence of the Event Group of the Event. If repeating Event Group the value increments starting at 1, 2.... If it does not repeat, then 1 is always returned
`forms`	`event_name`	Study design name for a the Event
`forms`	`event_sequence`	Currently, always a 1. If the Event within a repeating Event Group the sequence increments at the `evengroup_sequence` level
`forms`	`event_date`	Event date of the Event. yyyy-MM-dd format is returned.
`forms`	`form_name`	Study design name for a Form in the Event (entry per form)
`forms`	`form_sequence`	If the Form repeats per study design, these increment starting at 1, 2.... If it does repeat, 1 is always returned.
`forms`	`form_status`	The status (picklist name) of that form (e.g. blank__v, submitted__v, etc. See the table below for possible form statuses.
`forms`	`locked`	Whether the form is locked (true/false). Locked Forms cannot be updated, nor the queries on them
`forms`	`frozen`	Whether the form is locked (true/false). Frozen Forms cannot be updated (data wise), queries can be updated / added.
`forms`	`first_submit_date`	The first time the form was submitted.
`forms`	`last_submit_date`	The most recent time the form was submitted.
`forms`	`intentionally_left_blank`	Whether the Form has been marked intentionally left blank (ILB) by a site user. (true/false)
`forms`	`intentionally_left_blank_reason`	When `intentionally_left_blank` is true for the Form, the reason. Otherwise, omitted.
`forms/itemgroups`	`id`	Vault internal ID for the Item Group (will never change)
`forms/itemgroups`	`itemgroup_name`	Study design name for an Item Group in the Form
`forms/itemgroups`	`itemgroup_sequence`	If the Item Group repeats per study design (within the Form), these increment starting at 1, 2.... If it does repeat, 1 is always returned.
`forms/itemgroups`	`itemgroup_external_id`	Another study design reference/name for the Item Group. This value is usually the same as the name.
`forms/itemgroups/items`	`id`	Vault internal ID for the Item (will never change)
`forms/itemgroups/items`	`item_name`	Study design name for the Item
`forms/itemgroups/items`	`value`	The value for that Item. The value returned will differ by the type of the Item, study design wise (e.g. Date, DateTime, Time, Check Box, Codelist, etc., see the table below)
`forms/itemgroups/items`	`unit_value`	Only applies when the Item type is Unit Codelist. This is the unit selected to pair with the value entered by the end user. If the Item is not a Unit Codelist, this line is omitted.
`forms/itemgroups/items`	`translated_value`	Only applies when the Item type is Unit Codelist. The user value is calculated to the standard unit defined for the Item. If the user selects the standard unit, the value here will be the same as `value`. If the Item is not a Unit Codelist, this line is omitted.
`forms/itemgroups/items`	`translated_unit_value`	Only applies when the Item type is Unit Codelist. The standard unit for the Item, as defined in the study. If the user selects the standard unit, the value here will be the same as `unit_value`. If the Item is not a Unit Codelist, this line is omitted.
`forms/itemgroups/items`	`lab_modifier`	Only applies when the Item type is Unit Codelist, and the Item has a value for Lab Modifier. Example: A lab value is 'Less than 0.7', results in `value`: 1, and the coded value for 'Less than' as setup in the study design. If the Item is not a Unit Codelist or the Lab Modifier is empty / not set, this line is omitted.
`forms/itemgroups/items`	`intentionally_left_blank`	Whether the Item has been marked intentionally left blank (ILB) by a site user. (true/false)
`forms/itemgroups/items`	`intentionally_left_blank_reason`	When `intentionally_left_blank` is true for the Item, the reason. Otherwise, omitted.
`forms/itemgroups/items`	`externally_owned`	Whether the Item is owned by another system. When true, the Item value it not editable by site users, even if the Item Definition is set for editable.
`forms/itemgroups/items`	`frozen`	Whether the Item is currently frozen or not. An Item can be frozen without freezing the entire Form. Frozen does not allow data changes, but does allow Query activity.
`forms/itemgroups/items`	`locked`	Whether the Item is currently locked or not. An Item can be locked without freezing the entire Form. Locked does not allow data changes, nor Query activity.

Form Statuses

Status	API Value	Notes
Blank	`blank__v`	The form is not yet visited (no data points / items), or is visited but all fields are their initial blank status. The form can also take on this status after a reset action
In Progress	`in_progress__v`	At least one data point (item) on the form has its first value.
Submitted	`submitted__v`	The form is in submitted/completed state. No updates (UI or API) can occur until the form is opened for edit. NOTE: A form can be in submitted status and be additionally marked Intentionally Left Blank. (i.e., reasons for not having the data)
In Progress Post Submit	`in_progress_post_submit__v`	Like `in_progress__v`, but the form has been submitted (then reopened) at least once.

Item Value Return by Item Type

Item Type	State/Value	Example Return
Checkbox	(never been checked)	"value": null
Checkbox	Checked	"value": "true"
Checkbox	Unchecked (but at one time checked)	"value": "false"
Codelist	(never been selected)	"value": null
Codelist	Codelist code value	"value": "Y" (e.g. 'Yes' = 'Y' for codelist)
Codelist	Codelist saved non-empty, now empty	"value": null
Date	(never been set)	"value": null
Date	Full date set	"value": "05-Jun-2022" (The study date format is returned, not ISO)
Date	(value set, then later unset)	"value": null
Date	Partial date saved (day and month unknown)	"value": "UN-UNK-2022" (assuming dd-MMM-yyyy study date format)
DateTime	(never been set)	"value": null
DateTime	Full date time set	"value": "05-Jun-2022 13:30" (The study date format is returned, not ISO)
DateTime	(value set, then later unset)	"value": null
DateTime	Partial date saved (day and time unknown)	"value": "UN-Jun-2022 UN:UN" Assuming dd-MMM-yyyy study date format, day and time unknown
URL Field	(never been set)	"value": null
URL Field	Set with a value	"value": "https://www.google.com"
URL Field	(value set, then later unset)	"value": null
Unit Codelist	(never been set)	"value": null, "unit_value": null, "translated_value": null, "translated_unit_value": null
Unit Codelist	Set with value and unit	"value": "150.2", "unit_value": "lbs", "translated_value": "68.129574", "translated_unit_value": "kg"
Unit Codelist	Set with value and unit, plus lab modifier set	"value": "0.001" "unit_value": "mg", "translated_value": "1.0", "translated_unit_value": "g", "lab_modifier": "<"
Unit Codelist	(value set, then later unset)	"value": null, "unit_value": null, "translated_value": null, "translated_unit_value": null
Numeric (Integer or Decimal)	(never been set)	"value": null
Numeric (Integer or Decimal)	Set with a value	"value": "32.45"
Numeric (Integer or Decimal)	(value set, then later unset)	"value": null
Text	(never been set)	"value": null
Text	Set with a value	"value": "This is my text set in the field on screen"
Text	Set with a value - comments field with return character (use \n for breaks)	"value": "Here is my long text with a carriage return \nhere \nand here\nand the end of the text is here"
Text	(value set, then later unset)	"value": null

Combination Update Form Data

Request - Set data with a reopen and submit at the end

curl -L -X POST 'https://my-vault.veevavault.com/api{version}cdm/forms/actions/setdata' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{

    "study_name": "ABC-XYZ-001_DEV1",
    "reopen": true,
    "submit": true,
    "change_reason": "Integration Update",
    "form": {
        "study_country": "United States",
        "site": "001",
        "subject": "101-103",
        "eventgroup_name": "egSCR",
        "eventgroup_sequence": 1,
        "event_name": "evSCR",
        "form_name": "DM",
        "form_sequence": 1,
        "itemgroups": [
            {
                "itemgroup_name": "igBASE_DM",
                "itemgroup_sequence": 1,
                "items": [
                    {
                        "item_name": "BIRTHYR",
                        "value": "1976"
                    },
                    {
                        "item_name": "SEX",
                        "value": "M"
                    }
                ]
            }
        ]
    }
}'

Response - Set data with a reopen and submit at the end

{  
    "responseStatus": "SUCCESS",
    "reopen": true,
    "submit": true,
    "change_reason": "Integration Update",
    "externally_owned": true,      
    "form": {
        "id": "OPT000000000507",
        "form_status": "submitted__v",
        "study_country": "United States",
        "site": "001",
        "subject": "101-103",
        "eventgroup_name": "egSCR",
        "eventgroup_sequence": 1,
        "event_name": "evSCR",
        "event_sequence": 1,
        "form_name": "DM",
        "form_sequence": 1,
        "itemgroups": [
            {
                "responseStatus": "SUCCESS",
                "id": "V54000000006002",               
                "itemgroup_name": "igBASE_DM",
                "itemgroup_sequence": 1,
                "items": [
                    {
                        "responseStatus": "SUCCESS",                        
                        "id": "V55000000006005",
                        "item_name": "BIRTHYR",
                        "value": "1976"
                    },
                    {                      
                        "responseStatus": "SUCCESS",                        
                        "id": "V55000000006006",                      
                        "item_name": "SEX",
                        "value": "M"
                    }
                ]
            }
        ]
    }
}

Request - lacking sequence defaults, change reason (defaults used)

curl -L -X POST 'https://my-vault.veevavault.com/api{version}cdm/forms/actions/setdata' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABC-XYZ-001_DEV1",
    "reopen": true,
    "submit": true,
    "form": {
        "study_country": "United States",
        "site": "001",
        "subject": "101-103",
        "eventgroup_name": "egSCR",
        "event_name": "evSCR",
        "form_name": "DM",
        "itemgroups": [
            {
                "itemgroup_name": "igBASE_DM",
                "items": [
                    {
                        "item_name": "BIRTHYR",
                        "value": "1976"
                    },
                    {
                        "item_name": "SEX",
                        "value": "M"
                    }
                ]
            }
        ]
    }
}

Response - lacking sequence defaults, change reason (defaults used)

{  
    "responseStatus": "SUCCESS",
    "reopen": true,
    "submit": true,
    "change_reason": "Action performed via the API",
    "externally_owned": true, 
    "form": {
        "id": "OPT000000000507",
        "form_status": "submitted__v",
        "study_country": "United States",
        "site": "001",
        "subject": "101-103",
        "eventgroup_name": "egSCR",
        "eventgroup_sequence": 1,
        "event_name": "evSCR",
        "event_sequence": 1,
        "form_name": "DM",
        "form_sequence": 1,
        "itemgroups": [
            {
                "responseStatus": "SUCCESS",
                "id": "V54000000006002",               
                "itemgroup_name": "igBASE_DM",
                "itemgroup_sequence": 1,
                "items": [
                    {
                        "responseStatus": "SUCCESS",                        
                        "id": "V55000000006005",
                        "item_name": "BIRTHYR",
                        "value": "1976"
                    },
                    {                      
                        "responseStatus": "SUCCESS",                        
                        "id": "V55000000006006",                      
                        "item_name": "SEX",
                        "value": "M"
                    }
                ]
            }
        ]
    }
}

Request - Setting values for one of each type of item

curl -L -X POST 'https://my-vault.veevavault.com/api{version}cdm/forms/actions/setdata' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{

    "study_name": "ABC-XYZ-001_DEV1",
    "reopen": true,
    "submit": true,
    "form": {
        "study_country": "United States",
        "site": "101",
        "subject": "101-101",
        "eventgroup_name": "egSCR",
        "eventgroup_sequence": 1,
        "event_name": "evSCR",
        "form_name": "ONE_EACH_FORM",
        "form_sequence": 1,
        "itemgroups": [
            {
                "itemgroup_name": "igONE_EACH_TYPE",
                "itemgroup_sequence": 1,
                "items": [
                  {
                    "item_name": "CB",
                    "value": "true"
                  },
                  {
                    "item_name": "CL",
                    "value": "Y"
                  },
                  {
                    "item_name": "DATEONLY",
                    "value": "2022-06-01"
                  },
                  {
                    "item_name": "DATEONLY_UNKS",
                    "value": "2022-UN-UN"
                  },
                  {
                    "item_name": "DATEANDTIME",
                    "value": "2022-06-01T12:30Z"
                  },
                  {
                    "item_name": "DT_WITH_UNKS",
                    "value": "2022-06-UNTUN:UNZ"
                  },
                  {
                    "item_name": "INTFIELD",
                    "value": "3"
                  },
                  {
                    "item_name": "DECIMAL",
                    "value": "5.2"
                  },
                  {
                    "item_name": "UCLFIELD",
                    "value": "2.1",
                    "unit_value": "double_std"
                  },
                  {
                    "item_name": "URL_FIELD",
                    "value": "https://www.google.com"
                  },
                  {
                    "item_name": "SHORTTXT",
                    "value": "Some text short"
                  },
                  {
                    "item_name": "LONGTXT",
                    "value": "Some text in a long text field \n with a line break in the payload"
                  }
                  {
                    "item_name": "LINK_TO_OTHER_FORM",
                    "value": "", 
                    "item_to_form_link": {
                        "eventgroup_name": "egSCR",
                        "event_name": "evSCR",
                        "form_name": "MH", 
                        "form_sequence": 3
                  }                    
                 }                                
                ]
            }
        ]
    }        
}'

Response - Setting values for one of each type of item

{
    "study_name": "ABC-XYZ-001_DEV1",
    "reopen": true,
    "submit": true,
    "change_reason": "Action performed via the API",
    "externally_owned": true,    
    "form": {
        "id": "OPT000000000507",
        "form_status": "submitted__v",    
        "study_country": "United States",
        "site": "101",
        "subject": "101-101",
        "eventgroup_name": "egSCR",
        "eventgroup_sequence": 1,
        "event_name": "evSCR",
        "form_name": "ONE_EACH_FORM",
        "form_sequence": 1,
        "itemgroups": [
            {
                "responseStatus": "SUCCESS",
                "id": "V54000000006002",                               
                "itemgroup_name": "igONE_EACH_TYPE",
                "itemgroup_sequence": 1,
                "items": [
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "CB",
                    "value": "true"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "CL",
                    "value": "Y"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "DATEONLY",
                    "value": "2022-06-01"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "DATEONLY_UNKS",
                    "value": "2022-UN-UN"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "DATEANDTIME",
                    "value": "2022-06-01T12:30Z"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "DT_WITH_UNKS",
                    "value": "2022-06-UNTUN:UNZ"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "INTFIELD",
                    "value": "3"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "DECIMAL",
                    "value": "5.2"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "UCLFIELD",
                    "value": "2.1",
                    "unit_value": "double_std"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "URL_FIELD",
                    "value": "https://www.google.com"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "SHORTTXT",
                    "value": "Some text short"
                  },
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "LONGTXT",
                    "value": "Some text in a long text field \n with a line break in the payload"
                  }
                  {
                    "responseStatus": "SUCCESS",
                    "id": "VB67000000006002",
                    "item_name": "LINK_TO_OTHER_FORM",
                    "value": "", 
                    "item_to_form_link": {
                        "eventgroup_name": "egSCR",
                        "event_name": "evSCR",
                        "form_name": "MH", 
                        "form_sequence": 3
                  }                    
                 }                                
                ]
            }
        ]
    }  
}

Request - Failure at the item level, and bubble up to higher levels. The form was opened, and left open

curl -L -X POST 'https://my-vault.veevavault.com/api{version}cdm/forms/actions/setdata' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '
{
    "study_name": "ABC-XYZ-001_DEV1",
    "reopen": true,
    "submit": true,
    "form": {
        "study_country": "United States",
        "site": "001",
        "subject": "101-103",
        "eventgroup_name": "egSCR",
        "event_name": "evSCR",
        "form_name": "DM",
        "itemgroups": [
            {
                "itemgroup_name": "igBASE_DM",
                "items": [
                    {
                        "item_name": "BIRTHYR",
                        "value": "1976"
                    },
                    {
                        "item_name": "SEX",
                        "value": "MM"
                    }
                ]
            }
        ]
    }
}

Response - Failure at the item level, and bubble up to higher levels. The form was opened, and left open

{  
    "responseStatus": "FAILURE",
    "errorMessage": "One or more [Item] updates failed",
    "reopen": true,
    "submit": true,
    "change_reason": "Action performed via the API",
    "externally_owned": true,
    "form": {
        "id": "OPT000000000507",
        "form_status": "in_progress_post_submit__v",
        "study_country": "United States",
        "site": "001",
        "subject": "101-103",
        "eventgroup_name": "egSCR",
        "eventgroup_sequence": 1,
        "event_name": "evSCR",
        "event_sequence": 1,
        "form_name": "DM",
        "form_sequence": 1,
        "itemgroups": [
            {
                "responseStatus": "FAILURE",
                "errorMessage": "One or more [Item] updates failed",               
                "itemgroup_name": "igBASE_DM",
                "itemgroup_sequence": 1,
                "items": [                     
                    {
                        "responseStatus": "SUCCESS",                        
                        "id": "V55000000006005",
                        "item_name": "BIRTHYR",
                        "value": "1976"
                    },
                    {                         
                        "responseStatus": "FAILURE",                        
                        "errorMessage": "[Codelist Item Definition] with name [MM] not found",       
                        "item_name": "SEX",
                        "value": "MM"
                    }
                ]
            }
        ]
    }
}

Request - Form is frozen (no actions happen), top level reported

curl -L -X POST 'https://my-vault.veevavault.com/api{version}cdm/forms/actions/setdata' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '
{
    "study_name": "ABC-XYZ-001_DEV1",
    "reopen": true,
    "submit": true,
    "form": {
        "study_country": "United States",
        "site": "001",
        "subject": "101-103",
        "eventgroup_name": "egSCR",
        "event_name": "evSCR",
        "form_name": "DM",
        "itemgroups": [
            {
                "itemgroup_name": "igBASE_DM",
                "items": [
                    {
                        "item_name": "BIRTHYR",
                        "value": "1976"
                    },
                    {
                        "item_name": "SEX",
                        "value": "M"
                    }
                ]
            }
        ]
    }
}

Response - Form is frozen (no actions happen), top level reported

{  
    "responseStatus": "FAILURE",
    "errorMessage": "Form is frozen"
}

This endpoint is a singular call that can perform many actions at once, and conditionally peform actions should the state of the Subject data require such.

The actions that can be performed cover these other endpoints:
- Upsert Forms (i.e. when Form repeats)
- Upsert Item Groups (i.e. when Item Groups in the Form repeat)
- Upsert Form Data (Items) (i.e. the actual setting of values to Items on the Form)
- Edit Submitted Form (i.e. to reopen Form currently in submitted state)
- Submit Form (i.e. submit the Form when finished, which runs study rules defined for the Form)
Actions that do / can happen:
- If the Form is currently submitted, the Form is automatically reopened for edit (default)
- If the Form repeats in the study’s design, and does not yet exist, it will add that Form. Caveat: ‘Skipped’ sequences are invalid. For example, with 3 existing Forms (sequences 1,2,3), an attempt of sequence = 5 results in an error
- All necessary repeating Item Groups are added
- Change reasons are automatically applies if/when necessary when omitted in the request
- Optionally, the final step can be to submit the Form. This is the normal course to close the Form and have configured study rules run.
Actions that do not happen:
- Any level above Form is not performed. For example, the Form lives in an Event which does not yet exist, i.e. the study design dictates dynamic add, user manual add, or other. The API attempt will fail in this case, the combination actions are only from Form down
- If a Form is locked, frozen, or part of locked Subject, locked site, locked study - the Form is not reopened, instead, the first step is a failure. These actions were / are specific human decisions, not to be circumvented via an API attempt.
- IMPORTANT: Rollbacks across multiple actions performed do not take place. For example, suppose the actions involved are Reopen Form, Add new Item Groups, set Item data, and Submit Form (4 in total). Then, suppose the Item updates fail (one or more). The end state is a reopened Form, with new Items groups added, i.e. partial success. A re-attempt of a corrected API request body would very likely pick up where the Form left off, i.e. this example the form is already open, Item Groups are already present, so the last two actions continue as normal.
- More than one Form attempted in the same API request

Endpoint

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

Required Permissions

The following permissions are required to use the Combination Update Form Data API:

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`reopen`		Optional Whether to open the Form, if currently in submitted status. If omitted, true is assumed.
`submit`		Optional Whether to submit the Form, as last step. If omitted, false is assumed.
`change_reason`		Optional When omitted a default reason will be set, if a change reason required.
`externally_owned`		Optional When omitted true is used, i.e. the site user cannot then further edit the value. Pass a false to re-enable the ability for a user to edit a previously read only Item.
`study_country`		Name of the Study Country of the Subject
`site`		Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`		Name of the Subject (ID / number)
`eventgroup_name`		Study design name of the Event Group
`eventgroup_sequence`		Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per study design.
`event_name`		Study design name of the Event
`form_name`		Study design name of the Form
`form_sequence`		Optional Specific form sequence (i.e., repeating form area) to perform on. If omitted, 1 is assumed.
`itemgroup_name`	`items_groups`	Study design name of the Item Group to be added within the Form
`itemgroup_sequence`	`items_groups`	The specific Item Group sequence where the Item resides, Required even if a non-repeating Item Group.
`item_name`	`items_groups/items`	Study design name for the Item
`value`	`items_groups/items`	The value to set. See the table below for notes on Item types and value.
`unit_value`	`items_groups/items`	Required when the Item is a unit codelist type. Omit otherwise. The value must be the unit codelist code, not label.

Setting Data by Item Type

Type	Example	Notes
Checkbox	`"value": "true"`	i.e., checked
Checkbox	`"value": "false"`	i.e., unchecked
Checkbox	`"value": ""`	Same effect as false - Suggest use true / false
Checkbox	(any other value)	Error returned
Codelist	`"value": "Y"`	e.g. "Yes" = "Y" in codelist definition
Codelist	`"value": ""`	Empty / unset the selection
Codelist	(any other value, i.e., not a codelist code)	Error returned
URL	`"value": "https://www.google.com"`	Set the value to a URL, on screen user can click to navigate to the URL, in another tab
URL	`"value": ""`	Empty / unset the value
URL	(any value that does not start http or ftp)	Error returned
Text Field	`"value": "Here is my text in the field"`	Set a value
Text Field	`"value": ""`	Empty / unset the value
Text Field	(over max length)	Error returned
Numeric	`"value": "3"`	E.g., a field with precision = 0 (no decimal portion)
Numeric	`"value": "13.4"`	E.g., a decimal portion allowed field (precision > 0)
Numeric	`"value": ""`	Empty / unset the value
Numeric	(not numeric or violates length or precision)	Error returned
Date	`"value": "2022-06-01"`	E.g., to set June 1st, 2022
Date	`"value": ""`	Empty / unset the value
Date	`"value": "2022-UN-UN"`	E.g., when the field allows unknowns in month and/or day. UN must be used in the appropriate portion
Date	(bad date, not of proper format, yyyy-MM-dd)	Error returned
DateTime	`"value": "2022-06-01T12:30:00Z"`	Set the datetime in full, this will take on the 'on screen' value (not the normalized)
DateTime	`"value": ""`	Empty / unset the value
DateTime	(bad date, not of proper format, yyyy-MM-ddTHH:mmZ)	Error returned
Time	`"value": "12:30"`	Set the time value
Time	`"value": ""`	Empty / unset the value
Time	(bad date, not of proper format, HH:mm)	Error returned
Unit Codelist	`"value": "62.2", "unit_value": "in"`	E.g., 'in' is a valid code in the unit codelist definition.
Unit Codelist	`"value": "" , "unit_value": ""`	Empty / unset the value
Unit Codelist	`"value": "62.2"`	Error returned (must have both)
Unit Codelist	(any violation of length, precision, or invalid unit code)	Error returned
Item to Form Link	(example below and to the right)	IMPORTANT: The `value` portion for the Item must be included, but with no value for this Item Definition type. Only the information about the remote Form being linked to by the Item is indicated

(example for Item to Form Link type of Item)

{ "item_name": "AE_LINK_TO_MH", "value": "", "item_to_form_link": { "eventgroup_name": "egSCR", "event_name": "evSCR", "form_name": "MH", "form_sequence": 3 } } :

Create Forms

Request - adding one new form

curl -L -X POST 'https://my-vault.veevavault.com/api/{version}cdm/forms' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
        {
            "study_country": "United States",
            "site": "101",          
            "subject": "101-001",
            "eventgroup_name": "egLOGS",
            "event_name": "evLOGS",
            "form_name": "AE"
        }
    ]
}'

Response - adding one new form

{
    "responseStatus": "SUCCESS",
    "forms": [
        {
        "responseStatus": "SUCCESS",
        "study_country": "United States",
        "site": "101",
        "subject": "101-001",
        "eventgroup_name": "egLOGS",        
        "eventgroup_sequence": 1,
        "event_name": "evLOGS",
        "event_sequence": 1,
        "form_name": "AE",
        "form_sequence": 1
        }
    ]
}

Request - adding multiple forms

curl -L -X POST 'https://my-vault.veevavault.com/api/{version}cdm/forms' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
        {
            "study_country": "United States",
            "site": "101",          
            "subject": "101-001",
            "eventgroup_name": "egLOGS",
            "event_name": "evLOGS",
            "form_name": "AE"
        },
        {
            "study_country": "United States",
            "site": "101",          
            "subject": "101-001",
            "eventgroup_name": "egLOGS",
            "event_name": "evLOGS",
            "form_name": "AE"
        }       
    ]
}'

Response - adding multiple forms

{
    "responseStatus": "SUCCESS",
    "forms": [
        {
        "responseStatus": "SUCCESS",
        "study_country": "United States",
        "site": "101",
        "subject": "101-001",
        "eventgroup_name": "egLOGS",        
        "eventgroup_sequence": 1,
        "event_name": "evLOGS",
        "event_sequence": 1,
        "form_name": "AE",
        "form_sequence": 2
        },
        {
        "responseStatus": "SUCCESS",
        "study_country": "United States",
        "site": "101",
        "subject": "101-001",
        "eventgroup_name": "egLOGS",        
        "eventgroup_sequence": 1,
        "event_name": "evLOGS",
        "event_sequence": 1,
        "form_name": "AE",
        "form_sequence": 3
        }
    ]
}

Notes

The action adds repeating Form instances, the next available sequence.
The Maximum Repeats value of the Study design will be enforced when attempting.
BEST PRACTICE - Use the Combination Update Form Data endpoint, a more efficient approach than this legacy endpoint..
The limit for actions in one request is 100.

Endpoint

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

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`forms`	Name of the Study Country of the Subject
`site`	`forms`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`forms`	Name of the Subject (ID / number)
`eventgroup_name`	`forms`	Study design name of the Event Group
`eventgroup_sequence`	`forms`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per study design.
`event_name`	`forms`	Study design name of the Event where the Form resides
`form_name`	`forms`	Study design name of the Form to add

Upsert Forms

Request - adding one new form

curl -L -X POST 'https://my-vault.veevavault.com/api/{version}cdm/forms' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
        {
            "study_country": "United States",
            "site": "101",          
            "subject": "101-001",
            "eventgroup_name": "egLOGS",
            "event_name": "evLOGS",
            "form_name": "AE",
            "form_sequence": 3
        }
    ]
}'

Response - adding one new form

{
    "responseStatus": "SUCCESS",
    "forms": [
        {
        "responseStatus": "SUCCESS:CREATED",
        "study_country": "United States",
        "site": "101",
        "subject": "101-001",
        "eventgroup_name": "egLOGS",        
        "eventgroup_sequence": 1,
        "event_name": "evLOGS",
        "event_sequence": 1,
        "form_name": "AE",
        "form_sequence": 3
        }
    ]
}

Request - adding multiple forms

curl -L -X POST 'https://my-vault.veevavault.com/api/{version}cdm/forms' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
        {
            "study_country": "United States",
            "site": "101",          
            "subject": "101-001",
            "eventgroup_name": "egLOGS",
            "event_name": "evLOGS",
            "form_name": "AE",
            "form_sequence": 4
        },
        {
            "study_country": "United States",
            "site": "101",          
            "subject": "101-001",
            "eventgroup_name": "egLOGS",
            "event_name": "evLOGS",
            "form_name": "AE",
            "form_sequence": 5
        }       
    ]
}'

Response - adding multiple forms

{
    "responseStatus": "SUCCESS",
    "forms": [
        {
        "responseStatus": "SUCCESS:UPDATED",
        "study_country": "United States",
        "site": "101",
        "subject": "101-001",
        "eventgroup_name": "egLOGS",        
        "eventgroup_sequence": 1,
        "event_name": "evLOGS",
        "event_sequence": 1,
        "form_name": "AE",
        "form_sequence": 4
        },
        {
        "responseStatus": "SUCCESS:CREATED",
        "study_country": "United States",
        "site": "101",
        "subject": "101-001",
        "eventgroup_name": "egLOGS",        
        "eventgroup_sequence": 1,
        "event_name": "evLOGS",
        "event_sequence": 1,
        "form_name": "AE",
        "form_sequence": 5
        }
    ]
}

Notes

The action adds repeating Form instances where they do not already exist, and skips requests where the Form already exists at that sequence.
BEST PRACTICE - Use the Combination Update Form Data endpoint, a more efficient approach than this legacy endpoint.
The limit for actions in one request is 100.

Endpoint

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

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`forms`	Name of the Study Country of the Subject
`site`	`forms`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`forms`	Name of the Subject (ID / number)
`eventgroup_name`	`forms`	Study design name of the Event Group
`eventgroup_sequence`	`forms`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per study design.
`event_name`	`forms`	Study design name of the Event where the Form resides
`form_name`	`forms`	Study design name of the Form to add
`form_sequence`	`forms`	Required for the PUT version of this endpoint. The sequence of the Form to act on - created if does not exist, skipped if exists.

Create Item Groups

Request - Add one item group, where form already has 3

curl -L -X POST 'https://my-vault.veevavault.com/api/{version}cdm/itemgroups' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "itemgroups": [
            {
                "study_country": "United States",
                "site": "102",                
                "subject": "102-001",
                "eventgroup_name": "egSCR",
                "event_name": "evSCR",
                "form_name": "IE",
                "form_sequence": 1,
                "itemgroup_name": "ig-IE2"
            }
    ]
}'

Response - Add one item group, where form already has 3

{
    "responseStatus": "SUCCESS",
    "itemgroups": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "102",
            "subject": "102-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "IE",
            "form_sequence": 1,
            "itemgroup_name": "ig-IE2",
            "itemgroup_sequence": 4
        }
    ]
}

Request - Add two item groups, where form already has 4

curl -L -X POST 'https://my-vault.veevavault.com/api/{version}cdm/itemgroups' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "itemgroups": [
            {
                "study_country": "United States",
                "site": "102",                
                "subject": "102-001",
                "eventgroup_name": "egSCR",
                "event_name": "evSCR",
                "form_name": "IE",
                "form_sequence": 1,
                "itemgroup_name": "ig-IE2"
            },
            {
                "study_country": "United States",
                "site": "102",                
                "subject": "102-001",
                "eventgroup_name": "egSCR",
                "event_name": "evSCR",
                "form_name": "IE",
                "form_sequence": 1,
                "itemgroup_name": "ig-IE2"
            }
    ]
}'

Response - Add two item groups, where form already has 4

{
    "responseStatus": "SUCCESS",
    "itemgroups": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "102",
            "subject": "102-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "IE",
            "form_sequence": 1,
            "itemgroup_name": "ig-IE2",
            "itemgroup_sequence": 5
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "102",
            "subject": "102-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "IE",
            "form_sequence": 1,
            "itemgroup_name": "ig-IE2",
            "itemgroup_sequence": 6
        }
    ]
}

Notes

The action adds repeating Item Group instances, the next available sequence.
The Maximum Repeats value of the Study design will be enforced when attempting.
BEST PRACTICE - Use the Combination Update Form Data endpoint, a more efficient approach than this legacy endpoint.
The limit for actions in one request is 100.

Endpoint

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

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`itemgroups`	Name of the Study Country of the Subject
`site`	`itemgroups`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`itemgroups`	Name of the Subject (ID / number)
`eventgroup_name`	`itemgroups`	Study design name of the Event Group
`eventgroup_sequence`	`itemgroups`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per study design.
`event_name`	`itemgroups`	Study design name of the Event
`form_name`	`itemgroups`	Study design name of the Form
`form_sequence`	`itemgroups`	Optional Specific Form sequence (i.e., repeating Form area) to perform on. If omitted, 1 is assumed.
`itemgroup_name`	`itemgroups`	Study design name of the Item Group to be added within the Form

Upsert Item Groups

Request - Add 2nd, 3rd, where 2nd already exists

curl -L -X PUT 'https://my-vault.veevavault.com/api/v24.1/cdm/itemgroups' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "itemgroups": [
            {
                "study_country": "United States",
                "site": "102",               
                "subject": "SCR-0002",
                "eventgroup_name": "egSCR",
                "event_name": "evSCR",
                "form_name": "IE",
                "form_sequence": 1,
                "itemgroup_name": "ig-IE2",
                "itemgroup_sequence": 2 
            },
            {
                "study_country": "United States",
                "site": "102",               
                "subject": "SCR-0002",
                "eventgroup_name": "egSCR",
                "event_name": "evSCR",
                "form_name": "IE",
                "form_sequence": 1,
                "itemgroup_name": "ig-IE2",
                "itemgroup_sequence": 3 
            } 
    ]
}'

Response - Add 2nd, 3rd, where 2nd already exists

{
    "responseStatus": "SUCCESS",
    "itemgroups": [
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "102",
            "subject": "SCR-0002",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "IE",
            "form_sequence": 1,
            "itemgroup_name": "ig-IE2",
            "itemgroup_sequence": 2
        },
        {
            "responseStatus": "SUCCESS:CREATED",
            "study_country": "United States",
            "site": "102",
            "subject": "SCR-0002",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "IE",
            "form_sequence": 1,
            "itemgroup_name": "ig-IE2",
            "itemgroup_sequence": 3
        }
    ]
}

Request - Add 3rd item group, where form currently has 1 (2 added, GAPS FILLED)

curl -L -X PUT 'https://my-vault.veevavault.com/api/v24.1/cdm/itemgroups' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "itemgroups": [
            {
                "study_country": "United States",
                "site": "102",               
                "subject": "SCR-0002",
                "eventgroup_name": "egSCR",
                "event_name": "evSCR",
                "form_name": "IE",
                "form_sequence": 1,
                "itemgroup_name": "ig-IE2",
                "itemgroup_sequence": 3 
            }

    ]
}'

Response - Add 3rd item group, where form currently has 1 (2 added, GAPS FILLED)

{
    "responseStatus": "SUCCESS",
    "itemgroups": [
        {
            "responseStatus": "SUCCESS:CREATED",
            "study_country": "United States",
            "site": "102",
            "subject": "SCR-0002",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "IE",
            "form_sequence": 1,
            "itemgroup_name": "ig-IE2",
            "itemgroup_sequence": 3
        }
    ]
}

Notes

The action adds repeating Item Group instances where they do not already exist, and skips requests where the Item Group already exists at that sequence.
BEST PRACTICE - Use the Combination Update Form Data endpoint, a more efficient approach than this legacy endpoint.
The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`itemgroups`	Name of the Study Country of the Subject
`site`	`itemgroups`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`itemgroups`	Name of the Subject (ID / number)
`eventgroup_name`	`itemgroups`	Study design name of the Event Group
`eventgroup_sequence`	`itemgroups`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per study design.
`event_name`	`itemgroups`	Study design name of the Event
`form_name`	`itemgroups`	Study design name of the Form
`form_sequence`	`itemgroups`	Optional Specific Form sequence (i.e., repeating Form area) to perform on. If omitted, 1 is assumed.
`itemgroup_name`	`itemgroups`	Study design name of the Item Group to be added within the Form
`itemgroup_sequence`	`itemgroups`	Required, the specific sequence to have added. If the item group at that sequence already exists, the action is skipped

Set Form Data (Items)

Request - Setting values for one of each type of item

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/items \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
            {
                "study_country": "United States"
                "site": "101",
                "subject": "SCR-0001",
                "eventgroup_name": "egUNS",
                "eventgroup_sequence": 3,
                "event_name": "evUNS",
                "form_name": "OE",
                "form_sequence": 1,
                "items": [
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "CB",
                    "value": "true"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "CL",
                    "value": "Y"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "DATEONLY",
                    "value": "2022-06-01"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "DATEONLY_UNKS",
                    "value": "2022-UN-UN"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "DATEANDTIME",
                    "value": "2022-06-01T12:30Z"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "DT_WITH_UNKS",
                    "value": "2022-06-UNTUN:UNZ"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "INTFIELD",
                    "value": "3"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "DECIMAL",
                    "value": "5.2"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "UCLFIELD",
                    "value": "2.1",
                    "unit_value": "double_std"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "URL_FIELD",
                    "value": "https://www.google.com"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "SHORTTXT",
                    "value": "Some text short"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "LONGTXT",
                    "value": "Some text in a long text field \n with a line break in the payload"
                  }
                ]
            }
        ]
}'

Response - Setting values for one of each type of item

{
    "responseStatus": "SUCCESS",
    "items": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "CB",
            "value": "true",
            "change_reason": "Action performed via the API",
            "externally_owned": true 
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "CL",
            "value": "Y",
            "change_reason": "Action performed via the API",
            "externally_owned": true
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "DATEONLY",
            "value": "2022-06-01",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "DATEONLY_UNKS",
            "value": "2022-UN-UN",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "DATEANDTIME",
            "value": "2022-06-01T12:30Z",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "DT_WITH_UNKS",
            "value": "2022-06-UNTUN:UNZ",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "INTFIELD",
            "value": "3",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "DECIMAL",
            "value": "5.2",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "UCLFIELD",
            "value": "2.1",
            "unit_value": "double_std",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "URL_FIELD",
            "value": "https://www.google.com",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "SHORTTXT",
            "value": "Some text short",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "LONGTXT",
            "value": "Some text in a long text field \n with a line break in the payload",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         }
    ]
}

Notes

Used to set (or update) data values on a Form.
The endpoint does not create/upsert a Form that does not yet exist, nor open a Form for edit (if currently submitted).
BEST PRACTICE - Use the Combination Update Form Data endpoint, a more efficient approach than this legacy endpoint.
The limit for actions in one request is 25 Forms. Additionally, any one Form entry can only have at most 100 items within.

Endpoint

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

Required Permissions

The following permissions are required to use the Set Form Data API:

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`forms`	Name of the Study Country of the Subject
`site`	`forms`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`forms`	Name of the Subject (ID / number)
`eventgroup_name`	`forms`	Study design name of the Event Group
`eventgroup_sequence`	`forms`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per study design.
`event_name`	`forms`	Study design name of the Event
`form_name`	`forms`	Study design name of the Form
`form_sequence`	`forms`	Optional Specific Form sequence (i.e., repeating Form area) to perform on. If omitted, 1 is assumed.
`itemgroup_name`	`forms/items`	Study design name of the Item Group to be added within the Form
`itemgroup_sequence`	`forms/items`	Optional The specific Item Group sequence where the Item resides. If omitted, 1 is assumed. It is strongly recommended to always include the sequence, even for non-repeating.
`value`	`forms/items`	The value to set. See the table below for notes on Item types and value.
`unit_value`	`forms/items`	Required when the Item is a unit codelist type. Omit otherwise. The value must be the unit codelist code, not label.
`change_reason`	`forms/items`	Optional The reason for change of an Item value. For example: "Data updated by remote system"
`externally_owned`	`forms/items`	Optional When omitted true is used, i.e. the site user cannot then further edit the value. Pass a false to re-enable the ability for a user to edit a previously read only Item.

Upsert Form Data (Items)

Request - Setting values for one of each type of item

curl -X PUT https://my-vault.veevavault.com/api/v24.1/app/cdm/items \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
            {
                "study_country": "United States",
                "site": "101",                
                "subject": "SCR-0001",
                "eventgroup_name": "egUNS",
                "eventgroup_sequence": 3,
                "event_name": "evUNS",
                "form_name": "OE",
                "form_sequence": 1,
                "items": [
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "CB",
                    "value": "true"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "CL",
                    "value": "Y"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "DATEONLY",
                    "value": "2022-06-01"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "DATEONLY_UNKS",
                    "value": "2022-UN-UN"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "DATEANDTIME",
                    "value": "2022-06-01T12:30Z"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "DT_WITH_UNKS",
                    "value": "2022-06-UNTUN:UNZ"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "INTFIELD",
                    "value": "3"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "DECIMAL",
                    "value": "5.2"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "UCLFIELD",
                    "value": "2.1",
                    "unit_value": "double_std"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "URL_FIELD",
                    "value": "https://www.google.com"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "SHORTTXT",
                    "value": "Some text short"
                  },
                  {
                    "itemgroup_name": "igOE",
                    "itemgroup_sequence": 1,                   
                    "item_name": "LONGTXT",
                    "value": "Some text in a long text field \n with a line break in the payload"
                  }
                ]
            }
        ]
}'

Response - Setting values for one of each type of item

{
    "responseStatus": "SUCCESS",
    "items": [
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "CB",
            "value": "true",
            "change_reason": "Action performed via the API",
            "externally_owned": true
        },
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "CL",
            "value": "Y",
            "change_reason": "Action performed via the API",
            "externally_owned": true
        },
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "DATEONLY",
            "value": "2022-06-01",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "DATEONLY_UNKS",
            "value": "2022-UN-UN",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "DATEANDTIME",
            "value": "2022-06-01T12:30Z",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "DT_WITH_UNKS",
            "value": "2022-06-UNTUN:UNZ",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "INTFIELD",
            "value": "3",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "DECIMAL",
            "value": "5.2",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "UCLFIELD",
            "value": "2.1",
            "unit_value": "double_std",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "URL_FIELD",
            "value": "https://www.google.com",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "SHORTTXT",
            "value": "Some text short",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         },
         {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0001",
            "eventgroup_name": "egUNS",
            "eventgroup_sequence": 3,
            "event_name": "evUNS",
            "event_sequence": 1,
            "form_name": "OE",
            "form_sequence": 1,
            "itemgroup_name": "igOE",
            "itemgroup_sequence": 1,
            "item_name": "LONGTXT",
            "value": "Some text in a long text field \n with a line break in the payload",
            "change_reason": "Action performed via the API",
            "externally_owned": true
         }
    ]
}

Notes

This endpoint is like Set Form Data (previous section, POST), but a later release (as PUT).
Used to set (or update) data values on a Form.
The endpoint does not create/upsert a Form that does not yet exist, nor open a Form for edit (if currently submitted).
The current version of this endpoint returns SUCCESS:UPDATED, even if no change was made on a specific Item. (i.e. a 'skip')
BEST PRACTICE - If also updating data on a Form, use the Combination Update Form Data endpoint, a more efficient approach than this legacy endpoint.
The limit for actions in one request is 25 Forms. Additionally, any one Form entry can only have at most 100 items within.

Setting Data by Item Type

Type	Example	Notes
Checkbox	`"value": "true"`	i.e., checked
Checkbox	`"value": "false"`	i.e., unchecked
Checkbox	`"value": ""`	Same effect as false - Suggest use true / false
Checkbox	(any other value)	Error returned
Codelist	`"value": "Y"`	e.g. "Yes" = "Y" in codelist definition
Codelist	`"value": ""`	Empty / unset the selection
Codelist	(any other value, i.e., not a codelist code)	Error returned
URL	`"value": "https://www.google.com"`	Set the value to a URL, on screen user can click to navigate to the URL, in another tab
URL	`"value": ""`	Empty / unset the value
URL	(any value that does not start http or ftp)	Error returned
Text Field	`"value": "Here is my text in the field"`	Set a value
Text Field	`"value": ""`	Empty / unset the value
Text Field	(over max length)	Error returned
Numeric	`"value": "3"`	E.g., a field with precision = 0 (no decimal portion)
Numeric	`"value": "13.4"`	E.g., a decimal portion allowed field (precision > 0)
Numeric	`"value": ""`	Empty / unset the value
Numeric	(not numeric or violates length or precision)	Error returned
Date	`"value": "2022-06-01"`	E.g., to set June 1st, 2022
Date	`"value": ""`	Empty / unset the value
Date	`"value": "2022-UN-UN"`	E.g., when the field allows unknowns in month and/or day. UN must be used in the appropriate portion
Date	(bad date, not of proper format, yyyy-MM-dd)	Error returned
DateTime	`"value": "2022-06-01T12:30:00Z"`	Set the datetime in full, this will take on the 'on screen' value (not the normalized)
DateTime	`"value": ""`	Empty / unset the value
DateTime	(bad date, not of proper format, yyyy-MM-ddTHH:mmZ)	Error returned
Time	`"value": "12:30"`	Set the time value
Time	`"value": ""`	Empty / unset the value
Time	(bad date, not of proper format, HH:mm)	Error returned
Unit Codelist	`"value": "62.2", "unit_value": "in"`	E.g., 'in' is a valid code in the unit codelist definition.
Unit Codelist	`"value": "", "unit_value": ""`	Empty / unset the value
Unit Codelist	`"value": "62.2"`	Error returned (must have both)
Unit Codelist	(any violation of length, precision, or invalid unit code)	Error returned

Endpoint

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

Required Permissions

The following permissions are required to use the Upsert Form Data API:

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`forms`	Name of the Study Country of the Subject
`site`	`forms`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`forms`	Name of the Subject (ID / number)
`eventgroup_name`	`forms`	Study design name of the Event Group
`eventgroup_sequence`	`forms`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per study design.
`event_name`	`forms`	Study design name of the Event
`form_name`	`forms`	Study design name of the Form
`form_sequence`	`forms`	Optional Specific Form sequence (i.e., repeating Form area) to perform on. If omitted, 1 is assumed.
`itemgroup_name`	`forms/items`	Study design name of the Item Group to be added within the Form
`itemgroup_sequence`	`forms/items`	The specific Item Group sequence where the Item resides, Required even if a non-repeating Item Group.
`value`	`forms/items`	The value to set. See the table below for notes on Item types and value.
`unit_value`	`forms/items`	Required when the Item is a unit codelist type. Omit otherwise. The value must be the unit codelist code, not label.
`change_reason`	`forms/items`	Optional The reason for change of an Item value. For example: "Data updated by remote system"
`externally_owned`	`forms/items`	Optional When omitted true is used, i.e. the site user cannot then further edit the value. Pass a false to re-enable the ability for a user to edit a previously read only Item.

Submit Forms

Request - Submit one form

curl -X POST https://my-vault.veevavault.com/api/v24.1/app/cdm/forms/actions/submit \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "Enrollment-Visit",
            "event_name": "Enrollment-Visit",
            "form_name": "Randomization"
        }
    ]
}'

Response - Submit one form

{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
        {
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "eventgroup_name": "Enrollment-Visit",
            "event_name": "Enrollment-Visit",
            "form_name": "Randomization"
        }
    ]
}

Notes

Used to perform the equivalent of the on screen Complete button.
All study design Rules (of that Form) will be run as part of the action.
BEST PRACTICE - If also updating data on a Form, use the Combination Update Form Data endpoint, a more efficient approach than this legacy endpoint.
The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`forms`	Name of the Study Country of the Subject
`site`	`forms`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`forms`	Name of the Subject (ID / number)
`eventgroup_name`	`forms`	Study design name of the Event Group
`eventgroup_sequence`	`forms`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per study design.
`event_name`	`forms`	Study design name of the Event
`form_name`	`forms`	Study design name of the Form
`form_sequence`	`forms`	Optional Specific Form sequence (i.e., repeating Form area) to perform on. If omitted, 1 is assumed.

Reopen Submitted Forms

Request - Open one form for edit

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

Response - Open one form for edit

{
    "responseStatus": "SUCCESS",
    "forms": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "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"
        }
    ]
}

Notes

Used to perform the equivalent of the on screen Edit Form button.
BEST PRACTICE - Use the Combination Update Form Data endpoint, a more efficient approach than this legacy endpoint.
The limit for actions in one request is 100.

Endpoint

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

Required Permissions

The following permissions are required to use the Reopen Submitted Forms API:

API Access
View Casebook
Data Entry

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`forms`	Name of the Study Country of the Subject
`site`	`forms`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`forms`	Name of the Subject (ID / number)
`eventgroup_name`	`forms`	Study design name of the Event Group
`eventgroup_sequence`	`forms`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per Study design.
`event_name`	`forms`	Study design name of the Event
`form_name`	`forms`	Study design name of the Form
`form_sequence`	`forms`	Optional Specific Form sequence (i.e., repeating Form area) to perform on. If omitted, 1 is assumed.
`change_reason`	`forms`	The reason for change for editing the Form

Queries

Queries are a method of review or error checking of entered data. There are two types of queries:

System queries generally originate from a Study design rule at the submit of a Form. (by API or end user). Vault creates these queries based on configured data validation rules in your Study.
Manual queries are those added by an end user, or by an API user. That is, they are not tied to a Study design rule / validation. Examples include CRA or Data Manager creating one with questions to the Site user, or ones created via Open Queries.

Learn more about queries in Vault CDMS Help.

Retrieve Queries

Request

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/queries?study_name=ABCP-2022-01_DEV1&study_country=United States&site=0101' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "queries": [
        {
            "id": "OPW000000003001",
            "query_name": "VV-000003",
            "manual": true,
            "query_status": "open__v",
            "study_country": "United States",
            "site": "101",
            "subject": "101-003",
            "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": "101",
            "subject": "101-001",
            "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"
                }
            ]
        }
    ]
}

Notes

Use this API to retrieve the existing Queries using Study Context.
When the Query was added via a specific design rule, the rule_definition indicates the name of the rule that originated the Query.
Queries are added at the Item or Event level. For Event level, the Form ‘down’ information is of course omitted
The respones includes a messages array with each comment/message appended to the Query. Reading top down in that array also reveals the progression of Query status, and by whom
This endpoint is used to retrieve a list of queries for a Study. You can filter this list using one or more of the following:
- Study Country
- Site
- Subject
- Form Definition
- Status (of the Query)
- Queries added against specific Medical Coding Requests (see Retrieve Coding Queries)
- Last modified date/time of the Query

Endpoint

GET /api/{version}/app/cdm/queries?study_name={study_name}&...other filters here...

Required Permissions

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

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

The CDMS API Read Write and CDMS API Read Only roles grant these permissions.

Headers

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

Query String Parameters

Name	Description
`study_name`	Name of the Study
`study_country`	Optional Name of the Study Country to filter to
`site`	Optional Name of the Site to filter to. Must include the `study_country` when using this.
`subject`	Optional Name (ID/number) to filter to. Must include `site` when using this.
`form_name`	Optional Study design name of a Form to filter to, e.g. all queries on the AE Form, across the Study.
`query_status`	Optional Current status of the queries to filter to. Values to use are one of `open__v`, `answered__v`, or `closed__v`.
`last_modified_date`	Optional Retrieve only Queries modified after this datetime. Use the format "yyyy-MM-ddTHH:mm:ssZ".
`id`	See next section: Retrieve Queries by ID (study context, by ID(s), or by coding definition are used, only one style)
`coding_item_definition`	See later section: Retrieve Coding Queries (study context, by ID(s), or by coding definition are used, only one style)

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

On SUCCESS, Vault returns a list of Queries (as JSON array entries) with the following information:

Array	Name	Description
`queries`	`id`	Vault internal ID for the Query
`queries`	`query_name`	Another Vault internal ID for the Query, this one is visible from the UI
`queries`	`manual`	Whether the Query is classified System (false) or Manual (true)
`queries`	`query_status`	Values will be one of `open__v`, `answered__v`, or `closed__v`
`queries`	`study_country`	Name of the Study Country for the site of the Subject
`queries`	`site`	Name of the Site for the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`queries`	`subject`	Name (ID/number) of the Subject
`queries`	`eventgroup_name`	Study design name for the Event Group
`queries`	`eventgroup_sequence`	Sequence of the Event Group of the Event. If repeating Event Group the value increments starting at 1, 2.... If it does not repeat, then 1 is always returned
`queries`	`event_name`	Study design name for a the Event
`queries`	`event_sequence`	Currently, always a 1. If the Event within a repeating Event Group the sequence increments at the `evengroup_sequence` level
`queries`	`form_name`	(When attached to an Item only, omitted for Event queries) Study design name for a Form
`queries`	`form_sequence`	(When attached to an Item only, omitted for Event queries) If the Form repeats per Study design, these increment starting at 1, 2.... If it does repeat, 1 is always returned.
`queries`	`itemgroup_name`	(When attached to an Item only, omitted for Event queries) Study design name of the Item Group
`queries`	`itemgroup_sequence`	(When attached to an Item only, omitted for Event queries) The specific Item Group sequence
`queries`	`item_name`	(When attached to an Item only, omitted for Event queries) Study design name of the Item
`queries`	`rule_definition`	When a Query originating from a Study design rule, that rule name. Omitted otherwise.
`queries`	`coding_item_definition`	When a Query originating from Open Coding Queries, that medical coding definition name. Omitted otherwise.
`queries`	`created_date`	The datetime that the Query was first created (UTC)
`queries`	`created_by`	Name (Firstname Lastname) of the User who created the Query
`queries/messages`	`id`	Vault internal ID of the Query message. These entries reading top to bottom (in the array) comprise the movement of statuses, plus comments of the Query
`queries/messages`	`activity`	The Query status at that entry. Values will be one of `open__v`, `answered__v`, or `closed__v`
`queries/messages`	`message`	The message at that Query update. Some activity entries do not include a specific message (e.g. close of an added Query)
`queries/messages`	`message_date`	The datetime that this message/status change (UTC)
`queries/messages`	`message_by`	Name (Firstname Lastname) of the User who moved the status / commented at this revision of the Query

Retrieve Queries by ID

Request

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/queries?study_name=ABCP-2022-01_DEV1&id=OPW000000003001' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
   "responseStatus": "SUCCESS",
   "queries": [
       {
           "id": "OPW000000003001",
           "query_name": "VV-000003",
           "manual": true,
           "query_status": "open__v",
           "study_country": "United States",
           "site": "101",
           "subject": "101-003",
           "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"
               }
           ]
       }
   ]
}

Notes

Use this API to retrieve the existing Queries of a specific ID (or IDs).
The ID of the Query is returned on add via the API, or from Retrieve Queries.
When the Query was added via a specific design rule, the rule_definition indicates the name of the rule that originated the Query.
Queries are added at the Item or Event level. For Event level, the Form ‘down’ information is of course omitted
The respones includes a messages array with each comment/message appended to the Query. Reading top down in that array also reveals the progression of Query status, and by whom

Endpoint

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

Required Permissions

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

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

The CDMS API Read Write and CDMS API Read Only roles grant these permissions.

Headers

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

Query String Parameters

Name	Description
`study_name`	Name of the Study
`last_modified_date`	Optional Retrieve only Queries modified after this datetime. Use the format "yyyy-MM-ddTHH:mm:ssZ".
`id`	The Vault internal ID of the Query, or multiple in a comma-separated list. This parameter overrides all other parameters, except for `study_name`

This API supports pagination, although unlikely to use paging when searching specific Queries by ID. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

On SUCCESS, Vault returns a list of Queries (as JSON array entries) with the following information:

Array	Name	Description
`queries`	`id`	Vault internal ID for the Query
`queries`	`query_name`	Another Vault internal ID for the Query, this one is visible from the UI
`queries`	`manual`	Whether the query is classified System (false) or Manual (true)
`queries`	`query_status`	Values will be one of `open__v`, `answered__v`, or `closed__v`
`queries`	`study_country`	Name of the Study Country for the site of the Subject
`queries`	`site`	Name of the Site for the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`queries`	`subject`	Name (ID/number) of the Subject
`queries`	`eventgroup_name`	Study design name for the Event Group
`queries`	`eventgroup_sequence`	Sequence of the Event Group of the Event. If repeating Event Group the value increments starting at 1, 2.... If it does not repeat, then 1 is always returned
`queries`	`event_name`	Study design name for a the Event
`queries`	`event_sequence`	Currently, always a 1. If the Event within a repeating Event Group the sequence increments at the `evengroup_sequence` level
`queries`	`form_name`	(When attached to an Item only, omitted for Event queries) Study design name for a Form
`queries`	`form_sequence`	(When attached to an Item only, omitted for Event queries) If the Form repeats per Study design, these increment starting at 1, 2.... If it does repeat, 1 is always returned.
`queries`	`itemgroup_name`	(When attached to an Item only, omitted for Event queries) Study design name of the Item Group
`queries`	`itemgroup_sequence`	(When attached to an Item only, omitted for Event queries) The specific Item Group sequence
`queries`	`item_name`	(When attached to an Item only, omitted for Event queries) Study design name of the Item
`queries`	`rule_definition`	When a Query originating from a Study design rule, that rule name. Omitted otherwise.
`queries`	`coding_item_definition`	When a Query originating from Open Coding Queries, that medical coding definition name. Omitted otherwise.
`queries`	`created_date`	The datetime that the Query was first created (UTC)
`queries`	`created_by`	Name (Firstname Lastname) of the User who created the Query
`queries/messages`	`id`	Vault internal ID of the Query message. These entries reading top to bottom (in the array) comprise the movement of statuses, plus comments of the Query
`queries/messages`	`activity`	The Query status at that entry. Values will be one of `open__v`, `answered__v`, or `closed__v`
`queries/messages`	`message`	The message at that Query update. Some activity entries do not include a specific message (e.g. close of an added Query)
`queries/messages`	`message_date`	The datetime that this message/status change (UTC)
`queries/messages`	`message_by`	Name (Firstname Lastname) of the User who moved the status / commented at this revision of the Query

Open Queries

Request - Add one query, item level

curl -X POST \
  https://my-vault.veevavault.com/api/v24.1/app/cdm/queries \
  -H "Authorization: {SESSION_ID}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
            {
                "study_country": "United States",
                "site": "101",                
                "subject": "101-001",
                "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 - Add one query, item level


{
    "responseStatus": "SUCCESS",
    "queries": [
                {
                    "responseStatus": "SUCCESS",
                    "id": "OPW000000006001",
                    "query_name": "VV-000091",
                    "query_status": "open__v",
                    "study_country": "United States",
                    "site": "101",                    
                    "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"
                }
              ]
}

Request - Add two queries, item level and event level

curl -X POST \
  https://my-vault.veevavault.com/api/v24.1/app/cdm/queries \
  -H "Authorization: {SESSION_ID}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
            {
                "study_country": "United States",
                "site": "101",
                "subject": "101-001",
                "eventgroup_name": "EG.SCR",
                "eventgroup_sequence": 1,
                "event_name": "EV.SCR",
                "message": "Please double check the screening date entered"
            },
            {
                "study_country": "United States",
                "site": "101",
                "subject": "101-001",
                "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 - Add two queries, item level and event level


{
    "responseStatus": "SUCCESS",
    "queries": [
                {
                    "responseStatus": "SUCCESS",
                    "id": "OPW000000006001",
                    "query_name": "VV-000091",
                    "query_status": "open__v",
                    "study_country": "United States",
                    "site": "101",
                    "subject": "101-001",
                    "eventgroup_name": "EG.SCR",
                    "eventgroup_sequence": 1,
                    "event_name": "EV.SCR",
                }
                {
                    "responseStatus": "SUCCESS",
                    "id": "OPW000000006002",
                    "query_name": "VV-000091",
                    "query_status": "open__v",
                    "study_country": "United States",
                    "site": "101",
                    "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"
                }
              ]
}

The action is used to add a new Query to an Item of a Form, or Event of a specific Subject, by study context.
WARNING: A locked Form will not allow the add a new Query, just as the EDC UI would disallow. Frozen Forms will accept new Queries added via the API.
For further manipulation of Queries (answer, close, re-open), it's good practice to inspect the return on Query API actions, for the id value.
The API user role must have permission to add Queries.
The limit for actions in one request is 100.
Other options exist to open a new Query, see also:
- Open Queries by Event ID - a Query added against a specific Event, when the Vault ID of that Event is known
- Open Queries by Item ID - a Query added against a specific Item, when the Vault ID of that Item is known
- Open Coding Query - a Query added against a specific Medical Coding Request

Endpoint

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

Required Permissions

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

API Access
Open Query

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`queries`	Name of the Study Country of the Subject
`site`	`queries`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`queries`	Name of the Subject (ID / number)
`eventgroup_name`	`queries`	Study design name of the Event Group
`eventgroup_sequence`	`queries`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per Study design.
`event_name`	`queries`	Study design name of the Event
`form_name`	`queries`	Optional (required for Item queries) Study design name of the Form
`form_sequence`	`queries`	Optional (required for Item queries) Specific Form sequence (i.e., repeating Form area) to perform on. If omitted, 1 is assumed.
`itemgroup_name`	`queries`	Optional (required for Item queries) Study design name of the Item Group where the Item resides
`itemgroup_sequence`	`queries`	Optional (required for Item queries) The specific Item Group sequence where the Item resides. If omitted, 1 is assumed. It is strongly recommended to always include the sequence, even for non-repeating.
`message`	`queries`	The initial message of the Query

Open Queries by Event ID

Request

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

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000003001",
            "query_status": "open__v",
            "event_id": "OPS00000001X001",
            "query_name": "VV-000248",
            "created_date": "2022-06-16T15:52:03Z",
            "created_by": "Eric Emerton",
            "messages": [
                {
                    "id": "OPY000000012001",
                    "activity": "open__v",
                    "message": "We ran screening at this site on Saturday, July 31.",
                    "message_date": "2022-06-16T15:52:04Z",
                    "message_by": "Eric Emerton"
                }
            ]
        }
    ]
}

Notes

The action is used to add a new Query to an Event of a specific Subject.
WARNING: A locked Event will not allow the add a new Query, just as the EDC UI would disallow. Frozen Events will accept new Queries added via the API.
For further manipulation of Queries (answer, close, re-open), it's good practice to inspect the return on Query API actions, for the id value.
The API user role must have permission to add Queries.
The limit for actions in one request is 500.
Other options exist to open a new Query, see also:
- Open Queries - a Query added by specifying the context of the location (Study Country, Site, Subject, Event Group, etc.)
- Open Queries by Item ID - a Query added against a specific Item, when the Vault ID of that Item is known
- Open Coding Queries - a Query added against a specific Medical Coding Request

Endpoint

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

Required Permissions

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

API Access
Open Query

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`manual`		Optional Whether the Query (or queries) should be considered manual. The default is true when omitted. A value of false implies the Query is added by a system, although not necessarily the CDMS system. This value will be applied to all queries added in the request.
`id`	`queries`	The Vault internal ID of the Event to open the Query on.
`message`	`queries`	The initial message of the Query

Open Queries by Item ID

Request

curl -L -g -X POST 'https://my-vault.veevavault.com/21.2/app/cdm/items/actions/openquery' \
-H 'Authorization: {SESSION_ID}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "manual": false,
    "queries": [
                 {
                   "id": "OPV000000000641",
                   "message": "This item value is out of range. Please correct."
                 }
               ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000004001",
            "query_status": "open__v",
            "item_id": "OPV000000000641"            
            "query_name": "VV-000249",
            "created_date": "2022-07-13T15:52:03Z",
            "created_by": "Eric Emerton",
            "messages": [
                {
                    "id": "OPY000000012001",
                    "activity": "open__v",
                    "message": "This item value is out of range. Please correct.",
                    "message_date": "2022-07-13T15:52:04Z",
                    "message_by": "Eric Emerton"
                }
            ]            

        }
    ]
}

Notes

The action is used to add a new Query to an Item (of a Form) of a specific Subject.
WARNING: A locked Form will not allow the add a new Query, just as the EDC UI would disallow. Frozen Forms / Items will accept new Queries added via the API.
For further manipulation of Queries (answer, close, re-open), it's good practice to inspect the return on Query API actions, for the id value.
The API user role must have permission to add Queries.
The limit for actions in one request is 500.
Other options exist to open a new Query, see also:
- Open Queries - a Query added by specifying the context of the location (Study Country, Site, Subject, Event Group, etc.)
- Open Queries by Event ID - a Query added against a specific Event, when the Vault ID of that Event is known
- Open Coding Queries - a Query added against a specific Medical Coding Request

Endpoint

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

Required Permissions

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

API Access
Open Query

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`manual`		Optional Whether the Query (or queries) should be considered manual. The default is true when omitted. A value of false implies the Query is added by a system, although not necessarily the CDMS system. This value will be applied to all queries added in the request.
`id`	`queries`	The Vault internal ID of the Item to open the Query on.
`message`	`queries`	The initial message of the Query

Open Queries by Medical Coding Request

See the section, Open Coding Queries for these details.

Answer Queries

Request - Answer by Country/Site/Subject...

curl -X POST  https://my-vault.veevavault.com/api/v24.1/app/cdm/queries/actions/answer \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "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 - Answer by Country/Site/Subject...

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000000201",
            "query_name": "VV-000002",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "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 - Answer by ID

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/queries/actions/answer' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
        {
           "id": "OPW000000001001",
           "message": "The screening date is correct."
        }
    ]
  }'

Response - Answer by ID

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

Notes

Used to answer a Query that is currently in the Open status, with a comment (required).
The action moves the Query from the Open (open__v) status into the Answered (answered__v) status.
A message is required.
The limit for actions in one request is 100.
There are two ways to answer a Query:
- By its internal Vault ID (returned in response on open Query, or from Retrieve Queries)
- By providing Study context to uniquely identify it (Study Country, Site, Subject, Event Group, Event, etc.)

Endpoint

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

Required Permissions

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

API Access
Answer Query

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters (by Study Context)

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`queries`	Name of the Study Country of the Subject
`site`	`queries`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`queries`	Name of the Subject (ID / number)
`eventgroup_name`	`queries`	Study design name of the Event Group
`eventgroup_sequence`	`queries`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per Study design.
`event_name`	`queries`	Study design name of the Event
`form_name`	`queries`	Optional (required for Item queries) Study design name of the Form
`form_sequence`	`queries`	Optional (required for Item queries) Specific Form sequence (i.e., repeating Form area) to perform on. If omitted, 1 is assumed.
`itemgroup_name`	`queries`	Optional (required for Item queries) Study design name of the Item Group where the Item resides
`itemgroup_sequence`	`queries`	Optional (required for Item queries) The specific Item Group sequence where the Item resides. If omitted, 1 is assumed. It is strongly recommended to always include the sequence, even for non-repeating.
`message`	`queries`	The message at answer of the Query

Body Parameters (By ID)

Name	Array	Description
`study_name`		Name of the Study
`id`	`queries`	The Vault ID of the Query, found from response on open of the Query or from Retrieve Queries endpoint
`message`	`queries`	The message at answer of the Query

Close Queries

Request - Close by Country/Site/Subject...

curl -X POST  https://my-vault.veevavault.com/api/v24.1/app/cdm/queries/actions/close \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "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 - Close by Country/Site/Subject...

{
    "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 - Close by ID

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/queries/actions/close' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
        {
           "id": "OPW000000001001",
           "message": "Closing query - verified that screening date is correct."
        }
    ]
  }'

Response - Close by ID

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

Notes

Used to close a Query that is currently in the Answered status, with a comment (optional).
The action moves the Query from the Answered (answered__v) status into the Closed (closed__v) status.
A message is not required, although is good practice.
The limit for actions in one request is 100.
There are two ways to close a Query:
- By providing Study context to uniquely identify it (Study Country, Site, Subject, Event Group, Event, etc.)
- By its internal Vault ID (returned in response on open Query, or from Retrieve Queries).
- As of v22.2, the close by ID style of this endpoint should be avoided, instead using the Close Queries (by ID / Batch) endpoint. The by ID style of this endpoint will be deprecated in a future release.

Endpoint

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

Required Permissions

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

API Access
Close Query

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters (by Study Context)

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`queries`	Name of the Study Country of the Subject
`site`	`queries`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`queries`	Name of the Subject (ID / number)
`eventgroup_name`	`queries`	Study design name of the Event Group
`eventgroup_sequence`	`queries`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per Study design.
`event_name`	`queries`	Study design name of the Event
`form_name`	`queries`	Optional (required for Item queries) Study design name of the Form
`form_sequence`	`queries`	Optional (required for Item queries) Specific Form sequence (i.e., repeating Form area) to perform on. If omitted, 1 is assumed.
`itemgroup_name`	`queries`	Optional (required for Item queries) Study design name of the Item Group where the Item resides
`itemgroup_sequence`	`queries`	Optional (required for Item queries) The specific Item Group sequence where the Item resides. If omitted, 1 is assumed. It is strongly recommended to always include the sequence, even for non-repeating.
`message`	`queries`	Optional The message at close of the Query

Body Parameters (By ID)

Name	Array	Description
`study_name`		Name of the Study
`id`	`queries`	The Vault ID of the Query, found from response on open of the Query or from Retrieve Queries endpoint
`message`	`queries`	Optional The message at close of the Query

Close Queries (by ID / Batch)

Request - Close by ID (22R2 and later...)

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/queries/actions/closebyid' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
        {
           "id": "OPW000000001001",
           "message": "Closing query - verified that screening date is correct."
        },
        {
           "id": "OPW000000001002",
           "message": "Closing query - added in error."
        }        
    ]
  }'

Response - Close by ID (22R2 and later...)

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000001001",
            "message": "Closing query - verified that screening date is correct.",
            "query_status": "closed__v"
        },
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000001002",
            "message": "Closing query - added in error.",
            "query_status": "closed__v"
        }        
    ]
}

Notes

Close a Query (or many) by ID.
This endpoint replaces the By ID style of the Close Queries endpoint.
The ID(s) of existing Queries can be found using the Retrieve Queries endpoint.
The limit for actions in one request is 500.

Endpoint

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

Required Permissions

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

API Access
Close Query

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`id`	`queries`	The Vault ID of the Query, found from response on open of the Query or from Retrieve Queries endpoint
`message`	`queries`	Optional The message at close of the Query

Reopen Queries

Request - Reopen by Country/Site/Subject...

curl -X POST  https://my-vault.veevavault.com/api/v24.1/app/cdm/queries/actions/reopen \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "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 - Reopen by Country/Site/Subject...

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000000201",
            "query_name": "VV-000002",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "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 - Reopen by ID

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/queries/actions/reopen' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
        {
            "id": "OPW000000001001",
            "message": "Reopening query: Received new information."
        }
    ]
  }'

Response - Reopen by ID

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

Notes

Used to reopen a Query that is currently in the Closed (closed__v) status, with a comment (required).
The action moves the Query into the Open (open__v) status.
The limit for actions in one request is 100.
There are two ways to reopen a Query:
- By its internal Vault ID (returned in response on open Query, or from Retrieve Queries)
- By providing Study context to uniquely identify it (Study Country, Site, Subject, Event Group, Event, etc.)

Endpoint

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

Required Permissions

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

API Access
Open Query

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters (by Study Context)

Name	Array	Description
`study_name`		Name of the Study
`study_country`	`queries`	Name of the Study Country of the Subject
`site`	`queries`	Name of the Site of the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`subject`	`queries`	Name of the Subject (ID / number)
`eventgroup_name`	`queries`	Study design name of the Event Group
`eventgroup_sequence`	`queries`	Optional If omitted, 1 is assumed. Use this parameter if the Event Group is repeating, per Study design.
`event_name`	`queries`	Study design name of the Event
`form_name`	`queries`	Optional (required for Item queries) Study design name of the Form
`form_sequence`	`queries`	Optional (required for Item queries) Specific Form sequence (i.e., repeating Form area) to perform on. If omitted, 1 is assumed.
`itemgroup_name`	`queries`	Optional (required for Item queries) Study design name of the Item Group where the Item resides
`itemgroup_sequence`	`queries`	Optional (required for Item queries) The specific Item Group sequence where the Item resides. If omitted, 1 is assumed. It is strongly recommended to always include the sequence, even for non-repeating.
`message`	`queries`	The message at reopen of the Query

Body Parameters (By ID)

Name	Array	Description
`study_name`		Name of the Study
`id`	`queries`	The Vault ID of the Query, found from response on open of the Query or from Retrieve Queries endpoint
`message`	`queries`	The message at reopen of the Query

Coding

A Medical Coding Request represents an Item that is being coded, e.g Severe Headache on an AE Form. These requests are added and updated upon the submission of the Form containing the Item. MedDRA and WHODrug (B3 or C3) versions are configured per Study design.

Retrieve Coding Requests

Request - 2 MedDRA coding requests, one coded, one not

curl --location --request GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/codingrequests?study_name=ABCP-2022-01_DEV1&coding_item_definition_id=V0T000000002001' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - 2 MedDRA coding requests, one coded, one not

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "codingrequests": [
        {
            "coding_item_definition_id": "V0T000000002001",
            "form_coding_status": "active__v",
            "form_type": "ae__v",
            "dictionary_definition": "MedDRA",
            "requests": [
                {
                    "id": "V0V000000003001",
                    "study_country": "United States",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "My Term 1",
                    "start_date": "",
                    "stop_date": "",
                    "eventgroup_name": "LOGS",
                    "eventgroup_sequence": 1,
                    "event_name": "LOGS",
                    "event_sequence": 1,
                    "form_name": "AE",
                    "form_sequence": 1,
                    "itemgroup_name": "ig-AE",
                    "itemgroup_sequence": 1,
                    "item_name": "AETERM",
                    "coding_status": "open__v",
                    "last_modified_date": "2022-05-23T17:34:46Z",
                    "created_date": "2022-05-23T17:34:46Z",
                    "created_by": "System",                     
                    "other_properties": {
                        "My Label for SAE Form Uploaded": null    
                    },
                    "seriousness": "Yes",
                    "severity": "",
                    "llt_code": "",
                    "llt": "",
                    "pt_code": "",
                    "pt": "",
                    "hlt_code": "",
                    "hlt": "",
                    "hlgt_code": "",
                    "hlgt": "",
                    "soc": "",
                    "soc_code": "",
                    "primary_path": ""
                },
                {
                    "id": "V0V000000003002",
                    "study_country": "United States",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "My AE 2",
                    "start_date": "2022-05-01T00:00:00Z",
                    "stop_date": "",
                    "eventgroup_name": "LOGS",
                    "eventgroup_sequence": 1,
                    "event_name": "LOGS",
                    "event_sequence": 1,
                    "form_name": "AE",
                    "form_sequence": 2,
                    "itemgroup_name": "ig-AE",
                    "itemgroup_sequence": 1,
                    "item_name": "AETERM",
                    "coding_status": "coded__v",
                    "last_coded_date": "2022-06-02T18:35:03Z",
                    "last_modified_date": "2022-06-02T18:35:03Z",
                    "created_date": "2022-05-23T17:35:27Z",
                    "created_by": "System",
                    "other_properties": {
                        "My Label for SAE Form Uploaded": "true"
                    },
                    "seriousness": "No",
                    "severity": "",
                    "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"
                }
            ]
        }
    ]
}

Request - 2 WHODrug coding requests, one coded, one not

curl --location --request GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/codingrequests?study_name=ABCP-2022-01_DEV1&coding_item_definition_id=V0T000000004001' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - 2 WHODrug coding requests, one coded, one not

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "codingrequests": [
        {
            "coding_item_definition_id": "V0T000000004001",
            "form_coding_status": "active__v",
            "form_type": "cm__v",
            "dictionary_definition": "WHODrug C3",
            "requests": [
                {
                    "id": "V0V000000004001",
                    "study_country": "United States",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "Aspirin",
                    "start_date": "",
                    "stop_date": "",
                    "eventgroup_name": "LOGS",
                    "eventgroup_sequence": 1,
                    "event_name": "LOGS",
                    "event_sequence": 1,
                    "form_name": "CM",
                    "form_sequence": 1,
                    "itemgroup_name": "ig-CM",
                    "itemgroup_sequence": 1,
                    "item_name": "CMTRT",
                    "coding_status": "coded__v",
                    "last_coded_date": "2022-06-02T20:02:26Z",
                    "last_modified_date": "2022-06-02T20:02:26Z",
                    "created_date": "2022-06-02T20:00:44Z",
                    "created_by": "System",
                    "other_properties": {},
                    "indication": "Headache",
                    "route": "Oral",
                    "drug_name": "Aspirin",
                    "drug_code": "00002701004",
                    "preferred_code": "00002701001",
                    "preferred_name": "Acetylsalicylic acid",
                    "atc4_code": "N02BA",
                    "atc4": "Salicylic acid and derivatives",
                    "atc3_code": "N02B",
                    "atc3": "OTHER ANALGESICS AND ANTIPYRETICS",
                    "atc2_code": "N02",
                    "atc2": "ANALGESICS",
                    "atc1_code": "N",
                    "atc1": "NERVOUS SYSTEM"
                },
                {
                    "id": "V0V000000004002",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "Ibuprofen",
                    "start_date": "",
                    "stop_date": "",
                    "eventgroup_name": "LOGS",
                    "eventgroup_sequence": 1,
                    "event_name": "LOGS",
                    "event_sequence": 1,
                    "form_name": "CM",
                    "form_sequence": 2,
                    "itemgroup_name": "ig-CM",
                    "itemgroup_sequence": 1,
                    "item_name": "CMTRT",
                    "coding_status": "open__v",
                    "last_coded_date": "",
                    "last_modified_date": "2022-06-02T20:01:47Z",
                    "created_date": "2022-06-02T20:01:47Z",
                    "created_by": "System",
                    "other_properties": {},
                    "indication": "My indication",
                    "route": "Nasal",
                    "drug_name": "",
                    "drug_code": "",
                    "preferred_code": "",
                    "preferred_name": "",
                    "atc4_code": "",
                    "atc4": "",
                    "atc3_code": "",
                    "atc3": "",
                    "atc2_code": "",
                    "atc2": "",
                    "atc1_code": "",
                    "atc1": ""
                }
            ]
        }
    ]
}

Request - WHODrug requests, filtered to just those with coded or auto coded status

curl --location --request GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/codingrequests?study_name=ABCP-2022-01_DEV1&coding_item_definition_id=V0T000000004001&coding_status=coded__v,autocoded__v' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - WHODrug requests, filtered to just those with coded or auto coded status

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 1,
        "total": 1
    },
    "codingrequests": [
        {
            "coding_item_definition_id": "V0T000000004001",
            "form_coding_status": "active__v",
            "form_type": "cm__v",
            "dictionary_definition": "WHODrug C3",
            "requests": [
                {
                    "id": "V0V000000004001",
                    "study_country": "United States",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "Aspirin",
                    "start_date": "",
                    "stop_date": "",
                    "eventgroup_name": "LOGS",
                    "eventgroup_sequence": 1,
                    "event_name": "LOGS",
                    "event_sequence": 1,
                    "form_name": "CM",
                    "form_sequence": 1,
                    "itemgroup_name": "ig-CM",
                    "itemgroup_sequence": 1,
                    "item_name": "CMTRT",
                    "coding_status": "coded__v",
                    "last_coded_date": "2022-06-02T20:02:26Z",
                    "last_modified_date": "2022-06-02T20:02:26Z",
                    "created_date": "2022-06-02T20:00:44Z",
                    "created_by": "System",
                    "other_properties": {},
                    "indication": "Headache",
                    "route": "Oral",
                    "drug_name": "Aspirin",
                    "drug_code": "00002701004",
                    "preferred_code": "00002701001",
                    "preferred_name": "Acetylsalicylic acid",
                    "atc4_code": "N02BA",
                    "atc4": "Salicylic acid and derivatives",
                    "atc3_code": "N02B",
                    "atc3": "OTHER ANALGESICS AND ANTIPYRETICS",
                    "atc2_code": "N02",
                    "atc2": "ANALGESICS",
                    "atc1_code": "N",
                    "atc1": "NERVOUS SYSTEM"
                }
            ]
        }
    ]
}

Request - MedDRA requests, including external suggestions - one request with two suggestions, the other none

curl --location --request GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/codingrequests?study_name=ABCP-2022-01_DEV1&coding_item_definition_id=V0T000000004001&include_external_suggestions=true
' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - MedDRA requests, including external suggestions - one request with two suggestions, the other none


{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "codingrequests": [
        {
            "coding_item_definition_id": "V0R00000003K001",
            "form_coding_status": "active__v",
            "form_type": "ae__v",
            "dictionary_definition": "MedDRA",
            "dictionary_release": "MedDRA_25_1",
            "requests": [
                {
                    "id": "V0T000000027001",
                    "study_country": "United States",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "Stroke",
                    "start_date": "",
                    "stop_date": "",
                    "eventgroup_name": "egMain",
                    "eventgroup_sequence": 1,
                    "event_name": "evMIN",
                    "event_sequence": 1,
                    "form_name": "AE",
                    "form_sequence": 1,
                    "itemgroup_name": "igAE",
                    "itemgroup_sequence": 1,
                    "item_name": "AETERM",
                    "coding_status": "autocoded__v",
                    "last_coded_date": "2023-04-24T18:40:48Z",
                    "last_modified_date": "2023-04-24T18:40:48Z",
                    "created_date": "2023-04-24T18:40:46Z",
                    "created_by": "System",
                    "other_properties": {},
                    "seriousness": "",
                    "severity": "",
                    "soc_code": "10029205",
                    "soc": "Nervous system disorders",
                    "hlgt_code": "10007963",
                    "hlgt": "Central nervous system vascular disorders",
                    "hlt_code": "10007948",
                    "hlt": "Central nervous system haemorrhages and cerebrovascular accidents",
                    "pt_code": "10008190",
                    "pt": "Cerebrovascular accident",
                    "llt_code": "10042244",
                    "llt": "Stroke",
                    "primary_path": "Y",
                    "external_suggestions": [
                        {
                            "external_definition_name": "my_medcdr_company",
                            "external_id": "123456-ABC",
                            "relevance_score": 5,
                            "external_version": "APR-2023v1.1",
                            "soc_code": "10029205",
                            "soc": "Nervous system disorders",
                            "hlgt_code": "10019231",
                            "hlgt": "Headaches",
                            "hlt_code": "10027603",
                            "hlt": "Migraine headaches",
                            "pt_code": "10027599",
                            "pt": "Migraine",
                            "llt_code": "10027599",
                            "llt": "Migraine",
                            "primary_path": "Y"
                        },
                        {
                            "external_definition_name": "my_medcdr_company",
                            "external_id": "123457-ABC",
                            "relevance_score": 10,
                            "external_version": "APR-2023v1.1",
                            "soc_code": "10029205",
                            "soc": "Nervous system disorders",
                            "hlgt_code": "10007963",
                            "hlgt": "Central nervous system vascular disorders",
                            "hlt_code": "10007948",
                            "hlt": "Central nervous system haemorrhages and cerebrovascular accidents",
                            "pt_code": "10008190",
                            "pt": "Cerebrovascular accident",
                            "llt_code": "10042244",
                            "llt": "Stroke",
                            "primary_path": "Y"
                        }
                    ]
                },
                {
                    "id": "V0T000000027002",
                    "study_country": "United States",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "Stroke",
                    "start_date": "",
                    "stop_date": "",
                    "eventgroup_name": "egMain",
                    "eventgroup_sequence": 1,
                    "event_name": "evMIN",
                    "event_sequence": 1,
                    "form_name": "AE",
                    "form_sequence": 3,
                    "itemgroup_name": "igAE",
                    "itemgroup_sequence": 1,
                    "item_name": "AETERM",
                    "coding_status": "open__v",
                    "last_coded_date": null,
                    "last_modified_date": "2023-04-24T18:40:48Z",
                    "created_date": "2023-04-24T18:40:46Z",
                    "created_by": "System",
                    "other_properties": {},
                    "seriousness": "",
                    "severity": "",
                    "soc_code": "",
                    "soc": "",
                    "hlgt_code": "",
                    "hlgt": "",
                    "hlt_code": "",
                    "hlt": "",
                    "pt_code": "",
                    "pt": "",
                    "llt_code": "",
                    "llt": "",
                    "primary_path": "",
                    "external_suggestions": []
                }
            ]
        }
    ]
}

Request - MedDRA requests, including external suggestions, but only those lacking suggestions

curl --location --request GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/codingrequests?study_name=ABCP-2022-01_DEV1&coding_item_definition_id=V0T000000004001&include_external_suggestions=true&has_external_suggestions=false
' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - MedDRA requests, including external suggestions, but only those lacking suggestions


{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 1,
        "total": 1
    },
    "codingrequests": [
        {
            "coding_item_definition_id": "V0R00000003K001",
            "form_coding_status": "active__v",
            "form_type": "ae__v",
            "dictionary_definition": "MedDRA",
            "dictionary_release": "MedDRA_25_1",
            "requests": [
                {
                    "id": "V0T000000027002",
                    "study_country": "United States",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "Stroke",
                    "start_date": "",
                    "stop_date": "",
                    "eventgroup_name": "egMain",
                    "eventgroup_sequence": 1,
                    "event_name": "evMIN",
                    "event_sequence": 1,
                    "form_name": "AE",
                    "form_sequence": 3,
                    "itemgroup_name": "igAE",
                    "itemgroup_sequence": 1,
                    "item_name": "AETERM",
                    "coding_status": "open__v",
                    "last_coded_date": null,
                    "last_modified_date": "2023-04-24T18:40:48Z",
                    "created_date": "2023-04-24T18:40:46Z",
                    "created_by": "System",
                    "other_properties": {},
                    "seriousness": "",
                    "severity": "",
                    "soc_code": "",
                    "soc": "",
                    "hlgt_code": "",
                    "hlgt": "",
                    "hlt_code": "",
                    "hlt": "",
                    "pt_code": "",
                    "pt": "",
                    "llt_code": "",
                    "llt": "",
                    "primary_path": "",
                    "external_suggestions": []
                }
            ]
        }
    ]
}

Notes

Retrieve a list of Medical Coding Requests for a Form.
For each request, coding status, definition information, and the assigned code (if any) are returned.
The parameter to get existing Medical Coding Requests of a Form (coding_item_definition_id) can be found by first using the Retrieve Coding Definitions API endpoint.

Endpoint

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

Required Permissions

The following permissions are required to use the Retrieve Coding Requests API:

API Access
View Code

The CDMS API Read Write and CDMS API Read Only roles grant these permissions.

Headers

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

Query String Parameters

Name	Description
`study_name`	Name of the Study
`coding_item_definition_id`	Specific medical coding definition of requests to return. The value is part of the Study design, and can be found using Retrieve Coding Definitions, specifically the `coding_item_definition_id` in that response.
`study_country`	Optional Name of the Study Country to filter the return on.
`site`	Optional Name of the Site to filter to. One must include the `study_country` when including.
`subject`	Optional Name (ID/number) to filter to. One must include `site` when including.
`last_modified_date`	Optional Retrieve only requests modified after this datetime. Use the format "yyyy-MM-ddTHH:mm:ssZ".
`coding_status`	Optional Retrieve only those requests of certain status (or statuses, if multiple, use comma separated value). Valid status values are - `open__v`, `autocoded__v`, `uncoded__v`, `noncurrent__v`, `coded__v`, `rejected__v`, `pending_approval__v`, `not_to_be_coded__v`, `better_code_found__v`, or `updated__v`.
`include_external_suggestions`	Optional Boolean value, whether or not to include any external suggestions to the requests. Default when omitted is `false`. Also note that the Study must also be configured with an external suggestion definition to return this information in the response.
`has_external_suggestions`	Optional Boolean value, when included, will filter the return to just those requests with external suggestions (`true`) in place, or not (`false`). When omitted, there is no filter one way or the other.

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

On SUCCESS, Vault returns a list of Medical Coding Requests (as JSON array entries) with the following information:

Array	Name	Description
`codingrequests`	`coding_item_definition_id`	Vault internal ID for the Study definition of the coding Item. (pre v22.3, this was `coding_item_definition`, now renamed to be in line with the Retrieve Coding Definitions API
`codingrequests`	`form_coding_status`	The status of the Study definition of the coding at the Form (of the Item being coded). Formerly named `form_status` (pre v22.3), but clarified in name for which status regarding the definition. If the coding of the Study is not fully setup, a return here of `needs_dictionary__v` is likely.
`codingrequests`	`form_type`	The coding definition type of Form, e.g. 'AE'. This is the picklist name (e.g. `ae__v`, `cm__v`, `other__v`)
`codingrequests`	`dictionary_definition`	The type of coding at that location, e.g. WHODrug B3, WHODrug C3, or MedDRA
`codingrequests/requests`	`id`	The Vault internal ID of the Medical Coding Request. Use this value when opening a Query on the coding request (Open Coding Queries)
`codingrequests/requests`	`study_country`	Name of the Study Country for the site of the Subject
`codingrequests/requests`	`site`	Name of the Site for the Subject (NOTE: Study Country to also be returned in a future release. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`codingrequests/requests`	`subject`	Name (ID/number) of the Subject
`codingrequests/requests`	`verbatim`	The current value in the Item being coded, e.g. Severe Headache
`codingrequests/requests`	`start_date`	The value in the field mapped to start date (on the Form of the Item being coded)
`codingrequests/requests`	`end_date`	The value in the field mapped to end date (on the Form of the Item being coded)
`codingrequests/requests`	`eventgroup_name`	Study design name for Event Group
`codingrequests/requests`	`event_sequence`	The sequence of the Event Group
`codingrequests/requests`	`event_name`	Study design name for the Event (pre v22.3, this was the label and `event`, changed for consistency with other endpoints)
`codingrequests/requests`	`event_sequence`	Currently, always a 1. If the Event within a repeating Event Group the sequence increments at the `evengroup_sequence` level.
`codingrequests/requests`	`form_name`	Study design name for the Form (pre v22.3, this was the label and `form`, changed for consistency with other endpoints)
`codingrequests/requests`	`form_sequence`	The specific Form sequence
`codingrequests/requests`	`itemgroup_name`	Study design name for Item Group (pre v22.3, this was the label and `item_group`, changed for consistency with other endpoints)
`codingrequests/requests`	`itemgroup_sequence`	The specific Item Group sequence (pre v22.3, `item_group_sequence`, changed for consistency with other endpoints)
`codingrequests/requests`	`item_name`	Study design name for the Item (pre v22.3, this was the label and `item`, changed for consistency with other endpoints)
`codingrequests/requests`	`coding_status`	The current status of the coding request, e.g. `open__v`, `coded__v`, etc. (pre v22.3, this was the label, changed for consistency with other endpoints)
`codingrequests/requests`	`last_coded_by_third_party`	The datetime that the request last had coding assigned / selected / auto coded by an external system from CDMS (UTC). Omitted when not set - a future release of CDMS will support 3rd party coding.
`codingrequests/requests`	`last_coded_date`	The datetime that the request last had coding assigned / selected / auto coded (UTC)
`codingrequests/requests`	`assigned_to_third_party`	If coding from another system involved, who in that other system the request is assigned. Omitted when not set - a future release of CDMS will support 3rd party coding.
`codingrequests/requests`	`last_modified_date`	The datetime that the request was last modified in any way (UTC)
`codingrequests/requests`	`created_date`	The datetime that the request was first created (UTC)
`codingrequests/requests`	`created_by`	Name (First Last) of the User who created the request
`codingrequests/requests`	`other_properties`	If study design uses, a set of label/value pairs (JSON array entries), i.e., other values on the Form
`codingrequests/requests`	`seriousness`	(MedDRA only) If the study design maps an Item on that same Form for seriousness, the value in that Item
`codingrequests/requests`	`severity`	(MedDRA only) If the study design maps an Item on that same Form for severity, the value in that Item
`codingrequests/requests`	`llt_code`	(MedDRA only) - numeric value of coding assignment at this level
`codingrequests/requests`	`llt`	(MedDRA only) - text value of coding assignment at this level
`codingrequests/requests`	`pt_code`	(MedDRA only)- numeric value of coding assignment at this level
`codingrequests/requests`	`pt`	(MedDRA only)- text value of coding assignment at this level
`codingrequests/requests`	`hlt_code`	(MedDRA only)- numeric value of coding assignment at this level
`codingrequests/requests`	`hlt`	(MedDRA only)- text value of coding assignment at this level
`codingrequests/requests`	`hlgt_code`	(MedDRA only)- numeric value of coding assignment at this level
`codingrequests/requests`	`hlgt`	(MedDRA only)- text value of coding assignment at this level
`codingrequests/requests`	`soc_code`	(MedDRA only)- numeric value of coding assignment at this level
`codingrequests/requests`	`soc`	(MedDRA only)- text value of coding assignment at this level
`codingrequests/requests`	`primary_path`	(MedDRA only) Values of Y or N only. If multiple paths involved for the coding assignment, whether it is the primary path (or not)
`codingrequests/requests`	`indication`	(WHODrug only) If the study design maps an Item on that same Form for indication, the value in that Item
`codingrequests/requests`	`route`	(WHODrug only) If the study design maps an Item on that same Form for route, the value in that Item
`codingrequests/requests`	`drug_name`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`drug_code`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`preferred_code`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`preferred_name`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`atc4_code`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`atc4`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`atc3_code`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`atc3`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`atc2_code`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`atc2`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`atc1_code`	(WHODrug only) Property from the coding that is assigned
`codingrequests/requests`	`atc1`	(WHODrug only) Property from the coding that is assigned

Retrieve Coding Queries

Request

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/queries?study_name=ABCP-2022-01_DEV1&coding_item_definition=V0R000000006001,V0R000000007001' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
                         "limit": 2,
                         "offset": 0,
                         "size": 2,
                         "total": 2
    },
    "queries": [
        {
            "id": "OPW000000000201"
            "query_name": "VV-000002",
            "manual": true,
            "created_date": "2019-11-21T22:40:49Z",
            "created_by": "John Doe",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "eventgroup_name": "Common Logs",
            "eventgroup_sequence": 1,
            "event_name": "Common Logs",
            "event_sequence": 1,
            "form_name": "Adverse Event",
            "form_sequence": 1,
            "itemgroup_name": "Adverse Event",
            "itemgroup_sequence": 1,
            "item_name": "AETERM",
            "rule_definition": "DM_001",
            "coding_item_definition": "V0R000000006001",
            "messages": [
                {
                    "id": "OPY000000000301",
                    "activity": "open__v",
                    "message": "Can you relook at this verbatim?",
                    "message_date": "2019-11-21T22:40:50Z",
                    "message_by": "John Doe"
                },
                {
                    "id": "OPY000000000302",
                    "activity": "answered__v",
                    "message": "I updated it, take another look.",
                    "message_date": "2019-11-21T22:41:50Z",
                    "message_by": "Jane Doe"
                },
                {
                    "id": "OPY000000000303",
                    "activity": "closed__v",
                    "message": "Perfect, thanks.",
                    "message_date": "2019-11-21T22:42:50Z",
                    "message_by": "John Doe"
                }
            ]
        },
        {
            "id": "OPW000000000801",
            "query_name": "VV-000002",
            "manual": true,
            "created_date": "2019-11-21T22:40:49Z",
            "created_by": "John Doe",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "101",
            "subject": "101-001",
            "eventgroup_name": "Common Logs",
            "eventgroup_sequence": 1,
            "event_name": "Common Logs",
            "event_sequence": 1,
            "form_name": "Adverse Event",
            "form_sequence": 1,
            "itemgroup_name": "Adverse Event",
            "itemgroup_sequence": 1,
            "item_name": "AETERM",
            "rule_definition": "DM_002",
            "coding_item_definition": "V0R000000007001"
            "messages": [
                {
                    "id": "OPY000000000301",
                    "activity": "open__v",
                    "message": "Can you relook at this verbatim?",
                    "message_date": "2019-11-21T22:40:50Z",
                    "message_by": "John Doe"
                },
                {
                    "id": "OPY000000000302", 
                    "activity": "answered__v",
                    "message": "I updated it, take another look.",
                    "message_date": "2019-11-21T22:41:50Z",
                    "message_by": "Jane Doe"
                },
                {
                    "id": "OPY000000000303",
                    "activity": "closed__v",
                    "message": "Perfect, thanks.",
                    "message_date": "2019-11-21T22:42:50Z",
                    "message_by": "John Doe"
                }
            ]
        }
    ]
}

Notes

Use this API to retrieve the existing Queries using medical coding definitions, i.e. Queries created using Open Coding Queries.
Queries opened any other way are not part of this response
For the coding_item_definition parameter, the appropriate value can be found using Retrieve Coding Definitions, it's coding_item_definition_id value returned.
The response includes a messages array with each comment/message appended to the Query. Reading top down in that array also reveals the progression of Query status, and by whom

Endpoint

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

Required Permissions

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

API Access
View Casebook
View Code
View Query (if this feature is enabled in your Vault)

The CDMS API Read Write and CDMS API Read Only roles grant these permissions.

Headers

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

Query String Parameters

Name	Description
`study_name`	Name of the Study
`coding_item_definition`	Specific medical coding definition (use comma-separated for multiple) to filter against. That is, queries added using Open Coding Queries against those definition(s). The value(s) are part of the Study design, and can be found using Retrieve Coding Definitions, values from `coding_item_definition_id` in that response.
`last_modified_date`	Optional Retrieve only Queries modified after this datetime. Use the format "yyyy-MM-ddTHH:mm:ssZ".

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

On SUCCESS, Vault returns a list of Queries (as JSON array entries) with the following information:

Array	Name	Description
`queries`	`id`	Vault internal ID for the Query
`queries`	`query_name`	Another Vault internal ID for the Query, this one is visible from the UI
`queries`	`manual`	Whether the query is classified System (false) or Manual (true)
`queries`	`query_status`	Values will be one of `open__v`, `answered__v`, or `closed__v`
`queries`	`study_country`	Name of the Study Country for the site of the Subject
`queries`	`site`	Name of the Site for the Subject. Name here refers to the Name field in Vault. It is alphanumeric and may consist of numbers, letters, or both.
`queries`	`subject`	Name (ID/number) of the Subject
`queries`	`eventgroup_name`	Study design name for the Event Group
`queries`	`eventgroup_sequence`	Sequence of the Event Group of the Event. If repeating Event Group the value increments starting at 1, 2.... If it does not repeat, then 1 is always returned
`queries`	`event_name`	Study design name for a the Event
`queries`	`event_sequence`	Currently, always a 1. If the Event within a repeating Event Group the sequence increments at the `evengroup_sequence` level
`queries`	`form_name`	(When attached to an Item only, omitted for Event queries) Study design name for a Form
`queries`	`form_sequence`	(When attached to an Item only, omitted for Event queries) If the Form repeats per Study design, these increment starting at 1, 2.... If it does repeat, 1 is always returned.
`queries`	`itemgroup_name`	(When attached to an Item only, omitted for Event queries) Study design name of the Item Group
`queries`	`itemgroup_sequence`	(When attached to an Item only, omitted for Event queries) The specific Item Group sequence
`queries`	`item_name`	(When attached to an Item only, omitted for Event queries) Study design name of the Item
`queries`	`rule_definition`	When a Query originating from a Study design rule, that rule name. Omitted otherwise.
`queries`	`coding_item_definition`	When a Query originating from Open Coding Queries, that medical coding definition name. Omitted otherwise.
`queries`	`created_date`	The datetime that the Query was first created (UTC)
`queries`	`created_by`	Name (Firstname Lastname) of the User who created the Query
`queries/messages`	`id`	Vault internal ID of the Query message. These entries reading top to bottom (in the array) comprise the movement of statuses, plus comments of the Query
`queries/messages`	`activity`	The Query status at that entry. Values will be one of `open__v`, `answered__v`, or `closed__v`
`queries/messages`	`message`	The message at that Query update. Some activity entries do not include a specific message (e.g. close of an added Query)
`queries/messages`	`message_date`	The datetime that this message/status change (UTC)
`queries/messages`	`message_by`	Name (Firstname Lastname) of the User who moved the status / commented at this revision of the Query

Open Coding Queries

Request

$ curl -X POST \
    https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/actions/openquery \
    -H "Authorization: {SESSION_ID}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
             "study_name": "ABCP-2022-01_DEV1",
             "queries": [
               {
                 "coding_request": "V0T00000000R001",                   
                 "message": "Can you relook at this verbatim?"
               },
               {
                 "coding_request": "V0T00000000R002",                  
                 "message": "Can you relook at this verbatim?"
               }    
             ]   
}'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
                {
                    "responseStatus": "SUCCESS",          
                    "id": "OPM000000000502",          
                    "query_name": "VV-000002",        
                    "query_status": "open__v",
                    "coding_request": "V0T00000000R001"
                },    
                {      
                    "responseStatus": "SUCCESS",          
                    "id": "OPM000000000502",          
                    "query_name": "VV-000002",        
                    "query_status": "open__v",
                    "coding_request": "V0T00000000R002"
                }
    ]
}

Notes

The action is used to add a new Query to an Item who is tagged with a specific Medical Coding Request.
The id of the Medical coding Request is used to add the Query (Item that the coding request is tied to)
WARNING: A locked Form will not allow the add a new Query, just as the EDC UI would disallow. Frozen Forms / Items will accept new Queries added via the API.
For further manipulation of Queries (answer, close, re-open), it's good practice to inspect the return on Query API actions, for the id value.
The API user role must have permission to add Queries.
The limit for actions in one request is 100.
Other options exist to open a new Query, see also:
- Open Queries - a Query added by specifying the context of the location (Study Country, Site, Subject, Event Group, etc.)
- Open Queries by Event ID - a Query added against a specific Event, when the Vault ID of that Event is known
- Open Queries by Item ID - a Query added against a specific Item, when the Vault ID of that Item is known

Endpoint

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

Required Permissions

The following permissions are required to use the Open Coding Queries API:

API Access
View Casebook
Open Query
View Code

The CDMS API Read Write grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`coding_request`	`queries`	The Vault internal ID of the Medical Coding Request to open the Query on. This request was added on submit of a Form that contains an Item being coded in Vault CDMS Coder. The value to use is the `id` found from Retrieve Coding Requests response.
`message`	`queries`	The initial message of the Query

Set Coding Suggestions

Request - MedDRA suggestions

$ curl -X POST \
    https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/actions/setcodingsuggestions \
    -H "Authorization: {SESSION_ID}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '
{
    "study_name": "ABCP-2022-01_DEV1",
    "external_definition_name": "API_company_name_here",  
    "requests": [
    {
        "id": "V0V000000003002",
        "dictionary_release": "MedDRA_25_1",
        "verbatim": "Severe Headache",
        "external_suggestions": [
        {                   
            "external_id": "123456-ABC",
            "relevance_score": 5,
            "external_version": "JAN-2022v1.1", 
            "soc": "Nervous system disorders",
            "soc_code": "10029205",
            "hlgt_code": "10019231",
            "hlgt": "Headaches",
            "hlt_code": "10027603",
            "hlt": "Migraine headaches",
            "pt_code": "10027599",
            "pt": "Migraine",
            "llt_code": "10027599",
            "llt": "Migraine",
            "primary_path": "Y"
        },
        {                   
            "external_id": "123457-ABC",
            "relevance_score": 4,
            "external_version": "JAN-2022v1.1", 
              :
              ... etc...
              :

        },
        :
        : etc.. 5 suggestions for this coding request
        :
        ]              
    },
    {
        "id": "V0V000000003003",
        "dictionary_release": "MedDRA_25_1",
        "verbatim": "Back pain",
        "external_suggestions": [       
        :
        : etc.. 3 suggestions for this coding request here...
        :
        ]
    }
    ]
}'

Response - MedDRA suggestions

{      
    "responseStatus": "SUCCESS",      
    "study_name": "ABCP-2022-01_DEV1",
    "external_definition_name": "API_company_name_here",  
    "requests": [
        {
            "responseStatus": "SUCCESS",
            "id": "V0V000000003002",
            "dictionary_release": "MedDRA_25_1",
            "verbatim": "Severe Headache",
            "external_suggestions": 5
        },
        {          
            "responseStatus": "SUCCESS",
            "id": "V0V000000003003",
            "dictionary_release": "MedDRA_25_1",
            "verbatim": "Back pain",
            "external_suggestions": 3
        }         
}

Request - WHODrug suggestions

$ curl -X POST \
    https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/actions/setcodingsuggestions \
    -H "Authorization: {SESSION_ID}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '
{
    "study_name": "ABCP-2022-01_DEV1",
    "external_definition_name": "API_company_name_here",    
    "requests": [
        {
            "id": "V0V000000003002",
            "dictionary_release": "GLOBALC3Mar19",
            "verbatim": "Aspirin",
            "indication": "Headache",
            "route": "Oral",
            "external_suggestions": [
                {                                        
                    "external_id": "1234345-XYZ",
                    "relevance_score": 100,
                    "external_version": "JAN-2022v1.1", 
                    "drug_name": "Aspirin",
                    "drug_code": "00002701004",
                    "preferred_code": "00002701001",
                    "preferred_name": "Acetylsalicylic acid",                     
                    "atc1_code": "N",
                    "atc1": "NERVOUS SYSTEM"
                    "atc2_code": "N02",
                    "atc2": "ANALGESICS",
                    "atc3_code": "N02B",
                    "atc3": "OTHER ANALGESICS AND ANTIPYRETICS",                     
                    "atc4_code": "N02BA",
                    "atc4": "Salicylic acid and derivatives",
                }
                {
                    "external_id": "1234345-XYZ",
                    "relevance_score": 95,
                    "external_version": "JAN-2022v1.1", 
                      ... etc...

                },
            :
            : etc.. 5 suggestions for this coding request
            :
            ]              
        },
        {
            "id": "V0V000000003003",
            "dictionary_release": "GLOBALC3Mar19",
            "verbatim": "Ibuprofen",
            "indication": "Joint Pain",
            "route": "Oral",             
            "external_suggestions": [
            :
            : etc.. 3 suggestions for this coding request here...
            :
            ]   
        }       
    ]
}'

Response - WHODrug suggestions

{    
    "responseStatus": "SUCCESS",
    "study_name": "ABCP-2022-01_DEV1",
    "external_definition_name": "API_company_name_here",   
    "requests": [
        {
            "responseStatus": "SUCCESS",
            "id": "V0V000000003002",
            "verbatim": "Aspirin", 
            "indication": "Headache",
            "route": "Oral",            
            "dictionary_release": "GLOBALC3Mar19",
            "external_suggestions": 5
        },
        {
            "responseStatus": "SUCCESS",
            "id": "V0V000000003003",
            "verbatim": "Ibuprofen", 
            "indication": "Joint Pain",
            "route": "Oral",                         
            "dictionary_release": "GLOBALC3Mar19",
            "external_suggestions": 3
        }
}

Request - Remove suggestions from a coding request

$ curl -X POST \
    https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/actions/setcodingsuggestions \
    -H "Authorization: {SESSION_ID}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '
{
    "study_name": "ABCP-2022-01_DEV1",
    "external_definition_name": "API_company_name_here",    
    "requests": [
        {
            "id": "V0V000000003002",
            "dictionary_release": "GLOBALC3Mar19",
            "external_suggestions": []
        }
    ]
}'

Response - Remove suggestions from a coding request

{    
    "responseStatus": "SUCCESS",
    "study_name": "ABCP-2022-01_DEV1",
    "external_definition_name": "API_company_name_here",   
    "requests": [
        {
            "responseStatus": "SUCCESS",
            "id": "V0V000000003002",
            "verbatim": "Aspirin", 
            "indication": "Headache",
            "route": "Oral",            
            "dictionary_release": "GLOBALC3Mar19",
            "external_suggestions": 0
        }
}

Request - Top level failure (study not configured)

$ curl -X POST \
    https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/actions/setcodingsuggestions \
    -H "Authorization: {SESSION_ID}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '
{
    "study_name": "ABCP-2022-01_DEV1",
    "external_definition_name": "API_company_name_here_bad_name",    
    "requests": [
        {
            "id": "V0V000000003002",
            "dictionary_release": "GLOBALC3Mar19",
            "external_suggestions": [
                :
                ...etc..
                :
            ]
        },
            :
            etc.. more requests and suggestions
            :
    ]
}'

Response - Top level failure (study not configured)

{
    "responseStatus": "FAILURE",
    "errorMessage": "[External Definition Name] with name [API_company_name_here_bad_name] not found in _Study_ configuration for external suggestions"
}

Request - Entry level failure (one succeeds, one fails)

$ curl -X POST \
    https://my-vault.veevavault.com/api/v24.1/app/cdm/coder/actions/setcodingsuggestions \
    -H "Authorization: {SESSION_ID}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '
{
    "study_name": "ABCP-2022-01_DEV1",
    "external_definition_name": "API_company_name_here",  
    "requests": [
        {
            "id": "V0V000000003002",
            "dictionary_release": "MedDRA_25_1",
            "verbatim": "Severe Headache",
            "external_suggestions": [
                {                   
                    "external_id": "123456-ABC",
                    "relevance_score": 5,
                    "external_version": "JAN-2022v1.1", 
                    "soc": "Nervous system disorders",
                    "soc_code": "10029205",
                    "hlgt_code": "10019231",
                    "hlgt": "Headaches",
                    "hlt_code": "10027603",
                    "hlt": "Migraine headaches",
                    "pt_code": "10027599",
                    "pt": "Migraine",
                    "llt_code": "10027599",
                    "llt": "Migraine",
                    "primary_path": "Y"
                }
                {                   
                    "external_id": "123457-ABC",
                    "relevance_score": 4,
                    "external_version": "JAN-2022v1.1", 
                      ... etc...

                },
                {
                    ... etc... other suggestions
                }
            ]              
        },
        {
            "id": "V0V000000003002",
            "dictionary_release": "MedDRA_25_1",
            "verbatim": "Back pain",
            "external_suggestions": [ 
            :
            : etc.. 3 suggestions for this coding request here... but verbatim is stale / out of date
            :            
            ]
        }       
    ]
}'

Response - Entry level failure (one succeeds, one fails)

{      
    "responseStatus": "SUCCESS",      
    "study_name": "ABCP-2022-01_DEV1",
    "external_definition_name": "My Company Name",  
    "requests": [
        {
            "responseStatus": "SUCCESS",
            "id": "V0V000000003002",
            "dictionary_release": "MedDRA_25_1",
            "verbatim": "Severe Headache",
            "external_suggestions": 5
        },
        {          
            "responseStatus": "FAILURE",
            "errorMessage": "The verbatim submitted with the suggestions is no longer the verbatim in the system.   Suggestions were not updated for the coding request.", 
            "id": "V0V000000003003",
            "dictionary_release": "MedDRA_25_1",
            "verbatim": "Severe back pain"
        }        
}

Notes

The action is used to set external coding suggestions to specific Medical Coding Requests.
The action will DELETE existing suggestions (for a request that has them currently), and replace with the new set posted (no upsert)
To unset a request that has suggestions to have none, simply use "external_suggestions": []. (empty array of suggestions)
Each suggestion (of request) is validated against a match of dictionary version (current on the Med Coding Request) and vendor/company name.
Optionally include verbatim / route / indication values with the post of suggestions. This will check that the values have not changed recently, i.e. perhaps the suggestions no longer apply.
Each Study must be activated in it’s Study settings to use external suggestions. The company/vendor on the post then also must match the API Name as set up in the Vault for that company/vendor.
WARNING: For WHODrug coding, whether the ATC1 (or other levels) is required depends on that Study's setting in the Vault for medical coding.
Suggestions posted to one coding request is limited to 5.
The limit for actions in one API post is 100. (coding requests)
Use Retrieve Coding Requests, including suggestions in the response to observe current state of requests to their suggestions. The parameter/value of has_suggestions=false will filter to requests needing suggestions.

Endpoint

POST /api/{version}/app/cdm/coder/actions/setcodingsuggestions

Required Permissions

The following permissions are required to use the Open Coding Queries API:

API Access
View Casebook
Manage Coding

The role CDMS API Read Write grants these permissions.

Headers

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

Body Parameters

Name	Array	Description
`study_name`		Name of the Study
`external_definition_name`		The API Name of the external suggestions definition in the Vault. This is setup once, then must also be applied to the Studies that will use the external suggestions concept.
`id`	`requests`	The `id` value for the Medical Coding Request. These values can be found in the responses from Retrieve Coding Requests
`dictionary_release`	`requests`	This value must match the current dictionary version (`name__v` value) of that coding Form in the Study. The current value can be found both at Retrieve Coding Definitions and with each response entry returned in Retrieve Coding Requests. If passed in the attempt, and it does not match the current value in CDMS, the attempt on the coding request is rejected.
`verbatim`	`requests`	Optional When passed with the attempt, the current value of the value is checked in the Study. This is helpful in ensuring the value used in the external coding algorithm is still the same in the Study, at the time of posting the suggestions. Later changes to this in the system will appropriately remove suggestions since they no longer apply. If the value is not passed, the extra check is not performed.
`indication`	`requests`	Optional (WHODrug only) When passed with the attempt, the current value of the value is checked in the Study. This is helpful in ensuring the value used in the external coding algorithm is still the same in the Study, at the time of posting the suggestions. Later changes to this in the system will appropriately remove suggestions since they no longer apply. If the value is not passed, the extra check is not performed. WARNING: A Study must be configured for the coding Form to use this property.
`route`	`requests`	Optional (WHODrug only) When passed with the attempt, the current value of the value is checked in the Study. This is helpful in ensuring the value used in the external coding algorithm is still the same in the Study, at the time of posting the suggestions. Later changes to this in the system will appropriately remove suggestions since they no longer apply. If the value is not passed, the extra check is not performed. WARNING: A Study must be configured for the coding Form to use this property.
`external_id`	`../external_suggestions`	Optional Use this field to set a value meaningful to the remote system / algorithm, e.g. an ID from a database storing these suggestion combinations.
`relevance_score`	`../external_suggestions`	This is the value for the suggestion that ranks it amongst other suggestions of the same request. The higher the number, the better the ranking, i.e. appearing at the top in the user interface. For example, suggestions with relevance score of 10, 70, 40, 95, 20 in the post of five suggestions would be ordering in the Coder user interface (reading down) in order 95,70,40,20,10
`external_version`	`../external_suggestions`	Optional Use this field to set a value meaningful to the remote system / algorithm, e.g. its version when the suggestion was generated.
`soc_code`	`../external_suggestions`	(MedDRA only) The soc_code value for the suggestion
`soc`	`../external_suggestions`	(MedDRA only) The soc value for the suggestion
`hlgt_code`	`../external_suggestions`	(MedDRA only) The hlgt_code value for the suggestion
`hlgt`	`../external_suggestions`	(MedDRA only) The hlgt value for the suggestion
`hlt_code`	`../external_suggestions`	(MedDRA only) The hlt_code value for the suggestion
`hlt`	`../external_suggestions`	(MedDRA only) The hlt value for the suggestion
`pt_code`	`../external_suggestions`	(MedDRA only) The pt_code value for the suggestion
`pt`	`../external_suggestions`	(MedDRA only) The pt value for the suggestion
`llt_code`	`../external_suggestions`	(MedDRA only) The llt_code value for the suggestion
`llt`	`../external_suggestions`	(MedDRA only) The llt value for the suggestion
`primary_path`	`../external_suggestions`	Optional (MedDRA only) The primary path value for the suggestion - only values of Y (Yes) or N (No) allowed.
`drug_code`	`../external_suggestions`	(WHODrug only) The drug_code value for the suggestion
`drug_name`	`../external_suggestions`	(WHODrug only) The drug_name value for the suggestion
`preferred_code`	`../external_suggestions`	(WHODrug only) The preferred_code value for the suggestion
`preferred_name`	`../external_suggestions`	(WHODrug only) The preferred_name value for the suggestion
`atc1_code`	`../external_suggestions`	Optional (!) (WHODrug only) WARNING: Can be Required, depending on Study configuration. The atc1_code value for the suggestion
`atc1`	`../external_suggestions`	Optional (!) (WHODrug only) WARNING: Can be Required, depending on Study configuration. The atc1 value for the suggestion
`atc2_code`	`../external_suggestions`	Optional (WHODrug only) The atc2_code value for the suggestion
`atc2`	`../external_suggestions`	Optional (WHODrug only) The atc2 value for the suggestion
`atc3_code`	`../external_suggestions`	Optional (WHODrug only) The atc3_code value for the suggestion
`atc3`	`../external_suggestions`	Optional (WHODrug only) The atc3 value for the suggestion
`atc4_code`	`../external_suggestions`	Optional (WHODrug only) The atc4_code value for the suggestion
`atc4`	`../external_suggestions`	Optional (WHODrug only) The atc4 value for the suggestion

Jobs

Job Summary / Types

For Vault CDMS, a Job (also known as Study Job) processes against a Study, either updating data, or generating information about the Study. In the current release, we only support data extract related jobs in the API.

The following job types are currently supported:

Name	API Name	Description
Study Data Extract (SDE)	`study_data_extract__v`	Generates ZIP of CSV files (with/without SAS and SAS XPT files). The file includes clinical datasets (Form data), system/operational datasets, custom objects involved with the Study, and/or Study definitions. This export is the primary and most comprehensive full export of Study data. It can be run in subset for faster execution, e.g., just Adverse Events, SYS_Q (queries), and so forth. Learn more about the content of the SDE can be found at CDMS Help
Subject Progress Listing	`subject_progress_listings__v`	Generates CSV of metrics at Subject level. This summary is not Study design specific, instead primarily operational data, statuses, row per Subject
Subject Progress Listing (Versioned)	`subject_progress_versioned_extract__v`	(Requires Veeva enablement for your Vault) Same/similar content as `subject_progress_listings__v`, but with a version required. Similar to the SDE in that the structure of the output won't change for a version consistently supplied to start (or schedule) the job. Additionally, this job type can also be forwarded to a Veeva FTP site on completion.
Event Progress Listing	`event_progress_listing__v`	Generates CSV of metrics at Event level. This summary is not Study design specific, although is a 'row per event' of the Study design. Each row includes operational / status information about the Event.
Event Progress Listing (Versioned)	`event_progress_versioned_extract__v`	(Requires Veeva enablement for your Vault) Same/similar content as `event_progress_listing__v`, but with a version required. Similar to the SDE in that the structure of the output won't change for a version consistently supplied to start (or schedule) the job. Additionally, this job type can also be forwarded to a Veeva FTP site on completion.
Form Progress Listing	`form_progress_listing__v`	Generates CSV of metrics at Form level. This summary is not Study design specific, although is a 'row per Form' of the Study design. Each row includes operational / status information about the Form.
Form Progress Listing (Versioned)	`form_progress_versioned_extract__v`	(Requires Veeva enablement for your Vault) Same/similar content as `form_progress_listing__v`, but with a version required. Similar to the SDE in that the structure of the output won't change for a version consistently supplied to start (or schedule) the job. Additionally, this job type can also be forwarded to a Veeva FTP site on completion.
Query Detail Listing	`query_detail_listing__v`	Generates CSV of metrics at Query level. This summary is not Study design specific, although each row will indicate the location (of Study design) of the Query.
Query Detail Listing (Versioned)	`query_detail_versioned_extract__v`	(Requires Veeva enablement for your Vault) Same/similar content as `query_detail_listing__v`, but with a version required. Similar to the SDE in that the structure of the output won't change for a version consistently supplied to start (or schedule) the job. Additionally, this job type can also be forwarded to a Veeva FTP site on completion.
Core Listing	`core_listing__v`	Predecessor to the SDE. Generates ZIP of CSVs for each Form, but without Study definition. It can be run on subset(s) of Forms and/or Sites. (Format different from the SDE)
Data and Definition Export (Deprecated)	`data_and_definition_export__v`	Predecessor to the SDE, also once known as the `JReview` job type. Generates a ZIP file of CSVs representing collected data in your Study, as well as definitions. (Format different from the SDE)
Audit Trail by Study	`audit_trail_export__v`	Job that produces audit trail reporting, with specified start to end date ranges and/or specific users. The result of the job is a zip file containing CSVs, by Subject. The range of start to end can be no more than 30 days when starting this job from the API. Wider ranges are started from the EDC Tools user interface.
Audit Trail by Site	`audit_trail_export_by_site__v`	Job that produces audit trail reporting, with specified start to end date ranges, specific users, and/or specific sites. The result of the job is a zip file containing CSVs, by Subject. The range of start to end can be no more than 30 days when starting this job from the API. Wider ranges are started from the EDC Tools user interface.
Audit Trail by Subject	`audit_trail_export_by_subject__v`	Job that produces audit trail reporting, with specified start to end date ranges, specific users, and/or specific Subjects. The result of the job is a zip file containing CSVs, by Subject. The range of start to end can be no more than 30 days when starting this job from the API. Wider ranges are started from the EDC Tools user interface.
Data Change Report	`data_change_report__v`	Job that produces changes to Items, with specified start to end date ranges, Forms (or all), and with/without restricted data. Optionally, send the resulting results to a Vault FTP folder. The range of start to end can be no more than 90 days when starting this job from the API, and the job can be configured with just 'Last X Days' (vs. specific dates). Wider ranges are started from the EDC Tools user interface.
Casebook Design Export	`casebook_design_export__v`	Job that generates a JSON file of the Study design. Included in the content are the schedule of the Study, all Form designs of the schedule, codelists, unit definition, coding definitions, and Study settings. Each job run (file) is one to one with a specific casebook version of the Study design.
Safety Follow-Up Scan	`safety_integrations_follow_up_scan__v`	For Studies with the CDMS Safety Integrations module enabled, this job will start a job that scans for any appropriate follow-up sends to a safety system. The job can be run to detect recent changes (since last job run) OR in full (scanning every safety case). If a scheduled job is in place for the Study, this is largely unnecessary. Instead, it's purpose is for cases where the start of the scanning is to be driven by conditions outside Vault CDMS.

For cases where a recurring job already runs, Retrieve Study Jobs can be used to detect recently finished jobs, across multiple Studies. In this way, a single integration API job can easily detect new Studies deployed to a Vault and retrieve now executing data export files.

If using the API to start a Job, you can monitor the status of a Job using Retrieve Job Status or in the UI by accessing Tools > EDC Tools > Job History.

To download the output files for a Job, use Retrieve Job Output File or download from Tools > EDC Tools > Job History.

Learn more about managing jobs in CDMS Help.

Retrieve Study Jobs

Request - Single Study, SDE type, default date filters, no status filter (7 days ago to now, assuming run on July 1st, 2022)

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs?study_name=ABCP-2022-01_DEV1&&job_type=study_data_extract__v' \
-H 'Authorization: {SESSION_ID}'

Response - Single Study, SDE type, default date filters, no status filter (7 days ago to now, assuming run on July 1st, 2022)

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
     "created_start": "2022-06-01T12:00:00Z",
     "created_end": null,
     "jobs": [
          {
            "job_id": 324003,
            "job_type": "study_data_extract__v",
            "study_name": "ABCP-2022-01_DEV1",
            "status": "completed__v",
            "created_by": "John Smith",
            "created_date": "2022-06-02T12:14:42Z",
            "last_modified_date": "2022-06-02T12:20:42Z"
          },
          {
            "job_id": 324002,
            "job_type": "study_data_extract__v",
            "study_name": "ABCP-2022-01_DEV1",
            "status": "errors__v",
            "created_by": "John Smith",
            "created_date": "2022-06-01T08:14:42Z",
            "last_modified_date": "2022-06-01T08:02:42Z"
          }
      ]
}

Request - Multiple Studies, SDE type, specific range of job created dates, no status filter

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs?job_type=study_data_extract__vcreated_start=2022-05-20T12:00:00Z&created_end=2022-06-01T12:00:00Z' \
-H 'Authorization: {SESSION_ID}'

Response - Multiple Studies, SDE type, specific range of job created dates, no status filter

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 5,
        "total": 5
    },
     "created_start": "2022-05-20T12:00:00Z",
     "created_end": "2022-06-01T12:00:00Z",
     "jobs": [
          {
            "job_id": 324002,
            "job_type": "study_data_extract__v",
            "study_name": "ABCP-2022-01_DEV1",
            "status": "errors__v",
            "created_by": "John Smith",
            "created_date": "2022-06-01T08:14:42Z",
            "last_modified_date": "2022-06-01T08:02:42Z"
          },
          {
            "job_id": 323991,
            "job_type": "study_data_extract__v",
            "study_name": "ABCP-2022-01_DEV1",
            "status": "completed__v",
            "created_by": "John Smith",
            "created_date": "2022-05-31T09:15:42Z",
            "last_modified_date": "2022-05-31T17:02:42Z"
          },
          {
            "job_id": 323923,
            "job_type": "study_data_extract__v",
            "study_name": "ABCP-XYZ-REG-01_DEV1",
            "status": "completed__v",
            "created_by": "John Smith",
            "created_date": "2022-05-29T13:31:42Z",
            "last_modified_date": "2022-05-29T13:33:42Z"
          },
          {
            "job_id": 323912,
            "job_type": "study_data_extract__v",
            "study_name": "ABCP-2022-01_DEV1",
            "status": "completed__v",
            "created_by": "John Smith",
            "created_date": "2022-05-25T07:54:42Z",
            "last_modified_date": "2022-05-25T08:02:41Z"
          },
          {
            "job_id": 323898,
            "job_type": "study_data_extract__v",
            "study_name": "ABCP-XYZ-REG-01_DEV1",
            "status": "completed__v",
            "created_by": "John Smith",
            "created_date": "2022-05-21T08:14:42Z",
            "last_modified_date": "2022-05-21T08:16:42Z"
          }                              
      ]
}

Notes

Used to retrieve recent Study Jobs, across one or more Studies in one request.
The primary use case is for API automation of retrieving export files, i.e., already setup and scheduled.
With this API, one can determine recently finished successful jobs (status = completed__v), determine each job_id, then retrieve the output using Retrieve Job Output File.

Endpoint

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

Required Permissions

The following permissions are required to use the Retrieve Study Jobs API:

API Access

The CDMS API Read Write and CDMS API Read Only roles grant these permissions.

Headers

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

Query String Parameters

Name	Description
`study_name`	OptionalName of the Study. This API supports retrieve across multiple Studies in one request
`job_type`	The specific type of Job to retrieve. Only one type can be used per request. Valid job types can be found at Job Summary / Types
`created_start`	Optional Retrieve only Jobs after this datetime of creation. Use the format "yyyy-MM-ddTHH:mm:ssZ". When omitted, 'Now' - 7 days is used. The difference between `created_start` and `created_end` - provided or not - can be no more than 30 days.
`created_end`	Optional Retrieve only Jobs before this datetime of creation. Use the format "yyyy-MM-ddTHH:mm:ssZ". When omitted, 'Now' is used. The difference between `created_start` and `created_end` - provided or not - can be no more than 30 days.

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

On SUCCESS, Vault returns a list of Study Jobs (as JSON array entries) with the following information:

Array	Name	Description
	`created_start`	If passed in the request, re-iterated, otherwise the default value.
	`created_end`	If passed in the request, re-iterated, otherwise the default value.
`jobs`	`job_id`	The ID of the Vault Job tied to the Study Job. Use this value in Retrieve Job Output File to retrieve the file content of the job
`jobs`	`job_type`	The type of the Job (re-iterate of the request value)
`jobs`	`study_name`	Name of the Study of the Job
`jobs`	`status`	The current status of the job, e.g. `completed__v`, `errors__v`, `in_progress__v`
`jobs`	`created_by`	The user who started the Job
`jobs`	`created_date`	Format yyyy-MM-ddThh:ss:mmZ, UTC date time
`jobs`	`last_modified_date`	Format yyyy-MM-ddThh:ss:mmZ, UTC date time

Start Job by Type

Each job requires different body parameters. Each section below uses the same endpoint (Start Job), but lists the parameters and other details specific to that section's job type.

Study Data Extract (SDE)

Request - Start SDE

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "study_data_extract__v",
       "include_restricted_data": true,
       "include_study_design": true,
       "version": "v24.1",
       "export_file_types": ["CSV", "SAS"],
       "file_name": "ABCP-2022-01_DEV1_Study_Data_Extract",
       "use_external_ids": false,
       "include_formilb": true,
       "split_datetime": false,
       "exclude_blank_forms": false,
       "all_clinical_datasets": true,
       "all_system_datasets": true,
       "include_custom_objects": false
    }
}'

Response - Start SDE

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "study_data_extract__v",
       "job_id": 522518,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-05-05T18:18:54Z",
       "include_restricted_data": true,
       "include_study_design": true,
       "version": "v24.1",
       "export_file_types": ["CSV", "SAS"],
       "file_name": "ABCP-2022-01_DEV1_Study_Data_Extract",
       "external_connections": null,
       "use_external_ids": false,
       "include_formilb": true,
       "split_datetime": true,
       "exclude_blank_forms": false,
       "include_rand_treatment": false,
       "all_clinical_datasets": true,
       "clinical_datasets": null,
       "all_system_datasets": true,
       "system_datasets": null,
       "include_custom_objects": false,
       "custom_objects": null,
       "boolean_formatting": "y_n"
   }
}

Notes

The Study Data Extract (SDE) job allows the extract of Study execution data from Vault, in CSV (UTF-8), and optional SAS/SAS XPT format. The job's output includes Study datasets (AE, CM, etc.) as configured in the Study design, plus the following system datasets:

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

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

Custom objects - if involved in the Study design - are also included as datasets. Definition file(s) of Study design are also included (differs by SDE version):

Endpoint

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

Required Permissions

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

API Access
Manage Jobs
View Casebook

The CDMS API Read Write role grants the API Access, Manage Jobs, and View Casebook permissions.

Additional permissions:

Restricted Data Access: This permission is also required when including restricted data in the job output.
View Randomization Enrollment: This permission is also required when including randomization treatment information in the job output of an unmasked study.
View Unmasked Data & View Randomization Enrollment: This permission is also required when including randomization treatment information in the job output of a masked study.

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `study_data_extract__v` in this case, i.e., for start of this type of job.
`include_restricted_data`	Optional. true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.
`include_study_design`	Optional. true/false, false when omitted. Whether the run should include additional CSVs about the Study design.
`version`	The SDE version (not API version) to use for the export run. Formats/options are different by SDE version. Values are of format vX.Y, e.g. `v21.2`, `v21.3`, `v22.1`, `v22.2`, `v22.3`, `v23.1`, `v23.2`, `v23.3`, `v24.1` etc.
`export_file_types`	The type(s) of files of export. The is a JSON array of strings, with valid values of CSV, SAS, and/or XPT, in any order. Previous to SDE version `v23.2`, this was instead just `export_file_type` with different choices. If an older SDE version is desired for the start of the job, refer to that API release documentation for valid values using `export_file_type`.
`file_name`	Optional Filename to use for the resulting ZIP file (up to 200 characters). If omitted, Vault names the file "{Study_Name}_Study_Data_Extract_{DATETIME}_{TIMEZONE}.zip", with a 'SAS_' prefix when the export includes SAS/SAS XPT files.
`external_connections`	Optional. JSON array of names of FTP connection names to also push a copy of the zip file to. These connections are setup with the Study, in the Tools -> EDC Tools -> FTP area. Example, assuming send to two FTP locations: `"external_connections": [ "My_FTP_Connection1", "CRO_Connector" ]`
`use_external_ids`	Optional true/false, false when omitted. Whether to use the Form / Item design External IDs for the naming of datasets and dataset columns. The default is to use Form / Item design name.
`include_formilb`	Optional true/false, false when omitted. Whether the export run should include clinical dataset rows for Forms in status of Intentionally Left Blank (ILB), or not.
`split_datetime`	Optional true/false, false when omitted. Whether all datetime Item fields should be split into separate (additional) dataset columns for date only / time only
`exclude_blank_forms`	Optional true/false, false when omitted. Whether to exclude data from Forms in status `blank__v,` or not
`include_rand_treatment`	Optional true/false, false when omitted. Only applicable if the Study is using the Randomization module within CDMS, and for those with unmasked permissions in the module. The result (with parameter true) will be treatment values within the SYS_RAND dataset.
`all_clinical_datasets`	true/false - whether all clinical datasets (e.g. Forms/CRFs) should be included or not. When using false, then specific ones must be listed in the `clinical_datasets` parameter
`clinical_datasets`	Optional JSON array of names of specific clinical datasets to include. The names are those of the Form Study design names. Must be provided when `all_clinical_datasets` = false and there are no system datasets or custom objects included in the request. Example, assuming just two of the datasets: `"clinical_datasets": [ "AE", "DM" ]`
`all_system_datasets`	true/false - whether all SYS_* datasets should be included or not. When using false, then specific ones must be listed in the `system_datasets` parameter
`system_datasets`	Optional JSON array of names of system datasets to include. Only those system datasets that are applicable for the Study's design settings are valid. Must be provided when `all_system_datasets` = false and there are no other clinical datasets or custom objects included in the request. Example: SYS_RAND would not be available if the Study is not configured to use the CDMS Randomization module. Example, assuming just two of the datasets: `"system_datasets": [ "SYS_SUB", "SYS_FORM" ]`
`include_custom_objects`	true/false, false when omitted.
`custom_objects`	Optional Must provide when `include_custom_objects` = true. JSON array of names of custom object configuration to include in the export. These values are those found in `sde_customobject_config__v.name__v` for the Study. (usually the same as the object name itself). These are configured via Admin -> Business Admin only at current release. Example, assuming just two custom objects (document_tracking_c / cra_visit_trackingc) with name_v values of CustomObj1_Docs and CustomObj2_VisitTracking: `"custom_objects": [ "CustomObj1_Docs", "CustomObj2_VisitTracking" ]`
`boolean_formatting`	Optional. The format to use for boolean/checkbox values, y_n when omitted. Possible values are `y_n`, `y_n_empty`, `t_f`, `t_f_empty`, `1_0`, `1_empty`, `1_0_empty`, `true_false`, `true_false_empty`, `yes_no`, `yes_no_empty`
`item_display_label`	Optional. The format to use for SAS labels. Possible values are `label` and `short_label`. When omitted, the default is `label`.

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `study_data_extract__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`include_restricted_data`	Parameter provided, or the default if omitted.
`include_study_design`	Parameter provided, or the default if omitted.
`version`	Parameter provided in the request
`export_file_type`	Parameter provided, or the default if omitted.
`file_name`	Parameter provided, or the default if omitted.
`external_connections`	Parameter provided, or the default if omitted.
`use_external_ids`	Parameter provided, or the default if omitted.
`include_formilb`	Parameter provided, or the default if omitted.
`split_datetime`	Parameter provided, or the default if omitted.
`exclude_blank_forms`	Parameter provided, or the default if omitted.
`include_rand_treatment`	Parameter provided, or the default if omitted.
`all_clinical_datasets`	Parameter provided, or the default if omitted.
`clinical_datasets`	Parameter provided, or null if omitted
`all_system_datasets`	Parameter provided, or the default if omitted.
`system_datasets`	Parameter provided, or null if omitted
`include_custom_objects`	Parameter provided, or the default if omitted.
`custom_objects`	Parameter provided, or null if omitted
`boolean_formatting`	Parameter provided, or the default if omitted (`y_n`)

Subject Progress Listing

Request - Start Subject Progress Listing

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "subject_progress_listing__v",
       "include_restricted_data": true
   }
}'

Response - Start Subject Progress Listing

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "subject_progress_listing__v",
       "job_id": 525007,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-12-23T00:09:54Z",
       "include_restricted_data": true
   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

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

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `subject_progress_listing__v` in this case, i.e., for start of this type of job.
`include_restricted_data`	Optional. true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `subject_progress_listing__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`include_restricted_data`	Parameter provided, or the default if omitted.

Subject Progress Listing (Versioned)

Request - Start Subject Progress Listing (Versioned)

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "subject_progress_versioned_extract__v",
       "version": "v24.1",
       "include_restricted_data": true,
       "external_connections": ["My_FTP_Drop"]
   }
}'

Response - Start Subject Progress Listing (Versioned)

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "subject_progress_versioned_extract__v",
       "job_id": 525007,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-12-23T00:09:54Z",
       "version": "v24.1",
       "include_restricted_data": true,
       "external_connections": ["My_FTP_Drop"] 
   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

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

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `subject_progress_versioned_extract__v` in this case, i.e., for start of this type of job.
`version`	The version of the output to generate. Example - `v24.1`.
`include_restricted_data`	Optional. true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.
`external_connections`	Optional JSON array of names of FTP connection names to also push a copy of the zip file to. These connections are setup with the Study, in the Tools -> EDC Tools -> FTP area. Example, assuming send to two FTP locations: `"external_connections": [ "My_FTP_Connection1", "CRO_Connector" ]`

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `subject_progress_versioned_extract__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`version`	Parameter provided in the request.
`include_restricted_data`	Parameter provided, or the default if omitted.
`external_connections`	Parameter provided, or the default if omitted.

Event Progress Listing

Request - Start Event Progress Listing

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "event_progress_listing__v",
       "include_restricted_data": true,
       "include_review_data": true
   }
}'

Response - Start Event Progress Listing

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "event_progress_listing__v",
       "job_id": 525008,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-12-23T00:11:35Z",
       "include_restricted_data": true,
       "include_review_data": true
   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

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

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `event_progress_listing__v` in this case, i.e., for start of this type of job.
`include_restricted_data`	Optional. true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.
`include_review_data`	Optional. true/false, false when omitted. Whether the run of data should include data about review activity (SDV / DMR). The API caller must have the permission for view of this information when using true on this option.

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `event_progress_listing__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`include_restricted_data`	Parameter provided, or the default if omitted.
`include_review_data`	Parameter provided, or the default if omitted.

Event Progress Listing (Versioned)

Request - Start Event Progress Listing (Versioned)

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "event_progress_versioned_extract__v",
       "version": "v24.1",
       "include_restricted_data": true,
       "include_review_data": true,
       "external_connections": ["My_FTP_Drop"]       
   }
}'

Response - Start Event Progress Listing (Versioned)

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "event_progress_versioned_extract__v",
       "job_id": 525008,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-12-23T00:11:35Z",
       "version": "v24.1",
       "include_restricted_data": true,
       "include_review_data": true,
       "external_connections": ["My_FTP_Drop"]        
   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

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

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `event_progress_versioned_extract__v` in this case, i.e., for start of this type of job.
`version`	The version of the output to generate. Example - `v24.1`.
`include_restricted_data`	Optional. true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.
`include_review_data`	Optional. true/false, false when omitted. Whether the run of data should include data about review activity (SDV / DMR). The API caller must have the permission for view of this information when using true on this option.
`external_connections`	Optional JSON array of names of FTP connection names to also push a copy of the zip file to. These connections are setup with the Study, in the Tools -> EDC Tools -> FTP area. Example, assuming send to two FTP locations: `"external_connections": [ "My_FTP_Connection1", "CRO_Connector" ]`

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `event_progress_versioned_extract__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`version`	Parameter provided in the request.
`include_restricted_data`	Parameter provided, or the default if omitted.
`include_review_data`	Parameter provided, or the default if omitted.
`external_connections`	Parameter provided, or the default if omitted.

Form Progress Listing

Request - Start Form Progress Listing

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "form_progress_listing__v",
       "include_restricted_data": true,
       "include_item_counts": true
   }
}'

Response - Start Form Progress Listing

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "form_progress_listing__v",
       "job_id": 525105,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-12-23T00:14:29Z",
       "include_restricted_data": true,
       "include_item_counts": true
   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

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

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `form_progress_listing__v` in this case, i.e., for start of this type of job.
`include_restricted_data`	Optional. true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.
`include_item_counts`	Optional. true/false, false when omitted. Whether to include a count of existing Items in each row, i.e., Items on that Form.

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `form_progress_listing__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`include_restricted_data`	Parameter provided, or the default if omitted.
`include_item_counts`	Parameter provided, or the default if omitted.

Form Progress Listing (Versioned)

Request - Start Form Progress Listing (Versioned)

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "form_progress_versioned_extract__v",
       "version": "v24.1",
       "include_restricted_data": true,
       "include_item_counts": true,       
       "external_connections": ["My_FTP_Drop"]       
   }
}'

Response - Start Form Progress Listing (Versioned)

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "form_progress_versioned_extract__v",
       "job_id": 525105,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-12-23T00:14:29Z",
       "version": "v24.1",
       "include_restricted_data": true,
       "include_item_counts": true,
       "external_connections": ["My_FTP_Drop"]        
   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

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

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `form_progress_versioned_extract__v` in this case, i.e., for start of this type of job.
`version`	The version of the output to generate. Example - `v24.1`.
`include_restricted_data`	Optional. true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.
`include_item_counts`	Optional. true/false, false when omitted. Whether to include a count of existing Items in each row, i.e., Items on that Form.
`external_connections`	Optional JSON array of names of FTP connection names to also push a copy of the zip file to. These connections are setup with the Study, in the Tools -> EDC Tools -> FTP area. Example, assuming send to two FTP locations: `"external_connections": [ "My_FTP_Connection1", "CRO_Connector" ]`

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `form_progress_versioned_extract__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`version`	Parameter provided in the request.
`include_restricted_data`	Parameter provided, or the default if omitted.
`include_item_counts`	Parameter provided, or the default if omitted.
`external_connections`	Parameter provided, or the default if omitted.

Query Detail Listing

Request - Start Query Detail Listing

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "query_detail_listing__v",
       "include_restricted_data": true
   }
}'

Response - Start Query Detail Listing

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "query_detail_listing__v",
       "job_id": 525006,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-12-23T00:09:06Z",
       "include_restricted_data": true
   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

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

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `query_detail_listing__v` in this case, i.e., for start of this type of job.
`include_restricted_data`	Optional. true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `query_detail_listing__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`include_restricted_data`	Parameter provided, or the default if omitted.

Query Detail Listing (Versioned)

Request - Start Query Detail Listing (Versioned)

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "query_detail_versioned_extract__v",
       "version": "v24.1",
       "include_restricted_data": true,
       "external_connections": ["My_FTP_Drop"]
   }
}'

Response - Start Query Detail Listing (Versioned)

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "query_detail_versioned_extract__v",
       "job_id": 525006,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-12-23T00:09:06Z",
       "version": "v24.1",
       "include_restricted_data": true,
       "external_connections": ["My_FTP_Drop"] 
   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

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

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `query_detail_versioned_extract__v` in this case, i.e., for start of this type of job.
`version`	The version of the output to generate. Example - `v24.1`.
`include_restricted_data`	Optional. true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.
`external_connections`	Optional JSON array of names of FTP connection names to also push a copy of the zip file to. These connections are setup with the Study, in the Tools -> EDC Tools -> FTP area. Example, assuming send to two FTP locations: `"external_connections": [ "My_FTP_Connection1", "CRO_Connector" ]`

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `query_detail_versioned_extract__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`version`	Parameter provided in the request.
`include_restricted_data`	Parameter provided, or the default if omitted.
`external_connections`	Parameter provided, or the default if omitted.

Core Listings

Request - Start Core Listings

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "core_listing__v",
       "all_sites": true,
       "sites": [],
       "all_forms": true,
       "forms": []
   }
}'

Response - Start Core Listings

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

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `core_listing__v` in this case, i.e., for start of this type of job.
`all_sites`	Optional true/false, false when omitted, i.e., specific Sites must be provided in `sites`.
`sites`	Optional Must provide when `all_sites` = false. JSON array of names of specific Sites to retrieve data for. Example, assuming just two of the Sites: `"sites": [ "101", "102" ]`
`all_forms`	Optional true/false, false when omitted, i.e., specific Form design names must be provided in `forms`.
`forms`	Optional Must provide when `all_forms` = false. JSON array of design names of Forms to include. Example, assuming just two of the Forms: `"forms": [ "DM", "AE" ]`

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `core_listing__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`all_sites`	Parameter provided, or the default if omitted.
`sites`	Parameter provided, or null if omitted
`all_forms`	Parameter provided, or the default if omitted.
`forms`	Parameter provided, or null if omitted

Data and Definition Export (Deprecated)

Request - Start DDE

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "data_and_definition_export__v",
       "include_restricted_data": true
   }
}'

Response - Start DDE

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

This job is retired. Contact your Veeva Services Representative to obtain explicit usage permissions. The Study Data Extract (SDE) job has been enhanced to replace the functionality previously provided by the Data and Definition Export job, including access to the study's definition files.

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs OR Manage Data and Definition Export

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

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

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `data_and_definition_export__v` in this case, i.e., for start of this type of job.
`include_restricted_data`	Optional. true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `data_and_definition_export__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`include_restricted_data`	Parameter provided, or the default if omitted.

Audit Trail by Study

Request - Start Audit Trail by Study

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "audit_trail_export__v",
       "date_range_start": "2023-05-01",
       "date_range_start": "2023-05-03"
   }
}'

Response - Start Audit Trail by Study

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "audit_trail_export__v",
       "job_id": 522417,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-05-05T18:10:01Z",
       "date_range_start": "2023-05-01",
       "date_range_start": "2023-05-03",
       "specific_users": null

   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

The following permissions are required to use the Start Audit Trail by Study API:

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `audit_trail_export__v` in this case, i.e., for start of this type of job.
`date_range_start`	YYYY-MM-DD format, the date from which to retrieve audit trail. The start to end range can be no more than 30 days.
`date_range_end`	Optional. YYYY-MM-DD format, the date retrieve audit trail through / up to. The start to end range can be no more than 30 days. When omitted, today is assumed.
`specific_users`	Optional. Specific users to obtain audit trail about, as JSON array of users names. For example - `"specific_users": ["joe.smith@abcpharma.com", "mary.jones@abcpharma.com"]`

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `audit_trail_export__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`date_range_start`	Parameter provided.
`date_range_end`	Parameter provided, or the default if omitted.
`specific_users`	Parameter provided, or null if omitted.

Audit Trail by Site

Request - Start Audit Trail by Site

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "audit_trail_export_by_site__v",
       "date_range_start": "2023-05-01",
       "date_range_start": "2023-05-03",
       "specific_sites": ["101", "102"]
   }
}'

Response - Start Audit Trail by Site

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "audit_trail_export_by_site__v",
       "job_id": 522417,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-05-05T18:10:01Z",
       "date_range_start": "2023-05-01",
       "date_range_start": "2023-05-03",
       "specific_users": null,
       "specific_sites": ["101", "102"]       
   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

The following permissions are required to use the Start Audit Trail by Site API:

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `audit_trail_export_by_site__v` in this case, i.e., for start of this type of job.
`date_range_start`	YYYY-MM-DD format, the date from which to retrieve audit trail. The start to end range can be no more than 30 days.
`date_range_end`	Optional. YYYY-MM-DD format, the date retrieve audit trail through / up to. The start to end range can be no more than 30 days. When omitted, today is assumed.
`specific_sites`	Specific sites to obtain audit trail about, as JSON array of Site name/number. For example - `"specific_sites": ["101", "201"]`
`specific_users`	Optional. Specific users to obtain audit trail about, as JSON array of users names. For example - `"specific_users": ["joe.smith@abcpharma.com", "mary.jones@abcpharma.com"]`

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `audit_trail_export_by_site__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`date_range_start`	Parameter provided.
`date_range_end`	Parameter provided, or the default if omitted.
`specific_sites`	Parameter provided.
`specific_users`	Parameter provided, or null if omitted.

Audit Trail by Subject

Request - Start Audit Trail by Subject

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "audit_trail_export_by_subject__v",
       "date_range_start": "2023-05-01",
       "date_range_start": "2023-05-03",
       "specific_subjects": ["101-001", "101-002"]
   }
}'

Response - Start Audit Trail by Subject

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "audit_trail_export_by_subject__v",
       "job_id": 522417,
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-05-05T18:10:01Z",
       "date_range_start": "2023-05-01",
       "date_range_start": "2023-05-03",
       "specific_users": null,
       "specific_subjects": ["101-001", "101-002"],
       "deleted_subjects": false
   }
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

The following permissions are required to use the Start Audit Trail by Site API:

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `audit_trail_export_by_subject__v` in this case, i.e., for start of this type of job.
`date_range_start`	YYYY-MM-DD format, the date from which to retrieve audit trail. The start to end range can be no more than 30 days.
`date_range_end`	Optional. YYYY-MM-DD format, the date retrieve audit trail through / up to. The start to end range can be no more than 30 days. When omitted, today is assumed.
`specific_subjects`	Specific Subjects to obtain audit trail about, as JSON array of Subject name/number. For example - `"specific_subjects": ["101-001", "101-002"]`
`specific_users`	Optional. Specific users to obtain audit trail about, as JSON array of users names. For example - `"specific_users": ["joe.smith@abcpharma.com", "mary.jones@abcpharma.com"]`

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `audit_trail_export_by_subject__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`date_range_start`	Parameter provided.
`date_range_end`	Parameter provided, or the default if omitted.
`specific_subjects`	Parameter provided.
`specific_users`	Parameter provided, or null if omitted.
`deleted_subjects`	Always false for clarity, as it cannot be specified with the start of the job via API (at this time). For audit trail on deleted Subjects, use instead the EDC Tools user interface.

Data Change Report

Request - Start Data Change report - (open ended date range, today is July 14th, all Forms, no restricted data)

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
    "job_type": "data_change_report__v",
    "export_file_type": "CSV",
    "date_range_start": "2023-07-10",
    "include_restricted_data": false,
    "all_forms": true
   }
}'

Response - Data Change Report

{
   "responseStatus": "SUCCESS",
   "response": {
    "job_type": "data_change_report__v",
    "job_id": 307483,
    "created_by": "chunter@abcpharma.com",
    "created_date": "2023-06-27T20:27:26Z",  
    "export_file_type": "CSV", 
    "date_range_start": "2023-07-10",
    "date_range_end": "2023-07-14",
    "days_previous": null,
    "include_restricted_data": false,
    "all_forms": true,
    "forms": null,
    "external_connections": null
   } 
}

Request - Start Data Change report - (restricted data included, using days previous, specific Forms, Excel, and FTP)

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
   "study_name": "ABCP-2022-01_DEV1",
    "request": {
        "job_type": "data_change_report__v",
        "export_file_type": "Excel",
        "date_range_start": null,
        "date_range_end": null,
        "days_previous": 5,
        "include_restricted_data": true,
        "all_forms": false,
        "forms": ["AE", "CM", "DM"],
        "external_connections": ["MyFTPLocation"]
   }   
}'

Response - Data Change Report

{
    "responseStatus": "SUCCESS",
    "response": {
        "job_type": "data_change_report__v",
        "job_id": 307483,
        "created_by": "chunter@abcpharma.com",
        "created_date": "2023-06-27T20:27:26Z",  
        "export_file_type": "Excel", 
        "date_range_start": null,
        "date_range_end": null,
        "days_previous": 5,
        "include_restricted_data": true,
        "all_forms": false,
        "forms": ["AE", "CM", "DM"],
        "external_connections": ["MyFTPLocation"]
    }
}

The Data Change Report is referred to as the Data Change Extract in the EDC Tools user interface. The report includes changes to Items and Event Dates during a specific date range.

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

The following permissions are required to use the Data Change Report API:

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `data_change_report__v` in this case, i.e., for start of this type of job.
`export_file_type`	Values of `CSV` or `Excel` only.
`date_range_start`	Optional (Start to end, or days previous is required, but not both) YYYY-MM-DD format, the date from which to retrieve item data changes. The start to end range can be no more than 90 days.
`date_range_end`	Optional (Start to end, or days previous is required, but not both) YYYY-MM-DD format, the date retrieve item data changes through / up to. The start to end range can be no more than 90 days. When omitted, today is assumed.
`days_previous`	Optional (Start to end, or days previous is required, but not both) Whole numbers from 1 to 90 only.
`include_restricted_data`	Optional true/false, false when omitted. Whether the run of data should include data from restricted Forms (or not). The API caller must have the permission for the restricted data when using true on this option.
`all_forms`	Optional true/false, true when omitted. Whether to filter to a specific list of Forms, by design name, or not.
`forms`	Optional (Must provide when `all_forms` = false) JSON array of names of Form design names to include.
`external_connections`	Optional JSON array of names of FTP connection names to also push a copy of the zip file to. These connections are setup with the Study, in the Tools -> EDC Tools -> FTP area. Example, assuming send to two FTP locations: `"external_connections": [ "My_FTP_Connection1", "CRO_Connector" ]`

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `data_change_report__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`export_file_type`	Parameter provided.
`date_range_start`	Parameter provided, or the default if omitted.
`date_range_end`	Parameter provided, or the default if omitted.
`days_previous`	Parameter provided, or the default if omitted.
`include_restricted_data`	Parameter provided, or the default if omitted.
`all_forms`	Parameter provided, or the default if omitted.
`forms`	Parameter provided, or the default if omitted.
`external_connections`	Parameter provided, or the default if omitted.

Casebook Design Export (CDE)

Request - Start CDE

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
    "job_type": "casebook_design_export__v",
    "casebook_version": 1
   }
}'

Response - CDE

{
   "responseStatus": "SUCCESS",
   "response": {
    "job_type": "casebook_design_export__v",
    "job_id": 307483,
    "created_by": "chunter@abcpharma.com",
    "created_date": "2023-06-27T20:27:26Z",  
    "casebook_version": 1
   } 
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

The following permissions are required to use the Casebook Design Export Job API:

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `casebook_design_export__v` in this case, i.e., for start of this type of job.
`casebook_version`	Optional When not provided, the latest casebook version is used for the output generated.

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `casebook_design_export__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`casebook_version`	Parameter provided, or the default if omitted.

Safety Follow-Up Scan

Request - Safety Follow-Up Scan

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
    "job_type": "safety_integrations_follow_up_scan__v",
    "full_scan": true
   }
}'

Response - Safety Follow-Up Scan

{
   "responseStatus": "SUCCESS",
   "response": {
    "job_type": "safety_integrations_follow_up_scan__v",
    "job_id": 307483,
    "created_by": "chunter@abcpharma.com",
    "created_date": "2023-06-27T20:27:26Z",  
    "full_scan": true
   } 
}

See Job Summary / Types (above) for description of this job type.

Endpoint

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

Required Permissions

The following permissions are required to use the Safety Follow-Up Scan Job API:

API Access
Manage Jobs

The CDMS API Read Write role grants the API Access and Manage Jobs permissions.

Headers

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

Body Parameters

Name	Description
`study_name`	Name of the Study
`job_type`	Value of `safety_integrations_follow_up_scan__v` in this case, i.e., for start of this type of job.
`full_scan`	Optional True or false, false is the default if omitted. The parameter dictates whether all safety cases are rescanned (`"full_scan": true`), or just the safety cases of recently updates Subjects since the last scan. (`"full_scan": false`)

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	The provided job type: `safety_integrations_follow_up_scan__v`
`job_id`	Vault Job ID for the job, used to Retrieve Job Status and Retrieve Job Output File
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)
`full_scan`	Parameter provided, or the default if omitted.

Cancel Job

Request

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

Response

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "study_data_extract__v",
       "job_id": 525010,
       "study_name": "ABCP-2022-01_DEV1"
   }
}

Notes

You can cancel a job that is only of In Progress (in_progress__v) status.
Vault stops the job and moves it into the Canceled (canceled__v) status.
If you cancel the run of a scheduled job, that job continues to follow the configured schedule, the next round / time period.
Only Jobs of certain types (see Job Summary / Types) can be canceled.

Endpoint

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

Required Permissions

The following permissions are required to use the Cancel Job API:

API Access
Manage Jobs

The CDMS API Read Write role grants these permissions.

Headers

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

URI Path Parameters

Name	Description
`job_id`	The Vault ID of the Job.

Retrieve Job Status

Request

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

Response

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

Notes

You can retrieve the current status of a Study Job using its known Vault Job ID.
The ID is returned in the response to start a Job, or from Retrieve Study Jobs
Only Jobs of certain types (see Job Summary / Types) can be inspected for current status.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants these permissions.

Headers

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

URI Path Parameters

Name	Description
`job_id`	The Vault ID of the Job.

Retrieve Job Output File

Request

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

Notes

You can retrieve the output file of a Study Job (e.g. ZIP CSV, JSON, or other formatted file) using its known Vault Job ID.
The output file is available for up to thirty (30) after it runs.
These IDs are part of the response to start a _Job).
Only jobs of certain types (see Job Summary / Types) allow download of an output file.

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants these permissions.

Headers

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

URI Path Parameters

Name	Description
`job_id`	The Vault ID of the Job.

Retrieve Job Log

Request

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

Response

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

Notes

You can retrieve the log file of a Study Job using its known Vault Job ID for up to thirty (30) days after a job is completed.
The ID is returned in the response to start a Job, or from Retrieve Study Jobs

Endpoint

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

Required Permissions

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

API Access
Manage Jobs

The CDMS API Read Write role grants these permissions.

Headers

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

URI Path Parameters

Name	Description
`job_id`	The Vault ID of the Job.

Users

These endpoints allow for inspection of Study users, and also the update of Study access and/or the overall Vault account of users. Learn more about Study user access in Vault CDMS Help.

Retrieve Users

Request

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/users' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 10,
        "total": 10
    },
    "vault_id": 1004329,
    "users": [
        {
            "user_id": "886159",
            "user_name": "mary.jones@my-cdms-vaults.com",
            "user_email": "mary.jones@mycompany.com",
            "user_title": "",
            "user_last_name": "Mary",
            "user_first_name": "Jones",
            "company": "",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)",            
            "security_policy": "Basic",
            "security_profile": "cdms_all_access__v",
            "activation_date": "2023-09-22",
            "created_date": "2023-09-22T14:21:54Z",
            "created_by": "Mary Jones",
            "last_modified_date": "2023-09-22T15:02:41Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "last_login": null,
            "studies": [
                {
                    "study_environment": "EKE_SFTY_TEST2_DEV1",
                    "study_role": "CDMS Safety Administrator",
                    "study_access": "Enabled",
                    "all_sites_access": true,
                    "lms_training_status": "Trained",
                    "ignore_lms_training_status": false
                },
                {
                    "study_environment": "EKE_SFTY_TEST1_DEV1",
                    "study_role": "CDMS Safety Administrator",
                    "study_access": "Enabled",
                    "all_sites_access": true,
                    "lms_training_status": "Trained",
                    "ignore_lms_training_status": false
                }
            ]
        }, 
        {
            "user_id": "885131",
            "user_name": "tim.young@my-cdms-vaults.com",
            "user_email": "tim.young@mycompany.com",
            "user_title": "",
            "user_last_name": "Tim",
            "user_first_name": "Young",
            "company": "",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)",
            "security_policy": "Basic",
            "security_profile": "cdms_all_access__v",
            "activation_date": "2023-09-22",
            "created_date": "2023-09-22T14:21:54Z",
            "created_by": "Mary Jones",
            "last_modified_date": "2023-09-22T15:02:41Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "last_login": "2024-01-04T11:12:31Z",
            "studies": [
                {
                    "study_environment": "EKE_SFTY_TEST2_DEV1",
                    "study_role": "CDMS Clinical Research Associate",
                    "study_access": "Enabled",
                    "site_access": "101,102,105"
                    "country_access": "",
                    "lms_training_status": "Trained",
                    "ignore_lms_training_status": false
                },
                {
                    "study_environment": "EKE_SFTY_TEST1_DEV1",
                    "study_role": "CDMS Clinical Research Associate",
                    "study_access": "Enabled",
                    "site_access": ""
                    "country_access": "United States,Mexico,Canada",
                    "lms_training_status": "Not Trained",
                    "ignore_lms_training_status": true
                }
            ]
        },        
        {
            "user_id": "886151",
            "user_name": "joe.smith@my-cdms-vaults.com",
            "user_email": "joe.smith@mycompany.com",
            "user_title": "",
            "user_last_name": "Smith",
            "user_first_name": "Joe",
            "company": "",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)",
            "security_policy": "Basic",
            "security_profile": "cdms_all_access__v",
            "activation_date": "2022-06-28",
            "created_date": "2022-06-28T19:31:12Z",
            "created_by": "Mary Jones",
            "last_modified_date": "2022-06-28T19:31:14Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "last_login": "2024-01-02T13:34:31Z",
            "studies": [
                {
                    "access_to_all_environments": true,
                    "study": "EKE_SFTY_VSCC",
                    "study_role": "CDMS Lead Data Manager",
                    "study_access": "Enabled",
                    "lms_training_status": "",
                    "ignore_lms_training_status": true
                }
            ]
        },
        {
            "user_id": "883233",
            "user_name": "john.johnson@my-cdms-vaults.com",
            "user_email": "john.johnson@mycompany.com",
            "user_title": "",
            "user_last_name": "John",
            "user_first_name": "Johnson",
            "company": "",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)",
            "security_policy": "Basic",
            "security_profile": "cdms_all_access__v",
            "activation_date": "2023-09-22",
            "created_date": "2023-09-22T14:20:33Z",
            "created_by": "Mary Jones",
            "last_modified_date": "2023-09-22T15:02:41Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": true,
            "last_login": "2023-12-15T16:05:31Z",
            "studies": [
                {
                    "study_role": "CDMS Study Designer",
                    "study_access": "Enabled",
                    "lms_training_status": "",
                    "ignore_lms_training_status": true
                }
            ]
        },        
        {
            "user_id": "884213",
            "user_name": "jennifer.harrison@my-cdms-vaults.com",
            "user_email": "jennifer.harrison@mycompany.com",
            "user_title": "",
            "user_last_name": "Harrison",
            "user_first_name": "Jennifer",
            "company": "",
            "federated_id": "",
            "user_language": "en",
            "user_locale": "en_US",
            "user_timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)",
            "security_policy": "Basic",
            "security_profile": "cdms_all_access__v",
            "activation_date": "",
            "created_date": "2018-07-25T11:23:31Z",
            "created_by": "Mary Jones",
            "last_modified_date": "2021-03-15T16:05:31Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": true,
            "all_studies_access": false,
            "last_login": "2024-01-15T16:05:31Z"

        },
        :
        :
        :
    ]
}

Notes

Retrieve a list of Users in a single Study, or of many Studies.
Also retrieve very specific users by username(s).
Four generic types of users are returned in responses regardless of Study role or Study membership:
- Each has different behavior in their respective entry in the response.
- Review the table below for the different types of users in a CDMS Vault, and the specific examples to the right for each

Type	Example Users	Description
Vault Owner	`Jennifer Harrison`	Users that have full access to all aspects of the Vault, thus automatically a member of all Studies. Their role in each Study is unlimited. The `studies` array is omitted from its entry in the response.
All Studies User	`John Johnson`	Users that have a specific Study role for all Studies in the Vault, now and for any future Study. This is typical in a UAT/Test Vault, where Studies are often deployed, and alleviates the need to re-setup users with every new Study deployment. For the array `studies`, there is only one entry, and it does not contain `study_environment` or `study` property/value since all Studies are granted. These users will always have all site access in their Studies, and as such, `all_sites_access`, `site_access`, and `country_access` are omitted. Only `study_role`, `study_access`, `lms_training_status`, and `ignore_lms_training_status` are returned, and as a single entry of the array.
All Environments User	`Joe Smith`	Users that have a specific Study role for all instances of a Study in the Vault, now and for any future instances of that Study. This is also typical in a UAT/Test Vault, where Studies are often deployed, and alleviates the need to re-setup users with every new Study deployment. Example: for a Study in a UAT Vault called ABC-PROT-12345, it will have one or more instances / environments for testing purposes. Suppose they are: ABC-PROT-12345_TST1, ABC-PROT-12345_TST2, and ABC-PROT-12345_TST3. Users of this type will have access into all three with a specific Study role. Any additional deployment for the Study, say ABC-PROT-12345_TST4, will result in automatic access for the user into the newly deployed Study. Similar to the All Studies User, the `studies` array contains `study_role`, `study_access`, `lms_training_status`, and `ignore_lms_training_status`. Additionally included is `"access_to_all_environments": true` and a `study` value to indicate the Study master name that houses all the instances of the Study. These users will always have all site access in their Studies, and as such `all_sites_access`, `site_access`, and `country_access` are omitted.
Study by Study User	`Mary Jones` and `Tim Young`	Users that are the most typical users for CDMS, most notably in production Vaults. These users are granted access to one or more Studies each with their own Study role, plus specific Site or Study Country access.

Endpoint

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

Required Permissions

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

API Access
View Users

The CDMS API Read Only and CDMS API Read Write roles grant these permissions.

Headers

Name	Description
`Accept`	`application/json` (default)

Query String Parameters

Name	Description
`study_name`	Optional Name of the Study
`user_names`	Optional Include a list of usernames (`user__v.user_name__v`) to retrieve information about specific users. If omitted, Vault returns all Users for the specified Study, or across Studies (if `study_name` omitted).

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0. For example, if the `limit` is set to 100, and there are 150 possible records, an offset of 0 returns records 0 through 99 (zero based). Then, `offset` of 100 would return records 100 through 149. More information on pagination is in the section Pagination

Response Details

On SUCCESS, Vault returns a list of users with properties on their Vault level account, plus any Study access:

Array	Name	Description
	`vault_id`	The unique Vault ID, i.e., one currently connected with.
`users`	`user_id`	Value is across all Vaults / domains
`users`	`user_name`	E.g., joe.smith@eke.com
`users`	`user_email`
`users`	`user_title`
`users`	`user_last_name`
`users`	`user_first_name`
`users`	`users/company`
`users`	`federated_id`	This value is the username in a system the user is using SSO for to login to the Vault. The security policy must be set appropriately for this value to line up. (multiple SSO policies can reside in one Vault)
`users`	`user_language`	E.g., `en`, `fr`, `de`, etc.
`users`	`user_locale`	E.g., `en_US`, `en_AU`, etc.
`users`	`user_timezone`	Full label of the user’s time zone
`users`	`security_policy`	The security policy name value, e.g. `Basic` or `Customer Network SSO`, etc.
`users`	`security_profile`	The overall Vault security profile for the user. In CDMS, this is most often a very generice profile, with Study level role dictating the actual permissions of a user in the Study.
`users`	`activation_date`	If there is an activation date, shown as yyyy-MM-dd format. Otherwise the line is omitted
`users`	`created_date`	Format yyyy-MM-ddThh:ss:mmZ, UTC date time
`users`	`created_by`	The user that created this account (Vault level account)
`users`	`last_modified_date`	Format yyyy-MM-ddThh:ss:mmZ, UTC date time
`users`	`principal_investigator`	true/false When choosing 'Add as Principal Investigator' from the UI, a user can also be a PI for tagging to a specific site.
`users`	`active`	The status of the overall Vault account in the Vault (no specific Study)
`users`	`vault_owner`	If the user is a Vault Owner, they have access to all Studies (need no specific Study access). These users returned will not have the `studies` array in their response entry.
`users`	`all_studies_access`	When a user is set to have access to all Studies, now and in the future. (e.g. a Sandbox or Test Vault). Users with `true` will always have all sites access in the Studies. See also the All Studies User described above.
`users`	`last_login`	The last login to the Vault for this user (no specific Study). Format yyyy-MM-ddThh:ss:mmZ, UTC date time
`users/studies`	`access_to_all_environments`	When `true`, the user has access to all Study instances, and the Study master name is noted in the `study` line noted below, and will not yield a `study_environment` line. This user will also always have all sites access in the Study instances. When the user does not have all environments access, the line is omitted. See also the All Environments User described above.
`users/studies`	`study_environment`	The Study instance label, e.g. ABC-2022-01_DEV1. Only the Study by Study User described above will contain this property / value.
`users/studies`	`study`	The Study master name, e.g. ABC-2022-01, where ABC-2022-01_DEV1 is the development Study, ABC-2022-01_TST1, ABC-2022-01_TST2, .. are the test Vault Studies. Only those with `"access_to_all_environments": true` will have this property / value. See also the All Environments User described above.
`users/studies`	`study_role`	The Study role name in the Study (Study by Study User), all instances of Study (All Environments User), or all Studies (All Studies User)
`users/studies`	`study_access`	Values of Enabled or Disabled, the status of the entry, it for a single Study (Study by Study User), multiple instances of a Study (All Environments User), or all Studies (All Studies User)
`users/studies`	`all_sites_access`	When the value is `true`, the user has access to all sites in the Study. If `false`, the line is omitted from the return, and instead the Site level access is shown in `site_access` or `country_access`
`users/studies`	`site_access`	Comma list of Sites the user has access to, usually a single entry when used. Data entry users (CRC / PI) are the common roles for this access line. The line is omitted when `"all_sites_access": true`, or when the user is of type All Studies User or All Environments User.
`users/studies`	`country_access`	Comma list of Study Countries the user has access to. That is, the Sites of those listed countries. The line is omitted when `"all_sites_access": true`, or when the user is of type All Studies User or All Environments User.
`users/studies`	`lms_training_status`	Values are empty, Trained or Not Trained. This appears for Study by Study User, All Studies User, or All Environments User.
`users/studies`	`ignore_lms_training_status`	When this value is `true`, the LMS training status on that Study is ignored (e.g. Not Trained). That is, the user is allowed into the Study per this override - common to development / test Study users. This appears for Study by Study User, All Studies User, or All Environments User.

Upload Users (CSV)

Request

curl -L -X PUT 'https://my-vault.veevavault.com/api/v24.1/app/cdm/users' \
-H 'Authorization: {SESSION_ID}' \
-F 'append_site_country_access="false"' \
-F 'import_file=@"/Users/joe_smith/user-import-test.csv"'

Response

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "EDC Import",
       "job_id": 581803,
       "status": "Queued",
       "created_by": "chunter@abcpharma.com",
       "created_date": "2022-02-14T23:37:17Z"
   }
}

Notes

This endpoint is used to create or update users in a Study or Studies.
Each row of the uploaded CSV is for a user to create or make updates to. This can be the creation of both the Vault account and access into a specific Study or Studies, or just the creation or update of Study specific access for an existing User.
For deactivation at a Study level, this endpoint is also used. Specifically, a value of Disabled in the Study Access column for the specific User to deactivate. A value of Enabled can be used to re-activate or initially activate an existing Study user that is currently inactive.
Vault or domain activation or deactivation - see the next few sections
If ANY of the rows fail, the return response will enumerate those rows with issues. A job does NOT start in such cases. A list of possible errors and warnings for user import is available on CDMS Help
Once a job successfully starts, the job ID is returned. Check the job status using:

<your Vault URL>/api/v24.1/services/jobs/{job_id}

Once the job is complete, consider using Retrieve Users to verify the state of each of the users created and/or updated.
Information about the upload of Users via CSV via the UI are also available here: Importing Users

Preparing the Import File

Use this template file to create your CSV. Detailed explanations for the required columns are available on CDMS Help.

The CSV file must meet the following general requirements:

The CSV file must be smaller than 20 mb.
Use CSV UTF-8 encoding, or don't use any special characters.
The CSV file must follow standard CSV format.
The matching of values in the import file to those values in CDMS is case-sensitive.
The CSV attempted is checked for correct column header names first, then cell by cell validation of values.
CSV Column names are case sensitive, but can be in any order

Endpoint

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

Required Permissions

The following permissions are required to use the Upload Users (CSV) API:

API Access
View Users
Edit Users

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name Description

import_file Provide the path to the import CSV file.

append_site_country_access Optional When omitted, false is assumed. Use true to append Site and Country access ONLY for existing users. Example - a user has existing Site access of 101,102. If a CSV is uploaded with line corresponding to the user and only 103 is in the Site Access column, the result is the user having overall Site access of 101,102,103. With this parameter false in the example, the user would be updated to just Site 103.

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	Value is always EDC Import, the job label for the User import
`job_id`	Vault Job ID for the job that will start
`status`	Value is always Queued, i.e., about to start
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)

Upload Users (JSON)

Request - Two users

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/users_json' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '
{
    "append_site_country_access": false,
    "users": [
        {             
             "User Name": "joe.smith@my-cdms-vaults.com",
             "Email": "joe.smith@veeva.com",
             "Title": "Mr.",
             "First Name": "Joe",
             "Last Name": "Smith",
             "Company": "Sponsor ABCXYZ",
             "Language": "en",
             "Locale": "en_US",
             "Timezone": "(GMT-08:00) Pacific Standard Time (America/Los_Angeles)",
             "Security Policy": "Basic",             
             "Federated ID": "",
             "Activation Date": "10/15/2023",
             "Send Welcome Email": "Yes",                          
             "Add as Principal Investigator": "No",             
             "Study": "ABCP-2023-001",
             "Study Environment": "ABCP-2023-001_TST5",             
             "Access to All Environments": "No",
             "Cross Study Role": "",
             "Study Access": "Enabled",
             "Study Role": "CDMS Lead Data Manager",
             "Access to All Sites": "Yes",
             "Country Access": "",
             "Site Access": "",
             "Ignore LMS Status": "No",             
             "Domain Administrator": "No",
             "Service Availability Notifications": "No",
             "Product Announcement Emails": "No",
             "Status": "Active",
             "Bypass Veeva ID Check": "No"             
        },
        {             
             "User Name": "mary.jones@my-cdms-vaults.com",
             "Email": "mary.jones@veeva.com",
             "Title": "",
             "First Name": "Mary",
             "Last Name": "Jones",
             "Company": "Cary General Hospital",
             "Language": "en",
             "Locale": "en_US",
             "Timezone": "(GMT-08:00) Pacific Standard Time (America/Los_Angeles)",
             "Security Policy": "Basic",             
             "Federated ID": "",
             "Activation Date": "10/15/2023",
             "Send Welcome Email": "Yes",                          
             "Add as Principal Investigator": "No",             
             "Study": "ABCP-2023-001",
             "Study Environment": "ABCP-2023-001_TST5",             
             "Access to All Environments": "No",
             "Cross Study Role": "",
             "Study Access": "Enabled",
             "Study Role": "CDMS Clinical Research Coordinator",
             "Access to All Sites": "No",
             "Country Access": "",
             "Site Access": "101",
             "Ignore LMS Status": "No",             
             "Domain Administrator": "No",
             "Service Availability Notifications": "No",
             "Product Announcement Emails": "No",
             "Status": "Active",
             "Bypass Veeva ID Check": "No"             
        }        
    ]
} 
'

Response - Success - job started to process users

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "EDC Import",
       "job_id": 581803,
       "status": "Queued",
       "created_by": "chunter@abcpharma.com",
       "created_date": "2023-06-14T23:37:17Z"
   }
}

Notes

This endpoint is used to create or update users in a Study or Studies.
Instead of a CSV file as the body of the request, JSON formatted body for the request.
Use cases include the creation of both the Vault account and access into a specific Study or Studies, or just the creation or update of Study specific access for an existing User.
For deactivation at a Study level, the endpoint is also used. Specifically, a value of Disabled in the Study Access JSON node for the specific User to deactivate. A value of Enabled can be used to re-activate or initially activate an existing Study user that is currently inactive.
Vault or domain activation or deactivation - see the next few sections
If ANY of the entries in the request fail, the return response will enumerate those entries with issues. A job does NOT start in such cases. A list of possible errors and warnings for user import is available on CDMS Help
Once a job successfully starts, the job ID is returned. Check the job status using:

<your Vault URL>/api/v24.1/services/jobs/{job_id}

This is a general check on any Vault Job, by its ID. Once the job is complete, consider using Retrieve Users to verify the state of each of the users created and/or updated.
Information about the upload of Users via CSV via the UI is also available here: Importing Users. The API attempt through CSV or JSON goes through all of the same validation checks.

Endpoint

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

Required Permissions

The following permissions are required to use the Upload Users (JSON) API:

API Access
View Users
Edit Users

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

Name Description

import_file Provide the path to the import CSV file.

Response Details

On SUCCESS, Vault returns the following information on successful start of the job:

Name	Description
`job_type`	Value is always EDC Import, the job label for the User import
`job_id`	Vault Job ID for the job that will start
`status`	Value is always Queued, i.e., about to start
`created_by`	User Name of the user who started the job.
`created_date`	Datetime the job was started. (UTC)

Inactivate User

Request - Inactivate User in a Vault

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://my-vault.veevavault.com/api/v24.1/objects/users/25001

Request - Inactivate User in All Vaults of the Domain

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://my-vault.veevavault.com/api/v24.1/objects/users/25001?domain=true

Response - (either)

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

Notes

Use this endpoint ONLY to inactivate a user account, Vault or domain wise.
For the deactivation of just a specific Study, use the Upload Users endpoint, but with a line for the user indicating Disabled Study status.
WARNING: This endpoint with domain = true will inactivate the user across ALL Vaults they otherwise have access into. The use of domain = false (or omitting the domain parameter) will inactivate the user in just the Vault targeted. This will of course deactivate the user in all Studies in that Vault they otherwise had access to.
This endpoint is a mirror of the main Vault endpoint for inactivating a user : Vault Help
To inactivate a user across a domain, your account must be a Domain Admin

Endpoint

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

Required Permissions

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

API Access
View Users
Edit Users

The CDMS API Read Write role grants these permissions.

Headers

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

URI Path Parameters

Name	Description
`user_id`	The Vault unique ID for the user. See Retrieve Users above to retrieve those ID(s).

Query String Parameters

Name	Description
`domain`	Optional When true, this disables the user account in all Vaults in the domain. When omitted, a value of false is assumed, i.e., inactivate the user just in the one Vault.

Activate User - Domain Level

Request - Activate User at Domain-Level

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "domain_active__v=true" \
https://my-vault.veevavault.com/api/v24.1/objects/users/25001

Response - Activate User at Domain-Level

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

Notes

Use this endpoint ONLY to activate a user account that is currently inactive on the domain (all Vaults in the domain)
This action must be performed first, prior to more actions to activate in specific Vaults, then more to activate specific Studies (where necessary)
This endpoint is a mirror of the main Vault endpoint for updating a user : Vault Help
To activate a user across a domain, your account must be a Domain Admin

Required Permissions

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

API Access
View Users
Edit Users

The CDMS API Read Write role grants these permissions.

Your user account must also be a Domain Administrator to make changes at the domain level.

Endpoint

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

Headers

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

URI Path Parameters

Name	Description
`user_id`	The Vault unique ID for the user. See Retrieve Users above to retrieve those ID(s).

Body Parameters

Name	Description
`domain_active__v`	Encoded parameter, use true. This is the field name on the user object in Vault. The endpoint is a generic endpoint to update various fields of the user (at Vault level). In this case/use, one just uses just the domain active, i.e., setting to true for re-activation of a user.

Activate User - Vault(s)

Request - Activate User at Vault Level

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "active__v=true" \
https://my-vault.veevavault.com/api/v24.1/objects/users/25001/vault_membership/456789

Response - Activate User at Vault Level

{
    "responseStatus": "SUCCESS"
}

Notes

Use this endpoint ONLY to activate a user account that is currently inactive on a specific Vault, and the account is to be activated on that Vault only.
This action must be performed first, prior to specific Study activations (where necessary)
This endpoint is a mirror of the main Vault endpoint for updating a user : Vault Help

Required Permissions

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

API Access
View Users
Edit Users

The CDMS API Read Write role grants these permissions.

Endpoint

PUT /api/{version}/objects/users/{user_id}/vault_memberships/{vault_id}

Headers

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

URI Path Parameters

Name	Description
`user_id`	The Vault unique ID for the user. See Retrieve Users above to retrieve those ID(s).
`vault_id`	The Vault ID, i.e., the one being activated on

Body Parameters

Name	Description
`active__v`	Encoded parameter, use true. The status in the Vault for the user, in this case true for now active there.

Retrieve Study Roles

Request - Retrieve study roles

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/studyroles' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - Standard and configured roles in Vault

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 47,
        "total": 47
    },
    "studyroles": [
        {
            "id": "0AR00000000I001",
            "role_api_name": "cdms_api_read_only__v",
            "role_name": "CDMS API Read Only",
            "role_team": "other__v",
            "accept_closeout_pdf": false,
            "add_casebook": false,
            "answer_query": false,
            "answer_third_party_queries": false,
            "api_access": true,
            "approve_code": false,
            "approve_import": false,
            "approve_lab_normals": false,
            "assessments_tab": false,
            "assign_code": false,
            "browse_view": false,
            "cdb_tools": false,
            "close_all_queries": false,
            "close_query": false,
            "coder_tab": false,
            "coder_tools_tab": false,
            "configure_cdb": false,
            "configure_randomization": false,
            "copy_study_data_to_ppt": false,
            "create_export_definition": false,
            "create_listing": false,
            "create_protocol_deviations": false,
            "create_view": false,
            "data_entry": false,
            "data_entry_tab": false,
            "delete_casebook": false,
            "delete_export_definition": false,
            "delete_listing": false,
            "delete_view": false,
            "design_library": false,
            "design_study": false,
            "download_import_package": false,
            "edc_tools_tab": false,
            "edit_classification": false,
            "edit_clinical_assessments": false,
            "edit_cql": false,
            "edit_dmr": false,
            "edit_form_linking": false,
            "edit_integration_mappings": false,
            "edit_lab_analyte_library": false,
            "edit_lab_locations_and_normals": false,
            "edit_protocol_deviations": false,
            "edit_sdv": false,
            "edit_study_settings": false,
            "execute_query_rules": false,
            "freeze_data": false,
            "generate_blank_pdf": false,
            "generate_closeout_pdf": false,
            "generate_csv": false,
            "generate_detail_pdf": false,
            "generate_export_package": false,
            "invalidate_randomization": false,
            "lab_mass_update": false,
            "labs_tab": false,
            "library_tab": false,
            "lock_data": false,
            "manage_amendments": false,
            "manage_assessments": false,
            "manage_bulk_lock_and_freeze": false,
            "manage_coder_study_settings": false,
            "manage_coding_lists": false,
            "manage_data_and_definition_export": false,
            "manage_email_group_assignment": false,
            "manage_ftp": false,
            "manage_jobs": false,
            "manage_key_mappings": false,
            "manage_lab_study_settings": false,
            "manage_lab_units_and_codelists": false,
            "manage_learning": false,
            "manage_randomization_list": false,
            "manage_review_plan_assignment_criteria": false,
            "manage_review_plan_manual_assignment": false,
            "manage_review_plans_assignment": false,
            "manage_safety_configuration": false,
            "manage_safety_integrations": false,
            "manage_site_lab_assignment": false,
            "manage_site_vault_settings": false,
            "manage_sources": false,
            "manage_study_countries": false,
            "manage_study_deployments": false,
            "manage_study_lock": false,
            "manage_study_priority": false,
            "manage_study_roles": false,
            "manage_study_sites": false,
            "manage_unblinding_rules": false,
            "manage_users": false,
            "modify_listing": false,
            "modify_view": false,
            "notify_sites_of_closeout": false,
            "open_query": false,
            "protocol_deviations_tab": false,
            "public_access": false,
            "randomization_list_actions": false,
            "randomization_tab": false,
            "randomize_subject": false,
            "reports_dashboards_tab": false,
            "restricted_data_access": false,
            "reveal_treatment": false,
            "review_closeout_pdf": false,
            "review_tab": false,
            "safety_integrations_tab": false,
            "schedule_reports": false,
            "sign": false,
            "studio_tab": false,
            "system_tools_tab": false,
            "unrestrict_randomization_data": false,
            "vault_configuration_report": false,
            "view_admin": false,
            "view_all_lab_settings": false,
            "view_bulk_lock_and_freeze": false,
            "view_casebook": true,
            "view_classification": true,
            "view_clinical_assessments": false,
            "view_code": true,
            "view_dmr": false,
            "view_export": false,
            "view_export_packages": false,
            "view_form_linking": false,
            "view_import": false,
            "view_integration_mappings": false,
            "view_lab_analyte_library": false,
            "view_lab_locations_and_normals": false,
            "view_library": true,
            "view_listings": false,
            "view_protocol_deviations": false,
            "view_queries": false,
            "view_query": true,
            "view_randomization_enrollment": false,
            "view_randomization_kit_device": false,
            "view_restricted_randomization_enrollment": false,
            "view_safety_integrations": false,
            "view_sdv": false,
            "view_selected_cdb_query_listings": false,
            "view_selected_listings": false,
            "view_study_design": true,
            "view_study_sites": true,
            "view_users": true,
            "workbench_tab": false
        },
        {
            "id": "0AR00000000I002",
            "role_api_name": "cdms_api_read_write__v",
            "role_name": "CDMS API Read Write",
            "role_team": "other__v",
            "accept_closeout_pdf": false,
            "add_casebook": true,
            "answer_query": true,
            "answer_third_party_queries": false,
            "api_access": true,
            "approve_code": false,
            "approve_import": false,
            "approve_lab_normals": false,
            "assessments_tab": true,
            "assign_code": true,
            "browse_view": false,
            "cdb_tools": false,
            "close_all_queries": false,
            "close_query": true,
            "coder_tab": true,
            "coder_tools_tab": true,
            "configure_cdb": false,
            "configure_randomization": false,
            "copy_study_data_to_ppt": false,
            "create_export_definition": false,
            "create_listing": false,
            "create_protocol_deviations": false,
            "create_view": false,
            "data_entry": true,
            "data_entry_tab": true,
            "delete_casebook": false,
            "delete_export_definition": false,
            "delete_listing": false,
            "delete_view": false,
            "design_library": true,
            "design_study": true,
            "download_import_package": false,
            "edc_tools_tab": true,
            "edit_classification": true,
            "edit_clinical_assessments": false,
            "edit_cql": false,
            "edit_dmr": false,
            "edit_form_linking": false,
            "edit_integration_mappings": false,
            "edit_lab_analyte_library": false,
            "edit_lab_locations_and_normals": false,
            "edit_protocol_deviations": false,
            "edit_sdv": false,
            "edit_study_settings": false,
            "execute_query_rules": false,
            "freeze_data": false,
            "generate_blank_pdf": false,
            "generate_closeout_pdf": false,
            "generate_csv": false,
            "generate_detail_pdf": false,
            "generate_export_package": false,
            "invalidate_randomization": false,
            "lab_mass_update": false,
            "labs_tab": true,
            "library_tab": true,
            "lock_data": false,
            "manage_amendments": false,
            "manage_assessments": false,
            "manage_bulk_lock_and_freeze": false,
            "manage_coder_study_settings": false,
            "manage_coding_lists": false,
            "manage_data_and_definition_export": false,
            "manage_email_group_assignment": true,
            "manage_ftp": false,
            "manage_jobs": true,
            "manage_key_mappings": false,
            "manage_lab_study_settings": false,
            "manage_lab_units_and_codelists": false,
            "manage_learning": false,
            "manage_randomization_list": false,
            "manage_review_plan_assignment_criteria": false,
            "manage_review_plan_manual_assignment": false,
            "manage_review_plans_assignment": false,
            "manage_safety_configuration": false,
            "manage_safety_integrations": false,
            "manage_site_lab_assignment": false,
            "manage_site_vault_settings": false,
            "manage_sources": false,
            "manage_study_countries": false,
            "manage_study_deployments": false,
            "manage_study_lock": false,
            "manage_study_priority": false,
            "manage_study_roles": false,
            "manage_study_sites": true,
            "manage_unblinding_rules": false,
            "manage_users": true,
            "modify_listing": false,
            "modify_view": false,
            "notify_sites_of_closeout": false,
            "open_query": true,
            "protocol_deviations_tab": true,
            "public_access": false,
            "randomization_list_actions": false,
            "randomization_tab": true,
            "randomize_subject": false,
            "reports_dashboards_tab": true,
            "restricted_data_access": false,
            "reveal_treatment": false,
            "review_closeout_pdf": false,
            "review_tab": true,
            "safety_integrations_tab": true,
            "schedule_reports": false,
            "sign": false,
            "studio_tab": true,
            "system_tools_tab": true,
            "unrestrict_randomization_data": false,
            "vault_configuration_report": false,
            "view_admin": false,
            "view_all_lab_settings": false,
            "view_bulk_lock_and_freeze": false,
            "view_casebook": true,
            "view_classification": true,
            "view_clinical_assessments": false,
            "view_code": true,
            "view_dmr": false,
            "view_export": false,
            "view_export_packages": false,
            "view_form_linking": false,
            "view_import": false,
            "view_integration_mappings": false,
            "view_lab_analyte_library": false,
            "view_lab_locations_and_normals": false,
            "view_library": true,
            "view_listings": false,
            "view_protocol_deviations": false,
            "view_queries": false,
            "view_query": true,
            "view_randomization_enrollment": false,
            "view_randomization_kit_device": false,
            "view_restricted_randomization_enrollment": false,
            "view_safety_integrations": false,
            "view_sdv": false,
            "view_selected_cdb_query_listings": false,
            "view_selected_listings": false,
            "view_study_design": true,
            "view_study_sites": true,
            "view_users": true,
            "workbench_tab": true
        },
        {
            "id": "0AR000000000706",
            "role_api_name": "cdms_lead_data_manager__v",
            "role_name": "CDMS Lead Data Manager",
            "role_team": "data_management__v",
            "accept_closeout_pdf": false,
            "add_casebook": false,
            "answer_query": false,
            "answer_third_party_queries": false,
            "api_access": true,
            "approve_code": false,
            "approve_import": true,
            "approve_lab_normals": false,
            "assessments_tab": false,
            "assign_code": false,
            "browse_view": true,
            "cdb_tools": true,
            "close_all_queries": true,
            "close_query": true,
            "coder_tab": false,
            "coder_tools_tab": false,
            "configure_cdb": false,
            "configure_randomization": false,
            "copy_study_data_to_ppt": false,
            "create_export_definition": true,
            "create_listing": true,
            "create_protocol_deviations": true,
            "create_view": false,
            "data_entry": false,
            "data_entry_tab": false,
            "delete_casebook": false,
            "delete_export_definition": false,
            "delete_listing": false,
            "delete_view": false,
            "design_library": false,
            "design_study": false,
            "download_import_package": true,
            "edc_tools_tab": true,
            "edit_classification": false,
            "edit_clinical_assessments": false,
            "edit_cql": true,
            "edit_dmr": true,
            "edit_form_linking": false,
            "edit_integration_mappings": true,
            "edit_lab_analyte_library": false,
            "edit_lab_locations_and_normals": false,
            "edit_protocol_deviations": true,
            "edit_sdv": false,
            "edit_study_settings": true,
            "execute_query_rules": true,
            "freeze_data": true,
            "generate_blank_pdf": true,
            "generate_closeout_pdf": true,
            "generate_csv": true,
            "generate_detail_pdf": true,
            "generate_export_package": true,
            "invalidate_randomization": false,
            "lab_mass_update": true,
            "labs_tab": true,
            "library_tab": false,
            "lock_data": true,
            "manage_amendments": true,
            "manage_assessments": true,
            "manage_bulk_lock_and_freeze": true,
            "manage_coder_study_settings": false,
            "manage_coding_lists": false,
            "manage_data_and_definition_export": false,
            "manage_email_group_assignment": true,
            "manage_ftp": true,
            "manage_jobs": true,
            "manage_key_mappings": false,
            "manage_lab_study_settings": true,
            "manage_lab_units_and_codelists": true,
            "manage_learning": true,
            "manage_randomization_list": false,
            "manage_review_plan_assignment_criteria": false,
            "manage_review_plan_manual_assignment": false,
            "manage_review_plans_assignment": true,
            "manage_safety_configuration": false,
            "manage_safety_integrations": true,
            "manage_site_lab_assignment": true,
            "manage_site_vault_settings": true,
            "manage_sources": true,
            "manage_study_countries": true,
            "manage_study_deployments": false,
            "manage_study_lock": true,
            "manage_study_priority": true,
            "manage_study_roles": true,
            "manage_study_sites": true,
            "manage_unblinding_rules": true,
            "manage_users": false,
            "modify_listing": true,
            "modify_view": false,
            "notify_sites_of_closeout": true,
            "open_query": true,
            "protocol_deviations_tab": true,
            "public_access": true,
            "randomization_list_actions": false,
            "randomization_tab": true,
            "randomize_subject": false,
            "reports_dashboards_tab": true,
            "restricted_data_access": true,
            "reveal_treatment": false,
            "review_closeout_pdf": false,
            "review_tab": true,
            "safety_integrations_tab": true,
            "schedule_reports": true,
            "sign": false,
            "studio_tab": false,
            "system_tools_tab": true,
            "unrestrict_randomization_data": false,
            "vault_configuration_report": false,
            "view_admin": false,
            "view_all_lab_settings": true,
            "view_bulk_lock_and_freeze": true,
            "view_casebook": true,
            "view_classification": false,
            "view_clinical_assessments": false,
            "view_code": true,
            "view_dmr": true,
            "view_export": true,
            "view_export_packages": true,
            "view_form_linking": true,
            "view_import": true,
            "view_integration_mappings": true,
            "view_lab_analyte_library": true,
            "view_lab_locations_and_normals": true,
            "view_library": false,
            "view_listings": true,
            "view_protocol_deviations": true,
            "view_queries": true,
            "view_query": true,
            "view_randomization_enrollment": true,
            "view_randomization_kit_device": false,
            "view_restricted_randomization_enrollment": false,
            "view_safety_integrations": true,
            "view_sdv": true,
            "view_selected_cdb_query_listings": false,
            "view_selected_listings": false,
            "view_study_design": false,
            "view_study_sites": true,
            "view_users": false,
            "workbench_tab": true
        },
    :
    :
    :
    (etc. - all other roles...)
    ]
}

Notes

Retrieve Study roles in the Vault.
The roles returned include the standard/template and configured/custom roles
The response details - role name - is used in Upload Users (CSV) and Upload Users (JSON).
As new releases come out, the list of permissions in the system will grow (e.g. add_casebook__v, view_sdv__v, etc). The response is not API version specific.

Endpoint

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

Required Permissions

The following permission is required to use the Retrieve Study Roles API:

API Access

The CDMS API Read Write and CDMS API Read Only roles grant this permission.

Headers

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

Query String Parameters

Name	Type	Required	Description
`limit`	URL parameter	No	Standard Vault behavior for limit - to limit the return body. Depending on offset used, one receives the ones starting at that point. The maximum is 1000. If the API user passed a negative integer or zero, it is converted to default (1000).
`offset`	URL parameter	No	Standard Vault behavior for offset - to limit the return body. Depending on offset used, one receives the ones starting at that point. The maximum is 2147483647 (large integer). If the API user passed a negative integer, it is converted to default (0).

Response Details

Array	Name	Description
`studyroles`	`id`	Vault internal ID for the Study role.
`studyroles`	`role_api_name`	Study role API name.
`studyroles`	`accept_closeout_pdf`	Study role acceptance closeout PDF.

Retrieve Email Groups

Request - Two email groups

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/email_groups?study=ABCP-2023-001_TST5' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - Two email groups

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "email_groups": [
        {
            "id": "XYZ0000000123",
            "name": "Main Study Alerts",
            "members": 2
        },         
        {
            "id": "XYZ0000000125",
            "name": "Safety Alerts",           
            "members": 0   
        }      
      ]
}

Notes

Retrieve information about email groups.
This API tells you if a group exists, including groups without members.
It does not provide member details. (see Retrieve Email Group Members)

Endpoint

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

Required Permissions

The following permission is required to use the Retrieve Email Groups API:

API Access

The CDMS API Read Write and CDMS API Read Only roles grant this permission.

Headers

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

Query String Parameters

Name	Type	Required	Description
`study`	URL parameter	Yes	Match of `study__v.label__v`
`limit`	URL parameter	No	Standard Vault behavior for limit - to limit the return body. Depending on offset used, one receives the ones starting at that point. The maximum is 1000. If the API user passed a negative integer or zero, it is converted to default (1000).
`offset`	URL parameter	No	Standard Vault behavior for offset - to limit the return body. Depending on offset used, one receives the ones starting at that point. The maximum is 2147483647 (large integer). If the API user passed a negative integer, it is converted to default (0).

Response Details

On SUCCESS, Vault returns information about email groups.

Array	Name	Description
`email_groups`	`id`	Vault internal ID for the email group.
`email_groups`	`name`	Name of the email group.
`email_groups`	`members`	Count of existing members in the email group.

Retrieve Email Group Members

Request - Email group with members (by ID)

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/email_groups?study=ABCP-2023-001_TST5&email_group_id=XYZ0000000123' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - Email group with members (by ID)

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "users": [
        {
            "user_id": 212333,
            "user_name": "joe.smith@sb-abcpharma.com",
            "user_email": "joe.smith@veeva.com",
            "user_last_name": "Smith",
            "user_first_name": "Joe"
        },
        {
            "user_id": 212345,
            "user_name": "mary.jones@sb-abcpharma.com",
            "user_email": "mary.jones@veeva.com",
            "user_last_name": "Jones",
            "user_first_name": "Mary"
        }
    ]
}

Request - Group with no members (by name)

curl -L -X GET 'https://my-vault.veevavault.com/api/v24.1/app/cdm/email_groups?study=ABCP-2023-001_TST5&email_group_name=Safety_Alerts' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - Group with no members (by name)

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 0,
        "total": 0
    },
    "users": []
}

Notes

Get users who are members of a single email group.
For existing email groups in the Study, see Retrieve Email Groups

Endpoint

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

Required Permissions

The following permission is required to use the Retrieve Email Group Members API:

API Access

The CDMS API Read Write and CDMS API Read Only roles grant this permission.

Headers

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

Query String Parameters

Name	Type	Required	Description
`study`	URL parameter	Yes	Match of `study__v.label__v`
`email_group_name`	URL parameter	Yes	Match to `email_group_def__v.name__v`. Name or ID is required.
`email_group_id`	URL parameter	Yes	Match to `email_group_def__v.id`. Name or ID is required. If both are provided, the ID is used for lookup, as if the name was not passed.
`limit`	URL parameter	No	Standard Vault behavior for limit to limit within the return body. Depending on the offset used, you receive the ones starting at that point. The maximum is 1000. If the API user passes a negative integer or zero, it is converted to the default (1000).
`offset`	URL parameter	No	Standard Vault behavior for offset to limit within the return body. Depending on the offset used, you receive the ones starting at that point. The maximum is 2147483647 (large integer). If the API user passes a negative integer, it is converted to the default (0).

Response Details

On SUCCESS, Vault returns members of a single email group.

Array	Name	Description
`users`	`user_id`	Vault internal ID of the user.
`users`	`user_name`	User name.
`users`	`user_email`	User's email address.
`users`	`user_last_name`	User's last name.
`users`	`user_first_name`	User's first name.

Update Email Group Members

Request - Remove existing members and set specified users

curl -L -X PUT 'https://my-vault.veevavault.com/api/v24.1/app/cdm/email_group_members' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'
-d '{
    "study": "ABCP-2022-01_DEV1",
    "email_group_name": "Main Study Alerts",
    "users": ["212333", "212345"]
}'

Response - Remove existing members and set specified users

{
    "responseStatus": "SUCCESS",
    "study": "ABCP-2022-01_DEV1",
    "email_group_id": "XYZ0000000123",
    "email_group_name": "Main Study Alerts",
    "members": 2
}

Request - Add one user to an existing group

curl -L -X POST 'https://my-vault.veevavault.com/api/v24.1/app/cdm/email_group_members' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'
-d '{
    "study": "ABCP-2022-01_DEV1",
    "email_group_name": "Main Study Alerts",
    "users": ["212336"]           
}'

Response - Add one user to an existing group

{
    "responseStatus": "SUCCESS",
    "study": "ABCP-2022-01_DEV1",
    "email_group_id": "XYZ0000000123",
    "email_group_name": "Main Study Alerts",
    "members": 12,
    "users_added": 1
}

Request - Remove a specific user from a group

curl -L -X DELETE 'https://my-vault.veevavault.com/api/v24.1/app/cdm/email_group_members' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'
-d '{
    "study": "ABCP-2022-01_DEV1",
    "email_group_name": "Main Study Alerts",
    "users": ["212347"]
}'

Response - Remove a specific user from a group

{
    "responseStatus": "SUCCESS",
    "study": "ABCP-2022-01_DEV1",
    "email_group_id": "XYZ0000000123",
    "email_group_name": "Main Study Alerts",
    "members": 11,
    "users_removed": 1
}

Notes

Update the users of an email group.
Actions possible - remove and replace users, delete all users, and add specific users.
For the different actions:
- PUT: Deletes all members and adds specified users as members (i.e., a complete replacement of the members with the supplied array of users).
- POST: Adds specified users to an email group as members. If the users are already members of the group, no change occurs.
- DELETE: Delete specified group members. No action occurs for non-members.
Learn more about Email Groups in CDMS Help.

Endpoints

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

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

DELETE /api/{version}/app/cdm/email_group_members

Required Permissions

The following permission is required to use the Update Email Group Members API:

API Access

The CDMS API Read Write role grants this permission.

Headers

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

Query String Parameters

Name	Type	Required	Description
`study`	String	Yes	Match of `study__v.label__v`.
`email_group_name`	String	No	Match to `email_group_def__v.name__v`. Name or ID is required.
`email_group_id`	String	No	Match to `email_group_def__v.id`. Name or ID is required.
`users`	JSON array of string	Yes	The users to act on. Entries are Vault user IDs.

Response Details

Name	Description
`email_group_id`	Vault internal ID for the email group.
`email_group_name`	Name of the email group.
`members`	Count of users in the email group, after PUT, POST, or DELETE.
`users_added`	Count of actual users added, during POST only. The value considers users who were already present and those included in the request.
`users_removed`	Count of actual users removed, during DELETE only. The value considers users who were previously absent from the group as well as those included in the request.

Study Design

Studies are designed using design level components that mirror the data levels:

Specifically, a Casebook Version is comprised of:
- Event Group Definition (top level)
- .. then.. -> Event Definition
- .. then.. -> Form Definition
- .. then.. -> Item Group Definition
- .. then.. -> Item Definition
- .. finally, with Codelist / Unit Codelist Definitions (used by Item Definitions)
Each casebook version yields an ordered structure of the various levels, i.e. the intended schedule of a Subject in the Study.
Once a Study is live, a casebook version is published and locked from further updates. Only brand-new casebook versions can be used for design changes.
The Vault CDMS Studio application allows for export of a Study Design Specification (SDS), plus annotated workbook (PDF) - by casebook version.
The SDS describes the entire Study design, but is not a job that can be started via the API. Further, the resulting zip file containing Excel/PDF content can be problematic for automating.
The primary Study design format for automation needs is the Casebook Design Export (next section), a JSON based representation for the Study design.
Studies go live - typically- on casebook version 1. Then, as changes / amendments happen, additional casebook versions are created, deployed, and Sites are activated to them, plus Subjects get migrated forward to the new design.

Casebook Design Export

Overview

The Casebook Design Export (CDE) is a JSON representation of the Study's design, at a specific Casebook Version.
Full JSON file for example Study : ExampleStudy-24-01_cde_v1_2024-02-16T15-51-56.json

How to Generate the CDE

To generate the CDE:

1. Determine which Casebook Versions are available for a Study: Retrieve Studies

2. Start the job against the desired Casebook Version: Start Casebook Definition Export Job.

3. Check when the job completes: Retrieve Job Status

4. When the job completes successfully, retrieve the output of the job, a JSON file: Retrieve Job Output File

Overall Structure

Overall Structure of CDE

{
  "study_name": "ABCP-2023-01_DEV1",
  "study_label": "ABCP-2023-01_DEV1",
  "study": "ABCP-2023-01_DEV1",
  "study_external_id": "ABCP-2023-01",
  "name": "Initial Version",  
  "label": "Initial Version",
  "version": 1,
  "external_id": "Initial Version",
  "file_name": "ABCP-2022-01_DEV1_cde_v1_2022-07-13T12-02-33.json",
  "created_date": "2023-10-27T20:32:01",
  "eventgroup_def": [
        :
        :
        :
  ],
  "form_def": [
        :
        :
        :
  ],
  "coding_form_def": [
        :
        :
        :
  ],
  "unit_def": [
        :
        :
        :
  ],
  "codelist_def": [
        :
        :
        :
  ]
  "study_setting": [
        :
        :
        :
  ]
}

Section	Description	Relevant SDS Tab(s)
(top)	High level information on the Study, see the table below
`eventgroup_def`	The ordered schedule of the Study. The content will be a hierarchy of Event Group -> Event -> Form for the full schedule at the Casebook Version	Schedule - Grid, Schedule - Tree, and Repeating Event Groups
`form_def`	From Form down through Codelist / Unit Definition, how each Form is structured. A Form that appears many times in the schedule section (`event_group_def`) is shown once in this section	Form Definitions
`coding_form_def`	For any Form where an Item is configured for Medical Coding, an entry appears in this section	Medical Coding Items
`unit_def`	Any unit definition in the Study schedule appears as an entry in this section. Examples - Weight, Height	Unit Codelists
`codelist_def`	Any codelist in the Study schedule appears as an entry in this section.	Codelists
`study_setting`	Studio's Study Settings page and other top level Study settings appear in this section	Study Settings

WARNING: Study settings (study_setting section) are not specific to any Casebook Version. The values will always be as of the time the job is run.

Path	Type	Notes
`study_name`	String	Value used in all endpoints to identify the Study. Alternatively, all endpoints will accept `study` (matching the label) at API release v24.2.
`study_label`	String	WARNING The `study_name` can be different from the label shown in the UI.
`study`	String	Always the same value as Study label, provided for clarity, as with Retrieve Studies. This will be an option on all APIs (instead of `study_name`) at API release v24.2.
`study_external_id`	String	Also known as 'OID'
`name`	String
`label`	String
`version`	Integer
`external_id`	String
`file_name`	String
`created_date`	String	UTC value as YYYY-MM-DDTHH:MI:SSZ

Schedule - Event Group Level

Schedule - Event Group Level (eventgroup_def)

:
:
  "eventgroup_def": [
    {
      "name": "egSCR",
      "label": "Screening",
      "override_label": "Screening",
      "external_id": "egSCR",
      "description": "My description here..", 
      "help_content": "Some help content here..",
      "repeating": false,
      "repeat_maximum": null,
      "type": "edc__v",
      "dynamic_rule": [],
      "repeat_label": [],
      "event_def" : [
            :
            : 
            :
      ]
    },
:
:
    {
      "name": "egCYCLES",
      "label": "Repeating Cycle",
      "override_label": "Repeating Cycle",
      "external_id": "egCYCLES",
      "description": null, 
      "help_content": null,
      "repeating": true,
      "repeat_maximum": 50,
      "type": "edc__v",
      "dynamic_rule": [
        {
            "name": "ruleENROLL_IN_STUDY",
            "rule_status": "active__v",
            "description": "When enrollment question is answered yet, the event group is added."
        }
      ],
      "repeat_label": [
        {
          "sequence": 1,
          "label": "Cycle 1"
        },
        {
          "sequence": 2,
          "label": "Cycle 2"
        },
        {
          "sequence": 2,
          "label": "Cycle 2"
        }
        :
        :
        {
          "sequence": 50,
          "label": "Cycle 50"
        }
      ],
      "event_def" : [
            :
            : 
            :
      ]
    },
:
:
     {
      "name": "egUNS",
      "label": "Unscheduled",
      "override_label": "Unscheduled",
      "external_id": "egUNS",
      "description": null, 
      "help_content": null,
      "repeating": true,
      "repeat_maximum": 10,
      "type": "EDC",
      "dynamic_rule": [],
      "repeat_label": [],
      "event_def" : [
            :
            : 
            :
      ]
    }
  ]
:
:

Path	SDS Tab - Column	Type / Notes
`eventgroup_def/`	Tree	(Array) Ordered the same as Studio's schedule view
`eventgroup_def/name`	Tree - C	(String)
`eventgroup_def/label`	Tree - B	(String)
`eventgroup_def/override_label`	Tree - B	(String) When a design element is used more than once in a schedule, it can have different labels at the various locations
`eventgroup_def/external_id`	Tree - O	(String) Also known as 'OID'
`eventgroup_def/description`	Tree - Z	(String)
`eventgroup_def/help_content`	-	(String) Future release field, exists in Studio design, but not shown in the Study, so excluded from SDS
`eventgroup_def/repeating`	Tree - I	(Boolean)
`eventgroup_def/repeat_maximum`	Tree - J	(Integer) When the Event Group repeats, the max is allowed
`eventgroup_def/type`	Tree - M	(String)
`eventgroup_def/dynamic_rule/`	Tree - AB	(Array) Empty array if no dynamic Rules
`eventgroup_def/dynamic_rule/name`	Tree - AB	(String)
`eventgroup_def/dynamic_rule/rule_status`	Rules - M	(String)
`eventgroup_def/dynamic_rule/description`	Rules - H	(String)
`eventgroup_def/repeat_label/`	Tree - AA and Repeating Event Groups	(String) Optional labels for each sequence or instance when the Event Group repeats
`eventgroup_def/repeat_label/sequence`	Tree - AA	(Integer)
`eventgroup_def/repeat_label/label`	Tree - AA	(String)
`eventgroup_def/event_def/`	-	(Array) Events of the Event Group, per the Study schedule (see later section)

In the schedule view of Studio pictured, the Event Groups are the outermost boxes - Screening and On Study:

For additional information regarding Event Groups, Events, and Study schedule see CDMS Help

Schedule - Event Level

Schedule - Event Level (event_def)

"eventgroup_def": [
    :
    :
    :
    "event_def": [
        {
          "name": "evSCR",
          "label": "Screening",
          "override_label": "Screening",
          "short_label": "SCR",
          "override_short_label": "SCR",
          "external_id": "evSCR",
          "description": "Screening Event",
          "help_content": "Subject Screening Event",
          "type": "edc__v",
          "dynamic": false,
          "dynamic_rule": null,
          "overdue_days": 10,
          "open_query_future_date": false,
          "open_query_out_of_window": false,    
          "event_window": [],
          "method": [],
          "form_def": [
                :
                :  
                :
           ]
        },
        {
          "name": "evV1",
          "label": "Visit 1",
          "override_label": "Visit 1",
          "short_label": "V1",
          "override_short_label": "V1",
          "external_id": "evV1",
          "description": null,
          "help_content": null,
          "type": "edc__v",
          "dynamic": true,
          "dynamic_rule": [
                {
                    "name": "ruleV1Add",
                    "rule_status": "active__v",
                    "description": "Visit 1 added when screening indicated as complete and enrolled"
                },
                {
                    "name": "ruleV1Add_CBOld",
                    "rule_status": "inactive__v",
                    "description": "Visit 1 added when screening indicated as complete and enrolled (previous CB versions)"
                }
          ],
          "overdue_days": 10,
          "open_query_future_date": true,
          "open_query_out_of_window": true,    
          "event_window": [
                {
                    "default": true,
                    "sequence": 0,
                    "offset_type": "specific_event__v",
                    "offset_eventgroup_def": "egSCR",
                    "offset_event_def": "evSCR",
                    "offset_days": 14,
                    "day_range_early": 3,
                    "day_range_late": 3
                }
           ],
           "method": ["on_site_visit__v"],
           "form_def": [
                :
                :  
                :
           ]
        },
        {
          "name": "evV2",
          "label": "Visit 2",
          "override_label": "Visit 2",
          "short_label": "V2",
          "override_short_label": "V2",
          "external_id": "evV2",
          "description": null,
          "help_content": null,
          "type": "edc__v",
          "dynamic": true,
          "dynamic_rule": [
                {
                    "name": "rule_continue_to_V2",
                    "rule_status": "active__v",
                    "description": "Indicating continue to V2, adds the event"
                }         
          ], 
          "overdue_days": 10,
          "open_query_future_date": true,
          "open_query_out_of_window": true,    
          "event_window": [
                {
                    "default": true,
                    "sequence": 0,
                    "offset_type": "previous_event__v",
                    "offset_eventgroup_def": null,
                    "offset_event_def": null,
                    "offset_days": 14,
                    "day_range_early": 3,
                    "day_range_late": 3
                }
           ],
           "method": ["on_site_visit__v", "virtual_visit__v", "at_home_visit__v"], 
           "form_def": [
                :
                :  
                :
           ]
        },
        :
        :
        :

    ]
:
:

Path	SDS Tab - Column	Type / Notes
`../event_def/`	Tree	(Array) Ordered the same as Studio's schedule view
`../event_def/name`	Tree - E	(String)
`../event_def/label`	Tree - D	(String) Default label for the Event
`../event_def/override_label`	Tree - D	(String) Should the Event be used many times (different Event Groups) in the schedule, a label can be different at the various locations
`../event_def/short_label`	Tree - L	(String) Default short label for the Event
`../event_def/override_short_label`	Tree - L	(String) Should the Event be used many times (different Event Groups) in the schedule, a short label can be different at the various locations
`../event_def/external_id`	Tree - O	(String) Also known as 'OID'
`../event_def/description`	Tree - Z	(String)
`../event_def/help_content`	-	(String) Future release field, exists in Studio design, but not shown in the Study, so excluded from SDS for now
`../event_def/type`	Tree - N	(String)
`../event_def/dynamic`	Tree - AB	(Boolean) Whether the Event is to be dynamic, i.e. added by a Rule
`../event_def/dynamic_rule/`	Tree - AB	(Array) Empty array if no dynamic Rules
`../event_def/dynamic_rule/name`	Tree - AB	(String)
`../event_def/dynamic_rule/rule_status`	Rules - M	(String)
`../event_def/dynamic_rule/description`	Rules - H	(String)
`../event_def/overdue_days`	Tree - R	(Integer) When the Event date entered plus this many days are now past, the Forms of the Event will be considered overdue
`../event_def/open_query_future_date`	Tree - Y	(Boolean) Whether or not a future date entered for the Event should generate a Query to the data entry user
`../event_def/open_query_out_of_window`	Tree - X	(String) `yes__v`, `no__v`, or `inherit__v`. The inherit means yes/no stems from the Study level setting. Otherwise the yes/no are 'at that Event' behavior
`../event_def/event_window`	Tree and Repeating Event Groups	(Array) Series of Event window rules, e.g. Visit 1 has a target of 7 days from Screening, with an allowed window of 2 days before or after the target
`../event_def/event_window/default`	-	(Boolean) If the Event is the first of a series of repeating in the Event Group, this will be `true`. Also `true` for non-repeating
`../event_def/event_window/sequence`	-	(Number) Will move 0,1,2.. for the sequence, when the Event is in a repeating Event Group
`../event_def/event_window/offset_type`	Tree - Q	(String) Whether the previous Event in the schedule (or sequence) is used, or a specific Event
`../event_def/event_window/offset_eventgroup_def`	Tree - R	(String) When the window is to a specific Event, the Event Group name where the related Event resides
`../event_def/event_window/offset_event_def`	Tree - R	(String) When the window is to a specific Event, that Event name
`../event_def/event_window/day_range_early`	Tree - U	(Integer) The Event date would be on/after this many days before the target to be considered 'in window'
`../event_def/event_window/offset_days`	Tree - T	(Integer) The target for the Event 'from' (in days) the related Event
`../event_def/event_window/day_range_late`	Tree - V	(Integer) The Event date would be on/before this many days after the target to be considered 'in window'
`../event_def/method`	Tree - P	(Array of String) Valid visit method values at this location in the Study schedule. The option must be Study enabled and valid choices are also configured per the needs of the Study.
`../event_def/form_def/`	(next section)	(Array) Forms of the Event in the Study schedule (see next section)

In the schedule view of Studio pictured, the Events are the boxes inside the outermost boxes (Event Groups) - Screening and Visit 1:

Additional information regarding Event Groups, Events, and Study schedule -> see CDMS API Help

Schedule - Form Level

Schedule - Form Level (form_def inside evengroup_def)

"eventgroup_def": [
    :
    :
    :
    "event_def": [
          :
          :
          :
          "form_def": [
            {
              "name": "DM",
              "label": "Subject Demographics",
              "override_label": "Demography",
              "short_label": "Demog",
              "override_short_label": "DM",
              "repeating": false,
              "repeat_maximum": null,
              "dynamic": false,
              "dynamic_rule": []
            },
            {
              "name": "VS",
              "label": "Vitals",
              "override_label": "Vitals",
              "short_label": "VS",
              "override_short_label": "VS",
              "repeating": false,
              "repeat_maximum": null,
              "dynamic": false,
              "dynamic_rule": []
            },
            {
              "name": "IE",
              "label": "Inclusion / Exclusion Criteria",
              "override_label": "Inclusion / Exclusion Criteria",
              "short_label": "Inc/Exc Criteria",
              "override_short_label": "Inc/Exc Criteria",
              "repeating": false,
              "repeat_maximum": null,
              "dynamic": false,
              "dynamic_rule": [],
            },
            {
              "name": "PREG_INFO",
              "label": "Pregnancy Information",
              "override_label": "Pregnancy Information",
              "short_label": "Preg Info",
              "override_short_label": "Preg Info",
              "repeating": true,
              "repeat_maximum": 5,
              "dynamic": true,
              "dynamic_rule": [
                {
                    "name": "rule_FEMALE_PREG_INFO_SHOW",
                    "rule_status": "active__v",
                    "description": "form is added only when gender = female"
                }
              ]
            }
            :
            :
            :
          ]
    ]     
]

Path	SDS Tab - Column	Type / Notes
`../form_def/`	Tree	(Array) Ordered the same as Studio's schedule view, shortened version of the Form, the next section describes 'form down' design
`../form_def/name`	Tree - G	(String) Default label for the Form
`../form_def/label`	Tree - F	(String) Should the Form be used many times (different Form) in the schedule, a label can be different at the various locations
`../form_def/override_label`	Tree - F	(String) Should the Form be used many times (different Events) in the schedule, a label can be different at the various locations
`../form_def/short_label`	Tree - L	(String) Default short label for the Form
`../form_def/override_short_label`	Tree - L	(String) Should the Form be used many times (different Events) in the schedule, a short label can be different at the various locations
`../form_def/repeating`	Tree - I	(Boolean)
`../form_def/repeat_maximum`	Tree - J	(Integer) When the Form repeats, the max allowed
`../form_def/dynamic`	Tree - AB	(Boolean) Whether the Form is to be dynamic, i.e. added by a Rule
`../form_def/dynamic_rule/`	Tree - AB	(Array)
`../form_def/dynamic_rule/name`	Tree - AB	(String)
`../form_def/dynamic_rule/rule_status`	Rules - M	(String)
`../form_def/dynamic_rule/description`	Rules - H	(String)

In the schedule view of Studio pictured, the Forms are those at the level of (example) Informed Consent, ECG, and Demographics:

Additional information regarding Event Groups, Events, and Study schedule -> see CDMS API Help

Form Definitions - Form Level

Form Definitions - Form Level (form_def standalone level)


:
:
"form_def": [
    {
        "name": "VS",
        "label": "Vitals",
        "short_label": "VS",
        "external_id": "VS",
        "special_type": [],
        "description": "Vitals Form",
        "help_content": "Enter Patient Vitals",
        "sdtm_name": "VS",
        "repeating": false,
        "repeat_maximum": null,
        "restricted": false,
        "linking_detail": [],
        "itemgroup_def": [
        :
        : 
        :
        ]
    },
    {
        "name": "AE",
        "label": "Adverse Events",
        "short_label": "AEs",
        "external_id": "AE",
        "special_type": [],
        "description": null,
        "help_content": null,
        "sdtm_name": "AE",
        "repeating": true,
        "repeat_maximum": 99,
        "restricted": false,
        "linking_detail": [
        {
            "remote_form_def": "CM",
            "form_linked_warn_empty" true,
            "description": "For SAE to CM linking"
        },
        {
            "remote_form_def": "MH",
            "form_linked_warn_empty" false,
            "description": "For SAE to MH linking"
        }
        ],
        "itemgroup_def": [
        :
        : 
        :
        ]
    },
    {
        "name": "CHEM",
        "label": "Chemistry Panel",
        "short_label": "Chemistry",
        "external_id": "CHEM",
        "special_type": ["lab__v"],
        "description": null,
        "help_content": null,
        "sdtm_name": "LB",
        "repeating": false,
        "repeat_maximum": null,
        "restricted": false,
        "linking_detail": [],
        "itemgroup_def": [
        :
        : 
        :
        ]
    },
    :
    :
]
:
:

Path	SDS Tab - Column	Type / Notes
`form_def/`	Form Definitions	(Array) Unique Forms that exist somewhere in the casebook version's schedule. If the schedule (shown in `eventgroup_def`) shows a Form many times, it only appears once in this section
`form_def/name`	Form Definitions - A	(String)
`form_def/label`	Form Definitions - B	(String) If an override label is used on a Form that appears in several Events of the full schedule, which is noted in the schedule (`eventgroup_def`) section for the locations that use an override.
`form_def/short_label`	Form Definitions - B	(String) If an override short label is used on a Form that appears in several Events of the full schedule, which is noted in the schedule (`eventgroup_def`) for the locations that use an override.
`form_def/external_id`	Form Definitions - P	(String) Also known as 'OID'
`form_def/special_type`	-	(Array of Strings) Values only appear if the Form behaves differently than standard EDC Forms. For example, a Local Labs Form will indicate `lab__v` as a special type
`form_def/description`	Form Definitions - AS	(String)
`form_def/help_content`	-	(String) Future release field, exists in Studio design, but not shown in the Study, so excluded from SDS for now
`form_def/sdtm_name`	Form Definitions - AV	(String) Property - optional - regarding data exports and SDTM format
`form_def/repeating`	Tree - I	(Boolean)
`form_def/repeat_maximum`	Tree - J	(Integer) When the Form repeats, the max allowed
`form_def/restricted`	Tree - H	(Boolean) Whether or not the Form is specially protected from certain roles in the Study (UI, reports, exports)
`form_def/linking_detail/`	Form Definitions - E	(Array) Each is a linking definition for a pair of Forms. At either Form the end user can do Form to Form Linking. Item to Form Linking information is found at the `item_def` level.
`form_def/linking_detail/remote_form_def`	-	(String) Remote Form that can be linked to this Form
`form_def/linking_detail/form_linked_warn_empty`	-	(Boolean) Whether or not to warn an end user if no links are added
`form_def/linking_detail/description`	-	(String)
`form_def/itemgroup_def/`	(next section)	(Array) Item Groups of the Form (see next section)

In the Studio view pictured, the Demographics Form content (its Item Groups and Items) is shown:

Form Definitions - Item Group Level

Form Definitions - Item Group Level (itemgroup_def)

:
:
"form_def": [
   {
    "name": "VS",
    :
    :
    :
    "itemgroup_def": [
            {
                "name": "igSUMMARY_VS",
                "label": "Vitals Summary",
                "override_label": "Summary",
                "external_id": "igSUMMARY_VS",
                "description": null,
                "help_content": null,
                "special_type": [],
                "sdtm_name": "VS",
                "repeating": false,
                "repeat_maximum": null,
                "display_format": null,
                "header_visible": true,
                "visual_group": true,
                "progressive_display": null,   
                "item_def": [
                    :
                    : 
                    :
                ]
            },
            {
                "name": "igREP_VS",
                "label": "Vitals Taken",
                "override_label": "Vitals",
                "external_id": "igREP_VS",
                "description": null,
                "help_content": null,
                "special_type": [],
                "sdtm_name": "VS",
                "repeating": true,
                "repeat_maximum": 5,
                "display_format": "editable_grid__v",
                "header_visible": true,
                "visual_group": true,
                "progressive_display": {
                    "controlling_itemgroup_def": "igSUMMARY_VS",
                    "controlling_item_def": "VS_YN",
                    "values": ["Y"],
                    "display_type_enable": true
                },   
                "item_def": [
                    :
                    : 
                    :
                ]
            }
        ]
     },
:
:

Path	SDS Tab - Column	Type / Notes
`../itemgroup_def/`	Form Definitions	(Array) Ordered the same as Studio's schedule view, the Item Groups of the Form in the casebook version.
`../itemgroup_def/name`	Form Definitions - G	(String)
`../itemgroup_def/label`	Form Definitions - H	(String)
`../itemgroup_def/override_label`	Form Definitions - T	(String) When an Item Group is used in different Forms of the schedule, it can have different labels at the various locations
`../itemgroup_def/external_id`	Form Definitions - P	(String) Also known as 'OID'
`../itemgroup_def/description`	Form Descriptions - AS	(String)
`../itemgroup_def/help_content`	-	(String) Future release field, exists in Studio design, but not shown in the Study, so excluded from SDS for now
`../itemgroup_def/special_type`	Form Definitions - AQ	(Array of String) Picklist names - `lab__v`, `lab_header__v` - special types for the Item Group
`../itemgroup_def/sdtm_name`	Form Definitions - AV	(String) Property - optional - regarding data exports and SDTM format
`../itemgroup_def/repeating`	Form Definitions - I	(Boolean)
`../itemgroup_def/repeat_maximum`	Form Definitions - I	(Integer) When the Item Group repeats, the max allowed
`../itemgroup_def/display format`	Form Definitions - M	(String) When the Item Group repeats, how it is displayed on the Form. Values - `form__v`, `read_only_grid__v`, `editable_grid__v`
`../itemgroup_def/header_visible`	Form Definitions - J	(Boolean)
`../itemgroup_def/visual_group`	Form Definitions - K	(Boolean)
`../../progressive_display`	Form Definitions	(JSON Section) When progressive display involved in the UI, the Item and it's value that drive this Item Group visually. (show/hide or enable/disable style is used)
`../../progressive_display/controlling_itemgroup_def`	Form Definitions - W	(String) The Item Group on the Form of the Item whose value(s) dictates the progressive display
`../../progressive_display/controlling_item_def`	Form Definitions - W	(String) The other Item on the Form it's value(s) that dictates the progressive display
`../../progressive_display/values`	Form Definitions - X	(String) Values of that Item that dictate the progressive display
`../../progressive_display/display_type_enable`	Form Definitions - Y	(Boolean) Whether the style of progressive display is enable/disable or not. (`false` means show/hide style is instead used)

In the Studio view pictured, General and Race/Ethnicity are Item Groups of the Form Demographics:

Form Definitions - Item Level

Form Definitions - Item Level (Date Only)

:
:
"form_def": [
   {
    "name": "DM",
    :
    :
    "itemgroup_def": [
      {
        "name": "igDM",
        :
        :
        "item_def": [
            {                                         
            "name": "DOB",
            "label": "Date of Birth",
            "override_label": null,
            "short_label": "DOB",
            "override_short_label": null,
            "hint_label": "For entry of only birth year, use unknown month and day",
            "external_id": "DOB",
            "description": null,
            "help_content": null,
            "sdtm_name": "SEX",
            "item_type": ["edc__v"],
            "data_type": "date__v",
            "label_type": null,
            "length": null,
            "precision": null,
            "codelist_def": null,
            "codelist_display_type": null,
            "indent_level": 0,        
            "unit_def": null,
            "analyte_def": null,
            "linking_detail": [],
            "default_display": [],
            "progressive_display": null,
            "query_required": true,
            "query_for_ilb": true,
            "query_for_future_date": true,
            "query_range_minimum": "2001-01-01",
            "query_range_maximum": null,
            "allow_unknown_day": true,
            "allow_unknown_month": true,
            "allow_unknown_time": false
            },
            :
            :

Form Definitions - Item Level (Date Time)

:
:
"form_def": [
   {
    "name": "PK",
    :
    :
    "itemgroup_def": [
      {
        "name": "igPK",
        :
        :
        "item_def": [
            {                                         
            "name": "PK_DATETIME",
            "label": "PK Draw Date/Time (Pre Dose)",
            "override_label": null,
            "short_label": "Draw DT (Pre Dose)",
            "override_short_label": null,
            "hint_label": null,
            "external_id": "PK_DATETIME",
            "description": null,
            "help_content": null,
            "sdtm_name": "LB_PK_DT",
            "item_type": ["edc__v"],
            "data_type": "datetime__v",
            "label_type": null,
            "length": null,
            "precision": null,
            "codelist_def": null,
            "codelist_display_type": null,
            "indent_level": 0,
            "unit_def": null,
            "analyte_def": null,
            "linking_detail": [],
            "default_display": [],
            "progressive_display": null,
            "query_required": true,
            "query_for_ilb": true,
            "query_for_future_date": true,
            "query_range_minimum": "2001-01-01",
            "query_range_maximum": null,
            "allow_unknown_day": true,
            "allow_unknown_month": true,
            "allow_unknown_time": false
            },
            :
            :

Form Definitions - Item Level (Time Only)

:
:
"form_def": [
   {
    "name": "PK",
    :
    :
    "itemgroup_def": [
      {
        "name": "igPK",
        :
        :
        "item_def": [    
            {                                         
                "name": "PK_DRAW_TIME",
                "label": "Time of Draw",
                "override_label": null,
                "short_label": "Time of Draw",
                "override_short_label": null,
                "hint_label": null,
                "external_id": "PK_DRAW_TIME",
                "description": null,
                "help_content": null,
                "sdtm_name": null,
                "item_type": ["edc__v"],
                "data_type": "time__v",
                "label_type": null,
                "length": 3,
                "precision": 0,
                "codelist_def": null,
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": null,
                "analyte_def": null,
                "linking_detail": [],
                "default_display": [],
                "progressive_display": null,
                "query_required": false,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": null,
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            },
            :
            :

Form Definitions - Item Level (Numeric without Precision)

:
:
"form_def": [
   {
    "name": "DM",
    :
    :
    "itemgroup_def": [
      {
        "name": "igDM",
        :
        :
        "item_def": [ 
            {                                         
            "name": "AGE_SCR",
            "label": "Age at Screening",
            "override_label": null,
            "short_label": "Numeric Result",
            "override_short_label": null,
            "hint_label": "(years)",
            "external_id": "AGE_SCR",
            "description": null,
            "help_content": null,
            "sdtm_name": "DM_AGE",
            "item_type": ["edc__v"],
            "data_type": "integer__v",
            "label_type": null,
            "length": 3,
            "precision": 0,
            "codelist_def": null,
            "codelist_display_type": null,
            "indent_level": 0,        
            "unit_def": null,
            "analyte_def": null,
            "linking_detail": [],
            "default_display": [],
            "progressive_display": null,
            "query_required": false,
            "query_for_ilb": false,
            "query_for_future_date": false,
            "query_range_minimum": null,
            "query_range_maximum": null,
            "allow_unknown_day": false,
            "allow_unknown_month": false,
            "allow_unknown_time": false
            },
            :
            :

Form Definitions - Item Level (Numeric with Precision)

:
:
"form_def": [
   {
    "name": "LB",
    :
    :
    "itemgroup_def": [
      {
        "name": "igLBRES",
        :
        :
        "item_def": [ 
            {                                         
                "name": "LB_RESULT",
                "label": "Lab Result (Numeric)",
                "override_label": null,
                "short_label": "Numeric Result",
                "override_short_label": null,
                "hint_label": "When value not numeric, use the text result below",
                "external_id": "LB_RESULT",
                "description": null,
                "help_content": null,
                "sdtm_name": "BMI",
                "item_type": ["edc__v"],
                "data_type": "float__v",
                "label_type": null,
                "length": 9,
                "precision": 4,
                "codelist_def": null,
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": null,
                "analyte_def": null,
                "linking_detail": [],
                "default_display": [],
                "progressive_display": null,
                "query_required": false,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": null,
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            },
            :
            :

Form Definitions - Item Level (Label - non data collecting)

:
:
"form_def": [
   {
    "name": "LB",
    :
    :
    "itemgroup_def": [
      {
        "name": "igLBRES",
        :
        :
        "item_def": [ 
            :
            :       
            {                                         
                "name": "LBL_RACE",
                "label": "For race, check all that apply:",
                "override_label": null,
                "short_label": "Check all that apply:",
                "override_short_label": null,
                "hint_label": null,
                "external_id": "LBL_RACE",
                "description": null,
                "help_content": null,
                "sdtm_name": null,
                "item_type": ["edc__v"],
                "data_type": "text__v",
                "label_type": "informational__v",
                "length": null,
                "precision": null,
                "codelist_def": null,
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": null,
                "analyte_def": null,
                "linking_detail": [],
                "default_display": [],
                "progressive_display": null,
                "query_required": false,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": null,
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
                },
                :
                :

Form Definitions - Item Level (Checkbox)

:
:
"form_def": [
   {
    "name": "AE",
    :
    :
    "itemgroup_def": [
      {
        "name": "igAEGEN",
        :
        :
        "item_def": [ 
            :
            :       
            {                                         
                "name": "AESI",
                "label": "Check if the event is an AESI",
                "override_label": null,
                "short_label": "Is AESI",
                "override_short_label": null,
                "hint_label": null,
                "external_id": "AESI",
                "description": null,
                "help_content": null,
                "sdtm_name": "AESI",
                "item_type": ["edc__v"],
                "data_type": "boolean__v",
                "label_type": null,
                "length": null,
                "precision": null,
                "codelist_def": null,
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": null,
                "analyte_def": null,
                "linking_detail": [],
                "default_display": [],
                "progressive_display": null,
                "query_required": false,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": null,
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            },
            :
            :

Form Definitions - Item Level (Item to Form Linking)

:
:
"form_def": [
   {
    "name": "MH",
    :
    :
    "itemgroup_def": [
      {
        "name": "igMHGEN",
        :
        :
        "item_def": [ 
            :
            :       
            {                                         
                "name": "MH_REL",
                "label": "Medical History Related",
                "override_label": null,
                "short_label": "MH Related",
                "override_short_label": null,
                "hint_label": null,
                "external_id": "MH_REL",
                "description": null,
                "help_content": null,
                "sdtm_name": "MH_REL",
                "item_type": ["edc__v", "reference__v"],
                "data_type": "text__v",
                "label_type": null,
                "length": null,
                "precision": null,
                "codelist_def": null,
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": null,
                "analyte_def": null,
                "linking_detail": {
                "form_name": "MH",
                "display_item_def": [
                    {
                        "itemgroup_def": "igMH_DETAILS",
                        "item_def": "MH_REPORTED"
                    },
                    {
                        "itemgroup_def": "igMH_DETAILS",
                        "item_def": "MHSTDT"
                    },
                    {
                        "itemgroup_def": "igMH_DETAILS",
                        "item_def": "MHENDT"
                    }
                ]
                },
                "default_display": [],
                "progressive_display": null,
                "query_required": false,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": null,
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            },
            :
            :

Form Definitions - Item Level (Codelist)

:
:
"form_def": [
   {
    "name": "DM",
    :
    :
    "itemgroup_def": [
      {
        "name": "igDM",
        :
        :
        "item_def": [ 
            :
            :       
            {                                         
                "name": "SEX",
                "label": "Gender",
                "override_label": null,
                "short_label": "Gender",
                "override_short_label": null,
                "hint_label": null,
                "external_id": "SEX",
                "description": null,
                "help_content": null,
                "sdtm_name": "SEX",
                "item_type": ["edc__v"],
                "data_type": "text__v",
                "label_type": null,
                "length": null,
                "precision": null,
                "codelist_def": "cl_GENDER",
                "codelist_display_type": "picklist__v",
                "indent_level": 0,
                "unit_def": null,
                "analyte_def": null,
                "linking_detail": [],
                "default_display": [],
                "progressive_display": null,
                "query_required": true,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": null,
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            },
            :
            :

Form Definitions - Item Level (Unit Definition)

:
:
"form_def": [
   {
    "name": "DM",
    :
    :
    "itemgroup_def": [
      {
        "name": "igDM",
        :
        :
        "item_def": [ 
            :
            :       
            {                                         
                "name": "WEIGHT",
                "label": "Weight",
                "override_label": null,
                "short_label": "Weight",
                "override_short_label": null,
                "hint_label": null,
                "external_id": "WEIGHT",
                "description": null,
                "help_content": null,
                "sdtm_name": "WEIGHT",
                "item_type": ["edc__v"],
                "data_type": "float__v",
                "label_type": null,
                "length": 4,
                "precision": 1,
                "codelist_def": null,
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": "WEIGHT_UNIT",
                "analyte_def": null,
                "linking_detail": [],
                "default_display": [],
                "progressive_display": null,
                "query_required": true,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": "50.5",
                "query_range_maximum": "90.5",
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            }
            :
            :

Form Definitions - Item Level (Local Lab / Analyte)

:
:
"form_def": [
   {
    "name": "LB",
    :
    :
    "itemgroup_def": [
      {
        "name": "igLB_TEST",
        :
        :
        "item_def": [ 
            :
            :       
            {                                         
                "name": "LBORRES_WBC",
                "label": "White Blood Cell Count",
                "override_label": null,
                "short_label": "WBC",
                "override_short_label": null,
                "hint_label": null,
                "external_id": "LBORRES_WBC",
                "description": null,
                "help_content": null,
                "sdtm_name": "LBORRES_WBC",
                "item_type": ["edc__v"],
                "data_type": "float__v",
                "label_type": null,
                "length": null,
                "precision": null,
                "codelist_def": null,
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": "CHEM_UNITS",
                "analyte_def": "wbc__v",
                "linking_detail": [],
                "default_display": [],
                "progressive_display": null,
                "query_required": true,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": null,
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            },
            :
            :

Form Definitions - Item Level (Involves Defaulting of Item Groups)

:
:
"form_def": [
   {
    "name": "PK",
    :
    :
    "itemgroup_def": [
      {
        "name": "igPK",
        :
        :
        "item_def": [ 
            :
            :       
            {                                         
                "name": "PK_DRAW_TIME",
                "label": "Draw",
                "override_label": null,
                "short_label": "Draw",
                "override_short_label": null,
                "hint_label": null,
                "external_id": "PK_DRAW_TIME",
                "description": null,
                "help_content": null,
                "sdtm_name": "PK_TIME_PERIOD",
                "item_type": ["edc__v", "read_only__v"],
                "data_type": "text__v",
                "label_type": null,
                "length": null,
                "precision": null,
                "codelist_def": "PK_DRAW_PERIODS",
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": null,
                "analyte_def": null,
                "linking_detail": null,
                "default_display": [
                    {
                        "sequence": 1,
                        "code": "PRE_DOSE"
                    },
                    {
                        "sequence": 2,
                        "code": "HOUR_1"
                    },
                    {
                        "sequence": 3,
                        "code": "HOUR_2"
                    },
                    {
                        "sequence": 4,
                        "code": "HOUR_4"
                    },
                    {
                        "sequence": 5,
                        "code": "HOUR_8"
                    }
                ],
                "progressive_display": null,
                "query_required": false,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": null,
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            }
            :
            :

Form Definitions - Item Level (Involves Progressive Display)

:
:
"form_def": [
   {
    "name": "DM",
    :
    :
    "itemgroup_def": [
      {
        "name": "igDMGEN",
        :
        :
        "item_def": [ 
            :
            :
            {                                         
                "name": "LAST_MENST",
                "label": "Last Menstrual Date",
                "override_label": null,
                "short_label": "Last Menstrual",
                "override_short_label": null,
                "hint_label": null,
                "external_id": "LAST_MENST",
                "description": null,
                "help_content": null,
                "sdtm_name": "LAST_MENST",
                "item_type": ["edc__v"],
                "data_type": "date__v",
                "label_type": null,
                "length": null,
                "precision": null,
                "codelist_def": null,
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": null,
                "analyte_def": null,
                "linking_detail": [],
                "default_display": [],
                "progressive_display": 
                   {
                    "controlling_itemgroup": "igDEMOG_GEN",
                    "controlling_item": "GENDER",
                    "values": ["F"],
                    "display_type_enable": true
                   },
                "query_required": true,
                "query_for_ilb": true,
                "query_for_future_date": true,
                "query_range_minimum": "2023-06-30",
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            }
            :
            :

Form Definitions - Item Level (Derived / Read Only)

:
:
"form_def": [
   {
    "name": "DM",
    :
    :
    "itemgroup_def": [
      {
        "name": "igDMGEN",
        :
        :
        "item_def": [ 
            :
            :
            {                                         
                "name": "BMI",
                "label": "BMI (Calculated)",
                "override_label": null,
                "short_label": "Time of Draw",
                "override_short_label": null,
                "hint_label": "This value is calculated on submit of the form",
                "external_id": "BMI",
                "description": null,
                "help_content": null,
                "sdtm_name": "BMI",
                "item_type": ["edc__v", "derived__v", "read_only__v"],
                "data_type": "float__v",
                "label_type": null,
                "length": 4,
                "precision": 2,
                "codelist_def": null,
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": null,
                "analyte_def": null,
                "linking_detail": [],
                "default_display": [],
                "progressive_display": null,
                "query_required": false,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": null,
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            }
            :
            :

Form Definitions - Item Level (URI)

:
:
"form_def": [
   {
    "name": "DM",
    :
    :
    "itemgroup_def": [
      {
        "name": "igDMGEN",
        :
        :
        "item_def": [ 
            :
            :
            {                                         
                "name": "MY_URL",
                "label": "Enter URL of the Submitted Report",
                "override_label": null,
                "short_label": "URL for Report",
                "override_short_label": null,
                "hint_label": null,
                "external_id": "MY_URL",
                "description": null,
                "help_content": null,
                "sdtm_name": "CUS_URL",
                "item_type": ["edc__v"],
                "data_type": "uri__v",
                "label_type": null,
                "length": null,
                "precision": null,
                "codelist_def": null,
                "codelist_display_type": null,
                "indent_level": 0,
                "unit_def": null,
                "analyte_def": null,
                "linking_detail": [],
                "default_display": [],
                "progressive_display": null,
                "query_required": false,
                "query_for_ilb": false,
                "query_for_future_date": false,
                "query_range_minimum": null,
                "query_range_maximum": null,
                "allow_unknown_day": false,
                "allow_unknown_month": false,
                "allow_unknown_time": false
            }
            :
            :

Path	SDS Tab - Column	Type / Notes
`../item_def/`	Form Definitions	(Array) Ordered the same as Studio's schedule view, the Items in the_Item Group_ at the casebook version.
`../item_def/name`	Form Definitions - O	(String)
`../item_def/label`	Form Definitions - Q	(String)
`../item_def/override_label`	Form Definitions - T	(String) Should the Item be used many times (different Item Groups) in the schedule, a label can be different at the various locations
`../item_def/short_label`	Form Definitions - AL	(String)
`../item_def/override_short_label`	Form Definitions - AL	(String) Should the Item be used many times (different Item Groups) in the schedule, a short label can be different at the various locations
`../item_def/hint_label`	Form Definitions - AG	(String) Text to the right of the field in italics
`../item_def/external_id`	Form Definitions - P	(String) Also known as 'OID'
`../item_def/description`	Form Definitions - AS	(String)
`../item_def/help_content`	Form Definitions - AH	(String) Hover text on the Item label. In SDS, column name is Hover Help
`../item_def/sdtm_name`	Form Definitions - AV	(String) Property - optional - regarding data exports and SDTM format
`../item_def/item_type`	Form Definitions - AM to AR	(Array of String) Values in the array are the signal of the 'Yes' in the SDS column(s)
`../item_def/data_type`	Form Definitions - R	(String)
`../item_def/label_type`	Form Definitions - AR	(String)
`../item_def/length`	Form Definitions - AD	(Integer) Maximum number of digits for the whole part of a numeric value, or maximum characters for a text value
`../item_def/precision`	Form Definitions - AE	(Integer) Maximum number of digits for the decimal part of a numeric value
`../item_def/codelist_def`	Form Definitions - Z	(String)
`../item_def/codelist_display_type`	Form Definitions - AA	(String) Style of the codelist, whether Picklist, Radio Buttons (horizontal), or Radio Buttons (vertical)
`../item_def/indent_level`	Form Definitions - U	(Integer) The indent level from the left side (`0` = not indented)
`../item_def/unit_def`	Form Definitions -	(String)
`../item_def/analyte_def`	Form Definitions - V	(String) If an Item that collects values for the Local Labs module, which analyte
`../item_def/linking_detail/`	Form Definitions - AT	(JSON Section)If the Item is an Item to Form type, this is the detail of that remote Form being linked
`../item_def/linking_detail/remote_form_def`	Form Definitions - AT	(String) Remote Form being linked to by the Item
`../item_def/linking_detail/display_item_def/`	Form Definitions - AU	(Array) Items from the Remote Form (values on it) to display inline on this Form
`../item_def/linking_detail/display_item_def/itemgroup_def`	Form Definitions - AU	(String) Item Group of the Item on the remote Form (its value) to display inline
`../item_def/linking_detail/display_item_def/item_def`	Form Definitions - AU	(String) Item on the remote Form (its value) to display inline
`../item_def/default_display/`	Form Definitions - N	(Array) When the Item Group of the Item is involved in defaulting on first visiting the Form, these are the values seeded
`../item_def/default_display/sequence`	Form Definitions - N	(Integer) The Item Group sequence getting that value on default add
`../item_def/default_display/code`	Form Definitions - N	(Integer) The Item value being set on default add (at the sequence)
`../../progressive_display`	Form Definitions	(JSON Section) When progressive display involved in the UI, the Item and it's value that drive this Item visually. (show/hide or enable/disable style is used)
`../../progressive_display/controlling_itemgroup_def`	Form Definitions - W	(String) The Item Group on the Form of the Item whose value(s) dictates the progressive display
`../../progressive_display/controlling_item_def`	Form Definitions - W	(String) The other Item on the Form it's value(s) that dictates the progressive display
`../../progressive_display/values`	Form Definitions - X	(String) Values of that Item that dictate the progressive display
`../../progressive_display/display_type_enable`	Form Definitions - Y	(Boolean) Whether the style of progressive display is enable/disable or not. (`false` means show/hide style is instead used)
`../item_def/query_required`	Form Definitions -	(Boolean) Whether or not the Item requires a value. (`true` = query fires on the Item)
`../item_def/query_for_ilb`	Form Definitions -	(Boolean) Whether or not the Item should or should not allow the Intentionally Left Blank action. (`true` = query fires on the Item when set ILB)
`../item_def/query_for_future_date`	Form Definitions -	(Boolean) Whether or not the Item should allow future dates (`true` = query fires on the Item when value is in future)
`../item_def/query_range_minimum`	Form Definitions -	(String) Minimum value such that a value below/before (date or numeric Items) will fire a query
`../item_def/query_range_maximum`	Form Definitions -	(String) Maximum value such that a value above/after (date or numeric Items) will fire a query
`../item_def/allow_unknown_day`	Form Definitions - AF	(Boolean) For date or datetime Items, whether the day portion of the value is allowed to be unknown. (dd* will appear in SDS)
`../item_def/allow_unknown_month`	Form Definitions - AF	(Boolean) For date or datetime Items, whether the month portion of the value is allowed to be unknown. (MMM* will appear in SDS)
`../item_def/allow_unknown_time`	Form Definitions - AF	(Boolean) For datetime Items, whether the time portion of the value is allowed to be unknown.

In the Studio view pictured, Item examples include Year of Birth, Gender, and Ethnicity:

Coding Form Definitions

Coding Form Definitions

:
:
  "coding_form_def": [
    {
      "form_def": "AE",
      "form_type": "ae__v",
      "form_type_other_label": null,
      "form_coding_status", "active__v",
      "dictionary": "MedDRA",
      "dictionary_release": "MedDRA_25_1",
      "coding_definition_name": "VV-12345",
      "coding_definition_id": "XYZ000000034",
      "coding_status": "active__v",
      "coding_item_def": "AETERM",
      "related_item_def": [ ]
    },
    {
      "form_def": "CM",
      "form_type": "conmed__v",
      "form_type_other_label": null,
      "form_coding_status", "active__v",
      "dictionary": "WHODrug",
      "dictionary_release": "GLOBALC3Mar23",
      "coding_definition_name": "VV-12347",
      "coding_definition_id": "XYZ000000037",
      "coding_status": "needs_dictionary__v",
      "coding_item_def": "CMTERM",
      "related_item_def": [
            {
                "item_def": "CMDOSE",
                "type": "dose__v",
                "type_other": null
            },
            {
                "item_def": "CMROUTE",
                "type": "route__v",
                "type_other": null
            }
      ]
    },
    {
      "form_def": "DTH",
      "form_type": "other__v",
      "form_type_other_label": "Death Cause",
      "form_coding_status", "active__v",
      "dictionary": "MedDRA",
      "dictionary_release": "MedDRA_25_1",
      "coding_definition_name": "VV-12349",
      "coding_definition_id": "XYZ000000040",
      "coding_status": "active__v",
      "coding_item_def": "REP_CAUSE",
      "related_item_def": [
            {
                "item_def": "CAUSE_TYPE",
                "type": "other__v",
                "type_other": "Death Cause Type"
            }    
      ]
    }
  ]
:
:

Path	SDS Tab - Column	Type / Notes
`coding_form_def/`	Medical Coding Items	(Array) Each Form in the Study that is configured for medical coding. See also Retrieve Coding Definitions
`coding_form_def/form_def`	Medical Coding Items - A	(String) The Form design name where coding happens
`coding_form_def/form_type`	Medical Coding Items - C	(String) Type of coding taking place on the Form
`coding_form_def/form_type_other_label`	Medical Coding Items - C	(String) When `form_type` = `other__v`, the label to use in in parenthesis in the SDS
`coding_form_def/form_coding_status`	-	(String)
`coding_form_def/dictionary`	-	(String)
`coding_form_def/dictionary_release`	-	(String)
`coding_form_def/coding_definition_name`	-	(String) The Vault internal `name__v` of the definition
`coding_form_def/coding_definition_id`	-	(String) The Vault internal `id` of the definition
`coding_form_def/coding_status`	-	(String)
`coding_form_def/coding_item_def`	Medical Coding Items - E	(String) The Item on the Form whose value will take part in medical coding
`coding_form_def/related_item_def/`	Medical Coding Items	(Array) Other Items on the Form (their values) that will be stored on the coding request
`coding_form_def/related_item_def/item_def`	Medical Coding Items - G	(String)
`coding_form_def/related_item_def/type`	Medical Coding Items - I	(String)
`coding_form_def/related_item_def/type_other`	Medical Coding Items - I	(String)

In the Studio view pictured, the Form ConMed has a Drug Name Item being coded, with additional properties for the coding request from other Items on the same Form:

Codelists

Codelists

:
:
    "codelist_def": [
        {
            "name": "cYN",
            "external_id": "cYN", 
            "description": "My description text here",
            "lab_related": false,
            "choice": [
                {
                    "sequence": 1,
                     "code": "Y",
                    "label": "Yes",
                    "description": null,
                    "hidden": false
                },
                {
                    "sequence": 2,
                     "code": "N",
                    "label": "No",
                    "description": null,
                    "hidden": false
                }
            ]
        },
        {
          "name": "AEOUT",
          "external_id": "AEOUT",
          "description": null,
          "lab_related": false,
          "choice": [
            {
              "sequence": 1,
              "code": "RECOVERED",
              "label": "Recovered / Resolved",
              "description": null,
              "hidden": false
            },
            {
              "sequence": 2,
              "code": "RECOVERING",
              "label": "Recovering / Resolving",
              "description": null,
              "hidden": false
            },
            {
              "sequence": 3,
              "code": "NOT_RECOVERED",
              "label": "Not Recovered / Resolved",
              "description": null,
              "hidden": false
            },
            {
              "sequence": 4,
              "code": "RECOVERED_W_SEQ",
              "label": "Recovered / Resolved with Sequelae",
              "description": null,
              "hidden": false
            },
            {
              "sequence": 5,
              "code": "FATAL",
              "label": "Fatal",
              "description": null,
              "hidden": false
            },
            {
              "sequence": 6,
              "code": "UNKNOWN",
              "label": "Unknown",
              "description": null,
              "hidden": false
            }
          ]
        },
        :
        :
        :
    ]   
:
:

Path	SDS Tab - Column	Type / Notes
`codelist_def/`	Codelists	(Array) Each Codelist that appears at least once in an Item of the casebook version
`codelist_def/name`	Codelists - A	(String)
`codelist_def/external_id`	Codelists - B	(String)
`codelist_def/description`	Codelists - C	(String)
`codelist_def/lab_related`	Codelists - H	(Boolean) Whether or not the Codelist is part of the Local Labs module
`codelist_def/choice/`	Codelists	(Array) The choices of the Codelist
`codelist_def/choice/sequence`	Codelists	(Integer) Order is 'reading down' in Studio, SDS, EDC UI
`codelist_def/choice/code`	Codelists - E	(String)
`codelist_def/choice/label`	Codelists - F	(String)
`codelist_def/choice/description`	Codelists - C	(String)
`codelist_def/choice/hidden`	Codelists - G	(Boolean) Whether the choice is hidden or not, in the casebook version

Unit Definitions

Unit Definitions

:
:
    "unit_def": [
        {
            "name": "uclWEIGHT",
            "label": "Weight - KG / LB",
            "external_id": "uclWEIGHT",  
            "description": "My description text here",
            "lab_related": false,
            "choice": [
                {
                    "sequence": 1,
                    "name": "kg",
                    "label": "Kilograms",
                    "description": null,
                    "hidden": false,
                    "standard": true,      
                    "abbreviation": "KG", 
                    "external_id": "KG",               
                    "unit_conversion": null
                },
                {
                    "sequence": 2,
                    "name": "lbs",
                    "label": "Pounds",
                    "description": null,
                    "hidden": false,
                    "standard": false,      
                    "abbreviation": "LBS", 
                    "external_id": "LBS",                  
                    "unit_conversion": "$value__v /2.2046"
                }
            ]
        },
    :
    :
    ]

Path	SDS Tab - Column	Type / Notes
`unit_def/`	Unit Codelists	(Array) Each Unit Definition that appears at least once in an Item of the casebook version
`unit_def/name`	Unit Codelists - A	(String)
`unit_def/label`	-	(String)
`unit_def/external_id`	Unit Codelists - H	(String)
`unit_def/type`	Unit Codelists - C	(String)
`unit_def/description`	Unit Codelists - B	(String)
`unit_def/lab_related`	Unit Codelists - J	(Boolean) Whether or not the Unit Definition is part of the Local Labs module
`unit_def/choice/`	Unit Codelists	(Array) The choices of the Unit
`unit_def/choice/sequence`	Unit Codelists	(Integer) Order is 'reading down' in Studio, SDS, EDC UI
`unit_def/choice/name`	Unit Codelists - A	(String)
`unit_def/choice/code`	Unit Codelists - D	(String)
`unit_def/choice/label`	Unit Codelists - E	(String)
`unit_def/choice/description`	Unit Codelists - B	(String)
`unit_def/choice/hidden`	Unit Codelists - I	(Boolean) Whether the choice is hidden or not, in the casebook version
`unit_def/choice/standard`	Unit Codelists - F	(Boolean) Whether or not the unit choice is the Study default unit
`unit_def/choice/abbreviation`	-	(String)
`unit_def/choice/external_id`	Unit Codelists - H	(String)
`unit_def/choice/unit_conversion`	Unit Codelists - G	(String) The formula used to convert a value of that unit to the default unit

Additional information regarding Unit Definitions -> see CDMS API Help

Study Settings

Study Settings

:
:
    "study_setting": [
         {
            "setting_name": "environment_type",
            "setting label": "Environment Type",
            "value": "development__v",
            "value_label": "Development"
        },
        {
            "setting_name": "study_phase",
            "setting label": "Study Phase",
            "value": "phase_i__v",
            "value_label": "Phase I"
        },
        {
            "setting_name": "standard_date_format",
            "setting_label": "Standard Date Format",
            "value": "dd-MMM-yyyy"
        },       
        :
        : 
    ]

Path	SDS Tab - Column	Type / Notes
`study_setting/`	Study Settings	(Array)
`study_setting/setting_name`	Study Settings	(String)
`study_setting/setting_label`	Study Settings	(String)
`study_setting/value`	Study Settings	(String)
`study_setting/value_label`	Study Settings	(String) When the value originates from a Vault Picklist, then this is the picklist label. (`value` = picklist name). This property is omitted from the entry when the setting is not of picklist type

Additional information regarding Study settings:

Setting Name	Setting Label	Location / Notes
`environment_type`	Environment Type	Picklist, so both value and value_label to be shown
`study_instance_label`	Study Label
`external_id`	External ID	(Studio)
`study_phase`	Study Phase	(Studio) Picklist, so both value and value_label to be shown
`study_status`	CDMS Study Status	(Studio) Picklist, so both value and value_label to be shown
`standard_date_format`	Standard Date Format	(Studio)
`twelve_hour_time`	Twelve Hour Time	(Studio) Values: true/ false
`reason_for_change_other_specify`	Enable Other Specify - Reason for change	(Studio) Values: true/ false
`intentionally_left_blank_other_specify`	Enable Other Specify - Intentionally Left Blank	(Studio) Values: true/ false
`enable_team_query_restrictions`	Enable Team Query Restrictions	(Studio) Values: true/ false
`system_query_team`	Query Team for System Queries	(Studio) Values: (plain text, field is Text(50))
`enable_randomization`	Enable Veeva Randomization
`enable_local_labs`	Enable Local Labs	(Studio) Values: true/ false
`safety_integration_type`	Safety Integration Type	(Studio) Picklist, so included value AND value_label in return
`lab_default_fire_queries`	Local Labs - Fire Out-of-range Queries by Default	(Labs) Omitted when `enable_local_labs` = `false`
`age_calculations_default_values`	Local Labs - Default Day and Month for Age Calculations (MM-DD)	(Labs) Omitted when `enable_local_labs` = `false`
`lab_clinical_significance`	Local Labs - Enable Clinical Significance	(Labs) Omitted when `enable_local_labs` = `false`
`enable_normal_override`	Local Labs - Enable Normal Override	(Labs) Omitted when `enable_local_labs` = `false`
`disable_unit_selection_for_lab_results`	Local Labs - Disable Unit Selection for Results	(Labs) Omitted when `enable_local_labs` = `false`
`enable_protocol_deviations`	Enable Protocol Deviations	(Studio) Values: true/ false
`enable_additive_review`	Enable Additive Review	(Studio) Values: true/ false
`subject_id_gen_type`	Subject ID Generation - Type	(Studio) Picklist, so both value and value_label to be shown
`subject_id_gen_format`	Subject ID Generation - Format	(Studio)
`subject_id_range_start`	Subject ID Generation - Range Start	(Studio)
`subject_id_range_end`	Subject ID Generation - Range End	(Studio)
`event_out_of_window_add_query`	Event Out of Window Add Query	(Studio) Values: true/ false
`enable_assessments`	Enable Assessments	(Studio) Values: true/ false

Retrieve Casebook Definition Versions

Request - Retrieve Studies (for Casebook Versions)

curl -L -X GET 'https://myvault.veevavault.com/api/v24.1/app/cdm/studies' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response - Retrieve Studies (for Casebook Versions)

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "studies": [
        {
            "study_name": "Labrinone_DEV1",
            "external_id": "Labrinone",
            "study_phase": "Phase III",
            "study_status": "Execution",
            "casebook_versions": [
                {
                    "study_name": "Labrinone_DEV1",
                    "casebook_version": 1,
                    "version_name": "Initial Version",
                    "external_id": "1",
                    "previous_version_name": null,
                    "description": null,
                    "change_reason": null,
                    "casebook_status": "in_progress__v",
                    "created_by": "Eric Emerton",
                    "created_date": "2018-02-12T22:32:21Z",
                    "last_modified_date": "2020-03-04T14:16:20Z"
                }
            ]
        },
        {
            "study_name": "ABCP-2022-01_DEV1",
            "external_id": "ABCP-2022-01",
            "study_phase": "Phase I",
            "study_status": "Planning",
            "casebook_versions": [
                {
                    "study_name": "ABCP-2022-01_DEV1",
                    "casebook_version": 2,
                    "version_name": "Version2",
                    "external_id": "Initial Version",
                    "previous_version_name": null,
                    "description": "Casebook Definition for the ABCP-2022-01_DEV1 study" ,
                    "change_reason": "Layout changes",
                    "casebook_status": "in_progress__v",
                    "created_by": "Maisha Muddaththir",
                    "created_date": "2023-06-09T13:26:34Z",
                    "last_modified_date": "2023-06-09T13:26:34Z"
                },
                {
                    "study_name": "ABCP-2022-01_DEV1",
                    "casebook_version": 1,
                    "version_name": "Initial Version",
                    "external_id": "Initial Version",
                    "previous_version_name": null,
                    "description": "Initial casebook definition version for the ABCP-2022-01_DEV1 study" ,
                    "change_reason": null,
                    "casebook_status": "published__v",
                    "created_by": "Maisha Muddaththir",
                    "created_date": "2023-06-09T13:26:34Z",
                    "last_modified_date": "2023-06-09T13:26:34Z"
                }
            ]
        }
    ]
}

Currently, the casebook definitions are available via the Retrieve Studies API. The return comprised what casebook versions exist, but not the schedule / detail of each.

Retrieve Coding Definitions

Request

curl -L -X GET 'https://myvault.veevavault.com/api/v24.1/app/cdm/coder/forms?study_name=ABCP-2022-01_DEV1' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 3,
        "total": 3
    },
    "forms": [
        {
            "form_name": "AE",
            "form_type": "ae__v",
            "form_definition_status": "active__v",
            "form_coding_status": "active__v",
            "dictionary_definition": "MedDRA",
            "dictionary_release": "MedDRA_25_1",
            "coding_item_definition_id": "V0T000000002001",
            "coding_item_definition_name": "VV-000004"
        },
        {
            "form_name": "MULTI_CODING",
            "form_type": "other__v",
            "form_type_other_label": "My Other Label Here",
            "form_definition_status": "active__v",
            "form_coding_status": "active__v",
            "dictionary_definition": "MedDRA",
            "dictionary_release": "MedDRA_25_1",
            "coding_item_definition_id": "V0T000000003001",
            "coding_item_definition_name": "VV-000005"
        },
        {
            "form_name": "Concomitant-Medication",
            "form_type": "conmed__v",
            "form_definition_status": "active__v",
            "form_coding_status": "active__v",
            "dictionary_definition": "WHODrug C3",
            "dictionary_release": "GLOBALC3Mar22",
            "coding_item_definition_id": "V0T000000004001",
            "coding_item_definition_name": "VV-000006"
        }
    ]
}

Notes

Retrieves a list of coding-enabled Form Definitions in a Study.
This API returns values required to use the Retrieve Coding Requests endpoint.
Depending on Study design changes, additional entries can/will be returned, but with inactive__v value for form_definition_status. These additional entries might have older coding requests tied to them, but the Form has since updated to a new coding configuration, it tied to the newer coding requests

Endpoint

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

Required Permissions

The following permissions are required to use the Retrieve Coding Definitions API:

API Access
View Code

The CDMS API Read Only and CDMS API Read Write roles grant these permissions.

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 (Study Number) of the Study (`study__v.name__v`) that you want to retrieve the coding-enabled Form Definitions for, returned as `study_name` by the Retrieve Studies API.

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer). If omitted, the default is 1. For example, if the `limit` is set to "100", and there are 150 possible records, use "101" as the `offset` to show results 101 through 150.

Response Details

On SUCCESS, Vault returns a list of Forms (as JSON array entries) where Medical Coding is configured to occur. The information includes:

Array	Name	Description
`forms`	`form_name`	Study design name for a Form where Medical Coding is configured to occur.
`forms`	`form_type`	The picklist name of the type of coding - `ae__v`, `conmed__v`, `medical_history__v`, or `other__v`.
`forms`	`form_definition_status`	The picklist name for status of the definition. Possible values are `active__v` or `inactive__v`.
`forms`	`form_coding_status`	The picklist name for current status within the Study. Possible values are `active__v` (creating coding requests allowed), `needs_dictionary__v` (no dictionary version set yet), `needs_synonym_list__v`, `study_locked__v`, `upversioning__v`, or `failed_upversioning__v`.
`forms`	`dictionary_definition`	The name value from the Vault's configured Medical Coding Dictionary Definition records. These values are typically one of `MedDRA`, `WHODrug B3`, `WHODrug C3`, or `Custom`.
`forms`	`dictionary_release`	Name value of the dictionary in use at the coding location. Examples - `MedDRA_25_1`, `GLOBALC3Mar22`
`forms`	`coding_item_definition_id`	The Vault internal ID of the Medical Coding Item Definition. This value is used in Retrieve Coding Requests.
`forms`	`coding_item_definition_name`	The Vault name value of the Medical Coding Item Definition, for additional reference. Previously this was used in retrieving specific Medical Coding Requests.

Retrieve Study Masters

Request - Get study masters in a vault

curl -L -X GET 'https://myvault.veevavault.com/api/v24.1/app/cdm/design/study_masters' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 3,
        "total": 3
    },
    "study_masters": [
        {
            "study_master_name": "ABCP-2023-01",
            "organization_name": "ABC Pharma",
            "external_id": "",
            "library": false,
            "study_instances": [
                {          
                    "study_id": "OOZ00000009W001",
                    "study_name": "ABCP-2023-01_DEV1",
                    "study_label": "ABCP-2023-01_DEV1",
                    "study_external_id": "ABCP-2023-01",
                   "created_date": "2023-04-06T18:49:42Z",
                    "last_deployed_date": null,
                    "environment_type": "development__v",
                    "instance_status": "live__v",
                    "build_number": 15,
                    "highest_casebook_version": 1,
                    "sequence": 1,
                    "vault_id": 114107,
                    "vault_name": "My Development Vault"
                },
                {          
                    "study_id": "-remote vault-",
                    "study_name": "-remote vault-",
                    "study_label": "ABCP-2023-01_TST1",
                    "study_external_id": "-remote vault-",
                    "created_date": "2023-04-17T18:49:42Z",
                    "last_deployed_date": "2023-04-20T13:49:42Z",
                    "environment_type": "test__v",
                    "instance_status": "live__v",
                    "build_number": 13,
                    "highest_casebook_version": 1,
                    "sequence": 1,
                    "vault_id": 114108,
                    "vault_name": "My TST Vault"
                }
            ]
        },
        :
        : 
        :
    ]
}

Notes

This action can be performed from any Vault type (Development, Test, Prod, Training), but makes the most sense when from the Development / ‘Control Center’ Vault (where deployments happen from).
Control center CDMS Vaults drive the deployments Dev -> Test(s) -> Production
Thusly, they have the best information on where a Study master stands, relative to its instances.

Endpoint

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

Required Permissions

The following permissions are required to use the Retrieve Coding Definitions API:

API Access
View Study Design and/or View Library

The CDMS API Read Only and CDMS API Read Write roles grant these permissions.

Headers

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

Query Parameters

Include the following parameters to filter the results:

Name	Description
`study_master_name`	Optional A specific Study to filter the response to, or all is returned.
`organization_name`	Optional A specific organization in the Vault that holds the Studies.
`library`	Optional Boolean, true or false to filter to Library / Collection Studies only, or non-Library. When not provided, there is no filter on the property.

This API supports pagination. By default, the page limit is set to 1000 records. The pagination parameters are:

Name	Description
`limit`	The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
`offset`	The starting record number for the result set (as a positive integer). If omitted, the default is 1. For example, if the `limit` is set to "100", and there are 150 possible records, use "101" as the `offset` to show results 101 through 150.

Response Details

On SUCCESS, Vault returns a list of Study Masters (as JSON array entries). The information includes:

Array	Name	Description
	`study_master_name`	The overall name of the Study, often one to one with the name in the production instance.
	`organization_name`	The organization name the Study belongs to, is associated with.
	`external_id`	For the Study master, its external ID, often the same as the Study master name.
	`library`	true / false - whether the Study is classified for library purposes (or not)
`study_instances`	`study_id`	Study ID value, if local to the Vault being API'ed against. If the instance is in a remote Vault, this will not be known, so -remote Vault- is returned.
`study_instances`	`study_name`	Study name value, if local to the Vault being API'ed against. If the instance is in a remote Vault, this will not be known, so -remote Vault- is returned.
`study_instances`	`study_label`	The intended Study instance label in that target Vault. (as known in the development / control center Vault)
`study_instances`	`study_external_id`	Study external ID value. If the instance is in a remote Vault, this will not be known, so -remote Vault- is returned.
`study_instances`	`created_date`	Creation of the instance. This does NOT equate to when an instance was deployed 'to', just when setup for future deployment.
`study_instances`	`last_deployed_date`	If deployed, when was the most recent
`study_instances`	`environment_type`	The type of instance, e.g. development, test, training, production
`study_instances`	`instance_status`	If live__v the instance has been deployed to, at least once.
`study_instances`	`build_number`	The Study build number the Study instance contains.
`study_instances`	`highest_casebook_version`	The Study design casebook version (highest) the Study instance resides.
`study_instances`	`sequence`	The sequence of the instance
`study_instances`	`vault_id`	The ID of the Vault the instance resides (could be the same Vault, or other)
`study_instances`	`vault_name`	The name of the Vault the instance resides (could be the same Vault, or other)

Create Study Master

Request - Create a new study master, with external ID provided

curl -X POST  https://my-vault.veevavault.com/api/v24.1/app/cdm/subjects \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
{
    "study_master_name": "ABCP-2023-01",
    "organization_name": "ABC Pharma",
    "external_id": "ABCP-2023-01",
}
'

Response - Two subjects created at once

{
    "responseStatus": "SUCCESS",     
    "study_master_name": "ABCP-2023-01",
    "organization_name": "ABC Pharma",
    "external_id": "ABCP-2023-01",
    "library": false, 
    "study_instances": [
        {          
            "study_id": "OOZ00000009W001",
            "study_name": "ABCP-2023-01_DEV1",
            "study_label": "ABCP-2023-01_DEV1",
            "instance_created_date": "2023-04-06T18:49:42Z",
            "last_deployed_date": null,
            "environment_type": "development__v",
            "instance_status": "live__v",
            "build_number": 1,
            "highest_casebook_version": 1,
            "sequence": 1,
            "vault_id": 114107,
            "vault_name": "My Development Vault"
        }  
    ]
}

Notes

The action is for creating a new Study master.
A Study master generally encompasses all ‘instances’ of the Study (DEV1, TST1, TST2, prod instance, etc).
However, the endpoint only creates a DEV1 Study (same Vault). TST and/or Production instances must be configured or created via the Tools -> EDC Tools UI.
The action cannot be performed in any Vault other than the development / control center

Endpoint

POST https://my-vault.veevavault.com/api/v24.1/app/cdm/design/actions/create_study

Required Permissions

The following permissions are required to use the Create Study Master API:

API Access
API Read/Write access + Edit on Study Design and/or View Library

Headers

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

Body Parameters

Name	Description
`study_master_name`	Name of the new Study
`organization_name`	Name of the Organization the new Study should be classified under, in the Vault.
`external_id`	Optional If omitted, the Study master name value is used (usually the same value)
`library`	Optional Default is false, if not provided. Whether this new Study should be classified as a library Study (or not)

Best Practices

Error Detection

Inner vs. Outer Response - Create Subject (1)

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Study Country] with name [Belgium] not found"
            "study_country": "Belgium"
            "site": "103",
            "subject": "103-001"            
        }
    ]
}

Inner vs. Outer Response - Create Event Groups (2)

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States", 
            "site": "101",
            "subject": "101-001",
            "eventgroup_name": "egIRT_INFO",
            "eventgroup_sequence": 1
        },
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Subject] with name [101-021] not found"
            "study_country": "United States",
            "site": "101",
            "subject": "101-021",
            "eventgroup_name": "egIRT_INFO"
        }
    ]
}

Strategy

If creating an integration into Vault CDMS, what is your error detection overall strategy?

Do you examine each response for success before moving on to a sequential / next call?
What sort of alerting / process kicks off when there is an error?
How do you avoid things falling through the cracks? (data out of synch with the EDC system)
What about the mistake / update scenarios in the source system? What happens when your source data changes, mistake or otherwise, how do you push the data in, where an update might have a different course of action from the initial add?

Inner vs Outer Response Status

Watch the inner vs. outer success/fail statuses in API responses!

The Vault API is designed such that most API endpoints allow multiple actions of that type in the same request.
As such, the status of each entry in the request is embedded at the inner level, responseStatus.
The outer responseStatus is largely an indication that 'yes, you reached the server, and it attempted an action (or actions)'.
The examples to the right include:
- Attempt to Create Subjects (Casebooks) - one - that fails
- Attempt to Create Event Groups - two - where one succeeds, one fails

Study Design

Forms for Integration

For an inbound integration to Vault CDMS:

If possible, avoid Form designs that involve both user entered data and integrated data. Users will open the Form when the integration does not expect such, among many other timing related potential issues.
If the data is semi-consistent from the upstream system from Vault CDMS, consider:
- A template of Forms, 100% read only in their own dedicated Event Group.
- The approach can make use of Copy Event Group function in Studio to port the consistent Form designs to new Studies.
- Using cross Form derived rules, the read only remote system data can be pulled/copied or referenced in the main Study design.

Repeating Events

A repeating visit in Vault CDMS increments the eventgroup_sequence values (1, 2, .. etc).
Although there is an Event sequence property on Event level, current system design yields that as a 1, always.
Instead, the Event Group is used for both single repeating Events (e.g. Unscheduled), or series of Events (e.g. Day 1, Day 8, Day 15.. but by Cycle)

API Account for Integrations

Security Policy

The suggested approach for the API account performing an integration is one where the Vault Security Policy has No Password Expiration checked.
In this way, a recurring integration is not at risk of having an expired password upend the important push or pull of information.

Study Access and Training

An API user is no different from any other Study user.
Typically, users must go through / pass training before their Study access is truly enabled.
For an API / system user, ensure to check the Ignore LMS Status, Assume Trained attribute on the account (typically). Otherwise the API user won’t find the Study (or Studies) intended.
The action is not necessary if the specific Vault is not activated to required LMS training before Study access is granted. (e.g. test / sandbox Vaults)

Sequences

The various design levels of a Study - Event Group, Form, Item Group - can repeat, or not repeat.
When they do not repeat the Create / Upsert endpoints do not require the specific indication of, say: "eventgroup_sequence": 1 in the request body.
That said, consider always including these regardless, as it makes for a more consistent request/response match

Inspecting Before Doing

Strive to inspect the existing Forms / Events before attempting an action to push data into the Study.
Does the Subject even exist?
Does the target area of data (Form, Event Group, etc) exist?
If a Form is submitted, it must first be opened for edit via the Edit Submitted Forms endpoint before proceeding with the update of data using endpoints like Set Form Data or Upsert Form Data.
TIP: The Combination Update Form Data endpoint is the most efficient approach (details below)

Create vs Upsert

Various API endpoints started as only create actions (POST), where the intended location must *not exist for the action to be successful. (Exception: Set Form Data used for updating existing)
Later releases included PUT action, which does no action when the location already exists (e.g. repeating Event Group, Form, or Item Group)
The upsert option is a better option, since specific sequences can be indicated at the various design levels, with the result being either an add (if does not exist) or a skipped action.
Update ‘2nd time in’ scenarios benefit from this approach.

Combination API for Form Data

The CDMS API's first release was #19R3*
As releases progressed for the CDMS API, endpoints were largely one to one with an action by an end user, and are used in a specific sequence. Examples:
- Create Subjects (Casebooks)
- Create Event Groups
- Set Event Date
- Create Forms (when repeating)
- Set Form Data
- Submit Form
The sequence described above is common for an IxR vendor pushing data into CDMS. But, it is a distinct API call to be made, each of the steps
At API version 23R1, the Combination Update Form Data was introduced to allow for 'many in one' ability when updating Form data. Although it will not create Subjects, it will perform all of these in one request:
- Create Forms (when repeating and not present)
- Edit Submitted Forms (when the Form is currently in submitted state)
- Create Itemgroups (when repeating and are not present yet)
- Set Form Data
- Submit Form

Locked / Frozen Forms

Frozen and Locked are not automatable through the API, by design. These were/are human decisions to stop actions from happening.
Depending on the data location, Locked and Frozen statuses differ in ability to push data into Vault CDMS:

Area	Status	Add/Update Data	Add/Update Queries
Study	Locked	Disallowed	Disallowed
Site	Locked	Disallowed	Disallowed
Subject	Locked	Disallowed	Disallowed
Subject	Frozen	Disallowed	Allowed
Event	Locked	Disallowed	Disallowed
Event	Frozen	Disallowed (event date changes)	Allowed (on event date)
Form	Locked	Disallowed	Disallowed
Form	Frozen	Disallowed	Allowed

Change Reasons

For the update of a Form data, a change_reason is only used when there is an update/change to existing values, after there has been at least one submit of the Form.
Change reasons can be included for the initial set of data, but they are ignored, instead the default 'changes before submission' is used.
That said, it is easier to send a change_reason with all Form updates. In this way you don’t have to track necessarily that it's the 1st or later touch of the Form data.
Actions that require a change_reason will default to a system reason, if not provided. Providing one is preferred to better identify the action in the remote system.

Jobs

The Vault CDMS job types that allow for starting, inspecting, and retrieving output follow the Vault platform job flow. That is, a job of Completed status might still potentially have issues (no output file available).
Depending on the job type (Job Summary / Types), a more detailed log style information is usually included in the output.
Both the Vault job log and the content of the job’s output should be inspected.

User Administration

For updating of users with a CDMS Vault, ensure the proper usage depending on the need:
- For deactivation of an account at the Vault level, this will remove the user from any Studies they otherwise would have had access to, in that Vault.
- For full deactivation of an account, this will remove the user from all* Vaults (thus all Studies in those Vaults) on that domain. Later reactivation of an account in such a state is then a two-step process. (update of domain status, then update of Vault memberships)
- For Study access deactivation, use the upload users endpoint (CSV or JSON), with a line indicating Study Status = Disabled, to remove access to a single Study.
- Specific site / country access does not need to be removed when disabling Study access, as later a re-activation in the Study might happen, returning the user to the state they were at deactivation in the Study.
For (CSV or JSON):
- The structure of user information is the same as performing in the Vault CDMS Users UI.
- The template can change from release to release as new properties are introduced.
- If some of the new properties are required, this could upend existing built integrations.
- The API version does NOT refer back and use older templates.
- Consult the CDMS Help and experiment in pre release Vaults on coming releases when writing user administration integrations.
IMPORTANT - review the Types of Users sub-section above from the Retrieve Users.

Getting Started

Run in Postman™

CDMS Overview

Data Organization

Study Design and Operations

CDMS API Overview

Structuring the Endpoint

API Access

Read vs. Write Access

Insufficient Access

Login / Sessions

Session Duration

Best Practices

Pagination

Rate Limits

How Does Vault Calculate Limits?

APU Rate Limit Headers

Authentication Rate Limit Headers

Client ID

Errors - General

Errors - CDMS

Authentication

User Name & Password

Endpoint

Headers

URI Path Parameters

Body Parameters

Response Details

Basic Authorization

Bearer Token Authorization

OAuth 2.0 / OpenID Connect

Endpoint

Headers

URI Path Parameters

Body Parameters

Authentication Type Discovery

Endpoint

Headers

Query String Parameters

Response Details

Studies

Retrieve Studies

Notes

Endpoint

Required Permissions

Headers

Response Details

Study Countries

Retrieve Study Countries

Notes

Endpoint

Required Permissions

Headers

Query Parameters

Response Details

Sites

Retrieve Sites

Notes

Endpoint

Required Permissions

Headers

Query String Parameters

Response Details

Subjects / Casebooks

Retrieve Subjects

Notes

Endpoint

Required Permissions

Headers

Query String Parameters (by Study Context)

Query String Parameters (by ID)

Response Details

Create Subjects (Casebooks)

Notes

Endpoint

Required Permissions

Headers

Body Parameters

Set Subject Status

Notes