REST API for Clinical One Platform

Create a study role group for an organization

post

/ec-auth-svc/rest/v1.0/studyroles

Creates a new study role group at the tenant level with the specified configuration. You must provide all required fields in the request body. This API is intended for creating roles not bound to any specific study.

Request

Query Parameters

localize: boolean

Default Value: false

Supported Media Types

application/json

Root Schema : schema

Type: object

DTO to create a new study role with requested settings and related roles.

Show Source

comment: string

Minimum Length: 0

Maximum Length: 2048

Additional comments about the study role.

Example: Primary coordinator assignment for site.
reason: string

Minimum Length: 0

Maximum Length: 255

Reason for creating or updating this study role.

Example: Configured at initial setup.
roleList(required): object RoleIdDto

Simple DTO containing only the role's unique identifier.
studyRoleCreationType: string

Indicates how the study role was created.

Example: MANUAL
studyRoleDesc: string

Minimum Length: 0

Maximum Length: 500

Description of the study role.

Example: Can manage subject and site data.
studyRoleName(required): string

Minimum Length: 0

Maximum Length: 100

Name of the study role.

Example: SITE_COORDINATOR
studyRoleStatus: string

Status of the study role.

Example: ACTIVE
studyRoleType(required): string

Type of the study role.

Example: SITE

{
    "required":[
        "roleList",
        "studyRoleName",
        "studyRoleType"
    ],
    "type":"object",
    "properties":{
        "studyRoleName":{
            "maxLength":100,
            "minLength":0,
            "type":"string",
            "description":"Name of the study role.",
            "example":"SITE_COORDINATOR"
        },
        "studyRoleDesc":{
            "maxLength":500,
            "minLength":0,
            "type":"string",
            "description":"Description of the study role.",
            "example":"Can manage subject and site data."
        },
        "studyRoleType":{
            "type":"string",
            "description":"Type of the study role.",
            "example":"SITE"
        },
        "studyRoleStatus":{
            "type":"string",
            "description":"Status of the study role.",
            "example":"ACTIVE"
        },
        "studyRoleCreationType":{
            "type":"string",
            "description":"Indicates how the study role was created.",
            "example":"MANUAL"
        },
        "roleList":{
            "$ref":"#/components/schemas/RoleIdDto"
        },
        "reason":{
            "maxLength":255,
            "minLength":0,
            "type":"string",
            "description":"Reason for creating or updating this study role.",
            "example":"Configured at initial setup."
        },
        "comment":{
            "maxLength":2048,
            "minLength":0,
            "type":"string",
            "description":"Additional comments about the study role.",
            "example":"Primary coordinator assignment for site."
        }
    },
    "description":"DTO to create a new study role with requested settings and related roles.",
    "example":{
        "studyRoleName":"SITE_COORDINATOR",
        "studyRoleDesc":"Can manage subject and site data.",
        "studyRoleType":"SITE",
        "studyRoleStatus":"ACTIVE",
        "studyRoleCreationType":"MANUAL",
        "roleList":[
            {
                "roleId":"C2F3B799BCED4C868E668A002A3F30F3"
            }
        ],
        "reason":"Configured at initial setup.",
        "comment":"Primary coordinator assignment for site."
    }
}

Example:

{
    "studyRoleName":"SITE_COORDINATOR",
    "studyRoleDesc":"Can manage subject and site data.",
    "studyRoleType":"SITE",
    "studyRoleStatus":"ACTIVE",
    "studyRoleCreationType":"MANUAL",
    "roleList":[
        {
            "roleId":"C2F3B799BCED4C868E668A002A3F30F3"
        }
    ],
    "reason":"Configured at initial setup.",
    "comment":"Primary coordinator assignment for site."
}

Nested Schema : RoleIdDto

Type: object

Simple DTO containing only the role's unique identifier.

Show Source

roleId(required): string (uuid)

Unique identifier for the role.

{
    "required":[
        "roleId"
    ],
    "type":"object",
    "properties":{
        "roleId":{
            "type":"string",
            "description":"Unique identifier for the role.",
            "format":"uuid"
        }
    },
    "description":"Simple DTO containing only the role's unique identifier.",
    "example":{
        "roleId":"078123AF1E024F7C8D0053D74A11AEC3"
    }
}

Example:

{
    "roleId":"078123AF1E024F7C8D0053D74A11AEC3"
}

Examples

Response

Supported Media Types

application/json

200 Response

Successful creation of the study role.

Root Schema : schema

Type: object

Describes a study role with its associated details and constituent roles.

Show Source

comment: string

Minimum Length: 0

Maximum Length: 2048

Additional comments about the study role.

Example: This group was created as part of baseline configuration.
reason: string

Minimum Length: 0

Maximum Length: 255

Reason for assigning or modifying this study role.

Example: Initial assignment.
roleList(required): object RoleObjectNumDto

Represents a role reference along with its object version number.
studyRoleCreationType: string

How the study role was created (e.g., MANUAL, AUTO).

Example: MANUAL
studyRoleDesc: string

Minimum Length: 0

Maximum Length: 500

Description of the study role.

Example: A role allowing access to all site-specific data.
StudyRoleID(required): string (uuid)

Unique identifier for this study role.
studyRoleName(required): string

Minimum Length: 0

Maximum Length: 100

Name of the study role.

Example: SITE_VIEWER
studyRoleType(required): string

Type of the study role.

Example: SITE

