REST API for Clinical One Cloud Service

V9.0

get

/ec-dc-svc/rest/v9.0/studies/{studyId}/{mode}/subjects/sitestudyversion

Retrieves a list of subject and also searches for subjects based on input parameters. This API request returns mHealthSubjectId as part of the response body for the sites having a study version. Also filters subject based on site and state. The supported parameters are 'readyToSign', 'readyToVerify', 'signed', 'verified', 'freezed' and 'signedandverified'. Use v9 to get operational fields that support replacement-randomization including additional fields replaceRand, unResolvedQueries, incompleteVisits, canBeReplaced, canBeUndoWithdrawn

Request

Path Parameters

mode(required): string
Indicates the operational mode of the study. Accepted values: active, test, or training.
Example:
```
active
```
studyId(required): string(UUID)
Unique identifier of the study. Uses UUID in a 32-character uppercase hexadecimal string format.
Example:
```
ABCDEF1234567890ABCDEF1234567890
```

Query Parameters

containsSearchKeyword: array[string]
List of search words containing the subject number.
Example:
```
[
    "SUBJ"
]
```
exactSearchKeyword: array[string]
List of search words matching exactly the subject number.
Example:
```
[
    "SUBJ-001",
    "SUBJ-002"
]
```
limit: integer(int64)
Minimum Value: 0

Maximum number of records to display per page.
Example:
```
25
```
offset: integer(int64)
Minimum Value: 0

An order number to specify with which object you want to start retrieving result. If provided, you also need to specify a value for the limit parameter.
Example:
```
0
```
order: string
asc or desc
Example:
```
ASC
```
reviewStatus: string
Review status filter applied to subjects.values can be noopenqueries, openqueries, verified, signed, locked, allvisitscomplete, readytosign, allvisitscomplete, readytoverify
Example:
```
ALL
```
signVerifyStatus: string
Status of Sign / Verify.
Example:
```
ALL
```
siteId: array[string]
Unique identifier of the site. Uses UUID in a 32-character uppercase hexadecimal string format.
Example:
```
[\"ABCDEF1234567890ABCDEF1234567891\"]
```
subjectState: array[string]
States of subjects to filter by Active, New, Screening_Initiated, Enrolled, Complete, Withdrawn, ehrLinked, ehrNotLinked, Screen_Failed, Auto_Screen_Failed
Example:
```
[
    "Active",
    "Screened"
]
```

There's no request body for this operation.

Response

Supported Media Types

application/json

200 Response

Success

Root Schema : schema

Type: array

Show Source

Array of: object SubjectRespDto14

Subject response details including fields like replacement randomization, unresolved queries etc..

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/SubjectRespDto14"
    }
}

Nested Schema : SubjectRespDto14

Type: object

Subject response details including fields like replacement randomization, unresolved queries etc..

Show Source

canBeCompleted: boolean

Indicates if the subject has met conditions to be completed

Example: true
canBeReplaced: boolean

Indicates if the subject can be replaced

Example: true
canBeUndoWithdrawn: boolean

Indicates if a withdrawn subject can be undone

Example: true
comment: string

Minimum Length: 0

Maximum Length: 2048

Comment for latest subject update

Example: Initial enrollment
description: string

Minimum Length: 0

Maximum Length: 500

Free text description for the subject

Example: Screened subject
dob: string (date-time)

Date of birth
ehrLinkStatus: number

EHR link status code for the subject

Example: 1
enrollmentFailure: string

Minimum Length: 0

Maximum Length: 255

Reason for enrollment failure, if any

Example: Consent withdrawn
enrollmentOverride: string

Minimum Length: 0

Maximum Length: 255

If subject enrollment is overridden.

Example: Subject Enrollment Overridden
eventType: string

Event Type for Subject, can have value New, Screened, Randomized, Withdrawn, Undo_Withdrawn, Randomization_Replaced, Transferred, Screen_Failed, Undo_Randomization.

Example: Screened
freezedStatus: string

Frozen status of the record can have values NOT_APPLICABLE, FROZEN, UNFREEZE.

Example: FROZEN
fromStudyId: string

Origin study identifier (UUID, 32-character uppercase hexadecimal string) from which the subject was transferred

Example: 5D5F9311C591424F852B99FD902E98A4
gender: string

Minimum Length: 0

Maximum Length: 10

