Getting Started

This tutorial explains the Vault user permissions needed to access the DQS Workbench API, how to structure an endpoint and retrieve a session ID, and other key components related to API usage.

Run in Postman™

Starting with v23.2, DQS provides a Postman™ collection for each GA release of the DQS API. Note that this collection represents the point in time when the API became GA, and will not receive additional updates. For the most up-to-date documentation, developers should reference the API reference.

Install Postman™, then click the button below to import the DQS API collection.

To use this collection effectively, set the following environment variables:

• vaultDNS: DNS of the vault. Do not include a trailing slash (/).
• cdbDNS: DNS of the DQS instance you're using. For example, "https://my-vault.veevavault.com”.
• username: Your user name, including the domain, for example, "chunter@verteopharma.com".
• password: Your password.
• version: The version of the API that you want to use, for example, "v23.2". See the Versioning section for details.

The term Full Payload in the collection is referred to as Full Hierarchy in this documentation.

To learn more about the structure of Clinical Data, see Clinical Data Structure Overview.

API Access

To access the DQS Workbench API, your Study Role must grant the API Access permission. You must also have the appropriate permissions for the action you want to perform via the API. For example, for the Open Queries on Items endpoint, you must have the Open Query and Workbench Tab permissions, in addition to API Access. In the API Reference, each endpoint lists the required permissions.

Your user account must also have All Sites access in your study.

See Managing User Access in Clinical Data Help for details on account creation and role assignment.

Insufficient Access

If you do not have API access, your authentication request will succeed, but subsequent API calls return standard Vault error responses, such as:

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

If you receive this error, contact your Vault administrator to adjust your security profile and permission set.

Structuring the Endpoint

DQS API endpoints use the Unified Vault URL structure, allowing you to execute requests directly using your Vault URL:

https://[Vault-domain]/api/{version}/dqs/[resource]

Replace the following variables with your unique details:

• {Vault-domain}: The domain URL of your Vault instance (for example, myvault.veevavault.com).
• {version}: The API release version (for example, v26.3).
• [resource]: The specific endpoint path (for example, queries or sff/packages).

Path Examples

The following examples illustrate DQS’s current endpoint structure compared to legacy paths:

Path Type	Structure Example
Unified Vault Path	https://[Vault-domain]/api/v26.3/dqs/queries
Legacy Path	https://[DQS-domain]/edcworkbench/api/v26.1/queries

Versioning & Naming

DQS introduces new API versions during its triannual release cycles, coinciding with the DQS General Releases. DQS API versions follow the pattern vYY.1, vYY.2, vYY.3 where YY is the last two digits of the current year. For example, the first DQS General Release of 2023 is 23R1. The API version which coincides with this release is API v23.1. The third DQS General Release of 2022 is 22R3, which coincides with API v22.3.

Each General Release is made up of multiple limited releases. For example, DQS release 23R1 includes all features released in 22R3.2, 22R3.3, 22R3.4, and 22R3.5.

The API versioning does not have limited release numbering. Instead, the latest version (in this example, v23.1) is labeled as Beta and all limited release features are added to the Beta API. For example, API v18.1 contains all features released in 17R3.2, 17R3.3, 17R3.4, and 17R3.5.

Backwards Compatibility

All API updates and breaking changes apply to the latest active API version. To access new endpoints, fields, or parameters, you must update the version segment in your request URL to the newest version.

Legacy Domain Versioning

Some older API endpoints (prior to v26.3) utilize legacy domain-specific versioning (i.e., seperate domain version numbers for Forms, Queries, and Study File Format). DQS continues to support these legacy paths and will announce end-of-support schedules in advance.

See the Release Notes for the latest DQS APIs, enhancements, bug fixes, and service announcments.

Get a Session ID

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": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 1776,
      "name": "PromoMats",
      "url": "https://promo-vee.veevavault.com/api"
    },
    {
      "id": 1782,
      "name": "Platform",
      "url": "https://platform-vee.veevavault.com/api"
    }
  ],
  "vaultId": 1776
}

Your first API call will be an authentication request, which provides your session ID for other API calls. The call returns a JSON response that contains the session ID. To do this, call the auth endpoint. The auth endpoint (/api/{version}/auth) expects two URL-encoded form parameters (x-www-form-urlencoded): username and password.

Pagination

By default, DQS returns a maximum of 500 records per page. You can lower this using the size operator. The size operator must be a positive integer.

The first example illustrates limiting the number of Queries returned to 20 per page.

Example: Size Operator

curl -L -X GET 'https://my-vault.veevavault.com/edcworkbench/api/v23.2/forms/data?study_name=Laterzen_DEV1&source=EDC&site_number=100&subject_name=SCR-0003&form_name=physical_exam&size=20

With a maximum of 500 records returned per page, you must submit a new request to see the "next page" or results using the page operator. The page operator is used in a request the same way as the size operator above. The page operator defaults to 1. The number you provide for the offset is the number of the first record from the collection to include in the results. For example, "51" would return the fifty-first (51st) result in the collection and the following results (subject to the limit). The page operator must be a positive integer. If the value is greater than the total number of records in the collection, no results will be returned.

In the second example, if you're viewing the first page of 200 results within a record (the default maximum per page) out of 1,000 total results found, and you want to see the next 200 results, enter page=201. In the third example from Get Form Data, assuming there are 5 total pages, the total records = 10 and the size = 2.

Example: Page Operator

curl -L -X GET 'https://my-vault.veevavault.com/edcworkbench/api/v23.2/forms/data?study_name=Laterzen_DEV1&source=EDC&site_number=100&subject_name=SCR-0003&form_name=physical_exam&size=5&page=201

Example: Get Form Data

{
  "metadata": {
    "totalRecords": 10,
    "links": {
         "first": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&size=2&subject_name=SCR-0001&source=EDC&page=1&site_number=100&form_name=adverse_event",
            "self": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&size=2&subject_name=SCR-0001&source=EDC&page=1&site_number=100&form_name=adverse_event",
            "any": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&size=2&subject_name=SCR-0001&source=EDC&page={page}&site_number=100&form_name=adverse_event",
            "prev": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&size=2&subject_name=SCR-0001&source=EDC&page=1&site_number=100&form_name=adverse_event",
            "next": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&size=2&subject_name=SCR-0001&source=EDC&page=2&site_number=100&form_name=adverse_event",
            "last": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&size=2&subject_name=SCR-0001&source=EDC&page=5&site_number=100&form_name=adverse_event"
        }
      }      
}

If additional pages are available, the response includes a node called metadata containing information about the totalRecords, and a links block containing the URLs to the additional pages. The fields are as follows:

Field	Description
first	The first page
self	The current page
any	Contains a variable {page} where users can specify which page they want to access
prev	The previous page
next	The next page
last	The last page

When fetching the next page of data, there is no need to provide any of the original API parameters, for example, study_name or source. Users can use the URL in the next attribute to fetch the next page of results, if available.

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.

Learn more about how Vault enforces rate limits on the Vault Developer Portal and in Vault Help.

Queries API

DQS implements the following limits for the Queries API.

Description	Limit	Comments
Open Queries on Items	500	Number of queries that can be opened on Items in one payload request for both EDC and 3PD sources.
Open Queries on Events	500	Number of queries that can be opened on Events in one payload request for both EDC and 3PD sources.
Answer Queries (EDC Data)	100	Number of queries that can be answered in one payload request for an EDC source. When combined with 3PD data, the total limit is 500 queries (100 for the EDC source and 400 for the 3PD source).
Answer Queries (3PD Data)	500	Number of queries that can be answered in one payload request for a 3PD source.
Close Queries	500	Number of queries that can be closed in one payload request for both EDC and 3PD sources.

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:

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

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

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

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

We recommend basing your logic on the responseStatus field and error types, not on the HTTP response status codes.

DQS-Specific Errors

The table below lists common errors for DQS APIs:

Area	Error	Details
Forms	The page field must be an integer greater than or equal to 1	Invalid input for page
Forms	The size field must be an integer greater than or equal to 1	Invalid input for size
Forms	The [study_name/source/site_number/form_name] field is required	Missing required parameter for Get Forms
Forms	The study_name field is required in the request URL	Study Name parameter not provided
Forms	Site with number [site_number] not found in Study [study_name]	Site provided, but invalid
Forms	Source with name [source] not found in Study [study_name]	Source provided but invalid
Forms	Subject with name [subject_name] not found in Site [site_name]	Subject provided, but invalid
Forms, Queries	User does not have the permissions required to use this API	Invalid permission to run API - Generic
Forms, Queries	Study with name [study_name] not found. This may have been caused by a pending load in the study.	Study Name provided, but invalid
Queries	Object with ID [OPW00000003D004] not found.	User does not have permission to answer a query on blinded/restricted Item on EDC data
Queries	User cannot answer [EDC or Non-EDC] queries without [Answer query or answer third-party query] permission	User has only one of the Answer permissions but tries to open queries on data they don't have access to
Queries	Required field [query_id] is missing or empty for provided query [payload]	Query ID is not provided
Queries	Query with Query ID(s) [string] not found	Query ID is provided, but not found
Queries	Query is already in the Closed status	Query is already Closed
Queries	Duplicate Query IDs [query IDs] were found in the request	Duplicate Query ID found in the request
Queries	[Query] with ID [OPW00000003D004] not found	User does not have permission to close a query on blinded/restricted Item on EDC data
Queries	The [field_name] field is required and must be non-empty	Missing the entire queries field
Queries	User does not have the permissions required to answer the query with the ID [query_id]	Invalid permission for one or more queries when answering a query
Queries	The study_name field is required in the top level of the request body	Study Name parameter not provided
Queries	Cannot query on Event with ID [event_id]	Adding a query on a Log Type event
Queries	Provided identifiers [source/site_number/subject_name/eventgroup_name/event_name] does not identify an event in this study.	Identifiers provided in the input cannot be mapped to a valid Event
Queries	Required field [required field] is missing or empty for provided query [query information]	Missing a required parameter for other endpoints
Queries	Provided query [information] is missing one or more identifying fields. Please populate [event_id/item_id] or the following fields: [fields required to be filled if the event_id is not populated]	Missing one or more of the identifying fields
Queries	Provided identifiers [source/form_name/itemgroup_name/item_name] does not identify an Item in this study.	Identifiers provided in the input cannot be mapped to a valid Item
Queries	Item with ID [item_id] not found	Item ID is provided, but invalid
Queries	Item is locked	Form, Site, Study, or Subject is locked
Queries	Event with ID [event_id] not found	Event ID is provided, but invalid (or restricted/blinded)
Queries	[origin_sys/origin_id/origin_name] field exceeds length of [max length]	Origin input fields exceed character length
Queries	Cannot set field with name [origin_sys/origin_id/origin_name] as reserved name "CDB"	User tries to set origin_sys as "CDB"
Queries	Cannot set field with name [origin_sys/origin_id/origin_name] when [manual] = true	Conflict between manual flag and origin fields
Queries	[origin_sys] are required in order to set field with name [origin_id/origin_name]	origin_sys must be set before other origin fields
Queries	Event date is locked	Event date is locked specifically
Queries	Required field 'message' is missing or empty for provided query [source/study_name/site_number/form_name]	Message is missing or an empty string
Queries	Message exceeds maximum length of 500 for provided query	Message is invalid (too long)
Queries	Cannot set field with name [manual], queries created through the DQS API are categorized as System queries	User tries to specify a manual field in v24.3+
Queries	Requested api version is not available: requested_version; available versions are [available_versions]	Endpoint-specific validation when a user specifies an invalid API version.
Queries	Study with name study_name could not be found. This may have been caused by a pending load in the study	Study is invalid, archived, or there is no active swap.
Queries	The resource locator resource_locator has expired or is invalid.	The resource_locator has exceeded the 20 minute window.
Queries	The study_name field is required in the request URL	Missing the required study_name parameter.
Queries	Source with name input not found in study_name	Invalid parameter provided for source.
Queries	Country with name input not found in study_name	Invalid parameter provided for site_country.
Queries	Site with name input not found in study_name	Invalid parameter provided for site_number.
Queries	Subject with name input not found in Site site	Invalid parameter provided for subject_name.
Queries	Form Definition with name input not found in study_name	Invalid parameter provided for form_name.
Queries	Required field field is missing or empty for provided query	Missing a required field. The site_number parameter is required when using subject_name.
Queries	Maximum limit of 200 of unique Query IDs reached.	The id parameter count exceeds the maximum allowed.
Queries	ACCESS DENIED	The user does not have the necessary permissions.
SFF	Requested api version is not available: [version]	Applicable to List/Download Packages
SFF	Requested api version is not available: [version]	Applicable to List/Download Packages
SFF	SFF is not enabled for this study: [study_name]	SFF feature is turned off for this specific study
SFF	The study_name field is required in the request URL	Missing study_name in SFF request
SFF	Invalid parameter: stop_time. Reason: Text could not be parsed	Expected format: yyyy-MM-dd'T'HH:mm[:ss]Z
SFF	Invalid parameter: type. Must be one of [full, incremental]	Invalid SFF type provided
SFF	Unknown SFF ID: [sff_id]	SFF ID provided does not exist
SFF	Package has expired. SFF ID: [sff_id]	Packages remain accessible for only 48 hours
Jobs	Package has expired for job id [job_id].	Retrieve Job Artifact: Package deleted after 30 days
Jobs	Job with status 'In Progress' is not able to return an export	Retrieve Job Artifact: Job not yet finished
Jobs	Job with id [job_id] not found	Retrieve Job Status: ID does not exist
Jobs	Date range requested exceeds 30 days.	Retrieve Job History: window must be within 30 days
Export	Unable to start job because study_name is Inactive.	Start Export Job: Study must be Active
Export	Definition with name '[name]' not found	Start Export Job: Definition name does not exist
Export	An export job with the same definition in the Study is already running.	Start Export Job: Concurrent job conflict
Export	Jobs, Get Forms	Invalid parameter: size Reason: Parameter size cannot exceed 1000
Listings	The 'ids' field is required	The request payload does not specify the required listing IDs.
Listings	status 'test' is not supported	The request provides an invalid listing status.
Listings	Invalid parameter: '[last_refreshed_date_start/last_refreshed_date_stop]'. Expected format: yyyy-MM-dd'T'HH:mm[:ss]'Z'	The request provides an incorrectly formatted date parameter.
Listings	You do not have permission to view this resource.	The user is attempting to access or download a package without the required access permissions.
Listings	Resource not found.	The system cannot find the specified listing package ID.
Listings	The 'study_name' field is required in the top level of the request body	The required study_name parameter is not present in the request body.
Listings	CDB_MAINTENANCE	The DQS (formerly CDB) platform is currently undergoing maintenance.

