Getting Started

CDMS API Guide

The CDMS API Guide is a bookmarked PDF containing extended information, best practices, and several examples per endpoint. Error scenarios are also illustrated.

Run in Postman™

Starting with v21.1, a Postman™ collection is available for each GA (General Availability) release of the CDMS REST API.

Note that this collection represents the point in time when the API became GA, and will not receive additional updates. For the most up-to-date documentation, reference the REST API reference and the CDMS API Guide (PDF).

You can use this collection locally in the Postman™ application (download in the Run in Postman dialog or from the Postman™ website) or in a Postman™ for Web workspace, if you have one set up.

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 similarly to the screenshot below, with folders and example API requests within the folders. These folders use the same section names and orders as this developer reference.

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
Username: jsmith@verteopharma.com
Vault Version: 22.1

Once you've set up your environment variables, make use of them throughout.

CDMS Structure Overview

Vault CDMS is organized by Study. A single vault typically contains many Studies.
There is usually a production domain with production vaults (for production studies), and a sandbox domain with Sandbox, Development, UAT, Training, etc. vaults.
Study design work will originate in a study of the Development vault and then deploy to UAT studies (of a UAT vault), and eventually a Production vault.
Within each Study, there are Study Countries that contain Sites, who in turn contain the Subjects of the Study. (at those Sites)
Each Subject (also known as Casebook), contains collected data about that Subject.
The components of data follow a model similar to ODM CDISC model - Visits/Forms/Item Groups/Items -, where ‘Event’ = ‘Visit’. There is an additional layer for Event Groups to cover repeating cycles of events/visits as one unit.
Site users enter collected data into Forms (eCRFs). Each Form contains Items, and can repeat form wise, where appropriate.
Items on a Form are question/fields, each an individual data point. Items are grouped into Item Groups, who can repeat, where appropriate, inside a single Form.
Depending on your study design, repeating Event Groups might be used. Repeating Event Groups allow you to add an Event Group to a Casebook multiple times. Each time you add that Event Group, it contains the same collection of Events and Forms as the previous. Each new Event Group may have a customized label, and often incremented labels, such as Visit 1, Visit 2, Visit 3,... etc. You can use the Create Event Groups / Upsert Event Groups API(s) to add a new instance of a repeating Event Group.
Common forms (also known as "Logs") are a special type of repeating Form that aren't associated within a specific event/visit, such as an Adverse Events or Concomitant Medications.
Study design can involve dynamic Rules, who will add appropriate Event Groups, Events and/or Forms, on the submit of forms who contain specific conditions. The API can also add new Event Groups, Events, Forms, perhaps exclusively, or it can also simply submit existing Forms to kick off the dynamic rules.

CDMS API Overview

The CDMS API is part of / 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 2021 is 21R1. The API version which coincides with this release is API v21.1. The third Vault General Release of 2021 is 21R3, which coincides with REST API v21.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, abilities of existing APIs - in the new release of the API - 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.

Endpoint Example Syntax

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

{vaultDNS} : the domain name of your vault. You can find this by logging into your vault via the UI. As example, on logging in, suppose the URL is https://my-vault.veevavault.com/ui/.... Given that, the {vaultDNS} value is my-vault.veevavault.com. If you have access to multiple vaults on a single domain, the user account used will be the same, login endpoint 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 v22.1. Remember that 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 Upsert 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/v22.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 (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 this list tells you which vault you’ve authenticated against. Rarely, you can authenticate against the wrong vault if the intended vault is inactive. In this situation, you’ll authenticate against the last vault you accessed or the oldest vault in your domain. Check the `vaultId` against the information in the list to ensure that it’s the vault you intended, as you begin other requests.

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/v22.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/v22.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": [
        :
        :   
    ]
}

Starting with the 22R1 release, several CDMS data retrieval APIs support pagination of results.

In the current release, pagination is supported for the following APIs:

Retrieve Subjects
Retrieve Queries
Retrieve Coding Queries
Retrieve Users

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

API Rate Limits

API rate limits are a common way to guarantee a high-quality service by preventing servers from becoming overloaded and the web service itself from becoming unusable. Web services are a fundamental resource to any 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)
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 API Rate Limit Headers

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

X-VaultAPI-BurstLimitRemaining: Indicates the number of API calls remaining for the current 1-minute burst window. For example, 19.
X-VaultAPI-BurstLimit: Indicates the maximum number of calls allowed in a 1-minute burst window. For example, 20.
X-VaultAPI-ResponseDelay: Indicates the length of delay for a throttled response in milliseconds. For example, 2000.

Developing with Rate Limits

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

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/Vault-level Errors

Example: Failed Authentication

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

Example: Down for Maintenance

{
    "responseStatus": "FAILURE",
    "responseMessage": "Authentication failed for user [chunter@verteopharma.com]",
    "errors": [
        {
            "type": "DOWN_FOR_MAINTENANCE",
            "message": "Vault is currently down for maintenance"
        }
    ],
    "errorType": "AUTHENTICATION_FAILED"
}

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

CDMS-Specific Errors

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 calls 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, such as an inner responseStatus. 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 occurred. More important, inner statuses (depending upon the endpoint's response format) usually indicate the true outcomes of the attempted actions. 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 are 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.
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/v22.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.

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.
`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.1 and run your integrations with v22.2.

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.

Basic Authorization

Name	Description
`Authorization`	{`sessionId`}

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

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

Bearer Token Authorization

Name	Description
`Authorization`	Bearer {`sessionId`}

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 object (study__v) to group together the study data. Examples include Study Countries, Sites, Subjects (also known as Casebooks), Queries, Medical Coding Requests, Study Jobs, and Form data,

Retrieve Studies

Request

$ curl -X GET \
-H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
https://my-vault.veevavault.com/api/v22.1/app/cdm/studies

Response

{
    "responseStatus": "SUCCESS",
    "studies": [
        {
            "study_name": "CHOLECAP_DEV",
            "external_id": "CHOLECAP",
            "study_phase": "Phase I",
            "study_status": "Execution"
        },
        {
            "study_name": "DEETOZA_DEV1",
            "external_id": "DEETOZA",
            "study_phase": "Phase I",
            "study_status": "Planning"
        },
        {
            "study_name": "ABCP-2022-01_DEV1",
            "external_id": "ABCP-2022-01",
            "study_phase": "Phase I",
            "study_status": "Execution"
        },
        {
            "study_name": "CHOLECAP_UAT1",
            "external_id": "CHOLECAP",
            "study_phase": "Phase I",
            "study_status": "Planning"
        }
    ]
}

Retrieve a list of all Studies in your vault. The response returns Studies to which the logged in user has access to, even if more Studies exist.

Vault returns a maximum of 200 Studies per response. You can lower this number using the limit query parameter. A coming release will convert API to use Pagination.

Endpoint

GET https://my-vault.veevavault.com/api/v22.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`

Response Details

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

Name	Description
`name`	Name of the Study. Although very rare, this may differ from the study label seen on screen. ).
`external_id`	External ID field value from the Study record (`study__v.oid__v`)
`study_status`	Study Status field label from the Study record (`study__v.study_status__v`)
`study_phase`	Study Phase field label from the Study record (`study__v.study_phase__v`)

