API calls related to Sample Inventory objects:
Retrieve
GET /api/v1/vaults/<vault_id>/inventory_samples
Returns Sample Inventory information for all Batches.
GET /api/v1/vaults/<vault_id>/inventory_samples?inventory_sample_ids=[123,321]
Returns Sample Inventory information using a list of Sample ID(s).
Note: You may also pass the inventory_sample_ids at the end of the url, like:
GET /api/v1/vaults/<vault_id>/inventory_samples/123
Note: You may also pass the inventory_sample_ids parameter as JSON, like:
GET /api/v1/vaults/<vault_id>/inventory_samples
{
"inventory_sample_ids":[123,321]
}
GET /api/v1/vaults/<vault_id>/inventory_samples?batch_ids=[123456789,987654321]
Returns Sample Inventory information using a list of Batch ID(s).
Note: You may also pass the batch_ids parameter as JSON, like:
GET /api/v1/vaults/<vault_id>/inventory_samples
{
"batch_ids":[123456789,987654321]
}
Query Parameters (all optional):
batch_ids |
Comma separated list of Batch ids |
inventory_sample_ids |
Comma separated list of Sample ids |
created_before |
Date (YYYY-MM-DDThh:mm:ss±hh:mm) |
created_after |
Date (YYYY-MM-DDThh:mm:ss±hh:mm) |
modified_before |
Date (YYYY-MM-DDThh:mm:ss±hh:mm) |
modified_after |
Date (YYYY-MM-DDThh:mm:ss±hh:mm) |
projects |
Comma-separated list of project ids Defaults to all available projects Limits scope of query |
async |
Boolean If true, do an asynchronous export (see Async Export) Use for large data sets. This is recommended any time you want to download more than page_size results. Note: any page_size parameter used in an API GET call that also uses the async=true parameter will be ignored. The GET call will return all valid data for the given GET call. |
Example - Return Inventory Samples for a specified Batch
curl -H "X-CDD-Token: $TOKEN" https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/inventory_samples?batch_ids=[123456789]
Returns:
[
{
"count": 1,
"objects": [
{
"id": 368,
"units": "mL",
"created_at": "2023-11-01T15:57:39.910Z",
"inventory_location_id": 1226,
"inventory_location_position": 3,
"slurp_id": 1869905,
"current_amount": 100.0,
"depleted": false,
"batch_name": "001",
"modified_at": "2023-11-02T00:19:32.173Z",
"name": "CWT-0000010-001-CWT10-001-S1",
"modified_user": null,
"inventory_events": [
{
"id": 615,
"created_at": "2023-11-01T15:57:39.913Z",
"slurp_id": null,
"modified_at": "2023-11-01T15:57:39.913Z",
"modified_user": null,
"owner": "Charles Weatherall",
"fields": {}
},
{
"id": 616,
"created_at": "2023-11-01T15:57:39.915Z",
"slurp_id": 1869905,
"modified_at": "2023-11-01T15:57:39.915Z",
"modified_user": null,
"owner": "Charles Weatherall",
"fields": {
"Credit": 100.0,
"Location": {
"id": 1226,
"position": 3,
"value": "Krypton Building 1 Freezer 1 Box 1 3/A3"
},
"Physical Form": "Solution",
"Tube Type": "Eppendorf",
"Ship Date": "2023-11-05"
}
}
],
"owner": "Charles Weatherall",
"fields": {
"Sample ID": "CWT10-001-S1",
"State": "Liquid",
"Destination": "CRO"
},
"location": "Krypton Building 1 Freezer 1 Box 1 3/A3",
"batch": 123456789
}
]
}
]
Example - Return Inventory Samples created after specified date
curl -H "X-CDD-Token: $TOKEN" https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/inventory_samples?created_after=2023-11-14
Notes on Date/Time Formats
The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20".
You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.
Create
POST /api/v1/vaults/<vault_id>/inventory_samples
Creates a new Sample for a specified Batch ID, including initial Inventory Sample Event information.
The body of the POST must contain a JSON structure specifying the Sample's attributes.
Allowed JSON keys for Samples and Inventory Events:
batch_id |
The internal Batch ID for which the new Sample will be created. |
units |
Used to specify the Units of the Sample's initial amount. Allowed values are:
|
fields |
Used to specify the user-defined Sample fields created by the Vault Administrator in the Settings > Vault > Sample/Inventory Fields tab. |
inventory_events |
Used to specify the user-defined Sample Inventory Event fields created by the Vault Administrator in the Settings > Vault > Sample/Inventory Fields tab. |
Example
curl -H "X-CDD-Token: $TOKEN" -X POST -H "Content-Type: application/json" -d "@data.json" https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/inventory_samples
File data.json:
{
"batch_id": 123456789,
"units": "mg",
"fields": {
"Sample ID": "CWT011-001-S12",
"State":"Powder"
},
"inventory_events": [
{"fields":{
"Barcode": "CWT11S1abc",
"Physical Form":"Dry",
"Tube Type":"Vial",
"Credit": 1000,
"Location":{
"id":1212,
"position":1
}
}
}
]
}Returns:
{
"id": 53182,
"units": "mg",
"created_at": "2024-05-03T14:12:45.862Z",
"inventory_location_id": null,
"inventory_location_position": null,
"slurp_id": null,
"current_amount": 1000.0,
"depleted": false,
"batch_name": "001",
"modified_at": "2024-05-03T14:12:45.865Z",
"name": "CWT-0000011-001-CWT011-001-S12",
"modified_user": null,
"inventory_events": [
{
"id": 61283,
"created_at": "2024-05-03T14:12:45.865Z",
"slurp_id": null,
"modified_at": "2024-05-03T14:12:45.865Z",
"modified_user": null,
"owner": "Charlie Weatherall",
"fields": {
"Barcode": "CWT11S12zzzz",
"Physical Form": "Dry",
"Tube Type": "Vial",
"Credit": 1000.0
}
}
],
"owner": "Charlie Weatherall",
"fields": {
"Sample ID": "CWT011-001-S12",
"State": "Powder"
},
"location": null,
"batch": 123456789
}
],
"owner": "Charlie Weatherall",
"fields": {
"Sample ID": "CWT011-001-S1",
"State": "Powder"
}
}
Note:
You may specify a Location when creating a new Sample. The "Location" parameter is passed in the JSON as part of the "inventory_events" > "fields" section. The "Location parameter" accepts a Location id and position.
- The Location id can be found using the GET inventory_locations API call.
- The Location position can also be determined from the same GET inventory_locations API call.
In my example above, the GET inventory_samples API call returned with a Location like this:
...
{
"id": 1212,
"class": "inventory location",
"created_at": "2023-10-30T18:25:41.779Z",
"modified_at": "2023-10-30T18:25:41.779Z",
"filled_position_count": 0,
"num_columns": 8,
"num_rows": 8,
"parent_id": 1211,
"position_limit": 64,
"value": "Box 1"
},
...
Since the "filled_position_count" was currently set to 0, I could use a "position" of 1 for my Location id of 1212 when creating my new Sample above.
"Location":{
"id":1212,
"position":1
Update
PUT /api/v1/vaults/<vault_id>/inventory_samples
Updates an existing Sample to create a new Sample Inventory Event row.
Example
curl -H "X-CDD-Token: $TOKEN" -X PUT -H "Content-Type: application/json" -d "@data.json" https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/inventory_samples/<sample_id>
File data.json:
{
"inventory_events": [
{"fields":{
"Barcode": "CWT11S2defz",
"Physical Form":"Dry",
"Tube Type":"Vial",
"Debit": 10
}
}
]
}Returns:
{
"current_amount": 980.0,
"inventory_location_id": null,
"inventory_location_position": null,
"units": "mg",
"id": 2392,
"created_at": "2023-11-08T20:11:20.027Z",
"slurp_id": null,
"depleted": false,
"batch_name": "001",
"modified_at": "2024-05-03T14:16:25.506Z",
"name": "CWT-0000011-001-CWT011-001-S1",
"modified_user": "Charlie Weatherall",
"inventory_events": [
{
"id": 3691,
"created_at": "2023-11-08T20:11:20.029Z",
"slurp_id": null,
"modified_at": "2023-11-08T20:11:20.029Z",
"modified_user": null,
"owner": "Charlie Weatherall",
"fields": {
"Credit": 1000.0,
"Physical Form": "Dry",
"Barcode": "CWT11S1abc",
"Tube Type": "Vial"
}
},
{
"id": 3693,
"created_at": "2023-11-08T20:45:32.907Z",
"slurp_id": null,
"modified_at": "2023-11-08T20:45:32.907Z",
"modified_user": null,
"owner": "Charlie Weatherall",
"fields": {
"Debit": 10.0,
"Physical Form": "Dry",
"Barcode": "CWT11S1def",
"Tube Type": "Vial"
}
},
{
"id": 61284,
"created_at": "2024-05-03T14:16:25.505Z",
"slurp_id": null,
"modified_at": "2024-05-03T14:16:25.505Z",
"modified_user": null,
"owner": "Charlie Weatherall",
"fields": {
"Barcode": "CWT11S1defz",
"Physical Form": "Dry",
"Tube Type": "Vial",
"Debit": 10.0
}
}
],
"owner": "Charlie Weatherall",
"fields": {
"Sample ID": "CWT011-001-S1",
"State": "Powder"
},
"location": null,
"batch": 123456789
}