Welcome to VBR API’s documentation!¶

A2CPS Virtual Biospecimen Repository API¶

This API manages Biospecimen logistics and processing.

Prerequistes¶

Be part of a A2CPS Project/group
Have a TACC username and TACC password

Getting Started¶

To get started working with the A2CPS Virtual Biospecimen Repository API, you need to get authenticated.

Authentication and Authorization¶

/auth/token

Use the /auth/token endpoint to authenticate using TACC credentials.

Click on the POST method for /auth/token endpoint. We create a Tapis Token using this endpoint.
Hit the Try it out Button to unlock the Request body fields.
Enter your TACC username and TACC password in the fields and hit Execute.

You could also use the curl request on the command line to get your access token.

curl -X 'POST' \
     'https://vbr-api.a2cps.cloud/auth/token' \
     -H 'accept: application/json' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'grant_type=&username=taccUsername&password=taccPassword!&scope=&client_id=&client_secret='

Once the request is submitted, you would see a response body as shown below. The response body holds your access_token.

{
     "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmYT24252MzMS00ZWQ4Ltwtwtwfwr21",
     "token_type": "bearer"
}

Alternate Method for Authentication¶

Click on the Authorize button here as shown below.

Enter your TACC username and TACC password and hit Authorize to get started.

With the correct credentials entered, you would be able to see your available authorizations.

Note

Once authentication is successful, you will be able to see the locks in closed state on the webpage.

To Verify Authentication was successfull¶

/status endpoint

Status endpoints can be used to provide basic system health checks.

Use the /status endpoint to check if authentication was successful.

A simple GET request on the /status endpoint would provide an unauthenticated status check.

curl -X 'GET' \
'https://vbr-api.a2cps.cloud/status' \
-H 'accept: application/json'

A successful response would be:

{
     "service": "A2CPS Virtual Biospecimen Repository API",
     "versions": {
         "app": "0.1.0",
         "python_vbr": "0.1.0",
         "tapipy": "1.0.3"
     },
     "tenant": "a2cpsdev",
     "status": "OK",
     "uptime": 184669.836504,
     "message": "Status retrieved"
}

Here we can see the status is “OK”.

A simple GET request on the /status/auth endpoint would provide an authenticated status check.

curl -X 'GET' \
 'https://vbr-api.a2cps.cloud/status/auth' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIxYzZiZWU2OS1kYzcyLTQ1ZTYtOTEwYy0zNjhiYzk1NTQzMTkiLCJpc3MiOiJodHRwczovL2EyY3BzZGV2LnRhcGlzLmlvL3YzL3Rva2VucyIsInN1YiI6InNnb3BhbEBhMmNwc2RldiIsInRhcGlzL3RlbmFudF9pZCI6ImEyY3BzZGV2IiwidGFwaXMvdG9rZW5fdHlwZSI6ImFjY2VzcyIsInRhcGlzL2RlbGVnYXRpb24iOmZhbHNlLCJ0YXBpcy9kZWxlZ2F0aW9uX3N1YiI6bnVsbCwidGFwaXMvdXNlcm5hbWUiOiJzZ29wYWwiLCJ0YXBpcy9hY2NvdW50X3R5cGUiOiJ1c2VyIiwiZXhwIjoxNjQzMzM4NzY2LCJ0YXBpcy9jbGllbnRfaWQiOm51bGwsInRhcGlzL2dyYW50X3R5cGUiOiJwYXNzd29yZCJ9.fnz-5lRMWF_6yUNnJJFrGTrjWL2LuoPPxOTIL9TL4f0xVcqqGjFl2DeS6AtsEhP2NfZAoWg9BnhpCDuFWd8Ss4SRpx2LOOg_P42edWlXuJizCP8wOq_A4GUp1Nk1to1qWfZ-M907YwFzfZQZDz12Ei8QbjmpWcnZ0Da6WTGVBAz840D7fxQb-XioTQDCJJM-A95hTAfk9ZvCxeObmIUKZ0qn6HtLVVRiaRbl_OkcubgCPxHQJXWocxC0fiUqLeo9QJRfjLTO38Z8_j5MX2ITh9jhgGI-45vf_qYXwwABCpK3tuRbXS77sDcS2halWHKHU-ZvdGBDEEpiS6J1KI5SKg'

A successful response would look like:

{
     "service": "A2CPS Virtual Biospecimen Repository API",
     "versions": {
         "app": "0.1.0",
         "python_vbr": "0.1.0",
         "tapipy": "1.0.3"
     },
     "tenant": "a2cpsdev",
     "status": "OK",
     "uptime": 184860.123499,
     "message": "Authentication successful"
}

Here we can see the status is “OK”. You are now logged in to the service!

Biospecimens¶

Biospecimens are collected from Subjects.

List Biospecimens¶

GET /biospeciments/ yields a list of the different biospecimens available.

The following curl request can be used through the command line to list the biospecimens:

curl -X 'GET' \
 'https://vbr-api.a2cps.cloud/biospecimens/?offset=0&limit=50' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer Access Token'

Note

The offset field can be used to change the number of records that show up.

A successful response would look like:

