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 REST API. Note that this collection represents the point in time when the API became GA, and will not receive additional updates. For the most up-to-date documentation, developers should reference the REST 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:

To learn more about the structure of Vault CDMS, see CDMS 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 REST 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 Vault CDMS 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

CDB Workbench maintains Beta and GA versions of the CDB REST API. The Beta version is subject to change as it includes features from the limited releases. The GA version remains stable. Many new APIs are not backward compatible. You'll need the latest version to access new features. See the Release Notes for new APIs, enhancements, and bug fixes.

Naming

CDB Workbench introduces new API versions during its triannual release cycles, coinciding with the CDB General Releases. CDB REST 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 REST 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 REST 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, REST 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 50 records per page. You can change (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 50 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.

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 Description
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. Please verify your input and try again 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. Please verify your input and try again 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 is locked
Queries Event with ID [event_id] not found Event ID is provided, but invalid
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 User tries to specify origin_sys, origin_id or origin_name when manual = true
Queries [Origin_sys] are required in order to set field with name [origin_id/origin_name] User tries to set origin fields without origin_sys. Origin_sys must be set first, before the origin fields.
Queries Event date is locked Event date is locked only (not the rest of the event)
Queries Event is locked Event is locked
Queries Required field 'message' is missing or empty for provided query [source/study_name/site_number/form_name] Message is an empty string
Queries Message exceeds maximum length of 500 for provided query Message is invalid (too long)
Queries Required field 'message' is missing or empty for provided query [source/study_name/site_number/form_name] Message parameter is missing
Queries Item is locked Site is locked
Queries Item is locked Study is locked
Queries Item is locked Subject is locked
Queries Event with ID [event_id] not found User does not have permission to open query on blinded/restricted Event on EDC data
Queries User does not have permission to open query on blinded item with ID [item_id] in source [source] User does not have permission to open query on blinded Item on 3PD data
Queries Item with ID [item_id] not found User does not have permission to open query on blinded/restricted Item on EDC data

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 REST API version. Your authentication version does not need to match the version in subsequent calls. For example, you can authenticate with v22.2 and run your integrations with v22.3.

Body Parameters

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

Basic Authorization

Name Description
Authorization {sessionId}

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

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

Bearer Token Authorization

Name Description
Authorization Bearer {sessionId}

OAuth 2.0 / OpenID Connect

Request

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

Response

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

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

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

Endpoint

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

Headers

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

URI Path Parameters

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

Body Parameters

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

Authentication Type Discovery

Request

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

Response: Password User

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

Response: SSO User

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

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

Endpoint

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

Headers

Name Description
Accept application/json (default)

Query String Parameters

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

Response Details

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

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

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

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

Forms

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.

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 (for Vault EDC, enter “EDC”)
site_number Yes Site Number
subject_name Yes Subject Name (ID/number) to filter to. Must include site_number when using this.
form_name Yes Form Definition Name

Queries

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",
  "manual": false,
  "origin_sys": "externalSystem",
  "origin_name": "externalSystemName",
  "origin_id": "12345",
  "queries": [
    {
      "source": "EDC",
      "site_number": "101",
      "subject_name": "SCR-0002",
      "eventgroup_name": "baseline",
      "eventgroup_sequence": 1,
      "event_name": "baseline_visit",
      "form_name": "chemistry",
      "form_sequence": 1,
      "itemgroup_name": "chemistry",
      "itemgroup_sequence": 1,
      "item_name": "LBORRES",
      "message": "please check this lab result."
    }
  ]
}

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 Vault CDMS 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 Set to false if the query originates from an external system outside of CDB. Defaults to true if omitted.
origin_sys No External originating system. This parameter is used when defining the name of an external system used to open queries in CDB. If this field is not set and manual equals false, it defaults to “CDB”, a protected keyword. This applies to all queries within the payload.
origin_id No External origin system ID. This parameter is used when defining the ID of an external system used to open queries in CDB. When this is specified, you must also specify a value for origin_sys. This applies to all queries within the payload.
origin_name No External origin system name. This parameter is used when defining the name of an external system (which can be an alternative to origin_sys) used to open queries in CDB. When this is specified, you must also specify a value for origin_sys.
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",
  "manual": false,
  "origin_sys": "externalSystem",
  "origin_name": "externalSystemName",
  "origin_id": "12345",
  "queries": [
    {
      "source": "EDC",
      "event_id": "OPS00000006K002",
      "form_name": "chemistry",
      "itemgroup_name": "chemistry",
      "item_id": "V5500000008D043",
      "item_name": "LBORRES",
      "message": "please correct this lab result"
    }
  ]
}

Response 