{
    "required":[
        "roleList",
        "StudyRoleID",
        "studyRoleName",
        "studyRoleType"
    ],
    "type":"object",
    "properties":{
        "StudyRoleID":{
            "type":"string",
            "description":"Unique identifier for this study role.",
            "format":"uuid"
        },
        "studyRoleName":{
            "maxLength":100,
            "minLength":0,
            "type":"string",
            "description":"Name of the study role.",
            "example":"SITE_VIEWER"
        },
        "studyRoleDesc":{
            "maxLength":500,
            "minLength":0,
            "type":"string",
            "description":"Description of the study role.",
            "example":"A role allowing access to all site-specific data."
        },
        "studyRoleType":{
            "type":"string",
            "description":"Type of the study role.",
            "example":"SITE"
        },
        "studyRoleCreationType":{
            "type":"string",
            "description":"How the study role was created (e.g., MANUAL, AUTO).",
            "example":"MANUAL"
        },
        "roleList":{
            "$ref":"#/components/schemas/RoleObjectNumDto"
        },
        "reason":{
            "maxLength":255,
            "minLength":0,
            "type":"string",
            "description":"Reason for assigning or modifying this study role.",
            "example":"Initial assignment."
        },
        "comment":{
            "maxLength":2048,
            "minLength":0,
            "type":"string",
            "description":"Additional comments about the study role.",
            "example":"This group was created as part of baseline configuration."
        }
    },
    "description":"Describes a study role with its associated details and constituent roles.",
    "example":{
        "StudyRoleID":"6D84A3F9D41E4BB8B5FC99A27DCC2B9B",
        "studyRoleName":"SITE_VIEWER",
        "studyRoleDesc":"A role allowing access to all site-specific data.",
        "studyRoleType":"SITE",
        "studyRoleCreationType":"MANUAL",
        "roleList":[
            {
                "roleId":"ED123C41A2304E21850F4A2B92FED971",
                "objectVersionNumber":1
            }
        ],
        "reason":"Initial assignment.",
        "comment":"This group was created as part of baseline configuration."
    }
}

Example:

{
    "StudyRoleID":"6D84A3F9D41E4BB8B5FC99A27DCC2B9B",
    "studyRoleName":"SITE_VIEWER",
    "studyRoleDesc":"A role allowing access to all site-specific data.",
    "studyRoleType":"SITE",
    "studyRoleCreationType":"MANUAL",
    "roleList":[
        {
            "roleId":"ED123C41A2304E21850F4A2B92FED971",
            "objectVersionNumber":1
        }
    ],
    "reason":"Initial assignment.",
    "comment":"This group was created as part of baseline configuration."
}

Nested Schema : RoleObjectNumDto

Type: object

Represents a role reference along with its object version number.

Show Source

objectVersionNumber(required): number

Current object version number for the role.

Example: 1
roleId(required): string (uuid)

Unique identifier for the role.

{
    "required":[
        "objectVersionNumber",
        "roleId"
    ],
    "type":"object",
    "properties":{
        "roleId":{
            "type":"string",
            "description":"Unique identifier for the role.",
            "format":"uuid"
        },
        "objectVersionNumber":{
            "type":"number",
            "description":"Current object version number for the role.",
            "example":1
        }
    },
    "description":"Represents a role reference along with its object version number.",
    "example":{
        "roleId":"ED123C41A2304E21850F4A2B92FED971",
        "objectVersionNumber":1
    }
}

Example:

{
    "roleId":"ED123C41A2304E21850F4A2B92FED971",
    "objectVersionNumber":1
}

Examples

400 Response

Invalid parameters supplied; see error response.

Root Schema : AuthResponse

Type: object

Generic API response wrapper containing result, error data, response version and status.

Show Source

errorData: object ErrorResponseData

Structure representing an error response from the reporting service. Contains an error code, human-readable message, and details.
result: object result

Result data of the API response; actual type depends on the API
status: string (none)

Indicates request success ("success") or failure ("failure").

Example: success
version: integer (int32)

Version of the response schema.

Example: 1

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string",
            "description":"Indicates request success (\"success\") or failure (\"failure\").",
            "format":"none",
            "example":"success"
        },
        "result":{
            "type":"object",
            "description":"Result data of the API response; actual type depends on the API",
            "example":null
        },
        "errorData":{
            "$ref":"#/components/schemas/ErrorResponseData"
        },
        "version":{
            "type":"integer",
            "description":"Version of the response schema.",
            "format":"int32",
            "example":1
        }
    },
    "description":"Generic API response wrapper containing result, error data, response version and status."
}

Nested Schema : ErrorResponseData

Type: object

Structure representing an error response from the reporting service. Contains an error code, human-readable message, and details.

Show Source

details: string

Detailed error context or debugging information such as validation error, stack trace, or field/parameter cause.

Example: User role is missing required permission REPORTING_VIEW. Field: userId
errorCode: string

Application or business-specific error code representing the error type.

Example: REPT_401
errorMessage: string

Human-readable error message describing the failure or issue.

Example: Unauthorized: User does not have access to the requested resource

{
    "type":"object",
    "properties":{
        "errorCode":{
            "type":"string",
            "description":"Application or business-specific error code representing the error type.",
            "example":"REPT_401"
        },
        "errorMessage":{
            "type":"string",
            "description":"Human-readable error message describing the failure or issue.",
            "example":"Unauthorized: User does not have access to the requested resource"
        },
        "details":{
            "type":"string",
            "description":"Detailed error context or debugging information such as validation error, stack trace, or field/parameter cause.",
            "example":"User role is missing required permission REPORTING_VIEW. Field: userId"
        }
    },
    "description":"Structure representing an error response from the reporting service. Contains an error code, human-readable message, and details."
}

Nested Schema : result

Type: object

Result data of the API response; actual type depends on the API

Example:

oracle.doceng.json.BetterJsonNull@3565a0f5