[
   {
      "biospecimen_id": "7yAnxZN36BJJb",
      "tracking_id": "K_RU_P_0021",
      "creation_time": "2021-04-30T00:00:00",
      "biospecimen_type": "serum or plasma",
      "collection_id": "PdV482PnBozxe",
      "collection_tracking_id": "K_RU_KIT_0021",
      "container_id": "8PqD2Xb7AgzA2",
      "container_tracking_id": "K_RU_BOX_ALI_0002",
      "project": "A2CPS Multisite Clinical Center 1",
      "status": "created",
      "unit": "plasma_aliquot_tube",
      "subject_guid": "90f8fc45-5d53-0de4-6853-284607a8c4e6",
      "subject_id": "Pxk1yXJPV3ADX",
      "bscp_time_blood_draw": "2021-04-30T11:53:00",
      "bscp_time_centrifuge": "2021-04-30T12:13:00",
      "bscp_aliquot_freezer_time": "2021-04-30T12:24:00",
      "bscp_deg_of_hemolysis": 1,
      "bscp_phleb_by_init": "KB",
      "bscp_procby_initials": "MM",
      "bscp_protocol_dev": true,
      "bscp_comments": "Unable to collect blood at baseline. Blood collected DOS.",
      "location": "MCC1: Rush University Medical Center"
   }
]

In the above JSON response:

Each biospecimen is identified by it’s biospecimen_id.
Containers hold biospecimens and each container is identified by it’s container_id.
Location refers to the physical address of a container.

Filter results¶

We can also filter the results by modifying the parameters passed to the request.

For example, we can pick the collection_tracking_id value from the above JSON response (e.g: “collection_tracking_id”: “K_RU_KIT_0021” ) and use this to filter our results specific to the collection_tracking_id of interest.

The curl command for the above example would be:

curl -X 'GET' \
'https://vbr-api.a2cps.cloud/biospecimens/?collection_tracking_id=K_RU_KIT_0021&offset=0&limit=50' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token

A successful response would be a list of all the biospecimens that have the collection_tracking_id we queried for.

[
   {
      "biospecimen_id": "7yAnxZN36BJJb",
      "tracking_id": "K_RU_P_0021",
      "creation_time": "2021-04-30T00:00:00",
      "biospecimen_type": "serum or plasma",
      "collection_id": "PdV482PnBozxe",
      "collection_tracking_id": "K_RU_KIT_0021",
      "container_id": "8PqD2Xb7AgzA2",
      "container_tracking_id": "K_RU_BOX_ALI_0002",
      "project": "A2CPS Multisite Clinical Center 1",
      "status": "created",
      "unit": "plasma_aliquot_tube",
      "subject_guid": "90f8fc45-5d53-0de4-6853-284607a8c4e6",
      "subject_id": "Pxk1yXJPV3ADX",
      "bscp_time_blood_draw": "2021-04-30T11:53:00",
      "bscp_time_centrifuge": "2021-04-30T12:13:00",
      "bscp_aliquot_freezer_time": "2021-04-30T12:24:00",
      "bscp_deg_of_hemolysis": 1,
      "bscp_phleb_by_init": "KB",
      "bscp_procby_initials": "MM",
      "bscp_protocol_dev": true,
      "bscp_comments": "Unable to collect blood at baseline. Blood collected DOS.",
      "location": "MCC1: Rush University Medical Center"
   },
   {
      "biospecimen_id": "1D457580MWkq9",
      "tracking_id": "K_RU_P_0021",
      "creation_time": "2021-04-30T00:00:00",
      "biospecimen_type": "serum or plasma",
      "collection_id": "PdV482PnBozxe",
      "collection_tracking_id": "K_RU_KIT_0021",
      "container_id": "8PqD2Xb7AgzA2",
      "container_tracking_id": "K_RU_BOX_ALI_0002",
      "project": "A2CPS Multisite Clinical Center 1",
      "status": "created",
      "unit": "plasma_aliquot_tube",
      "subject_guid": "90f8fc45-5d53-0de4-6853-284607a8c4e6",
      "subject_id": "Pxk1yXJPV3ADX",
      "bscp_time_blood_draw": "2021-04-30T11:53:00",
      "bscp_time_centrifuge": "2021-04-30T12:13:00",
      "bscp_aliquot_freezer_time": "2021-04-30T12:24:00",
      "bscp_deg_of_hemolysis": 1,
      "bscp_phleb_by_init": "KB",
      "bscp_procby_initials": "MM",
      "bscp_protocol_dev": true,
      "bscp_comments": "Unable to collect blood at baseline. Blood collected DOS.",
      "location": "MCC1: Rush University Medical Center"
   }
]

Similarly, another example would be using the container_tracking_id. Picking a container_tracking_id K_RU_BOX_ALI_0002, our curl request would be:

curl -X 'GET' \
   'https://vbr-api.a2cps.cloud/biospecimens/?container_tracking_id=K_RU_BOX_ALI_0002&offset=0&limit=50' \
   -H 'accept: application/json' \
   -H 'Authorization: Bearer

A successful response would look like:

[
   {
      "biospecimen_id": "P4J7dzV7JE9Jg",
      "tracking_id": "K_RU_P_0017",
      "creation_time": "2021-04-22T00:00:00",
      "biospecimen_type": "serum or plasma",
      "collection_id": "eewy6N2b8bmEA",
      "collection_tracking_id": "K_RU_KIT_0017",
      "container_id": "8PqD2Xb7AgzA2",
      "container_tracking_id": "K_RU_BOX_ALI_0002",
      "project": "A2CPS Multisite Clinical Center 1",
      "status": "created",
      "unit": "plasma_aliquot_tube",
      "subject_guid": "82509ba8-bed1-6621-730a-f5cb91e2ff78",
      "subject_id": "8w9DbopPgv2Bn",
      "bscp_time_blood_draw": "2021-04-22T15:59:00",
      "bscp_time_centrifuge": "2021-04-22T16:21:00",
      "bscp_aliquot_freezer_time": "2021-04-22T16:28:00",
      "bscp_deg_of_hemolysis": 0.5,
      "bscp_phleb_by_init": "SM",
      "bscp_procby_initials": "SN",
      "bscp_protocol_dev": false,
      "bscp_comments": "",
      "location": "MCC1: Rush University Medical Center"
   },
   {
      "biospecimen_id": "8ezxAr2y2dxw6",
      "tracking_id": "K_RU_P_0018",
      "creation_time": "2021-04-23T00:00:00",
      "biospecimen_type": "serum or plasma",
      "collection_id": "e4eLorzMJw6dj",
      "collection_tracking_id": "K_RU_KIT_0018",
      "container_id": "8PqD2Xb7AgzA2",
      "container_tracking_id": "K_RU_BOX_ALI_0002",
      "project": "A2CPS Multisite Clinical Center 1",
      "status": "created",
      "unit": "plasma_aliquot_tube",
      "subject_guid": "0b7a0079-9451-431b-972e-d8a7539b97b0",
      "subject_id": "7zeWMyN6Wqdpd",
      "bscp_time_blood_draw": "2021-04-23T09:10:00",
      "bscp_time_centrifuge": "2021-04-23T09:23:00",
      "bscp_aliquot_freezer_time": "2021-04-23T09:29:00",
      "bscp_deg_of_hemolysis": 1,
      "bscp_phleb_by_init": "K",
      "bscp_procby_initials": "MM",
      "bscp_protocol_dev": true,
      "bscp_comments": "Will obtain blood day of surgery. Blood taken 4/23.",
      "location": "MCC1: Rush University Medical Center"
   }
]

Get Biospecimen By Id¶

GET /biospecimen/{biospecimen_id} endpoint can be used to retrieve a specific biospecimen using the biospecimen_id field.

We can get a biospecimen_id of interest from the above responses and substitute it value in our request. The curl request for the above would be:

curl -X 'GET' \
   'https://vbr-api.a2cps.cloud/biospecimens/eev1JWn5yE8vm' \
   -H 'accept: application/json' \
   -H 'Authorization: Bearer

A successful response would hold the entry for the specific biospecimen requested.

 {
    "biospecimen_id": "eev1JWn5yE8vm",
    "tracking_id": "K_RU_P_0017",
    "creation_time": "2021-04-22T00:00:00",
    "biospecimen_type": "serum or plasma",
    "collection_id": "eewy6N2b8bmEA",
    "collection_tracking_id": "K_RU_KIT_0017",
    "container_id": "8PqD2Xb7AgzA2",
    "container_tracking_id": "K_RU_BOX_ALI_0002",
    "project": "A2CPS Multisite Clinical Center 1",
    "status": "created",
    "unit": "plasma_aliquot_tube",
    "subject_guid": "82509ba8-bed1-6621-730a-f5cb91e2ff78",
    "subject_id": "8w9DbopPgv2Bn",
    "bscp_time_blood_draw": "2021-04-22T15:59:00",
    "bscp_time_centrifuge": "2021-04-22T16:21:00",
    "bscp_aliquot_freezer_time": "2021-04-22T16:28:00",
    "bscp_deg_of_hemolysis": 0.5,
    "bscp_phleb_by_init": "SM",
    "bscp_procby_initials": "SN",
    "bscp_protocol_dev": false,
    "bscp_comments": "",
    "location": "MCC1: Rush University Medical Center"
 }

Get Biospecimen By Tracking Id¶

The GET /biospecimens/tracking/{tracking_id} endpoint can be used to get a Biospecimen by Tracking ID.

Let us pick a tracking_id of interest, for example “tracking_id”: “K_RU_P_0017” and substitute it’s value in our request below.

Our curl request would be:

curl -X 'GET' \
'https://vbr-api.a2cps.cloud/biospecimens/tracking/%22K_RU_P_0017%22' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token

A successful response would look like:

{
   "biospecimen_id": "P4Jqdgx6EDE4W",
   "tracking_id": "K_RU_P_0017",
   "creation_time": "2021-04-22T00:00:00",
   "biospecimen_type": "serum or plasma",
   "collection_id": "eewy6N2b8bmEA",
   "collection_tracking_id": "K_RU_KIT_0017",
   "container_id": "8PqD2Xb7AgzA2",
   "container_tracking_id": "K_RU_BOX_ALI_0002",
   "project": "A2CPS Multisite Clinical Center 1",
   "status": "created",
   "unit": "plasma_aliquot_tube",
   "subject_guid": "82509ba8-bed1-6621-730a-f5cb91e2ff78",
   "subject_id": "8w9DbopPgv2Bn",
   "bscp_time_blood_draw": "2021-04-22T15:59:00",
   "bscp_time_centrifuge": "2021-04-22T16:21:00",
   "bscp_aliquot_freezer_time": "2021-04-22T16:28:00",
   "bscp_deg_of_hemolysis": 0.5,
   "bscp_phleb_by_init": "SM",
   "bscp_procby_initials": "SN",
   "bscp_protocol_dev": false,
   "bscp_comments": "",
   "location": "MCC1: Rush University Medical Center"
}

Update Biospecimen Container¶

We can use PATCH /biospecimens/{biospecimen_id}/container endpoint to update the container of the biospecimen.

The curl request would be:

