Bulk sample registration
========================
How to programmatically submit samples in bulk
----------------------------------------------

The bulk-submit-get-receipt API endpoint allows submitters to send multiple sample metadata records together
(in one bulk operation) and then retrieve a “receipt” that reports the outcome (success/failure) and any
assigned accessions.
In the context of BioSamples this supports high-volume submissions rather than individual sample POSTs.


Example curl commands
---------------------
This is an example of a curl command request and reponse to the bulk-submit-get-receipt API endpoint.

.. code-block:: console

    curl 'https://wwwdev.ebi.ac.uk/biosamples/v2/samples/bulk-submit-get-receipt' \
        -i -X POST
        -H "Content-Type: application/json;charset=UTF-8"
        -H "Accept: application/hal+json"
        -H "Authorization: Bearer $TOKEN"
        -d '[{
            "name" : "FakeSample1",
            "update" : "2012-03-19T13:56:40.720567Z",
            "release" : "2020-03-10T13:56:40.720559Z",
            "webinSubmissionAccountId" : "Webin-59287",
            "characteristics" : {
            "description" : [ {
                "text" : "fake sample"
            } ],
            "organism" : [ {
                "text" : "Homo sapiens",
                "ontologyTerms" : [ "http://purl.obolibrary.org/obo/NCBITaxon_9606" ]
            } ]
          }
        }]


.. code-block:: json

    {
        "samples": [
            {
                "name": "FakeSample1",
                "accession": "SAMEA131847325",
                "sraAccession": "ERS32039383",
                "webinSubmissionAccountId": "Webin-59287",
                "taxId": 9606,
                "status": "PUBLIC",
                "release": "2020-03-10T13:56:40.720559Z",
                "update": "2025-11-14T12:12:30.396351204Z",
                "submitted": "2025-11-14T12:12:30.396350160Z",
                "characteristics": {
                    "SRA accession": [
                        {
                            "text": "ERS32039383"
                        }
                    ],
                    "description": [
                        {
                            "text": "fake sample"
                        }
                    ],
                    "organism": [
                        {
                            "text": "Homo sapiens",
                            "ontologyTerms": [
                                "http://purl.obolibrary.org/obo/NCBITaxon_9606"
                            ]
                        }
                    ]
                },
                "submittedVia": "JSON_API",
                "create": "2025-11-14T12:12:30.396348732Z"
            }
        ],
        "errors": []
    }





Important details & caveats
---------------------------

- **Relationships between samples:** If your context involves derivation (e.g., same donor, multiple timepoints, replicates, derived_from relationships), you may need to include relationship attributes (e.g., derived_from, same_as). The API reference shows sample metadata supports relationships.

- **Release date / privacy:** In the sample metadata you must specify a release date. If you need samples to remain private until associated data (e.g., sequence reads) are published, pick appropriate dates.

- **Metadata consistency for search/discovery:** The bulk-submit receipt only ensures technical submission succeeds; you should still review your metadata for FAIR discoverability.