Sites

A Site in Vault CDMS represents a single clinical research site. 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 - Two sites exist at a specific country

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

Response

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

Request - No sites in study yet

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

Response

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

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

Vault returns a maximum of 200 Sites per response. You can lower this number using the limit query parameter. A coming release will convert API to use Pagination.

Endpoint

GET https://my-vault.veevavault.com/api/v22.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.

Response Details

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

Name	Array	Description
`site`	`sites`	Site Number of the Site e.g. 101, 102, 201, or however the study defines Site numbering
`site_name`	`sites`	Name of the Site
`site_status`	`sites`	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)
`site_closeout_status`	`sites`	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.
`study_country`	`sites`	Name of the Study Country of the Site
`principal_investigator`	`sites`	The Principal Investigator assigned to the Site
`casebook_version`	`sites`	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
`timezone`	`sites`	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 subject 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

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

Response

{
   "responseStatus": "SUCCESS",
   "responseDetails": {
       "limit": 1000,
       "offset": 0,
       "size": 6,
       "total": 6
   },
   "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"
       },
       {
           "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"
       },
       {
           "id": "OPP00000000A001",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "102",
           "subject": "102-001",
           "status": "in_screening__v",
           "created_date": "2020-09-21T23:12:55Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2020-09-21T23:13:42Z"
       },
       {
           "id": "OPP000000009002",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "101",
           "subject": "101-003",
           "status": "in_screening__v",
           "created_date": "2020-09-21T23:08:00Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2020-09-21T23:12:44Z"
       },
       {
           "id": "OPP000000009001",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "101",
           "subject": "101-002",
           "status": "in_screening__v",
           "created_date": "2020-09-21T23:07:07Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2020-09-21T23:07:50Z"
       },
       {
           "id": "OPP000000000501",
           "study_name": "ABCP-2022-01_DEV1",
           "study_country": "United States",
           "site": "101",
           "subject": "101-001",
           "status": "enrolled__v",
           "created_date": "2020-02-12T18:51:53Z",
           "created_by": "Cordelia Hunter",
           "last_modified_date": "2020-03-11T20:23:56Z"
       }
   ]
}

Retrieve a list of Subjects within a given Study. For each Subject, Vault returns properties about the Subject, including the Study Country, Site, current Status, created datetime, and more. If your study design sets subject status milestone dates, or if you set those dates via the API, Vault also returns those dates.

Endpoint

GET https://my-vault.veevavault.com/api/v22.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

Name	Description
`study_name`	Name of the Study
`study_country`	Optional Name of the Study Country to filter on
`site`	Optional Name of the Site to filter on
`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.

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 thru 99 (zero based). Then, `offset` of 100 would return records 100 thru 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.

Name	Array	Description
`study_name`	`subjects`	Name of the Study
`site`	`subjects`	Name of the Site assigned to the Subject
`study_country`	`subjects`	Name of the Study Country assigned to the Subject
`subject`	`subjects`	Subject ID (Name) of the Subject
`id`	`subjects`	Vault internal ID for the subject (willl never change, whereas Subject name might)
`status`	`subjects`	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`
`created_date`	`subjects`	The datetime that the Subject was first created
`created_by`	`subjects`	Name (Firstname Lastname) of the User who created the Subject
`initial_consent_date`*	`subjects`	Initial Consent Date for the Subject
`screened_date`*	`subjects`	Screened Date for the Subject
`screen_failed_date`*	`subjects`	Screen Failed Date for the Subject
`enrolled_date`*	`subjects`	Enrolled Date for the Subject
`randomized_date`*	`subjects`	Randomized Date for the Subject
`start_treatment_date`*	`subjects`	Start Treatment Date for the Subject
`end_treatment_date`*	`subjects`	End Treatment Date for the Subject
`withdrawn_date`*	`subjects`	Withdrawn Date for the Subject
`started_follow_up_date`*	`subjects`	Started Follow Up Date for the Subject
`lost_to_follow_up_date`*	`subjects`	Lost to Follow Up Date for the Subject
`end_study_date`*	`subjects`	End Study Date for the Subject
`last_modified_date`	`subjects`	The datetime that the Subject was last updated

These values can be null. If the value is null, Vault does not include this field in the response. Values are set either through the study design rules, or via the API using Set Subject Status

Create Subjects (Casebooks)

Example - Two subjects created at once

curl -X POST  https://my-vault.veevavault.com/api/v22.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

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

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

curl -X POST  https://my-vault.veevavault.com/api/v22.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

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States"
            "site": "101",
            "subject": "101-001"
        },
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Study Country] with name [Belgium] not found"
            "study_country": "United States"
            "site": "103",
            "subject": "103-001"            
        }
    ]
}

Create a new Subject (also known as Casebook). As part of this action, Vault also creates the first Event Group for the subject and the first Event (visit) within that group. This does not set any event dates. To set the Event Date, you must use Set Event Date. Learn more about Casebooks in Vault CDMS Help.

Endpoint

POST https://my-vault.veevavault.com/api/v22.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
`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).

Set Subject Status

Request

curl -L -X POST 'https://my-vault.veevavault.com/api/v22.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"
        }
    ]
}

Set the Subject Status for a Subject and set a milestone date for that status. The milestone dates are found in Retrieve Subjects.

A Subject moves through the different statuses with an order of precedence:

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`

