TOC Navbar
shell

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:

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

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

CDMS Structure Overview

CDMS API Overview

Endpoint Example Syntax

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

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

API Login / Sessions

Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d "username={username}&password={password}" \
"https://my-vault.veevavault.com/api/v23.2/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

Session Duration

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

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

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

Best Practices

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

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

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/v23.2/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/v23.2/app/cdm/queries/resource_locator=4db7ac7f-aa08-486a-99e1-9acb5cdda80e&limit=1000&offset=1000"

Response: 2nd Page (Results 1000 - 1749)

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

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

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

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.

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

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:

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.

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.

Developing with Rate Limits

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

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

  2. Cache configuration data. Configuration data does not change often. Retrieve it once and store it locally in a database like SQLite or serialized in a file.

  3. Optimize your code to eliminate unnecessary API requests. Are you retrieving data that isn’t being used in your application? Are you updating data that hasn’t changed? Eliminate these calls.

  4. Regulate the API request rate. If you are frequently approaching or reaching the API rate limit, consider implementing a throttling process in your application to distribute your requests more uniformly over time. For example, observe the above-mentioned response headers and monitor your request rate. Throttle requests when your rate reaches a certain threshold.

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

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

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

Example: Incorrect study_name for Create Subject / Casebook

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Study] with name [ABCP-2022-01_DEV2] not found",
            "study_country": "United States",
            "site": "101"
        }
    ]
}

Example: Using Set Event Date on a Frozen Subject

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

The table below lists common errors for CDMS APIs:

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

Authentication

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

User Name & Password

Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d "username={username}&password={password}" \
"https://my-vault.veevavault.com/api/v23.2/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.2 and run your integrations with v22.3.

Body Parameters

Name Description
username The username of your Vault account
password The password of your Vault account
vaultDNS Optional The DNS of the vault for which you want to generate a session. If omitted, generates a session for the user’s default vault.

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

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

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

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

Studies

Vault CDMS uses the Study object (study__v) to group together 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 -L -X GET 'https://myvault.veevavault.com/api/v23.2/app/cdm/studies' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 2,
        "total": 2
    },
    "studies": [
        {
            "study_name": "Labrinone_DEV1",
            "external_id": "Labrinone",
            "study_phase": "Phase III",
            "study_status": "Execution",
            "casebook_versions": [
                {
                    "study_name": "Labrinone_DEV1",
                    "casebook_version": 1,
                    "version_name": "Initial Version",
                    "external_id": "1",
                    "previous_version_name": null,
                    "description": null,
                    "change_reason": null,
                    "casebook_status": "in_progress__v",
                    "created_by": "Eric Emerton",
                    "created_date": "2018-02-12T22:32:21Z",
                    "last_modified_date": "2020-03-04T14:16:20Z"
                }
            ]
        },
        {
            "study_name": "ABCP-2022-01_DEV1",
            "external_id": "ABCP-2022-01",
            "study_phase": "Phase I",
            "study_status": "Planning",
            "casebook_versions": [
                {
                    "study_name": "ABCP-2022-01_DEV1",
                    "casebook_version": 2,
                    "version_name": "Version2",
                    "external_id": "Initial Version",
                    "previous_version_name": null,
                    "description": "Casebook Definition for the ABCP-2022-01_DEV1 study" ,
                    "change_reason": "Layout changes",
                    "casebook_status": "in_progress__v",
                    "created_by": "Maisha Muddaththir",
                    "created_date": "2023-06-09T13:26:34Z",
                    "last_modified_date": "2023-06-09T13:26:34Z"
                },
                {
                    "study_name": "ABCP-2022-01_DEV1",
                    "casebook_version": 1,
                    "version_name": "Initial Version",
                    "external_id": "Initial Version",
                    "previous_version_name": null,
                    "description": "Initial casebook definition version for the ABCP-2022-01_DEV1 study" ,
                    "change_reason": null,
                    "casebook_status": "published__v",
                    "created_by": "Maisha Muddaththir",
                    "created_date": "2023-06-09T13:26:34Z",
                    "last_modified_date": "2023-06-09T13:26:34Z"
                }
            ]
        }
    ]
}

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 1000 Studies per response. You can lower this number using the limit query parameter.

Endpoint

GET https://my-vault.veevavault.com/api/v23.2/app/cdm/studies