Gender value

Example: [{"value":"1","label":"male"}]
hasLockData: boolean

Indicates whether lock related data exists for the subject

Example: false
id: string

Unique identifier (UUID, 32-character uppercase hexadecimal string) of the subject

Example: 1BC29B36F5D64B1B95F4BDBBCEA481BE
incompleteVisits: integer (int32)

Number of incomplete visits for the subject

Example: 1
informedConsentDate: string (date-time)

Informed consent date

Example: 2025-09-25T09:00:00Z
lastSigned: string (date-time)

Timestamp when the subject was last signed

Example: 2025-10-16T14:30:31.892Z
lockedDateTime: string (date-time)

Timestamp when the subject was locked

Example: 2025-10-16T14:30:31.892Z
lockedInStudyVersion: string

Study version in which the subject is locked

Example: 3.0.0.4
lockedStatus: string

Lock status of the subject,applicable values are LOCKED, UNLOCKED

Example: UNLOCKED
mhealthSubjectId: string

Unique Identifier (UUID, 32-character uppercase hexadecimal string) of the subject in mHealth system.

Example: 1BC29B36F5D64B1B95F4BDBBCEA481BE
objectVersionNumber: number

Audit trail field that represents the version number of the data.

Example: 14
operationType: string

Operation type on the record, can have values CREATED, MODIFIED or REMOVED

Example: MODIFIED
previousSubjectNumber: string

Previous subject number if renumbered or transferred

Example: SUBJECT-0001-OLD
randomizationNumber: string

Randomization number assigned to the subject if applicable.

Example: RND-001
reason: string

Minimum Length: 0

Maximum Length: 255

Reason for latest subject update

Example: Protocol break happened
replaceRand: string

Replacement randomization identifier if applicable

Example: Y
screenFailureComment: string

Additional comment for screen failure

Example: Subject breached protocols
screenFailureDate: string (date-time)

Date when the subject was marked as screen failure

Example: 2025-10-16T14:30:31.892Z
screeningDate: string (date-time)

Screening date if applicable

Example: 2025-10-01T10:00:00Z
screeningFailure: string

Minimum Length: 0

Maximum Length: 255

Reason for screening failure, if any

Example: Inclusion criteria not met
screeningNumber: string

Screening number assigned to the subject

Example: SCR-0001
signedStatus: string

Signed status for workflow, the acceptable values are: NEVER_SIGNED, SIGNED, UNSIGNED, NEVER_SIGNED.

Example: SIGNED
siteId: string

Unique identifier of the site. Uses UUID in a 32-character uppercase hexadecimal string format.

Example: ABCDEF1234567890ABCDEF1234567890
softwareVersionNumber: number

Software version number associated with the event

Example: 14
sourceTimeStamp: string (date-time)

Source system timestamp for the subject payload

Example: 2025-10-16T14:30:31.892Z
state(required): string
Minimum Length: 0

Maximum Length: 100
Lifecycle state of the subject in the study. Reflects the subject???s current status. Common values include:
- New
- Active
- Screening_Initiated
- Screen_Failed
- Withdrawn
- Auto_Screen_Failed
- Complete
- Enrolled
Example: Active
stateDate: string (date-time)

Timestamp when the subject transitioned to current state

Example: 2025-10-16T14:30:31.892Z
studyCompletionDate: string (date-time)

Date when the subject completed the study

Example: 2025-10-16T14:30:31.892Z
studyId: string

Unique identifier of the study. Uses UUID in a 32-character uppercase hexadecimal string format.

Example: ABCDEF1234567890ABCDEF1234567890
studyVersion(required): string

String representing the version of the study. Helps track changes in form or study design.

Example: 3.0.0.1
subjectNumber(required): string

Minimum Length: 0

Maximum Length: 500

Unique subject Number representing the patient/participant enrolled in the study.

Example: SUBJ-0001
subjectSiteSerialNumber: string

Site-level serial number assigned to the subject

Example: SITE-0001-001
subjectStudySerialNumber: string

Study-level serial number assigned to the subject

Example: STUDY-0001-001
subjectTransferId: string

Unique Identifier(UUID, 32-character uppercase hexadecimal string) of a subject transfer if applicable

Example: 1BC29B36F5D64B1B95F4BDBBCEA481BE
subjNumSiteOrgId: string

