1. REST API for Clinical One Cloud Service
  2. Tasks
  3. Data Hub
  4. Datasets
  5. Get codelists for a study and a given mode

V1.0

post

/ec-datahub-svc/rest/v1.0/tenant/{tenantId}/studies/{studyId}/{mode}/codelists

Retrieves the study-permissioned Codelists dataset for a single study and explicitly selected study mode.

The dataset exposes codelist values used by forms and questions, together with study, form, item, codelist, audit and reference attributes.

Supports select, filter, sort, limit, and offset query patterns.

The dataset returns rows for codelist values available in the selected study mode.

Required permission: StudyCodelistDatasetPost.

Recommended order columns: The backend query always orders results by DH_TIMESTAMP and VERSION_START in ascending order first. If orderColumns is empty, only these two columns are used. If orderColumns is provided, the specified columns are appended after DH_TIMESTAMP and VERSION_START. For stable, deterministic pagination, use STUDY_ID, FORM_ID, ITEM_ID, CODELIST_ID, and CODELISTITEM_ID in the orderColumns field of the request payload.

Request

Path Parameters

  • Execution mode for the study.

    Allowed values: test, active, training.

    Example: test.

  • Unique study identifier supplied in the studyId path parameter.

    Use the uppercase hexadecimal UUID value for the study.

    Example: 0C7CBA3F70034C47947E2FAB086BFBF5.

    Example:
    0C7CBA3F70034C47947E2FAB086BFBF5

  • Unique tenant identifier supplied in the tenantId path parameter.

    Use the uppercase hexadecimal UUID value for the tenant.

    Example: EC942244BB30163BE053BEC44C64CF34.

    Example:
    EC942244BB30163BE053BEC44C64CF34
Query Parameters
  • Minimum Value: 0

    Page size for the result set.

    • 0 disables pagination and returns the maximum result set allowed by the dataset endpoint.
    • Positive values enable pagination.
    • Negative values return HTTP 400.
    Example:
    100
  • Minimum Value: 0

    Zero-based row offset.

    • Counts rows, not pages.
    • To fetch the next page, repeat the same request body and set offset = previous offset + previous count.
    • When limit = 0, this value is ignored and the response echoes offset = 0.
    • When limit > 0, an offset beyond the available rows returns HTTP 200 with an empty page.
    • Negative values return HTTP 400.
    Example:
    0
Supported Media Types
Request Body - application/json ()
Root Schema : schema
Type: object

Submit a structured query for a Data Hub dataset.

  • selectColumns is required and must contain one or more valid column names exposed by the target dataset version.
  • whereColumns is optional and provides structured filter predicates. Supported operators are =, !=, <>, >, >=, <, <=, LIKE, NOT LIKE, IN, NOT IN, BETWEEN, NOT BETWEEN, IS, and IS NOT.

    Default behavior: Data is filtered based on the STUDY_WID column.

  • orderColumns is optional and controls sort order. For stable multi-page retrieval, keep the same orderColumns across page requests.
Show Source
  • orderColumns

    Optional sort instructions to apply to the result set.

    Duplicate order-by columns are rejected.

  • selectColumns

    Required non-empty list of dataset column names to return.

    Column validation is case-insensitive, and the response echoes canonical uppercase dataset column names in the same order.

  • whereColumns

    Optional structured filter predicates.

    This is the request-body equivalent of a WHERE clause.

    All predicate values are supplied as strings and are parsed according to the underlying dataset column type.

Nested Schema : orderColumns
Type: array

Optional sort instructions to apply to the result set.

Duplicate order-by columns are rejected.

Show Source
Example:
[
    {
        "columnName":"VERSION_START",
        "sortOrder":"ASC"
    }
]
Nested Schema : selectColumns
Type: array

Required non-empty list of dataset column names to return.

Column validation is case-insensitive, and the response echoes canonical uppercase dataset column names in the same order.

Show Source

  • Required non-empty list of dataset column names to return.

    Column validation is case-insensitive, and the response echoes canonical uppercase dataset column names in the same order.

    Example: ["STUDY_VERSION","STUDY_ID"]