For general errors, see General/Vault-level Errors.

Authentication

To make API calls against Vault, you need a Vault user account with API access. Once you have this, you can authenticate to obtain a session ID.

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

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

URI Path Parameters

Parameter	Description
vault_subdomain	The DNS of the Vault for which you want to generate a session.
version	The Vault 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

Parameter	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 Header

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

Header	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

Header	Description
Authorization	Bearer {access_token}
Accept	application/json (default)

URI Path Parameters

Parameter	Description
oath_oidc_profile_id	The ID of your OAuth2.0 / Open ID Connect profile

Body Parameters

Parameter	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

Header	Description
Accept	application/json (default)

Query String Parameters

Parameter	Description
username	The user’s Vault username
client_id	Optional The user's mapped Authorization Server client_id. This only applies the SSO auth_type.

Response Details

The response specifies the user’s authentication type (auth_type):

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

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

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

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

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

File Staging

You can create and manage files and folders in your Vault’s file staging. Learn more about file staging in Vault Help.

To upload files up to 50 MB, use the Create Folder or File API. For third-party data (3PD) loads or files larger than 50 MB, use Resumable Upload Sessions.

Forms

v23.2

Get Form Data

Request

curl -L -X GET 'https://my-vault.veevavault.com/edcworkbench/api/v23.2/forms/data?study_name=Deetoza_DEV1&subject_name=SCR-0003&source=EDC&page=1&site_number=100&form_name=physical_exam' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response

{
  "responseStatus": "SUCCESS",
  "metadata": {
    "totalRecords": 1,
    "links": {
        "first": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&subject_name=SCR-0003&source=EDC&page=1&site_number=100&form_name=physical_exam",
        "self": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&subject_name=SCR-0003&source=EDC&page=1&site_number=100&form_name=physical_exam",
        "any": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&subject_name=SCR-0003&source=EDC&page={page}&site_number=100&form_name=physical_exam",
        "prev": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&subject_name=SCR-0003&source=EDC&page=1&site_number=100&form_name=physical_exam",
        "next": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&subject_name=SCR-0003&source=EDC&page=1&site_number=100&form_name=physical_exam",
        "last": "/api/v23.2/forms/data?study_name=Deetoza_DEV1&subject_name=SCR-0003&source=EDC&page=1&site_number=100&form_name=physical_exam"
    }
  },
  "data": [
       {
        "source": "EDC",
        "site_number": "100",
        "site_country": "USA",
        "subject_name": "SCR-0003",
        "event_id": "OPS00000002I002",
        "eventgroup_name": "cohort1",
        "eventgroup_sequence": 1,
        "event_name": "visit1",
        "event_sequence": 1,
        "form_id": "OPT00000002U004",
        "form_name": "physical_exam",
        "form_sequence": 1,
        "itemgroups": [
               {
                   "itemgroup_name": "physical_exam",
                   "itemgroup_sequence": 1,
                   "items": [
                       {
                           "item_id": "V5700000002M018",
                           "item_name": "abnormal_findings",
                           "restricted": true,
                           "datatype": "text__v",
                           "length": 1500
                       },
                       {
                           "item_id": "V5700000002M017",
                           "item_name": "body_system",
                           "restricted": true,
                           "datatype": "text__v",
                           "length": 1500
                       },
                       {
                           "item_id": "V5700000002M021",
                           "item_name": "clinical_significance",
                           "restricted": true,
                           "datatype": "text__v"
                       },
                       {
                           "item_id": "V5700000002M020",
                           "item_name": "exam_date",
                           "restricted": true,
                           "datatype": "date__v"
                       },
                       {
                           "item_id": "V5700000002M019",
                           "item_name": "result",
                           "restricted": true,
                           "datatype": "text__v"
                       }
                   ]
               },
               {
                   "itemgroup_name": "physical_exam_general",
                   "itemgroup_sequence": 1,
                   "items": [
                       {
                           "item_id": "V5700000002M016",
                           "item_name": "DOB",
                           "restricted": true,
                           "datatype": "date__v"
                       },
                       {
                           "item_id": "V5700000002M013",
                           "item_name": "evaluator",
                           "restricted": true,
                           "datatype": "text__v",
                           "length": 1500
                       },
                       {
                           "item_id": "V5700000002M014",
                           "item_name": "exam_date",
                           "restricted": true,
                           "datatype": "date__v"
                       },
                       {
                           "item_id": "V5700000002M015",
                           "item_name": "exam_performed",
                           "restricted": true,
                           "datatype": "text__v"
                       }
                   ]
               }
           ]
       }
   ]
}

Retrieve high level Item Group and Item information for a particular form instance. This endpoint consists of basic definition information as well as Event IDs and Item IDs which users can use to open queries on a particular Event or Item. The only purpose of this endpoint is to provide the necessary data for opening queries on an Item or an Event.

In 24R3, the Get Forms API is not versioned, users must specify v23.2 to use this API.

Endpoint

GET https://{cdbDNS}/edcworkbench/api/{version}/forms/data

Required Permissions

• Workbench Tab Access
• API Access

The CDB API Read Write role grants these permissions.

Headers

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

Query Parameters

Parameter	Description
study_name	Study Name
source	Source Name (EDC or third-party source name)
site_number	Study Site Number
subject_name	Subject Name
form_name	Form Definition Name

Queries

v24.3 v26.1

Open Queries on Items

Request

curl -X POST  https://my-vault.veevavault.com/edcworkbench/api/v23.2/queries/item/open \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
{
  "study_name": "Deetoza_DEV1",
  "queries": [
    {
      "source": "EDC",
      "origin_sys": "mySystem",
      "origin_user": "Jane Smith",
      "origin_id": "00123456",
      "origin_name": "mySystemName",
      "site_number": "101",
      "subject_name": "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": "date_of_birth",
      "message": "This date does not match our records."
    }
  ]
}

Open a query on a particular Item in DQS Workbench.

This endpoint can support up to 500 queries in bulk and accepts two types of payload input: Item ID and full hierarchy. The latter type requires additional information to identify a particular item.

The Item ID is an identifier that specifies where to open the query.

Full hierarchy is to include all the necessary information in the EDC Study context to identify the target field (Items in our case). When we open queries for Items, the full hierarchy includes details such as, Study Name, Site, Subject, Event Group, Event, Form, Item Group, which help accurately identify the Item. In contrast, the "by ID" example payload requires less information and therefore is not considered a full hierarchy payload structure.

See Exporting Queries in Clinical Data Help for instructions on how to retrieve a query.

Endpoint

POST https://{cdbDNS}/edcworkbench/api/{version}/queries/item/open

Required Permissions

• Workbench Tab Access
• API Access
• Open Query

The CDB API Read Write role grants these permissions.

Headers

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

Body Parameters: Full Hierarchy

Parameter	Array	Description
study_name		Study Name
manual		Optional As of v24.3, users can no longer mark a query as manual. Any query opened through the CDB API will automatically have this setting set to false.
origin_id		Optional External origin system ID. This parameter can be set for each query inside the queries array. It is used when defining the ID of an external system used to open queries in CDB. It is visible in the EDC UI when the query is opened on EDC data.
origin_sys	queries	External originating system. This parameter is required and can be set for each query inside the queries array. It is used when defining the name of an external system used to open queries in CDB. It is visible in the EDC UI when the query is opened on EDC data.
origin_name	queries	Optional External origin system name. This parameter can be set for each query inside the queries array. It is used when defining the name of an external system (which can be an alternative to origin_sys) and to open queries in CDB.
origin_user	queries	Optional External origin system user. This is an optional field that can be set for each query and is visible in the EDC UI when the query is opened on EDC data. This field is limited to 100 characters.
source	queries	Source Name (for Vault EDC, enter “EDC”)
site_number	queries	Site Number
subject_name	queries	Subject Name (ID/number) to filter to. Must include site_number when using this.
eventgroup_name	queries	Event Group Definition Name
eventgroup_sequence	queries	Optional Event Group Sequence (for repeating Event Groups). The system defaults this value to 1 when you omit the parameter, pass an empty string (""), or provide null.
event_name	queries	Event Definition Name
form_name	queries	Item Definition Name
form_sequence	queries	Form Sequence (for repeating Forms). For non-repeating forms, enter "1".
itemgroup_name	queries	Item Group Definition Name
itemgroup_sequence	queries	Item Group Sequence (for repeating Item Groups). For non-repeating item groups, enter "1".
item_name	queries	Item Definition Name
message	queries	Query Message (limited to 500 characters)