Subject number site organization identifier (UUID, 32-character uppercase hexadecimal string)

Example: 5D5F9311C591424F852B99FD902E98A4
unResolvedQueries: integer (int32)

Number of unresolved queries for the subject

Example: 2
verifiedStatus: string

Verified status for review workflow,the acceptable values are: NEVER_VEIFIED, VERIFIED, UNVERIFIED, NOT_APPLICABLE.

Example: VERIFIED
versionEnd: string (date-time)

End timestamp of the subject version record

Example: 2025-10-16T14:30:31.892Z
versionStart: string (date-time)

The timestamp marking the beginning of the validity period for this record version within the system.

Example: 2025-10-16T14:30:31.892Z
withdrawalComment: string

Additional comment provided for withdrawal

Example: Subject breached protocols
withdrawalDate: string (date-time)

Date when the subject was withdrawn

Example: 2025-10-16T14:30:31.892Z
withdrawalReason: string

Reason provided when the subject is withdrawn

Example: Not applicable

{
    "required":[
        "state",
        "studyVersion",
        "subjectNumber"
    ],
    "type":"object",
    "properties":{
        "screeningDate":{
            "type":"string",
            "description":"Screening date if applicable",
            "format":"date-time",
            "example":"2025-10-01T10:00:00Z"
        },
        "eventType":{
            "type":"string",
            "description":"Event Type for Subject, can have value New, Screened, Randomized, Withdrawn, Undo_Withdrawn, Randomization_Replaced, Transferred, Screen_Failed, Undo_Randomization.",
            "example":"Screened"
        },
        "subjectTransferId":{
            "type":"string",
            "description":"Unique Identifier(UUID, 32-character uppercase hexadecimal string) of a subject transfer if applicable",
            "example":"1BC29B36F5D64B1B95F4BDBBCEA481BE"
        },
        "objectVersionNumber":{
            "type":"number",
            "description":"Audit trail field that represents the version number of the data.",
            "example":14
        },
        "mhealthSubjectId":{
            "type":"string",
            "description":"Unique Identifier (UUID, 32-character uppercase hexadecimal string)  of the subject in mHealth system.",
            "example":"1BC29B36F5D64B1B95F4BDBBCEA481BE"
        },
        "fromStudyId":{
            "type":"string",
            "description":"Origin study identifier (UUID, 32-character uppercase hexadecimal string) from which the subject was transferred",
            "example":"5D5F9311C591424F852B99FD902E98A4"
        },
        "subjNumSiteOrgId":{
            "type":"string",
            "description":"Subject number site organization identifier (UUID, 32-character uppercase hexadecimal string) ",
            "example":"5D5F9311C591424F852B99FD902E98A4"
        },
        "signedStatus":{
            "type":"string",
            "description":"Signed status for workflow, the acceptable values are:  NEVER_SIGNED, SIGNED, UNSIGNED, NEVER_SIGNED.",
            "example":"SIGNED"
        },
        "verifiedStatus":{
            "type":"string",
            "description":"Verified status for review workflow,the acceptable values are: NEVER_VEIFIED, VERIFIED, UNVERIFIED, NOT_APPLICABLE.",
            "example":"VERIFIED"
        },
        "freezedStatus":{
            "type":"string",
            "description":"Frozen status of the record can have values NOT_APPLICABLE, FROZEN, UNFREEZE.",
            "example":"FROZEN"
        },
        "lastSigned":{
            "type":"string",
            "description":"Timestamp when the subject was last signed",
            "format":"date-time",
            "example":"2025-10-16T14:30:31.892Z"
        },
        "softwareVersionNumber":{
            "type":"number",
            "description":"Software version number associated with the event",
            "example":14
        },
        "operationType":{
            "type":"string",
            "description":"Operation type on the record, can have values CREATED, MODIFIED or REMOVED",
            "example":"MODIFIED"
        },
        "subjectStudySerialNumber":{
            "type":"string",
            "description":"Study-level serial number assigned to the subject",
            "example":"STUDY-0001-001"
        },
        "subjectSiteSerialNumber":{
            "type":"string",
            "description":"Site-level serial number assigned to the subject",
            "example":"SITE-0001-001"
        },
        "versionEnd":{
            "type":"string",
            "description":"End timestamp of the subject version record",
            "format":"date-time",
            "example":"2025-10-16T14:30:31.892Z"
        },
        "previousSubjectNumber":{
            "type":"string",
            "description":"Previous subject number if renumbered or transferred",
            "example":"SUBJECT-0001-OLD"
        },
        "screenFailureDate":{
            "type":"string",
            "description":"Date when the subject was marked as screen failure",
            "format":"date-time",
            "example":"2025-10-16T14:30:31.892Z"
        },
        "lockedStatus":{
            "type":"string",
            "description":"Lock status of the subject,applicable values are LOCKED, UNLOCKED",
            "example":"UNLOCKED"
        },
        "hasLockData":{
            "type":"boolean",
            "description":"Indicates whether lock related data exists for the subject",
            "example":false
        },
        "lockedDateTime":{
            "type":"string",
            "description":"Timestamp when the subject was locked",
            "format":"date-time",
            "example":"2025-10-16T14:30:31.892Z"
        },
        "canBeCompleted":{
            "type":"boolean",
            "description":"Indicates if the subject has met conditions to be completed",
            "example":true
        },
        "lockedInStudyVersion":{
            "type":"string",
            "description":"Study version in which the subject is locked",
            "example":"3.0.0.4"
        },
        "canBeReplaced":{
            "type":"boolean",
            "description":"Indicates if the subject can be replaced",
            "example":true
        },
        "canBeUndoWithdrawn":{
            "type":"boolean",
            "description":"Indicates if a withdrawn subject can be undone",
            "example":true
        },
        "id":{
            "type":"string",
            "description":"Unique identifier (UUID, 32-character uppercase hexadecimal string) of the subject",
            "example":"1BC29B36F5D64B1B95F4BDBBCEA481BE"
        },
        "versionStart":{
            "type":"string",
            "description":"The timestamp marking the beginning of the validity period for this record version within the system.",
            "format":"date-time",
            "example":"2025-10-16T14:30:31.892Z"
        },
        "description":{
            "maxLength":500,
            "minLength":0,
            "type":"string",
            "description":"Free text description for the subject",
            "example":"Screened subject"
        },
        "subjectNumber":{
            "maxLength":500,
            "minLength":0,
            "type":"string",
            "description":"Unique subject Number representing the patient/participant enrolled in the study.",
            "example":"SUBJ-0001"
        },
        "studyId":{
            "type":"string",
            "description":"Unique identifier of the study. Uses UUID in a 32-character uppercase hexadecimal string format.",
            "example":"ABCDEF1234567890ABCDEF1234567890"
        },
        "siteId":{
            "type":"string",
            "description":"Unique identifier of the site. Uses UUID in a 32-character uppercase hexadecimal string format.",
            "example":"ABCDEF1234567890ABCDEF1234567890"
        },
        "dob":{
            "type":"string",
            "description":"Date of birth",
            "format":"date-time"
        },
        "state":{
            "maxLength":100,
            "minLength":0,
            "type":"string",
            "description":"Lifecycle state of the subject in the study.  Reflects the subject???s current status. Common values include: <ul><li>New</li><li>Active</li><li>Screening_Initiated</li><li>Screen_Failed</li><li>Withdrawn</li><li>Auto_Screen_Failed</li><li>Complete</li><li>Enrolled</li></ul>",
            "example":"Active"
        },
        "stateDate":{
            "type":"string",
            "description":"Timestamp when the subject transitioned to current state",
            "format":"date-time",
            "example":"2025-10-16T14:30:31.892Z"
        },
        "screeningFailure":{
            "maxLength":255,
            "minLength":0,
            "type":"string",
            "description":"Reason for screening failure, if any",
            "example":"Inclusion criteria not met"
        },
        "enrollmentFailure":{
            "maxLength":255,
            "minLength":0,
            "type":"string",
            "description":"Reason for enrollment failure, if any",
            "example":"Consent withdrawn"
        },
        "enrollmentOverride":{
            "maxLength":255,
            "minLength":0,
            "type":"string",
            "description":"If subject enrollment is overridden.",
            "example":"Subject Enrollment Overridden"
        },
        "informedConsentDate":{
            "type":"string",
            "description":"Informed consent date",
            "format":"date-time",
            "example":"2025-09-25T09:00:00Z"
        },
        "gender":{
            "maxLength":10,
            "minLength":0,
            "type":"string",
            "description":"Gender value",
            "example":"[{\"value\":\"1\",\"label\":\"male\"}]"
        },
        "reason":{
            "maxLength":255,
            "minLength":0,
            "type":"string",
            "description":"Reason for latest subject update",
            "example":"Protocol break happened"
        },
        "comment":{
            "maxLength":2048,
            "minLength":0,
            "type":"string",
            "description":"Comment for latest subject update",
            "example":"Initial enrollment"
        },
        "studyVersion":{
            "type":"string",
            "description":"String representing the version of the study. Helps track changes in form or study design.",
            "example":"3.0.0.1"
        },
        "sourceTimeStamp":{
            "type":"string",
            "description":"Source system timestamp for the subject payload",
            "format":"date-time",
            "example":"2025-10-16T14:30:31.892Z"
        },
        "screeningNumber":{
            "type":"string",
            "description":"Screening number assigned to the subject",
            "example":"SCR-0001"
        },
        "randomizationNumber":{
            "type":"string",
            "description":"Randomization number assigned to the subject if applicable.",
            "example":"RND-001"
        },
        "withdrawalReason":{
            "type":"string",
            "description":"Reason provided when the subject is withdrawn",
            "example":"Not applicable"
        },
        "ehrLinkStatus":{
            "type":"number",
            "description":"EHR link status code for the subject",
            "example":1
        },
        "withdrawalDate":{
            "type":"string",
            "description":"Date when the subject was withdrawn",
            "format":"date-time",
            "example":"2025-10-16T14:30:31.892Z"
        },
        "studyCompletionDate":{
            "type":"string",
            "description":"Date when the subject completed the study",
            "format":"date-time",
            "example":"2025-10-16T14:30:31.892Z"
        },
        "withdrawalComment":{
            "type":"string",
            "description":"Additional comment provided for withdrawal",
            "example":"Subject breached protocols"
        },
        "screenFailureComment":{
            "type":"string",
            "description":"Additional comment for screen failure",
            "example":"Subject breached protocols"
        },
        "replaceRand":{
            "type":"string",
            "description":"Replacement randomization identifier if applicable",
            "example":"Y"
        },
        "unResolvedQueries":{
            "type":"integer",
            "description":"Number of unresolved queries for the subject",
            "format":"int32",
            "example":2
        },
        "incompleteVisits":{
            "type":"integer",
            "description":"Number of incomplete visits for the subject",
            "format":"int32",
            "example":1
        }
    },
    "description":"Subject response details including fields like replacement randomization, unresolved queries etc.."
}

