Register Samples via API

Using the BioSamples API you can submit new samples to our resource, as well as update or curate samples.

This website requires the limited processing of your personal data in order to function. By using the site you are agreeing to this as outlined in our Submission Privacy Notice.

Submission minimal fields

Sample

Sample submission fields
Field	Description	Type	Cardinality
name	The short name of the sample.	String	Required
release	The date on which the sample was first made public.	Date ISO 8601	Required
update	The date on which the sample was last updated.	Date ISO 8601	System Generated
accession	The sample unique identifier in the BioSamples database; assigned automatically if omitted.	String	Required for PUT requests
characteristics	The key-value pairs representing the attributes of the sample.	Object	Optional
externalReferences	A list of links to external references (e.g., datasets in other archives).	Array	Optional
relationships	A list of relationships this sample has to other, existing, samples.	Array	Optional
data	A structured format (e.g., antibiogram) alongside key-value pairs.	Array	Optional (required only for structured-data submission)

Structure of characteristics elements
Field	Type	Cardinality
text	String	Recommended
ontologyTerms	Array	Optional
unit	String	Optional

Curation Link

Curation link fields
Field	Type	Cardinality
sample	String	Required
curation	Object	Required
curation.attributesPre	Array	Required (could be empty)
curation.attributesPost	Array	Required (could be empty)
curation.externalReferencesPre	Array	Required (could be empty)
curation.externalReferencesPost	Array	Required (could be empty)

Submit a sample

POST a sample to BioSamples.

Request

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

{
  "name" : "FakeSample",
  "release" : "2025-07-30T08:54:07.592313138Z",
  "webinSubmissionAccountId" : "Webin-12345"
}

Response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://www.ebi.ac.uk/biosamples/samples
Content-Type: application/hal+json
Content-Length: 1001

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

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

Submit structured data

PUT structured data associated with a sample (e.g., antibiogram data).

Request

PUT /biosamples/structureddata/SAMFAKE123456 HTTP/1.1
Content-Type: application/json
Authorization: Bearer $TOKEN
Content-Length: 1825
Host: www.ebi.ac.uk

{
  "accession": "SAMFAKE123456",
  "create": "2025-07-30T08:54:07.421677129Z",
  "update": "2025-07-30T08:54:07.421717217Z",
  "data": [
    {
      "domain": "self.ExampleDomain",
      "webinSubmissionAccountId": null,
      "type": "AMR",
      "schema": null,
      "content": [
        {
          "resistancePhenotype": {"value": "intermediate", "iri": null},
          "astStandard": {"value": "CLSI", "iri": null},
          "laboratoryTypingMethod": {"value": "disk diffusion", "iri": null},
          "laboratoryTypingMethodVersionOrReagent": {"value": "missing", "iri": null},
          "vendor": {"value": "Becton Dickinson", "iri": null},
          "measurementSign ": {"value": "==", "iri": null},
          "antibioticName": {"value": "nalidixic acid", "iri": "http://purl.obolibrary.org/obo/value_1"},
          "measurementUnits": {"value": "mm", "iri": null},
          "measurement": {"value": "17", "iri": null},
          "platform": {"value": "missing", "iri": null}
        }
      ]
    },
    {
      "domain": "self.ExampleDomain",
      "webinSubmissionAccountId": null,
      "type": "CHICKEN_DATA",
      "schema": null,
      "content": [
        {
          "Measurement": {"value": "value_1", "iri": null},
          "Marker": {"value": "value_1", "iri": "http://purl.obolibrary.org/obo/value_1"},
          "Method": {"value": "value_1", "iri": null},
          "Measurement Units": {"value": "value_1", "iri": null},
          "Partner": {"value": "value_1", "iri": null}
        }
      ]
    }
  ]
}

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: 1825

{
  "accession": "SAMFAKE123456",
  "create": "2025-07-30T08:54:07.421677129Z",
  "update": "2025-07-30T08:54:07.421717217Z",
  "data": [
    {
      "domain": "self.ExampleDomain",
      "webinSubmissionAccountId": null,
      "type": "AMR",
      "schema": null,
      "content": [
        {
          "resistancePhenotype": {"value": "intermediate", "iri": null},
          "astStandard": {"value": "CLSI", "iri": null},
          "laboratoryTypingMethod": {"value": "disk diffusion", "iri": null},
          "laboratoryTypingMethodVersionOrReagent": {"value": "missing", "iri": null},
          "vendor": {"value": "Becton Dickinson", "iri": null},
          "measurementSign ": {"value": "==", "iri": null},
          "antibioticName": {"value": "nalidixic acid", "iri": "http://purl.obolibrary.org/obo/value_1"},
          "measurementUnits": {"value": "mm", "iri": null},
          "measurement": {"value": "17", "iri": null},
          "platform": {"value": "missing", "iri": null}
        }
      ]
    },
    {
      "domain": "self.ExampleDomain",
      "webinSubmissionAccountId": null,
      "type": "CHICKEN_DATA",
      "schema": null,
      "content": [
        {
          "Measurement": {"value": "value_1", "iri": null},
          "Marker": {"value": "value_1", "iri": "http://purl.obolibrary.org/obo/value_1"},
          "Method": {"value": "value_1", "iri": null},
          "Measurement Units": {"value": "value_1", "iri": null},
          "Partner": {"value": "value_1", "iri": null}
        }
      ]
    }
  ]
}

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

