Jump to

• Request
• Response

v12.0

get

/ec-ors-svc/rest/v12.0/studies/{studyId}/{mode}/subjects/{externalSubjectId}/dispensation-history

Retrieves dispensation history for a study, by subject and visit ID. This version adds the includeRollback query parameter and response fields dispensationRollback, reason, comment and lastActionDate.
Rights: OrsSubjectVisitGet.

Request

Path Parameters

• externalSubjectId(required): string(uuid)
  Unique identifier of the subject. Used to represent a participant enrolled in a study. Uses UUID in a 32-character uppercase hexadecimal string format.

  Example:

  C36A3197FDEE433FB5547EE83DE99E4B

• mode(required): string
  Indicates the operational mode of the study. Accepted values: active, test, or training.

  Example:

  test

• studyId(required): string(uuid)
  Unique identifier of the study. Uses UUID in a 32-character uppercase hexadecimal string format.

  Example:

  B1B8327AFAA6412287106192AB5984EF

Query Parameters

• asofdate: string
  Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

  Get data as of the given date and time in yyyy-MM-dd'T'HH:mm:ss.SSS'Z' format.

  Example:

  2026-03-01T00:00:00.000Z

• includeRollback: boolean
  When true, includes dispensation rollback rows in the response.

  Default Value: false

  Example:

  false

• visitId: string
  Unique identifier (UUID, 32-character uppercase hexadecimal string) of the visit

  Example:

  B1B8327AFAA6412287106192AB5984EF

There's no request body for this operation.

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful operation

Body ()

Root Schema : schema

Type: array

Show Source

• Array of: object DispensationHistoryResponse v12.0
  Title: DispensationHistoryResponse v12.0

  Response object containing Dispensation History with dispensation rollback details.

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

Nested Schema : DispensationHistoryResponse v12.0

Type: object

Title: DispensationHistoryResponse v12.0

Response object containing Dispensation History with dispensation rollback details.

Show Source

• allowReplacement: boolean
  Title: Allow Replacement

  Indicates whether the kit is allowed for replacement.

  Example: true
• balanceUnits: number (double)
  Title: Balance Units

  Balanced units for the kit.

  Example: 1
• barcode: string
  Barcode.

  Example: 1236
• comment: string
  Title: Comment

  Comment.
• conserved: boolean
  Title: Conserved

  Conserved for dispensation.

  Example: true
• deviceConnection: string
  Title: Device Connection Type

  Allowed Values: [ "CloudtoCloud", "DevicetoCloud", "NoConnection" ]

  Device connection type.

  Example: DevicetoCloud
• deviceType: string
  Title: Device Type

  Allowed Values: [ "ActivityWatch", "BloodPressureMonitor", "WeightScale", "ECGReader", "Spirometer", "MobileApp", "SmartPillBottle", "PulseOximeter", "WearablePatch", "Other", "GlucoseMonitor" ]

  Device type.

  Example: WearablePatch
• dispensationConfirmed: boolean
  Indicates whether dispensation is confirmed.

  Example: true
• dispensationDate: string (date-time)
  Title: Dispensation Date

  Dispensation date.
• dispensationRollback: boolean
  Title: Dispensation Rollback

  Indicates whether the row is related to a rolled-back dispensation.
• dose: number (double)
  Title: Dose

  Dose.

  Example: 5
• dosingInstruction: string
  Title: Dosing Instruction

  Dosing instruction.

  Example: once daily
• dosingUnblinded: boolean
  Title: Dosing Unblinded

  Indicates whether dosing is unblinded.

  Example: true
• frequency: string
  Title: Frequency

  Allowed Values: [ "Once", "QD", "BID", "TID", "QID", "Q3", "Q4", "Q8", "Q12", "Q24", "Bedtime", "With meals", "With meals and at bedtime" ]

  Dosing frequency.

  Example: BID
• instanceNumber: number (BigDecimal)
  Title: Instance Number

  Visit instance number.

  Example: 2
• inventoryId: string (uuid)
  Title: Inventory ID

  Inventory ID.