Request

curl -X POST  https://my-vault.veevavault.com/edcworkbench/api/v23.2/queries/item/open \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
{
  "study_name": "Deetoza_DEV1",
  "queries": [
    {
      "source": "EDC",
      "origin_sys": "mySystem",
      "origin_user": "Jane Smith",
      "origin_id": "00123456",
      "origin_name": "mySystemName",
      "event_id": "OPS00000003Y002",
      "form_name": "F.DM",
      "itemgroup_name": "IG.DEMOG",
      "item_id": "OPV000000000641",
      "item_name": "date_of_birth",
      "message": "This date does not match our records."
    }
  ]
}

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "id": "19278e1d-2030-471d-8dc8-0794dea8a973",
            "query_name": "19278e1d-2030-471d-8dc8-0794dea8a973",
            "query_status": "open__v",
            "origin_sys": "mySystem",
            "origin_user": "Jane Smith",
            "origin_id": "00123456",
            "origin_name": "mySystemName",
            "last_modified_date": "2023-09-01 23:04:50.5",
            "first_message": {
                "id": "21abf993-17b5-4597-aaf7-b2f7cfb2d983",
                "message_status": "open__v",
                "message": "please check this lab result",
                "message_by": "API Account",
                "message_date": "2023-09-01 23:04:50.5",
                "message_origin_sys": "mySystem",
                "message_origin_user": "Jane Smith",
                "message_origin_id": "00123456"
            },
            "latest_message": {
                "id": "21abf993-17b5-4597-aaf7-b2f7cfb2d983",
                "message_status": "open__v",
                "message": "This date does not match our records.",
                "message_by": "API Account",
                "message_date": "2023-09-01 23:04:50.5",
                "message_origin_sys": "mySystem",
                "message_origin_user": "Jane Smith",
                "message_origin_id": "00123456"
            },
            "source": "EDC",
            "event_id": "OPS00000003Y002",
            "site_country": "USA",
            "site_number": "101",
            "subject_name": "101-001",
            "eventgroup_name": "EG.SCR",
            "eventgroup_sequence": 1,
            "event_name": "EV.SCR",
            "manual": false,
            "created_date": "2023-09-01 23:04:50.5",
            "created_by": "API Account",
            "form_name": "F.DM",
            "form_sequence": 1,
            "itemgroup_name": "IG.DEMOG",
            "itemgroup_sequence": 1,
            "item_id": "OPV000000000641",
            "item_name": "date_of_birth"
        }
    ]
}

Body Parameters: Item ID

Parameter	Array	Description
study_name		Study Name
manual		Optional As of v24.3, users can no longer mark a query as manual. Any query opened through the CDB API will automatically have this setting set to false.
origin_sys		External originating system. This parameter is required and can be set for each query inside the queries array.
origin_id		Optional External origin system ID. This parameter can be set for each query inside the queries array.
origin_name		Optional External origin system name. This parameter can be set for each query inside the queries array.
source	queries	Source Name (for Vault EDC, enter “EDC”)
event_id	queries	Event ID
form_name	queries	Form Definition Name
itemgroup_name	queries	Item Group Definition Name
item_id	queries	Item ID
item_name	queries	Item Definition Name
message	queries	Query Message (limited to 500 characters)

Open Queries on Events

Request

curl -X POST  https://my-vault.veevavault.com/edcworkbench/api/v23.2/queries/event/open \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "Deetoza_DEV1",
    "queries": [
      {
        "source": "EDC",
        "origin_sys": "mySystem",
        "origin_user": "Jane Smith",
        "origin_id": "00123456",
        "origin_name": "mySystemName",
        "site_number": "101",
        "subject_name": "101-001",
        "eventgroup_name": "EG.SCR",
        "eventgroup_sequence": 1,
        "event_name": "EV.SCR",
        "message": "This date does not match our records."
      }
    ]
   }  

Open a query on a particular Event in DQS Workbench. This endpoint can support up to 500 queries in bulk. It accepts two types of payload input: Event ID or full hierarchy. The latter type requires additional information to identify a particular Event. The Event ID is an identifier that specifies where to open the query. Full hierarchy means including all the necessary information in the EDC Study context to identify the target field (Events in our case). When we open queries for Events, the full hierarchy includes details such as, Study name, Site, Subject, Event group, Event, Form, Item group, and item information, which help accurately identify the Event. In contrast, the "by ID" example payload requires less information and therefore is not considered a full hierarchy payload structure.

Endpoint

POST https://{cdbDNS}/edcworkbench/api/{version}/queries/event/open

Required Permissions

• Workbench Tab Access
• API Access
• Open Query

The CDB API Read Write role grants these permissions.

Headers

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

Body Parameters: Full Hierarchy

Parameter	Array	Description
study_name		Study Name
manual		Optional As of v24.3, users can no longer mark a query as manual. Any query opened through the CDB API will automatically have this setting set to false.
origin_sys		External originating system. This parameter is required and can be set for each query inside the queries array. If manual equals false and this is not set, it will default to “CDB”, which is a protected keyword.
origin_id		Optional External origin system ID. This parameter can be set for each query inside the queries array.
origin_name		Optional External origin system name. This parameter can be set for each query inside the queries array.
origin_user		Optional External origin user’s name, the user who opened this query in the exernal system. This can be set for each query and is visible in the EDC UI when the query is opened on EDC data. This field is limited to 100 characters.
source	queries	Source Name (for Vault EDC, enter “EDC”)
site_number	queries	Site Number
subject_name	queries	Subject Name (ID/number) to filter to. Must include site_number when using this.
eventgroup_name	queries	Event Group Definition Name
eventgroup_sequence	queries	Optional Event Group Sequence (for repeating Event Groups). The system defaults this value to 1 when you omit the parameter, pass an empty string (""), or provide null.
event_name	queries	Event Definition Name
message	queries	Query Message (limited to 500 characters)

Request

curl -X POST  hhttps://my-vault.veevavault.com/edcworkbench/api/v23.2/queries/event/open \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "Deetoza_DEV1",
    "queries": [
      {
        "source": "eCOA",
        "origin_sys": "External System",
        "origin_user": "Jane Smith",
        "origin_id": "00123456",
        "origin_name": "mySystemName",
        "event_id": "OPS00000003Y002",
        "message": "Please check this event date."
      }
    ]
  }

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "id": "19278e1d-2030-471d-8dc8-0794dea8a973",
            "query_name": "19278e1d-2030-471d-8dc8-0794dea8a973",
            "query_status": "open__v",
            "origin_sys": "mySystem",
            "origin_user": "Jane Smith",
            "origin_id": "00123456",
            "origin_name": "mySystemName",
            "last_modified_date": "2023-09-01 23:04:50.5",
            "first_message": {
                "id": "21abf993-17b5-4597-aaf7-b2f7cfb2d983",
                "message_status": "open__v",
                "message": "please check this event date",
                "message_by": "API Account",
                "message_date": "2023-09-01 23:04:50.5",
                "message_origin_sys": "mySystem",
                "message_origin_user": "Jane Smith",
                "message_origin_id": "00123456"
            },
            "latest_message": {
                "id": "21abf993-17b5-4597-aaf7-b2f7cfb2d983",
                "message_status": "open__v",
                "message": "This date does not match our records.",
                "message_by": "API Account",
                "message_date": "2023-09-01 23:04:50.5",
                "message_origin_sys": "mySystem",
                "message_origin_user": "Jane Smith",
                "message_origin_id": "00123456"
            },
            "source": "EDC",
            "event_id": "OPS00000003Y002",
            "site_country": "USA",
            "site_number": "101",
            "subject_name": "101-001",
            "eventgroup_name": "EG.SCR",
            "eventgroup_sequence": 1,
            "event_name": "EV.SCR",
            "manual": false,
            "created_date": "2023-09-01 23:04:50.5",
            "created_by": "API Account",
            "form_name": "F.DM",
            "form_sequence": 1,
            "itemgroup_name": "IG.DEMOG",
            "itemgroup_sequence": 1,
            "item_id": "OPV000000000641",
            "item_name": "date_of_birth"
        }
    ]
}

Body Parameters: Event ID

Parameter	Array	Description
study_name		Study Name
manual		Optional As of v24.3, users can no longer mark a query as manual. Any query opened through the CDB API will automatically have this setting set to false.
origin_sys		External originating system. This parameter is required and can be set for each query inside the queries array. If manual equals false and this is not set, it will default to “CDB”, which is a protected keyword.
origin_id		Optional External origin system ID. This parameter can be set for each query inside the queries array.
origin_name		Optional External origin system name. This parameter can be set for each query inside the queries array.
source	queries	Source Name (for Vault EDC, enter “EDC”)
event_id	queries	Event ID
message	queries	Query Message (limited to 500 characters)

Retrieve Queries

Request

curl -L -X GET 'https://my-vault.veevavault.com/edcworkbench/api/v26.1/queries?study_name=Supera&source=EDC' \
-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,
        "next_page": "/api/v26.1/queries?resource_locator=4db7ac7f-aa08-486a-99e1-9acb5cdda80e&limit=1000&offset=1000",
        "resource_locator": "4db7ac7f-aa08-486a-99e1-9acb5cdda80e"
    },
    "queries": [
            {
                "source": "EDC",
                "id": "OPW000000004001",
                "query_name": "VV-000008",
                "rowexternalid": null,
                "manual": false,
                "query_status": "open__v",
                "site_country": "Japan",
                "site_number": "101",
                "subject_name": "SCR-0001",
                "eventgroup_name": "TRT",
                "eventgroup_sequence": 1,
                "event_id": "OPS00000000C001",
                "event_name": "WEEK1",
                "event_sequence": 1,
                "form_name": "labs",
                "form_sequence": 1,
                "itemgroup_name": "LBCHEM",
                "itemgroup_sequence": 1,
                "item_id": "V5500000000F036", 
                "item_name": "LBORRES_Test_Analyte",
                "rule_definition": null, 
                "created_date": "2024-10-03T19:53:37Z",
                "created_by": "System",
                "origin_sys": null,
                "origin_user": null,
                "origin_id": null,
                "origin_name": null,
                "messages": [
                    {
                        "id": "OPY000000004001",
                        "message_status": "open__v",
                        "message": "The lab result value is abnormal. Please review.",
                        "message_date": "2024-10-03T19:53:38Z",
                        "message_by": "System",
                        "message_origin_sys": null,
                        "message_origin_user": null,
                        "message_origin_id": null
                    }
                ]
            }
        ]
}

Retrieve query details for small batches of queries based on the query ID or select parameters.

Endpoint

GET https://{cdbDNS}/edcworkbench/api/v26.1/queries

Required Permissions

• Workbench Tab Access
• API Access
• View Query

The CDB API Read Write role grants these permissions.

Headers

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

Query Parameters

Parameter	Description
study_name	Study Name
source	Source Name. If query_status, site_country, site_number, subject_name, form_name, origin_sys, or id are provided, this becomes optional.
query_status	Optional Query Status of the original query (not the query messages).
site_country	Optional Uses the three-character ISO code. For example, "USA".
site_number	Optional The Name field on the site object. This becomes required if using subject_name in the request.
subject_name	Optional Returns the subject's queries across all statuses and sources. This must be used in conjunction with the site_number parameter.
form_name	Optional Specifies the Form Definition Name.
origin_sys	Optional Specifies the origin_sys of the original query (not the query message).
id	Optional Provides a comma separated list of query IDs (strings). Other filters are ignored when using this filter.
limit	Optional The maximum number of records to return. Defaults to 1000.
offset	Optional The number of the first record from the collection to include in the results. Defaults to zero (0).