Notes

A subject does not have to go through each subject status. Study design requirements dictate which statuses a subject transitions through.
The Subject Status History object (subject_status_history__v) records the sequence of statuses as they are set.
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 lowers status if that status is the previous one (most recent record in the Subject Status History). Otherwise, the request fails.
You can override order of precedence by setting up statuses and orders in the Subject Status Definition object (subject_status_definition__v) for your Study.
You can undo any changes made with this API using Unset Subject Status.

Endpoint

POST https://my-vault.veevavault.com/api/v22.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
`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/v22.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"
        }
    ]
}

You can use Unset Subject Status to clear a Status from a Subject. The action will also clear the milestone date of that status. See the list above for a list of statuses and their date fields. The Subject will remain in the highest possible status. If you use this endpoint to remove the subject's current status, Vault moves the Subject into the last held status.

Endpoint

POST https://my-vault.veevavault.com/api/v22.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
`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.

Event Groups

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

Create Event Groups

Request - Scheduled Event Group

curl -X POST https://my-vault.veevavault.com/api/v22.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

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

Request - Unscheduled Event Group (requires a date)

curl -X POST https://my-vault.veevavault.com/api/v22.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

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

Create an Event Group. An Event Group is a container for multiple Events, or visits, in a subject's casebook. This endpoint is the equal of the New Event button in the CDMS UI. Some study design rules might also add Event Groups (via normal study data entry)

Common Use Cases

Add of an area for integration data, that only the integration should add (not an end user).
Unscheduled Event (requires a date on add)
The Study may be using Cycles, by way of repeating Event Groups, allowing the add to a Casebook multiple times. 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 - often incremented labels, such as Cycle 1, Cycle 2, Cycle 3, etc.

To create new Event Groups at a specific sequence, use Upsert Event Groups. The upsert version of this endpoint (PUT) will either add the event group where it does not yet exist or skip the action. The create version (POST) will always attempt to add the next (new) in sequence.

Endpoint

POST https://my-vault.veevavault.com/api/v22.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
`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/v22.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

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

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

curl -X PUT https://my-vault.veevavault.com/api/v22.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

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
      {
          "responseStatus": "SUCCESS:UPDATED",
          "study_country": "United States",
          "site": "101",          
          "subject": "101-001",
          "eventgroup_name": "unscheduled_treatment_visits",
          "eventgroup_sequence": 2
      },
      {
          "responseStatus": "SUCCESS:CREATED",
          "study_country": "United States",
          "site": "101",          
          "subject": "101-001",
          "eventgroup_name": "unscheduled_treatment_visits",
          "eventgroup_sequence": 3
      }      
   ]
}

Create new Event Groups by specifying a specific Event Group Sequence. If there is an existing Event Group at that sequence, no action is taken. If there isn't a matching Event Group at the sequence, Vault creates a new Event Group.

For the upsert / PUT on this endpoint, when the Event Group at the specific eventgroup_sequence already exists, no action is taken, despite the SUCCESS:UPDATED returned (verbiage subject to change in a future release). For an unscheduled Event Group, the action with an updated date will not change the date of that Event in the Event Group. Use the **Set Event Date**](#set-event-date) endpoint to change an _Event_ date.

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
`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 - One Subject

curl -L -X GET 'https://my-vault.veevavault.com/api/v22.1/app/cdm/events?study_name=Veepharm&study_country=United%20States&site=101&subject=101-001' \
-H 'Authorization: {SESSION_ID}'

Response

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

Retrieve a list of Events, 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.

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

Response Details

On SUCCESS, Vault returns a list of Events within a Subject with the following information:

Array	Name	Description
`events`	`study_country`	Name of the Study Country for the site of the Subject
`events`	`site`	Name of the Site for the Subject
`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 repeating Event Group the value increments starting at 1, 2.... If it does not repeat, then 1 is always returned
`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/forms`	`form_name`	Study design name for a Form in the Event (entry per form)
`events/forms`	`form_sequence`	If the Form repeats per study design, these increment starting at 1, 2.... If it does repeat, 1 is always returned.
`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`	`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`	Only when `intentionally_left_blank` is true, the reason for such. If the form is not ILB, then null is returned.

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

{
    "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/v22.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

{
    "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
        }
    ]
}

Create a new Event (visit) within an existing Event Group. The action does not also create/upsert an Event Group. The common use case for this endpoint is the need to add the Event via integration only (not by the end user). If the desired Event is the first of an Event Group, then Create Event Groups / Upsert Event Groups for that Event Group already creates the Event.

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
`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/v22.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

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

Request - Change one event date

curl -X POST https://my-vault.veevavault.com/api/v22.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"
          }
      ]
    }'

Response

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

Set the event date of an Event. Vault CDMS conventions 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.

Endpoint

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

Required Permissions

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

API Access
View Casebook
Data Entry

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
`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 (required when changing the date) The reason for change of an event's date, where there is already a value. For example, "Date updated by remote system".
`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.

Set Event as Did Not Occur

Request - Set two events as did not occur

curl -X POST https://my-vault.veevavault.com/api/v22.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

{
    "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
    }
    ]
}

Mark an Event as Did Not Occur. The Did Not Occur event attribute indicates that data was not collected for this Event, and thus no forms/data under it. Example: subject missed the visit, subject discontinued from the study, etc. A reason for this action is required.

Endpoint

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

Required Permissions

