TOC Navbar
shell

Getting Started

This tutorial explains the Vault user permissions needed to access the CDB 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, CDB provides a Postman™ collection for each GA release of the CDB 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 CDB API collection.

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

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 CDB Workbench API, your Study Role must grant the API Access permission. Then, you must 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 any other API calls you make will return the following error:

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

As we talk about API calls, you’ll see the following variables in each endpoint. You’ll need to replace these with the correct values.

Versioning

Veeva CDB uses domain-specific versioning of the CDB API. As of the current release, the CDB API comprises three domains (or sections): Forms, Queries, and Study File Format. Previous versions are deprecated when new ones are released.

For example, when a new version of Queries is released, the previous version is deprecated. This does not impact the versioning of Forms or the Study File Format. Check the applicable version number(s) for each domain in its respective section.

Both Beta and GA domain versions are maintained by CDB and accessible from the top navigation bar. The Beta version of a domain is subject to change, and the GA version remains stable. Beta versions are not consistently available in every release cycle, unlike the Vault and EDC APIs.

See the Release Notes for the latest CDB APIs, enhancements, and bug fixes.

Naming

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

Each General Release is made up of multiple limited releases. For example, CDB 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.

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, CDB 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://cdb-1-wkb.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://cdb-1-wkb.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

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

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.

CDB-Specific Errors

The table below lists common errors for CDB 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 CDB 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 Size limit for API versions 24.3 and 25.2

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

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

URI Path Parameters

Name Description
vault_subdomain The DNS of the Vault for which you want to generate a session.
version The Vault API version. Your authentication version does not need to match the version in subsequent calls. For example, you can authenticate with v22.2 and run your integrations with v22.3.

Body Parameters

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

Basic Authorization

Name Description
Authorization {sessionId}

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

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

Bearer Token Authorization

Name Description
Authorization Bearer {sessionId}

OAuth 2.0 / OpenID Connect

Request

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

Response

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

Authenticate your account using OAuth 2.0 / Open ID Connect token to obtain a Vault Session ID. Learn more about OAuth 2.0 / Open ID Connect in Vault Help.

