API Reference: Blood Bag Events

Blood Bag API Access is available in SANDBOX & BETA.

The events endpoint returns the complete audit history for a blood bag unit — every scan, check-in, check-out, inspection, shipment, and disposition recorded against that DIN. Events are returned in chronological order by the time the physical action occurred, not the time it was recorded in the system.

PREMIUM license required. All /blood routes require a BloodCOMM PREMIUM license. Requests from organizations without a PREMIUM license receive a 402 response.

Event Fields

Field	Description
`event`	Event type — see event types table below
`timestamp`	Effective time of the physical action — seconds since unix epoch
`edited`	Timestamp of the last edit to this event, if applicable — seconds since unix epoch. Absent if the event has never been edited.
`organization`	Organization under which this event was recorded
`user`	User who triggered this event. `id` is a pseudonymous per-org stable identifier — see User Identification below.
`data`	Event-specific payload — shape varies by `event` type, see Data Shapes below

Timestamps

Events use the time of the physical action, not the time the record was written to the system:

Event Type	Effective Time Source
`CHECK_IN`	Time the unit was physically checked in
`CHECK_OUT`, `SHIPMENT`, `INSPECT`	Time of the last temperature measurement
`TRANSFUSE`	Clinical time of transfusion
`RETURN`	Time of return
All others	Time the event was recorded

User Identification

The user.id field is a pseudonymous per-org identifier. It is:

Stable — the same user always produces the same ID within the relevant organization, enabling persistent mapping to your own user records
Org-scoped — the same user produces a different ID under a different organization, preventing cross-org correlation
Non-reversible — the original user identity cannot be recovered from the ID alone

Event Types

Type	Description
`REGISTER`	Unit registered into the system
`INSPECT`	Manual temperature inspection
`CHECK_IN`	Unit checked in to a Delta device
`CHECK_OUT`	Unit checked out to an external cooler
`SHIPMENT`	Unit shipped via tracked carrier
`TRANSFUSE`	Transfusion administered
`RETURN`	Unit returned to blood bank
`DISCARD`	Unit discarded
`MODIFY`	ISBT 128 values corrected

`/blood/<DIN>/events`

Returns the full event history for a single blood bag, sorted ascending by effective event time. The = prefix is optional in the URL — both /blood/A99991234567800/events and /blood/=A99991234567800/events resolve to the same unit.

Returns 404 if the DIN does not exist or does not belong to your organization. These cases are intentionally indistinguishable.

Method	Response
GET	JSON Array

Request Example

https://api.blood.dev/v1/blood/A99991234567800/events

Response

[
   {
     "event": <string>,
     "timestamp": <number>,
     "edited": <number>,
     "organization": {
       "uuid": <string>,
       "name": <string>
     },
     "user": {
       "name": <string>,
       "id": <string>
     },
     "data": { ... }
   },
   ...
]

edited is only present if the event has been modified after creation.

Data Shapes

The data field shape depends on the event type.

`REGISTER`

Field	Description
`din`	DIN at time of registration
`productCode`	Product code at time of registration
`expirationDate`	Expiration at time of registration
`bloodType`	Blood type at time of registration
`note`	Registration note

{
   "din": <string>,
   "productCode": <string>,
   "expirationDate": <string>,
   "bloodType": <string>,
   "note": <string> 
}

`INSPECT`

Field	Description
`temperature`	Temperature at time of inspection — °C
`lastMeasured`	Timestamp of the measurement — seconds since unix epoch
`inspected`	Whether the unit passed inspection
`note`	Inspection note

{
   "temperature": <number|null>,
   "lastMeasured": <number|null>,
   "inspected": <boolean>,
   "note": <string> 
}

`CHECK_IN`

Field	Description
`deviceID`	Device the unit was checked in to, in `<DEVICE-TYPE>_<SERIAL>` format
`checkInTime`	Time the unit was physically checked in — seconds since unix epoch
`note`	Check-in note

{
   "deviceID": <string>,
   "checkInTime": <number|null>,
   "note": <string> 
}

`CHECK_OUT`

Field	Description
`deviceData`	External cooler the unit was checked out to — `{ name, location }`
`temperature`	Temperature at time of check-out — °C
`lastMeasured`	Timestamp of the measurement — seconds since unix epoch
`note`	Check-out note

{
  "deviceData": {
    "name": <string>,
    "location": <string> 
  },
  "temperature": <number|null>,
  "lastMeasured": <number|null>,
  "note": <string>
}

`SHIPMENT`

Field	Description
`trackingNumber`	Carrier tracking number
`temperature`	Temperature at time of shipment — °C
`lastMeasured`	Timestamp of the measurement — seconds since unix epoch
`note`	Shipment note

{
   "trackingNumber": <string>,
   "temperature": <number|null>,
   "lastMeasured": <number|null>,
   "note": <string> 
}

`TRANSFUSE`

Field	Description
`receivingFacilityName`	Name of the receiving facility
`receivingFacilityID`	Patient or facility ID at the receiving facility
`firstResponderID`	ID of the administering first responder
`transportAgencyID`	EMS or transport agency patient ID
`transfusionTime`	Clinical time of transfusion — seconds since unix epoch
`note`	Transfusion note

{
  "receivingFacilityName": <string|null>,
  "receivingFacilityID": <string|null>,
  "firstResponderID": <string|null>,
  "transportAgencyID": <string|null>,
  "transfusionTime": <number|null>,
  "note": <string>
}

`RETURN`

Field	Description
`receivedBy`	Person at the blood bank who accepted the return — `{ name, email }`
`bloodBank`	Name of the blood bank
`reason`	Reason for return — see Discard/Return Reasons below
`returnTime`	Time of return — seconds since unix epoch
`note`	Return note

{
  "receivedBy": {
    "name": <string>,
    "email": <string> 
  },
  "bloodBank": <string>,
  "reason": <string>,
  "returnTime": <number|null>,
  "note": <string>
}

`DISCARD`

Field	Description
`reason`	Reason for discard — see Discard/Return Reasons below
`note`	Discard note

{
   "reason": <string>,
   "note": <string>
}

Discard / Return Reasons

Value	Description
`EXCHANGE`	Unit exchanged
`EXPIRED`	Unit reached expiration
`RECALLED`	Unit subject to a recall
`REQUESTED`	Return requested by blood bank
`DAMAGED`	Unit damaged
`OTHER`	Other reason
`ISSUE`	Issue identified with the unit

`MODIFY`

Field	Description
`new`	Updated ISBT 128 values — `{ din, productCode, expirationDate, bloodType }`
`old`	Previous ISBT 128 values — `{ din, productCode, expirationDate, bloodType }`
`note`	Modification note

{
  "new": {
    "din": <string>,
    "productCode": <string>,
    "expirationDate": <string>,
    "bloodType": <string>
  },
  "old": {
     "din": <string>,
     "productCode": <string>,
     "expirationDate": <string>,
     "bloodType": <string>
  },   
  "note": <string>
}