curl -X 'PATCH' \
   'https://vbr-api.a2cps.cloud/biospecimens/7yAnxZN36BJJb/container' \
   -H 'accept: application/json' \
   -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0ZTcyNTM2NC1hNzUzLTRkMjEtYmI2Ni1kYTgxZDEzZjRmNzIiLCJpc3MiOiJodHRwczovL2EyY3BzZGV2LnRhcGlzLmlvL3YzL3Rva2VucyIsInN1YiI6InNnb3BhbEBhMmNwc2RldiIsInRhcGlzL3RlbmFudF9pZCI6ImEyY3BzZGV2IiwidGFwaXMvdG9rZW5fdHlwZSI6ImFjY2VzcyIsInRhcGlzL2RlbGVnYXRpb24iOmZhbHNlLCJ0YXBpcy9kZWxlZ2F0aW9uX3N1YiI6bnVsbCwidGFwaXMvdXNlcm5hbWUiOiJzZ29wYWwiLCJ0YXBpcy9hY2NvdW50X3R5cGUiOiJ1c2VyIiwiZXhwIjoxNjQzNjcwODI3LCJ0YXBpcy9jbGllbnRfaWQiOm51bGwsInRhcGlzL2dyYW50X3R5cGUiOiJwYXNzd29yZCJ9.DwyzMvLGm1hPvxFmMRpPGJ9DhyZqQTlp_newlgRCFvKsywDVnGofOD3s62OBxRJvuaxdlfSKoWTnPzGTfuFfItKCGzOWl9USkvKnroRq8m47z5gX1m3DkqOE_zrzyQn-u4nqJvFGWOLOPB94W5mgf4jFncU2LXmNdjy5eJvmqSXe3FqKYHxsPRweZc12ykgUYeaJSmd45Pce8bG2-KTLEcvX3ECh6sjtJ7w5rZY5ASn0BPBayYMUtUsJrV5dKwmAmRWbxjDvBf9sHysxpUj2FwkbIsMTwSyDUN9Euii0zbKfYcUg3fBJUYF86ll3CNpixzxe23T6Tr9jbf2HE5PDTQ' \
   -H 'Content-Type: application/json' \
   -d '{
      "container_id": "8PqD2Xb7AgzA2",
      "comment": "Updating biospecimen container"
   }'

A successful response would look like:

{
   "biospecimen_id": "7yAnxZN36BJJb",
   "tracking_id": "K_RU_P_0017",
   "creation_time": "2021-04-30T00:00:00",
   "biospecimen_type": "serum or plasma",
   "collection_id": "PdV482PnBozxe",
   "collection_tracking_id": "K_RU_KIT_0021",
   "container_id": "8PqD2Xb7AgzA2",
   "container_tracking_id": "K_RU_BOX_ALI_0002",
   "project": "A2CPS Multisite Clinical Center 1",
   "status": "measurement.inflight",
   "unit": "plasma_aliquot_tube",
   "subject_guid": "90f8fc45-5d53-0de4-6853-284607a8c4e6",
   "subject_id": "Pxk1yXJPV3ADX",
   "bscp_time_blood_draw": "2021-04-30T11:53:00",
   "bscp_time_centrifuge": "2021-04-30T12:13:00",
   "bscp_aliquot_freezer_time": "2021-04-30T12:24:00",
   "bscp_deg_of_hemolysis": 1,
   "bscp_phleb_by_init": "KB",
   "bscp_procby_initials": "MM",
   "bscp_protocol_dev": true,
   "bscp_comments": "Unable to collect blood at baseline. Blood collected DOS.",
   "location": "MCC1: Rush University Medical Center"
}

Update Biospecimen Status¶

We can update the status of a biospecimen using the PATCH /biospecimens/{biospecimen_id}/status endpoint.

The permitted values for status are: “inflight”, “present”, “spoiled”, “depleted”, “lost”, “destroyed”.

The curl request would be:

curl -X 'PATCH' \
   'https://vbr-api.a2cps.cloud/biospecimens/7yAnxZN36BJJb/status' \
   -H 'accept: application/json' \
   -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0ZTcyNTM2NC1hNzUzLTRkMjEtYmI2Ni1kYTgxZDEzZjRmNzIiLCJpc3MiOiJodHRwczovL2EyY3BzZGV2LnRhcGlzLmlvL3YzL3Rva2VucyIsInN1YiI6InNnb3BhbEBhMmNwc2RldiIsInRhcGlzL3RlbmFudF9pZCI6ImEyY3BzZGV2IiwidGFwaXMvdG9rZW5fdHlwZSI6ImFjY2VzcyIsInRhcGlzL2RlbGVnYXRpb24iOmZhbHNlLCJ0YXBpcy9kZWxlZ2F0aW9uX3N1YiI6bnVsbCwidGFwaXMvdXNlcm5hbWUiOiJzZ29wYWwiLCJ0YXBpcy9hY2NvdW50X3R5cGUiOiJ1c2VyIiwiZXhwIjoxNjQzNjcwODI3LCJ0YXBpcy9jbGllbnRfaWQiOm51bGwsInRhcGlzL2dyYW50X3R5cGUiOiJwYXNzd29yZCJ9.DwyzMvLGm1hPvxFmMRpPGJ9DhyZqQTlp_newlgRCFvKsywDVnGofOD3s62OBxRJvuaxdlfSKoWTnPzGTfuFfItKCGzOWl9USkvKnroRq8m47z5gX1m3DkqOE_zrzyQn-u4nqJvFGWOLOPB94W5mgf4jFncU2LXmNdjy5eJvmqSXe3FqKYHxsPRweZc12ykgUYeaJSmd45Pce8bG2-KTLEcvX3ECh6sjtJ7w5rZY5ASn0BPBayYMUtUsJrV5dKwmAmRWbxjDvBf9sHysxpUj2FwkbIsMTwSyDUN9Euii0zbKfYcUg3fBJUYF86ll3CNpixzxe23T6Tr9jbf2HE5PDTQ' \
   -H 'Content-Type: application/json' \
   -d '{
      "status": "inflight",
      "comment": "string"
   }'