The following permissions are required to use the Set Event as Did Not Occur 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
`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`	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 represent the case report forms of a Subject. These can repeat per study design. 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/v22.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",
    "forms": [
        {
            "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": "demographics",
            "form_sequence": 1,
            "form_status": "submitted__v",
            "locked": false,
            "frozen": false,
            "intentionally_left_blank": false,
            "intentionally_left_blank_reason": null,
            "itemgroups": [
                {
                    "itemgroup_name": "creation_criteria",
                    "itemgroup_sequence": 1,
                    "itemgroup_externalid": "creation_criteria"
                    "items": [
                        {
                            "item_name": "subject_date_of_birth",
                            "value": "17-Jun-1978",
                            "unit_value": null
                        },
                        {
                            "item_name": "subject_gender",
                            "value": "F",
                            "unit_value": null
                        },
                        {
                            "item_name": "subject_initials",
                            "value": "QGT",
                            "unit_value": null
                        },
                        {
                            "item_name": "subject_race",
                            "value": "Caucasian",
                            "unit_value": null
                        }
                    ]
                }
            ]
        },
        {
            "study_country": "United States",
            "site": "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,
            "intentionally_left_blank": false,
            "intentionally_left_blank_reason": null,
            "itemgroups": [
                {
                    "itemgroup_name": "exclusion_criteria",
                    "itemgroup_sequence": 1,
                    "itemgroup_externalid": "exclusion_criteria",
                    "items": [
                        {
                            "item_name": "exclusion_hypersensitivity_constituents",
                            "value": "N",
                            "unit_value": null
                        },
                        {
                            "item_name": "exclusion_study_calendar",
                            "value": "N",
                            "unit_value": null
                        },
                        {
                            "item_name": "exclusion_pregnant_or_nursing",
                            "value": "N",
                            "unit_value": null
                        },
                        {
                            "item_name": "exclusion_chronic_medical_condition",
                            "value": "N",
                            "unit_value": null
                        }
                    ]
                }
            ]
        },
        {
            "study_country": "United States",
            "site": "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,
            "intentionally_left_blank": false,
            "intentionally_left_blank_reason": null,
            "itemgroups": [
                {
                    "itemgroup_name": "inclusion_criteria",
                    "itemgroup_sequence": 1,
                    "itemgroup_externalid": "inclusion_criteria",
                    "items": [
                        {
                            "item_name": "inclusion_negative_pregnancy_test",
                            "value": "Y",
                            "unit_value": null
                        },
                        {
                            "item_name": "inclusion_normal_healthy",
                            "value": "Y",
                            "unit_value": null
                        },
                        {
                            "item_name": "inclusion_age_18",
                            "value": "Y",
                            "unit_value": null
                        },
                        {
                            "item_name": "inclusion_informed_consent",
                            "value": "Y",
                            "unit_value": null
                        }
                    ]
                }
            ]
        }
    ]
}

Retrieve a list of Forms, with all contained data (Item Groups / Items) for a specific Subject / Event. This endpoint can return no wider than that level (one Subject / one Event), and is typically used for specific inspection of a Form (data on it), prior to updating that form's data. For retrieval of more than one Event (or many Subjects), see the various export options at the Job Summary / Types section.

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

Response Details

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

Array	Name	Description
`forms`	`study_country`	Name of the Study Country for the site of the Subject
`forms`	`site`	Name of the Site for the Subject
`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`	`intentionally_left_blank`	Whether the form has been marked intentionally left blank (ILB) by a site user. (true/false)
`forms`	`intentionally_left_blank_reason`	Only when `intentionally_left_blank` is true, the reason for such. If the form is not ILB, then null is returned.
`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`	`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. When not a unit codelist list, null is returned. In a future release, when the Item is not a unit codelist, it will be omitted the response, and when it is a unit codelist, the translated value / unit will be returned in the response.

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 once 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, i.e., 'UNK' for three character month portion (The study date format is returned for the date portion, not ISO)
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
Unit Codelist	Set with value and unit	"value": "0.45" "unit_value": "tenth_unit"
Unit Codelist	(value set, then later unset)	"value": null "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

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

{
    "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

{
    "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
        }
    ]
}

Create a new instance of a Form. This is most used to add a new repeating form, and is the equivalent of clicking Add in the EDC UI at that Form location. That is, the next in sequence will/would be added. To create specific instances of Forms by sequence, use Upsert Forms, where either the form is added (when not present) or the action is skipped (when is present).

Another use case for create Form is non repeating Form where only the integration should be adding the form. That is, there is no study design Rule that otherwise would add the Form within an existing Event (normal data entry) The Event Group and Event where the Form resides in the schedule must exist first to perform.

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

{
    "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

{
    "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
        }
    ]
}

Create a new instance of a repeating Form, at a specific sequence. The upsert version of this endpoint (PUT) will either add the form where it does not yet exist or skip the action. The create version (POST) will always attempt to add the next (new) in sequence. Learn more about repeating forms in Vault CDMS Help.

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

{
    "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

{
    "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
        }
    ]
}

Create a new instance of a repeating Item Group. An Item Group is a section of a single Form who can repeat. For non-repeating Item Groups they are available when the parent Form exists, plus first attempt to set data into any Item of the Item Group via API or end user UI. The action is the equivalent of clicking Add Section (on a Form) in the EDC UI. That is, the next in sequence will/would be added. To create specific instances of Item Groups by sequence number, use Upsert Item Groups, where either the Item Group is added (when not present) or the action is skipped (when is present).

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
`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/v22.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

{
    "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/v22.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 (only 1 reported, even though 2 were added)

{
    "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
        }
    ]
}

Upsert instances of a repeating Item Group. If you specify an itemgroup_sequence (Sequence Number for the Item Group instance) that does not exist, the API automatically creates the instance for you, otherwise the action is skipped.

Sequence Gaps: For this endpoint if the request has a sequence that would otherwise leave gaps, the Item Groups are created up to the sequence requested. For example - if the target Form currently has one Item Group, and the request uses "itemgroup_sequence": 3, two are added. That is, sequence 2 and 3 are added by virtue of just requesting #3.

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
`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/v22.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

{
    "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"
        },
        {
            "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"
        },
        {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         }
    ]
}

Original primary endpoint for updating data on a form. To update data on a form, one should steer towards Upsert Form Data, which better assists with any repeating Item Groups involved in the Form design.

Notes:

The endpoint does not create/upsert a form that does not yet exist, nor open a form for edit (if currently submitted). A future release will wrap those up with this endpoint as a single combination endpoint.
The value portion of updating Items depends on the Item type. See the table in Upsert Form Data section notes on Item types and appropriate values using the API.
Before the first submit of the form, all Item changes are tagged with a default reason for change. The API can lace its request with a specific change_reason, but it only takes affect when the Form has been re-opened from an initial submitted status.
Set Form Data (POST) requires that repeating Item Group instances must exist first before attempting this endpoint. (see Upsert Item Groups). For this reason, it is recommended that you instead use the Upsert Form Data.

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
`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 (required when changing a value after first submit of the form) The reason for change of an Item value. For example: "Data updated by remote system"