Example:
[
    "STUDY_VERSION",
    "STUDY_ID"
]
Nested Schema : whereColumns
Type: array

Optional structured filter predicates.

This is the request-body equivalent of a WHERE clause.

All predicate values are supplied as strings and are parsed according to the underlying dataset column type.

Show Source
Example:
[
    {
        "columnName":"STUDY_ID",
        "operator":"=",
        "value":[
            "A86F2D0BB610404DB62D37AFA9C20B50"
        ]
    }
]
Nested Schema : QueryOrder
Type: object

Sort instruction specifying a dataset column and optional order direction.

Show Source

  • Required dataset column name to sort by.

    Column-name validation is case-insensitive.

    Example: VERSION_START
  • Allowed Values: [ "ASC", "DESC" ]

    Optional sort direction.

    If omitted, SQL default ascending order is used for that column. Allowed values are ASC and DESC.

    Example: ASC
Example:
[
    {
        "columnName":"VERSION_START",
        "sortOrder":"ASC"
    }
]
Nested Schema : QueryPredicate
Type: object
Structured filter predicate used to constrain dataset results by column, operator, and value
Show Source
  • Required dataset column name to filter on. Column-name validation is case-insensitive.
    Example: STUDY_ID
  • Allowed Values: [ ">", "<", "=", ">=", "<=", "<>", "!=", "IN", "NOT IN", "BETWEEN", "NOT BETWEEN", "LIKE", "NOT LIKE", "IS", "IS NOT" ]
    Required comparison operator. Use one value for =, !=, <>, >, >=, <, <="," like, and not like; one or more values for in in; exactly two between between; value equal to null is not.< div>
    Example: =
  • value
    Filter values as strings. Value cardinality depends on the operator: one for most operators, one or more for IN/NOT IN, exactly two for BETWEEN/NOT BETWEEN, and exactly one value equal to NULL for IS/IS NOT.
Example:
[
    {
        "columnName":"STUDY_ID",
        "operator":"=",
        "value":[
            "A86F2D0BB610404DB62D37AFA9C20B50"
        ]
    }
]
Nested Schema : value
Type: array
Filter values as strings. Value cardinality depends on the operator: one for most operators, one or more for IN/NOT IN, exactly two for BETWEEN/NOT BETWEEN, and exactly one value equal to NULL for IS/IS NOT.
Show Source
  • Filter values as strings. Value cardinality depends on the operator: one for most operators, one or more for IN/NOT IN, exactly two for BETWEEN/NOT BETWEEN, and exactly one value equal to NULL for IS/IS NOT.
    Example: ["A86F2D0BB610404DB62D37AFA9C20B50"]
Example:
[
    "A86F2D0BB610404DB62D37AFA9C20B50"
]
Examples

Back to Top

Response

Supported Media Types

200 Response

Response behavior

  • The response is tabular. columns defines the selected output order, and each row in data follows that same order.
  • Every value in data is returned as a JSON string or null, including logical numbers and date/time values.
  • hasMore = "true" means more matching rows exist after the current page.
  • If filters match no rows, or offset is beyond the last row, the API returns HTTP 200 with data = [], count = 0, and hasMore = "false".

Section index

Study context | Form context | Item context | Codelist context | Audit context | Reference and system identifiers

Study context

Study-level identifiers and version metadata associated with the dataset row.

Column Name Data Type Description
STUDY_NAMEVARCHAR2(64 CHAR)Study identifier associated with the dataset row.
STUDY_VERSIONVARCHAR2(32 CHAR)Indicates the study version associated with the dataset row.

Parent topic: Section index


Form context

Form-level attributes associated with the codelist value row.

Column Name Data Type Description
FORM_NAMEVARCHAR2(64 CHAR)The name of the form, as specified by the study designer.
FORM_REFERENCE_CODEVARCHAR2(64 CHAR)A form's reference code, as specified by the study designer.
IS_REPEATINGNUMBER(1)Indicates whether the form is repeating. Possible values include 0 or 1.

Parent topic: Section index


Item context

Question-level attributes associated with the codelist value row.