When requesting a sessionId, Vault allows the ability for Oauth2/OIDC client applications to pass the client_id with the request. Vault uses this client_id when talking with the introspection endpoint at the authorization server to validate that the access_token presented by the application is valid. More information on `client_id' found in a previous section

Endpoint

POST https://login.veevavault.com/auth/oauth/session/{oath_oidc_profile_id}

Headers

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

URI Path Parameters

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

Body Parameters

Name Description
vaultDNS Optional The DNS of the vault for which you want to generate a session. If omitted, the session is generated for user’s default vault.
client_id Optional The ID of the client application at the Authorization server

Authentication Type Discovery

Request

$ curl -X GET \
-H "Accept: application/json" \
"https://login.veevavault.com/auth/discovery?username=meganmurray@veepharm.com&client_id=VaultCheckOut"

Response: Password User

{
    "responseStatus": "SUCCESS",
    "errors": [],
    "data": {
        "auth_type": "password"
    }
}

Response: SSO User

{
    "responseStatus": "SUCCESS",
    "data": {
        "auth_type": "sso",
        "auth_profiles": [
            {
                "id": "_9ad0a091-cbd6-4z59-ab5a-d4f35789918c",
                "label": "VeePharm",
                "description": "",
                "vault_session_endpoint": "https://veepharm.com/auth/oauth/session/_9ad0a091-cbd6-4z59-ab5a-d4f35789918c",
                "use_adal": false,
                "as_client_id":"34524523452345234523452345098098234",
                "as_metadata": {
                    "issuer": "https://veevaintrospection.com/oauth2/asdf123",
                    "authorization_endpoint": "https://veevintrospection.com/oauth2/asdf123/v1/authorize",
                    "token_endpoint": "https://veevaintrospection.com/oauth2/asdf123/v1/token",
                    "registration_endpoint": "https://veevaintrospection.com/oauth2/v1/clients",
                    "jwks_uri": "https://veevaintrospection.com/oauth2/asdf123/v1/keys",
                    "response_types_supported": [
                        "code",
                        "token",
                        "code token"
                    ],
                    "response_modes_supported": [
                        "query"
                    ],
                    "introspection_endpoint": "https://veevatintrospection.com/oauth2/asdf1234/v1/introspect",
                    "introspection_endpoint_auth_methods_supported": [
                        "client_secret_basic",
                    ],
                    "revocation_endpoint": "https://veevaintrospection.com/oauth2/asdf123/v1/revoke",
                    "revocation_endpoint_auth_methods_supported": [
                        "client_secret_basic",
                    ],
                    "end_session_endpoint": "https://veevaintrospection.com/oauth2/asdf123/v1/logout"
                }
            }
        ]
    }
}

Discover the user's authentication type. With this API, applications can dynamically adjust the login requirements per user, and support either username/password or OAuth2.0 / OpenID Connect authentication schemes.

Endpoint

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

Headers

Name Description
Accept application/json (default)

Query String Parameters

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

Response Details

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

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

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

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

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://cdb-1-wkb.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

The CDB API Read Write role grants these permissions.

Headers

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

Query Parameters

Name Required Description
study_name Yes Study Name
source Yes Source Name (EDC or 3rd-party source name)
site_number Yes Study Site Number
subject_name Yes Subject Name
form_name Yes Form Definition Name

Queries

Specify v24.3 or v26.1 to use these APIs.

Open Queries on Items

Request 

curl -X POST  https://cdb-1-wkb.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 CDB 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

The CDB API Read Write role grants these permissions.

Headers

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

Body Parameters: Full Hierarchy

Name Array Required Description
study_name Yes Study Name
manual No 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 No 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 Yes 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 No 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 No 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 Yes Source Name (for Vault EDC, enter “EDC”)
site_number queries Yes Site Number
subject_name queries Yes Subject Name (ID/number) to filter to. Must include site_number when using this.
eventgroup_name queries Yes Event Group Definition Name
eventgroup_sequence queries No (defaults to 1) Event Group Sequence (for repeating Event Groups)
event_name queries Yes Event Definition Name
form_name queries Yes Item Definition Name
form_sequence queries Yes Form Sequence (for repeating Forms). For non-repeating forms, enter "1".
itemgroup_name queries Yes Item Group Definition Name
itemgroup_sequence queries Yes Item Group Sequence (for repeating Item Groups). For non-repeating item groups, enter "1".
item_name queries Yes Item Definition Name
message queries Yes Query Message (limited to 500 characters)

Request 

curl -X POST  https://cdb-1-wkb.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

Name Array Required Description
study_name Yes Study Name
manual No 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 Yes External originating system. This parameter is required and can be set for each query inside the queries array.
origin_id No External origin system ID. This parameter can be set for each query inside the queries array.
origin_name No External origin system name. This parameter can be set for each query inside the queries array.
source queries Yes Source Name (for Vault EDC, enter “EDC”)
event_id queries Yes Event ID
form_name queries Yes Form Definition Name
itemgroup_name queries Yes Item Group Definition Name
item_id queries Yes Item ID
item_name queries Yes Item Definition Name
message queries Yes Query Message (limited to 500 characters)

Open Queries on Events

Request 

curl -X POST  https://cdb-1-wkb.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 CDB 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

The CDB API Read Write role grants these permissions.

Headers

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

Body Parameters: Full Hierarchy

Name Array Required Description
study_name Yes Study Name
manual No 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 Yes 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 No External origin system ID. This parameter can be set for each query inside the queries array.
origin_name No External origin system name. This parameter can be set for each query inside the queries array.
origin_user No 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 Yes Source Name (for Vault EDC, enter “EDC”)
site_number queries Yes Site Number
subject_name queries Yes Subject Name (ID/number) to filter to. Must include site_number when using this.
eventgroup_name queries Yes Event Group Definition Name
eventgroup_sequence queries No (defaults to 1) Event Group Sequence (for repeating Event Groups)
event_name queries Yes Event Definition Name
message queries Yes Query Message (limited to 500 characters)

Request 

curl -X POST  hhttps://cdb-1-wkb.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

Name Array Required Description
study_name Yes Study Name
manual No 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 Yes 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 No External origin system ID. This parameter can be set for each query inside the queries array.
origin_name No External origin system name. This parameter can be set for each query inside the queries array.
source queries Yes Source Name (for Vault EDC, enter “EDC”)
event_id queries Yes Event ID
message queries Yes Query Message (limited to 500 characters)

Retrieve Queries

Request 

curl -L -X GET 'https://cdb-1-wkb.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

The CDB API Read Write role grants these permissions.

Headers

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

Query Parameters

Name 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 Name Description
queries source Query Source Name
queries id Query ID
queries query_name Query Name
queries rowexternalid Row External ID (for CDB 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 CDB 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://cdb-1-wkb.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 CDB 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 CDB Workbench UI.

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

Endpoint

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

Required Permissions

The CDB API Read Write role grants these permissions.

Headers

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

Body Parameters

Name Array Required Description
study_name Yes Study Name
id queries Yes Query ID
message queries Yes Query Message (limited to 500 characters)
message_origin_sys No The external originating system of the query message. This cannot equal "CDB" and is case insensitive.
message_origin_user No The external origin user of the query message.
message_origin_id No 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://cdb-1-wkb.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 CDB 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 CDB Workbench UI.

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

Endpoint

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

Required Permissions

The CDB API Read Write role grants these permissions.

Headers

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

Body Parameters

Name Array Required Description
study_name Yes Study Name
id queries Yes Query ID
message queries Yes Query Message (limited to 500 characters)
message_origin_sys No The external originating system of the query message. This cannot equal "CDB" and is case insensitive.
message_origin_user No The external origin user of the query message.
message_origin_id No 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.

Study File Format

v24.3

The Study File Format (SFF) is a standardized, unified format that allows both EDC and CDB 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:

The Study Definition is represented as a JSON file called "manifest.json" and includes:

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://cdb-1-wkb.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://cdb-1-wkb.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://cdb-1-wkb.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://cdb-1-wkb.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](https://cdmshelp.veeva.com/lr/monitors/cdb/study-file-format/).

Endpoint

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

Required Permissions

The CDB API Read Write role grants these permissions.

Headers

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

Query Parameters

Name Required Description
study_name Yes Study Name
type Package Type. Enter either incremental or full. If omitted, the response includes available packages of both types.
start_time 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 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 Name 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://cdb-1-wkb.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

The CDB API Read Write role grants these permissions.

Headers

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

Query Parameters

Name Required Description
study_name Yes Study Name

Study File Format Versioning

Specify v24.3 or v25.3 to use these APIs.

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

The CDB API Read Write role grants these permissions.

Headers

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

Response Details

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

Array Name Description
packages supported 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

The CDB API Read Write role grants these permissions.

Headers

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

Query Parameters

Name Required Description
study_name Yes The name of the Study.

Response Details

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

Array Name Description
packages 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

The CDB API Read Write role grants these permissions.

Headers

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

Response Details

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

Array Name Description
packages default The default SFF package version set for the vault (e.g., 2.0).

Jobs

Specify v25.2 to use these APIs.

Retrieve Job Status

Request with In Progress Status

curl -X GET  'https://cdb-1-wkb.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://cdb-1-wkb.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:

The CDB API Read Write role grants these permissions.

Headers

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

URI Path Parameters

Parameter Required Notes
job_id Yes Input the job ID returned from the Start Job API.

Query Parameters

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

Response Details

Parameter Description
id The Job ID.
study_name The Study Name.
status The current Job Status. Possible values are: Complete, In Progress, Skipped, Error, and Deleted.
created_by The Created By Username.
created_date The Export Created Datetime. Seconds can be included. Format is: yyyy-MM-dd'T'HH:mm:ss'Z' in UTC.
completed_date The execution date and time. Seconds can be included. Format is: yyyy-MM-dd'T'HH:mm:ss'Z' in UTC.
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:

Headers

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

URI Path Parameters

Parameter Required Notes
job_id Yes Input the job ID returned from the Start Job API.

Query Parameters

Parameter Required Description
study_name Yes Returns jobs that you have access to.

Retrieve Job History

Request 

curl -X POST  'https://cdb-1-wkb.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:

Headers

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

Query Parameters

Parameter Required Description
study_name Yes Return study jobs that a user has access to.
type No Return export jobs. If empty, returns an error. Can be omitted.
start_time No 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 No 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_definiton_id If the job type is export, return this field.
details export_definition_type The export definition type: Raw or Custom
details id Job ID.
details 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.
shell