Upsert Form Data (Items)

Request - Setting values for one of each type of item

curl -X PUT https://my-vault.veevavault.com/api/v22.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

{
    "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"
        },
        {
            "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"
        },
        {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         },
         {
            "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"
         }
    ]
}

This endpoint is like Set Form Data (previous section, POST), but a later release (as PUT).

Notes:

This endpoint will create any necessary Item Groups (repeating) that do not exist on the form, as part of its execution. The POST style (previous section) does not create them.
The endpoint does not create/upsert a form that does not yet exist, nor open a form for edit (if currently submitted). A future release will wrap those up with this endpoint as a single combination endpoint.
The value portion of updating Items depends on the Item type. See the table lower in this section for notes on Item types.
Before the first submit of the form, all Item changes are tagged with a default reason for change. The API can lace its request with a specific change_reason, but it only takes affect when the Form has been re-opened from an initial submitted status.

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"<br>"unit_value": "in"`	E.g., 'in' is a valid code in the unit codelist definition.
Unit Codelist	`"value": ""<br>"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
`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 (required when changing a value after first submit of the form) The reason for change of an Item value. For example: "Data updated by remote system"

Submit Forms

Request - Submit one form

curl -X POST https://my-vault.veevavault.com/api/v22.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

{
    "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"
        }
    ]
}

This endpoint will perform the equivalent of the on screen Complete button. All study design Rules (of that Form) will be run as part of the action.

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

{
    "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"
        }
    ]
}

This API will act on a currently submitted Form, making it editable. From there, one then uses Upsert Form Data to change data on the form. Learn more about editing Forms in Vault CDMS Help.

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
`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 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/v22.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"
                }
            ]
        }
    ]
}

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 thru 99 (zero based). Then, `offset` of 100 would return records 100 thru 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
`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/v22.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"
               }
           ]
       }
   ]
}

Retrieve details about a specific Queries by their IDs. Only the filter for last_modified_date applies when searching Queries by ID(s).

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. The `id` value can be found from Retrieve Queries. 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 thru 99 (zero based). Then, `offset` of 100 would return records 100 thru 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
`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/v22.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


{
    "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/v22.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


{
    "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"
                }
              ]
}

Open a Query on an Item or Event (located on the Event date) by providing study context to uniquely identify it (Study Country, Site, Subject, Event Group, Event, and so on).

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 Queries Query - a query added against a specific Medical Coding Request

On successful open of a Query the query id and query_name are returned. These are the same values you will find in subsequent calls to Retrieve Queries. Consider storing the internal ID of the new query, as later answer, close will be simpler to perform 'By ID'

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
`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/api/v22.1/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",
    "queries": [
                 {
                   "id": "V57000000005002",
                   "message": "We ran screening at this site on Saturday, July 31."
                 }
               ]
}'

Response

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

Open a Query on an Event (located on the Event date) by providing the Vault internal ID of the Event.

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
`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/api/v22.1/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",
    "queries": [
                 {
                   "id": "OPT000000004001",
                   "message": "This Item is out of range."
                 }
               ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000003001",
            "query_status": "open__v",
            "item_id": "OPT000000004001"
        }
    ]
}

Open a Query on an Item (residing on a Form) by providing the Vault internal ID of the Item.

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	Description
`study_name`	Name of the Study (`study__v.name__v`)
`queries`	For each Query that you want to open, include the following as an array: `id`: The ID (`id`) of the Item (`item__v`) that you want to open a query on. `message`: Enter the query message text.

Open Queries by Medical Coding Request

Open a Query on an Item who is tagged with a specific Medical Coding Request. The Vault internal ID of the request is provided as input to open the query on that Item (e.g AE verbatim, CM verbatim, etc.)

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

This method is documented in the Medical Coding later section: Open Coding Queries

Answer Queries

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

curl -X POST  https://my-vault.veevavault.com/api/v22.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

{
    "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/v22.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

{
    "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
        }
    ]
}

Answer a Query that is currently in the Open status, with a comment (required). This moves the query from the Open (open__v) status into the Answered (answered__v) status. A message is required.

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
`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/v22.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

{
    "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/v22.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

{
    "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
        }
    ]
}

Close a Query that is currently in the Answered status, with a comment (optional). This moves the query from the Answered (answered__v) status into the Closed (closed__v) status. A message is not required, although is good practice.

