API Reference: Blood Bags

Blood Bag API Access is available in SANDBOX & BETA.

Blood bags are identified using ISBT 128 encoding — an international standard for blood product labeling. The din, productCode, expirationDate, and bloodType fields are returned in their raw ISBT 128 format, exactly as scanned (including identifier characters). The DIN (Donor Identification Number) serves as the unique identifier for each unit and always begins with =.

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

Blood Bag Fields

Field	Description	Format
`din`	Donation Identification Number — unique identifier for this unit	ISBT 128 string
`productCode`	Blood product code identifying the component type	ISBT 128 string
`expirationDate`	Expiration date/time of this unit	ISBT 128 string
`bloodType`	ABO/Rh blood type	ISBT 128 string
`status`	Current lifecycle status	See status table below
`location`	Current location of the unit. Format is `<DEVICE-TYPE>_<SERIAL>` when stored in a Delta device	Device Identifier or generic name
`updated`	Timestamp of the last status update	seconds since unix epoch
`organization`	Organization currently holding this unit	`{ uuid, name }`

Status Values

Status	Description
`NEW`	Registered, not yet checked in to a device
`CHECKED_IN`	Currently stored in a Delta device — temperature is being tracked
`CHECKED_OUT`	Checked out to an external cooler or transport device
`SHIPPED`	In transit via tracked shipment
`EXTERNAL`	Held by an external organization
`TRANSFUSED`	Transfusion complete
`RETURNED`	Returned to blood bank
`DISCARDED`	Discarded
`UNKNOWN`	Status could not be determined

`/blood`

Returns all blood bags registered to your organization. By default, only active units are returned (TRANSFUSED, RETURNED, and DISCARDED are excluded).

Result limit: A maximum of 250 bags are returned per request. If your result set exceeds this limit, the API returns a 400 error with a suggestion to narrow the query using status or a date range filter.

Method	Response
GET	JSON Array

Query Parameters

Parameter	Type	Description
`status`	string	Filter to a specific status. If omitted, active-only bags are returned.
`start`	integer	Start of date range (unix seconds). Requires `end`.
`end`	integer	End of date range (unix seconds). Requires `start`.

Request Examples

https://api.blood.dev/v1/blood 
https://api.blood.dev/v1/blood?status=CHECKED_IN 
https://api.blood.dev/v1/blood?start=1738300000&end=1738400000

Response

[   
  {    
    "din": <string>,   
    "productCode": <string>,  
    "expirationDate": <string>,  
    "bloodType": <string>,     
    "status": <string>,  
    "updated": <number>,   
    "location": <string>,  
    "organization": {   
      "uuid": <string>,    
      "name": <string>   
    }   
  },  
  ...
]

`/blood/<DIN>`

Returns a single blood bag by DIN. The = prefix is optional in the URL — both /blood/A99991234567800 and /blood/=A99991234567800resolve 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 Object

Request Example

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

Response


{
  "din": <string>,   
  "productCode": <string>,  
  "expirationDate": <string>,  
  "bloodType": <string>,     
  "status": <string>,  
  "updated": <number>,   
  "location": <string>,  
  "organization": {   
    "uuid": <string>,    
    "name": <string>   
  }   
}