THE csms 2.32.0 INTERVENTIONAL API

Overview

The CSMS 2.32.0 INTERVENTIONAL API is composed of a collection of endpoints which you can use to interact with the many features of the system.

Endpoints

You can follow the instructions in the codeblocks in this guide, in addition to using the CSMS GUI, to interact with the APIs. There are two csms tiers that you can interact with:

  The User Accessibility Tier (UAT) is for users who want to test the features and code.<br>
  <u>UAT</u>: <a href="https://csms-api-uat.nci.nih.gov/api/v2">https://csms-api-uat.nci.nih.gov/api/v2</a><br>
  <u>UAT API GUI</u>: <a href="https://csms-uat.nci.nih.gov/doc">https://csms-uat.nci.nih.gov/doc</a><br><br>

  <u>Examples</u>:<br>
  <a href="https://csms-api-uat.nci.nih.gov/api/v2">https://csms-api-uat.nci.nih.gov/api/v2/manifests?manifest_id=X</a><br>
  <a href="https://csms-api-uat.nci.nih.gov/api/v2">https://csms-api-uat.nci.nih.gov/api/v2/manifests?manifest_id=X&status=shipped</a><br><br>





  The Production tier is for working with your live data in a stable environment.<br>
  <u>Production</u>: <a href="https://csms-api.nci.nih.gov/api/v2">https://csms-api.nci.nih.gov/api/v2</a><br>
  <u>Production API GUI</u>: <a href="https://csms.nci.nih.gov/doc">https://csms.nci.nih.gov/doc</a><br><br>

  <u>Examples</u>:<br>
  <a href="https://csms-api.nci.nih.gov/api/v2">https://csms-api.nci.nih.gov/api/v2/manifests?manifest_id=X</a><br>
  <a href="https://csms-api.nci.nih.gov/api/v2">https://csms-api.nci.nih.gov/api/v2/manifests?manifest_id=X&status=shipped</a><br><br>

In order to use the csms API, an Okta API token is required for authentication. The API token is tier specific. For example, an API token for UAT will not work with the Production tier. Some API endpoints and operations are restricted based on role and may not work with your API token.

The sample requests in this guide are examples only. You should substitute call-specific parameters with your own values.

Request Headers

In order to use the CSMS API, clients must set the following request headers accordingly:

GET /api/v1/not_a_real_endpoint
Host: csms-api-uat.nci.nih.gov
Authorization: Bearer yourBearerToken
Accept: application/json

PATCH /api/v1/not_a_real_endpoint
Host: csms-api-uat.nci.nih.gov
Authorization: Bearer yourBearerToken
Content-Type: application/json
Accept: application/json

POST /api/v1/not_a_real_endpoint
Host: csms-api-uat.nci.nih.gov
Authorization: Bearer yourBearerToken
Content-Type: application/json
Accept: application/json

PUT /api/v1/not_a_real_endpoint
Host: csms-api-uat.nci.nih.gov
Authorization: Bearer yourBearerToken
Content-Type: application/json
Accept: application/json

AUTHORIZATION

Requests must contain valid logon credentials in the header. For example, Authorization: Bearer yourBearerToken

See the GETTING STARTED section for details.

CONTENT-TYPE

All PATCH, POST and PUT requests must contain a valid JSON body with the Content-Type header set to application/json.

ACCEPT

Unless otherwise noted, all CSMS APIs are JSON based. Your request should include an Accept: application/json header, however this header is optional as any response under the /api/ namespace will return JSON.

Field Projections

GET /manifests?manifest_id=213

RESPONSE BODY

  {
    "manifest_id": "123",
    "biobank_id": "abc",
    "receiving_party": "xyz"
    "samples": [
      {
        "cimac_id": "456"
      },
      {
        "cimac_id": "789"
      }
    ]
  }
  
  

GET /manifests?manifest_id=213&fields=manifest_id,biobank_id

RESPONSE BODY

  {
    "manifest_id": "123",
    "biobank_id": "abc",
  }

Field projection controls how much of an entity's data is displayed in response to an API request.

All APIs have a default set of field projections that control which fields are returned. If you don't need certain fields, you can decrease response time and payload size by using a projection to ask only for the fields your application is interested in.

Field projections are defined using the &fields= query parameter and narrowed by providing a comma-separated list of field names that you want returned as the value of the parameter.

Error Handling

CSMS uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (for example, a required parameter was omitted, invalid search parameter, etc.). Codes in the 5xx range indicate an error with CSMS's servers (these are rare).

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

Attributes

GETTING STARTED

Account Requests

In order to get access to use the CSMS API, please send an access request email to csms-support@nih.gov. The email should contain the following information:

• Name of user
• Email Address
• Role Type: Biobank or Lab.
• Organization Affiliation: ID or Name
• Access Tier:
  • Specify 'UAT' if you have not completed training on the User Accessibility Tier (UAT).
  • Specify 'Production' if you have completed training on UAT and it has been verified by the CSMS Administrator.
• Study Type:
  • Specify 'Ancillary/Correlative' if you will be using the system for Ancillary/Correlative studies.
  • Specify 'Interventional' if you will be using the system for Interventional studies.
  • Specify 'Ancillary/Correlative, Interventional' if your institution requires access to work with both types of studies.
• Any additional contact information

Once the access request email has been received by the csms Application Support Team, a support team member will review the request and provide further instructions on how to generate an access token in order to use the csms API.

Note that if your organization is requesting machine-machine API communication with the CSMS API and access to both Ancillary/Correlative and Interventional study types, you will receive a unique Okta client id/client secret pairing to use for each study type.

Authentication

# You can also use wget
curl -X POST https://bioappdev.okta.com/oauth2/[csms_server_id_UAT]/v1/token \
  -H'Content-Type: x-www-form-urlencoded'
  -d'client_id&client_secret=&grant_type=client_credentials'

All API requests must provide authentication. The csms API uses Okta as the authentication provider, leveraging OAuth2 authentication using the client credentials flow. The access token returned from the endpoints should be passed in the headers of HTTP request, as: Authorization: Bearer [TOKEN].

There are two variable values used in Okta access token generation for CSMS

• Client ID
• Client Secret

Note that the Client Secret is secret and must be kept confidential. If discovered that your Client Secret has been lost or compromised, contact our Support Team immediately at csms_support@mail.nih.gov.

The variable values Client ID and Client Secret will be provided to you following access approval. The following is an example of how an access toke is generated:

Roles & Authorization

The csms API leverages role-based authorization that allows for specific operations to be performed in the application. Presently the API accepts the following roles and the corresponding operations:

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

COMMENTS

Routes for comments

Create Comment

<span class="endpoint">
<span class="method post"> POST </span>
<code>/comments</code>
</span>

# You can also use wget

curl -X POST /comments \
  -H 'Content-Type: application/json'

