{"openapi":"3.0.3","info":{"title":"Upload Genomic Data","description":"## Overview\n\nUse this API to securely upload patient genomic data for downstream processing by [NHS Genomic Medicine Service (GMS)](https://www.england.nhs.uk/genomics/nhs-genomic-med-service/) applications.\n\nThis page describes the technical details of the Upload Genomic Data (UGD) service, including available endpoints. For a high-level overview of the service, see the [Upload Genomic Data service page](https://digital.nhs.uk/services/genomic-data/upload-genomic-data-service?key=3gjQjuQhN7E1nzAcGRZ1Jt5dpSHGrQ3Gye0D7vH82OM0Ov97BWwRvpY7PTbCBkx6).\n\n## Who can use this API\n\nThis API can only be used by staff associated with [Genomic Laboratory Hubs (GLHs)](https://www.england.nhs.uk/genomics/genomic-laboratory-hubs/) operating as part of the NHS Genomic Medicine Service (GMS) where there is a legal basis to do so.\n\n## How to use this API\n\nUploading genomic data occurs in six stages:\n\n1. Verify that genomic sequence data is expected.\n2. Make an upload request.\n3. Upload the data.\n4. Register the data.\n5. Provide associated metadata.\n6. Update the ServiceRequest to reference uploaded specimens.\n\n---\n\n### Stage 1: Verify that genomic sequence data is expected\n\nBefore uploading any genomic sequence data, consumers must confirm that Genomics England (GEL) is expecting data for the referral.\n\nConsumers should issue a `GET` request to the `/fhir/r4/ServiceRequest` endpoint to locate a `ServiceRequest` that matches the National Genomic Informatics System (NGIS) `referral_id`. The matching `ServiceRequest` must reference the relevant NGIS `participant_id` in either:\n\n- `ServiceRequest.subject` — representing the proband, or \n- `ServiceRequest.supportingInfo` — representing family members associated with the referral\n\nRecommendation: Consumers should also check for existing `DocumentReference` and `Specimen` (type: `wgs-data`) resources. If data for the sample has already been registered, consumers should abort unless performing a deliberate re-upload of data.\n\n[Try Search for ServiceRequest endpoint](#get-/fhir/r4/ServiceRequest)\n\n---\n\n### Stage 2: Make an upload request\n\nSend a `POST` request to the `/gel/drsupload/v1/upload-request` endpoint with metadata describing the files to be uploaded.\n\nThe response will include upload locations and the credentials required to upload the data.\n\n#### Upload session lifetime\n\nFor a given upload request, consumers have up to 1 hour from the time upload locations and credentials are issued to successfully upload all files in that batch to the locations provided.\n\nIf all files in the batch are not successfully uploaded within this time window, the upload request expires and the batch must be retried by starting a new upload request.\n\n[Try Upload Request endpoint](#post-/gel/drsupload/v1/upload-request)\n\n---\n\n### Stage 3: Upload the data\n\nUpload each file using the locations and temporary credentials returned in Stage 2.\n\nFor each file in the Stage 2 response:\n\n1. Parse the access URL from `upload_methods[0].access_url.url` to extract the location of where the data should be uploaded.\n2. Extract the temporary credentials from `upload_methods[0].credentials`.\n3. Upload the file.\n\n**Example using AWS SDK (Python boto3):**\n\nThe current UGD implementation uses [AWS S3](https://aws.amazon.com/s3/) for data storage.\n\nSee the [worked example](#worked-example-rare-disease-single-lane-upload) below for further information.\n\nNote: No API authentication token is required for Stage 3 — the temporary S3 credentials are sufficient. These credentials are scoped to the specific upload and expire after a limited time. For very large files (tens of GB), plan for uploads that may take longer than the APIM token lifetime; the token will be refreshed automatically when needed for Stage 4.\n\n#### Handling upload failures\n\nIf an upload to the storage location (for example S3) fails or times out for a file, consumers must abandon the upload protocol for that file at Stage 3.\n\nIn this scenario, consumers must restart the upload process from Stage 1 for the affected sample and obtain new upload locations and credentials.\n\n- Partially uploaded or failed files must not be reused or registered.\n\n---\n\n### Stage 4: Register the data\n\nAfter uploading the data, send a `POST` request to the `/gel/drsupload/v1/register-objects` endpoint with candidate DRS objects.\n\nEach candidate must include `access_methods` containing the S3 `access_url` from the Stage 2 response. This tells DRS where the uploaded file is stored.\n\n#### Registration batch size limits\n\nThe `register-objects` operation accepts up to 20 candidate DRS objects per request.\n\nIf more than 20 uploaded files need to be registered, consumers must split registration across multiple Stage 4 requests, each containing no more than 20 candidate objects.\n\nThis limit applies only to the registration step and does not restrict the number of files uploaded in Stages 2 and 3.\n\n```json\n{\n\"candidates\": [\n {\n \"name\": \"sample1_S1_L001_R1_001.fastq.gz\",\n \"size\": 31457280,\n \"mime_type\": \"text/fastq\",\n \"checksums\": [\n { \"checksum\": \"a1b2c3d4e5f6...\", \"type\": \"sha-256\" }\n ],\n \"access_methods\": [\n {\n \"type\": \"s3\",\n \"access_url\": {\n \"url\": \"s3://gel-bucket/uploads/sample1_S1_L001_R1_001.fastq.gz\"\n }\n }\n ]\n }\n]\n}\n\n```\n\nA successful registration returns HTTP 201.\n\n[Try Register Objects endpoint](#post-/gel/drsupload/v1/register-objects)\n\n---\n\n### Stage 5: Provide associated metadata\n\nSend a `POST` request to the `/fhir/r4` endpoint containing a [FHIR transaction Bundle](https://build.fhir.org/bundle.html) that describes the uploaded files and their clinical context.\n\nFHIR (Fast Healthcare Interoperability Resources) metadata allows uploaded genomic data to be discovered and used by other NHS Genomic Medicine Service (GMS) applications.\n\nThe transaction Bundle must contain the following resources:\n\n1. Child Specimen (type: wgs-data, sample category: e.g. germline, gel1001 sample state: e.g. blood_unsorted_edta) - references parent Specimen and ServiceRequest.\n2. Parent Specimen (type: lab-sample) - identified by 2D barcode tube identifier, and optionally, a local lab sample ID.\n3. Procedures - one or more sequencing runs for which the sample was sequenced on, linked to referral via `basedOn`. Each `Procedure` represents a distinct run (e.g., Run ID) the Specimen was sequenced on.\n4. DocumentReference (Read1) - FASTQ file, links to Read2 via relatesTo \"appends\".\n5. DocumentReference (Read2) - FASTQ file, links to Read1 via relatesTo \"transforms\".\n6. Composition - the subject being the `wgs-data` Specimen, author being the ODS code of the Sequencing Genomic Laboratories (SGLs), with a section titled \"files\" listing all DocumentReferences for the Specimen\n\nLinking Requirement: Each `DocumentReference` MUST reference the specific `Procedure` resource that corresponds to its sequencing run . All internal cross-references use `urn:uuid:` format.\n\nFor multi-lane samples, an additional DocumentReference pair is added per lane. All internal cross-references use `urn:uuid:` format.\n\n#### DRS object identifiers used in DocumentReference\n\nEach DocumentReference in the transaction Bundle must reference the DRS object created during Stage 4 (registration).\n\nClients must not use the temporary object identifiers returned from Stage 2 (`upload-request`) in DocumentReference content blocks.\n\n#### Specimen extensions\n\nThe `wgs-data` child Specimen must be the first entry in the transaction Bundle, as its server-assigned ID (returned in the response) is needed for Stage 6.\n\nThe UK Core Sample Category extension (Extension-UKCore-SampleCategory) must be present on all Specimen resources in the transaction Bundle, including both the `wgs-data` child Specimen and the parent `lab-sample` Specimen.\n\nThe GEL primary sample state extension (gel1001-primary-sample-state) must be present on the `wgs-data` child Specimen and must not be supplied on the parent lab-sample Specimen.\n\nFor details of the values that can go into the \"gel1001-primary-sample-state\" of the `wgs-data` child Specimen please refer to the \"NGIS Sample Specification\" in the [NHS Futures platform](https://future.nhs.uk/NHSgenomics/view?objectId=83469925). Specifically, see Column name \"primary_sample_state\" in the \"GEL1001 - fields\" tab.\n\nAll intra-Bundle cross-references use `urn:uuid:` format. References to existing resources (e.g. the ServiceRequest found in Stage 1) use the standard `ResourceType/{id}` format.\n\nExtracting the Specimen ID from the response: The response is a transaction-response Bundle. Each entry has a `response.location` header in the format `ResourceType/{id}/_history/{version}`. Extract the `{id}` from the first Specimen entry — this is the wgs-data child Specimen (because the Bundle places it first). This ID is what you need for Stage 6.\n\nExample response (abridged):\n\n```json\n{\n\"resourceType\": \"Bundle\",\n\"type\": \"transaction-response\",\n\"entry\": [\n {\n \"response\": {\n \"status\": \"201 Created\",\n \"location\": \"Specimen/aabbccdd-1122-3344-5566-778899aabbcc/_history/1\"\n }\n },\n {\n \"response\": {\n \"status\": \"201 Created\",\n \"location\": \"Specimen/eeff0011-2233-4455-6677-8899aabbccdd/_history/1\"\n }\n },\n ...\n]\n}\n\n```\n\nThe first Specimen (`aabbccdd-1122-3344-5566-778899aabbcc`) is the wgs-data child. Record its ID for Stage 6.\n\n---\n\n### Stage 6: Update the ServiceRequest to reference uploaded specimens\n\nAfter all files have been successfully uploaded and registered, consumers must update the originating `ServiceRequest` to reference the uploaded wgs-data Specimen(s).\n\nSend a `PATCH` request to the `/fhir/r4/ServiceRequest/{id}` endpoint using the ServiceRequest ID from Stage 1. The request must use Content-Type `application/json-patch+json` (JSON Patch format per RFC 6902).\n\nOnly reference the wgs-data child Specimen (not the lab-sample parent). This is the reference that triggers downstream bioinformatics pipelines.\n\nThe JSON Patch body depends on whether the ServiceRequest already has a `specimen` array (check the response from Stage 1):\n\nIf the ServiceRequest already has a `specimen` array (for example, if a prior upload for the same referral has completed):\n\n```json\n[\n{\n \"op\": \"add\",\n \"path\": \"/specimen/-\",\n \"value\": { \"reference\": \"Specimen/{wgs_data_specimen_id}\" }\n}\n]\n\n```\n\nIf the ServiceRequest has no `specimen` array (first upload for this referral):\n\n```json\n[\n{\n \"op\": \"add\",\n \"path\": \"/specimen\",\n \"value\": [{ \"reference\": \"Specimen/{wgs_data_specimen_id}\" }]\n}\n]\n\n```\n\nOnce all expected specimens have been referenced, downstream processing of the genomic sequence data is automatically triggered by the GEL WGS bioinformatics pipelines.\n\n[Try Update a FHIR ServiceRequest endpoint](#patch-/fhir/r4/ServiceRequest/-id-).\n\n### Data flow between stages\n\nEach stage produces outputs that subsequent stages depend on. Understanding this flow is essential.\n\n#### Stage 1: GET /fhir/r4/ServiceRequest\n\n- service_request_id (FHIR resource ID, used in Stages 5 and 6)\n- confirm participant is on the referral\n\n#### Stage 2: POST /gel/drsupload/v1/upload-request\n\n- returns temporary object identifiers and upload locations\n- these identifiers must be used only to upload data and complete Stage 4\n- they must not be referenced in FHIR metadata\n- per file: upload_methods.access_url (URL, used in Stages 3 and 4)\n- per file: upload_methods.credentials (temporary creds, used in Stage 3)\n\n#### Stage 3: Upload files using credentials from Stage 2\n\n- no UGD API call - direct to storage location specified e.g S3 bucket\n\n#### Stage 4: POST /gel/drsupload/v1/register-objects\n\n- registers uploaded files as persistent GA4GH DRS objects\n- accepts up to 20 candidate objects per request\n- larger uploads must be registered across multiple requests\n- returns persistent GA4GH DRS object identifiers\n- these identifiers must be used in Stage 5 DocumentReference content blocks\n- requires: file metadata + access_methods (access_url from Stage 2)\n\n#### Stage 5: POST /fhir/r4 (FHIR transaction Bundle)\n\n- Requires: service_request_id (Stage 1), persistent DRS object URIs from Stage 4, plus metadata (see worked example below)\n- Returns: Specimen IDs (extracted from response Bundle entry locations)\n\n#### Stage 6: PATCH /fhir/r4/ServiceRequest/{id}\n\n- requires: service_request_id (Stage 1), wgs-data Specimen ID (Stage 5)\n- triggers downstream bioinformatics pipelines\n\n### File requirements\n\nFor each file to be uploaded, consumers must provide:\n\n- the file size in bytes\n- a SHA‑256 checksum of the file contents, hex‑encoded using lowercase characters\n\n#### Recommended approaches\n\nClients should calculate file sizes and checksums directly from the final file artefact that will be uploaded.\n\nCommon approaches include:\n\n- using operating system utilities or standard libraries to obtain the file size in bytes\n- using a cryptographic hash function from a well‑tested standard library to generate a SHA‑256 checksum\n\nChecksums should be computed before requesting upload locations (Stage 2) and must not be recalculated against a modified or recompressed file.\n\nMIME types: Use the following MIME types based on file extension:\n\n| File extension | MIME type |\n| ------------------------------ | -------------------------- |\n| `.fastq.gz`, `.fq.gz` | `text/fastq` |\n| `.ora` (DRAGEN ORA-compressed) | `application/octet-stream` |\n\n### Performance and connectivity considerations\n\nSequencing Genomic Laboratories (SGLs) are expected to have a dedicated high‑throughput network connection (for example, a 10 Gbps upload link).\n\nClients should validate their implementations using realistically sized datasets and batch sizes to ensure uploads can reliably complete within the upload session lifetime.\n\n### Worked example: rare disease single-lane upload\n\nThis example walks through a complete upload of a single-lane paired-end FASTQ dataset for a rare disease referral. It shows every HTTP request and response across all six stages.\n\n#### Scenario\n\n- referral ID: `r123456789`\n- participant ID: `p123456789`\n- ODS code for requesting lab: `69A70`\n- ODS code for sequencing lab: `69A50`\n- sequencing run ID: `251230_A00123_0001_3F159011F8`\n- lab sample ID (2D barcode identifier): `123456789` and local lab sample ID (e.g. from local LIMS): `LIMS-123456`\n- lane: 1\n- files:\n - `sample1_S1_L001_R1_001.fastq.gz` (31,457,280 bytes, SHA-256: `a3f1b7c9d2e4f6a8b0c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5`)\n - `sample1_S1_L001_R2_001.fastq.gz` (32,505,856 bytes, SHA-256: `b4e2c8d3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9`)\n\n#### Stage 1: Verify the referral\n\n**Request:**\n\n```shell\nGET /fhir/r4/ServiceRequest?identifier=r123456789&category=https://fhir.hl7.org.uk/CodeSystem/UKCore-GenomeSequencingCategory|rare-disease-wgs\nAccept: application/fhir+json\nAuthorization: Bearer {access_token}\n# or \napikey: {api_key}\n```\n\n**Response (200 OK):**\n\n```json\n{\n\"resourceType\": \"Bundle\",\n\"type\": \"searchset\",\n\"total\": 1,\n\"entry\": [\n {\n \"resource\": {\n \"resourceType\": \"ServiceRequest\",\n \"id\": \"239218e7-1926-4272-a019-5410baf4c2e0\",\n \"status\": \"active\",\n \"intent\": \"order\",\n \"identifier\": [\n {\n \"system\": \"https://genomicsengland.co.uk/healthcare/referral-id\",\n \"value\": \"r123456789\"\n }\n ],\n \"category\": [\n {\n \"coding\": [\n {\n \"system\": \"https://fhir.hl7.org.uk/CodeSystem/UKCore-GenomeSequencingCategory\",\n \"code\": \"rare-disease-wgs\"\n }\n ]\n }\n ],\n \"subject\": {\n \"type\": \"Patient\",\n \"identifier\": {\n \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n \"value\": \"p123456789\"\n }\n }\n }\n }\n]\n}\n\n```\n\n**What to record:**\n- `service_request_id` = `239218e7-1926-4272-a019-5410baf4c2e0`\n- participant `p123456789` confirmed in `subject` (proband)\n- no existing `specimen` array on this ServiceRequest (first upload — affects Stage 6 patch format)\n\n#### Stage 2: Request upload locations\n\n**Request:**\n\n```bash\nPOST /gel/drsupload/v1/upload-request\nContent-Type: application/json\nAuthorization: Bearer {access_token}\n# or \napikey: {api_key}\n```\n\n**Body:**\n\n```json\n{\n\"objects\": [\n {\n \"name\": \"sample1_S1_L001_R1_001.fastq.gz\",\n \"size\": 31457280,\n \"mime_type\": \"text/fastq\",\n \"checksums\": [\n {\n \"checksum\": \"a3f1b7c9d2e4f6a8b0c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5\",\n \"type\": \"sha-256\"\n }\n ]\n },\n {\n \"name\": \"sample1_S1_L001_R2_001.fastq.gz\",\n \"size\": 32505856,\n \"mime_type\": \"text/fastq\",\n \"checksums\": [\n {\n \"checksum\": \"b4e2c8d3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9\",\n \"type\": \"sha-256\"\n }\n ]\n }\n]\n}\n\n```\n\n**Response (200 OK):**\n\n```json\n{\n\"objects\": {\n \"f47ac10b-58cc-4372-a567-0e02b2c3d479\": {\n \"id\": \"5918a83b-36e2-4f71-ad1f-b3de3a127314\",\n \"self_uri\": \"drs://api.service.nhs.uk/upload-genomic-data/ga4gh/drs/v1/objects/5918a83b-36e2-4f71-ad1f-b3de3a127314\",\n \"name\": \"sample1_S1_L001_R1_001.fastq.gz\",\n \"size\": 31457280,\n \"mime_type\": \"text/fastq\",\n \"checksums\": [\n {\n \"checksum\": \"a3f1b7c9d2e4f6a8b0c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5\",\n \"type\": \"sha-256\"\n }\n ],\n \"upload_methods\": [\n {\n \"type\": \"s3\",\n \"access_url\": {\n \"url\": \"s3://gel-fos-prod-uploads/uploads/5918a83b-36e2-4f71-ad1f-b3de3a127314/sample1_S1_L001_R1_001.fastq.gz\"\n },\n \"region\": \"eu-west-2\",\n \"credentials\": {\n \"access_key_id\": \"ASIAXXX...\",\n \"secret_access_key\": \"wJalrXX...\",\n \"session_token\": \"FwoGZX...\"\n }\n }\n ]\n },\n \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\": {\n \"id\": \"7bf30889-18b6-4e31-bbce-f010f8261b24\",\n \"self_uri\": \"drs://api.service.nhs.uk/upload-genomic-data/ga4gh/drs/v1/objects/7bf30889-18b6-4e31-bbce-f010f8261b24\",\n \"name\": \"sample1_S1_L001_R2_001.fastq.gz\",\n \"size\": 32505856,\n \"mime_type\": \"text/fastq\",\n \"checksums\": [\n {\n \"checksum\": \"b4e2c8d3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9\",\n \"type\": \"sha-256\"\n }\n ],\n \"upload_methods\": [\n {\n \"type\": \"s3\",\n \"access_url\": {\n \"url\": \"s3://gel-fos-prod-uploads/uploads/7bf30889-18b6-4e31-bbce-f010f8261b24/sample1_S1_L001_R2_001.fastq.gz\"\n },\n \"region\": \"eu-west-2\",\n \"credentials\": {\n \"access_key_id\": \"ASIAXXX...\",\n \"secret_access_key\": \"wJalrXX...\",\n \"session_token\": \"FwoGZX...\"\n }\n }\n ]\n }\n}\n}\n\n```\n\nImportant: Response objects are keyed by server-generated UUIDs, not by filename. Match response entries back to your files using the `name` field within each object.\n\n**What to record per file:**\n\n- `id` and `self_uri` — needed for Stage 5 DocumentReferences\n- `upload_methods[0].access_url.url` — needed for Stages 3 and 4\n- `upload_methods[0].credentials` — needed for Stage 3\n- `upload_methods[0].region` — needed for Stage 3\n\n#### Stage 3: Upload files to S3\n\nFor each file, use the S3 credentials from Stage 2 to upload directly. No API authentication token is needed for this stage.\n\n```python\n\nimport boto3\n\ncreds = upload_method[\"credentials\"]\ns3_client = boto3.client(\n \"s3\",\n region_name=upload_method[\"region\"],\n aws_access_key_id=creds[\"access_key_id\"],\n aws_secret_access_key=creds[\"secret_access_key\"],\n aws_session_token=creds[\"session_token\"],\n)\n\n# Parse bucket and key from the access_url, e.g.\n# \"s3://gel-fos-prod-uploads/uploads/.../sample1_S1_L001_R1_001.fastq.gz\"\nbucket = \"gel-fos-prod-uploads\"\nkey = \"uploads/5918a83b-.../sample1_S1_L001_R1_001.fastq.gz\"\n\ns3_client.upload_file(\n Filename=\"/path/to/sample1_S1_L001_R1_001.fastq.gz\",\n Bucket=bucket,\n Key=key,\n)\n\n```\n\nRepeat for each file.\n\n#### Stage 4: Register DRS objects\n\nThis example registers the two files in a single request. In practice, registration requests are limited to 20 candidate objects and larger upload batches must be split across multiple Stage 4 calls.\n\n**Request:**\n\n```bash\n\nPOST /gel/drsupload/v1/register-objects\nContent-Type: application/json\nAuthorization: Bearer {access_token}\n# or \napikey: {api_key}\n\n```\n\n**Body:**\n\n```json\n\n{\n\"candidates\": [\n {\n \"name\": \"sample1_S1_L001_R1_001.fastq.gz\",\n \"size\": 31457280,\n \"mime_type\": \"text/fastq\",\n \"checksums\": [\n {\n \"checksum\": \"a3f1b7c9d2e4f6a8b0c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5\",\n \"type\": \"sha-256\"\n }\n ],\n \"access_methods\": [\n {\n \"type\": \"s3\",\n \"access_url\": {\n \"url\": \"s3://gel-fos-prod-uploads/uploads/5918a83b-36e2-4f71-ad1f-b3de3a127314/sample1_S1_L001_R1_001.fastq.gz\"\n }\n }\n ]\n },\n {\n \"name\": \"sample1_S1_L001_R2_001.fastq.gz\",\n \"size\": 32505856,\n \"mime_type\": \"text/fastq\",\n \"checksums\": [\n {\n \"checksum\": \"b4e2c8d3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9\",\n \"type\": \"sha-256\"\n }\n ],\n \"access_methods\": [\n {\n \"type\": \"s3\",\n \"access_url\": {\n \"url\": \"s3://gel-fos-prod-uploads/uploads/7bf30889-18b6-4e31-bbce-f010f8261b24/sample1_S1_L001_R2_001.fastq.gz\"\n }\n }\n ]\n }\n]\n}\n\n```\n\n**Response: 201 Created**\n\n#### Stage 5: Submit the FHIR transaction Bundle\n\nThe transaction Bundle references the ServiceRequest ID from Stage 1 and the DRS URIs from Stage 4. Note that intra-Bundle references use `urn:uuid:` format; references to existing resources (the ServiceRequest) use `ResourceType/{id}` format.\n\nImportant\n\nThe DocumentReference resources in this transaction Bundle reference the DRS object URIs returned from Stage 4 (register-objects).\n\nAlthough Stage 2 also returns object identifiers and DRS URIs, those are temporary and must not be used in FHIR DocumentReference resources.\n\n**Request:**\n\n```bash\n\nPOST /fhir/r4\nContent-Type: application/fhir+json\nAccept: application/fhir+json\nAuthorization: Bearer {access_token}\n# or \napikey: {api_key}\n\n```\n\n**Body:**\n\n
\nClick to see an example FHIR transaction Bundle\n\n```json\n{\n \"resourceType\": \"Bundle\",\n \"type\": \"transaction\",\n \"entry\": [\n {\n \"fullUrl\": \"urn:uuid:c1d2e3f4-a5b6-7890-cdef-1234567890ab\",\n \"resource\": {\n \"resourceType\": \"Specimen\",\n \"status\": \"available\",\n \"extension\": [\n {\n \"url\": \"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-SampleCategory\",\n \"valueCodeableConcept\": {\n \"coding\": [\n {\n \"system\": \"https://fhir.hl7.org.uk/CodeSystem/UKCore-SampleCategory\",\n \"code\": \"germline\"\n }\n ]\n }\n },\n {\n \"url\": \"https://genomicsengland.co.uk/fhir/StructureDefinition/gel1001-primary-sample-state\",\n \"valueCodeableConcept\": {\n \"coding\": [\n {\n \"system\": \"https://genomicsengland.co.uk/fhir/CodeSystem/gel1001-primary-sample-state\",\n \"code\": \"blood_unsorted_edta\"\n }\n ]\n }\n }\n ],\n \"type\": {\n \"coding\": [\n {\n \"system\": \"https://genomicsengland.co.uk/healthcare/data-specimen-type\",\n \"code\": \"wgs-data\"\n }\n ]\n },\n \"subject\": {\n \"type\": \"Patient\",\n \"identifier\": {\n \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n \"value\": \"p123456789\"\n }\n },\n \"request\": [\n {\n \"reference\": \"ServiceRequest/239218e7-1926-4272-a019-5410baf4c2e0\"\n }\n ],\n \"parent\": [\n {\n \"reference\": \"urn:uuid:d2e3f4a5-b6c7-8901-def0-234567890abc\"\n }\n ]\n },\n \"request\": {\n \"method\": \"POST\",\n \"url\": \"Specimen\"\n }\n },\n {\n \"fullUrl\": \"urn:uuid:d2e3f4a5-b6c7-8901-def0-234567890abc\",\n \"resource\": {\n \"resourceType\": \"Specimen\",\n \"status\": \"available\",\n \"extension\": [\n {\n \"url\": \"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-SampleCategory\",\n \"valueCodeableConcept\": {\n \"coding\": [\n {\n \"system\": \"https://fhir.hl7.org.uk/CodeSystem/UKCore-SampleCategory\",\n \"code\": \"germline\"\n }\n ]\n }\n }\n ],\n \"identifier\": [\n {\n \"system\": \"https://genomicsengland.co.uk/healthcare/lab-sample-id\",\n \"value\": \"123456789\",\n \"assigner\": {\n \"type\": \"Organization\",\n \"identifier\": {\n \"system\": \"https://fhir.nhs.uk/Id/ods-organization-code\",\n \"value\": \"69A50\"\n }\n }\n }\n ],\n \"subject\": {\n \"type\": \"Patient\",\n \"identifier\": {\n \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n \"value\": \"p123456789\"\n }\n }\n },\n \"request\": {\n \"method\": \"POST\",\n \"url\": \"Specimen\"\n }\n },\n {\n \"fullUrl\": \"urn:uuid:e3f4a5b6-c7d8-9012-ef01-34567890abcd\",\n \"resource\": {\n \"resourceType\": \"Procedure\",\n \"identifier\": [\n {\n \"system\": \"https://69A50.nhs.uk/sequencing-run-id\",\n \"value\": \"251230_A00123_0001_3F159011F8\"\n }\n ],\n \"basedOn\": [\n {\n \"type\": \"ServiceRequest\",\n \"identifier\": {\n \"system\": \"https://genomicsengland.co.uk/healthcare/referral-id\",\n \"value\": \"r123456789\"\n }\n }\n ],\n \"status\": \"completed\",\n \"code\": {\n \"coding\": [\n {\n \"system\": \"http://snomed.info/sct\",\n \"code\": \"51201000000109\",\n \"display\": \"Whole genome sequencing\"\n }\n ]\n },\n \"subject\": {\n \"type\": \"Patient\",\n \"identifier\": {\n \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n \"value\": \"p123456789\"\n }\n },\n \"performer\": [\n {\n \"actor\": {\n \"type\": \"Organization\",\n \"identifier\": {\n \"system\": \"https://fhir.nhs.uk/Id/ods-organization-code\",\n \"value\": \"69A50\"\n }\n }\n }\n ]\n },\n \"request\": {\n \"method\": \"POST\",\n \"url\": \"Procedure\"\n }\n },\n {\n \"fullUrl\": \"urn:uuid:f4a5b6c7-d8e9-0123-f012-4567890abcde\",\n \"resource\": {\n \"resourceType\": \"DocumentReference\",\n \"extension\": [\n {\n \"url\": \"lane_number\",\n \"valuePositiveInt\": 1\n }\n ],\n \"identifier\": [\n {\n \"system\": \"https://69A50.nhs.uk/file-id\",\n \"value\": \"sample1_S1_L001_R1_001.fastq.gz\"\n }\n ],\n \"status\": \"current\",\n \"docStatus\": \"final\",\n \"subject\": {\n \"type\": \"Patient\",\n \"identifier\": {\n \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n \"value\": \"p123456789\"\n }\n },\n \"author\": [\n {\n \"type\": \"Organization\",\n \"identifier\": {\n \"system\": \"https://fhir.nhs.uk/Id/ods-organization-code\",\n \"value\": \"69A50\"\n }\n }\n ],\n \"relatesTo\": [\n {\n \"code\": \"appends\",\n \"target\": {\n \"reference\": \"urn:uuid:a5b6c7d8-e9f0-1234-0123-567890abcdef\"\n }\n }\n ],\n \"content\": [\n {\n \"attachment\": {\n \"contentType\": \"text/fastq\",\n \"url\": \"drs://api.service.nhs.uk/upload-genomic-data/ga4gh/drs/v1/objects/5918a83b-36e2-4f71-ad1f-b3de3a127314\",\n \"hash\": \"a3f1b7c9d2e4f6a8b0c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5\",\n \"size\": 31457280,\n \"title\": \"sample1_S1_L001_R1_001.fastq.gz\"\n }\n }\n ],\n \"context\": {\n \"related\": [\n {\n \"reference\": \"ServiceRequest/239218e7-1926-4272-a019-5410baf4c2e0\"\n },\n {\n \"reference\": \"urn:uuid:c1d2e3f4-a5b6-7890-cdef-1234567890ab\",\n \"type\": \"Specimen\"\n },\n {\n \"reference\": \"urn:uuid:e3f4a5b6-c7d8-9012-ef01-34567890abcd\",\n \"type\": \"Procedure\"\n }\n ]\n }\n },\n \"request\": {\n \"method\": \"POST\",\n \"url\": \"DocumentReference\"\n }\n },\n {\n \"fullUrl\": \"urn:uuid:a5b6c7d8-e9f0-1234-0123-567890abcdef\",\n \"resource\": {\n \"resourceType\": \"DocumentReference\",\n \"extension\": [\n {\n \"url\": \"lane_number\",\n \"valuePositiveInt\": 1\n }\n ],\n \"identifier\": [\n {\n \"system\": \"https://69A50.nhs.uk/file-id\",\n \"value\": \"sample1_S1_L001_R2_001.fastq.gz\"\n }\n ],\n \"status\": \"current\",\n \"docStatus\": \"final\",\n \"subject\": {\n \"type\": \"Patient\",\n \"identifier\": {\n \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n \"value\": \"p123456789\"\n }\n },\n \"author\": [\n {\n \"type\": \"Organization\",\n \"identifier\": {\n \"system\": \"https://fhir.nhs.uk/Id/ods-organization-code\",\n \"value\": \"69A50\"\n }\n }\n ],\n \"relatesTo\": [\n {\n \"code\": \"transforms\",\n \"target\": {\n \"reference\": \"urn:uuid:f4a5b6c7-d8e9-0123-f012-4567890abcde\"\n }\n }\n ],\n \"content\": [\n {\n \"attachment\": {\n \"contentType\": \"text/fastq\",\n \"url\": \"drs://api.service.nhs.uk/upload-genomic-data/ga4gh/drs/v1/objects/7bf30889-18b6-4e31-bbce-f010f8261b24\",\n \"hash\": \"b4e2c8d3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9\",\n \"size\": 32505856,\n \"title\": \"sample1_S1_L001_R2_001.fastq.gz\"\n }\n }\n ],\n \"context\": {\n \"related\": [\n {\n \"reference\": \"ServiceRequest/239218e7-1926-4272-a019-5410baf4c2e0\"\n },\n {\n \"reference\": \"urn:uuid:c1d2e3f4-a5b6-7890-cdef-1234567890ab\",\n \"type\": \"Specimen\"\n },\n {\n \"reference\": \"urn:uuid:e3f4a5b6-c7d8-9012-ef01-34567890abcd\",\n \"type\": \"Procedure\"\n }\n ]\n }\n },\n \"request\": {\n \"method\": \"POST\",\n \"url\": \"DocumentReference\"\n }\n },\n {\n \"fullUrl\": \"urn:uuid:a1b7c8d8-e9f0-1234-0123-567890ffffff\",\n \"resource\": {\n \"resourceType\": \"Composition\",\n \"meta\": {\n \"versionId\": \"1\",\n \"lastUpdated\": \"2000-01-01T00:00:00.000000+00:00\"\n },\n \"status\": \"final\",\n \"type\": {\n \"text\": \"dWGS upload manifest\"\n },\n \"subject\": {\n \"reference\": \"urn:uuid:c1d2e3f4-a5b6-7890-cdef-1234567890ab\",\n \"type\": \"Specimen\"\n },\n \"date\": \"2000-01-01T00:00:00.000000+00:00\",\n \"author\": [\n {\n \"type\": \"Organization\",\n \"identifier\": {\n \"system\": \"https://fhir.nhs.uk/Id/ods-organization-code\",\n \"value\": \"69A50\"\n }\n }\n ],\n \"title\": \"dWGS upload manifest\",\n \"section\": [\n {\n \"title\": \"files\",\n \"entry\": [\n {\n \"reference\": \"urn:uuid:f4a5b6c7-d8e9-0123-f012-4567890abcde\"\n },\n {\n \"reference\": \"urn:uuid:a5b6c7d8-e9f0-1234-0123-567890abcdef\"\n }\n ]\n }\n ]\n },\n \"request\": {\n \"method\": \"POST\",\n \"url\": \"Composition\"\n }\n }\n ]\n}\n\n```\n\n
\n\n**Response (200 OK):**\n\n```json\n{\n\"resourceType\": \"Bundle\",\n\"type\": \"transaction-response\",\n\"entry\": [\n { \"response\": { \"status\": \"201 Created\", \"location\": \"Specimen/aabbccdd-1122-3344-5566-778899aabbcc/_history/1\" } },\n { \"response\": { \"status\": \"201 Created\", \"location\": \"Specimen/eeff0011-2233-4455-6677-8899aabbccdd/_history/1\" } },\n { \"response\": { \"status\": \"201 Created\", \"location\": \"Procedure/11223344-5566-7788-99aa-bbccddeeff00/_history/1\" } },\n { \"response\": { \"status\": \"201 Created\", \"location\": \"DocumentReference/22334455-6677-8899-aabb-ccddeeff0011/_history/1\" } },\n { \"response\": { \"status\": \"201 Created\", \"location\": \"DocumentReference/33445566-7788-99aa-bbcc-ddeeff001122/_history/1\" } }\n]\n}\n\n```\n\nWhat to record: The first Specimen entry is the wgs-data child. Extract its ID: `aabbccdd-1122-3344-5566-778899aabbcc`.\n\n#### Stage 6: Patch the ServiceRequest\n\nThis ServiceRequest had no existing `specimen` array (as observed in Stage 1), so the first operation uses `\"path\": \"/specimen\"` to create it.\n\n**Request:**\n\n```bash\n\nPATCH /fhir/r4/ServiceRequest/239218e7-1926-4272-a019-5410baf4c2e0\nContent-Type: application/json-patch+json\nAccept: application/fhir+json\nAuthorization: Bearer {access_token}\n# or \napikey: {api_key}\n\n```\n\n**Body:**\n\n```json\n[\n{\n \"op\": \"add\",\n \"path\": \"/specimen\",\n \"value\": [\n { \"reference\": \"Specimen/aabbccdd-1122-3344-5566-778899aabbcc\" }\n ]\n}\n]\n\n```\n\n**Response (200 OK):** Returns the updated ServiceRequest with the new `specimen` array.\n\nThe upload is now complete. The wgs-data Specimen reference on the ServiceRequest triggers downstream processing by the GEL WGS bioinformatics pipelines.\n\n#### Multi-lane uploads\n\nFor samples sequenced across multiple lanes, the transaction Bundle structure is the same except:\n\n- add one additional DocumentReference pair (Read 1 + Read 2) per extra lane\n- all DocumentReferences share the same Specimen and Procedure resources\n- each DocumentReference pair has its own `lane_number` extension value\n- a single Composition listing all DocumentReference resources\n\n#### Handling data quality issues\n\nIf consumers identify low-quality data for a sample on a single sequencing run (e.g., data that does not pass pre-defined quality thresholds), they should NOT attempt to upload data for that sample from that run's data.\n\nIf, by performing additional sequencing runs using the same sample library preparation, they generate sufficient high-quality data for the sample, they should either:\n\nUpload only the data from the additional sequencing run (e.g., if it created enough data to pass quality thresholds for the sample). The sample data from the first run that failed QC checks should not be uploaded.\n\nPerform a \"combined upload\" of data for that sample across both runs.\n\nIn a combined upload scenario, the FHIR transaction Bundle (Stage 5) must provide details of all contributing sequencing runs as separate Procedure resources. Each DocumentReference resource (e.g., for FASTQ files) must reference the specific Procedure resource that created it to ensure full traceability of the data's origin. All DocumentReferences from both sequencing runs must reference the same wgs-data Specimen.\n\n#### Troubleshooting\n\nThis section helps you diagnose and resolve common issues when using the Upload Genomic Data (UGD) API. Follow the guidance below before retrying a request.\n\n##### ServiceRequest and referral issues\n\n- No matching `ServiceRequest` is returned when searching by NGIS `referral_id`.\n- The expected `participant_id` is not present in `ServiceRequest.subject` or `ServiceRequest.supportingInfo`.\n- A `Specimen` or `DocumentReference` already exists for the sample and a re-upload was not intended.\n\nWhat to do\n\n- Verify e.g. with the Requesting Genomic Laboratory (RGL) the referral and participant identifiers before starting the upload.\n- If data is already registered for the sample, stop unless you are performing a deliberate re-upload.\n\n##### Upload request expires\n\n- Upload locations and temporary credentials are valid for 1 hour only.\n- The upload request expires if all files are not uploaded within this time window.\n\nWhat to do\n\n- Restart the process from Stage 1 to obtain new upload locations and credentials.\n\n##### File upload fails or times out (Stage 3)\n\n- Uploads to the storage location (for example S3) fail or are interrupted.\n- Temporary credentials expire before the upload completes.\n\nWhat to do\n\n- Abandon the upload for the affected file.\n- Do not reuse partially uploaded files.\n- Restart the process from Stage 1 for the affected sample.\n- Ensure network throughput is sufficient for large files to complete within the upload session lifetime.\n\n##### Incorrect file metadata\n\n- File size or SHA‑256 checksum does not match the uploaded file.\n- An incorrect MIME type is supplied.\n\nWhat to do\n\n- Calculate file size and checksum from the final file artefact.\n- Do not modify or recompress files after checksums are generated.\n- Use the documented MIME type for each file extension.\n\n##### Register-objects request fails (Stage 4)\n\n- More than 20 candidate objects are included in a single request.\n- An incorrect or missing `access_url` is supplied.\n- Registration is attempted for a file that was not successfully uploaded.\n\nWhat to do\n\n- Split registrations across multiple requests, with no more than 20 candidates per request.\n- Use the `access_url` returned in the corresponding upload request.\n- Register only files that were uploaded successfully.\n\n##### FHIR transaction Bundle validation errors (Stage 5)\n\n- Temporary object identifiers from Stage 2 are used in `DocumentReference` resources.\n- Required resources are missing from the transaction Bundle.\n- The wgs-data child `Specimen` is not the first entry in the Bundle.\n- Intra-Bundle references do not use `urn:uuid:` format.\n- `DocumentReference` resources do not reference the correct `Procedure` for the sequencing run.\n\nWhat to do\n\n- Use only persistent DRS object URIs returned from Stage 4.\n- Include all required resources: Specimen(s), Procedure(s), DocumentReference(s), and a Composition.\n- Ensure all internal references use `urn:uuid:`.\n- For multi-lane or multi-run uploads, ensure all lanes and runs are fully represented and correctly linked.\n\n##### ServiceRequest patch does not trigger downstream processing (Stage 6)\n\n- The ServiceRequest update completes but downstream pipelines are not triggered.\n\nWhat to do\n\n- Patch the wgs-data child Specimen only, not the parent lab-sample Specimen.\n- Use the correct JSON Patch path depending on whether the `specimen` array already exists.\n- Confirm the ServiceRequest ID matches the one retrieved in Stage 1.\n\n##### Data quality issues\n\n- Uploaded data fails local quality thresholds.\n- Repeat sequencing runs are not represented correctly.\n\nWhat to do\n\n- Do not upload data that failed local SGL QC checks.\n- Upload only high-quality data, or perform a combined upload where appropriate.\n- In combined uploads, include a separate `Procedure` for each sequencing run and ensure each file references the correct run.\n\n##### Authentication, rate limiting, and environment issues\n\n- Requests fail due to authentication or authorisation errors.\n- Requests are throttled due to rate limits.\n- Incorrect environment base URL is used.\n\nWhat to do\n\n- Confirm signed JWT authentication is configured correctly.\n- Ensure you are using the correct base URL for Dev, Integration, or Production.\n- Be aware of the default rate limit of 5 TPS per app when performing batch operations.\n\n## Access modes\n\nAccess to endpoints is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) and uses the NHS API Platform's 'signed JSON Web Token (JWT) authentication' method.\n\nTo set this up, see [NHS API Platform instructions](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\n\n## Status and roadmap\n\nThis API is in [Beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses)\n\n## Service level\n\nThis API is a silver service, meaning it is operational and supported 24 hours a day, 365 days a year.\n\nFor more information, [see service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Rate limits\n\nThe default rate limit is 5TPS (transactions per second) per app. If you require a higher rate limit please contact us or raise this during the onboarding process.\n\n## Technology\n\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).\n\nIt conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) and [GA4GH](https://www.ga4gh.org/) global standards.\n\nRefer to the [FHIR Genomics Implementation Guide](https://simplifier.net/guide/fhir-genomics-implementation-guide/Home?version=current) for more details about implementation requirements.\n\nThis specification is based on UK Core Ballot2 and conforms to the same.\n\n## Network access\n\nThis API is available on the internet. For more details, [see Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Errors\n\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n- 400 to 499 if it failed because of a client error by your application\n- 500 to 599 if it failed because of an error on our server\n\nErrors specific to this API are shown in the Operations section, under Response.\n\n[See the reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n\n## Open source\n\nThe following [open source resources](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) may be useful.\n\n## Environments and testing\n\n| Environment | Base URL |\n| ---------------- | -------------------------------------------------------- |\n| Dev | `https://dep.api.service.nhs.uk/upload-genomic-data-dep` |\n| Integration test | `https://int.api.service.nhs.uk/upload-genomic-data` |\n| Production | `https://api.service.nhs.uk/upload-genomic-data` |\n\n## Onboarding\n\nTo onboard to this API, you will need:\n\n- an NHS API Platform account\n- approval from Genomics England\n\nThe onboarding approval process can sometimes take awhile, so it's worth starting 2-4 weeks in advance.\n\n### How to get access\n\n1. Sign in to or create an account with the Developer Hub. [See Developer Hub](https://onboarding.prod.api.platform.nhs.uk/)\n2. Select Upload Genomic Data API\n3. Follow the steps\n4. Wait for approval\n\nFor a detailed guide to onboarding to this API, see onboarding guide.\n\nThis API is in the Alpha stage of development.\n\nYou cannot use the digital onboarding service (DOS) until it moves into Beta stage.\n\nOnce this happens, you will need to get your software approved by Genomics England. This takes about 5 working days.\n\nTo understand how the NHS API Platform digital onboarding process works, [see digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding).\n\n### Contact us\n\nFor help connecting to any NHS APIs see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support)\n\nFor support with connecting to the UGD API [contact Genomics England support desk](https://www.genomicsengland.co.uk/service-desk)\n","contact":{"name":"Genomics England","url":"https://www.genomicsengland.co.uk/","email":"ge-servicedesk@genomicsengland.co.uk"},"license":{"name":"TBC","url":"TBC"},"version":"v1.0"},"servers":[{"url":"https://dep.api.service.nhs.uk/upload-genomic-data-dep","description":"NHS APIM development/deployment"},{"url":"https://int.api.service.nhs.uk/upload-genomic-data","description":"NHS APIM integration"},{"url":"https://api.service.nhs.uk/upload-genomic-data","description":"NHS APIM production"}],"paths":{"/ga4gh/drs/v1/objects/{object_id}":{"get":{"tags":["GA4GH DRS endpoints"],"summary":"Get info about a DrsObject","operationId":"GetDrsObject","parameters":[{"name":"object_id","in":"path","description":"DrsObject identifier","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The DrsObject was found successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsObjectResponse"}}}},"202":{"description":"The operation is delayed and will continue asynchronously. The client should retry this same request after the delay specified by Retry-After header.","headers":{"Retry-After":{"name":"","in":"header","description":"Delay in seconds. The client should retry this same request after waiting for this duration. To simplify client response processing, this must be an integral relative time in seconds. This value SHOULD represent the minimum duration the client should wait before attempting the operation again with a reasonable expectation of success. When it is not feasible for the server to determine the actual expected delay, the server may return a brief, fixed value instead.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"integer"}}}},"400":{"description":"The request is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"403":{"description":"The requester is not authorized to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"404":{"description":"The requested DrsObject wasn't found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"500":{"description":"An unexpected error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}}},"deprecated":false}},"/gel/drsupload/v1/register-objects":{"post":{"tags":["GA4GH DRS endpoints"],"summary":"Register candidates as new DRS Objects","operationId":"registerDrsObjects","requestBody":{"description":"An array of DRS Objects to register.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterDrsObjectsRequest"}}},"required":true},"responses":{"201":{"description":"DRS Objects registered successfully"},"400":{"description":"At least one candidate DRS Object is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"403":{"description":"The requester is not authorized to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"409":{"description":"Duplicate candidate DRS Object names detected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"500":{"description":"An unexpected error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}}},"deprecated":false}},"/gel/drsupload/v1/upload-request":{"post":{"tags":["GA4GH DRS endpoints"],"summary":"Request upload locations and credentials for files","operationId":"requestDrsUpload","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsUploadRequest"}}},"required":true},"responses":{"200":{"description":"Upload locations and credentials created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsUploadResponse"}}}},"400":{"description":"Malformed DRS upload request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"403":{"description":"The requester is not authorized to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"500":{"description":"An unexpected error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}}},"deprecated":false}},"/fhir/r4/ServiceRequest":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Search for ServiceRequest resource type","description":"Performs a standard FHIR search against the ServiceRequest resource. Returns a Bundle\nof type `searchset` containing ServiceRequest resources that match the supplied \nsearch parameters.\n","parameters":[{"name":"identifier","in":"query","description":"NGIS referral ID","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"r123456789"},{"name":"category","in":"query","description":"The category of the ServiceRequest (e.g. rare-disease-wgs or cancer-wgs)\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-GenomeSequencingCategory|rare-disease-wgs"},{"name":"subject:identifier","in":"query","description":"Identifier of the ServiceRequest subject i.e. proband, expressed as a chained search on \nServiceRequest.subject. Typically an NGIS proband identifier.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"p123456789"},{"name":"requester:identifier","in":"query","description":"Identifier of the ServiceRequest requester, expressed as a chained search on \nServiceRequest.requester. Typically an ODS organisation code.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"699P0"},{"name":"performer:identifier","in":"query","description":"Identifier of the ServiceRequest performer, expressed as a chained search on \nServiceRequest.performer. Typically an ODS organisation code.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"699P0"}],"responses":{"200":{"description":"Success - Returns a Bundle","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/ServiceRequest/{id}":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Look up a specific ServiceRequest","parameters":[{"name":"id","in":"path","description":"The FHIR ServiceRequest \"id\"","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"1914486a-3302-4664-b4e4-b79140020059"}],"responses":{"200":{"description":"Success","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirServiceRequest"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"deprecated":false},"patch":{"tags":["HL7 FHIR endpoints"],"summary":"Update ServiceRequest","description":"Updates a ServiceRequest using JSON Patch (RFC 6902). In the upload protocol, this is used in Stage 6 to add wgs-data Specimen references to `ServiceRequest.specimen`, which triggers downstream bioinformatics pipelines.\n\nThe request body must use Content-Type `application/json-patch+json`.\n","parameters":[{"name":"id","in":"path","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/JsonPatchDocument"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirServiceRequest"}}}},"201":{"description":"Created","headers":{"Location":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirServiceRequest"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/Specimen":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Search for Specimen resource type","description":"Performs a standard FHIR search against the Specimen resource. Returns a Bundle\nof type `searchset` containing Specimen resources that match the supplied \nsearch parameters.\n","parameters":[{"name":"identifier","in":"query","description":"Specimen identifier (e.g. depending on the Specimen \"type\" either 2D barcode tube identifier (lab-sample-id) or GEL sample ID. Format: {system}|{value} e.g. https://genomicsengland.co.uk/healthcare/lab-sample-id|123456789\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://genomicsengland.co.uk/healthcare/sample-id|s_01km2v4qrfez18h0517d2db4ef"},{"name":"subject:identifier","in":"query","description":"Patient / participant identifier associated with the Specimen.\nFormat: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://genomicsengland.co.uk/healthcare/participant-id|p123456789"},{"name":"type","in":"query","description":"Specimen type code (e.g. wgs-data).\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"wgs-data"}],"responses":{"200":{"description":"Success - Returns a Bundle","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/Specimen/{id}":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Get a Specimen by ID","description":"Retrieve a single Specimen resource by its logical id.","operationId":"getSpecimenById","parameters":[{"name":"id","in":"path","description":"Logical id of the Specimen resource","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"002634d2-5d6b-4fcb-af24-dc0690a72a90"}],"responses":{"200":{"description":"Specimen resource","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirSpecimen"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/DocumentReference":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Search for DocumentReference resource type","description":"Performs a standard FHIR search against the DocumentReference resource. Returns a Bundle\nof type `searchset` containing DocumentReference resources that match the supplied \nsearch parameters.\n","parameters":[{"name":"subject","in":"query","description":"Reference to the Patient","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"Patient/5db37923-d212-42f7-aaaf-9035f301e26f"},{"name":"identifier","in":"query","description":"DocumentReference identifier e.g. the file name Format: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://ods123.nhs.uk/file-id|myfile.fastq.gz"},{"name":"subject:identifier","in":"query","description":"Patient / participant identifier associated with the DocumentReference.\nFormat: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://genomicsengland.co.uk/healthcare/participant-id|p123456789"},{"name":"status","in":"query","description":"DocumentReference status","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"enum":["current","superseded","entered-in-error"],"type":"string"},"example":"current"}],"responses":{"200":{"description":"Success - Returns a Bundle","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/DocumentReference/{id}":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Look up a specific DocumentReference","parameters":[{"name":"id","in":"path","description":"The FHIR DocumentReference \"id\"","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"00044410-e9e6-4bfc-890c-436a4c06a05e"}],"responses":{"200":{"description":"Success","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirDocumentReference"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/Procedure":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Search for Procedure resource type","description":"Performs a standard FHIR search against the Procedure resource. Returns a Bundle\nof type `searchset` containing Procedure resources that match the supplied \nsearch parameters.\n","parameters":[{"name":"subject","in":"query","description":"Reference to the Patient","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"Patient/50102606-7edb-4385-a01c-8d689d2702b2"},{"name":"subject:identifier","in":"query","description":"Patient participant NGIS identifier. Format: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://genomicsengland.co.uk/healthcare/participant-id|p123456789"},{"name":"identifier","in":"query","description":"Sequencing run identifier. Format: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://ods123.nhs.uk/sequencing-run-id|251230_A00123_0001_3F159011F8"},{"name":"based-on:identifier","in":"query","description":"Referral identifier from the originating ServiceRequest Format: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://genomicsengland.co.uk/healthcare/referral-id|r123456789"}],"responses":{"200":{"description":"Success - Returns a Bundle","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/Procedure/{id}":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Look up a specific Procedure","parameters":[{"name":"id","in":"path","description":"The FHIR Procedure \"id\"","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"2565ab5e-b110-4252-b1ee-e58ed0b1f070"}],"responses":{"200":{"description":"Success","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirProcedure"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4":{"post":{"tags":["HL7 FHIR endpoints"],"summary":"Submit a FHIR R4 transaction Bundle","description":"Submits a FHIR R4 transaction Bundle. The server processes each entry and returns a transaction-response Bundle. The request Bundle must have `type` set to `transaction`.\n","requestBody":{"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}},"required":true},"responses":{"200":{"description":"Success - Bundle processed (OK)","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"201":{"description":"Success - Bundle processed and resources created","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}}},"components":{"schemas":{"FhirServiceRequest":{"type":"object","description":"A FHIR R4 ServiceRequest resource. See the [FHIR R4 ServiceRequest documentation](https://hl7.org/fhir/R4/servicerequest.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/servicerequest.html"},"example":{"resourceType":"ServiceRequest","id":"239218e7-1926-4272-a019-5410baf4c2e0","meta":{"versionId":"1","lastUpdated":"2026-03-27T20:46:10.783652042Z"},"identifier":[{"system":"https://genomicsengland.co.uk/healthcare/referral-id","value":"r123456789"}],"status":"active","intent":"order","category":[{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-GenomeSequencingCategory","code":"rare-disease-wgs"}]}],"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"p123456789"}}}},"FhirSpecimen":{"type":"object","description":"A FHIR R4 Specimen resource. See the [FHIR R4 Specimen documentation](https://hl7.org/fhir/R4/specimen.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/specimen.html"},"example":{"resourceType":"Specimen","id":"002634d2-5d6b-4fcb-af24-dc0690a72a90","meta":{"versionId":"1","lastUpdated":"2026-03-19T10:44:29.324070944Z"},"extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-SampleCategory","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SampleCategory","code":"germline"}]}},{"url":"https://genomicsengland.co.uk/fhir/StructureDefinition/gel1001-primary-sample-state","valueCodeableConcept":{"coding":[{"system":"https://genomicsengland.co.uk/fhir/CodeSystem/gel1001-primary-sample-state","code":"blood_unsorted_edta"}]}}],"type":{"coding":[{"system":"https://genomicsengland.co.uk/healthcare/data-specimen-type","code":"wgs-data"}]},"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"p73353612603"}},"request":[{"reference":"ServiceRequest/239218e7-1926-4272-a019-5410baf4c2e0"}],"parent":[{"reference":"Specimen/2db7b176-fbf1-432b-8cb2-0fa51d502cdd"}],"identifier":[{"system":"https://genomicsengland.co.uk/healthcare/sample-id","value":"s_01km2v4qrfez18h0517d2db4ef"}]}},"FhirProcedure":{"type":"object","description":"A FHIR R4 Procedure resource. See the [FHIR R4 Procedure documentation](https://hl7.org/fhir/R4/procedure.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/procedure.html"},"example":{"resourceType":"Procedure","id":"2565ab5e-b110-4252-b1ee-e58ed0b1f070","identifier":[{"system":"https://69A50.nhs.uk/sequencing-run-id","value":"251230_A00123_0001_3F159011F8"}],"basedOn":[{"type":"ServiceRequest","identifier":{"system":"https://genomicsengland.co.uk/healthcare/referral-id","value":"r123456789"}}],"status":"completed","code":{"coding":[{"system":"http://snomed.info/sct","code":51201000000109,"display":"Whole genome sequencing"}]},"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"p123456789"}},"performer":[{"actor":{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"69A50"}}}],"meta":{"versionId":"1","lastUpdated":"2026-03-24T20:33:24.908401588Z"}}},"FhirDocumentReference":{"type":"object","description":"A FHIR R4 DocumentReference resource. See the [FHIR R4 DocumentReference documentation](https://hl7.org/fhir/R4/documentreference.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/documentreference.html"},"example":{"resourceType":"DocumentReference","id":"00044410-e9e6-4bfc-890c-436a4c06a05e","meta":{"versionId":"1","lastUpdated":"2026-03-13T18:12:57.157802680Z"},"extension":[{"url":"lane_number","valuePositiveInt":5}],"identifier":[{"system":"https://ods123.nhs.uk/file-id","value":"my-fastq.fastq.gz"}],"status":"current","docStatus":"final","subject":{"reference":"Patient/5db37923-d212-42f7-aaaf-9035f301e26f","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"p123456789"}},"author":[{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"69A50"}}],"relatesTo":[{"code":"appends","target":{"reference":"DocumentReference/956f244a-766f-451a-acaa-99cda79be373"}}],"content":[{"attachment":{"contentType":"text/fastq","url":"drs://api.service.nhs.uk/upload-genomic-data/ga4gh/drs/v1/objects/5918a83b-36e2-4f71-ad1f-b3de3a127314","hash":"ca1cf98c789b28c46af29493b5375ae3986a60a1cf8c78a849d8d36c40ab82ed","title":"my-fastq.fastq.gz"}}],"context":{"related":[{"reference":"ServiceRequest/10bbd33e-0676-4f95-ba41-dc9850956889"},{"reference":"Specimen/0d19b909-e6ba-4d95-9dde-b64c7f417fde","type":"Specimen"},{"reference":"Procedure/f6b8c147-c4ae-4c63-8cb6-5098766c64c4","type":"Procedure"}]}}},"FhirBundle":{"type":"object","description":"A FHIR R4 Bundle resource used as a transaction container. See the [FHIR R4 Bundle documentation](https://hl7.org/fhir/R4/bundle.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/bundle.html"},"example":{"resourceType":"Bundle","type":"transaction","entry":[{"fullUrl":"urn:uuid:{specimen_child_random_uuid}","resource":{"resourceType":"Specimen","status":"available","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-SampleCategory","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SampleCategory","code":"{sample_category}"}]}},{"url":"https://genomicsengland.co.uk/fhir/StructureDefinition/gel1001-primary-sample-state","valueCodeableConcept":{"coding":[{"system":"https://genomicsengland.co.uk/fhir/CodeSystem/gel1001-primary-sample-state","code":"{gel1001_sample_state}"}]}}],"type":{"coding":[{"system":"https://genomicsengland.co.uk/healthcare/data-specimen-type","code":"wgs-data"}]},"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"{participant_id}"}},"request":[{"reference":"ServiceRequest/{service_request_id}"}],"parent":[{"reference":"urn:uuid:{specimen_parent_random_uuid}"}]},"request":{"method":"POST","url":"Specimen"}},{"fullUrl":"urn:uuid:{specimen_parent_random_uuid}","resource":{"resourceType":"Specimen","status":"available","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-SampleCategory","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SampleCategory","code":"{sample_category}"}]}}],"identifier":[{"system":"https://genomicsengland.co.uk/healthcare/lab-sample-id","value":"{random_lsid}","assigner":{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"{ods_code}"}}}],"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"{participant_id}"}}},"request":{"method":"POST","url":"Specimen"}},{"fullUrl":"urn:uuid:{procedure_random_uuid}","resource":{"resourceType":"Procedure","identifier":[{"system":"https://\"{ods_code}\".nhs.uk/sequencing-run-id","value":"{sequencing_run_id}"}],"basedOn":[{"type":"ServiceRequest","identifier":{"system":"https://genomicsengland.co.uk/healthcare/referral-id","value":"{referral_id}"}}],"status":"completed","code":{"coding":[{"system":"http://snomed.info/sct","code":"51201000000109","display":"Whole genome sequencing"}]},"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"{participant_id}"}},"performer":[{"actor":{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"{ods_code}"}}}]},"request":{"method":"POST","url":"Procedure"}},{"fullUrl":"urn:uuid:{read1_ref_uuid}","resource":{"resourceType":"DocumentReference","extension":[{"url":"lane_number","valuePositiveInt":"{lane_id}"}],"identifier":[{"system":"https://\"{ods_code}\".nhs.uk/file-id","value":"{read1_filename}"}],"status":"current","docStatus":"final","subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"{participant_id}"}},"author":[{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"{ods_code}"}}],"relatesTo":[{"code":"appends","target":{"reference":"urn:uuid:{read2_ref_uuid}"}}],"content":[{"attachment":{"contentType":"text/fastq","url":"{read1_drs_uri}","hash":"{read1_checksum}","title":"{read1_filename}"}}],"context":{"related":[{"reference":"ServiceRequest/{service_request_id}"},{"reference":"urn:uuid:{specimen_child_random_uuid}","type":"Specimen"},{"reference":"urn:uuid:{procedure_random_uuid}","type":"Procedure"}]}},"request":{"method":"POST","url":"DocumentReference"}},{"fullUrl":"urn:uuid:{read2_ref_uuid}","resource":{"resourceType":"DocumentReference","extension":[{"url":"lane_number","valuePositiveInt":"{lane_id}"}],"identifier":[{"system":"https://\"{ods_code}\".nhs.uk/file-id","value":"{read2_filename}"}],"status":"current","docStatus":"final","subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"{participant_id}"}},"author":[{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"{ods_code}"}}],"relatesTo":[{"code":"transforms","target":{"reference":"urn:uuid:{read1_ref_uuid}"}}],"content":[{"attachment":{"contentType":"text/fastq","url":"{read2_drs_uri}","hash":"{read2_checksum}","title":"{read2_filename}"}}],"context":{"related":[{"reference":"ServiceRequest/{service_request_id}"},{"reference":"urn:uuid:{specimen_child_random_uuid}","type":"Specimen"},{"reference":"urn:uuid:{procedure_random_uuid}","type":"Procedure"}]}},"request":{"method":"POST","url":"DocumentReference"}}]}},"FhirOperationOutcome":{"type":"object","description":"A FHIR R4 OperationOutcome resource returned when an error occurs. See the [FHIR R4 OperationOutcome documentation](https://hl7.org/fhir/R4/operationoutcome.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/operationoutcome.html"},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"invalid","details":{"text":"ServiceRequest/service-request-001 not found"},"diagnostics":"The referenced ServiceRequest does not exist or you do not have permission to access it"}]}},"JsonPatchDocument":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/JsonPatchOperation"},"description":"JSON Patch (RFC 6902) document used with the FHIR PATCH interaction. Use with Content-Type: application/json-patch+json. [1](https://swagger.io/docs/specification/v3_0/adding-examples/)[2](https://github.com/microsoft/fhir-server/blob/main/docs/rest/JsonPatchRequests.http)\n","example":[{"op":"replace","path":"/status","value":"completed"},{"op":"add","path":"/specimen/-","value":{"reference":"Specimen/7bf30889-18b6-4e31-bbce-f010f8261b24"}}]},"Checksum":{"required":["checksum","type"],"type":"object","properties":{"checksum":{"type":"string","description":"The hex-string encoded checksum for the data."},"type":{"type":"string","description":"The digest method used to create the checksum. The value (e.g. sha-256) SHOULD be listed as Hash Name String in the https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg[IANA\n"}}},"AccessUrl":{"required":["url"],"type":"object","properties":{"url":{"type":"string","description":"A fully resolvable URL that can be used to fetch the actual object bytes."},"headers":{"type":"array","items":{"type":"string"},"description":"An optional list of headers to include in the HTTP request to url. These headers can be used to provide auth tokens required to fetch the object bytes.\n"}}},"AccessMethod":{"required":["type"],"type":"object","properties":{"type":{"enum":["s3","gs","ftp","gsiftp","globus"],"type":"string","description":"Type of the access method."},"access_url":{"$ref":"#/components/schemas/AccessUrl"},"access_id":{"type":"string","description":"An arbitrary string to be passed to the /access method to get an AccessURL. This string must be unique within the scope of a single object. Note that at least one of access_url and access_id must be provided.\n"},"region":{"type":"string","description":"The region where the object is stored."}}},"ContentsObject":{"required":["name"],"type":"object","properties":{"name":{"type":"string","description":"A name declared by the bundle author that must be used when materialising this object, overriding any name directly associated with the object itself. The name must be unique with the containing bundle. This string is made up of uppercase and lowercase letters, decimal digits, hypen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames].\n"},"id":{"type":"string","description":"A DRS identifier of a DrsObject (either a single blob or a nested bundle). If this ContentsObject is an object within a nested bundle, then the id is optional. Otherwise, the id is required.\n"},"drs_uri":{"type":"string","description":"A list of full DRS identifier URI paths that may be used to obtain the object. These URIs may be external to this DRS instance.\n"},"contents":{"type":"array","items":{"$ref":"#/components/schemas/ContentsObject"},"description":"If this ContentsObject describes a nested bundle and the caller specified \"?expand=true\" on the request, then this contents array must be present and describe the objects within the nested bundle.\n"}}},"DrsObjectResponse":{"required":["id","self_uri","size","created_time","checksums"],"type":"object","properties":{"id":{"type":"string","description":"An identifier unique to this DrsObject."},"name":{"pattern":"^[A-Za-z0-9.\\-_~]+$","type":"string","description":"A string that can be used to name a DrsObject. This string is made up of uppercase and lowercase letters, decimal digits, hyphen, period, and underscore [A-Za-z0-9.-_].\n"},"self_uri":{"type":"string","description":"A drs:// hostname-based URI, as defined in the DRS documentation, that tells clients how to access this object.\n"},"size":{"type":"integer","description":"For blobs, the blob size in bytes. For bundles, the cumulative size, in bytes, of items in the contents field.\n","format":"int64"},"created_time":{"type":"string","description":"Timestamp of content creation in RFC3339. (This is the creation time of the underlying content, not of the JSON object.)\n","format":"date-time"},"updated_time":{"type":"string","description":"Timestamp of content update in RFC3339, identical to created_time in systems that do not support updates. (This is the update time of the underlying content, not of the JSON object.)\n","format":"date-time"},"version":{"type":"string","description":"A string representing a version."},"mime_type":{"type":"string","description":"A string providing the mime-type of the DrsObject."},"checksums":{"type":"array","items":{"$ref":"#/components/schemas/Checksum"},"description":"The checksum of the DrsObject. At least one checksum must be provided. For blobs, the checksum is computed over the bytes in the blob. For bundles, the checksum is computed over a sorted concatenation of the checksums of its top-level contained objects (not recursive, names not included). The list of checksums is sorted alphabetically (hex-code) before concatenation and a further checksum is performed on the concatenated checksum value. For example, if a bundle contains blobs with the following checksums: md5(blob1) = 72794b6d md5(blob2) = 5e089d29 Then the checksum of the bundle is: md5( concat( sort( md5(blob1), md5(blob2) ) ) ) = md5( concat( sort( 72794b6d, 5e089d29 ) ) ) = md5( concat( 5e089d29, 72794b6d ) ) = md5( 5e089d2972794b6d ) = f7a29a04\n"},"access_methods":{"type":"array","items":{"$ref":"#/components/schemas/AccessMethod"},"description":"The list of access methods that can be used to fetch the DrsObject. Required for single blobs; optional for bundles.\n"},"contents":{"type":"array","items":{"$ref":"#/components/schemas/ContentsObject"},"description":"If not set, this DrsObject is a single blob. If set, this DrsObject is a bundle containing the listed ContentsObjects (some of which may be further nested).\n"},"description":{"type":"string","description":"A human readable description of the DrsObject."},"aliases":{"type":"array","items":{"type":"string"},"description":"A list of strings that can be used to find other metadata about this DrsObject from external metadata sources. These aliases can be used to represent secondary accession numbers or external GUIDs.\n"}}},"DrsErrorResponse":{"properties":{"msg":{"type":"string"},"status_code":{"type":"number"}},"additionalProperties":false},"CandidateDrsObject":{"required":["name","size","checksums","mime_type"],"type":"object","properties":{"name":{"type":"string","description":"A string that can be used to name a DrsObject. This string is made up of uppercase and lowercase letters, decimal digits, hyphen, period, and underscore [A-Za-z0-9.-_].\n"},"size":{"type":"integer","description":"For blobs, the blob size in bytes. For bundles, the cumulative size, in bytes, of items in the contents field.\n","format":"int64"},"mime_type":{"type":"string","description":"A string providing the mime-type of the DrsObject."},"checksums":{"type":"array","items":{"$ref":"#/components/schemas/Checksum"},"description":"The checksum of the DrsObject. At least one checksum must be provided. For blobs, the checksum is computed over the bytes in the blob. For bundles, the checksum is computed over a sorted concatenation of the checksums of its top-level contained objects (not recursive, names not included). The list of checksums is sorted alphabetically (hex-code) before concatenation and a further checksum is performed on the concatenated checksum value. For example, if a bundle contains blobs with the following checksums: md5(blob1) = 72794b6d md5(blob2) = 5e089d29 Then the checksum of the bundle is: md5( concat( sort( md5(blob1), md5(blob2) ) ) ) = md5( concat( sort( 72794b6d, 5e089d29 ) ) ) = md5( concat( 5e089d29, 72794b6d ) ) = md5( 5e089d2972794b6d ) = f7a29a04\n"},"access_methods":{"type":"array","items":{"$ref":"#/components/schemas/AccessMethod"},"description":"The list of access methods that can be used to fetch the DrsObject. Required for single blobs; optional for bundles.\n"},"description":{"type":"string","description":"A human readable description of the DrsObject."}}},"RegisterDrsObjectsRequest":{"required":["candidates"],"type":"object","properties":{"candidates":{"type":"array","items":{"$ref":"#/components/schemas/CandidateDrsObject"},"description":"A list of candidate DRS Objects to register."}}},"DrsUploadRequestObject":{"required":["name","size","mime_type","checksums"],"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer","format":"int64"},"mime_type":{"type":"string"},"checksums":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/Checksum"}},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}}}},"DrsUploadRequest":{"required":["objects"],"type":"object","properties":{"objects":{"type":"array","items":{"$ref":"#/components/schemas/DrsUploadRequestObject"}}}},"DrsUploadMethodType":{"enum":["s3","https"],"type":"string"},"DrsUploadMethod":{"required":["type","access_url","credentials"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/DrsUploadMethodType"},"access_url":{"$ref":"#/components/schemas/AccessUrl"},"region":{"type":"string"},"credentials":{"type":"object","additionalProperties":{"type":"string"}}}},"DrsUploadResponseObject":{"required":["id","self_uri","name","size","mime_type","checksums"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"self_uri":{"type":"string"},"name":{"type":"string"},"size":{"type":"integer","format":"int64"},"mime_type":{"type":"string"},"checksums":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/Checksum"}},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"upload_methods":{"type":"array","items":{"$ref":"#/components/schemas/DrsUploadMethod"}}}},"DrsUploadResponse":{"required":["objects"],"type":"object","properties":{"objects":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DrsUploadResponseObject"}}}},"JsonPatchOperation":{"required":["op","path"],"type":"object","properties":{"op":{"enum":["add","remove","replace","move","copy","test"],"type":"string","description":"JSON Patch operation."},"path":{"type":"string","description":"JSON Pointer path to the element being changed.","example":"/status"},"value":{"description":"Value to apply for add/replace/test operations."},"from":{"type":"string","description":"Source path for move/copy operations."}},"additionalProperties":false,"description":"A single JSON Patch operation. For simple status updates, use: { \"op\": \"replace\", \"path\": \"/status\", \"value\": \"completed\" }.\n"}},"responses":{"BadRequest":{"description":"400 - Bad Request. The request could not be understood or was missing required parameters.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirOperationOutcome"}}}},"Unauthorized":{"description":"401 - Unauthorized. Authentication is required or has failed.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirOperationOutcome"}}}},"Forbidden":{"description":"403 - Forbidden. You do not have permission to access this resource.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirOperationOutcome"}}}},"NotFound":{"description":"404 - Not Found. The resource ID does not exist.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirOperationOutcome"}}}},"ServerError":{"description":"500 - Internal Server Error.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirOperationOutcome"}}}}},"securitySchemes":{"app-level0":{"$ref":"https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/app-level0"},"app-level3":{"$ref":"https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/app-level3"}}},"security":[{"app-level3":[]}]}