Response Details

Array	Parameter	Description
queries	source	Query Source Name
queries	id	Query ID
queries	query_name	Query Name
queries	rowexternalid	Row External ID (for DQS only)
queries	manual	Query Manual Status (boolean, true or false)
queries	query_status	Query Status
queries	site_country	Site Country
queries	site_number	Site Number
queries	subject_name	Subject Name
queries	eventgroup_name	Event Group Definition Name
queries	eventgroup_sequence	Event Group Sequence
queries	event_id	Event ID
queries	event_name	Event Definition Name
queries	event_sequence	Event Sequence
queries	form_name	Form Definition Name
queries	form_sequence	Form Sequence
queries	itemgroup_name	Item Group Definition Name
queries	itemgroup_sequence	Item Group Sequence
queries	item_id	Item ID
queries	item_name	Item Definition Name
queries	rule_definition	If the query was created by a Studio rule, this is the rule definition name.
queries	created_date	Query Created Datetime with the following format: YYYY-MM-DDTHH:mm:ssZ
queries	created_by	Query Created By Username
queries	origin_sys	Origination System
queries	origin_user	Origination User
queries	origin_id	Origination ID
queries	origin_name	Origination Name (used by DQS only)
messages	id	Query Message ID
messages	message_status	Query Message Status
messages	message	Query Message
messages	message_date	Query Message Created Datetime with the following format: YYYY-MM-DDTHH:mm:ssZ
messages	message_by	Query Message By Username
messages	message_origin_sys	Query Message Origination System
messages	message_origin_user	Query Message Origination User
messages	message_origin_id	Query Message Origination ID

Answer Queries

Request

curl -X POST  https://my-vault.veevavault.com/edcworkbench/api/v23.2/queries/answer \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "Deetoza_DEV1",
    "queries": [
      {
        "id": "OPW00000003Y019",
        "message": "Replying to query.",
        "message_origin_sys": "MySystem",
        "message_origin_user": "Jane Smith",
        "message_origin_id": "123456"
      }
    ]
   }

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "id": "OPW00000003Y019",
            "query_name": "VV-000348",
            "query_status": "answered__v",
            "origin_sys": "CDB",
            "origin_id": "b0972985-291c-44a9-9856-714e5b5cae8d",
            "origin_name": "physical_exam",
            "last_modified_date": "2024-03-14 02:41:09.0",
            "first_message": {
                "id": "OPY00000004U019",
                "message_status": "open__v",
                "message": "please check this value.",
                "message_by": "Jane Smith",
                "message_date": "2024-03-14 02:40:25.0",
                "message_origin_sys": "CDB",
                "message_origin_user": "Jane Smith",
                "message_origin_id": "b0972985-291c-44a9-9856-714e5b5cae8d6"
            },
            "latest_message": {
                "id": "OPY00000004U020",
                "message_status": "answered__v",
                "message": "Replying to query.",
                "message_by": "Jane Smith",
                "message_date": "2024-03-14 02:41:09.0",
                "message_origin_sys": "MySystem",
                "message_origin_user": "Jane Smith",
                "message_origin_id": "123456"
            }
        }
    ]
}

Answer a query in DQS Workbench. This endpoint can support up to 500 queries in bulk and accepts one type of payload: Query ID. If you don't have access to the Query ID, you can obtain it by downloading the Query Listings from the DQS Workbench UI.

See Exporting Queries and DQS Exports in Clinical Data Help for more details.

Endpoint

POST https://{cdbDNS}/edcworkbench/api/{version}/queries/answer

Required Permissions

• Workbench Tab Access
• API Access
• Answer Query (to answer EDC queries)
• Answer 3rd Party Queries (to answer third-party queries)

The CDB API Read Write role grants these permissions.

Headers

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

Body Parameters

Parameter	Array	Description
study_name		Study Name
id	queries	Query ID
message	queries	Query Message (limited to 500 characters)
message_origin_sys		Optional The external originating system of the query message. This cannot equal "CDB" and is case insensitive.
message_origin_user		Optional The external origin user of the query message.
message_origin_id		Optional The external origin ID of the query message.

When a query is answered with any of these parameters populated, the system stamps the origination_type as external_v. If no fields are specified, the value is set to NULL and no default is applied. These parameters can be seen in the EDC UI if opened on EDC data.

Close Queries

Request

curl -X POST  https://my-vault.veevavault.com/edcworkbench/api/v23.2/queries/close \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "Deetoza_DEV1",
    "queries": [
        {
            "id": "OPW00000003Y019",
            "message": "Closing query.",
            "message_origin_sys": "MySystem",
            "message_origin_user": "Jane Smith",
            "message_origin_id": "123456"
        }
    ]
  }

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "id": "OPW00000003Y019",
            "query_name": "VV-000348",
            "query_status": "closed__v",
            "origin_sys": "CDB",
            "origin_id": "b0972985-291c-44a9-9856-714e5b5cae8d",
            "origin_name": "physical_exam",
            "last_modified_date": "2024-03-14 02:41:09.0",
            "first_message": {
                "id": "OPY00000004U019",
                "message_status": "open__v",
                "message": "please check this value.",
                "message_by": "Jane Smith",
                "message_date": "2024-03-14 02:40:25.0",
               "message_origin_sys": "CDB",                                
                "message_origin_user": "Jane Smith",                        
                "message_origin_id": "b0972985-291c-44a9-9856-714e5b5cae8d6"   
            },
            "latest_message": {
                "id": "OPY00000004U020",
                "message_status": "closed__v",
                "message": "Closing query.",
                "message_by": "Jane Smith",
                "message_date": "2024-03-17 12:30:00.0",
               "message_origin_sys": "MySystem",      
                "message_origin_user": "Jane Smith",        
                "message_origin_id": "123456"             
            }
        }
    ]
}

Close a query in DQS Workbench. This endpoint can support up to 500 queries in bulk and accepts one type of payload: Query ID. If you don't have access to the Query ID, you can obtain it by downloading the Query Listings from the DQS Workbench UI.

See Exporting Queries and DQS Exports in Clinical Data Help for more details.

Endpoint

POST https://{cdbDNS}/edcworkbench/api/{version}/queries/close

Required Permissions

• Workbench Tab Access
• API Access
• Close Query
• Close All Queries (if the Study is using Query Teams)

The CDB API Read Write role grants these permissions.

Headers

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

Body Parameters

Parameter	Array	Description
study_name		Study Name
id	queries	Query ID
message	queries	Query Message (limited to 500 characters)
message_origin_sys		Optional The external originating system of the query message. This cannot equal "CDB" and is case insensitive.
message_origin_user		Optional The external origin user of the query message.
message_origin_id		Optional The external origin ID of the query message.

When a query is closed with any of these parameters populated, the system stamps the origination_type as external_v. If no fields are specified, the value is set to NULL and no default is applied. These parameters can be seen in the EDC UI if opened on EDC data.

Listings

v26.3

Retrieve Listing Definitions

Request

curl -L -X GET 'https://myvaultdev.com/api/v26.3/dqs/listings?study_name=Deetoza&type=metric' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
  "responseStatus": "SUCCESS",
  "responseDetails": {
    "limit": 2,
    "offset": 0,
    "size": 2,
    "total": 2,
    "next_page": null,
    "resource_locator": "4db7ac7f-aa08-486a-99e1-9acb5cdda80e"
  },
  "data": {
    "listings": [
      {
        "name": "MyMetricListing",
        "id": "7f6eab36-c72b-4004-8551-9b65f9e55e34",
        "type": "metric",
        "definition": {
          "level": {
            "name": "Site",
            "column_name": "Site"
          },
          "metric_type": "KRI",
          "formula_name": "BINARY_RATE",
          "x_column_name": "Temp",
          "y_column_name": "Pulse",
          "upper_threshold_red": null,
          "lower_threshold_red": 0.05,
          "upper_threshold_yellow": null,
          "lower_threshold_yellow": 0.10
        },
        "sources": [
          "EDC"
        ],
        "objective": "myObjective",
        "description": "Metric for measurements",
        "review_enabled": false,
        "created_by": "Jane Doe",
        "created_date": "2026-10-11T22:10:50Z",
        "last_modified_by": "Jane Doe",
        "last_modified_date": "2026-10-11T22:10:50Z",
        "status": "DRAFT",
        "last_approved_by": null,
        "last_approved_date": null,
        "last_deployed_by": null,
        "last_deployed_date": null,
        "listing_builder_compatible": false
      }
    ]
  }
}

Retrieve an array of listing definitions by study_name.

The Retrieve Listing Definitions endpoint allows you to retrieve and filter listing definitions by type and status. For example, to retrieve all available metric listings specify the type as metric or to retrieve all listings in a Draft workflow status, specify the status as DRAFT. CTMS calls this endpoint whenever a user opens the metric configuration dialog in CTMS to retrieve the latest definitions.

Endpoint

GET https://{vaultDNS}/api/v26.3/dqs/listings

Required Permissions

To use this endpoint, you must have the following permissions and access to the relevant Study:

• Workbench Tab (for DQS studies)
• Clinical Reporting Tab (for Clinical Reporting studies)
• API Access

The CDB API Read Write role grants these permissions.

Required Permissions by Listing Type

Depending on the types of listings being retrieved, you must possess one or more of the following permissions:

• View All Listings: Grants users access to view Core Listings, Custom Listings, Check Listings, Report Listings, and standard System Listings.
• View Selected Listings: Serves as an alternative to View All Listings for viewing Core Listings, Custom Listings, and Check Listings.
• Browse Views: Enables users to view listings of the View type.
• View Observation: Allows users to view Observation System Listings (SYS_OBS and SYS_OBSMSG). Users must have this permission in addition to View All Listings.
• View Protocol Deviations: Allows users to view Protocol Deviation System Listings (SYS_PD). Users must have this permission in addition to View All Listings.
• View All CDB Query Listings: Allows users to view Query System Listings (SYS_QRY and SYS_QRYMSG). Users must have this permission in addition to View All Listings.
• Restricted Data Access: Allows users to view restricted data or Review Listings configured to show restricted data. Users with Restricted Data Access can view metric listing definitions and download all associated packages. Users without Restricted Data Access can view metric listing definitions and see associated packages, but cannot download packages, generate CSVs in the UI for restricted metrics, or export package data through DQS exports.

Headers

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

Response Parameters

Parameter	Description
study_name	Specifies the study name.
type	Optional Filters the results by listing type. Valid options include metric, custom, core, view, check, system, and report.
status	Optional Filters the results by workflow status. Valid options include DRAFT, READY, and APPROVED.
limit	Optional Sets the maximum number of records to return. Defaults to 1000.
offset	Optional Sets the number of records to skip. Defaults to zero (0).

Response Details