Column Name Data Type Description
QUESTION_NAMEVARCHAR2(64 CHAR)Indicates the title of the question, as entered by a study designer.
QUESTION_REFERENCE_CODEVARCHAR2(64 CHAR)A question's reference code, as specified by the study designer when they created the question.
QUESTION_REQUIREDNUMBERIndicates if the question is required. Possible values include 0 or 1.

Parent topic: Section index


Codelist context

Codelist value, code metadata, and codelist-level descriptive attributes associated with the row.

Column Name Data Type Description
CODE_LIST_TITLEVARCHAR2(64 CHAR)Title of the codelist associated with the question.
LAB_NORMALS_TAGSVARCHAR2(1000 CHAR)Lab normals tags associated with the codelist.
CODE_LIST_DESCRIPTIONVARCHAR2(4000 CHAR)Description of the codelist associated with the question.
CODE_VALUEVARCHAR2(4000 CHAR)The code value.
CODE_DESCRIPTIONVARCHAR2(4000 CHAR)The description of the code record.
CODEVARCHAR2(255 CHAR)Custom defined identifier for a code in Clinical One Cloud Service.

Parent topic: Section index


Audit context

Audit-trail metadata describing row versioning, acting users, and reason-for-change details.

Column Name Data Type Description
VERSION_STARTTIMESTAMP(6)Audit trail timestamp when this version of the dataset row became effective. Together with VERSION_END, it defines the validity window for the row version.
VERSION_ENDTIMESTAMP(6)Indicates the date and time of when data was changed, if the data is not current.
OPERATION_TYPEVARCHAR2(16 CHAR)

Audit trail field that indicates how the dataset row version was produced.

  • CREATED: the row was initially created.
  • MODIFIED: an existing row was updated.
  • REMOVED: the row was removed from the active record set.
USER_NAMEVARCHAR2(255 CHAR)

Audit trail field that represents the user who performed the action.

The value for this column may represent a user's actual username or a user's email address, depending on how the user login was defined in Oracle Life Sciences IAMS.

OBJECT_VERSION_NUMBERNUMBERAudit trail field that represents the version number of the data.
REASONVARCHAR2(255 CHAR)Audit trail reason recorded for the dataset row change. Populated when a reason for change is provided for the row update.
COMMENTVARCHAR2(2048 CHAR)Comment for record change.
IS_CURRENTCHAR(1 CHAR)Audit trail flag that indicates whether the dataset row version is the current version (Y) or a historical version (N).

Parent topic: Section index


Reference and system identifiers

System identifiers, numeric reference keys, and technical linkage fields carried with the dataset row.

Column Name Data Type Description
STUDY_IDRAW(16 BYTE)GUID of the study.
STUDY_WIDNUMBER(10)A number that represents the unique identifier of the study.
FORM_IDRAW(16 BYTE)GUID of the form.
FORM_WIDNUMBER(10)A number that represents the unique identifier of the form.
ITEM_IDRAW(16 BYTE)GUID of the item.
ITEM_WIDNUMBER(10)A number that represents the unique identifier of the item.
CODELIST_IDRAW(16 BYTE)GUID of the codelist.
CODELIST_WIDNUMBERA number that represents the unique identifier of the codelist.
CODELISTITEM_IDRAW(16 BYTE)GUID of the codelist item.
CODELISTITEM_WIDNUMBER(10)A number that represents the unique identifier of the codelist item.
USER_IDRAW(16 BYTE)GUID of the user who performed the action.
USER_WIDNUMBER(10)A number that represents the unique identifier of the user who performed the action.
DH_TIMESTAMPTIMESTAMP(6)Data Hub timestamp for the dataset row.
SOFTWARE_VERSION_NUMBERNUMBERClinical One software version number associated with the dataset row.

Parent topic: Section index


Body ()
Root Schema : DataHubReportDto
Type: object

Tabular dataset response for a dynamic Data Hub query.

columns defines the selected output order, and each row in data aligns positionally to that list.