Required Permissions

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

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

Headers

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

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

Name Description
limit The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
offset The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0.

For example, if the limit is set to 100, and there are 150 possible records, an offset of 0 returns records 0 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 Studies that you have permission to view.

Array Name Description
studies name Name of the Study. Although very rare, this may differ from the study label seen on screen. ).
studies external_id External ID field value from the Study record (study__v.oid__v)
studies study_status Study Status field label from the Study record (study__v.study_status__v)
studies study_phase Study Phase field label from the Study record (study__v.study_phase__v)
studies casebook_versions For each Casebook Version associated with the Study, Vault returns the following as an array:
  • study_name
  • casebook_version
  • version_name
  • external_id
  • previous_version_name
  • description
  • change_reason
  • casebook_status
  • created_by
  • created_date
  • last_modified_by
studies/casebook_versions study_name Re-iterate of the study name. Each entry in casebook_versions represents the study schedule/design at that version. Sites and Subjects take on a specific casebook version, typically migrating from one to the next.
studies/casebook_versions casebook_version The version number (integer) of the casebook definition
studies/casebook_versions version_name The version name of the casebook definition
studies/casebook_versions external_id The external ID of the casebook definition
studies/casebook_versions previous_version_name Not in use, return is null
studies/casebook_versions description The descripition of the casebook definition
studies/casebook_versions change_reason A reason for the casebook version (if set)
studies/casebook_versions casebook_status The status of the casebook version, e.g. published__v, validated__v, etc. (Vault picklist values)
studies/casebook_versions created_by The name of the user that added (or deployed to) the casebook version
studies/casebook_versions created_date The creation date/time of the add (or deployment)
studies/casebook_versions last_modified_by The name of the user that last modified the casebook definition

Study Countries

