{"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 at least the following resources:\n - a `Composition` resource as the first entry in the bundle, containing Composition.subject.identifier.value which is populated with the patient's NHS Number\n - a `ServiceRequest` resource, containing ServiceRequest.requester which references a `PractitionerRole` resource\n - a `PractitionerRole` resource, containing PractitionerRole.organisation which references an `Organization` resource\n - an `Organization` resource, containing a Organization.identifier which is populated with the ODS code of the requesting practitioners organisation\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":{"$ref":"#/components/schemas/meta"},"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/ServiceRequestResource"},{"$ref":"#/components/schemas/PractitionerRoleResource"},{"$ref":"#/components/schemas/OrganizationResource"},{"required":["resourceType"],"type":"object","properties":{"resourceType":{"enum":["Patient","Observation","DiagnosticReport","Specimen","Practitioner"],"type":"string","description":"Type of FHIR resource (e.g. \"Patient\", \"Observation\", etc.)","example":"Patient"}}}]}}},"description":"Entries that form a Test Result. 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 - `extension[http://hl7.eu/fhir/StructureDefinition/composition-basedOn-order-or-requisition]` - Defines a reference to the `ServiceRequest` within the provided `Bundle`. Provides a [Literal Reference](https://hl7.org/fhir/R4/references.html#literal) to a `ServiceRequest` within the current Test Result `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` resource within this `Bundle`. |\n| PractitionerRole | - `organization` - 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 request 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"},"extension":[{"url":"http://hl7.eu/fhir/StructureDefinition/composition-basedOn-order-or-requisition","valueReference":{"reference":"ServiceRequest"}}]}}},{"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"}},{"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"}},"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"},"resourceType":"Bundle","type":"document","entry":[{"fullUrl":"composition","resource":{"resourceType":"Composition","subject":{"identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9999999999"},"extension":[{"url":"http://hl7.eu/fhir/StructureDefinition/composition-basedOn-order-or-requisition","valueReference":{"reference":"ServiceRequest"}}]}}},{"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"}},{"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"}]}}}}}},"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","extension"],"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"}}},"extension":{"type":"array","items":{"required":["url","valueReference"],"type":"object","properties":{"url":{"enum":["http://hl7.eu/fhir/StructureDefinition/composition-basedOn-order-or-requisition"],"type":"string","example":"http://hl7.eu/fhir/StructureDefinition/composition-basedOn-order-or-requisition"},"valueReference":{"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"}}}}}}}}}},"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 a PractitionerRole resource within the current Bundle. This provided reference should resolve to the `fullUrl` of a PractitionerRole entry within the current Bundle.","example":"urn:uuid:8a6d85b8-9837-4fed-a257-4cf207988338"}}}}},"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"}}}}},"OrganizationResource":{"required":["resourceType","identifier"],"type":"object","properties":{"resourceType":{"enum":["Organization"],"type":"string","description":"Type of FHIR resource (always \"Organization\")","example":"Organization"},"identifier":{"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"}}}}},"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"}}}}}}},"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"}}}}