• inventoryStatus: number (double)
  Title: Inventory Status

  Allowed Values: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20 ]

  Unique ID corresponding to each inventory status value (1 for Available, 2 for Damaged, 3 for Destroyed, 4 for Dispensed, 5 for Expired, 6 for Not in Use, 7 for Misallocated, 8 for Missing, 9 for In Transit, 10 for Quarantined, 11 for Pre-quarantined, 12 for Pending Destruction, 13 for Lost by Subject, 14 for Temporarily Unavailable, 15 for Damaged by Subject, 16 for New, 17 for Not Dispensed to Subject, 18 for Returned to Site, 19 for Conserved, 20 for Received for Destruction).

  Example: 5
• inventoryStatusName: string
  Name of the inventory status.

  Example: Dispensed
• kitDescription: string
  Title: Kit Description

  Kit description.

  Example: Kit A
• kitNumber: number (double)
  Title: Kit Number

  Kit number.

  Example: 5
• kitNumberUTF: string
  Title: Kit Number UTF

  Kit number in UTF-8 format.

  Example: 000AB123
• lastActionDate: string (date-time)
  Title: Last Action Date

  Last action date for the dispensation history row.
• lastModifiedDate: string (date-time)
  Title: Last Modified Date

  Last modified date.
• lotId: string (uuid)
  Title: Lot ID

  Lot ID.
• lotNumber: string
  Title: Lot Number

  Lot number.

  Example: mf1
• measurement: string
  Title: Measurement

  Dose Measurement.

  Example: ml
• mHealthDeviceId: string
  Title: mHealth Device ID

  mHealth device identifier.

  Example: B1B8327AFAA6412287106192AB5984EF
• missingUnits: number (double)
  Title: Missing Units

  Missing units for the kit.

  Example: 1
• originalKit: string
  Original kit number for the replaced kit.

  Example: Kit-345
• originalLotNumber: string
  Title: Original Lot Number

  Original lot number.

  Example: mf1
• packageTypeId: number (double)
  Title: Package Type ID

  Allowed Values: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]

  Package type ID.

  Example: 5
• quantity: number (BigDecimal)
  Title: Quantity

  Kit quantity.

  Example: 2
• reason: string
  Title: Reason

  Reason.
• returnedUnits: number (double)
  Title: Returned Units

  Returned units for the kit.

  Example: 1
• siteId: string (uuid)
  Title: Site ID

  Site ID.
• subjectVisitNsInventoryId: string (uuid)
  Title: Subject Visit NS Inventory ID

  Subject visit non-serialized inventory ID.
• titration: string
  Titration options to dispense kits. For example: up/down/maintain.

  Example: maintain
• trialSupplyType: string
  Title: Trial Supply Type

  Type of the trial supply.

  Example: BOTTLE
• unitsPerKit: number (double)
  Title: Units Per Kit

  Units per kit.

  Example: 1
• userId: string (uuid)
  Title: User ID

  User ID.
• visitId: string (uuid)
  Title: Visit ID

  Visit ID.