Array	Parameter	Description
listings	name	Displays the name of the listing.
listings	id	Displays the listing ID.
listings	type	Indicates the listing type.
listings	definition	Provides the listing definition.
listings	sources	Provides an array containing the source system names.
listings	objective	Describes the objective of the listing.
listings	description	Provides the listing description.
listings	review_enabled	Indicates whether the system enables reviews for the listing (true or false).
listings	created_by	Displays the username of the user who created the listing.
listings	created_date	Displays the creation timestamp formatted as YYYY-MM-DDTHH:mm:ssZ.
listings	last_modified_by	Displays the username of the user who last modified the listing.
listings	last_modified_date	Displays the timestamp of the last modification formatted as YYYY-MM-DDTHH:mm:ssZ.
listings	status	Indicates the current workflow status of the listing.
listings	last_approved_by	Displays the username of the user who last approved the listing.
listings	last_approved_date	Displays the timestamp of the last approval formatted as YYYY-MM-DDTHH:mm:ssZ.
listings	last_deployed_by	Displays the username of the user who last deployed the listing.
listings	last_deployed_date	Displays the timestamp of the last deployment formatted as YYYY-MM-DDTHH:mm:ssZ.
listings	listing_builder_compatible	Indicates whether the listing supports listing builder compatibility (true or false).

Search Listing Definitions by ID

Request

curl -L -X POST '[https://myvaultdev.com/api/v26.3/dqs/listings/search](https://myvaultdev.com/api/v26.3/dqs/listings/search)' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
  "study_name": "Deetoza",
  "ids": [
    "7f6eab36-c72b-4004-8551-9b65f9e55e34",
    "b01bb5fe-a3bf-48ca-bc3a-198aa6d9dbac"
  ]
}'

Response

{
  "responseStatus": "SUCCESS",
  "responseDetails": {
    "offset": 0,
    "limit": 1000,
    "size": 2,
    "total": 2
  },
  "data": {
    "listings": [
      {
        "name": "MyMetricListing",
        "id": "7f6eab36-c72b-4004-8551-9b65f9e55e34",
        "type": "metric",
        "definition": {
          "level": {
            "name": "Site",
            "column_name": "Site"
          },
          "metric_type": "KRI",
          "formula_name": "BINARY_RATE",
          "x_column_name": "Temp",
          "y_column_name": "Pulse",
          "upper_threshold_red": null,
          "lower_threshold_red": 0.05,
          "upper_threshold_yellow": null,
          "lower_threshold_yellow": 0.10
        },
        "sources": [
          "EDC"
        ],
        "objective": "myObjective",
        "description": "Metric for measurements",
        "review_enabled": false,
        "created_by": "Jane Doe",
        "created_date": "2026-10-11T22:10:50Z",
        "last_modified_by": "Jane Doe",
        "last_modified_date": "2026-10-11T22:10:50Z",
        "status": "DRAFT",
        "last_approved_by": null,
        "last_approved_date": null,
        "last_deployed_by": null,
        "last_deployed_date": null,
        "listing_builder_compatible": false
      },
      {
        "name": "MyCustomReviewListing",
        "id": "b01bb5fe-a3bf-48ca-bc3a-198aa6d9dbac",
        "type": "custom",
        "definition": null,
        "sources": [
          "EDC",
          "LabData"
        ],
        "objective": null,
        "description": "custom listing description",
        "review_enabled": true,
        "created_by": "Jane Doe",
        "created_date": "2026-11-11T22:00:00Z",
        "last_modified_by": "Jane Doe",
        "last_modified_date": "2026-11-12T12:10:15Z",
        "status": "DRAFT",
        "last_approved_by": null,
        "last_approved_date": null,
        "last_deployed_by": null,
        "last_deployed_date": null,
        "listing_builder_compatible": false
      }
    ]
  }
}

Search listing definitions by study_name.

The Search Listing Definitions by ID endpoint allows you to retrieve listing definitions for specific listing IDs.

Endpoint

POST https://{vaultDNS}/api/v26.3/dqs/listings/search

Required Permissions

To use this endpoint, you must have the following permissions and access to the relevant Study:

• Workbench Tab (for DQS studies)
• Clinical Reporting Tab (for Clinical Reporting studies)
• API Access

The CDB API Read Write role grants these permissions.

Required Permissions by Listing Type

Depending on the types of listings being used in your search, you must possess one or more of the following permissions:

• View All Listings: Grants users access to view Core Listings, Custom Listings, Check Listings, Report Listings, and standard System Listings.
• View Selected Listings: Serves as an alternative to View All Listings for viewing Core Listings, Custom Listings, and Check Listings.
• Browse Views: Enables users to view listings of the View type.
• View Observation: Allows users to view Observation System Listings (SYS_OBS and SYS_OBSMSG). Users must have this permission in addition to View All Listings.
• View Protocol Deviations: Allows users to view Protocol Deviation System Listings (SYS_PD). Users must have this permission in addition to View All Listings.
• View All CDB Query Listings: Allows users to view Query System Listings (SYS_QRY and SYS_QRYMSG). Users must have this permission in addition to View All Listings.
• Restricted Data Access: Allows users to view restricted data or Review Listings configured to show restricted data. Users without Restricted Data Access can view metric listing definitions and listing metadata, but cannot view restricted data fields.

Headers

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

Request Parameters

Parameter	Description
study_name	Specifies the study name.
ids	Specifies an array of target listing IDs.

Response Details

Array	Parameter	Description
listings	name	Displays the name of the listing.
listings	id	Displays the listing ID.
listings	type	Indicates the listing type.
listings	definition	Provides the listing definition.
listings	sources	Provides an array containing the source system names.
listings	objective	Describes the objective of the listing.
listings	description	Provides the listing description.
listings	review_enabled	Indicates whether the system enables reviews for the listing (true or false).
listings	created_by	Displays the username of the user who created the listing.
listings	created_date	Displays the creation timestamp formatted as YYYY-MM-DDTHH:mm:ssZ.
listings	last_modified_by	Displays the username of the user who last modified the listing.
listings	last_modified_date	Displays the timestamp of the last modification formatted as YYYY-MM-DDTHH:mm:ssZ.
listings	status	Indicates the current workflow status of the listing.
listings	last_approved_by	Displays the username of the user who last approved the listing.
listings	last_approved_date	Displays the timestamp of the last approval formatted as YYYY-MM-DDTHH:mm:ssZ.
listings	last_deployed_by	Displays the username of the user who last deployed the listing.
listings	last_deployed_date	Displays the timestamp of the last deployment formatted as YYYY-MM-DDTHH:mm:ssZ.
listings	listing_builder_compatible	Indicates whether the listing supports listing builder compatibility (true or false).

Search Listing Packages

Request

curl -L -X POST 'https://myvaultdev.com/api/v26.3/dqs/listing-packages/search' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
  "study_name": "Deetoza",
  "ids": [
    "7f6eab36-c72b-4004-8551-9b65f9e55e34"
  ],
  "limit": 10,
  "offset": 0
}'

Response

{
  "responseStatus": "SUCCESS",
  "responseDetails": {
    "limit": 10,
    "offset": 0,
    "size": 1,
    "total": 1,
    "resource_locator": "4db7ac7f-aa08-486a-99e1-9acb5cdda80e"
  },
  "data": {
    "listings": [
      {
        "name": "MyMetricListing",
        "id": "7f6eab36-c72b-4004-8551-9b65f9e55e34",
        "last_modified_date": "2026-10-11T22:10:50Z",
        "packages": [
          {
            "name": "3d5880ef-b497-4c76-8656-6aca6760c968",
            "filename": "3d5880ef-b497-4c76-8656-6aca6760c968.zip",
            "last_refreshed_date": "2026-11-15T14:00:00Z",
            "restricted": true,
            "url": "/api/v26.3/dqs/listing-packages/3d5880ef-b497-4c76-8656-6aca6760c968/file?study_name=Deetoza"
          }
        ]
      }
    ]
  }
}

Search listing packages.

The Search Listing Packages endpoint allows you to retrieve data packages of specific listings by listing ID and study_name. In v26.3, DQS will only support Metric packages.

Endpoint

POST https://{vaultDNS}/api/v26.3/dqs/listings/search

Required Permissions

To use this endpoint, you must have the following permissions and access to the relevant Study:

• Workbench Tab (for DQS studies)
• Clinical Reporting Tab (for Clinical Reporting studies)
• API Access

The CDB API Read Write role grants these permissions.

Required Permissions by Listing Type

Depending on the types of listings being used in your search, you must possess one or more of the following permissions:

• View All Listings: Grants users access to view Core Listings, Custom Listings, Check Listings, Report Listings, and standard System Listings.
• View Selected Listings: Serves as an alternative to View All Listings for viewing Core Listings, Custom Listings, and Check Listings.
• Browse Views: Enables users to view listings of the View type.
• View Observation: Allows users to view Observation System Listings (SYS_OBS and SYS_OBSMSG). Users must have this permission in addition to View All Listings.
• View Protocol Deviations: Allows users to view Protocol Deviation System Listings (SYS_PD). Users must have this permission in addition to View All Listings.
• View All CDB Query Listings: Allows users to view Query System Listings (SYS_QRY and SYS_QRYMSG). Users must have this permission in addition to View All Listings.
• Restricted Data Access: Allows users to view restricted data or Review Listings configured to show restricted data. Users with Restricted Data Access view metric listing definitions and download all associated packages. Users without Restricted Data Access view metric listing definitions and see associated packages, but cannot download packages, generate CSVs in the UI for restricted metrics, or export package data through DQS exports.

Headers

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

Request Parameters

Parameter	Description
ids	Specifies an array of listing IDs to retrieve packages for.
study_name	Specifies the study name.
last_refreshed_date_start	OptionalFilters packages refreshed on or after the specified UTC datetime formatted as YYYY-MM-DDTHH:mm:ssZ.
last_refreshed_date_stop	OptionalFilters packages refreshed before the specified UTC datetime formatted as YYYY-MM-DDTHH:mm:ssZ.
latest	OptionalIndicates whether to return only the most recent package (true or false).
limit	OptionalSpecifies the maximum number of records to return. Defaults to 1000.
offset	OptionalSpecifies the number of records to skip. Defaults to 0.

Response Details

Array	Parameter	Description
listings	name	Displays the listing definition name.
listings	id	Displays the listing definition ID.
listings	last_modified_date	Displays the timestamp of the last modification formatted as YYYY-MM-DDTHH:mm:ssZ.
packages	name	Displays the listing package name.
packages	filename	Displays the filename of the package zip file.
packages	last_refreshed_date	Displays the timestamp of the last refresh formatted as YYYY-MM-DDTHH:mm:ssZ.
packages	restricted	Indicates whether the package contains restricted data (true or false).
packages	url	Provides the relative download URL for the package file.

Download Listing Packages

Request

curl -L -X GET 'https://myvaultdev.com/api/v26.3/dqs/listing-packages/3d5880ef-b497-4c76-8656-6aca6760c968/file?study_name=Deetoza' \
-H 'Accept: application/zip' \
-H 'Authorization: {SESSION_ID}'

Response - Successful Download

HTTP/1.1 200 OK
Date: Thu, 09 Jul 2026 17:14:26 GMT
Content-Type: application/zip
Content-Disposition: attachment; filename="3d5880ef-b497-4c76-8656-6aca6760c968.zip"
Content-Length: 10485760
X-Transaction-Id: 001d2188-df68-4e3d-a578-7a1e4d7d1897
X-Transfer-Message: Successfully transferred file

[Binary ZIP File Stream]

Response - Unsuccessful Download

{
  "responseMessage": null,
  "responseStatus": "EXCEPTION",
  "payload": {
    "guid": "1f27d05e-5a95-46a5-a5b3-5fcaad70b4e0",
    "errors": [
      "Resource not found."
    ]
  }
}

Download a listing package file by study_name.

The Download Listing Package endpoint streams the data package of a specified package ID (name) as a ZIP file. For v26.3, this endpoint only supports Metric packages. If the download fails, DQS generates a response.json file that contains the error details within the JSON payload.