{
    "data": {
        "queries": [
            {
                "id": "OPW000000033001",
                "query_name": "VV-000249",
                "query_status": "open__v",
                "origin_sys": "externalSystem",
                "origin_id": "12345",
                "origin_name": "externalSystemName",
                "last_modified_date": "2023-06-13 15:51:28.0",
                "first_message": {
                    "id": "OPY00000003X001",
                    "message_status": "open__v",
                    "message": "please correct this lab result",
                    "message_by": "Data Manager",
                    "message_date": "2023-06-13 15:51:28.0"
                },
                "latest_message": {
                    "id": "OPY00000003X001",
                    "message_status": "open__v",
                    "message": "please correct this lab result",
                    "message_by": "Data Manager",
                    "message_date": "2023-06-13 15:51:28.0"
                },
                "source": "EDC",
                "event_id": "OPS00000006K002",
                "site_country": "USA",
                "site_number": "101",
                "subject_name": "SCR-0002",
                "eventgroup_name": "baseline",
                "eventgroup_sequence": 1,
                "event_name": "baseline_visit",
                "manual": false,
                "created_date": "2023-06-13 15:51:28.0",
                "created_by": "Data Manager",
                "form_name": "chemistry",
                "form_sequence": 1,
                "itemgroup_name": "chemistry",
                "itemgroup_sequence": 2,
                "item_id": "V5500000008D043",
                "item_name": "LBORRES"
            }
        ]
    },
    "responseStatus": "SUCCESS"
}

Body Parameters: Item ID

Name Array Required Description
study_name Yes Study Name
manual No Set to false if the query originates from an external system outside of CDB. Defaults to true if omitted
origin_sys No External Origin System If manual = false and this is not set, it will default to “CDB”, which is a protected keyword
origin_id No External Origin System ID
origin_name No External Origin System Name; origin_sys is required if users want to specify external origin information, but origin_name is optional.
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",
        "subject_name": "SCR-0002",
        "site_number": "101",
        "eventgroup_name": "baseline",
        "event_name": "baseline_visit",
        "message": "please verify event date"  
      }
    ]
  }

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 Set to false if the query originates from an external system outside of CDB. Defaults to true if omitted
origin_sys No External Origin System If manual = false and this is not set, it will default to “CDB”, which is a protected keyword
origin_id No External Origin System ID
origin_name No External Origin System Name; origin_sys is required if users want to specify external origin information, but origin_name is optional.
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 '
  {
    "source": "EDC",
    "event_id": "OPS00000006K002",
    "message": "please check this event date"  
  }
]
}

Response 

{
    "data": {
        "queries": [
            {
                "id": "OPW000000033002",
                "query_name": "VV-000251",
                "query_status": "open__v",
                "last_modified_date": "2023-06-13 16:01:08.0",
                "first_message": {
                    "id": "OPY00000003X002",
                    "message_status": "open__v",
                    "message": "please check this event date",
                    "message_by": "Data Manager",
                    "message_date": "2023-06-13 16:01:08.0"
                },
                "latest_message": {
                    "id": "OPY00000003X002",
                    "message_status": "open__v",
                    "message": "please check this event date",
                    "message_by": "Data Manager",
                    "message_date": "2023-06-13 16:01:08.0"
                },
                "source": "EDC",
                "event_id": "OPS00000006K002",
                "site_country": "USA",
                "site_number": "101",
                "subject_name": "SCR-0002",
                "eventgroup_name": "baseline",
                "eventgroup_sequence": 1,
                "event_name": "baseline_visit",
                "manual": true,
                "created_date": "2023-06-13 16:01:08.0",
                "created_by": "Data Manager"
            }
        ]
    },
    "responseStatus": "SUCCESS"
}

Body Parameters: Event ID

Name Array Required Description
study_name Yes Study Name
manual No Set to false if the query originates from an external system outside of CDB. Defaults to true if omitted
origin_sys No External Origin System If manual = false and this is not set, it will default to “CDB”, which is a protected keyword
origin_id No External Origin System ID
origin_name No External Origin System Name; origin_sys is required if users want to specify external origin information, but origin_name is optional.
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)

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": "OPW000000033002",
        "message": "Answering EDC query."  
      }
    ]
  }

Response 

  {
    "data": {
        "queries": [
            {
                "id": "OPW000000033002",
                "query_name": "VV-000251",
                "query_status": "open__v",
                "origin_sys": "CDB",
                "last_modified_date": "2023-06-13 16:11:36.0",
                "first_message": {
                    "id": "OPY00000003X002",
                    "message_status": "open__v",
                    "message": "please check this event date",
                    "message_by": "Data Manager",
                    "message_date": "2023-06-13 16:01:08.0"
                },
                "latest_message": {
                    "id": "OPY000000040003",
                    "message_status": "open__v",
                    "message": "Answering EDC query.",
                    "message_by": "CRC User",
                    "message_date": "2023-06-13 16:11:36.0"
                }
            }
        ]
    },
    "responseStatus": "SUCCESS"
}

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

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": "OPW000000033002",
        "message": "Closing query."  
      }
    ]
  }

Response 

  {
    "data": {
        "queries": [
            {
                "id": "OPW000000033002",
                "query_name": "VV-000251",
                "query_status": "closed__v",
                "origin_sys": "CDB",
                "last_modified_date": "2023-06-13 16:15:36.0",
                "first_message": {
                    "id": "OPY00000003X002",
                    "message_status": "open__v",
                    "message": "please check this event date",
                    "message_by": "Data Manager",
                    "message_date": "2023-06-13 16:01:08.0"
                },
                "latest_message": {
                    "id": "OPY000000040004",
                    "message_status": "closed__v",
                    "message": "Closing this query.",
                    "message_by": "Data Manager",
                    "message_date": "2023-06-13 16:15:36.0"
                }
            }
        ]
    },
    "responseStatus": "SUCCESS"
}

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 Vault CDMS 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)
shell