A successful response would look like:

{
   "biospecimen_id": "7yAnxZN36BJJb",
   "tracking_id": "K_RU_P_0017",
   "creation_time": "2021-04-30T00:00:00",
   "biospecimen_type": "serum or plasma",
   "collection_id": "PdV482PnBozxe",
   "collection_tracking_id": "K_RU_KIT_0021",
   "container_id": "8PqD2Xb7AgzA2",
   "container_tracking_id": "K_RU_BOX_ALI_0002",
   "project": "A2CPS Multisite Clinical Center 1",
   "status": "measurement.inflight",
   "unit": "plasma_aliquot_tube",
   "subject_guid": "90f8fc45-5d53-0de4-6853-284607a8c4e6",
   "subject_id": "Pxk1yXJPV3ADX",
   "bscp_time_blood_draw": "2021-04-30T11:53:00",
   "bscp_time_centrifuge": "2021-04-30T12:13:00",
   "bscp_aliquot_freezer_time": "2021-04-30T12:24:00",
   "bscp_deg_of_hemolysis": 1,
   "bscp_phleb_by_init": "KB",
   "bscp_procby_initials": "MM",
   "bscp_protocol_dev": true,
   "bscp_comments": "Unable to collect blood at baseline. Blood collected DOS.",
   "location": "MCC1: Rush University Medical Center"
}

Update Biospecimen Tracking Id¶

We can update the Tracking Id of a biospecimen to an Id of our choice.

The curl request would be:

curl -X 'PATCH' \
   'https://vbr-api.a2cps.cloud/biospecimens/7yAnxZN36BJJb/tracking_id' \
   -H 'accept: application/json' \
   -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0ZTcyNTM2NC1hNzUzLTRkMjEtYmI2Ni1kYTgxZDEzZjRmNzIiLCJpc3MiOiJodHRwczovL2EyY3BzZGV2LnRhcGlzLmlvL3YzL3Rva2VucyIsInN1YiI6InNnb3BhbEBhMmNwc2RldiIsInRhcGlzL3RlbmFudF9pZCI6ImEyY3BzZGV2IiwidGFwaXMvdG9rZW5fdHlwZSI6ImFjY2VzcyIsInRhcGlzL2RlbGVnYXRpb24iOmZhbHNlLCJ0YXBpcy9kZWxlZ2F0aW9uX3N1YiI6bnVsbCwidGFwaXMvdXNlcm5hbWUiOiJzZ29wYWwiLCJ0YXBpcy9hY2NvdW50X3R5cGUiOiJ1c2VyIiwiZXhwIjoxNjQzNjcwODI3LCJ0YXBpcy9jbGllbnRfaWQiOm51bGwsInRhcGlzL2dyYW50X3R5cGUiOiJwYXNzd29yZCJ9.DwyzMvLGm1hPvxFmMRpPGJ9DhyZqQTlp_newlgRCFvKsywDVnGofOD3s62OBxRJvuaxdlfSKoWTnPzGTfuFfItKCGzOWl9USkvKnroRq8m47z5gX1m3DkqOE_zrzyQn-u4nqJvFGWOLOPB94W5mgf4jFncU2LXmNdjy5eJvmqSXe3FqKYHxsPRweZc12ykgUYeaJSmd45Pce8bG2-KTLEcvX3ECh6sjtJ7w5rZY5ASn0BPBayYMUtUsJrV5dKwmAmRWbxjDvBf9sHysxpUj2FwkbIsMTwSyDUN9Euii0zbKfYcUg3fBJUYF86ll3CNpixzxe23T6Tr9jbf2HE5PDTQ' \
   -H 'Content-Type: application/json' \
   -d '{
      "tracking_id": "1234check",
      "comment": "Optional comment explaining or documenting the change"
   }'

A successful response would hold the new tracking_id for our biospecimen.

{
   "biospecimen_id": "7yAnxZN36BJJb",
   "tracking_id": "1234check",
   "creation_time": "2021-04-30T00:00:00",
   "biospecimen_type": "serum or plasma",
   "collection_id": "PdV482PnBozxe",
   "collection_tracking_id": "K_RU_KIT_0021",
   "container_id": "8PqD2Xb7AgzA2",
   "container_tracking_id": "K_RU_BOX_ALI_0002",
   "project": "A2CPS Multisite Clinical Center 1",
   "status": "measurement.inflight",
   "unit": "plasma_aliquot_tube",
   "subject_guid": "90f8fc45-5d53-0de4-6853-284607a8c4e6",
   "subject_id": "Pxk1yXJPV3ADX",
   "bscp_time_blood_draw": "2021-04-30T11:53:00",
   "bscp_time_centrifuge": "2021-04-30T12:13:00",
   "bscp_aliquot_freezer_time": "2021-04-30T12:24:00",
   "bscp_deg_of_hemolysis": 1,
   "bscp_phleb_by_init": "KB",
   "bscp_procby_initials": "MM",
   "bscp_protocol_dev": true,
   "bscp_comments": "Unable to collect blood at baseline. Blood collected DOS.",
   "location": "MCC1: Rush University Medical Center"
}

Containers¶

Containers hold biospecimens. A biospecimen can be found only in one container.

List Containers¶

Use the GET /containers/ endpoint to view the list of containers

The following curl request can be used on the command line to list the containers available.

curl -X 'GET' \
'https://vbr-api.a2cps.cloud/containers/?offset=0&limit=50' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token'