const inputBody = '{
  "comment": "comment text about an entity",
  "entity_id": "20200727:testuser:63693",
  "entity_type": "manifest"
}';
const headers = {
  'Content-Type':'application/json'
};

fetch('/comments',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json'
}

r = requests.post('/comments', headers = headers)

print(r.json())

POST /comments

Comment information in a JSON dict sent to this path is used to create a new comment.

REQUEST BODY

{
  "comment": "comment text about an entity",
  "entity_id": "20200727:testuser:63693",
  "entity_type": "manifest"
}

Parameters

Enumerated Values

Responses

Query Comments

<span class="endpoint">
<span class="method get"> GET </span>
<code>/comments</code>
</span>

# You can also use wget

curl -X GET /comments?comment=comment

fetch('/comments?comment=comment',
{
  method: 'GET'

})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests

r = requests.get('/comments'
, params={"comment":"comment"}
)

print(r.json())

GET /comments

Retrieve comment information, matching search parameters.

Parameters

Enumerated Values

Responses

Retrieve Comment

<span class="endpoint">
<span class="method get"> GET </span>
<code>/comments/{commentId}</code>
</span>

# You can also use wget

curl -X GET /comments/{commentId}

fetch('/comments/{commentId}',
{
  method: 'GET'

})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests

r = requests.get('/comments/{commentId}')

print(r.json())

GET /comments/{commentId}

Retrieve the specified comment.

Parameters

Responses

DOCUMENTS

Routes for documents

Upload or Associate Document

<span class="endpoint">
<span class="method post"> POST </span>
<code>/documents</code>
</span>

# You can also use wget

curl -X POST /documents \
  -H 'Content-Type: multipart/form-data' \
  -H 'Accept: application/json' \
  -H 'Content-Disposition: Attachment; filename=test.txt' \
  -H 'x-file-descriptor: file description'

const inputBody = 'This is a test document text file';
const headers = {
  'Content-Type':'multipart/form-data',
  'Accept':'application/json',
  'Content-Disposition':'Attachment; filename=test.txt',
  'x-file-descriptor':'file description'
};

fetch('/documents',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'multipart/form-data',
  'Accept': 'application/json',
  'Content-Disposition': 'Attachment; filename=test.txt',
  'x-file-descriptor': 'file description'
}

r = requests.post('/documents', headers = headers)

print(r.json())

POST /documents

Upload a document or create a document association to an entity. Either upload a document by sending a valid file as the payload or create an association between an existing document and entity by providing the data in a JSON payload.

REQUEST BODY

"This is a test document text file"

This is a test document text file

Parameters

Enumerated Values

200 Response

{
  "file_id": "1618414651177_test.txt",
  "file_name": "test.txt",
  "message": "Association has been successfully created for Document 1618414651177_test.txt to Manifest 20220719:nationwide:68662758"
}

Responses

Response Schema

Query Document

<span class="endpoint">
<span class="method get"> GET </span>
<code>/documents</code>
</span>

# You can also use wget

curl -X GET /documents?descriptor=string&entity_id=20200727

fetch('/documents?descriptor=string&entity_id=20200727',
{
  method: 'GET'

})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests

r = requests.get('/documents'
, params={"descriptor":"string","entity_id":"20200727"}
)

print(r.json())

GET /documents

Retrieve document information, matching search parameters.

Parameters

Enumerated Values

Responses

Retrieve Document

<span class="endpoint">
<span class="method get"> GET </span>
<code>/documents/{file_id}</code>
</span>

# You can also use wget

curl -X GET /documents/{file_id} \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/documents/{file_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/documents/{file_id}', headers = headers)

print(r.json())

GET /documents/{file_id}

Fetch JSON representing information about a specific file that was uploaded.

Parameters

200 Response

{
  "data": {
    "file_id": "1618414651177_test.txt",
    "file_name": "test.txt",
    "s3_path": "docs/biobank/csms_developer@bioappdev.org/1618414651177_test.txt",
    "creator": "csms_developer@bioappdev.org",
    "creator_role": "biobank",
    "create_date": "2021-04-14T15:37:31Z"
  },
  "total": 1,
  "limit": 1
}

Responses

Response Schema

Disassociate Document

<span class="endpoint">
<span class="method delete"> DELETE </span>
<code>/documents/{file_id}/{entity_type}/{entity_id}</code>
</span>

# You can also use wget

curl -X DELETE /documents/{file_id}/{entity_type}/{entity_id}

fetch('/documents/{file_id}/{entity_type}/{entity_id}',
{
  method: 'DELETE'

})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests

r = requests.delete('/documents/{file_id}/{entity_type}/{entity_id}')

print(r.json())

DELETE /documents/{file_id}/{entity_type}/{entity_id}

Disassociate document from the specified entity.

Parameters

Responses

JOBS

Routes for jobs

Query Bulk Manifest Jobs

<span class="endpoint">
<span class="method get"> GET </span>
<code>/jobs</code>
</span>

# You can also use wget

curl -X GET /jobs?job_id=1609340193_csms_developer \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/jobs?job_id=1609340193_csms_developer',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/jobs'
, params={"job_id":"1609340193_csms_developer"}
, headers = headers)

print(r.json())

GET /jobs

Retrieve manifest bulk submission jobs information based on matching search parameters (for example, "creator=biobank").

Parameters

200 Response

{
  "data": {
    "job_id": "1648242062541_csms_developer@bioappdev.org",
    "manifest_id": "20220325:stanford:75522716",
    "sender_institution_id": "BBNCHP001",
    "submitter": "csms_developer@bioappdev.org",
    "status": "completed",
    "create_date": "2022-03-25T21:01:06Z",
    "message": "\"The manifest was successfully processed.\""
  },
  "total": 1,
  "limit": 1
}

Responses

Response Schema

Create Bulk Upload Manifest Job

<span class="endpoint">
<span class="method post"> POST </span>
<code>/jobs/manifest</code>
</span>

# You can also use wget