Submit curation object

POST a curation object to BioSamples.

Request

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

{
  "sample": "SAMEA12345",
  "curation": {
    "attributesPre": [
      {"type": "Organism", "value": "Human", "iri": ["9606"]}
    ],
    "attributesPost": [
      {"type": "Organism", "value": "Homo sapiens", "iri": ["http://purl.obolibrary.org/obo/NCBITaxon_9606"]}
    ],
    "externalReferencesPre": [
      {"url": "www.google.com", "duo": []}
    ],
    "externalReferencesPost": [
      {"url": "www.ebi.ac.uk/ena/ERA123456", "duo": []}
    ],
    "relationshipsPre": [],
    "relationshipsPost": [
      {"source": "SAMFAKE123456", "type": "DERIVED_FROM", "target": "SAMFAKE7654321"}
    ],
    "externalPre": [
      {"url": "www.google.com", "duo": []}
    ],
    "externalPost": [
      {"url": "www.ebi.ac.uk/ena/ERA123456", "duo": []}
    ],
    "hash": "09a5a9cddbea9f5bb6302b86b922c408abc92b8b10c78f0662ac7e41fd44e91f"
  },
  "domain": null,
  "webinSubmissionAccountId": "Webin-12345",
  "created": "2025-07-30T08:54:05.338606736Z",
  "hash": "d1f611ec2c8caf3d9f58fa40227ea60ebb5fc00eda06338fb81db7d987a6fa63"
}

Response

HTTP/1.1 201 Created
Location: https://www.ebi.ac.uk/biosamples/samples/SAMEA12345/curationlinks/d1f611ec2c8caf3d9f58fa40227ea60ebb5fc00eda06338fb81db7d987a6fa63
Content-Type: application/hal+json
Content-Length: 1397

{
  "sample": "SAMEA12345",
  "curation": {
    "attributesPre": [{"type": "Organism", "value": "Human", "iri": ["9606"]}],
    "attributesPost": [{"type": "Organism", "value": "Homo sapiens", "iri": ["http://purl.obolibrary.org/obo/NCBITaxon_9606"]}],
    "externalReferencesPre": [{"url": "www.google.com", "duo": []}],
    "externalReferencesPost": [{"url": "www.ebi.ac.uk/ena/ERA123456", "duo": []}],
    "relationshipsPre": [],
    "relationshipsPost": [{"source": "SAMFAKE123456", "type": "DERIVED_FROM", "target": "SAMFAKE7654321"}],
    "hash": "09a5a9cddbea9f5bb6302b86b922c408abc92b8b10c78f0662ac7e41fd44e91f"]
  },
  "domain": null,
  "webinSubmissionAccountId": "Webin-12345",
  "created": "2025-07-30T08:54:05.338606736Z",
  "hash": "d1f611ec2c8caf3d9f58fa40227ea60ebb5fc00eda06338fb81db7d987a6fa63",
  "_links": {
    "self": {
      "href": "https://www.ebi.ac.uk/biosamples/samples/SAMEA12345/curationlinks/d1f611ec2c8caf3d9f58fa40227ea60ebb5fc00eda06338f0662ac7e41fd44e91f"
    },
    "sample": {
      "href": "https://www.ebi.ac.uk/biosamples/samples/SAMEA12345"
    },
    "curation": {
      "href": "https://www.ebi.ac.uk/biosamples/curations/09a5a9cddbea9f5bb6302b86b922c408abc92b8b10c78f0662ac7e41fd44e91f"
    }
  }
}

Links

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

Accession a sample

POST a sample for accessioning. Accessioned sample is saved as a private sample.

Request

POST /biosamples/samples/accession HTTP/1.1
Content-Type: application/json
Authorization: Bearer $TOKEN
Content-Length: 74
Host: www.ebi.ac.uk

{
  "name": "FakeSample",
  "update": "2025-07-30T08:54:06.535179734Z"
}

Response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://www.ebi.ac.uk/biosamples/samples/SAMEA12345
Content-Type: application/json
Content-Length: 988