There are two ways to close 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/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
`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`	OptionalThe 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`	OptionalThe message at close of the Query

Reopen Queries

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

curl -X POST  https://my-vault.veevavault.com/api/v22.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

{
    "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/v22.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 (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
        }
    ]
}

Reopen a Query that is currently in the Closed status, with a comment (required). This moves the query from the Closed (closed__v) status into the Open (open__v) status.

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

Medical Coding

If your vault contains the Vault Coder application, and your Study is configured for coding, you can use these endpoints. A Medical Coding Request represents an Item that is being coded (1 to 1 with that Item), e.g Severe Headache on an AE Form. These requests are addedand 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/v22.1/app/cdm/coder/codingrequests?study_name=ABCP-2022-01_DEV1&coding_item_definition=VV-00123' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "codingrequests": [
        {
            "coding_item_definition": "V0T000000002001",
            "form_status": "Active",
            "form_type": "AE",
            "dictionary_definition": "MedDRA",
            "requests": [
                {
                    "id": "V0V000000003001",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "My Term 1",
                    "start_date": "",
                    "stop_date": "",
                    "event": "LOGS",
                    "event_sequence": 1,
                    "form": "Adverse-Event",
                    "form_sequence": 1,
                    "item_group": "ig-AE",
                    "item_group_sequence": 1,
                    "item": "AETERM",
                    "coding_status": "Open",
                    "last_coded_by_third_party": "",
                    "last_coded_date": "",
                    "assigned_to_third_party": "",
                    "last_modified_date": "2022-05-23T17:34:46Z",
                    "created_date": "2022-05-23T17:34:46Z",
                    "created_by": "System",                      
                    "severity": "",
                    "llt_code": "",
                    "llt": "",
                    "pt_code": "",
                    "pt": "",
                    "hlt_code": "",
                    "hlt": "",
                    "hlgt_code": "",
                    "hlgt": "",
                    "soc": "",
                    "soc_code": "",
                    "primary_path": ""
                },
                {
                    "id": "V0V000000003002",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "My AE 2",
                    "start_date": "2022-05-01T00:00:00Z",
                    "stop_date": "",
                    "event": "LOGS",
                    "event_sequence": 1,
                    "form": "Adverse-Event",
                    "form_sequence": 2,
                    "item_group": "ig-AE",
                    "item_group_sequence": 1,
                    "item": "AETERM",
                    "coding_status": "Coded",
                    "last_coded_by_third_party": "",
                    "last_coded_date": "2022-06-02T18:35:03Z",
                    "assigned_to_third_party": "",
                    "last_modified_date": "2022-06-02T18:35:03Z",
                    "created_date": "2022-05-23T17:35:27Z",
                    "created_by": "System",
                    "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/v22.1/app/cdm/coder/codingrequests?study_name=ABCP-2022-01_DEV1&coding_item_definition=VV-00125' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "codingrequests": [
        {
            "coding_item_definition": "V0T000000004001",
            "form_status": "Active",
            "form_type": "ConMed",
            "dictionary_definition": "WHODrug C3",
            "requests": [
                {
                    "id": "V0V000000004001",
                    "site": "101",
                    "subject": "SCR-0001",
                    "verbatim": "Aspirin",
                    "start_date": "",
                    "stop_date": "",
                    "event": "LOGS",
                    "event_sequence": 1,
                    "form": "Concomitant-Medication",
                    "form_sequence": 1,
                    "item_group": "ig-CM",
                    "item_group_sequence": 1,
                    "item": "CMTRT",
                    "coding_status": "Coded",
                    "last_coded_by_third_party": "",
                    "last_coded_date": "2022-06-02T20:02:26Z",
                    "assigned_to_third_party": "",
                    "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": "",
                    "event": "LOGS",
                    "event_sequence": 1,
                    "form": "Concomitant-Medication",
                    "form_sequence": 2,
                    "item_group": "ig-CM",
                    "item_group_sequence": 1,
                    "item": "CMTRT",
                    "coding_status": "Open",
                    "last_coded_by_third_party": "",
                    "last_coded_date": "",
                    "assigned_to_third_party": "",
                    "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": ""
                }
            ]
        }
    ]
}

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. Vault can retrieve up to 10,000 Medical Coding Requests. (Pagination available in a coming release)

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`	The specific medical coding definition of requests to return. Currently only one coding location/definition of the study can be returned at a time. This value is the name value (e.g. 'VV-0000...') of the coding definition in the study design. It currently can be found in Admin -> Business Admin -> Medical Coding Item Definitions only. (coming release, an API endpoint to retrieve this information will be available)
`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.
`last_modified_date`	Optional Retrieve only requests modified after this datetime. Use the format "yyyy-MM-ddTHH:mm:ssZ".

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`	Vault internal ID for the study definition of the coding Item (not name)
`codingrequests`	`form_status`	The status of the study definition of the coding at the Form (of the Item being coded). This is not the status of the coding request itself, instead just a status of the definition.
`codingrequests`	`form_type`	The coding definition type of form, e.g. 'AE'. This is the label currently, but will be the picklist name in a future release (e.g. `ae__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`	`site`	Name of the Site for the Subject (NOTE: study_country to also be returned in a future release)
`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`	`event_name`	Study design label for Event (WARNING: This will be the design name in a future release)
`codingrequests/requests`	`event_sequence`	Currently, always a 1. If the Event within a repeating Event Group the sequence increments at the `evengroup_sequence` level. NOTE: eventgroup information to be returned in a future release)
`codingrequests/requests`	`form_name`	Study design label for Form (WARNING: This will be the design name in a future release)
`codingrequests/requests`	`form_sequence`	The specific Form sequence
`codingrequests/requests`	`item_group_name`	Study design label for Item Group (WARNING: This will be the design name in a future release, also naming will be 'itemgroup')
`codingrequests/requests`	`item_group_sequence`	The specific Item Group sequence
`codingrequests/requests`	`item_name`	Study design label for Item (WARNING: This will be the design name in a future release, also naming will be 'itemgroup')
`codingrequests/requests`	`coding_status`	The current status of the coding request, e.g. 'Open', 'Coded', etc. (WARNING: This will be the status API value name in a future release, e.g. `open__v`, `coded__v`)
`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) (future release of CDMS will support 3rd party coding, with return into CDMS coding requests)
`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. (future release of CDMS will support 3rd party coding, with return into CDMS coding requests)
`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 (Firstname Lastname) 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/v22.1/app/cdm/queries?study_name=ABCP-2022-01_DEV1&coding_item_definition=V0R000000006001,V0R000000007001' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
                         "limit": 1000,
                         "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"
                }
            ]
        }
    ]
}

Retrieve a list of all queries associated with a given coding Form. You can also retrieve only queries in a certain Query Status.

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`	The specific medical coding definition (`id` value of the definition in the study) to filter to. That is, those queries added and tagged to a field that was medically coded in Vault CDMS Coder. Multiple coding definitions IDs can be used (comma-separated). It currently can be found in Admin -> Business Admin -> Medical Coding Item Definitions only. (coming release, an API endpoint to retrieve this information will be available) The add of a query, tagging a specific medical coding request (and thus its definition) is discussed in the section: Open Coding Queries
`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 thru 99 (zero based). Then, `offset` of 100 would return records 100 thru 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
`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/v22.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",                      
                }
    ]
}

Open a Query on an Item who is tagged with a specific Medical Coding Request. The Vault internal ID of the request is provided as input to open the query on that Item (e.g AE verbatim, CM verbatim, or other)

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

GET /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 and CDMS API Read Only roles grant 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

Jobs

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.

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.

Job Types

The following job types are currently supported:

Name	API Name	Description
Study Data Extract	`study_data_extract`	(SDE) 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 full export of study data, the most comprehensive. It can be run in subset for faster runtime (e.g., just Adverse Events)
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
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.
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.
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.
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	`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)

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/v22.1/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: 511E5C4ADBA98A18E5B48618F9CD7FDBE7E8451CCA2344EB62629FC9743C0AC4469A666DF1C28DF16D3290D4496B20A04B33055A4CE6A424C128CC731C04F4DD' \
-d '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "study_data_extract__v",
       "include_restricted_data": true,
       "version": "v22.1",
       "export_file_type": "CSV",
       "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

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "study_data_extract__v",
       "job_id": 522518,
       "created_by": "chunter@verteopharma.com",
       "created_date": "2021-10-18T18:18:54Z",
       "include_restricted_data": true,
       "version": "v22.1",
       "export_file_type": "CSV",
       "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
   }
}

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

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.

To include randomization treatment information in the job output, you must also have the View Unmasked Data 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 `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.
`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`, etc.
`export_file_type`	The type of export. Choices are only CSV (just CSVs) or SAS with XPT and CSV
`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 Must provided when `all_clinical_datasets` = false. JSON array of names of specific clinical datasets to include. The names are those of the Form study design names. 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 Must provided when `all_system_datasets` = false. JSON array of names of system datasets to include. Only those system datasets that are applicable for the study's design settings are valid. 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 provided 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" ]`

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`	Use Nname 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.
`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

Subject Progress Listing

Request - Start Subject Progress Listing

curl -L -X POST 'https://my-vault.veevavault.com/api/v22.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

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

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.

Event Progress Listing

Request - Start Event Progress Listing

curl -L -X POST 'https://my-vault.veevavault.com/api/v22.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
   }
}'

Response

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

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.

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.

Form Progress Listing

Request - Start Form Progress Listing

curl -L -X POST 'https://my-vault.veevavault.com/api/v22.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

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "form_progress_listing__v",
       "job_id": 525105,
       "created_by": "chunter@verteopharma.com",
       "created_date": "2021-10-22T00:14:29Z",
       "include_restricted_data": true,
       "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.

Query Detail Listing

Request - Start Query Detail Listing

curl -L -X POST 'https://my-vault.veevavault.com/api/v22.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

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

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.

Core Listings

Request - Start Core Listings

curl -L -X POST 'https://my-vault.veevavault.com/api/v22.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

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

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

Request - Start DDE

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

Response

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

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.

Cancel Job

Request

curl -L -X POST 'https://my-vault.veevavault.com/api/v22.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"
   }
}

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/v22.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@verteopharma.com",
                  "created_date": "2021-10-20T12:14:42Z",
                  "last_modified_date": "2021-10-20T12:20:42Z"
                }
}

You can retrieve the current status of a Study Job using its known Vault Job ID. These IDs are part of the response to start a job. A future release will include an endpoint to get the study jobs of a specific type, i.e., to get the Vault job ID(s) of each. For a workaround on this, download the extended guide here : CDMS API Guide

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/v22.1/app/cdm/jobs/525105/file/content' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \

You can retrieve the output file of a Study Job (typically a zip file) using its known Vault Job ID for up to thirty (30) days after a job is completed. These IDs are part of the response to start a job. A future release will include an endpoint to get the study jobs of a specific type, i.e., to get the Vault job ID(s) of each. For a workaround on this, download the extended guide here : CDMS API Guide

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/v22.1/app/cdm/jobs/525105/file/log' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

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

You can retrieve the log file of a Study Job (TXT file) using its known Vault Job ID for up to thirty (30) days after a job is completed. These IDs are part of the response to start a job. A future release will include an endpoint to get the study jobs of a specific type, i.e., to get the Vault job ID(s) of each. For a workaround on this, download the extended guide here : CDMS API Guide

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/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 the Study users the API user has rights into, plus the add/update of users at Study or Vault level.

Learn more about study user access in Vault CDMS Help.

Retrieve Users

Request

curl -L -X GET 'https://my-vault.veevavault.com/api/v22.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",
            "activation_date": "2023-09-22",
            "created_date": "2023-09-22T14:21:54Z",
            "last_modified_date": "2023-09-22T15:02:41Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "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",
            "activation_date": "2023-09-22",
            "created_date": "2023-09-22T14:21:54Z",
            "last_modified_date": "2023-09-22T15:02:41Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "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",
            "activation_date": "2022-06-28",
            "created_date": "2022-06-28T19:31:12Z",
            "last_modified_date": "2022-06-28T19:31:14Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": false,
            "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",
            "activation_date": "2023-09-22",
            "created_date": "2023-09-22T14:20:33Z",
            "last_modified_date": "2023-09-22T15:02:41Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": false,
            "all_studies_access": true,
            "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",
            "activation_date": "",
            "created_date": "2018-07-25T11:23:31Z",
            "last_modified_date": "2021-03-15T16:05:31Z",
            "principal_investigator": false,
            "active": true,
            "vault_owner": true,
            "all_studies_access": false
        },
        :
        :
        :
    ]
}

Retrieve a list of Users in a single Study, or of many studies. Also retrieve very specific users by username(s).