A successful response would look like:

 [
  {
      "container_id": "PAPXb8O6mj2nW",
      "container_tracking_id": "DEFAULT-CONTAINER",
      "container_type": "default container (virtual)",
      "location": "Default",
      "status": "created",
      "tracking_id": null
  },
  {
      "container_id": "8PqD2Xb7AgzA2",
      "container_tracking_id": "K_RU_BOX_ALI_0002",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: Rush University Medical Center",
      "status": "created",
      "tracking_id": "802001516986"
  },
  {
      "container_id": "8POyg4jKEKO36",
      "container_tracking_id": "K_RU_BOX_PAX_0001",
      "container_type": "paxgene freezer box",
      "location": "MCC1: Rush University Medical Center",
      "status": "created",
      "tracking_id": "802001516986"
  }
]

Get Container By Id¶

The GET /containers/{container_id} endpoint can be used to fetch a container of interest.

The cure request would be:

 curl -X 'GET' \
'https://vbr-api.a2cps.cloud/containers/8PqD2Xb7AgzA2' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token

A successful response would hold the entry for the container_id of request.

{
     "container_id": "8PqD2Xb7AgzA2",
     "container_tracking_id": "K_RU_BOX_ALI_0002",
     "container_type": "blood aliquot freezer box",
     "location": "MCC1: Rush University Medical Center",
     "status": "created",
     "tracking_id": "802001516986"
 }

Workflows¶

This is an example workflow:

Process receipt of a shipment:
- Get shipment by tracking ID
- Update shipment status
- List containers in shipment
- Update status of each container
- Update location of each container
- List biosamples in each container
- Update status of each biosample
- Update tracking ID for each biosample (if non-unique)

Get shipment by tracking ID¶

Let us use a known “tracking_id” : 285590095441.

Use the GET /shipments/tracking/{tracking_id} endpoint to get a shipment by it’s tracking id.

The curl request would be:

  curl -X 'GET' \
'https://vbr-api.a2cps.cloud/shipments/tracking/285590095441' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token

A successful response would look like:

 {
     "shipment_id": "76zV8EM980jA4",
     "tracking_id": "285590095441",
     "shipment_name": "Northshore Shipping -1",
     "sender_name": "MR/VW",
     "project_name": "A2CPS Multisite Clinical Center 1",
     "ship_from": "MCC1: NorthShore University HealthSystem",
     "ship_to": "Receiving: University of California San Diego",
     "status": "shipment.shipped"
 }

Update shipment status¶

Use the PATCH /shipments/tracking/{tracking_id}/status endpoint to update the shipment status.
Permitted status values are [‘created’, ‘shipped’, ‘received’, ‘processed’, ‘delayed’, ‘lost’].

The curl request would be:

 curl -X 'PATCH' \
'https://vbr-api.a2cps.cloud/shipments/tracking/285590095441/status' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token \
-H 'Content-Type: application/json' \
-d '{
  "status": "created",
  "relocate_containers": false,
  "comment": "string"
  }'

A successful response would be:

 {
     "shipment_id": "76zV8EM980jA4",
     "tracking_id": "285590095441",
     "shipment_name": "Northshore Shipping -1",
     "sender_name": "MR/VW",
     "project_name": "A2CPS Multisite Clinical Center 1",
     "ship_from": "MCC1: NorthShore University HealthSystem",
     "ship_to": "Receiving: University of California San Diego",
     "status": "shipment.created"
 }

List containers in shipment¶

The /shipments/tracking/{tracking_id}/containers endpoint can be used to get the containers in a shipment.

 curl -X 'GET' \
'https://vbr-api.a2cps.cloud/shipments/tracking/285590095441/containers' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token

A successful response would be:

  [
  {
      "container_id": "eAbV8nryeVoX",
      "container_tracking_id": "K_NS_BOX_ALI0001",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  },
  {
      "container_id": "P4KAOZ088xbpZ",
      "container_tracking_id": "K_NS_BOX_ALI0002",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  },
  {
      "container_id": "8em97go61M29W",
      "container_tracking_id": "K_NS_BOX_ALI0003",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  },
  {
      "container_id": "8L62j5zZ7yWP6",
      "container_tracking_id": "K_NS_BOX_ALI0004",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  },
  {
      "container_id": "7ykNrLzkZR3g3",
      "container_tracking_id": "K_NS_BOX_ALI0005",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  },
  {
      "container_id": "8PAnJWgwJNKLp",
      "container_tracking_id": "K_NS_BOX_ALI0006",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  }
]

Update status of each container¶

The PATCH /containers/{container_id}/status endpoint can be used to update the status of a container.

Let us pick a container_id of interest and update it’s status.

curl -X 'PATCH' \
'https://vbr-api.a2cps.cloud/containers/8PAnJWgwJNKLp/status' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token \
-H 'Content-Type: application/json' \
-d '{
    "status": "created",
    "comment": "string"
}'

A successful response would look like:

{
     "container_id": "8PAnJWgwJNKLp",
     "container_tracking_id": "K_NS_BOX_ALI0006",
     "container_type": "blood aliquot freezer box",
     "location": "MCC1: NorthShore University HealthSystem",
     "status": "container.created",
     "tracking_id": "285590095441"
 }

We can modify the status of each container using this endpoint.

Update location of each container¶

To update the location of each container, we need to find out the location_id of the location of interest. For e.g: “location”: “MCC1: NorthShore University HealthSystem”, let us find it’s location_id by following the procedure below.

Use the GET /locations/ endpoint to get a list of locations with their details.

 curl -X 'GET' \
'https://vbr-api.a2cps.cloud/locations/?offset=0&limit=50' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token