{
    "title":"DispensationHistoryResponse v12.0",
    "type":"object",
    "properties":{
        "kitNumber":{
            "title":"Kit Number",
            "type":"number",
            "description":"Kit number.",
            "format":"double",
            "example":5
        },
        "inventoryStatus":{
            "title":"Inventory Status",
            "type":"number",
            "description":"Unique ID corresponding to each inventory status value (1 for Available, 2 for Damaged, 3 for Destroyed, 4 for Dispensed, 5 for Expired, 6 for Not in Use, 7 for Misallocated, 8 for Missing, 9 for In Transit, 10 for Quarantined, 11 for Pre-quarantined, 12 for Pending Destruction, 13 for Lost by Subject, 14 for Temporarily Unavailable, 15 for Damaged by Subject, 16 for New, 17 for Not Dispensed to Subject, 18 for Returned to Site, 19 for Conserved, 20 for Received for Destruction).",
            "format":"double",
            "example":5,
            "enum":[
                1,
                2,
                3,
                4,
                5,
                6,
                7,
                8,
                9,
                10,
                11,
                12,
                13,
                14,
                15,
                16,
                17,
                18,
                19,
                20
            ]
        },
        "dispensationDate":{
            "title":"Dispensation Date",
            "type":"string",
            "description":"Dispensation date.",
            "format":"date-time"
        },
        "inventoryId":{
            "title":"Inventory ID",
            "type":"string",
            "description":"Inventory ID.",
            "format":"uuid"
        },
        "packageTypeId":{
            "title":"Package Type ID",
            "type":"number",
            "description":"Package type ID.",
            "format":"double",
            "example":5,
            "enum":[
                1,
                2,
                3,
                4,
                5,
                6,
                7,
                8,
                9,
                10
            ]
        },
        "unitsPerKit":{
            "title":"Units Per Kit",
            "type":"number",
            "description":"Units per kit.",
            "format":"double",
            "example":1
        },
        "returnedUnits":{
            "title":"Returned Units",
            "type":"number",
            "description":"Returned units for the kit.",
            "format":"double",
            "example":1
        },
        "missingUnits":{
            "title":"Missing Units",
            "type":"number",
            "description":"Missing units for the kit.",
            "format":"double",
            "example":1
        },
        "balanceUnits":{
            "title":"Balance Units",
            "type":"number",
            "description":"Balanced units for the kit.",
            "format":"double",
            "example":1
        },
        "siteId":{
            "title":"Site ID",
            "type":"string",
            "description":"Site ID.",
            "format":"uuid"
        },
        "lastModifiedDate":{
            "title":"Last Modified Date",
            "type":"string",
            "description":"Last modified date.",
            "format":"date-time"
        },
        "kitDescription":{
            "title":"Kit Description",
            "type":"string",
            "description":"Kit description.",
            "example":"Kit A"
        },
        "dose":{
            "title":"Dose",
            "type":"number",
            "description":"Dose.",
            "format":"double",
            "example":5
        },
        "measurement":{
            "title":"Measurement",
            "type":"string",
            "description":"Dose Measurement.",
            "example":"ml"
        },
        "frequency":{
            "title":"Frequency",
            "type":"string",
            "description":"Dosing frequency.",
            "example":"BID",
            "enum":[
                "Once",
                "QD",
                "BID",
                "TID",
                "QID",
                "Q3",
                "Q4",
                "Q8",
                "Q12",
                "Q24",
                "Bedtime",
                "With meals",
                "With meals and at bedtime"
            ]
        },
        "visitId":{
            "title":"Visit ID",
            "type":"string",
            "description":"Visit ID.",
            "format":"uuid"
        },
        "trialSupplyType":{
            "title":"Trial Supply Type",
            "type":"string",
            "description":"Type of the trial supply.",
            "example":"BOTTLE"
        },
        "deviceType":{
            "title":"Device Type",
            "type":"string",
            "description":"Device type.",
            "example":"WearablePatch",
            "enum":[
                "ActivityWatch",
                "BloodPressureMonitor",
                "WeightScale",
                "ECGReader",
                "Spirometer",
                "MobileApp",
                "SmartPillBottle",
                "PulseOximeter",
                "WearablePatch",
                "Other",
                "GlucoseMonitor"
            ]
        },
        "deviceConnection":{
            "title":"Device Connection Type",
            "type":"string",
            "description":"Device connection type.",
            "example":"DevicetoCloud",
            "enum":[
                "CloudtoCloud",
                "DevicetoCloud",
                "NoConnection"
            ]
        },
        "mHealthDeviceId":{
            "title":"mHealth Device ID",
            "type":"string",
            "description":"mHealth device identifier.",
            "example":"B1B8327AFAA6412287106192AB5984EF"
        },
        "conserved":{
            "title":"Conserved",
            "type":"boolean",
            "description":"Conserved for dispensation.",
            "example":true
        },
        "allowReplacement":{
            "title":"Allow Replacement",
            "type":"boolean",
            "description":"Indicates whether the kit is allowed for replacement.",
            "example":true
        },
        "instanceNumber":{
            "title":"Instance Number",
            "type":"number",
            "description":"Visit instance number.",
            "format":"BigDecimal",
            "example":2
        },
        "barcode":{
            "type":"string",
            "description":"Barcode.",
            "example":"1236"
        },
        "dispensationConfirmed":{
            "type":"boolean",
            "description":"Indicates whether dispensation is confirmed.",
            "example":true
        },
        "dosingUnblinded":{
            "title":"Dosing Unblinded",
            "type":"boolean",
            "description":"Indicates whether dosing is unblinded.",
            "example":true
        },
        "quantity":{
            "title":"Quantity",
            "type":"number",
            "description":"Kit quantity.",
            "format":"BigDecimal",
            "example":2
        },
        "kitNumberUTF":{
            "title":"Kit Number UTF",
            "type":"string",
            "description":"Kit number in UTF-8 format.",
            "example":"000AB123"
        },
        "inventoryStatusName":{
            "type":"string",
            "description":"Name of the inventory status.",
            "example":"Dispensed"
        },
        "userId":{
            "title":"User ID",
            "type":"string",
            "description":"User ID.",
            "format":"uuid"
        },
        "titration":{
            "type":"string",
            "description":"Titration options to dispense kits. For example: up/down/maintain.",
            "example":"maintain"
        },
        "originalKit":{
            "type":"string",
            "description":"Original kit number for the replaced kit.",
            "example":"Kit-345"
        },
        "subjectVisitNsInventoryId":{
            "title":"Subject Visit NS Inventory ID",
            "type":"string",
            "description":"Subject visit non-serialized inventory ID.",
            "format":"uuid"
        },
        "lotId":{
            "title":"Lot ID",
            "type":"string",
            "description":"Lot ID.",
            "format":"uuid"
        },
        "lotNumber":{
            "title":"Lot Number",
            "type":"string",
            "description":"Lot number.",
            "example":"mf1"
        },
        "originalLotNumber":{
            "title":"Original Lot Number",
            "type":"string",
            "description":"Original lot number.",
            "example":"mf1"
        },
        "dosingInstruction":{
            "title":"Dosing Instruction",
            "type":"string",
            "description":"Dosing instruction.",
            "example":"once daily"
        },
        "dispensationRollback":{
            "title":"Dispensation Rollback",
            "type":"boolean",
            "description":"Indicates whether the row is related to a rolled-back dispensation."
        },
        "reason":{
            "title":"Reason",
            "type":"string",
            "description":"Reason."
        },
        "comment":{
            "title":"Comment",
            "type":"string",
            "description":"Comment."
        },
        "lastActionDate":{
            "title":"Last Action Date",
            "type":"string",
            "description":"Last action date for the dispensation history row.",
            "format":"date-time"
        }
    },
    "description":"Response object containing Dispensation History with dispensation rollback details."
}

