{"openapi":"3.0.3","info":{"title":"Pathology and Laboratory Medicine Reporting - FHIR API","description":"## Overview\nUse this API to send structured pathology test results from a laboratory middleware system to the organisation that requested the test in general practice.\n\n![Pathology API High-level Diagram](https://digital.nhs.uk/binaries/content/gallery/website/developer/api-catalogue/pathology-laboratory-reporting/pathology-and-laboratory-medicine-reporting-fhir-api.png)\n\n
\n
\n \n
\n \n \n \n \n \n \n \n

How it works

\n
\n \n
\n

Laboratory middleware systems receive and process batches of test results from Laboratory Information Management Systems (LIMS), following which:

\n
    \n
  1. Laboratory middleware systems send individual test results to the Pathology API. Each test result relates to a single Patient, but may contain multiple observations.
    2. \n
  2. The Pathology API validates the request and stores the test result in Patient Data Manager (PDM).
    3. \n
  3. Once stored, the Pathology API publishes an event to the Multicast Notification Service (MNS), containing details of the organisation that requested the test and a pointer to where the test result is stored in PDM.
    4. \n
\n

Separate to this process:

\n
    \n
  1. General Practice Information Management (GPIT) systems subscribe to Pathology and Laboratory Medicine Reporting test result stored events, and receive events that are relevant to them.
    2. \n
  2. GPIT systems use the information specified on MNS events to request test results from Patient Data Manager.
    3. \n
  3. Test results are retrieved from Patient Data Manager and processed by the GPIT system.
    4. \n
\n
\n
\n
\n\nUsing this API you can:\n- Send a laboratory test result\n\nThis API replaces the current [Pathology Messaging - EDIFACT API](https://digital.nhs.uk/developer/api-catalogue/pathology-messaging-edifact) and provides support for the following pathology specialisms, with further specialism coverage under review:\n- clinical biochemistry (also known as chemical pathology), haematology, immunology, and transfusion medicine\n- microbiology - this includes bacteriology, virology, and serology\n\n## Who can use this API\nYou can use this API if you are a software developer for a middleware application, supporting the aggregation and dissemination of pathology test results from Laboratory Information Management Systems (LIMS).\n\nYou must register with us prior to using the API, with onboarding currently restricted to invited applications only.\n\n## Related APIs\nThe following APIs are used by the Pathology and Laboratory Medicine Reporting API to facilitate the storage of pathology test results and publication of events to GP systems:\n\n- [Patient Data Manager FHIR API](https://digital.nhs.uk/developer/api-catalogue/patient-data-manager) - used to store, retrieve, and manage patient healthcare data in a standardised, interoperable format.\n- [Multicast Notification Service API](https://digital.nhs.uk/developer/api-catalogue/multicast-notification-service) - used to publish and receive patient-related healthcare events.\n\n## API status and roadmap\nThis API is currently [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\n\n## Service level\nTo be confirmed.\n\n## Technology\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest) and conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir) global standards for health care data exchange, specifically to [FHIR Release 4](https://www.hl7.org/fhir/R4/).\n\nThe FHIR R4 API is built alongside the [NHS England Pathology FHIR Implementation Guide](https://simplifier.net/guide/pathology-fhir-implementation-guide?version=0.3.1), which is built on top of [FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core).\n\n## Network access\nThis API is available on the internet.\n\nFor more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Security and authorisation\nThis API has one access mode:\n- [application-restricted access](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis)\n\n### Application-restricted access\nWith application-restricted access, we authenticate the calling application but not the end user. This access mode can be used when an end user is not present, for example as part of an automated process.\n\nTo use this access mode, use the following security pattern: [Application-restricted RESTful APIs - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\n\n## Environments and testing\n| Environment | Base Url |\n|-------------|----------|\n| Integration | https://int.api.service.nhs.uk/pathology-laboratory-reporting |\n\nOur [integration](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing) test environment:\n- is for formal integration testing\n- is stateful, so persists updates\n- includes security and authorisation restrictions\n\nTo use our integration test environment:\n- use the [instructions](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis) to setup an application in our integration test environment\n- contact us with your application ID and application name\n\n## Onboarding\nYou need to get your software approved by us before it can go live with this API.\n\nThis API is currently in Alpha with restricted onboarding by invite only.\n\n## Errors\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\nOn error we return a FHIR [OperationOutcome](https://build.fhir.org/operationoutcome.html) resource. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n","contact":{"name":"API Support"},"version":"0.1.0"},"servers":[{"url":"https://int.api.service.nhs.uk/pathology-laboratory-reporting","description":"Integration environment"}],"paths":{"/FHIR/R4/Bundle":{"post":{"summary":"Send a laboratory test result","description":"Use this endpoint to send a FHIR [Document Bundle](https://hl7.org/fhir/R4/bundle.html) to the API.\n\nThe bundle type must be `document` (https://hl7.org/fhir/R4/bundle-definitions.html#Bundle.type). All other bundle types are not supported.\n\nThe request bundle must:\n\n- have type `document`\n- contain a `Composition` resource as the first entry in the bundle\n- contain exactly one `DiagnosticReport` resource\n- specify the ODS code of requesting practitioners organisation, either:\n - directly via a `ServiceRequest` resource:\n - DiagnosticReport.basedOn, which references one or more `ServiceRequest` resources\n - ServiceRequest.requester which references an `Organization` resource\n - Organization.identifier\n - or indirectly via a `PractitionerRole` resource:\n - DiagnosticReport.basedOn, which references one or more `ServiceRequest` resources\n - ServiceRequest.requester which references a `PractitionerRole` resource\n - PractitionerRole.organisation, which references an `Organization` resource\n - Organization.identifier\n - Note that only a single ODS code for the requesting organisation may be defined. Where multiple `ServiceRequest` resources are referenced from DiagnosticReport.basedOn, the Organization.identifier associated with each `ServiceRequest` must specify the same value. Requests that yield multiple distinct ODS codes for the requesting organisation will be rejected.\n- specify the Patient's NHS Number, found at Composition.subject.identifier.value\n- conform with the guidance and requirements outlined in the [NHS England Pathology FHIR Implementation Guide](https://simplifier.net/guide/pathology-fhir-implementation-guide)\n- have each entry specifying a fullUrl\n","operationId":"postBundle","parameters":[{"name":"X-Correlation-ID","in":"header","description":"Arbitrary identifier used to identify a given request. Useful when debugging or tracing a request that has been sent to this endpoint, as its value will be echoed in any response.","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"uuid","example":"b876145d-1ebf-4e22-8ff8-275b570c1ec4"}},{"name":"X-Request-ID","in":"header","description":"Note this value is not currently in use, however should be provided by Clients to ensure compatibility with future releases.\n\nA UUID unique to a given Test Result. This value will be utilised as an Idempotency key for a given request, utilised to ensure that multiple requests with the same X-Request-ID value will not result in multiple Test Results being created. When completing any retrying around the sending of a Test Result, Clients should ensure that the same `X-Request-ID` value is utilised for each retry attempt.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"uuid","example":"abafd190-3678-425c-94f5-d1d7dc595142"}}],"requestBody":{"content":{"application/fhir+json":{"schema":{"required":["resourceType","type","entry"],"type":"object","properties":{"resourceType":{"enum":["Bundle"],"type":"string","description":"FHIR resource type"},"meta":{"allOf":[{"$ref":"#/components/schemas/meta"}],"description":"Metadata for the Bundle resource. The `security` field must not be included; security labels are applied by the API and any request that includes `meta.security` will be rejected with a `400` response."},"type":{"enum":["document"],"type":"string","description":"The type of the bundle","example":"document"},"entry":{"type":"array","items":{"required":["fullUrl","resource"],"type":"object","properties":{"fullUrl":{"type":"string","description":"URI for resource","example":"composition"},"resource":{"anyOf":[{"$ref":"#/components/schemas/CompositionResource"},{"$ref":"#/components/schemas/DiagnosticReportResource"},{"$ref":"#/components/schemas/ServiceRequestResource"},{"$ref":"#/components/schemas/PractitionerRoleResource"},{"$ref":"#/components/schemas/OrganizationResource"},{"required":["resourceType"],"type":"object","properties":{"resourceType":{"enum":["Patient","Observation","Specimen","Practitioner"],"type":"string","description":"Type of FHIR resource (e.g. \"Patient\", \"Observation\", etc.)","example":"Patient"}}}]}}},"description":"Entries that form a Test Report. Any included entries should comply with the [Pathology FHIR Implementation Guide](https://simplifier.net/guide/pathology-fhir-implementation-guide/Home), though the following resources and fields are specifically required when calling this endpoint:\n| Resource Type | Required Fields |\n|------------------|-----------------|\n| Composition | - `subject` - Required to identify the Patient a given Test Result is for. The `Subject` should include an `identifier` referencing the `https://fhir.nhs.uk/Id/nhs-number` `system` value. |\n| DiagnosticReport | - `basedOn` - Identifies one or more ServiceRequests contained within the Test Report. This field should be a [Literal Reference](https://hl7.org/fhir/R4/references.html#literal) to one or more ServiceRequest resources within this `Bundle`. |\n| ServiceRequest | - `requester` - Identifies the requester of a given test. This field should be a [Literal Reference](https://hl7.org/fhir/R4/references.html#literal) to a `PractitionerRole`or `Organization` resource within this `Bundle`. |\n| PractitionerRole | - `organization` - When referenced from ServiceRequest.requester, identifies the organization that requested a given test. This field should be a [Literal Reference](https://hl7.org/fhir/R4/references.html#literal) to an `Organization` resource within this `Bundle`. |\n| Organization | - `identifier` - Indicates the [ODS](https://digital.nhs.uk/services/organisation-data-service#top) code for the organisation that requested a given test. This field should include an identifier utilising the `system` value of `https://fhir.nhs.uk/Id/ods-organization-code`. |\n"}},"example":{"resourceType":"Bundle","type":"document","entry":[{"fullUrl":"composition","resource":{"resourceType":"Composition","subject":{"identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9999999999"}}}},{"fullUrl":"ServiceRequest","resource":{"resourceType":"ServiceRequest","requester":{"reference":"PractitionerRole"}}},{"fullUrl":"PractitionerRole","resource":{"resourceType":"PractitionerRole","organization":{"reference":"Organization"}}},{"fullUrl":"Organization","resource":{"resourceType":"Organization","identifier":[{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"A12345"}]}},{"fullUrl":"Patient","resource":{"resourceType":"Patient"}},{"fullUrl":"DiagnosticReport","resource":{"resourceType":"DiagnosticReport","basedOn":[{"reference":"ServiceRequest"}]}},{"fullUrl":"Practitioner","resource":{"resourceType":"Practitioner"}},{"fullUrl":"Observation","resource":{"resourceType":"Observation"}}]}}}},"required":true},"responses":{"200":{"description":"Successful response","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/X-Correlation-ID"}},"content":{"application/fhir+json":{"schema":{"required":["resourceType","type"],"type":"object","properties":{"resourceType":{"enum":["Bundle"],"type":"string","description":"FHIR resource type (always \"Bundle\")"},"meta":{"type":"object","properties":{"versionId":{"type":"string","description":"Version identifier for the resource"},"lastUpdated":{"type":"string","description":"Timestamp of when the Test Result was created.","format":"date-time"},"tag":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","format":"uri"},"code":{"type":"string"}}},"description":"Tags applied to the resource"}},"description":"Metadata about the resource","nullable":true},"type":{"enum":["document","transaction"],"type":"string","description":"The type of the bundle"},"identifier":{"type":"object","properties":{"system":{"type":"string","format":"uri"},"value":{"type":"string","format":"uuid"}},"description":"Persistent identifier for the bundle (UUID)","nullable":true},"entry":{"type":"array","items":{"required":["fullUrl","resource"],"type":"object","properties":{"fullUrl":{"type":"string","description":"URI for resource"},"resource":{"required":["resourceType"],"type":"object"}}},"description":"Entries in the bundle","nullable":true}}},"examples":{"Example success response":{"summary":"Example success response","value":{"id":"f0f87d08-e5e9-4b28-a0ae-f5a8c6df01b4","meta":{"versionId":"1","lastUpdated":"2024-01-01T12:00:00Z","tag":[{"system":"http://terminology.hl7.org/CodeSystem/v3-ActCode","code":"NOPAT"}]},"resourceType":"Bundle","type":"document","entry":[{"fullUrl":"composition","resource":{"resourceType":"Composition","subject":{"identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9999999999"}}}},{"fullUrl":"ServiceRequest","resource":{"resourceType":"ServiceRequest","requester":{"reference":"PractitionerRole"}}},{"fullUrl":"PractitionerRole","resource":{"resourceType":"PractitionerRole","organization":{"reference":"Organization"}}},{"fullUrl":"Organization","resource":{"resourceType":"Organization","identifier":[{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"A12345"}]}},{"fullUrl":"Patient","resource":{"resourceType":"Patient"}},{"fullUrl":"DiagnosticReport","resource":{"resourceType":"DiagnosticReport","basedOn":[{"reference":"ServiceRequest"}]}},{"fullUrl":"Practitioner","resource":{"resourceType":"Practitioner"}},{"fullUrl":"Observation","resource":{"resourceType":"Observation"}}]}}}}}},"400":{"description":"Invalid request","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/X-Correlation-ID"}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"examples":{"Example Validation Error response":{"summary":"Example OperationOutcome response for invalid request","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"invalid","diagnostics":"Resources must be provided as a bundle of type document"}]}},"Example meta.tag rejected response":{"summary":"Example OperationOutcome response when meta.tag is present","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"invalid","diagnostics":"Bundles must not include meta.tag; tags are applied by the API"}]}}}}}},"401":{"description":"Unauthorized request","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/X-Correlation-ID"}}},"500":{"description":"Unexpected internal error","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/X-Correlation-ID"}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"examples":{"Example Internal Error response":{"summary":"Example OperationOutcome response for unexpected internal error","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"invalid","diagnostics":"An unexpected internal error has occurred"}]}}}}}},"403":{"description":"Forbidden request","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/X-Correlation-ID"}}}},"deprecated":false,"security":[{"app-level3":[]}]}}},"components":{"schemas":{"meta":{"type":"object","properties":{"profile":{"type":"array","items":{"type":"string"}},"versionId":{"type":"string"}}},"CompositionResource":{"required":["resourceType","subject"],"type":"object","properties":{"resourceType":{"enum":["Composition"],"type":"string","description":"Type of FHIR resource (always \"Composition\")","example":"Composition"},"meta":{"$ref":"#/components/schemas/meta"},"subject":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/nhs-number"],"type":"string","example":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"type":"string","example":"9999999999"}}}}}}},"DiagnosticReportResource":{"required":["resourceType","basedOn"],"type":"object","properties":{"resourceType":{"enum":["DiagnosticReport"],"type":"string","description":"Type of FHIR resource (always \"DiagnosticReport\")","example":"DiagnosticReport"},"basedOn":{"minItems":1,"type":"array","items":{"required":["reference"],"type":"object","properties":{"reference":{"type":"string","description":"A Literal Reference to a ServiceRequest resource within the current Bundle. This provided reference should resolve to the `fullUrl` of a ServiceRequest entry within the current Bundle.","example":"urn:uuid:8a6d85b8-9837-4fed-a257-4cf207988338"}}}},"meta":{"$ref":"#/components/schemas/meta"}}},"ServiceRequestResource":{"required":["resourceType","requester"],"type":"object","properties":{"resourceType":{"enum":["ServiceRequest"],"type":"string","description":"Type of FHIR resource (always \"ServiceRequest\")","example":"ServiceRequest"},"requester":{"required":["reference"],"type":"object","properties":{"reference":{"type":"string","description":"A Literal Reference to either a PractitionerRole or Organization resource within the current Bundle. This provided reference should resolve to the `fullUrl` of a PractitionerRole or Organization entry within the current Bundle.","example":"urn:uuid:8a6d85b8-9837-4fed-a257-4cf207988338"}}},"meta":{"$ref":"#/components/schemas/meta"}}},"PractitionerRoleResource":{"required":["resourceType","organization"],"type":"object","properties":{"resourceType":{"enum":["PractitionerRole"],"type":"string","description":"Type of FHIR resource (always \"PractitionerRole\")","example":"PractitionerRole"},"organization":{"required":["reference"],"type":"object","properties":{"reference":{"type":"string","description":"A Literal Reference to an `Organization` resource within the current Bundle. This provided reference should resolve to the `fullUrl` of an `Organization` entry within the current Bundle.","example":"urn:uuid:7cbbacfa-1b8c-4d9e-9c5a-8fbbacfa1b8c"}}},"meta":{"$ref":"#/components/schemas/meta"}}},"OrganizationResource":{"required":["resourceType","identifier"],"type":"object","properties":{"resourceType":{"enum":["Organization"],"type":"string","description":"Type of FHIR resource (always \"Organization\")","example":"Organization"},"identifier":{"minItems":1,"type":"array","items":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/ods-organization-code"],"type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"ODS code of the requesting organisation","example":"A12345"}}}},"meta":{"$ref":"#/components/schemas/meta"}}},"OperationOutcome":{"required":["resourceType","issue"],"type":"object","properties":{"resourceType":{"enum":["OperationOutcome"],"type":"string","example":"OperationOutcome"},"issue":{"type":"array","items":{"required":["severity","code","diagnostics"],"type":"object","properties":{"severity":{"enum":["fatal","error"],"type":"string","example":"error"},"code":{"enum":["invalid","not-found","exception"],"type":"string","example":"invalid"},"diagnostics":{"type":"string"}}}},"meta":{"$ref":"#/components/schemas/meta"}}}},"headers":{"X-Correlation-ID":{"name":"","in":"header","description":"Echoes the value provided within the `X-Correlation-ID` request header.","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}}},"securitySchemes":{"app-level3":{"$ref":"https://proxygen.ptl.api.platform.nhs.uk/components/securitySchemes/app-level3"}}}}