[
   {
      "location_id": "PAPmJLX2Pr4yM",
      "display_name": "MCC1: Institute for Translational Medicine",
      "address1": "",
      "address2": "",
      "address3": "",
      "city": "Chicago",
      "state_province_country": "IL",
      "zip_or_postcode": "60637",
      "organization": "ITM"
   },
   {
      "location_id": "PAPmqezqm8rOn",
      "display_name": "MCC1: The University of Chicago Medical Center",
      "address1": "",
      "address2": "",
      "address3": "",
      "city": "Chicago",
      "state_province_country": "IL",
      "zip_or_postcode": "60637",
      "organization": "UCMC"
   },
   {
      "location_id": "PAPmqjv157Moe",
      "display_name": "MCC1: NorthShore University HealthSystem",
      "address1": "",
      "address2": "",
      "address3": "",
      "city": "Evanston",
      "state_province_country": "IL",
      "zip_or_postcode": "60201",
      "organization": "NS"
   }
]

From the above response, we can see the the MCC1: NorthShore University HealthSystem corresponds to location_id : PAPmqjv157Moe

With the location_id in hand, we can now update the location of a container of interest.

The PATCH /containers/{container_id}/location endpoint can be used to update the location of each container.
Let us update the location of the container_id : 8PAnJWgwJNKLp

curl -X 'PATCH' \
'https://vbr-api.a2cps.cloud/containers/8PAnJWgwJNKLp/location' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token \
-H 'Content-Type: application/json' \
-d '{
   "location_id": "PAPmqjv157Moe",
   "comment": "string"
}'

A successful response would look like:

{
   "container_id": "8PAnJWgwJNKLp",
   "container_tracking_id": "K_NS_BOX_ALI0006",
   "container_type": "blood aliquot freezer box",
   "location": "MCC1: NorthShore University HealthSystem",
   "status": "container.created",
   "tracking_id": "285590095441"
}

List biosamples in each container¶

The GET /containers/{container_id}/biospecimens can be used to list the biospecimens in a container.

The curl request would be:

 curl -X 'GET' \
'https://vbr-api.a2cps.cloud/containers/8PAnJWgwJNKLp/biospecimens' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Tkeno

A successful response would look like:

  [
  {
      "biospecimen_id": "PdrmvReLkjeNB",
      "tracking_id": "K_NS_P_0050",
      "creation_time": "2021-09-08T00:00:00",
      "biospecimen_type": "serum or plasma",
      "collection_id": "8P6R89Y60NBn8",
      "collection_tracking_id": "K_NS_KIT_0050",
      "container_id": "8PAnJWgwJNKLp",
      "container_tracking_id": "K_NS_BOX_ALI0006",
      "project": "A2CPS Multisite Clinical Center 1",
      "status": "created",
      "unit": "plasma_aliquot_tube",
      "subject_guid": "67c83cf9-4e9e-985d-1003-e776efecee86",
      "subject_id": "1bnoL9dYY8xx8",
      "bscp_time_blood_draw": "2021-09-08T11:03:00",
      "bscp_time_centrifuge": "2021-09-08T11:23:00",
      "bscp_aliquot_freezer_time": "2021-09-08T11:28:00",
      "bscp_deg_of_hemolysis": 0,
      "bscp_phleb_by_init": "AV",
      "bscp_procby_initials": "MR",
      "bscp_protocol_dev": false,
      "bscp_comments": "",
      "location": "MCC1: NorthShore University HealthSystem"
  },
  {
      "biospecimen_id": "1yv0R0NvKBYXm",
      "tracking_id": "K_NS_P_0047",
      "creation_time": "2021-09-13T00:00:00",
      "biospecimen_type": "serum or plasma",
      "collection_id": "7kgm6XRjgkvmb",
      "collection_tracking_id": "K_NS_KIT_0047",
      "container_id": "8PAnJWgwJNKLp",
      "container_tracking_id": "K_NS_BOX_ALI0006",
      "project": "A2CPS Multisite Clinical Center 1",
      "status": "created",
      "unit": "plasma_aliquot_tube",
      "subject_guid": "24caec78-fd6d-5843-6338-d01d21d966a9",
      "subject_id": "P4Z1nP60yYkqX",
      "bscp_time_blood_draw": "2021-09-13T09:34:00",
      "bscp_time_centrifuge": "2021-09-13T09:54:00",
      "bscp_aliquot_freezer_time": "2021-09-13T09:59:00",
      "bscp_deg_of_hemolysis": 0,
      "bscp_phleb_by_init": "SL",
      "bscp_procby_initials": "MR",
      "bscp_protocol_dev": false,
      "bscp_comments": "",
      "location": "MCC1: NorthShore University HealthSystem"
  }
]

Update status of each biosample¶

We can update the status of a biospecimen using the PATCH /biospecimens/{biospecimen_id}/status endpoint.

The permitted values for status are: “inflight”, “present”, “spoiled”, “depleted”, “lost”, “destroyed”.

The curl request would be:

curl -X 'PATCH' \
   'https://vbr-api.a2cps.cloud/biospecimens/7yAnxZN36BJJb/status' \
   -H 'accept: application/json' \
   -H 'Authorization: Bearer Token \
   -H 'Content-Type: application/json' \
   -d '{
      "status": "inflight",
      "comment": "string"
   }'

A successful response would look like:

