How to Interactively Update Existing Samples

After registering your samples with your tsv file, the uploader will send back a file for download. This file will depend on the size of your sample registration.

• If your tsv file of samples is less than 20 KBytes and the file has less than 200 samples, the result file will be a tsv (example here) that looks similar to the original file, with sample metadata and the sample accessions.

  1. Take the result tsv file that you have just received which contains sample metadata and the Sample Identifier column

  2. Remove the receipt section (the bottom few rows)

  3. Make any metadata changes to this file

  4. Re-submit this update tsv submission file to the File Upload Service

  5. This will update the sample in BioSamples

• If your tsv file of samples is greater than 20 KBytes or the file has more than 200 samples, the result file will be a tsv that only has a unique submission ID for the upload. On the ‘View Submissions’ tab, you will be able to find your submission with the unique submission ID, and download a JSON file which shows the mapping between sampleName and sampleAccession.

  1. Take the original tsv file of samples and make metadata changes within that file.

  2. Add the Sample Identifier column to the tsv submission file, filling it in with the appropriate sample accessions. You can find these sample accessions in the JSON file in the ‘View Submissions’ tab (see example here).

  3. Submit this update tsv submission file to the File Upload Service.

  4. This will update the sample in BioSamples

How to Programmatically Update a Sample

PUT a sample to BioSamples. The submitted sample must include an accession matching the URL. Updating a sample overwrites its existing content. To preserve existing attributes, download the current sample, add additional attributes, and resubmit.

Request

PUT /biosamples/samples/SAMEA12345 HTTP/1.1
Content-Type: application/json
Authorization: Bearer $TOKEN
Content-Length: 376
Host: www.ebi.ac.uk

{
  "name": "FakeSample",
  "accession": "SAMEA12345",
  "webinSubmissionAccountId": "Webin-12345",
  "status": "PUBLIC",
  "release": "2025-07-30T08:54:04.025031918Z",
  "update": "2025-07-30T08:54:04.025032058Z",
  "submitted": "2025-07-30T08:54:04.025032140Z",
  "characteristics": {},
  "submittedVia": "JSON_API",
  "create": "2025-07-30T08:54:04.025032099Z"
}

Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Content-Length: 998

{
  "name": "FakeSample",
  "accession": "SAMEA12345",
  "webinSubmissionAccountId": "Webin-12345",
  "status": "PUBLIC",
  "release": "2025-07-30T08:54:04.025031918Z",
  "update": "2025-07-30T08:54:04.025032058Z",
  "submitted": "2025-07-30T08:54:04.025032140Z",
  "characteristics": {},
  "submittedVia": "JSON_API",
  "create": "2025-07-30T08:54:04.025032099Z",
  "_links": {
    "self": {"href": "https://www.ebi.ac.uk/biosamples/samples/SAMEA12345"},
    "applyCurations": {
      "href": "https://www.ebi.ac.uk/biosamples/samples/SAMEA12345{?applyCurations}",
      "templated": true
    },
    "curationLinks": {"href": "https://www.ebi.ac.uk/biosamples/samples/SAMEA12345/curationlinks"},
    "curationLink": {
      "href": "https://www.ebi.ac.uk/biosamples/samples/SAMEA12345/curationlinks/{hash}",
      "templated": true
    },
    "structuredData": {"href": "https://www.ebi.ac.uk/biosamples/structureddata/SAMEA12345"}
  }
}

Links

For all the links available in BioSamples responses, refer to the Links Reference.