{
  "name": "FakeSample",
  "accession": "SAMEA12345",
  "webinSubmissionAccountId": "Webin-12345",
  "status": "PUBLIC",
  "release": "2125-07-30T08:54:06Z",
  "update": "2025-07-30T08:54:06.535179734Z",
  "submitted": "2025-07-30T08:54:06.535179818Z",
  "characteristics": {},
  "submittedVia": "JSON_API",
  "create": "2025-07-30T08:54:06.535179780Z",
  "_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**.

Validate sample fields

POST a sample to validate its basic fields before submission.

Request

POST /biosamples/validate HTTP/1.1
Content-Type: application/json
Authorization: Bearer $TOKEN
Content-Length: 440
Host: www.ebi.ac.uk

{
  "name": "fake_sample",
  "update": "2025-07-30T08:54:06.361023322Z",
  "release": "2025-07-30T08:54:06.361023223Z",
  "domain": "self.ExampleDomain",
  "characteristics": {
    "material": [{
      "text": "cell line",
      "ontologyTerms": ["EFO_0000322"]
    }],
    "Organism": [{
      "text": "Homo sapiens",
      "ontologyTerms": ["9606"]
    }],
    "checklist": [{
      "text": "BSDC00001"
    }]
  }
}

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: 559

{
  "name": "fake_sample",
  "domain": "self.ExampleDomain",
  "taxId": 9606,
  "status": "PUBLIC",
  "release": "2025-07-30T08:54:06.361023223Z",
  "update": "2025-07-30T08:54:06.361023322Z",
  "characteristics": {
    "Organism": [{
      "text": "Homo sapiens",
      "ontologyTerms": ["9606"]
    }],
    "checklist": [{
      "text": "BSDC00001"
    }],
    "material": [{
      "text": "cell line",
      "ontologyTerms": ["EFO_0000322"]
    }]
  },
  "submittedVia": "JSON_API",
  "create": "2025-07-30T08:54:06.361023322Z"
}

POST sample with external references

POST a sample with external references.

Request

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

{
  "name": "FakeSample",
  "release": "2025-07-30T08:54:06.198269289Z",
  "webinSubmissionAccountId": "Webin-12345",
  "externalReferences": [{
    "url": "https://www.ebi.ac.uk/ena/data/view/SAMEA00001"
  }]
}

Response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://www.ebi.ac.uk/biosamples/samples
Content-Type: application/hal+json
Content-Length: 1090

{
  "name": "FakeSample",
  "accession": "SAMEA12345",
  "webinSubmissionAccountId": "Webin-12345",
  "status": "PUBLIC",
  "release": "2025-07-30T08:54:06.198269289Z",
  "update": "2025-07-30T08:54:06.198269371Z",
  "submitted": "2025-07-30T08:54:06.198269453Z",
  "characteristics": {},
  "externalReferences": [{
    "url": "https://www.ebi.ac.uk/ena/data/view/SAMEA00001",
    "duo": []
  }],
  "submittedVia": "JSON_API",
  "create": "2025-07-30T08:54:06.198269412Z",
  "_links": {
    "self": {"href": "https://www.ebi.ac.uk/biosamples/samples"},
    "applyCurations": {"href": "https://www.ebi.ac.uk/biosamples/samples{?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"}
  }
}

PUT sample with relationships

PUT a sample with relationships.

Request

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

{
  "name": "FakeSample",
  "accession": "SAMEA123456",
  "webinSubmissionAccountId": "Webin-12345",
  "status": "PUBLIC",
  "release": "2025-07-30T08:54:06.713767735Z",
  "update": "2025-07-30T08:54:06.713767809Z",
  "submitted": "2025-07-30T08:54:06.713767894Z",
  "characteristics": {},
  "relationships": [
    {
      "source": "SAMFAKE123456",
      "type": "derived from",
      "target": "SAMFAKE654321"
    }
  ],
  "submittedVia": "JSON_API",
  "create": "2025-07-30T08:54:06.713767854Z"
}

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: 1121

{
  "name": "FakeSample",
  "accession": "SAMEA12345",
  "webinSubmissionAccountId": "Webin-12345",
  "status": "PUBLIC",
  "release": "2025-07-30T08:54:06.713767735Z",
  "update": "2025-07-30T08:54:06.713767809Z",
  "submitted": "2025-07-30T08:54:06.713767894Z",
  "characteristics": {},
  "relationships": [
    {
      "source": "SAMFAKE123456",
      "type": "derived from",
      "target": "SAMFAKE654321"
    }
  ],
  "submittedVia": "JSON_API",
  "create": "2025-07-30T08:54:06.713767854Z",
  "_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**.