{
   "biospecimen_id": "7yAnxZN36BJJb",
   "tracking_id": "K_RU_P_0017",
   "creation_time": "2021-04-30T00:00:00",
   "biospecimen_type": "serum or plasma",
   "collection_id": "PdV482PnBozxe",
   "collection_tracking_id": "K_RU_KIT_0021",
   "container_id": "8PqD2Xb7AgzA2",
   "container_tracking_id": "K_RU_BOX_ALI_0002",
   "project": "A2CPS Multisite Clinical Center 1",
   "status": "measurement.inflight",
   "unit": "plasma_aliquot_tube",
   "subject_guid": "90f8fc45-5d53-0de4-6853-284607a8c4e6",
   "subject_id": "Pxk1yXJPV3ADX",
   "bscp_time_blood_draw": "2021-04-30T11:53:00",
   "bscp_time_centrifuge": "2021-04-30T12:13:00",
   "bscp_aliquot_freezer_time": "2021-04-30T12:24:00",
   "bscp_deg_of_hemolysis": 1,
   "bscp_phleb_by_init": "KB",
   "bscp_procby_initials": "MM",
   "bscp_protocol_dev": true,
   "bscp_comments": "Unable to collect blood at baseline. Blood collected DOS.",
   "location": "MCC1: Rush University Medical Center"
}

Update tracking ID for each biosample (if non-unique)¶

We can update the Tracking Id of a biospecimen to an Id of our choice.

The curl request would be:

curl -X 'PATCH' \
   'https://vbr-api.a2cps.cloud/biospecimens/7yAnxZN36BJJb/tracking_id' \
   -H 'accept: application/json' \
   -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0ZTcyNTM2NC1hNzUzLTRkMjEtYmI2Ni1kYTgxZDEzZjRmNzIiLCJpc3MiOiJodHRwczovL2EyY3BzZGV2LnRhcGlzLmlvL3YzL3Rva2VucyIsInN1YiI6InNnb3BhbEBhMmNwc2RldiIsInRhcGlzL3RlbmFudF9pZCI6ImEyY3BzZGV2IiwidGFwaXMvdG9rZW5fdHlwZSI6ImFjY2VzcyIsInRhcGlzL2RlbGVnYXRpb24iOmZhbHNlLCJ0YXBpcy9kZWxlZ2F0aW9uX3N1YiI6bnVsbCwidGFwaXMvdXNlcm5hbWUiOiJzZ29wYWwiLCJ0YXBpcy9hY2NvdW50X3R5cGUiOiJ1c2VyIiwiZXhwIjoxNjQzNjcwODI3LCJ0YXBpcy9jbGllbnRfaWQiOm51bGwsInRhcGlzL2dyYW50X3R5cGUiOiJwYXNzd29yZCJ9.DwyzMvLGm1hPvxFmMRpPGJ9DhyZqQTlp_newlgRCFvKsywDVnGofOD3s62OBxRJvuaxdlfSKoWTnPzGTfuFfItKCGzOWl9USkvKnroRq8m47z5gX1m3DkqOE_zrzyQn-u4nqJvFGWOLOPB94W5mgf4jFncU2LXmNdjy5eJvmqSXe3FqKYHxsPRweZc12ykgUYeaJSmd45Pce8bG2-KTLEcvX3ECh6sjtJ7w5rZY5ASn0BPBayYMUtUsJrV5dKwmAmRWbxjDvBf9sHysxpUj2FwkbIsMTwSyDUN9Euii0zbKfYcUg3fBJUYF86ll3CNpixzxe23T6Tr9jbf2HE5PDTQ' \
   -H 'Content-Type: application/json' \
   -d '{
      "tracking_id": "1234check",
      "comment": "Optional comment explaining or documenting the change"
   }'

A successful response would hold the new tracking_id for our biospecimen.

{
   "biospecimen_id": "7yAnxZN36BJJb",
   "tracking_id": "1234check",
   "creation_time": "2021-04-30T00:00:00",
   "biospecimen_type": "serum or plasma",
   "collection_id": "PdV482PnBozxe",
   "collection_tracking_id": "K_RU_KIT_0021",
   "container_id": "8PqD2Xb7AgzA2",
   "container_tracking_id": "K_RU_BOX_ALI_0002",
   "project": "A2CPS Multisite Clinical Center 1",
   "status": "measurement.inflight",
   "unit": "plasma_aliquot_tube",
   "subject_guid": "90f8fc45-5d53-0de4-6853-284607a8c4e6",
   "subject_id": "Pxk1yXJPV3ADX",
   "bscp_time_blood_draw": "2021-04-30T11:53:00",
   "bscp_time_centrifuge": "2021-04-30T12:13:00",
   "bscp_aliquot_freezer_time": "2021-04-30T12:24:00",
   "bscp_deg_of_hemolysis": 1,
   "bscp_phleb_by_init": "KB",
   "bscp_procby_initials": "MM",
   "bscp_protocol_dev": true,
   "bscp_comments": "Unable to collect blood at baseline. Blood collected DOS.",
   "location": "MCC1: Rush University Medical Center"
}

Welcome to VBR API’s documentation!¶

A2CPS Virtual Biospecimen Repository API¶

Prerequistes¶

Getting Started¶

Authentication and Authorization¶

Alternate Method for Authentication¶

To Verify Authentication was successfull¶

Biospecimens¶

List Biospecimens¶

Filter results¶

Get Biospecimen By Id¶

Get Biospecimen By Tracking Id¶

Update Biospecimen Container¶

Update Biospecimen Status¶

Update Biospecimen Tracking Id¶

Containers¶

List Containers¶

Get Container By Id¶

Workflows¶

Get shipment by tracking ID¶

Update shipment status¶

List containers in shipment¶

Update status of each container¶

Update location of each container¶

List biosamples in each container¶

Update status of each biosample¶

Update tracking ID for each biosample (if non-unique)¶

Indices and tables¶

VBR API

Navigation

Related Topics