Types of Users

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 thru 99 (zero based). Then, `offset` of 100 would return records 100 thru 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 timezone
`users`	`security_policy`	The security policy name value, e.g. `Basic` or `Customer Network SSO`, etc.
`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`	`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/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 (Add/Update)

Request

curl -L -X PUT 'https://my-vault.veevavault.com/api/v22.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@verteopharma.com",
       "created_date": "2022-02-14T23:37:17Z"
   }
}

Information about the upload of Users via CSV via the UI also available here: Importing Users

General Notes

This endpoint is used to create or update users in a Study (or Studies)
Each row of the uploaded CSV is a user to create or make updates. This can be creation of both the Vault account and access into a specific Study (or Studies), or just the creation / 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 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 successful starts, the job ID is returned. Check the job status using:

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

... which is a general check on any Vault Job, by its ID. Once the job completes, consider using Retrieve Users to verify the state of each of the users created and/or updated.

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

Inactivate User

Request: Inactivate User in a Vault

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://my-vault.veevavault.com/api/v22.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/v22.1/objects/users/25001?domain=true

Response

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

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

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/v22.1/objects/users/25001

Response

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

General 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/v22.1/objects/users/25001/vault_membership/456789

Response

{
    "responseStatus": "SUCCESS"
}

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

Tutorial: Create Subject & Submit Data

In this short tutorial/walkthrough, we will create a new Subject in our example study, ABCP-2022-01_UAT3, enter data on the Demographics Form, and then submit the Form.

For additional examples and scenarios, refer to the extended CDMS API Guide:

This tutorial uses the following APIs:

Authentication: User Name & Password
Create Subject/Casebook
Set Subject Status
Set Event Date
Upsert Form Data
Submit Form

Authenticate

Authentication Request

$ curl -X POST https://my-vault.veevavault.com/api/v22.1/auth \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/xml" \
-d "username=joe.smith@eke.com&password=my_password_here_as_body_parameter"

Authentication Response

{
  "responseStatus": "SUCCESS",
  "sessionId": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 2596,
      "name": "Verteo Pharma - UAT",
      "url": "https://my-vault.veevavault.com/api"
    }
  ]
  "vaultId": 12345
}

First, we connect and obtain a session from the vault, in this case a UAT vault. (full detail: Authentication: User Name & Password)

Create Subject

Create Subject Request

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

Create Subject Response

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

Next, we create a Subject / Casebook. The Casebook contains all of the Events (visits) and forms for the subject throughout the study. Our Subject number was set in the upstream system, so we set it, 101-005, at Site 101. (full detail: Create Subject/Casebook)

Set Subject Status

Request - Set Subject Status / Milestone

curl -L -X POST 'https://my-vault.veevavault.com/api/v22.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-005",
            "subject_status": "in_screening__v",
            "date": "2022-07-01"
        }
    ]
}'

Response

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

Initial statuses in Vault CDMS are Pre Screen. We move the new Subject forward in status to In Screening, plus stamp a Screening milestone date. (full detail: Set Subject Status)

Set Event Date

Request - Set Event Date

curl -X POST https://my-vault.veevavault.com/api/v22.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-005",
          "eventgroup_name": "egSCR",
          "event_name": "evSCR",
          "date": "2022-07-01"
          }
      ]
    }'

Response

{
    "responseStatus": "SUCCESS",
    "events": [
        {
          "responseStatus": "SUCCESS",
          "study_country": "United States",
          "site": "101",          
          "subject": "101-005",
          "eventgroup_name": "egSCR",
          "eventgroup_sequence": 1,
          "event_name": "evSCR",
          "event_sequence": 1
        }
    ]
}

Next, we set the event date of the Screening Event which in turn will build out the Forms of that Event, one of which is the Demographics form (design name = DM). The location of our Demographics Form is in the Event Group with design name egSCR and Event with design name evSCR. (full detail: Set Event Date)

Upsert Form Data (Items)

Upsert Form Data (Items) Request

curl -X PUT https://my-vault.veevavault.com/api/v22.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": "101-001",
            "eventgroup_name": "egSCR",
            "event_name": "evSCR",
            "form_name": "DM",
            "items": [
                {
                    "itemgroup_name": "igDM",
                    "item_name": "TRT_ONSET",
                    "value": "1998-UN-UN"
                },
                {
                    "itemgroup_name": "igDM",
                    "item_name": "DOB",
                    "value": "1978-11-22"
                },
                {
                    "itemgroup_name": "igDM",
                    "item_name": "SEX",
                    "value": "MALE"
                }
            ]
        }
    ]
}'

Set Item Values Response

{
    "responseStatus": "SUCCESS",
    "items": [
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "DM",
            "form_sequence": 1,            
            "itemgroup_name": "igDM",
            "itemgroup_sequence": 1,
            "item_name": "TRT_ONSET"
        },
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "DM",
            "form_sequence": 1,            
            "itemgroup_name": "igDM",
            "itemgroup_sequence": 1,
            "item_name": "DOB"
        },
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "DM",
            "form_sequence": 1,            
            "itemgroup_name": "igDM",
            "itemgroup_sequence": 1,
            "item_name": "SEX"
        }
    ]
}

With the Form now present under the Screening Event, we can now set data onto the Demographics Form. Our Items to be updated are read only on the Form, and all reside in an Item Group of design name igDM:

Treatment Onset (design name = TRT_ONSET) = 1998, unknown month and day.
Date of Birth (design name = DOB) = Nov 22nd, 1978
Gender (design name = SEX) = MALE (the codelist code used in that Item)

The Form is inside a non-repeating Event Group the Form itself does not repeat, nor does the Item Group of the Items repeat, so we can omit those sequence parameters. (1 is assumed for each) (full detail: Upsert Form Data)

Submit Form

Submit Form Request

curl -X POST https://my-vault.veevavault.com/api/v22.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": "egSCR",
            "event_name": "evSCR",
            "form_name": "DM"
        }
    ]
}'

Submit Form Response

{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "DM",
            "form_sequence": 1
        }
    ]
}

Finally, with data set on the Demographics Form, we submit the Form. (full detail: Submit Form)

Getting Started

CDMS API Guide

Run in Postman™

CDMS Structure Overview

CDMS API Overview

Endpoint Example Syntax

API Access

Read vs. Write Access

Insufficient Access

API Login / Session ID

Pagination

API Rate Limits

How Does Vault Calculate Limits?

APU Rate Limit Headers

Authentication API Rate Limit Headers

Client ID

Errors

General/Vault-level Errors

CDMS-Specific Errors

Authentication

User Name & Password

Endpoint

Headers

URI Path Parameters

Body Parameters

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

Endpoint

Required Permissions

Headers

Response Details

Sites

Retrieve Sites

Endpoint

Required Permissions

Headers

Query String Parameters

Response Details

Subjects / Casebooks

Retrieve Subjects

Endpoint

Required Permissions

Headers

Query String Parameters

Response Details

Create Subjects (Casebooks)

Endpoint

Required Permissions

Headers

Body Parameters

Set Subject Status

Notes

Endpoint

Required Permissions

Headers

Body Parameters

Unset Subject Status

Endpoint

Required Permissions

Headers

Body Parameters

Event Groups

Create Event Groups

Common Use Cases

Endpoint

Required Permissions

Headers

Body Parameters