Examples

400 Response

Bad request.

Root Schema : DcsResponse

Type: object

Show Source

errorData: object ErrorResponseData

Title: ErrorResponseData

Error Response Details Information
result: object result
status: string
version: integer (int32)

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string"
        },
        "result":{
            "type":"object"
        },
        "version":{
            "type":"integer",
            "format":"int32",
            "writeOnly":true
        },
        "errorData":{
            "$ref":"#/components/schemas/ErrorResponseData"
        }
    }
}

Nested Schema : ErrorResponseData

Type: object

Title: ErrorResponseData

Error Response Details Information

Show Source

details: object Object

Title: Object

Object with error details information.
errorCode: string

Error code which is stored in ErrorCode enum. Example : C1-003

Example: C1-003
errorMessage: string

Error message which is stored in service property file. Example : Cannot modify object after a study version has been approved

Example: Cannot modify object after a study version has been approved

{
    "title":"ErrorResponseData",
    "type":"object",
    "properties":{
        "errorCode":{
            "type":"string",
            "description":"Error code which is stored in ErrorCode enum. Example : C1-003",
            "example":"C1-003"
        },
        "errorMessage":{
            "type":"string",
            "description":"Error message which is stored in service property file. Example : Cannot modify object after a study version has been approved",
            "example":"Cannot modify object after a study version has been approved"
        },
        "details":{
            "title":"Object",
            "type":"object",
            "description":"Object with error details information.",
            "example":{
                "field":"studyId",
                "reason":"Invalid value"
            }
        }
    },
    "description":"Error Response Details Information"
}

Nested Schema : result

Type: object

Nested Schema : Object

Type: object

Title: Object

Object with error details information.

Example:

{
    "field":"studyId",
    "reason":"Invalid value"
}