400 Response

Invalid parameters

Body ()

Root Schema : ORSResponse

Type: object

Common response object.

Show Source

• errorData: object ErrorResponseData
  Title: ErrorResponseData

  Error Response Details Information
• result: object result
  Result Object
• status: string
  Status of request

  Example: Success
• version: integer (int32)

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string",
            "description":"Status of request",
            "example":"Success"
        },
        "result":{
            "type":"object",
            "description":"Result Object"
        },
        "errorData":{
            "$ref":"#/components/schemas/ErrorResponseData"
        },
        "version":{
            "type":"integer",
            "format":"int32"
        }
    },
    "description":"Common response object."
}

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

Result Object

Nested Schema : Object

Type: object

Title: Object

Object with error details information.

Example:

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

404 Response

Invalid study ID or version OR Subject not found

Body ()

Root Schema : ORSResponse

Type: object

Common response object.

Show Source

• errorData: object ErrorResponseData
  Title: ErrorResponseData

  Error Response Details Information
• result: object result
  Result Object
• status: string
  Status of request

  Example: Success
• version: integer (int32)

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string",
            "description":"Status of request",
            "example":"Success"
        },
        "result":{
            "type":"object",
            "description":"Result Object"
        },
        "errorData":{
            "$ref":"#/components/schemas/ErrorResponseData"
        },
        "version":{
            "type":"integer",
            "format":"int32"
        }
    },
    "description":"Common response object."
}

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

Result Object

Nested Schema : Object

Type: object

Title: Object

Object with error details information.

Example:

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

500 Response

Error

Body ()

Root Schema : ORSResponse

Type: object

Common response object.

Show Source

• errorData: object ErrorResponseData
  Title: ErrorResponseData

  Error Response Details Information
• result: object result
  Result Object
• status: string
  Status of request

  Example: Success
• version: integer (int32)

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string",
            "description":"Status of request",
            "example":"Success"
        },
        "result":{
            "type":"object",
            "description":"Result Object"
        },
        "errorData":{
            "$ref":"#/components/schemas/ErrorResponseData"
        },
        "version":{
            "type":"integer",
            "format":"int32"
        }
    },
    "description":"Common response object."
}

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

Result Object

Nested Schema : Object

Type: object

Title: Object

Object with error details information.

Example:

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

Back to Top