User Workflow

The following is a suggested user workflow for retrieving listing definitions and downloading packages:

1. Call the Retrieve Listing API to view the list of available listing definitions and obtain specific listing IDs.
2. Call the Search Listing Packages API to search for stored metric outcome packages associated with specific listing IDs.
3. Call the Download Listing Package API using the target package ID (name) to stream the outcome package zip file.

Endpoint

GET https://{vaultDNS}/api/v26.3/dqs/listing-packages/{name}/file

Required Permissions

To use this endpoint, you must have the following permissions and access to the relevant Study:

• Workbench Tab (for DQS studies)
• Clinical Reporting Tab (for Clinical Reporting studies)
• API Access

The CDB API Read Write role grants these permissions.

Required Permissions by Listing Type

Depending on the types of listings you download, you must possess one or more of the following permissions:

• View All Listings: Grants users access to view Core Listings, Custom Listings, Check Listings, Report Listings, and standard System Listings.
• View Selected Listings: Serves as an alternative to View All Listings for viewing Core Listings, Custom Listings, and Check Listings.
• Browse Views: Enables users to view listings of the View type.
• View Observation: Allows users to view Observation System Listings (SYS_OBS and SYS_OBSMSG). Users must have this permission in addition to View All Listings.
• View Protocol Deviations: Allows users to view Protocol Deviation System Listings (SYS_PD). Users must have this permission in addition to View All Listings.
• View All CDB Query Listings: Allows users to view Query System Listings (SYS_QRY and SYS_QRYMSG). Users must have this permission in addition to View All Listings.
• Restricted Data Access: Allows users to view restricted data or Review Listings configured to show restricted data. Users with Restricted Data Access view metric listing definitions and download all associated packages. Users without Restricted Data Access view metric listing definitions and see associated packages, but cannot download packages, generate CSVs in the UI for restricted metrics, or export package data through DQS exports.

Headers

Header	Description
Accept	application/zip (default) or application/json

Path Parameters

Parameter	Description
name	Specifies the unique package name returned.

Request Parameters

Parameter	Description
study_name	Specifies the study name.

Response Details

Header	Description
Content-Type	Returns application/zip for successful downloads, or application/json if an error occurs.
Content-Disposition	Specifies the download attachment filename (for example, filename="{package_id}.zip").
X-Transaction-Id	Displays the unique transaction ID generated for tracking the download session.
X-Transfer-Message	Provides a transfer status message (for example, Successfully transferred file).

Observations

Before generating a query, discrepancies must be reviewed by the data management team or discussed across various teams. Observations allow data managers to collaborate with colleagues before generating queries.

Retrieve Observations

Request

curl -X POST  https://my-vault.veevavault.com/dqs/api/v26.3/observations/search \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '
  {
    "study_name": "Supera",
    "limit": 2,
    "offset": 0
  }
'

Response

{
    "responseStatus": "SUCCESS",
    "responseDetails":
    {
        "limit": 2,
        "offset": 0,
        "size": 2,
        "total": 2,
        "next_page": "/api/v26.3/observations?study_name=<study_name>&resource_locator=4db7ac7f-aa08-486a-99e1-9acb5cdda80e&limit=2&offset=1000",
        "resource_locator": "4db7ac7f-aa08-486a-99e1-9acb5cdda80e"
    },
    "data": {
        "observations": [{
            "study_name": "Supera",
            "id": "ba303bfe-a1df-4122-bdf1-1fb8deae8f07",
            "source": "EDC",
            "obs_id": "OBS-000001",
            "category": "Mismatch",
            "assigned_user": "Sarah Jones",
            "assigned_user_id": "41234551",
            "external_id": null,
            "event_id": "OPS000000002004",
            "event_name": "Visit1",
            "form_name": null,
            "itemgroup_name": null,
            "item_id": null,
            "item_name": null,
            "restricted": true,
            "origin_sys": "CDB",
            "origin_id": "8e2d8cbb-52eb-4f1d-a8a0-3cd3f88aef16",
            "origin_name": "Lab_data",
            "created_date": "2024-09-10T18:43:22Z",
            "created_by": "Jim Jones",
            "messages": [
                {
                    "id": "04985f63-a0b2-4f7e-bd8a-479e4e85bf3f",
                    "message": "Date does not align with the visit schedule",
                    "message_status": "Open",
                    "message_assigned_user": "Sarah Jones",
                    "message_assigned_user_id": "41234551",
                    "message_team__v": "data_management",
                    "message_assigned_team__v": "data_management",
                    "message_date": "2026-07-13T16:08:30Z",
                    "message_by": "Thomas James"
                }
            ]
        }]
    }
}

Retrieve Observation details for small batches of Observations based on the Observation ID or select parameters.

Endpoint

POST https://{{cdbDNS}}/dqs/api/{{version}}/observations/search

Required Permissions

• API Access
• View Observations

The CDB API Read Write and CDB API Read Only study roles grant these permissions.

Headers

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

Body Parameters

Parameter	Description
study_name	Study Name
ids	Optional Provide a comma separated list of observation IDs (strings).
limit	Optional Specifies the maximum number of records to return. Defaults to 1000.
offset	Optional Specifies the number of records to skip. Defaults to 0.

Create Observation by Event ID

Request

curl -X POST  https://my-vault.veevavault.com/dqs/api/v26.3/observations/event/open \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '
  {
    "study_name": "Supera",
    "observations": {
      "event_id": "OPS00000001M006",
      "category": "Mismatch",
      "source": "mySystem",
      "origin_sys": "mySystem",
      "origin_id": "00123456",
      "origin_name": "mySystemName",
      "message": "Visit date does not match the specimen collected date"
    }
  }
'

Response

{
  "responseStatus": "SUCCESS",
    "data": {    
        "observations": [{
            "responseStatus": "SUCCESS",
            "id": "V6X000000001001",
            "obs_name": "OBS-000045"
        }]
    }
}

Create an Observation by specifying the Event ID.

Endpoint

POST https://{{cdbDNS}}/dqs/api/{{version}}/observations/event/open

Required Permissions

• API Access
• View Observations
• Create Observations

The CDB API Read Write study role grants these permissions.

Headers

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

Body Parameters

Parameter	Array	Description
study_name		Study Name
event_id	observations	The Event ID for the Event
category	observations	The Category that you want to assign the Observation
source	observations	Source Name (for Vault EDC, enter “EDC”)
origin_sys	observations	Optional The external originating system of the observation message. This cannot equal "CDB" and is case insensitive.
origin_name	observations	Optional The external origin system name of the observation message.
origin_id	observations	Optional The external origin ID of the observation message.
assigned_user	observations	Optional The Vault User ID (integer) to assign the observation to. Note that you can only provide assigned_user or assigned_team, not both.
assigned_team	observations	Optional The Team to assign the observation to. Note that you can only provide assigned_user or assigned_team, not both.
team	observations	Optional This corresponds to the Team that creates the observations. The only allowed value is "cdmw_application_role_team_sys".
message	observations	Enter the observation message text.

Create Observation by Item

Request

curl -X POST  https://my-vault.veevavault.com/dqs/api/v26.3/observations/item/open \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '
{
  "study_name": "Supera",
  "observations": [
    {
      "source": "EDC",
      "site_number": "101",
      "subject_name": "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": "date_of_birth",
      "category": "Mismatch",
      "origin_sys": "mySystem",
      "origin_id": "00123456",
      "origin_name": "mySystemName",
      "message": "This birthdate does not match the birthdate recorded on the informed consent."
    }
  ]
}
'

Response

{
  "responseStatus": "SUCCESS",
    "data": {    
      "observations": [{
            "responseStatus": "SUCCESS",
            "id": "V6X000000001001",
            "obs_name": "OBS-000047"
        }]
    }
}

Create an Observation by identifying the target Item.

Endpoint

POST https://{{cdbDNS}}/dqs/api/{{version}}/observations/item/open

Required Permissions

• API Access
• View Observations
• Create Observations

The CDB API Read Write study role grants these permissions.

Headers

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

Body Parameters

Parameter	Array	Description
study_name		Study Name
category	observations	The Category that you want to assign the Observation
source	observations	Source Name (for Vault EDC, enter “EDC”)
site_number	observations	Site Number
subject_name	observations	Subject Name (ID/number) to filter to. Must include site_number when using this.
eventgroup_name	observations	Event Group Definition Name
eventgroup_sequence	observations	Optional Event Group Sequence (for repeating Event Groups). The system defaults this value to 1 when you omit the parameter, pass an empty string (""), or provide null.
event_name	observations	Event Definition Name
form_name	observations	Form Definition Name
form_sequence	observations	Form Sequence (for repeating Forms). For non-repeating forms, enter "1".
itemgroup_name	observations	Item Group Definition Name
itemgroup_sequence	observations	Item Group Sequence (for repeating Item Groups). For non-repeating item groups, enter "1".
item_name	observations	Item Definition Name
origin_sys	observations	Optional The external originating system of the observation message. This cannot equal "CDB" and is case insensitive.
origin_name	observations	Optional The external origin system name of the observation message.
origin_id	observations	Optional The external origin ID of the observation message.
assigned_user	observations	Optional The Vault User ID (integer) to assign the observation to. Note that you can only provide assigned_user or assigned_team, not both.
assigned_team	observations	Optional The Team to assign the observation to. Note that you can only provide assigned_user or assigned_team, not both.
team	observations	Optional This corresponds to the Team that creates the observations. The only allowed value is "cdmw_application_role_team_sys".
message	observations	Enter the observation message text.

Study File Format API

v24.3 v25.3

The Study File Format (SFF) is a standardized, unified format that allows both EDC and DQS customers to export clinical data in the form of a single zip package generated for a single study. It contains two main components: Study Data and Study Definition. It is available as a API for customers to consume.

The Study Data lives in a folder called "data" and includes:

• Clinical Data: The raw data entered for each subject across all sites within the Study
• Operational Data: Data that tracks the progress of subjects, data cleaning, and data review within Clinical Data
• Reference Data: Ancillary data that can be used in tandem with Clinical Data to serve as lookup fields
• A CSV file for each clinical data file, operational data file, and reference data file.

The Study Definition is represented as a JSON file called "manifest.json". It includes the study definition information and the definition of each file in the Study Data portion

Package Contents & Structure

This API returns the SFF package as a ZIP file. Within the ZIP file, there is a "data" folder, which contains the CSV files. In the root of the ZIP file, the "manifest.json" file contains the self-describing structure of the package, as well as the study design information.

The package's file name is "<Study Name>_SFF_<Full/Incremental>_<YYYY_MM_DD_HH_MM_SS>". The timestamp is the established published time of the package, for example, "Natevba_SFF_Incremental_2024_08_16_00_30_00".

List Packages

Request

curl -X GET  https://my-vault.veevavault.com/edcworkbench/api/v24.3/sff/packages?study_name=Natevba \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \

Response