Show Source
  • columns

    Ordered dataset column names selected by the client.

    Each row in data uses this exact order.

  • Number of rows returned in the current page.

    Example: 2
  • data

    Row data aligned positionally with columns.

    Each cell is serialized as a JSON string or null, even for logical numbers and timestamps.

  • String pagination flag ("true" or "false") indicating whether more matching rows exist after the current page.

    Returned as a string for backward compatibility.

    Example: false

  • Requested page size.

    Dataset endpoints commonly use 0 to mean unpaginated or all rows.

    Example: 100

  • Zero-based row offset applied to the result set.

    Dataset endpoints that disable pagination with limit = 0 typically echo offset = 0 in the response.

    Example: 0

  • Total number of matching rows across all pages after filters are applied.

    This can be non-zero even when the current page is empty because the requested offset is beyond the last row.

    Example: 2
Nested Schema : columns
Type: array

Ordered dataset column names selected by the client.

Each row in data uses this exact order.

Show Source

  • Ordered dataset column names selected by the client.

    Each row in data uses this exact order.

    Example: ["STUDY_ID","RECORD_ID","STATUS"]
Example:
[
    "STUDY_ID",
    "RECORD_ID",
    "STATUS"
]
Nested Schema : data
Type: array

Row data aligned positionally with columns.

Each cell is serialized as a JSON string or null, even for logical numbers and timestamps.

Show Source
  • items

    Row data aligned positionally with columns.

    Each cell is serialized as a JSON string or null, even for logical numbers and timestamps.

Example:
[
    [
        "A86F2D0BB610404DB62D37AFA9C20B50",
        "REC001",
        "Active"
    ],
    [
        "A86F2D0BB610404DB62D37AFA9C20B50",
        "REC002",
        "Inactive"
    ]
]
Nested Schema : items
Type: array

Row data aligned positionally with columns.

Each cell is serialized as a JSON string or null, even for logical numbers and timestamps.

Show Source

  • Row data aligned positionally with columns.

    Each cell is serialized as a JSON string or null, even for logical numbers and timestamps.

    Example: [["A86F2D0BB610404DB62D37AFA9C20B50","REC001","Active"],["A86F2D0BB610404DB62D37AFA9C20B50","REC002","Inactive"]]
Example:
[
    [
        "A86F2D0BB610404DB62D37AFA9C20B50",
        "REC001",
        "Active"
    ],
    [
        "A86F2D0BB610404DB62D37AFA9C20B50",
        "REC002",
        "Inactive"
    ]
]
Examples

400 Response

Returned when the request is invalid.

  • Causes include invalid tenantId or studyId, negative limit or offset, empty selectColumns, invalid dataset columns, invalid whereColumns operator/value combinations, duplicate orderColumns, invalid sortOrder, and malformed typed filter values.
  • Error payload format: {"status":"failed","result":null,"errorData":{"errorCode":"...","errorMessage":"...","details":{...}},"version":1}.
Body ()
Root Schema : DataHubResponse
Type: object

Standard Data Hub response envelope.

Successful responses return status as "success" and populate result. Failed responses return status as "failed" and populate errorData.

Show Source
Nested Schema : errorData
Type: object

Machine-readable error payload when status is "failed".

This field is null when status is "success".

Example:
{
    "errorCode":"VALIDATION_ERROR",
    "errorMessage":"Invalid column name specified in the select columns: SITE_ID1",
    "details":{
        "field":"selectColumns"
    }
}
Nested Schema : result
Type: object

Payload returned by the API when status is "success".

This field is null when status is "failed".

Example:
{
    "message":"Operation succeeded"
}
Examples

401 Response

Returned when the request cannot be authenticated.

The response body is empty.

403 Response

Returned when the request is authenticated but the caller is not authorized to access the requested resource.

The response body contains a plain-text authorization message.

Possible response bodies:

  • Either the resource does not exist, or the user cannot access the resource.
  • The entity is in maintenance mode, or the user cannot access the resource.
Body ()
Root Schema : schema
Type: string

500 Response

Returned when an unexpected server-side error occurs while processing the request.

The response body contains the platform error payload with the error code and description.

Body ()
Root Schema : Status
Type: object
Show Source
Examples

Back to Top