curl -X POST /jobs/manifest \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const inputBody = '{
  "shipping_manifest": {
    "comments": "This is a comment for the shipping manifest",
    "courier": "UPS",
    "recipient_institution_id": "BBNCHP001",
    "sender_city": "Richmond",
    "sender_country": "USA",
    "sender_email": "enrolling_user@enroll_site.gov",
    "sender_institution_id": "enroll-99876512",
    "sender_institution_name": "blood draw lab east",
    "sender_person_name": "Joe Technician",
    "sender_phone": "000-000-0000",
    "sender_state": "Virginia",
    "sender_street_1": "Main St",
    "sender_street_2": "Suite 2",
    "sender_zip_code": "20047",
    "shipping_condition": "Frozen Dry Ice",
    "shipping_condition_other": "insulated",
    "shipping_date": "2021-04-30",
    "tracking_number": "4567788343"
  },
  "sample_manifest": []
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('/jobs/manifest',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('/jobs/manifest', headers = headers)

print(r.json())

POST /jobs/manifest

Similar to the manifest POST endpoint, but intended for submitting manifests that have a number of samples greater than 39. Manifest information can be submitted in the same JSON dict format or using an Excel file template (see Manifest template download endpoint for details).

REQUEST BODY

{
  "shipping_manifest": {
    "comments": "This is a comment for the shipping manifest",
    "courier": "UPS",
    "recipient_institution_id": "BBNCHP001",
    "sender_city": "Richmond",
    "sender_country": "USA",
    "sender_email": "enrolling_user@enroll_site.gov",
    "sender_institution_id": "enroll-99876512",
    "sender_institution_name": "blood draw lab east",
    "sender_person_name": "Joe Technician",
    "sender_phone": "000-000-0000",
    "sender_state": "Virginia",
    "sender_street_1": "Main St",
    "sender_street_2": "Suite 2",
    "sender_zip_code": "20047",
    "shipping_condition": "Frozen Dry Ice",
    "shipping_condition_other": "insulated",
    "shipping_date": "2021-04-30",
    "tracking_number": "4567788343"
  },
  "sample_manifest": []
}

Parameters

Enumerated Values

201 Response

{
  "job_id": "1648677659759_administrator",
  "job_url": "https://csms-api-int.nci.nih.gov/api/v2/manifests/jobs/1648677659759_administrator",
  "creator": "administrator",
  "create_date": "2022-03-30T22:00:59Z",
  "message": "A bulk upload job has been created. Please check job status with GET requests to the job URL."
}

Responses

Response Schema

Retrieve Bulk Manifest Job

<span class="endpoint">
<span class="method get"> GET </span>
<code>/jobs/manifest/{job_id}</code>
</span>

# You can also use wget

curl -X GET /jobs/manifest/{job_id} \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/jobs/manifest/{job_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/jobs/manifest/{job_id}', headers = headers)

print(r.json())

GET /jobs/manifest/{job_id}

Retrieve specific bulk submission job information.

Parameters

200 Response

{
  "data": {
    "job_id": "1648242062541_csms_developer@bioappdev.org",
    "manifest_id": "20220325:stanford:75522716",
    "sender_institution_id": "BBNCHP001",
    "submitter": "csms_developer@bioappdev.org",
    "status": "completed",
    "create_date": "2022-03-25T21:01:06Z",
    "message": "\"The manifest was successfully processed.\""
  },
  "total": 1,
  "limit": 1
}

Responses

Response Schema

MANIFESTS

Routes for manifests

Create Manifest

<span class="endpoint">
<span class="method post"> POST </span>
<code>/manifests</code>
</span>

# You can also use wget

curl -X POST /manifests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const inputBody = '{
  "shipping_manifest": {
    "comments": "This is a comment for the shipping manifest",
    "courier": "UPS",
    "recipient_institution_id": "BBNCHP001",
    "sender_city": "Richmond",
    "sender_country": "USA",
    "sender_email": "enrolling_user@enroll_site.gov",
    "sender_institution_id": "enroll-99876512",
    "sender_institution_name": "blood draw lab east",
    "sender_person_name": "Joe Technician",
    "sender_phone": "000-000-0000",
    "sender_state": "Virginia",
    "sender_street_1": "Main St",
    "sender_street_2": "Suite 2",
    "sender_zip_code": "20047",
    "shipping_condition": "Frozen Dry Ice",
    "shipping_condition_other": "insulated",
    "shipping_date": "2021-04-30",
    "tracking_number": "4567788343"
  },
  "sample_manifest": []
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('/manifests',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('/manifests', headers = headers)

print(r.json())

POST /manifests

The API enforces a hard limit of 39 samples that can be created as part of creating a manifest. To add more than 39 samples in a single request, refer to the Jobs API POST endpoint.

REQUEST BODY

{
  "shipping_manifest": {
    "comments": "This is a comment for the shipping manifest",
    "courier": "UPS",
    "recipient_institution_id": "BBNCHP001",
    "sender_city": "Richmond",
    "sender_country": "USA",
    "sender_email": "enrolling_user@enroll_site.gov",
    "sender_institution_id": "enroll-99876512",
    "sender_institution_name": "blood draw lab east",
    "sender_person_name": "Joe Technician",
    "sender_phone": "000-000-0000",
    "sender_state": "Virginia",
    "sender_street_1": "Main St",
    "sender_street_2": "Suite 2",
    "sender_zip_code": "20047",
    "shipping_condition": "Frozen Dry Ice",
    "shipping_condition_other": "insulated",
    "shipping_date": "2021-04-30",
    "tracking_number": "4567788343"
  },
  "sample_manifest": []
}

Parameters

Enumerated Values

201 Response

{
  "message": "Data Received Successfully by CSMS",
  "manifest_id": "20220330:nationwide:66786714",
  "csms_ids": [],
  "modified_time": 1648665187
}

Responses

Query Manifests

<span class="endpoint">
<span class="method get"> GET </span>
<code>/manifests</code>
</span>

# You can also use wget

curl -X GET /manifests?comments=string&courier=USPS \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/manifests?comments=string&courier=USPS',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/manifests'
, params={"comments":"string","courier":"USPS"}
, headers = headers)

print(r.json())

GET /manifests

Retrieve manifest(s) based on matching search parameters (for example, "manifest_id=20210101:biobank:61717939").

Parameters

Enumerated Values

200 Response

{
  "data": {
    "recipient_institution_id": "LBFHCR002",
    "event": "update",
    "reason": "just a test",
    "sender_institution_id": "BBNCHP001",
    "modified_timestamp": "2022-03-30T18:34:50Z",
    "modified_time": 1648665290,
    "manifest_id": "20220330:nationwide:66786714",
    "submitter": "csms_developer@bioappdev.org",
    "status": "draft",
    "samples": []
  },
  "total": 1,
  "limit": 1
}

Responses

Update Manifest

<span class="endpoint">
<span class="method patch"> PATCH </span>
<code>/manifests/{manifest_id}</code>
</span>

# You can also use wget

curl -X PATCH /manifests/{manifest_id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const inputBody = '{
  "shipping_manifest": {
    "comments": "This is a comment for the shipping manifest",
    "courier": "UPS",
    "package_condition": "Leakage",
    "received_date": "2021-04-30",
    "received_time": "16:30 Hawaii-Aleutian",
    "recipient_institution_id": "BBNCHP001",
    "sender_city": "Richmond",
    "sender_country": "USA",
    "sender_email": "enrolling_user@enroll_site.gov",
    "sender_institution_id": "enroll-99876512",
    "sender_institution_name": "blood draw lab east",
    "sender_person_name": "Joe Technician",
    "sender_phone": "000-000-0000",
    "sender_state": "Virginia",
    "sender_street_1": "Main St",
    "sender_street_2": "Suite 2",
    "sender_zip_code": "20047",
    "shipping_condition": "Frozen Dry Ice",
    "shipping_condition_other": "insulated",
    "shipping_date": "2021-04-30",
    "status": "received",
    "tracking_number": "4567788343"
  },
  "sample_manifest": []
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('/manifests/{manifest_id}',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.patch('/manifests/{manifest_id}', headers = headers)

print(r.json())

PATCH /manifests/{manifest_id}

The API enforces a hard limit of 39 samples that can be updated as part of updating a manifest. To update more than 39 samples in a single request, refer to the Jobs API PUT endpoint.

REQUEST BODY

{
  "shipping_manifest": {
    "comments": "This is a comment for the shipping manifest",
    "courier": "UPS",
    "package_condition": "Leakage",
    "received_date": "2021-04-30",
    "received_time": "16:30 Hawaii-Aleutian",
    "recipient_institution_id": "BBNCHP001",
    "sender_city": "Richmond",
    "sender_country": "USA",
    "sender_email": "enrolling_user@enroll_site.gov",
    "sender_institution_id": "enroll-99876512",
    "sender_institution_name": "blood draw lab east",
    "sender_person_name": "Joe Technician",
    "sender_phone": "000-000-0000",
    "sender_state": "Virginia",
    "sender_street_1": "Main St",
    "sender_street_2": "Suite 2",
    "sender_zip_code": "20047",
    "shipping_condition": "Frozen Dry Ice",
    "shipping_condition_other": "insulated",
    "shipping_date": "2021-04-30",
    "status": "received",
    "tracking_number": "4567788343"
  },
  "sample_manifest": []
}

Parameters

Enumerated Values

200 Response

{
  "message": "Data Received Successfully by CSMS",
  "manifest_id": "20220330:nationwide:66786714",
  "csms_ids": [],
  "modified_time": 1648665187
}

Responses

Response Schema

Retrieve Manifest

<span class="endpoint">
<span class="method get"> GET </span>
<code>/manifests/{manifest_id}</code>
</span>

# You can also use wget

curl -X GET /manifests/{manifest_id} \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/manifests/{manifest_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/manifests/{manifest_id}', headers = headers)

print(r.json())

GET /manifests/{manifest_id}

Retrieve the specified manifest. Specify 'Accept = vnd.openxmlformats-officedocument.spreadsheetml.sheet' in the header to download Manifest Excel file.

Parameters

200 Response

{
  "data": {
    "recipient_institution_id": "LBFHCR002",
    "excluded": false,
    "ship_from": "somewhere",
    "event": "update",
    "reason": "just a test",
    "sender_institution_id": "BBNCHP001",
    "modified_timestamp": "2022-03-30T18:34:50Z",
    "modified_time": 1648665290,
    "manifest_id": "20220330:nationwide:66786714",
    "submitter": "csms_developer@bioappdev.org",
    "status": "draft",
    "samples": []
  },
  "total": 1,
  "limit": 1
}

Responses

Response Schema

Delete Manifest

<span class="endpoint">
<span class="method delete"> DELETE </span>
<code>/manifests/{manifest_id}</code>
</span>

# You can also use wget

curl -X DELETE /manifests/{manifest_id} \
  -H 'Accept: application/json' \
  -H 'x-delete-reason: Erroneously created'

const headers = {
  'Accept':'application/json',
  'x-delete-reason':'Erroneously created'
};

fetch('/manifests/{manifest_id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json',
  'x-delete-reason': 'Erroneously created'
}

r = requests.delete('/manifests/{manifest_id}', headers = headers)

print(r.json())

DELETE /manifests/{manifest_id}

Delete the specified manifest.

Parameters

200 Response

{
  "message": "manifest deleted 20220330:nationwide:66786714"
}

Responses

Response Schema

Retrieve Manifest History

<span class="endpoint">
<span class="method get"> GET </span>
<code>/manifests/history/{manifest_id}</code>
</span>

# You can also use wget

curl -X GET /manifests/history/{manifest_id} \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/manifests/history/{manifest_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/manifests/history/{manifest_id}', headers = headers)

print(r.json())

GET /manifests/history/{manifest_id}

Retrieve all history for specified manifest

Parameters

200 Response

[
  {
    "data": {
      "qldb_id": "DJ3vVRFPlkx7rj9CNs0lLb",
      "qldb_version": 0,
      "qldb_txTime": "2021-12-15 15:23:42.117000+00:00",
      "qldb_txId": "3rXE6l7R8OqJi3YyndUHvG",
      "sender_institution_id": "BBNCHP001",
      "courier": "Inter-Site Delivery",
      "recipient_institution_id": "LBFHCR002",
      "modified_timestamp": "2021-12-15T15:23:42Z",
      "modified_time": 1639581822,
      "manifest_id": "20211215:nationwide:55421230",
      "submitter": "csms_developer@bioappdev.org",
      "status": "draft",
      "excluded": false,
      "event": "create"
    },
    "diff": {
      "qldb_id": [
        null,
        "DJ3vVRFPlkx7rj9CNs0lLb"
      ],
      "qldb_version": [
        null,
        0
      ],
      "qldb_txTime": [
        null,
        "2021-12-15 15:23:42.117000+00:00"
      ],
      "qldb_txId": [
        null,
        "3rXE6l7R8OqJi3YyndUHvG"
      ],
      "sender_institution_id": [
        null,
        "BBNCHP001"
      ],
      "courier": [
        null,
        "Inter-Site Delivery"
      ],
      "recipient_institution_id": [
        null,
        "LBFHCR002"
      ],
      "modified_timestamp": [
        null,
        "2021-12-15T15:23:42Z"
      ],
      "modified_time": [
        null,
        1639581822
      ],
      "manifest_id": [
        null,
        "20211215:nationwide:55421230"
      ],
      "submitter": [
        null,
        "csms_developer@bioappdev.org"
      ],
      "status": [
        null,
        "draft"
      ],
      "excluded": [
        null,
        false
      ],
      "event": [
        null,
        "create"
      ]
    }
  }
]

Responses

Response Schema

Retrieve Manifest Snapshot

<span class="endpoint">
<span class="method get"> GET </span>
<code>/manifests/snapshot/{manifest_id}/{modified_time}</code>
</span>

# You can also use wget

curl -X GET /manifests/snapshot/{manifest_id}/{modified_time} \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/manifests/snapshot/{manifest_id}/{modified_time}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/manifests/snapshot/{manifest_id}/{modified_time}', headers = headers)

print(r.json())

GET /manifests/snapshot/{manifest_id}/{modified_time}

Retrieve a snapshot for the specified manifest

Parameters

200 Response

{
  "data": {
    "recipient_institution_id": "LBCHLA001",
    "sender_email": "test@email.cm",
    "sender_institution_id": "BBNCHP001",
    "sender_institution_name": "MD Anderson Cancer Center",
    "sender_person_name": "Jack Torrance",
    "sender_phone": "703-867-5309",
    "sender_state": "TX",
    "sender_street_1": "123 Main St",
    "sender_zip_code": "20151",
    "shipping_condition": "Ambient",
    "courier": "USPS",
    "schema_version": "2.2.0",
    "status": "draft",
    "recipient_institution_name": "Children's Hospital of Los Angeles - Clinical Immunology Laboratory",
    "modified_timestamp": "2023-10-16T16:17:15Z",
    "modified_time": 1697473035,
    "manifest_id": "20231016:nationwide:58634102",
    "submitter": "0oa3p6e4lvwhhRoxI297",
    "creator_role": "administrator",
    "custodian_institution_id": "Biobank1",
    "event": "create",
    "qldb_id": "Djg3NtZY4DbFxD6UkYwEHA",
    "qldb_version": 0,
    "qldb_txId": "9xSyQQJxR74Ggefm4R6cQ9",
    "qldb_txTime": "2023-10-16 16:17:15.788000+00:00",
    "files_detail": [],
    "comments_detail": [],
    "samples": [
      {
        "sample_id": "pt_download_07",
        "screening_protocol_id": "MYELOMATCH",
        "screening_participant_id": "pt_download_07",
        "biological_sex": "Female",
        "biopsy_site": "C01.9",
        "collection_date": "2021-08-14",
        "collection_time": "10:00 EDT",
        "date_of_birth": "1977-10-01",
        "container_type": "EDTA Tube",
        "collection_event_name": "MRD Assessment",
        "sample_collection_procedure": "Surgical Excision",
        "sample_type": "Skin Tissue",
        "description_of_sample": "Normal",
        "sample_manifest_type": "interventional",
        "schema_version": "2.2.0",
        "modified_timestamp": "2023-10-16T16:17:15Z",
        "modified_time": 1697473035,
        "submitter": null,
        "custodian_institution_id": null,
        "sample_qc_result": null,
        "manifest_id": "20231016:nationwide:58634102",
        "recipient_institution_id": "LBCHLA001",
        "sender_institution_id": "BBNCHP001",
        "status": "draft",
        "creator_role": "administrator",
        "parent_sample_id": "pt_download_07",
        "csms_id": "mm_9106_pbe",
        "original_specimen": "False",
        "event": "create",
        "qldb_id": "HFv3mJQ7c6QBzhaWRMwfT0",
        "qldb_version": 0,
        "qldb_txId": "GJMn2Rbivz19oohIGLi2f6",
        "qldb_txTime": "2023-10-16 16:17:15.962000+00:00",
        "files_detail": [],
        "comments_detail": []
      },
      {
        "sample_id": "pt_download_08",
        "screening_protocol_id": "MYELOMATCH",
        "screening_participant_id": "pt_download_08",
        "biological_sex": "Male",
        "biopsy_site": "C02.9",
        "collection_date": "2020-08-14",
        "collection_time": "10:00 EDT",
        "date_of_birth": "1988-10-01",
        "container_type": "EDTA Tube",
        "collection_event_name": "MRD Assessment",
        "sample_collection_procedure": "Surgical Excision",
        "sample_type": "Skin Tissue",
        "description_of_sample": "Normal",
        "sample_manifest_type": "interventional",
        "schema_version": "2.2.0",
        "modified_timestamp": "2023-10-16T16:17:15Z",
        "modified_time": 1697473035,
        "submitter": null,
        "custodian_institution_id": null,
        "sample_qc_result": null,
        "manifest_id": "20231016:nationwide:58634102",
        "recipient_institution_id": "LBCHLA001",
        "sender_institution_id": "BBNCHP001",
        "status": "draft",
        "creator_role": "administrator",
        "parent_sample_id": "pt_download_08",
        "csms_id": "mm_8024_flw",
        "original_specimen": "False",
        "event": "create",
        "qldb_id": "60bqQFT1O694VhMWxSqVzV",
        "qldb_version": 0,
        "qldb_txId": "GJMn2Rbivz19oohIGLi2f6",
        "qldb_txTime": "2023-10-16 16:17:15.962000+00:00",
        "files_detail": [],
        "comments_detail": []
      }
    ]
  },
  "total": 1
}

Responses

Response Schema

Download Manifest Excel Template

<span class="endpoint">
<span class="method get"> GET </span>
<code>/manifests/template</code>
</span>

# You can also use wget

curl -X GET /manifests/template \
  -H 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'

const headers = {
  'Accept':'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
};

fetch('/manifests/template',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
}

r = requests.get('/manifests/template', headers = headers)

print(r.json())

GET /manifests/template

Download the Manifest Excel Template for Bulk Uploads.

200 Response

Responses

SAMPLES

Routes for samples

Create Sample

<span class="endpoint">
<span class="method post"> POST </span>
<code>/samples</code>
</span>

# You can also use wget

curl -X POST /samples \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const inputBody = '{
  "biological_sex": "Female",
  "biopsy_site": "C50.3",
  "collection_date": "2021-06-02",
  "collection_event_name": "Post-Treatment",
  "collection_time": "16:30 Hawaii-Aleutian",
  "comments": "This is a comment for the sample",
  "container_type": "Other",
  "container_type_other": "Description of some other tube used.",
  "cores_submitted": "Yes",
  "csms_id": "mm_1234_jrh",
  "date_of_birth": "1970-11-30",
  "description_of_sample": "Tumor",
  "description_of_tumor_sample": "Benign",
  "directionality": "Lateral",
  "fixation_stabilization_type": "Ficoll",
  "laterality": "Right",
  "locational_tumor_malignancy_class": "Primary",
  "number_cores_submitted": "2",
  "operational_id": "E1000-A",
  "parent_sample_id": "string",
  "processed_sample_derivative": "Germline DNA",
  "processed_sample_id": "string",
  "processed_sample_type": "Other",
  "sample_collection_procedure": "Other",
  "sample_collection_procedure_other": "Description of Other Procedure Used",
  "sample_id": "E1000-A",
  "sample_manifest_type": "interventional",
  "sample_shipping_condition": "Other",
  "sample_shipping_condition_other": "Describes a shipping condition not available in the predefined list.",
  "sample_type": "Other",
  "sample_type_other": "Some other sample type",
  "sample_uom": "mL",
  "sample_volume_quantity": "1.237",
  "screening_participant_id": "7bh45z",
  "screening_protocol_id": "MyeloMATCH",
  "treatment_participant_id": "tp_99-45688",
  "treatment_protocol_id": "22-6789"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('/samples',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('/samples', headers = headers)

print(r.json())

POST /samples

Sample information in a JSON dict sent to this path for creation of a new sample. The data is validated and queued for update. Samples created using this path may include an optional manfest_id field to associate the sample with a manifest.

REQUEST BODY

{
  "biological_sex": "Female",
  "biopsy_site": "C50.3",
  "collection_date": "2021-06-02",
  "collection_event_name": "Post-Treatment",
  "collection_time": "16:30 Hawaii-Aleutian",
  "comments": "This is a comment for the sample",
  "container_type": "Other",
  "container_type_other": "Description of some other tube used.",
  "cores_submitted": "Yes",
  "csms_id": "mm_1234_jrh",
  "date_of_birth": "1970-11-30",
  "description_of_sample": "Tumor",
  "description_of_tumor_sample": "Benign",
  "directionality": "Lateral",
  "fixation_stabilization_type": "Ficoll",
  "laterality": "Right",
  "locational_tumor_malignancy_class": "Primary",
  "number_cores_submitted": "2",
  "operational_id": "E1000-A",
  "parent_sample_id": "string",
  "processed_sample_derivative": "Germline DNA",
  "processed_sample_id": "string",
  "processed_sample_type": "Other",
  "sample_collection_procedure": "Other",
  "sample_collection_procedure_other": "Description of Other Procedure Used",
  "sample_id": "E1000-A",
  "sample_manifest_type": "interventional",
  "sample_shipping_condition": "Other",
  "sample_shipping_condition_other": "Describes a shipping condition not available in the predefined list.",
  "sample_type": "Other",
  "sample_type_other": "Some other sample type",
  "sample_uom": "mL",
  "sample_volume_quantity": "1.237",
  "screening_participant_id": "7bh45z",
  "screening_protocol_id": "MyeloMATCH",
  "treatment_participant_id": "tp_99-45688",
  "treatment_protocol_id": "22-6789"
}

201 Response

{
  "message": "Data Received Successfully by CSMS",
  "csms_id": "mm_0536_svu",
  "modified_time": 1650889491
}

Responses

Response Schema

Query Samples

<span class="endpoint">
<span class="method get"> GET </span>
<code>/samples</code>
</span>

# You can also use wget

curl -X GET /samples?a260_or_a230_value=10&a260_or_a280_value=10 \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/samples?a260_or_a230_value=10&a260_or_a280_value=10',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/samples'
, params={"a260_or_a230_value":"10","a260_or_a280_value":"10"}
, headers = headers)

print(r.json())

GET /samples

Retrieve sample(s) based on matching search parameters (for example, "csms_id=mm_0536_svu").

Parameters

Enumerated Values

200 Response

{
  "data": [
    {
      "biological_sex": "Female",
      "biopsy_site": "C02.9",
      "collection_date": "2022-06-18",
      "collection_event_name": "Progression",
      "container_type": "Saliva Tube",
      "date_of_birth": "1978-04-22",
      "description_of_sample": "Normal",
      "screening_participant_id": "pt_026",
      "screening_protocol_id": "iMATCH",
      "sample_collection_procedure": "Pleural Thoracentesis",
      "sample_type": "FFPE Section",
      "sample_manifest_type": "interventional",
      "sample_id": "mkMYELOMATCH01",
      "operational_id": "mkOperational1",
      "collection_time": "14:00 EDT",
      "sample_shipping_condition": "Frozen Dry Ice",
      "schema_version": "2.2.0",
      "recipient_institution_id": "LBTWST001",
      "sender_institution_id": "BBNCHP001",
      "creator_role": "administrator",
      "parent_sample_id": "mkMYELOMATCH01",
      "original_specimen": "False",
      "custodian_institution_id": "LBTWST001",
      "sample_qc_result": "QC Pass",
      "status": "in_lab",
      "manifest_id": null,
      "blast_percentage": 55.57,
      "viable_tumor_percent_area": 29.37,
      "viable_stroma_percent_area": 25.5,
      "fibrosis_percent_area": 24.017,
      "percent_viability": 23.3,
      "dv200": 15,
      "rin_value": 5,
      "necrosis_percent_area": 24,
      "csms_id": "im_9049_prm",
      "modified_timestamp": "2023-10-17T19:41:00Z",
      "modified_time": 1697571660,
      "submitter": null,
      "event": "update",
      "files_detail": [],
      "comments_detail": []
    }
  ],
  "total": 1,
  "limit": 1
}

Responses

Response Schema

Update Sample

<span class="endpoint">
<span class="method patch"> PATCH </span>
<code>/samples/{csms_id}</code>
</span>

# You can also use wget

curl -X PATCH /samples/{csms_id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

const inputBody = '{
  "biological_sex": "Female",
  "biopsy_site": "C50.3",
  "collection_date": "2021-06-02",
  "collection_event_name": "Post-Treatment",
  "collection_time": "16:30 Hawaii-Aleutian",
  "container_type": "Other",
  "date_of_birth": "1970-11-30",
  "sample_collection_procedure": "Other",
  "sample_type": "Other",
  "screening_participant_id": "7bh45z",
  "screening_protocol_id": "MyeloMATCH",
  "a260_or_a230_value": 10,
  "a260_or_a280_value": 10,
  "blast_percentage": "1.2",
  "box_coordinates": "tile 22h",
  "comments": "This is a comment for the sample",
  "container_type_other": "Description of some other tube used.",
  "cores_submitted": "Yes",
  "csms_id": "mm_1234_jrh",
  "custodian_institution_id": "string",
  "description_of_sample": "Tumor",
  "description_of_tumor_sample": "Benign",
  "din_value": 10,
  "directionality": "Lateral",
  "dv200": "51.273",
  "event": "string",
  "fibrosis_percent_area": "21.2",
  "fixation_stabilization_type": "Ficoll",
  "laterality": "Right",
  "locational_tumor_malignancy_class": "Primary",
  "manifest_id": "20220729_jrh_65108327",
  "med_tin": "7.381999",
  "necrosis_percent_area": 100,
  "nitrogen_tank": "nx-tank1",
  "number_cores_submitted": "2",
  "operational_id": "E1000-A",
  "original_sample": "True",
  "parent_csms_id": "mm_1214_jrh",
  "parent_sample_id": "string",
  "percent_viability": "1.2",
  "processed_sample_derivative": "Germline DNA",
  "processed_sample_id": "string",
  "processed_sample_type": "Other",
  "rack_id": "rack_id_2204",
  "reason": "string",
  "replacement_sample_requested": "Replacement Not Requested",
  "rin_value": "0.29",
  "sample_collection_procedure_other": "Description of Other Procedure Used",
  "sample_id": "E1000-A",
  "sample_manifest_type": "interventional",
  "sample_qc_fail_reason": "Container Damaged",
  "sample_qc_fail_reason_other": "Incorrect handling of sample",
  "sample_qc_result": "QC Pass",
  "sample_shipping_condition": "Other",
  "sample_shipping_condition_other": "Describes a shipping condition not available in the predefined list.",
  "sample_type_other": "Some other sample type",
  "sample_uom": "mL",
  "sample_volume_quantity": "1.237",
  "shelf": "string",
  "status": "in_lab",
  "storage_box_number": "box_76399",
  "storage_environment": "LN",
  "storage_room": "room bio-456",
  "storage_temperature": "5c",
  "storage_unit_type": "Refrigerator",
  "storage_unit_type_other": "Vault",
  "treatment_participant_id": "tp_99-45688",
  "treatment_protocol_id": "22-6789",
  "viable_stroma_percent_area": "4.82",
  "viable_tumor_percent_area": "81.2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('/samples/{csms_id}',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.patch('/samples/{csms_id}', headers = headers)

print(r.json())

PATCH /samples/{csms_id}

Update specific data on a previously created sample.

REQUEST BODY

{
  "biological_sex": "Female",
  "biopsy_site": "C50.3",
  "collection_date": "2021-06-02",
  "collection_event_name": "Post-Treatment",
  "collection_time": "16:30 Hawaii-Aleutian",
  "container_type": "Other",
  "date_of_birth": "1970-11-30",
  "sample_collection_procedure": "Other",
  "sample_type": "Other",
  "screening_participant_id": "7bh45z",
  "screening_protocol_id": "MyeloMATCH",
  "a260_or_a230_value": 10,
  "a260_or_a280_value": 10,
  "blast_percentage": "1.2",
  "box_coordinates": "tile 22h",
  "comments": "This is a comment for the sample",
  "container_type_other": "Description of some other tube used.",
  "cores_submitted": "Yes",
  "csms_id": "mm_1234_jrh",
  "custodian_institution_id": "string",
  "description_of_sample": "Tumor",
  "description_of_tumor_sample": "Benign",
  "din_value": 10,
  "directionality": "Lateral",
  "dv200": "51.273",
  "event": "string",
  "fibrosis_percent_area": "21.2",
  "fixation_stabilization_type": "Ficoll",
  "laterality": "Right",
  "locational_tumor_malignancy_class": "Primary",
  "manifest_id": "20220729_jrh_65108327",
  "med_tin": "7.381999",
  "necrosis_percent_area": 100,
  "nitrogen_tank": "nx-tank1",
  "number_cores_submitted": "2",
  "operational_id": "E1000-A",
  "original_sample": "True",
  "parent_csms_id": "mm_1214_jrh",
  "parent_sample_id": "string",
  "percent_viability": "1.2",
  "processed_sample_derivative": "Germline DNA",
  "processed_sample_id": "string",
  "processed_sample_type": "Other",
  "rack_id": "rack_id_2204",
  "reason": "string",
  "replacement_sample_requested": "Replacement Not Requested",
  "rin_value": "0.29",
  "sample_collection_procedure_other": "Description of Other Procedure Used",
  "sample_id": "E1000-A",
  "sample_manifest_type": "interventional",
  "sample_qc_fail_reason": "Container Damaged",
  "sample_qc_fail_reason_other": "Incorrect handling of sample",
  "sample_qc_result": "QC Pass",
  "sample_shipping_condition": "Other",
  "sample_shipping_condition_other": "Describes a shipping condition not available in the predefined list.",
  "sample_type_other": "Some other sample type",
  "sample_uom": "mL",
  "sample_volume_quantity": "1.237",
  "shelf": "string",
  "status": "in_lab",
  "storage_box_number": "box_76399",
  "storage_environment": "LN",
  "storage_room": "room bio-456",
  "storage_temperature": "5c",
  "storage_unit_type": "Refrigerator",
  "storage_unit_type_other": "Vault",
  "treatment_participant_id": "tp_99-45688",
  "treatment_protocol_id": "22-6789",
  "viable_stroma_percent_area": "4.82",
  "viable_tumor_percent_area": "81.2"
}

Parameters

Enumerated Values

200 Response

{
  "message": "Data Received Successfully by CSMS",
  "csms_id": "mm_0536_svu",
  "modified_time": 1650890004
}

Responses

Response Schema

Retrieve Sample

<span class="endpoint">
<span class="method get"> GET </span>
<code>/samples/{csms_id}</code>
</span>

# You can also use wget

curl -X GET /samples/{csms_id} \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/samples/{csms_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/samples/{csms_id}', headers = headers)

print(r.json())

GET /samples/{csms_id}

Retrive the specified sample.

Parameters

200 Response

{
  "data": {
    "biological_sex": "Female",
    "biopsy_site": "C02.9",
    "collection_date": "2022-06-18",
    "collection_event_name": "Progression",
    "container_type": "Saliva Tube",
    "date_of_birth": "1978-04-22",
    "description_of_sample": "Normal",
    "screening_participant_id": "pt_026",
    "screening_protocol_id": "iMATCH",
    "sample_collection_procedure": "Pleural Thoracentesis",
    "sample_type": "FFPE Section",
    "sample_manifest_type": "interventional",
    "sample_id": "mkMYELOMATCH01",
    "operational_id": "mkOperational1",
    "collection_time": "14:00 EDT",
    "sample_shipping_condition": "Frozen Dry Ice",
    "schema_version": "2.2.0",
    "recipient_institution_id": "LBTWST001",
    "sender_institution_id": "BBNCHP001",
    "creator_role": "administrator",
    "parent_sample_id": "mkMYELOMATCH01",
    "original_specimen": "False",
    "custodian_institution_id": "LBTWST001",
    "sample_qc_result": "QC Pass",
    "status": "in_lab",
    "manifest_id": null,
    "blast_percentage": 55.57,
    "viable_tumor_percent_area": 29.37,
    "viable_stroma_percent_area": 25.5,
    "fibrosis_percent_area": 24.017,
    "percent_viability": 23.3,
    "dv200": 15,
    "rin_value": 5,
    "necrosis_percent_area": 24,
    "csms_id": "im_9049_prm",
    "modified_timestamp": "2023-10-17T19:41:00Z",
    "modified_time": 1697571660,
    "submitter": null,
    "event": "update",
    "files_detail": [],
    "comments_detail": []
  },
  "total": 1,
  "limit": 1
}

Responses

Response Schema

Delete Sample

<span class="endpoint">
<span class="method delete"> DELETE </span>
<code>/samples/{csms_id}</code>
</span>

# You can also use wget

curl -X DELETE /samples/{csms_id} \
  -H 'Accept: application/json' \
  -H 'x-delete-reason: Erroneously created'

const headers = {
  'Accept':'application/json',
  'x-delete-reason':'Erroneously created'
};

fetch('/samples/{csms_id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json',
  'x-delete-reason': 'Erroneously created'
}

r = requests.delete('/samples/{csms_id}', headers = headers)

print(r.json())

DELETE /samples/{csms_id}

Delete the specified sample.

Parameters

200 Response

{
  "message": "sample deleted CUYNCNRP5.02"
}

Responses

Response Schema

Retrieve Sample History

<span class="endpoint">
<span class="method get"> GET </span>
<code>/samples/history/{csms_id}</code>
</span>

# You can also use wget

curl -X GET /samples/history/{csms_id} \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/samples/history/{csms_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/samples/history/{csms_id}', headers = headers)

print(r.json())

GET /samples/history/{csms_id}

Retrieve all history for specified sample

Parameters

200 Response

[
  {
    "data": {
      "biological_sex": "Male",
      "biopsy_site": "C50.3",
      "collection_date": "2021-06-02",
      "collection_event_name": "Post-Treatment",
      "collection_time": "15:30 EST",
      "container_type": "Other",
      "container_type_other": "description of some other tube used",
      "cores_submitted": "Yes",
      "date_of_birth": "1970-11-30",
      "description_of_sample": "Tumor",
      "description_of_tumor_sample": "Benign",
      "directionality": "Lateral",
      "fixation_stabilization_type": "Ficoll",
      "laterality": "Right",
      "locational_tumor_malignancy_class": "Primary",
      "number_cores_submitted": "2",
      "operational_id": "E1000-A",
      "parent_sample_id": "E1000-A",
      "processed_sample_derivative": "DNA",
      "processed_sample_id": "string",
      "processed_sample_type": "Other",
      "sample_collection_procedure": "Other",
      "sample_collection_procedure_other": "Description of Other Procedure Used",
      "sample_id": "E1000-A",
      "sample_manifest_type": "interventional",
      "sample_shipping_condition": "Other",
      "sample_shipping_condition_other": "Describes a shipping condition not available in the predefined list.",
      "sample_type": "Other",
      "sample_type_other": "Some other sample type",
      "sample_uom": "mL",
      "sample_volume_quantity": 1.237,
      "screening_participant_id": "7bh45z",
      "screening_protocol_id": "MYELOMATCH",
      "treatment_participant_id": "tp_99-45688",
      "treatment_protocol_id": "22-6789",
      "schema_version": "2.2.0",
      "modified_timestamp": "2023-10-17T18:51:19Z",
      "modified_time": 1697568679,
      "submitter": null,
      "status": "draft",
      "creator_role": "administrator",
      "csms_id": "mm_2947_zua",
      "event": "create",
      "qldb_id": "GjyudEK8YhI4EHFrxXHfhH",
      "qldb_version": 0,
      "qldb_txId": "A2mzwnpgEp4HO8jWIYuYTE",
      "qldb_txTime": "2023-10-17 18:51:19.395000+00:00"
    },
    "diff": {
      "biological_sex": [
        null,
        "Male"
      ],
      "biopsy_site": [
        null,
        "C50.3"
      ],
      "collection_date": [
        null,
        "2021-06-02"
      ],
      "collection_event_name": [
        null,
        "Post-Treatment"
      ],
      "collection_time": [
        null,
        "15:30 EST"
      ],
      "container_type": [
        null,
        "Other"
      ],
      "container_type_other": [
        null,
        "description of some other tube used"
      ],
      "cores_submitted": [
        null,
        "Yes"
      ],
      "date_of_birth": [
        null,
        "1970-11-30"
      ],
      "description_of_sample": [
        null,
        "Tumor"
      ],
      "description_of_tumor_sample": [
        null,
        "Benign"
      ],
      "directionality": [
        null,
        "Lateral"
      ],
      "fixation_stabilization_type": [
        null,
        "Ficoll"
      ],
      "laterality": [
        null,
        "Right"
      ],
      "locational_tumor_malignancy_class": [
        null,
        "Primary"
      ],
      "number_cores_submitted": [
        null,
        "2"
      ],
      "operational_id": [
        null,
        "E1000-A"
      ],
      "parent_sample_id": [
        null,
        "E1000-A"
      ],
      "processed_sample_derivative": [
        null,
        "DNA"
      ],
      "processed_sample_id": [
        null,
        "string"
      ],
      "processed_sample_type": [
        null,
        "Other"
      ],
      "sample_collection_procedure": [
        null,
        "Other"
      ],
      "sample_collection_procedure_other": [
        null,
        "Description of Other Procedure Used"
      ],
      "sample_id": [
        null,
        "E1000-A"
      ],
      "sample_manifest_type": [
        null,
        "interventional"
      ],
      "sample_shipping_condition": [
        null,
        "Other"
      ],
      "sample_shipping_condition_other": [
        null,
        "Describes a shipping condition not available in the predefined list."
      ],
      "sample_type": [
        null,
        "Other"
      ],
      "sample_type_other": [
        null,
        "Some other sample type"
      ],
      "sample_uom": [
        null,
        "mL"
      ],
      "sample_volume_quantity": [
        null,
        1.237
      ],
      "screening_participant_id": [
        null,
        "7bh45z"
      ],
      "screening_protocol_id": [
        null,
        "MYELOMATCH"
      ],
      "treatment_participant_id": [
        null,
        "tp_99-45688"
      ],
      "treatment_protocol_id": [
        null,
        "22-6789"
      ],
      "schema_version": [
        null,
        "2.2.0"
      ],
      "modified_timestamp": [
        null,
        "2023-10-17T18:51:19Z"
      ],
      "modified_time": [
        null,
        1697568679
      ],
      "status": [
        null,
        "draft"
      ],
      "creator_role": [
        null,
        "administrator"
      ],
      "csms_id": [
        null,
        "mm_2947_zua"
      ],
      "event": [
        null,
        "create"
      ],
      "qldb_id": [
        null,
        "GjyudEK8YhI4EHFrxXHfhH"
      ],
      "qldb_version": [
        null,
        0
      ],
      "qldb_txId": [
        null,
        "A2mzwnpgEp4HO8jWIYuYTE"
      ],
      "qldb_txTime": [
        null,
        "2023-10-17 18:51:19.395000+00:00"
      ]
    }
  }
]

Responses

Response Schema

Retrieve Sample Snapshot

<span class="endpoint">
<span class="method get"> GET </span>
<code>/samples/snapshot/{csms_id}/{modified_time}</code>
</span>

# You can also use wget

curl -X GET /samples/snapshot/{csms_id}/{modified_time} \
  -H 'Accept: application/json'

const headers = {
  'Accept':'application/json'
};

fetch('/samples/snapshot/{csms_id}/{modified_time}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/samples/snapshot/{csms_id}/{modified_time}', headers = headers)

print(r.json())

GET /samples/snapshot/{csms_id}/{modified_time}

Retrieve a snapshot for the specified sample.