Vault CDMS uses the Study Country object (study_country__v`) to group together Sites.

Retrieve Study Countries

Request

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

Response

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

Retrieve a list of all Study Countries for a given Study. Vault applications use a master Countries object, from which records are selected to take part in a study. These selections comprise Study Countries for the Study.

Endpoint

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

Required Permissions

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

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

Headers

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

Query Parameters

Include the following parameters to filter the results:

Name Description
study_name The Name (Study Number) of the Study (study__v.name__v) that you want to retrieve the study countries for, returned as study_name by the Retrieve Studies API.

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

Name Description
limit The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
offset The starting record number for the result set (as a positive integer). If omitted, the default is 1.

For example, if the limit is set to "100", and there are 150 possible records, use "101" as the offset to show results 101 through 150.

Response Details

Vault returns the following details about each Study Country:

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

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

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

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 - All sites in the study

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

Response - All sites in the study

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

Request - No sites in study yet

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

Response - No sites in study yet

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

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

Vault returns a maximum of 1000 Sites per response. You can lower this number using the limit query parameter.

Endpoint

GET https://my-vault.veevavault.com/api/v23.2/app/cdm/sites

Required Permissions

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

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

Headers

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

Query String Parameters

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

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

Name Description
limit The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
offset The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0.

For example, if the limit is set to 100, and there are 150 possible records, an offset of 0 returns records 0 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

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

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

Subjects / Casebooks

Vault CDMS uses two objects to manage participants in a study: Subject and Casebook. For the purposes of the CDMS API, these are synonyms. A Subject record represents an individual 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 - By Study Context

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

Response - By Study Context

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

Request - By IDs (two specific)

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

Response - By IDs (two specific)

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

Request - By Multiple Sites

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

Response - By Multiple Sites

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

Request - Where Subjects have IXRS IDs

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

Response - Where Subjects have IXRS IDs

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

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/v23.2/app/cdm/subjects

Required Permissions

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

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

Headers

Name Description
Accept application/json (default)

Query String Parameters (by Study Context)

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

Query String Parameters (by ID)

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

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

Name Description
limit The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
offset The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0.

For example, if the limit is set to 100, and there are 150 possible records, an offset of 0 returns records 0 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.

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

Create Subjects (Casebooks)

Request - Two subjects created at once

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

Response - Two subjects created at once

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

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

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

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

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

Request - Two subjects, with IXRS IDs

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

Response - Two subjects, with IXRS IDs

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

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. The limit for actions in one request is 100.

Endpoint

POST https://my-vault.veevavault.com/api/v23.2/app/cdm/subjects

Required Permissions

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

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).
ixrs_id subjects Optional The value in an IRT/IXRS system who adds the Subject, i.e. the ID it identifies the Subject with.

Set Subject Status

Request

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

Endpoint

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

Required Permissions

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

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/v23.2/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/v23.2/app/cdm/subjects/actions/unsetstatus

Required Permissions

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

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.

Update Subject

Request - Set new subject number

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

Response - Set new subject number

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

Request - Update an IXRS id

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

Response - Update an IXRS id

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

The endpoint is used for updating the Subject name/number, and/or the IXRS id previously set.

Endpoint

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

Required Permissions

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

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) now
subject_new subjects Optional Name of the Subject (ID / number) to change to
ixrs_id subjects Optional IXRS id value to update to

Update Subject by ID

Request - Set new subject number

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

Response - Set new subject number

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

Request - Update an IXRS id

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

Response - Update an IXRS id

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

The endpoint is used for updating the Subject name/number, and/or the IXRS id previously set. The internal ID of the subject is used instead of Study Country / Site / Subject values.

Endpoint

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

Required Permissions

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

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

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

Event Groups

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

Create Event Groups

Request - Scheduled Event Group

curl -X POST https://my-vault.veevavault.com/api/v23.2/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 - Scheduled Event Group

{
    "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/v23.2/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 - Unscheduled Event Group (requires a date)

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

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). The limit for actions in one request is 100.

Common Use Cases

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/v23.2/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/v23.2/app/cdm/eventgroups \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "ABCP-2022-01_DEV1",
    "eventgroups": [
      {
        "study_country": "United States",
        "site": "101",        
        "subject": "101-001",
        "eventgroup_name": "unscheduled_treatment_visits",
        "eventgroup_sequence": 1,
        "date": "2022-03-03"        
      }
    ]
  }'

Response - Attempt when Event does not exist

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

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

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

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

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

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. The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

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

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

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "limit": 1000,
        "offset": 0,
        "size": 5,
        "total": 5
    },
    "events": [
        {
            "id": "OPS00000001M006",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "screening",
            "eventgroup_sequence": 1,
            "event_name": "screening_visit",
            "event_sequence": 1,
            "locked": false,
            "frozen": false,
            "event_date": "2020-02-03",
            "externally_owned_date": true,
            "event_did_not_occur": false,
            "forms": [
                {
                    "id": "OPT00000001M002",
                    "form_name": "demographics",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "locked": false,
                    "frozen": false,
                    "intentionally_left_blank": false
                },
                {
                    "id": "OPT00000001M003",
                    "form_name": "exclusion_criteria",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "locked": false,
                    "frozen": false,
                    "intentionally_left_blank": false
                },
                {
                    "id": "OPT00000001M004",
                    "form_name": "inclusion_criteria",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "locked": false,
                    "frozen": false,
                    "intentionally_left_blank": true,
                    "intentionally_left_blank_reason": "Information not available"
                }
            ]
        },
        {
            "id": "OPS00000001M009",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "re_screen",
            "eventgroup_sequence": 1,
            "event_name": "baseline_visit",
            "event_sequence": 1,
            "locked": false,
            "frozen": false,
            "event_date": "",
            "externally_owned_date": false,
            "event_did_not_occur": true,
            "event_did_not_occur_reason": "Subject passed screening initially",
            "forms": []
        },
        {
            "id": "OPS00000001M011",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "enrollment",
            "eventgroup_sequence": 1,
            "event_name": "enrollment_visit",
            "event_sequence": 1,
            "locked": false,
            "frozen": false,
            "event_date": "2020-02-07",
            "externally_owned_date": false,            
            "event_did_not_occur": false,
            "forms": [
                {
                    "id": "OPT00000001M007",
                    "form_name": "randomization",
                    "form_sequence": 1,
                    "form_status": "submitted__v",
                    "locked": false,
                    "frozen": false,
                    "intentionally_left_blank": false
                }
            ]
        },
        {
            "id": "OPS00000001M008",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "treatment_visit",
            "eventgroup_sequence": 1,
            "event_name": "treatment_visit",
            "event_sequence": 1,
            "locked": false,
            "frozen": false,
            "event_date": "",
            "externally_owned_date": false,            
            "event_did_not_occur": false,
            "forms": []
        },        
        {
            "id": "OPS00000001M007",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0003",
            "eventgroup_name": "common_forms",
            "eventgroup_sequence": 1,
            "event_name": "common_forms",
            "event_sequence": 1,
            "locked": false,
            "frozen": false,
            "event_date": "",
            "externally_owned_date": false,            
            "event_did_not_occur": false,
            "forms": []
        }        
    ]
}

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.

The return array forms within each event can be empty for several reasons:

Endpoint

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

Required Permissions

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

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

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 Events and Forms within for a single Subject. Details of the response:

Array Name Description
events id Vault internal ID for the Event (willl never change)
events study_country Name of the Study Country for the site of the Subject
events site Name of the Site for the Subject
events subject Name (ID/number) of the Subject
events eventgroup_name Study design name for the Event Group
events eventgroup_sequence Sequence of the Event Group of the Event. If its a repeating Event Group, the value increments for each instance, starting at "1", then "2", and so on. If the Event Group isn't repeating, Vault returns "1".
events event_name Study design name for a the Event
events event_sequence Currently, always a 1. If the Event within a repeating Event Group the sequence increments at the evengroup_sequence level
events event_date Event date of the Event. yyyy-MM-dd format is returned.
events externally_owned_date Whether the date is owned by an external system, i.e. read only to the site users.
events event_did_not_occur Whether the event has been marked as not having occurred by a site user. (true/false)
events event_did_not_occur_reason Only when event_did_not_occur is true, otherwise this is omitted.
events/forms id Vault internal ID for the Form (willl never change)
events/forms form_name Study design name for a Form in the Event (entry per form)
events/forms form_sequence If its a repeating Form, the value increments for each instance, starting at "1", then "2", and so on. If the Form isn't repeating, Vault returns "1".
events/forms form_status The status (picklist name) of that form (e.g. blank__v, submitted__v, etc. See the table below for possible form statuses.
events/forms locked Whether the form is locked (true/false). Locked forms cannot be updated, nor the queries on them
events/forms frozen Whether the form is locked (true/false). Frozen forms cannot be updated (data wise), queries can be updated / added.
events/forms intentionally_left_blank Whether the Form has been marked intentionally left blank (ILB) by a site user. (true/false)
events/forms intentionally_left_blank_reason When intentionally_left_blank is true for the Form, the reason. Otherwise, omitted.

Form Statuses

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

Create Events

Request - Create two events, different subjects

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

Response - Create two events, different subjects

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

Request - Create event inside a repeating event group

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

Response - Create event inside a repeating event group

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

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. The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

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/v23.2/app/cdm/events/actions/setdate \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "events": [
          {
          "study_country": "United States",
          "site": "101",          
          "subject": "101-001",
          "eventgroup_name": "Screening-Visit",
          "event_name": "Screening-Visit",
          "date": "2022-05-21"
          }
      ]
    }'

Response - Set one event date

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

Request - Change one event date

curl -X POST https://my-vault.veevavault.com/api/v23.2/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 - Change one event date

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

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. The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

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.
externally_owned_date events Optional When omitted true is used, i.e. the site user cannot then further edit the date. Pass a false to re-enable the ability for a user to edit a previously read only event date.

Set Event as Did Not Occur

Request - Set two events as did not occur

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

Response - Set two events as did not occur

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

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. The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

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/v23.2/app/cdm/forms?study_name=ABCP-2022-01_DEV1&site=0101&study_country=United%20States&subject=101-001&eventgroup_name=screening&event_name=screening_visit' \
-H 'Authorization:{SESSION_ID}'

Response


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

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.

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/forms

Required Permissions

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

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.

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 Forms within the Subject / Event provided, with the following information:

Array Name Description
forms id Vault internal ID for the Form (willl never change)
forms study_country Name of the Study Country for the site of the Subject
forms site Name of the Site for the Subject
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 When intentionally_left_blank is true for the Form, the reason. Otherwise, omitted.
forms/itemgroups id Vault internal ID for the Item Group (willl never change)
forms/itemgroups itemgroup_name Study design name for an Item Group in the Form
forms/itemgroups itemgroup_sequence If the Item Group repeats per study design (within the Form), these increment starting at 1, 2.... If it does repeat, 1 is always returned.
forms/itemgroups itemgroup_external_id Another study design reference/name for the Item Group. This value is usually the same as the name.
forms/itemgroups/items id Vault internal ID for the Item (willl never change)
forms/itemgroups/items item_name Study design name for the Item
forms/itemgroups/items value The value for that Item. The value returned will differ by the type of the Item, study design wise (e.g. Date, DateTime, Time, Check Box, Codelist, etc., see the table below)
forms/itemgroups/items unit_value Only applies when the Item type is Unit Codelist. This is the unit selected to pair with the value entered by the end user. If the Item is not a Unit Codelist, this line is omitted.
forms/itemgroups/items translated_value Only applies when the Item type is Unit Codelist. The user value is calculated to the standard unit defined for the Item. If the user selects the standard unit, the value here will be the same as value. If the Item is not a Unit Codelist, this line is omitted.
forms/itemgroups/items translated_unit_value Only applies when the Item type is Unit Codelist. The standard unit for the Item, as defined in the study. If the user selects the standard unit, the value here will be the same as unit_value. If the Item is not a Unit Codelist, this line is omitted.
forms/itemgroups/items lab_modifier Only applies when the Item type is Unit Codelist, and the Item has a value for Lab Modifier. Example: A lab value is 'Less than 0.7', results in value: 1, and the coded value for 'Less than' as setup in the study design. If the Item is not a Unit Codelist or the Lab Modifier is empty / not set, this line is omitted.
forms/itemgroups/items intentionally_left_blank Whether the Item has been marked intentionally left blank (ILB) by a site user. (true/false)
forms/itemgroups/items intentionally_left_blank_reason When intentionally_left_blank is true for the Item, the reason. Otherwise, omitted.
forms/itemgroups/items externally_owned Whether the Item is owned by another system. When true, the Item value it not editable by site users, even if the Item Definition is set for editable.
forms/itemgroups/items frozen Whether the Item is currently frozen or not. An Item can be frozen without freezing the entire Form. Frozen does not allow data changes, but does allow query activity.
forms/itemgroups/items locked Whether the Item is currently locked or not. An Item can be locked without freezing the entire Form. Locked does not allow data changes, nor query activity.

Form Statuses

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

Item Value Return by Item Type

Item Type State/Value Example Return
Checkbox (never been checked) "value": null
Checkbox Checked "value": "true"
Checkbox Unchecked (but at one time checked) "value": "false"
Codelist (never been selected) "value": null
Codelist Codelist code value "value": "Y"
(e.g. 'Yes' = 'Y' for codelist)
Codelist Codelist saved non-empty, now empty "value": null
Date (never been set) "value": null
Date Full date set "value": "05-Jun-2022"
(The study date format is returned, not ISO)
Date (value set, then later unset) "value": null
Date Partial date saved (day and month unknown) "value": "UN-UNK-2022"

(assuming dd-MMM-yyyy study date format)
DateTime (never been set) "value": null
DateTime Full date time set "value": "05-Jun-2022 13:30"
(The study date format is returned, not ISO)
DateTime (value set, then later unset) "value": null
DateTime Partial date saved (day and time unknown) "value": "UN-Jun-2022 UN:UN"
Assuming dd-MMM-yyyy study date format, day and time unknown
URL Field (never been set) "value": null
URL Field Set with a value "value": "https://www.google.com"
URL Field (value set, then later unset) "value": null
Unit Codelist (never been set) "value": null,
"unit_value": null,
"translated_value": null,
"translated_unit_value": null
Unit Codelist Set with value and unit "value": "150.2",
"unit_value": "lbs",
"translated_value": "68.129574",
"translated_unit_value": "kg"
Unit Codelist Set with value and unit, plus lab modifier set "value": "0.001"
"unit_value": "mg",
"translated_value": "1.0",
"translated_unit_value": "g",
"lab_modifier": "<"
Unit Codelist (value set, then later unset) "value": null,
"unit_value": null,
"translated_value": null,
"translated_unit_value": null
Numeric (Integer or Decimal) (never been set) "value": null
Numeric (Integer or Decimal) Set with a value "value": "32.45"
Numeric (Integer or Decimal) (value set, then later unset) "value": null
Text (never been set) "value": null
Text Set with a value "value": "This is my text set in the field on screen"
Text Set with a value - comments field with return character (use \n for breaks) "value": "Here is my long text with a carriage return \nhere \nand here\nand the end of the text is here"
Text (value set, then later unset) "value": null

Combination Update Form Data

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

This endpoint is a singular call that can perform many actions at once. These actions are those from these existing endpoints:

Actions that do / can happen:

Actions that do not happen:

Endpoint

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

Required Permissions

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

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

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

Setting Data by Item Type

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

Create Forms

Request - adding one new form

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

Response - adding one new form

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

Request - adding multiple forms

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

Response - adding multiple forms

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

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). The limit for actions in one request is 100.

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:

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 - adding one new form

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

Request - adding multiple forms

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

Response - adding multiple forms

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

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. The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

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 - Add one item group, where form already has 3

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

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

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

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

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

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). The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

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/v23.2/cdm/itemgroups' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "itemgroups": [
            {
                "study_country": "United States",
                "site": "102",               
                "subject": "SCR-0002",
                "eventgroup_name": "egSCR",
                "event_name": "evSCR",
                "form_name": "IE",
                "form_sequence": 1,
                "itemgroup_name": "ig-IE2",
                "itemgroup_sequence": 2 
            },
            {
                "study_country": "United States",
                "site": "102",               
                "subject": "SCR-0002",
                "eventgroup_name": "egSCR",
                "event_name": "evSCR",
                "form_name": "IE",
                "form_sequence": 1,
                "itemgroup_name": "ig-IE2",
                "itemgroup_sequence": 3 
            } 
    ]
}'

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

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

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

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

    ]
}'

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

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

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. The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

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

Response - Setting values for one of each type of item

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

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:

Endpoint

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

Required Permissions

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

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"
externally_owned forms/items Optional When omitted true is used, i.e. the site user cannot then further edit the value. Pass a false to re-enable the ability for a user to edit a previously read only Item.

Upsert Form Data (Items)

Request - Setting values for one of each type of item

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

Response - Setting values for one of each type of item

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

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

Notes:

Setting Data by Item Type

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

Endpoint

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

Required Permissions

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

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"
externally_owned forms/items Optional When omitted true is used, i.e. the site user cannot then further edit the value. Pass a false to re-enable the ability for a user to edit a previously read only Item.

Submit Forms

Request - Submit one form

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

Response - Submit one form

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

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. The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

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 - Open one form for edit

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

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. The limit for actions in one request is 100.

Endpoint

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

Required Permissions

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

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:

Learn more about queries in Vault CDMS Help.

Retrieve Queries

Request

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

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:

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/v23.2/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:

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

Headers

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

Query String Parameters

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

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

Name Description
limit The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
offset The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0.

For example, if the limit is set to 100, and there are 150 possible records, an offset of 0 returns records 0 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/v23.2/app/cdm/queries \
  -H "Authorization: {SESSION_ID}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
            {
                "study_country": "United States",
                "site": "101",                
                "subject": "101-001",
                "eventgroup_name": "EG.SCR",
                "eventgroup_sequence": 1,
                "event_name": "EV.SCR",
                "form_name": "F.DM",
                "form_sequence": 1
                "itemgroup_name": "IG.DEMOG",
                "itemgroup_sequence": 1,
                "item_name": "DOB",
                "message": "This date does not match our records."
            }
    ]
  }'

Response - Add one query, item level


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

Request - Add two queries, item level and event level

curl -X POST \
  https://my-vault.veevavault.com/api/v23.2/app/cdm/queries \
  -H "Authorization: {SESSION_ID}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
            {
                "study_country": "United States",
                "site": "101",
                "subject": "101-001",
                "eventgroup_name": "EG.SCR",
                "eventgroup_sequence": 1,
                "event_name": "EV.SCR",
                "message": "Please double check the screening date entered"
            },
            {
                "study_country": "United States",
                "site": "101",
                "subject": "101-001",
                "eventgroup_name": "EG.SCR",
                "eventgroup_sequence": 1,
                "event_name": "EV.SCR",
                "form_name": "F.DM",
                "form_sequence": 1
                "itemgroup_name": "IG.DEMOG",
                "itemgroup_sequence": 1,
                "item_name": "DOB",
                "message": "This date does not match our records."
            }
    ]
  }'

Response - Add two queries, item level and event level


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

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). The limit for queries opened in one request is 100.

Other options exist to open a new query, see also:

Endpoint

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

Required Permissions

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

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/v23.2/app/cdm/events/actions/openquery' \
-H 'Authorization: {SESSION_ID}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "manual": false,
    "queries": [
                 {
                   "id": "OPS00000001X001",
                   "message": "We ran screening at this site on Saturday, July 31."
                 }
               ]
}'

Response

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

Open a Query on an Event (located on the Event date) by providing the Vault internal ID of the Event. The limit for queries opened in one request (by event ID) is 500. The response for this API includes information about messages on the query just added (id, message_date, etc.), but does not include the study context information.

Other options exist to open a new query, see also:

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:

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

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

Open Queries by Item ID

Request

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

Response

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

        }
    ]
}

Open a Query on an Item (residing on a Form) by providing the Vault internal ID of the Item. The limit for queries opened (by Item ID) in one request is 500. The response for this API includes information about messages on the query just added (id, message_date, etc.), but does not include the study context information.

Other options exist to open a new query, see also:

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:

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

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

Open Queries by Medical Coding Request

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.) The limit for actions in one request is 100.

Other options exist to open a new query, see also:

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/v23.2/app/cdm/queries/actions/answer \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization",
            "message": "This subject was enrolled late."
        }
    ]
  }'

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

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

Request - Answer by ID

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

Response - Answer by ID

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

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. The limit for actions in one request is 100.

There are two ways to answer a query:

Endpoint

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

Required Permissions

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

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/v23.2/app/cdm/queries/actions/close \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "queries": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization",
            "message": "This issue is now resolved. Query closed."
        }
    ]
  }'

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

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

Request - Close by ID

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

Response - Close by ID

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

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. The limit for actions in one request is 100.

There are two ways to close a query:

Endpoint

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

Required Permissions

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

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 Optional The message at close of the Query

Body Parameters (By ID)

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

Close Queries (by ID / Batch)

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

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

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

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

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

Endpoint

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

Required Permissions

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

The CDMS API Read Write role grants these permissions.

Headers

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

Body Parameters

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

Reopen Queries

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

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

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

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

Request - Reopen by ID

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

Response - Reopen by ID

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

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. The limit for actions in one request is 100.

There are two ways to reopen a query:

Endpoint

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

Required Permissions

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

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

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 added and updated upon the submission of the Form containing the Item. MedDRA and WHODrug (B3 or C3) versions are configured per study design.

Retrieve Coding Requests

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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


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

Retrieve a list of Medical Coding Requests for a Form. For each request, coding status, definition information, and the assigned code (if any) are returned.

The parameter to get existing Medical Coding Requests can be found by first using the Retrieve Coding Definitions API endpoint. It returns both coding_item_definition_id (Vault ID) and coding_item_definition_name. At v22.3 coding_item_definition_id is used for this endpoint, where it used to be the name value into coding_item_definition. The Retrieve Coding Definitions, Retrieve Coding Requests, and Retrieve Coding Queries - at v22.3 - all require the Vault ID of the coding definition as request parameter.

Endpoint

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

Required Permissions

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

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

Headers

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

Query String Parameters

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

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

Name Description
limit The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
offset The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0.

For example, if the limit is set to 100, and there are 150 possible records, an offset of 0 returns records 0 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 Medical Coding Requests (as JSON array entries) with the following information:

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

Retrieve Coding Queries

Request

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

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

Headers

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

Query String Parameters

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

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

Name Description
limit The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
offset The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0.

For example, if the limit is set to 100, and there are 150 possible records, an offset of 0 returns records 0 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/v23.2/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) The limit for actions in one request is 100.

Other options exist to open a new query, see also:

Endpoint

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

Required Permissions

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

The CDMS API Read Write grants these permissions.

Headers

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

Body Parameters

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

Set Coding Suggestions

Request - MedDRA suggestions

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

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

Response - MedDRA suggestions

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

Request - WHODrug suggestions

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

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

Response - WHODrug suggestions

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

Request - Remove suggestions from a coding request

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

Response - Remove suggestions from a coding request

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

Request - Top level failure (study not configured)

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

Response - Top level failure (study not configured)

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

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

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

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

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

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

The action is used to set external coding suggestions to specific Medical Coding Requests.

Endpoint

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

Required Permissions

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

The role CDMS API Read Write grants these permissions.

Headers

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

Body Parameters

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

Jobs

Job Summary / Types

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

The following job types are currently supported:

Name API Name Description
Study Data Extract (SDE) study_data_extract__v Generates ZIP of CSV files (with/without SAS and SAS XPT files). The file includes clinical datasets (Form data), system/operational datasets, custom objects involved with the study, and/or study definitions. This export is the primary and most comprehensive full export of study data. It can be run in subset for faster execution, e.g., just Adverse Events, SYS_Q (queries), and so forth. Learn more about the content of the SDE can be found at CDMS Help
Subject Progress Listing subject_progress_listings__v Generates CSV of metrics at Subject level. This summary is not study design specific, instead primarily operational data, statuses, row per Subject
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 (WARNING - to be deprecated 23R3) Predecessor to the SDE, also once known as the JReview job type. Generates a ZIP file of CSVs representing collected data in your Study, as well as definitions. (Format different from the SDE)
Audit Trail by Study audit_trail_export__v Job that produces audit trail reporting, with specified start to end date ranges and/or specific users. The result of the job is a zip file containing CSVs, by Subject. The range of start to end can be no more than 30 days when starting this job from the API. Wider ranges are started from the EDC Tools user interface.
Audit Trail by Site audit_trail_export_by_site__v Job that produces audit trail reporting, with specified start to end date ranges, specific users, and/or specific sites. The result of the job is a zip file containing CSVs, by Subject. The range of start to end can be no more than 30 days when starting this job from the API. Wider ranges are started from the EDC Tools user interface.
Audit Trail by Subject audit_trail_export_by_subject__v Job that produces audit trail reporting, with specified start to end date ranges, specific users, and/or specific subjects. The result of the job is a zip file containing CSVs, by Subject. The range of start to end can be no more than 30 days when starting this job from the API. Wider ranges are started from the EDC Tools user interface.

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

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

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

Learn more about managing jobs in CDMS Help.

Retrieve Study Jobs

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

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

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

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

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

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

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

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

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

Endpoint

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

Required Permissions

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

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

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

Name Description
limit The size of the result set on the page (as a positive integer). If omitted, the default is 1000.
offset The starting record number for the result set (as a positive integer or zero). If omitted, the default is 0.

For example, if the limit is set to 100, and there are 150 possible records, an offset of 0 returns records 0 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 Study Jobs (as JSON array entries) with the following information:

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

Start Job by Type

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

Study Data Extract (SDE)

Request - Start SDE

curl -L -X POST 'https://my-vault.veevavault.com/api/v23.2/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,
       "include_study_design": true,
       "version": "v23.2",
       "export_file_types": ["CSV", "SAS"],
       "file_name": "ABCP-2022-01_DEV1_Study_Data_Extract",
       "use_external_ids": false,
       "include_formilb": true,
       "split_datetime": false,
       "exclude_blank_forms": false,
       "all_clinical_datasets": true,
       "all_system_datasets": true,
       "include_custom_objects": false
    }
}'

Response - Start SDE

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

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:

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:

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

Response Details

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

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

Subject Progress Listing

Request - Start Subject Progress Listing

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

Response - Start Subject Progress Listing

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "subject_progress_listing__v",
       "job_id": 525007,
       "created_by": "chunter@abcpharma.com",
       "created_date": "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:

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/v23.2/app/cdm/jobs/start_now' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-D '{
   "study_name": "ABCP-2022-01_DEV1",
   "request": {
       "job_type": "event_progress_listing__v",
       "include_restricted_data": true,
       "include_review_data": true
   }
}'

Response - Start Event Progress Listing

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

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

Endpoint

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

Required Permissions

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

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

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

Headers

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

Body Parameters

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

Response Details

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

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

Form Progress Listing

Request - Start Form Progress Listing

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

Response - Start Form Progress Listing

{
   "responseStatus": "SUCCESS",
   "response": {
       "job_type": "form_progress_listing__v",
       "job_id": 525105,
       "created_by": "chunter@abcpharma.com",
       "created_date": "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:

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 in