{
    "metadata": {
        "size": 150
    },
    "data": {
        "warnings": [],
        "packages": [
            {
                "sff_id": "9187eb22-50da-491a-84f4-b25baa354ed0",
                "type": "full",
                "created_date": "2024-08-15 00:01:11.000",
                "filename": "Natevba_SFF_Full_2024_08_15_12_00_00.zip",
                "sha256": "298810c710ca4e97c71db32033a9da07-1",
                "size": 37550,
                "url": "https://my-vault.veevavault.com/edcworkbench/api/v24.3/sff/packages/download/9187eb22-50da-491a-84f4-b25baa354ed0?study_name=Natevba"
            },
            {
                "sff_id": "dfc7827a-f467-4671-a3e8-860b97558c66",
                "type": "incremental",
                "created_date": "2024-08-15 00:15:47.700",
                "filename": "Natevba_SFF_Incremental_2024_08_15_00_30_00.zip",
                "sha256": "9a8be9deb6b3fa91988c3e76b1ecbce7-1",
                "size": 22512,
                "url": "https://my-vault.veevavault.com/edcworkbench/api/v24.3/sff/packages/download/dfc7827a-f467-4671-a3e8-860b97558c66?study_name=Natevba"
            },
            {
                "sff_id": "8215d022-d9dd-4c82-8f66-423b52bcf892",
                "type": "incremental",
                "created_date": "2024-08-15 00:30:33.300",
                "filename": "Natevba_SFF_Incremental_2024_08_15_00_45_00.zip",
                "sha256": "70d6a9d2b2cedd90bce7e7a54cfcbe52-1",
                "size": 22525,
                "url": "https://my-vault.veevavault.com/edcworkbench/api/v24.3/sff/packages/download/8215d022-d9dd-4c82-8f66-423b52bcf892?study_name=Natevba"
            }
        ]
    },
    "responseStatus": "SUCCESS"
}

The List Packages endpoint returns a list of SFF packages for the given Study. There are two types of packages: full and incremental. Full SFF packages are available to users every 24 hours at 12:00PM UTC. Incremental SFF packages are published every 15 minutes. When using incrementals, download the full package if the full_required field is set to true or you need to reset your system or process.

Learn more about using these packages in Clinical Data Help.

Endpoint

GET https://{{cdbDNS}}/edcworkbench/api/{{version}}/sff/packages

Required Permissions

• Study File Format API Access
• Workbench Tab Access (for Workbench users only - this is in addition to the SFF API Access permission)

The CDB API Read Write role grants these permissions.

Headers

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

Query Parameters

Parameter	Description
study_name	Study Name
type	Optional Package Type. Enter either incremental or full. If omitted, the response includes available packages of both types.
start_time	Optional Start time to filter the files based on the documented published time. Use the yyyy-MM-dd'T'HH:mm'Z' date format.
stop_time	Optional Stop time to filter the files based on the documented published time. Use the yyyy-MM-dd'T'HH:mm'Z' date format.

Response Details

On SUCCESS, Vault returns a list of SFF packages for a given Study.

Array	Parameter	Description
packages	sff_id	Unique ID for the SFF package
packages	type	The type of SFF package, either incremental or full
packages	created_date	The created date of the package
packages	filename	The filename of the zip file
packages	sha256	The checksum for consumers to verify that they're downloading the correct file
packages	size	The size of the package in bytes
packages	url	The URL to download the specific SFF package
packages	full_required	For an incremental package, a true response means that incremental changes have stopped, and you have to wait for the next full SFF package to resume updates. For the full package, a true response means that the package can be used to refresh your data with the latest full set.

Download Packages

Request

curl -X GET  https://my-vault.veevavault.com/edcworkbench/api/v24.3/sff/packages/download/9187eb22-50da-491a-84f4-b25baa354ed0?study_name=Natevba \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \

Response

{
    "responseStatus": "SUCCESS"
}

The Download Packages endpoint allows the user to download the SFF ZIP file. This request downloads the file directly, and the response includes the HTTP status code and the file contents.

Replace the {{sffid}} with the SFF ID returned by the List Packages endpoint.

Endpoint

GET https://{{cdbDNS}}/edcworkbench/api/{{version}}/sff/packages/download/{{sffid}}

Required Permissions

• Study File Format API Access
• Workbench Tab Access (for Workbench users only - this is in addition to the SFF API Access permission)

The CDB API Read Write role grants these permissions.

Headers

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

Query Parameters

Parameter	Description
study_name	Study Name

Study File Format API Versioning

v25.3

A collection of endpoints for getting and setting SFF package versions (1.0 or 2.0). A study can only use one SFF package version at a time, and switching versions requires a new full package generation.

Retrieve List of Available Versions

Request

curl -X GET 'https://{cdbDNS}/edcworkbench/api/{version}/sff/packages/version/supported' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
  "data": {
      "versions": ["1.0", "2.0"]
  },
  "responseStatus": "SUCCESS"
}

This endpoint retrieves a list of all supported SFF package versions for the vault.

Endpoint

GET https://{cdbDNS}/edcworkbench/api/{version}/sff/packages/version/supported

Required Permissions

• Study File Format API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies only)

The CDB API Read Write role grants these permissions.

Headers

Header	Description
Accept	application/json (default)
Authorization	{SESSION_ID}

Response Details

On SUCCESS, Vault returns a list of available SFF package versions.

Object	Parameter	Description
data	versions	Array of supported SFF package versions (e.g., 1.0, 2.0).

Retrieve the Version of a Study

Request

curl -X GET 'https://{cdbDNS}/edcworkbench/api/{version}/sff/packages/version?study_name=MyStudyName' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
  "data": {
    "version": "2.0"
  },
  "responseStatus": "SUCCESS"
}

This endpoint retrieves the currently assigned SFF package version for a specific study.

Endpoint

GET https://{cdbDNS}/edcworkbench/api/{version}/sff/packages/version

Required Permissions

• Study File Format API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies only)

The CDB API Read Write role grants these permissions.

Headers

Header	Description
Accept	application/json (default)
Authorization	{SESSION_ID}

Query Parameters

Parameter	Description
study_name	The name of the Study.

Response Details

On SUCCESS, Vault returns the current SFF package version for the study.

Object	Parameter	Description
data	version	The SFF package version currently set for the study (e.g., 2.0).

Retrieve the Default Version of the Vault

Request

curl -X GET 'https://{cdbDNS}/edcworkbench/api/{version}/sff/packages/version/default' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
  "data": {
    "version": "2.0"
  },
  "responseStatus": "SUCCESS"
}

This endpoint retrieves the default SFF package version set for the vault.

Endpoint

GET https://{cdbDNS}/edcworkbench/api/{version}/sff/packages/version/default

Required Permissions

• Study File Format API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies only)

The CDB API Read Write role grants these permissions.

Headers

Header	Description
Accept	application/json (default)
Authorization	{SESSION_ID}

Response Details

On SUCCESS, Vault returns the current default SFF package version.

Object	Parameter	Description
data	default	The default SFF package version set for the vault (e.g., 2.0).

Set the Study Version

Request

curl -X POST 'https://{cdbDNS}/edcworkbench/api/{version}/sff/packages/version?package_version=2.0&study_name=MyStudyName' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
  "data": {
    "message": "SFF package version has been set to '2.0'"
  },
  "responseStatus": "SUCCESS"
}

This endpoint sets the SFF package version for a specific study. The SFF package version set for a study overrides the default version configured at the vault level. If a study does not have a specific SFF version set, it automatically inherits the vault-level default version. This applies to all studies.

Endpoint

POST https://{cdbDNS}/edcworkbench/api/{version}/sff/packages/version

Required Permissions

• Study File Format API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies)

The CDB API Read Write role grants these permissions.

Headers

Header	Description
Accept	application/json (default)
Authorization	{SESSION_ID}

Query Parameters

Parameter	Description
package_version	Specifies the SFF package version for the study.
study_name	Identifies the target study for the version update.

Response Details

On SUCCESS, Vault returns a confirmation message within the data object's message key.

Object	Parameter	Description
data	message	A confirmation message indicating the version set.

Set the Default Version for the Vault

Request

curl -X POST 'https://{cdbDNS}/edcworkbench/api/{version}/sff/packages/version/default?package_version=2.0' \
-H 'Accept: application/json' \
-H 'Authorization: {SESSION_ID}'

Response

{
  "data": {
    "message": "SFF default package version has been set to '2.0'"
  },
  "responseStatus": "SUCCESS"
}

This endpoint sets the default SFF package version for the entire vault. This default version will apply to all studies unless a study-specific version is explicitly set using the Set the Study Version endpoint.

Endpoint

POST https://{cdbDNS}/edcworkbench/api/{version}/sff/packages/version/default

Required Permissions

• Study File Format API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies)

The CDB API Read Write role grants these permissions.

Headers

Header	Description
Accept	application/json (default)
Authorization	{SESSION_ID}

Query Parameters

Parameter	Description
package_version	The SFF package version that the API sets as the vault default (e.g., 2.0).

Response Details

On SUCCESS, Vault returns a confirmation message within the data object's message key.

Object	Parameter	Description
data	message	A confirmation message indicating the version set.

Jobs

v25.2

Retrieve Job Status

Request with In Progress Status

curl -X GET  'https://my-vault.veevavault.com/edcworkbench/api/v25.2/jobs/658349e8-c5e6-41e8-93d3-046c83ee7325?study_name=Deetoza'
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d 

Response with In Progress Status

{
    "responseStatus": "SUCCESS",
    "data": {
          "id": "658349e8-c5e6-41e8-93d3-046c83ee7325",
          "study_name": "Deetoza",
          "status": "In Progress",
          "created_by": "Jane Smith",
          "created_date": "2025-01-02T12:18:54Z",
          "completed_date": null,
          "url": "https://cdb-3001-wkb.vaultdev.com/edcworkbench/api/v25.2/jobs/download/658349e8-c5e6-41e8-93d3-046c83ee7325?study_name=Deetoza"
    }
}

Request with Error Job Status

curl -X GET  'https://my-vault.veevavault.com/edcworkbench/api/v25.2/jobs/download/658349e8-c5e6-41e8-93d3-046c83ee7326?study_name=Deetoza'
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d 

Response with Error Job Status

{
    "responseStatus": "SUCCESS",
    "data": {
          "id": "658349e8-c5e6-41e8-93d3-046c83ee7326",
          "study_name": "Deetoza",
          "job_status": "Error",
          "created_by": "Jane Smith",
          "created_date": "2025-01-02T12:18:54Z",
          "completed_date": null,
          "url": "https://cdb-3001-wkb.vaultdev.com/edcworkbench/api/v25.2/jobs/download/658349e8-c5e6-41e8-93d3-046c83ee7326?study_name=Deetoza"
    }
}

This endpoint retrieves the job status. You'll only see jobs from studies you can access. If the job fails, the endpoint will return the Issue Log instead of the completed zip file.

GET https://{{cdbDNS}}/edcworkbench/api/{{version}}/jobs/{{job_id}}?study_name={{study_name}}

Required Permissions

To use this endpoint, you need the following permissions:

• API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies only)
• View Export

The CDB API Read Write role grants these permissions.

Headers

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

URI Path Parameters

Parameter	Description
job_id	Input the job ID returned from the Start Job API.

Query Parameters

Parameter	Description
study_name	If an an invalid Study Name is passed, nothing is returned or returns job not found.

Response Details

Object	Parameter	Description
data	id	The Job ID.
data	study_name	The Study Name.
data	status	The current Job Status. Possible values are: Complete, In Progress, Skipped, Error, and Deleted.
data	created_by	The Created By Username.
data	created_date	The Export Created Datetime. Seconds can be included. Format is: yyyy-MM-dd'T'HH:mm:ss'Z' in UTC.
data	completed_date	The execution date and time. Seconds can be included. Format is: yyyy-MM-dd'T'HH:mm:ss'Z' in UTC.
data	url	URL to access the package.

Retrieve Job Artifact

