1. REST API for Clinical One Cloud Service
  2. Tasks
  3. Data Hub
  4. Datasets
  5. Get codelists for tenant

V1.0

post

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

Retrieves the tenant-permissioned Tenant Codelists dataset for a tenant.

The dataset exposes versioned tenant codelist configuration, including codelist definitions, localized code values, display metadata, grouping metadata, hidden flags, LOINC metadata, and audit columns.

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

The dataset returns rows for system and tenant-level codelists available to the tenant.

Required permission: TenantCodelistDatasetPost.

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 CODE_LEVEL, CODE_ID, CODE_VALUE_ID, and LOCALE in the orderColumns field of the request payload.

Request

Path Parameters

  • Unique tenant identifier supplied in the tenantId path parameter.

    Use the uppercase hexadecimal UUID value for the tenant.

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

Codelist context | Audit context | Reference and system identifiers

Codelist context

Codelist values, localization fields, display metadata, and codelist-level grouping metadata associated with the tenant row.

Column Name Data Type Description
CODE_NAMEVARCHAR2(255 CHAR)Codelist name.
DISPLAY_CODE_NAMEVARCHAR2(255 CHAR)Indicates the display name shown for the codelist. When no display-specific name exists, the codelist name is used.
CODE_LABELVARCHAR2(4000)The code label associated with the codelist value.
CODE_VALUEVARCHAR2(4000)The displayed codelist value.
CODEVARCHAR2(255 CHAR)Indicates the code configured for the codelist value.
CODE_DESCRIPTIONVARCHAR2(4000 CHAR)Codelist description.
CODE_GROUP_NAMEVARCHAR2(255 CHAR)Represents the code group name to which the record belongs.
CODE_LEVELVARCHAR2(32 CHAR)Describes whether the record is at a system or custom level codelist. Values are SYSTEM or CUSTOM.
LOCALEVARCHAR2(255 CHAR)Code locale. English, Chinese and Japanese languages are supported.
LOINCVARCHAR2(400 CHAR)Indicates the LOINC code associated with the codelist value.
TAGVARCHAR2(4000)Tag associated with the codelist value.
CL_HIDDENNUMBER(1)Indicates whether the codelist value is hidden. Values are 0 or 1.
SEQUENCENUMBERSequence order of the codelist record.

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 captured for the change reason when provided; when the change is generated by rule execution, the system may populate this field with Rule Execution.
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
CODE_VALUE_IDRAW(16 BYTE)GUID of the codelist value.
CODE_VALUE_WIDNUMBER(10)A number that represents the unique identifier of the codelist value.
CODE_IDRAW(16 BYTE)GUID of the codelist.
CODE_WIDNUMBER(10)A number that represents the unique identifier of the codelist.
CODE_GROUP_IDRAW(16 BYTE)GUID of the codelist group.
CODE_GROUP_WIDNUMBER(10)A number that represents the unique identifier of the codelist group.
USER_IDRAW(16 BYTE)GUID of the user.
USER_WIDNUMBER(10)Indicates a user's numeric identifier.
DH_TIMESTAMPTIMESTAMP(6)A timestamp that indicates when the data became available in the dataset.
SOFTWARE_VERSION_NUMBERNUMBERA number that increases incrementally every time a data point is modified.

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