This endpoint retrieves the job artifact. If your export job succeeds, you'll receive a zip file with your data (CSV/SAS) and a manifest. If your job fails, you'll receive an Issue Log CSV file instead of the data. If you have Restricted Data Access, you can download Unblinded packages; otherwise, you can still get the Issue Log for failed jobs. Packages expire after 30 days.

GET https://{{cdbDNS}}/edcworkbench/api/{{version}}/jobs/download/{{job_id}}?study_name={{study_name}}

Required Permissions

To use this endpoint, you need the following permissions:

• API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies only)
• View Export
• View Export Packages
• Restricted Data Access (when the Export Definition is Unblinded)

Headers

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

URI Path Parameters

Parameter	Description
job_id	Input the job ID returned from the Start Job API.

Query Parameters

Parameter	Description
study_name	Returns jobs that you have access to.

Retrieve Job History

Request

curl -X POST  'https://my-vault.veevavault.com/edcworkbench/api/v25.2/jobs?study_name=Deetoza'\
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d 

Response

{
   "metadata": {
        "totalRecords": 2,
        "links": {
            "first": "/edcworkbench/api/v25.2/jobs?study_name=Deetoza&page=1",
            "self": "/edcworkbench/api/v25.2/jobs?study_name=Deetoza&page=1",
            "any": "/edcworkbench/api/v25.2/jobs?study_name=Deetoza&page={page}",
            "prev": "/edcworkbench/api/v25.2/jobs?study_name=Deetoza&page=1",
            "next": "/edcworkbench/api/v25.2/jobs?study_name=Deetoza&page=1",
            "last": "/edcworkbench/api/v25.2/jobs?study_name=Deetoza&page=1"
        }
    },
   "responseStatus": "SUCCESS",
   "data": {
      "jobs": [
         {
             "study_name": "Deetoza",
             "type": "export",
             "details": {
                "export_definition_name": "my-raw-export",
                "export_definition_id": 8,
                "export_definition_type": "Raw",
                "job_id": "658349e8-c5e6-41e8-93d3-046c83ee7325",
                "job_status": "Complete",
                "created_by": "Jane Smith",
                "created_date": "2025-01-02T12:18:54Z"
             }
         },
         {
             "study_name": "Deetoza",
             "type": "export",
             "details": {
                 "export_definition_name": "my-raw-export2",
                 "export_definition_id": 9,
                 "export_definition_type": "Raw",
                 "job_id": "658349e8-c5e6-41e8-93d3-046c83ee7325",
                 "job_status": "Complete",
                 "created_by": "Jane Smith",
                 "created_date": "2025-01-02T12:18:54Z"
             }
         }
      ]
   }
}

GET https://{{cdbDNS}}/edcworkbench/api/{{version}}/jobs?study_name={{study_name}}

Required Permissions

To use this endpoint, you need the following permissions:

• API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies only)
• View Export
• View Export Packages

Headers

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

Query Parameters

Parameter	Description
study_name	Return study jobs that a user has access to.
type	Optional Return export jobs. If empty, returns an error. Can be omitted.
start_time	Optional List any jobs with a created date after the specified date. Format is: yyyy-MM-dd'T'HH:mm[s]'Z' in UTC. You can specify both minutes and seconds. Must be within 30 days.
stop_time	Optional List jobs with a created date before the specified date. Format is: yyyy-MM-dd'T'HH:mm[s]'Z' in UTC. You can specify both minutes and seconds. Must be within 30 days.

Response Details

Array	Parameter	Description
jobs		Job array
jobs	study_name	Study Name
jobs	type	Return export type.
details	export_definition_name	If the job type is export, return this field.
details	export_definition_id	If the job type is export, return this field.
details	export_definition_type	The export definition type: Raw or Custom
details	job_id	Job ID.
details	job_status	The Current Job Status.
details	created_by	The System; the created by field of the row in the job history table.
details	created_date	The System; the created date and time field of the current row in the job history table. Format is: yyyy-MM-dd'T'HH:mm:ss'Z' in UTC.

Studies

v25.2

Retrieve Studies

Request

curl -X GET 'https://myvaultdev.com/api/v26.3/dqs/studies' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: {SESSION_ID}'

Response

{
  "metadata": {
    "totalRecords": 1,
    "links": {
      "first": "/edcworkbench/api/v26.3/studies?page=1",
      "self": "/edcworkbench/api/v26.3/studies?page=1",
      "any": "/edcworkbench/api/v26.3/studies?page={page}",
      "prev": "/edcworkbench/api/v26.3/studies?page=1",
      "next": "/edcworkbench/api/v26.3/studies?page=1",
      "last": "/edcworkbench/api/v26.3/studies?page=1"
    }
  },
  "data": {
    "studies": [
      {
        "study_id": "OOZ000000002001",
        "study_name": "Deetoza",
        "study_label": "Deetoza Phase II",
        "external_id": "DEETOZA",
        "study_phase": "phase_ii__v",
        "study_status": "planning__v",
        "dqs_study_status": "ACTIVE",
        "type": "veeva_v",
        "locked": true,
        "last_locked_date": "2025-03-01T12:00:00Z",
        "organization": "ABC Pharma",
        "environment_type": "production_v",
        "link__sys": "194674_0ST000000000301"
      }
    ]
  },
  "responseStatus": "SUCCESS"
}

This endpoint provides users with relevant DQS study information and supports other endpoints that require the study_name parameter.

GET https://{vaultDNS}/api/v26.3/dqs/studies

Required Permissions

To use this endpoint, you need the following permissions:

• API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies only)
• Study Access for the user (only for studies you have access to)

Headers

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

Response Details

On SUCCESS, Vault returns the following:

Array	Parameter	Description
studies		Array of study information.
studies	study_id	The Study ID.
studies	study_name	The Study Name.
studies	study_label	The export definition name.
studies	external_id	The Study External ID / OID.
studies	study_phase	The EDC Study Phase.
studies	study_status	The EDC Study Status.
studies	dqs_study_status	For DQS Studies: Inactive, Active, Marked for Deletion
studies	type	Helps to distinguish between Veeva EDC & OpenEDC Studies
studies	locked	Whether the study is locked or not. Boolean, true and false values.
studies	last_locked_date	If locked, the last locked date is populated. Format: yyyy-MM-dd'T'HH:mm:ss'Z' in UTC
studies	organization	The organization origin.
studies	environment_type	The environment type. uat__v, production__v
studies	link__sys	Displays the EDC global link ID for connected Clinical Operation - EDC studies.

DQS Exports

v25.2

Start Export Job

Request

curl -X POST 'https://my-vault.veevavault.com/edcworkbench/api/v25.2/exports/start' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: {SESSION_ID}' \
 -d '{
 "study_name": "Deetoza",
 "type": "export",
 "request": {
   "definition_name": "My_Def",
   "file_type": "CSV"
 }
}'

Response

{
 "responseStatus": "SUCCESS",
 "data": {
   "type": "export",
   "definition_name": "my-raw-export",
   "definition_type": "Raw",
   "file_type": "CSV",
   "job_id": "658349e8-c5e6-41e8-93d3-046c83ee7325",
   "created_by": "Jane Smith",
   "created_date": "2025-01-02T12:18:54Z"
 }
}

This endpoint allows you to initiate an export job.

To initiate an export job, specify the study name and the export definition name. The system uses this information to start the on-demand job and returns a job ID that you can use to track its status. You cannot start jobs for inactive or deleted studies using this API.

Endpoint

POST https://{{cdbDNS}}/edcworkbench/api/{{version}}/exports/start

Required Permissions

To use this endpoint, you need the following permissions:

• API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies only)
• Generate Export Package

The CDB API Read Write role grants these permissions.

Headers

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

Query Parameters

Parameter	Description
study_name	The name of the Study. If the study name contains spaces, they will be normalized by replacing them with underscores.
type	The Export Type. Allowed value is export.
request	An object to hold the job options.
request: definition_name	The name of the Export Definition as defined in the Exports tab for that Study (e.g., "MyDef"). This field is case-sensitive and will be validated against existing export definition names. Either definition_name or export_definition_id is required.
request: file_type	The desired file type for the export. Allowed values are CSV or SAS. SAS packages include CSV.

Response Details

Object	Parameter	Description
data	type	The export type.
data	definition_name	The export definition name.
data	definition_type	Values include Raw, Custom, and STDM (only for existing export definitions, as generation of new SDTM definitions is not supported).
data	file_type	CSV or SAS.
data	job_id	The Job ID.
data	created_by	The Username of the user who created the export.
data	created_date	The Export Created Datetime. The format is YYYY-MM-dd T HH:mm:ss Z in UTC, and can include seconds in the response.

Retrieve Export Definitions

Request

curl -X GET 'https://my-vault.veevavault.com/edcworkbench/api/v25.2/exports/definitions?study_name=Deetoza' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: {SESSION_ID}'

Response

{
  "metadata": {
    "totalRecords": 2,
    "links": {
      "first": "/edcworkbench/api/v25.2/exports/definitions?study_name=Deetoza&page=1",
      "self": "/edcworkbench/api/v25.2/exports/definitions?study_name=Deetoza&page=1",
      "any": "/edcworkbench/api/v25.2/exports/definitions?study_name=Deetoza&page={page}",
      "prev": "/edcworkbench/api/v25.2/exports/definitions?study_name=Deetoza&page=1",
      "next": "/edcworkbench/api/v25.2/exports/definitions?study_name=Deetoza&page=1",
      "last": "/edcworkbench/api/v25.2/exports/definitions?study_name=Deetoza&page=1"
    }
  },
  "responseStatus": "SUCCESS",
  "data": {
    "definitions": [
      {
        "study_name": "Deetoza",
        "name": "my-raw-export",
        "id": 8,
        "type": "Custom",
        "blinded": true,
        "created_by": "Jane Smith",
        "created_date": "2025-01-02T12:18:54Z",
        "last_modified_by": "Jane Smith",
        "last_modified_date": "2025-01-02T12:18:54Z"
      },
      {
        "study_name": "Deetoza",
        "name": "my-raw-export2",
        "id": 9,
        "type": "Raw",
        "blinded": false,
        "created_by": "Jane Smith",
        "created_date": "2025-01-02T12:18:54Z",
        "last_modified_by": "Jane Smith",
        "last_modified_date": "2025-01-02T12:18:54Z"
      }
    ]
  }
}

This endpoint allows users to retrieve existing export definitions and is useful for starting a new export job using a pre-configured definition.

Endpoint

GET https://{{cdbDNS}}/edcworkbench/api/{{version}}/exports/definitions

Required Permissions

To use this endpoint, you need the following permissions:

• API Access
• Workbench Tab (for Workbench studies)
• Clinical Reporting Tab (for Clinical Reporting studies only)
• View Export
• Study Access (you'll only see definitions for studies you have access to)

Headers

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

Query Parameters

Parameter	Description
study_name	This parameter is used as a filter to retrieve export definitions for a certain study. If passing the study name with spaces, normalize it (replace spaces with underscores).

Response Details

On SUCCESS, Vault returns the following:

Array	Parameter	Description
definitions		Array of export definition information.
definitions	study_name	The name of the Study.
definitions	name	The export definition name.
definitions	id	The export definition ID.
definitions	type	Values: Raw, Custom.
definitions	blinded	Values: true or false.
definitions	created_by	The created by name.
definitions	created_date	The created date. The format is YYYY-MM-dd T HH:mm:ss Z in UTC. Seconds are allowed.
definitions	last_modified_by	The modified by name.
definitions	last_modified_date	The modified by date. The format is YYYY-MM-dd'T'HH:mm:ss Z in UTC. Seconds are allowed.