{"openapi":"3.0.3","info":{"title":"Prescription Status Update API","description":"## Overview\nUse this API to enable dispensing suppliers to push status information about electronic prescriptions to patients on a national scale via the NHS App (and potential other third parties in the future).\n\nThe overall aim of the service is to reduce burden to frontline NHS services by reducing the number of routine patient queries about their prescriptions.\n\nYou can:\n* enable patients to know when their prescription is ready\n* enable dispensing suppliers to push status information about electronic prescriptions\n## Who can use this API\nThe Prescription Status Update API is intended for use by EPS assured dispensing PMR systems which have onboarded to the EPS Dispensing FHIR API or the legacy EPS HL7v3 API, so they can provide patient prescription status updates to enable NHS App user to track prescription readiness\n## Related APIs\nThe following APIs are related to the Prescription Status Update API:\n* [Electronic Prescriptions Service Prescribing](https://digital.nhs.uk/developer/api-catalogue/eps-fhir-prescribing-api): the national service for creating prescriptions across health and social care.\n* [Electronic Prescriptions Service Dispensing](https://digital.nhs.uk/developer/api-catalogue/eps-fhir-dispensing-api): the national service for dispensing prescriptions across health and social care.\n* [Prescriptions for Patients](https://digital.nhs.uk/developer/api-catalogue/prescriptions-for-patients-fhir-api-v2): the national service to retrieve prescriptions data for individual patients from the Electronic Prescription Service (EPS), for use in patient-facing applications.\n## API Status and Roadmap\nThis API is [in beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), which means it is being used by a small number of suppliers and could still be subject to breaking changes.\n## Service Level\nThis API is a silver service, meaning it is operational and supported between 8am and 6pm, Monday to Friday, but not bank holidays.\nFor more details see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n## Technology\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).\nIt conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) global standard for health care data exchange, specifically to [FHIR R4 (v4.0.1)](https://hl7.org/fhir/r4/).\nIt includes some country-specific FHIR extensions, which are built against FHIR UK Core, specifically [UK Core STU3 (v0.0.9)](https://simplifier.net/HL7FHIRUKCoreR4/).\nYou do not need to know much about FHIR to use this API. The API only supports POST requests containing FHIR transactions.\nFHIR APIs are just RESTful APIs that follow specific rules.\nThese rules mean:\n* resource names are capitalised and singular, for example `/Bundle` not `/bundle`\n* array names are singular, for example `line` not `lines` for address lines\n* data items that are country specific and not included in the FHIR global base resources are usually wrapped in an `extension` object\nThere are [libraries and software development kits](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) available to help with FHIR API integration.\n## Network Access\nThis API is available on the internet.\nFor more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n## Security and Authorisation\nThis API only supports [application-restricted access](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user.\n### Application-restricted Access\nThe end user could be:\n* a healthcare worker - in which case you must ensure they are authenticated and suitably authorised locally\n* not present at all - for example as part of a back end process to check NHS numbers for data flowing from one system to another\nTo use this access mode, use the following security pattern:\n* [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)\n### Errors\nWe use standard HTTP status codes to show whether an API request succeeded or not.\nThey are usually in the range:\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 each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n## Open source\nYou might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful:\n| Resource | Description | Links |\n|----------|-------------|-------|\n| FHIR libraries and SDKs | Various open source libraries for integrating with FHIR APIs. | [FHIR libraries and SDKs](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) |\n| nhs-number | Python package containing utilities for NHS numbers including validity checks, normalisation and generation. | [GitHub repo](https://github.com/uk-fci/nhs-number) \\| [Python Package index](https://pypi.org/project/nhs-number/) \\| [Docs](https://nhs-number.uk-fci.tech/) |\n| Prescription Status Update API | Source code for the EPS Prescription Status Update API | [GitHub](https://github.com/NHSDigital/eps-prescription-status-update-api) |\n| EPS FHIR Validator Lambda | An AWS Lambda function that validates FHIR R4 messages | [GitHub](https://github.com/NHSDigital/eps-FHIR-validator-lambda) |\n## Environment and testing\n| Environment      | Base URL                                                            |\n|------------------|---------------------------------------------------------------------|\n| Sandbox          | `https://sandbox.api.service.nhs.uk/prescription-status-update`     |\n| Integration test | `https://int.api.service.nhs.uk/prescription-status-update`         |\n| Production       | `https://api.service.nhs.uk/prescription-status-update`             |\n### Sandbox testing\nOur [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):\n* is for early developer testing\n* only covers a limited set of scenarios\n* is stateless, so it does not actually persist any updates\n* is open access, so does not allow you to test authorisation\nFor details of sandbox testing, or to try out the sandbox using our \"Try this API\" feature, see the documentation for each endpoint.\n### Integration testing\nOur [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):\n* is for formal integration testing\n* is stateful, so persists updates\n* includes authorisation, with [smartcard](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/nhs-smartcards-for-developers) and non-smartcard options\nFor more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).\n## Onboarding\nAll dispenser suppliers are being asked to integrate with this new service.\n","contact":{"name":"Prescription Status Update API Support","url":"https://digital.nhs.uk/developer/help-and-support","email":"api.management@nhs.net"},"version":"v1.16.14-beta"},"servers":[{"url":"https://int.api.service.nhs.uk/prescription-status-update"}],"paths":{"/":{"post":{"summary":"Update prescription status","description":"## Overview\nStatus updates to be provided on prescription items to allow users of the NHS App and third-party app consumers to track the progress of their prescriptions and when ready to collect.\n","operationId":"prescription-status-update-bundle","parameters":[{"name":"Authorization","in":"header","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis).\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"name":"X-Request-ID","in":"header","description":"A globally unique identifier (GUID) for the request, which we use to correlate logs through different components.\nMust be a universally unique identifier (UUID) (ideally version 4).\nMirrored back in a response header.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string","example":"60E0B220-8136-4CA5-AE46-1D97EF59D068"}},{"name":"X-Correlation-ID","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding `.` characters.\nMirrored back in a response header.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}],"requestBody":{"content":{"application/fhir+json":{"schema":{"required":["entry","resourceType","type"],"type":"object","properties":{"resourceType":{"enum":["Bundle"],"type":"string","description":"FHIR resource type."},"type":{"enum":["transaction"],"type":"string","description":"Denotes that the bundle is a list of status updates to be performed as one transaction."},"entry":{"type":"array","items":{"required":["fullUrl","resource","request"],"type":"object","properties":{"fullUrl":{"type":"string","example":"urn:uuid:4d70678c-81e4-4ff4-8c67-17596fd0aa46"},"resource":{"required":["id","resourceType","basedOn","status","businessStatus","intent","focus","for","lastModified","owner"],"type":"object","properties":{"resourceType":{"enum":["Task"],"type":"string"},"id":{"type":"string","description":"The unique identifier for the Task resource.","example":"4d70678c-81e4-4ff4-8c67-17596fd0aa46"},"meta":{"type":"object","properties":{"lastUpdated":{"type":"string","description":"When the resource last changed. This denotes that lastModified of items with status 'Ready to collect' and 'Ready to collect - partial' is a predicted value in the future. Updated predictions to lastModified must have a later value in this property.","format":"date-time","example":"2024-01-30T12:01:24Z","deprecated":true}},"description":"Metadata about the Task resource."},"basedOn":{"type":"array","items":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/prescription-order-number"],"type":"string"},"value":{"type":"string","example":"24F5DA-A83008-7EFE6Z"}}}}},"description":"Short-form Prescription ID for the parent prescription. Should only contain one item."},"status":{"enum":["in-progress","completed"],"type":"string","description":"Indicator to identify when the prescription id status is a terminal status, one for which no further patient action is required. If the prescription item status is a terminal status, the Task.status value must be set to 'completed', otherwise the value must be set to 'in-progress'."},"businessStatus":{"required":["coding"],"type":"object","properties":{"coding":{"type":"array","items":{"required":["system","code"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/CodeSystem/task-businessStatus-nppt"],"type":"string"},"code":{"enum":["With Pharmacy","With Pharmacy - Preparing Remainder","Ready to Collect","Ready to Collect - Partial","Collected","Dispatched","Not Dispensed","Ready to Dispatch","Ready to Dispatch - Partial"],"type":"string"}}}}},"description":"The tracking status for the prescription id. 'With Pharmacy' status updates must be sent for each item in the prescription when the prescription is downloaded from EPS. This is required because not all pharmacies currently support patient prescription tracking. The 'With Pharmacy' status is used as an indicator that the prescription has been downloaded by a pharmacy that does support patient prescription tracking. The 'ready to collect' or 'ready to collect - partial' status updates must only be submitted when the prescription item is ready for the patient to collect, as this may prompt the patient to call into the pharmacy for collection. When the patient has received the prescription item or there are no more actions for the patient, the status value could be 'Collected' or 'Dispatched'. The dispensing system may update the prescription item status with any of the following values to correct a status update which has been made in error or where the status has since reverted: 'With Pharmacy', 'Ready to collect', 'Collected' or 'Dispatched'."},"intent":{"enum":["order"],"type":"string","description":"Order is the allowed value to indicate the update informs an actionable task."},"focus":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/prescription-order-item-number"],"type":"string"},"value":{"type":"string","example":"6989b7bd-8db6-428c-a593-4022e3044c00"}}}},"description":"Identifier for the prescription line item represented by the task resource."},"for":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/nhs-number"],"type":"string"},"value":{"type":"string","example":"9449304130"}}}},"description":"The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number."},"lastModified":{"type":"string","description":"Date and time, specified as UTC value, when the prescription item status was updated. Only the latest last modified date will be displayed to users of the NHS App. This mechanism will be implemented to resolve updates received out of sequence.","format":"date-time","example":"2024-01-30T12:01:24Z"},"owner":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/ods-organization-code"],"type":"string"},"value":{"type":"string","example":"C9Z1O"}}}},"description":"ODS organisation code for the pharmacy that is processing the prescription."},"input":{"type":"array","items":{"required":["type","valueInteger"],"type":"object","properties":{"type":{"required":["text"],"type":"object","properties":{"text":{"enum":["Repeat Number"],"type":"string"}}},"valueInteger":{"maximum":6.0,"minimum":1.0,"type":"integer"}}},"description":"The eRD Repeat Number, with the prescription tracking status updates for eRD prescriptions. This is optional and only required for eRD type prescriptions."}}},"request":{"required":["method","url"],"type":"object","properties":{"method":{"enum":["POST"],"type":"string"},"url":{"enum":["Task"],"type":"string"}}}},"description":"A FHIR collection Bundle."},"description":"A collection of resources contained within the Bundle.\n"}},"description":"A FHIR transaction Bundle."},"examples":{"ready-to-dispatch":{"summary":"ready-to-dispatch","description":"A request message contains tracking status `Ready to Dispatch`.","value":{"$ref":"examples/request-ready-to-dispatch.json"}},"ready-to-dispatch-partial":{"summary":"ready-to-dispatch-partial","description":"A request message contains tracking status `Ready to Dispatch - Partial`.","value":{"$ref":"examples/request-ready-to-dispatch-partial.json"}},"dispatched":{"summary":"dispatched","description":"A request message contains tracking status `Dispatched`.","value":{"$ref":"examples/request-dispatched.json"}},"ready-to-collect":{"summary":"ready-to-collect","description":"A request message contains tracking status `Ready to collect`.","value":{"$ref":"examples/request-ready-to-collect.json"}},"collected":{"summary":"collected","description":"A request message contains tracking status `Collected`.","value":{"$ref":"examples/request-collected.json"}},"multiple-items":{"summary":"multiple-items","description":"A request message contains multiple items.","value":{"$ref":"examples/request-multiple-items.json"}}}}},"required":true},"responses":{"2XX":{"description":"The request was processed successfully. Below are the possible status codes within the 2XX range that may be returned:\n| HTTP status | Status code     | Description                                                                                                                            |\n| ----------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 200         | `success`       | The request was successfully processed.                                                                                                |\n| 201         | `success`       | A new resource was successfully created. No issues detected during validation.                                                         |\n","content":{"application/fhir+json":{"schema":{"required":["resourceType","type","entry"],"type":"object","properties":{"resourceType":{"enum":["Bundle"],"type":"string"},"type":{"enum":["transaction-response"],"type":"string","description":"Denotes that the bundle is a list of responses to status updates performed in the request transaction."},"entry":{"type":"array","items":{"required":["response"],"type":"object","properties":{"response":{"required":["status","outcome"],"type":"object","properties":{"status":{"enum":["201 Created"],"type":"string"},"outcome":{"required":["resourceType","issue"],"type":"object","properties":{"resourceType":{"enum":["OperationOutcome"],"type":"string"},"issue":{"type":"array","items":{"required":["severity","code","diagnostics"],"type":"object","properties":{"severity":{"enum":["information"],"type":"string"},"code":{"enum":["success"],"type":"string"},"diagnostics":{"type":"string","description":"A description of the reasoning for including an OperationOutcome","example":"No issues detected during validation."}}}}}}}}}}}}},"examples":{"single-item":{"description":"A successful response to a UpdatePrescriptionStatus request, contains a single item.","value":{"$ref":"examples/response-single-item.json"}},"multiple-items":{"description":"A successful response to a UpdatePrescriptionStatus request, contains multiple items.","value":{"$ref":"examples/response-multiple-items.json"}}}}}},"4XX":{"description":"An error occurred as follows:\n| HTTP status | Error code          | Description                                                                                                                               |\n| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| 400         | `value`             | Missing values or invalid JSON in request.                                                                                                |\n| 401         | `processing`        | Missing or invalid OAuth 2.0 bearer token in request.                                                                                     |\n| 408         | `timeout`           | Request timed out.                                                                                                                        |\n| 409         | `duplicate`         | Request contains a task ID and prescription ID identical to a record already in the data store.                                           |\n| 429         | `throttled`         | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n\nThe error code will be included in the returned OperationOutcome (below).\n","content":{"application/fhir+json":{"schema":{"required":["resourceType","type","entry"],"type":"object","properties":{"resourceType":{"enum":["Bundle"],"type":"string","description":"The type of resource."},"type":{"enum":["transaction-response"],"type":"string","description":"The type of bundle."},"entry":{"type":"array","items":{"required":["response","fullUrl"],"type":"object","properties":{"response":{"required":["status","outcome"],"type":"object","properties":{"status":{"type":"string","description":"HTTP status code and reason.","example":"400 Bad Request"},"outcome":{"required":["resourceType","meta","issue"],"type":"object","properties":{"resourceType":{"enum":["OperationOutcome"],"type":"string","description":"FHIR Resource Type."},"meta":{"required":["lastUpdated"],"type":"object","properties":{"lastUpdated":{"type":"string","description":"Timestamp at which the response was generated"}},"description":"Metadata regarding the request"},"issue":{"minItems":1,"type":"array","items":{"required":["severity","code"],"type":"object","properties":{"severity":{"enum":["fatal","error","warning","information"],"type":"string","description":"Severity of the error."},"code":{"enum":["business-rule","code-invalid","conflict","deleted","duplicate","exception","expired","extension","forbidden","incomplete","informational","invalid","invariant","lock-error","login","multiple-matches","no-store","not-supported","not-found","processing","required","structure","security","suppressed","throttled","timeout","too-costly","too-long","transient","unknown","value"],"type":"string","description":"FHIR error code."},"details":{"type":"object","properties":{"coding":{"type":"array","items":{"required":["system","code"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"],"type":"string","description":"URI of the coding system specification."},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}},"description":"Internal error code."},"expression":{"type":"string","description":"FHIR Path of element(s) related to the error.","example":"Patient.name.given"},"diagnostics":{"type":"string","description":"A description of the reasoning for including an OperationOutcome","example":"Prescription ID is invalid."}}},"description":"List of issues that have occurred."}},"description":"Outcome details of the operation."}},"description":"Contains the response details for the transaction."},"fullUrl":{"type":"string","description":"A URL or UUID that identifies the full location of the resource.","example":"urn:uuid:3b2d36a9-3cff-45e4-93a7-d1f70f911496"}}},"description":"An array of entry objects, each representing a single response in the transaction-response bundle."}},"description":"Outcome of an operation that does not result in a resource or bundle being returned.\nFor example - error, async/batch submission.\n"},"example":{"resourceType":"Bundle","type":"transaction-response","entry":[{"response":{"status":"400 Bad Request","outcome":{"resourceType":"OperationOutcome","meta":{"lastUpdated":"2024-07-22T23:59:07.673Z"},"issue":[{"code":"value","severity":"error","diagnostics":"Prescription ID is invalid."}]}},"fullUrl":"urn:uuid:3b2d36a9-3cff-45e4-93a7-d1f70f911496"}]}}}},"5XX":{"description":"An error occurred due to a server-side issue. Below are the possible status codes within the 5XX range that may be returned:\n| HTTP status | Error code      | Description                                                                                                 |\n| ----------- | --------------- | ----------------------------------------------------------------------------------------------------------- |\n| 500         | `exception`     | The server has encountered an error processing the request.                                                 |\n| 504         | `timeout`       | The server has timed out while processing the request sent by the client.                                   |\n"}},"deprecated":false,"security":[{"app-level3":[]}]}},"/metadata":{"get":{"summary":"Prescription status update metadata","operationId":"prescription-status-update-metadata","responses":{"200":{"description":"Successful retrieval of metadata."}},"deprecated":false,"security":[{"app-level3":[]}]}},"/checkprescriptionstatusupdates":{"get":{"summary":"Check prescription status updates","description":"## This endpoint is only available in PTL environments\n## Overview\nThis returns prescription status updates created by the authorized application. The result can be filtered by a combination of odscode, nhsnumber or prescription id.\nA maximum of 15 results is returned. If more results are available, then headers LastEvaluatedKey-PrescriptionID and LastEvaluatedKey-TaskID are returned in the result. These values should be used in a subsequent request in the headers ExclusiveStartKey-PrescriptionID and ExclusiveStartKey-TaskID.\nIt is possible that less than 15 results are returned even when more are available. This is a feature of the database and filtering methods being used. At least 5 results will be returned, if available.\n","operationId":"check-prescription-status-updates","parameters":[{"name":"odscode","in":"query","description":"The ods code to return prescription status updates for","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}},{"name":"nhsnumber","in":"query","description":"The nhs number to return prescription status updates for","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}},{"name":"prescriptionid","in":"query","description":"Please ensure that any non-ASCII characters, including symbols like '+', in URL query string parameters are properly URL encoded.\n\nURL encoding replaces unsafe characters with a \"%\" followed by two hexadecimal digits, and spaces are typically replaced with a plus (+) sign or \"%20\".\n\nThe prescription id to return prescription status updates for\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}},{"name":"ExclusiveStartKey-PrescriptionID","in":"header","description":"Used to paginate through results in combination with ExclusiveStartKey-TaskID. When paginated results are available, this should be set to the value of this value of LastEvaluatedKey-PrescriptionID returned in the header of a previous request","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}},{"name":"ExclusiveStartKey-TaskID","in":"header","description":"Used to paginate through results in combination with ExclusiveStartKey-PrescriptionID. When paginated results are available, this should be set to the value of this value of LastEvaluatedKey-TaskID returned in the header of a previous request","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful retrieval of prescription-status-updates.","headers":{"LastEvaluatedKey-PrescriptionID":{"name":"","in":"header","description":"The value of this header should be used in subsequent requests in the header ExclusiveStartKey-PrescriptionID. If not present, there are no more results available.","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}},"LastEvaluatedKey-TaskID":{"name":"","in":"header","description":"The value of this header should be used in subsequent requests in the header ExclusiveStartKey-TaskID. If not present, there are no more results available.","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"required":["items"],"type":"object","properties":{"items":{"minItems":0,"type":"array","items":{"required":["ApplicationName","RequestID","LastModified","TerminalStatus","PharmacyODSCode","Status","TaskID","PatientNHSNumber","LineItemID","PrescriptionID"],"type":"object","properties":{"ApplicationName":{"type":"string","description":"The application name that sent the update."},"RequestID":{"type":"string","description":"The requestID sent in the update."},"LastModified":{"type":"string","description":"The LastModified date sent in the update."},"TerminalStatus":{"type":"string","description":"The TerminalStatus sent in the update."},"PharmacyODSCode":{"type":"string","description":"The ODS code sent in the update."},"Status":{"type":"string","description":"The status sent in the update."},"TaskID":{"type":"string","description":"The TaskID sent in the update."},"PatientNHSNumber":{"type":"string","description":"The patient NHS number sent in the update."},"LineItemID":{"type":"string","description":"The LineItemId sent in the update."},"PrescriptionID":{"type":"string","description":"The prescriptionID sent in the update."}}},"description":"List of prescription status updates that have been sent."}},"description":"Prescription Status Update details that have been sent to the Prescription Status Update endpoint\n"},"examples":{"single-item":{"description":"A successful response to a checkprescriptionstatusupdates request.","value":{"$ref":"examples/response-checkprescriptionstatusupdates.json"}}}}}},"4XX":{"description":"An error occurred as follows:\n| HTTP status | Error code          | Description                                                                                                                               |\n| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| 401         | `processing`        | Missing or invalid OAuth 2.0 bearer token in request                                                                                      |\n| 408         | `timeout`           | Request timed out                                                                                                                         |\n| 429         | `throttled`         | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n"}},"deprecated":false,"security":[{"app-level3":[]}]}},"/notification-delivery-status-callback":{"post":{"summary":"Internal: Prescription status update notification delivery status callback","description":"## This endpoint is for internal usage only\n## Overview\nThis endpoint provides a callback for the NHS notifications service to update the\nPrescription Status Update API on the delivery status of requested notifications.\n\nPlease refer to [their documentation](https://digital.nhs.uk/developer/api-catalogue/nhs-notify#post-/%3Cclient-provided-message-status-URI%3E) for more detail on the request schema.\n","operationId":"prescription-status-update-notification-delivery-status-callback","parameters":[{"name":"x-hmac-sha256-signature","in":"header","description":"Contains a HMAC-SHA256 signature of the request body using a pre-agreed secret.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"9ee8c6aab877a97600e5c0cd8419f52d3dcdc45002e35220873d11123db6486f"}],"responses":{"202":{"description":"Successfully updated notification delivery status"},"4XX":{"description":"An error occurred as follows:\n| HTTP status | Error code          | Description                                                                                                                               |\n| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| 401         | `unauthorised`      | Missing or invalid OAuth 2.0 bearer token in request                                                                                      |\n| 403         | `forbidden`         | Supplied signature was incorrect.                                                                                                         |\n| 429         | `throttled`         | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n"}},"deprecated":false,"security":[{"app-level0":[]}]}}},"components":{"schemas":{"UpdatePrescriptionStatusBundle":{"required":["entry","resourceType","type"],"type":"object","properties":{"resourceType":{"enum":["Bundle"],"type":"string","description":"FHIR resource type."},"type":{"enum":["transaction"],"type":"string","description":"Denotes that the bundle is a list of status updates to be performed as one transaction."},"entry":{"type":"array","items":{"required":["fullUrl","resource","request"],"type":"object","properties":{"fullUrl":{"type":"string","example":"urn:uuid:4d70678c-81e4-4ff4-8c67-17596fd0aa46"},"resource":{"required":["id","resourceType","basedOn","status","businessStatus","intent","focus","for","lastModified","owner"],"type":"object","properties":{"resourceType":{"enum":["Task"],"type":"string"},"id":{"type":"string","description":"The unique identifier for the Task resource.","example":"4d70678c-81e4-4ff4-8c67-17596fd0aa46"},"meta":{"type":"object","properties":{"lastUpdated":{"type":"string","description":"When the resource last changed. This denotes that lastModified of items with status 'Ready to collect' and 'Ready to collect - partial' is a predicted value in the future. Updated predictions to lastModified must have a later value in this property.","format":"date-time","example":"2024-01-30T12:01:24Z","deprecated":true}},"description":"Metadata about the Task resource."},"basedOn":{"type":"array","items":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/prescription-order-number"],"type":"string"},"value":{"type":"string","example":"24F5DA-A83008-7EFE6Z"}}}}},"description":"Short-form Prescription ID for the parent prescription. Should only contain one item."},"status":{"enum":["in-progress","completed"],"type":"string","description":"Indicator to identify when the prescription id status is a terminal status, one for which no further patient action is required. If the prescription item status is a terminal status, the Task.status value must be set to 'completed', otherwise the value must be set to 'in-progress'."},"businessStatus":{"required":["coding"],"type":"object","properties":{"coding":{"type":"array","items":{"required":["system","code"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/CodeSystem/task-businessStatus-nppt"],"type":"string"},"code":{"enum":["With Pharmacy","With Pharmacy - Preparing Remainder","Ready to Collect","Ready to Collect - Partial","Collected","Dispatched","Not Dispensed","Ready to Dispatch","Ready to Dispatch - Partial"],"type":"string"}}}}},"description":"The tracking status for the prescription id. 'With Pharmacy' status updates must be sent for each item in the prescription when the prescription is downloaded from EPS. This is required because not all pharmacies currently support patient prescription tracking. The 'With Pharmacy' status is used as an indicator that the prescription has been downloaded by a pharmacy that does support patient prescription tracking. The 'ready to collect' or 'ready to collect - partial' status updates must only be submitted when the prescription item is ready for the patient to collect, as this may prompt the patient to call into the pharmacy for collection. When the patient has received the prescription item or there are no more actions for the patient, the status value could be 'Collected' or 'Dispatched'. The dispensing system may update the prescription item status with any of the following values to correct a status update which has been made in error or where the status has since reverted: 'With Pharmacy', 'Ready to collect', 'Collected' or 'Dispatched'."},"intent":{"enum":["order"],"type":"string","description":"Order is the allowed value to indicate the update informs an actionable task."},"focus":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/prescription-order-item-number"],"type":"string"},"value":{"type":"string","example":"6989b7bd-8db6-428c-a593-4022e3044c00"}}}},"description":"Identifier for the prescription line item represented by the task resource."},"for":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/nhs-number"],"type":"string"},"value":{"type":"string","example":"9449304130"}}}},"description":"The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number."},"lastModified":{"type":"string","description":"Date and time, specified as UTC value, when the prescription item status was updated. Only the latest last modified date will be displayed to users of the NHS App. This mechanism will be implemented to resolve updates received out of sequence.","format":"date-time","example":"2024-01-30T12:01:24Z"},"owner":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/ods-organization-code"],"type":"string"},"value":{"type":"string","example":"C9Z1O"}}}},"description":"ODS organisation code for the pharmacy that is processing the prescription."},"input":{"type":"array","items":{"required":["type","valueInteger"],"type":"object","properties":{"type":{"required":["text"],"type":"object","properties":{"text":{"enum":["Repeat Number"],"type":"string"}}},"valueInteger":{"maximum":6.0,"minimum":1.0,"type":"integer"}}},"description":"The eRD Repeat Number, with the prescription tracking status updates for eRD prescriptions. This is optional and only required for eRD type prescriptions."}}},"request":{"required":["method","url"],"type":"object","properties":{"method":{"enum":["POST"],"type":"string"},"url":{"enum":["Task"],"type":"string"}}}},"description":"A FHIR collection Bundle."},"description":"A collection of resources contained within the Bundle.\n"}},"description":"A FHIR transaction Bundle."},"UpdatePrescriptionStatusTask":{"required":["id","resourceType","basedOn","status","businessStatus","intent","focus","for","lastModified","owner"],"type":"object","properties":{"resourceType":{"enum":["Task"],"type":"string"},"id":{"type":"string","description":"The unique identifier for the Task resource.","example":"4d70678c-81e4-4ff4-8c67-17596fd0aa46"},"meta":{"type":"object","properties":{"lastUpdated":{"type":"string","description":"When the resource last changed. This denotes that lastModified of items with status 'Ready to collect' and 'Ready to collect - partial' is a predicted value in the future. Updated predictions to lastModified must have a later value in this property.","format":"date-time","example":"2024-01-30T12:01:24Z","deprecated":true}},"description":"Metadata about the Task resource."},"basedOn":{"type":"array","items":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/prescription-order-number"],"type":"string"},"value":{"type":"string","example":"24F5DA-A83008-7EFE6Z"}}}}},"description":"Short-form Prescription ID for the parent prescription. Should only contain one item."},"status":{"enum":["in-progress","completed"],"type":"string","description":"Indicator to identify when the prescription id status is a terminal status, one for which no further patient action is required. If the prescription item status is a terminal status, the Task.status value must be set to 'completed', otherwise the value must be set to 'in-progress'."},"businessStatus":{"required":["coding"],"type":"object","properties":{"coding":{"type":"array","items":{"required":["system","code"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/CodeSystem/task-businessStatus-nppt"],"type":"string"},"code":{"enum":["With Pharmacy","With Pharmacy - Preparing Remainder","Ready to Collect","Ready to Collect - Partial","Collected","Dispatched","Not Dispensed","Ready to Dispatch","Ready to Dispatch - Partial"],"type":"string"}}}}},"description":"The tracking status for the prescription id. 'With Pharmacy' status updates must be sent for each item in the prescription when the prescription is downloaded from EPS. This is required because not all pharmacies currently support patient prescription tracking. The 'With Pharmacy' status is used as an indicator that the prescription has been downloaded by a pharmacy that does support patient prescription tracking. The 'ready to collect' or 'ready to collect - partial' status updates must only be submitted when the prescription item is ready for the patient to collect, as this may prompt the patient to call into the pharmacy for collection. When the patient has received the prescription item or there are no more actions for the patient, the status value could be 'Collected' or 'Dispatched'. The dispensing system may update the prescription item status with any of the following values to correct a status update which has been made in error or where the status has since reverted: 'With Pharmacy', 'Ready to collect', 'Collected' or 'Dispatched'."},"intent":{"enum":["order"],"type":"string","description":"Order is the allowed value to indicate the update informs an actionable task."},"focus":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/prescription-order-item-number"],"type":"string"},"value":{"type":"string","example":"6989b7bd-8db6-428c-a593-4022e3044c00"}}}},"description":"Identifier for the prescription line item represented by the task resource."},"for":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/nhs-number"],"type":"string"},"value":{"type":"string","example":"9449304130"}}}},"description":"The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number."},"lastModified":{"type":"string","description":"Date and time, specified as UTC value, when the prescription item status was updated. Only the latest last modified date will be displayed to users of the NHS App. This mechanism will be implemented to resolve updates received out of sequence.","format":"date-time","example":"2024-01-30T12:01:24Z"},"owner":{"required":["identifier"],"type":"object","properties":{"identifier":{"required":["system","value"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/Id/ods-organization-code"],"type":"string"},"value":{"type":"string","example":"C9Z1O"}}}},"description":"ODS organisation code for the pharmacy that is processing the prescription."},"input":{"type":"array","items":{"required":["type","valueInteger"],"type":"object","properties":{"type":{"required":["text"],"type":"object","properties":{"text":{"enum":["Repeat Number"],"type":"string"}}},"valueInteger":{"maximum":6.0,"minimum":1.0,"type":"integer"}}},"description":"The eRD Repeat Number, with the prescription tracking status updates for eRD prescriptions. This is optional and only required for eRD type prescriptions."}}},"ResponseBundle":{"required":["resourceType","type","entry"],"type":"object","properties":{"resourceType":{"enum":["Bundle"],"type":"string"},"type":{"enum":["transaction-response"],"type":"string","description":"Denotes that the bundle is a list of responses to status updates performed in the request transaction."},"entry":{"type":"array","items":{"required":["response"],"type":"object","properties":{"response":{"required":["status","outcome"],"type":"object","properties":{"status":{"enum":["201 Created"],"type":"string"},"outcome":{"required":["resourceType","issue"],"type":"object","properties":{"resourceType":{"enum":["OperationOutcome"],"type":"string"},"issue":{"type":"array","items":{"required":["severity","code","diagnostics"],"type":"object","properties":{"severity":{"enum":["information"],"type":"string"},"code":{"enum":["success"],"type":"string"},"diagnostics":{"type":"string","description":"A description of the reasoning for including an OperationOutcome","example":"No issues detected during validation."}}}}}}}}}}}}},"OperationOutcome":{"required":["resourceType","type","entry"],"type":"object","properties":{"resourceType":{"enum":["Bundle"],"type":"string","description":"The type of resource."},"type":{"enum":["transaction-response"],"type":"string","description":"The type of bundle."},"entry":{"type":"array","items":{"required":["response","fullUrl"],"type":"object","properties":{"response":{"required":["status","outcome"],"type":"object","properties":{"status":{"type":"string","description":"HTTP status code and reason.","example":"400 Bad Request"},"outcome":{"required":["resourceType","meta","issue"],"type":"object","properties":{"resourceType":{"enum":["OperationOutcome"],"type":"string","description":"FHIR Resource Type."},"meta":{"required":["lastUpdated"],"type":"object","properties":{"lastUpdated":{"type":"string","description":"Timestamp at which the response was generated"}},"description":"Metadata regarding the request"},"issue":{"minItems":1,"type":"array","items":{"required":["severity","code"],"type":"object","properties":{"severity":{"enum":["fatal","error","warning","information"],"type":"string","description":"Severity of the error."},"code":{"enum":["business-rule","code-invalid","conflict","deleted","duplicate","exception","expired","extension","forbidden","incomplete","informational","invalid","invariant","lock-error","login","multiple-matches","no-store","not-supported","not-found","processing","required","structure","security","suppressed","throttled","timeout","too-costly","too-long","transient","unknown","value"],"type":"string","description":"FHIR error code."},"details":{"type":"object","properties":{"coding":{"type":"array","items":{"required":["system","code"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"],"type":"string","description":"URI of the coding system specification."},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}},"description":"Internal error code."},"expression":{"type":"string","description":"FHIR Path of element(s) related to the error.","example":"Patient.name.given"},"diagnostics":{"type":"string","description":"A description of the reasoning for including an OperationOutcome","example":"Prescription ID is invalid."}}},"description":"List of issues that have occurred."}},"description":"Outcome details of the operation."}},"description":"Contains the response details for the transaction."},"fullUrl":{"type":"string","description":"A URL or UUID that identifies the full location of the resource.","example":"urn:uuid:3b2d36a9-3cff-45e4-93a7-d1f70f911496"}}},"description":"An array of entry objects, each representing a single response in the transaction-response bundle."}},"description":"Outcome of an operation that does not result in a resource or bundle being returned.\nFor example - error, async/batch submission.\n"},"CheckPrescriptionStatusUpdates":{"required":["items"],"type":"object","properties":{"items":{"minItems":0,"type":"array","items":{"required":["ApplicationName","RequestID","LastModified","TerminalStatus","PharmacyODSCode","Status","TaskID","PatientNHSNumber","LineItemID","PrescriptionID"],"type":"object","properties":{"ApplicationName":{"type":"string","description":"The application name that sent the update."},"RequestID":{"type":"string","description":"The requestID sent in the update."},"LastModified":{"type":"string","description":"The LastModified date sent in the update."},"TerminalStatus":{"type":"string","description":"The TerminalStatus sent in the update."},"PharmacyODSCode":{"type":"string","description":"The ODS code sent in the update."},"Status":{"type":"string","description":"The status sent in the update."},"TaskID":{"type":"string","description":"The TaskID sent in the update."},"PatientNHSNumber":{"type":"string","description":"The patient NHS number sent in the update."},"LineItemID":{"type":"string","description":"The LineItemId sent in the update."},"PrescriptionID":{"type":"string","description":"The prescriptionID sent in the update."}}},"description":"List of prescription status updates that have been sent."}},"description":"Prescription Status Update details that have been sent to the Prescription Status Update endpoint\n"},"SpineErrorOrWarningCode":{"required":["system","code"],"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"],"type":"string","description":"URI of the coding system specification."},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}},"parameters":{"ApiKey":{"name":"apikey","in":"header","description":"Contains the pre-agreed API key.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"0bb04a0e-d005-42dd-8993-dacf37410a12"}},"BearerAuthorisation":{"name":"Authorization","in":"header","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis).\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},"RequestID":{"name":"X-Request-ID","in":"header","description":"A globally unique identifier (GUID) for the request, which we use to correlate logs through different components.\nMust be a universally unique identifier (UUID) (ideally version 4).\nMirrored back in a response header.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string","example":"60E0B220-8136-4CA5-AE46-1D97EF59D068"}},"CorrelationID":{"name":"X-Correlation-ID","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding `.` characters.\nMirrored back in a response header.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"securitySchemes":{"app-level0":{"$ref":"https://proxygen.ptl.api.platform.nhs.uk/components/securitySchemes/app-level0"},"app-level3":{"$ref":"https://proxygen.ptl.api.platform.nhs.uk/components/securitySchemes/app-level3"}}},"security":[{"app-level3":[]},{"app-level0":[]}],"x-nhsd-apim":{"target-attributes":[{"name":"name","required":false,"header":"attribute-name"},{"name":"show-all-suppliers","required":false,"header":"show-all-suppliers"},{"name":"id","required":false,"header":"nhsd-application-id"}],"target":{"type":"external","healthcheck":"/_status","url":"https://psu.int.eps.national.nhs.uk","security":{"type":"mtls","secret":"psu-mtls-1"}},"access":[{"title":"Application Restricted","grants":{"app-level3":[]},"visible":true},{"title":"API Key Restricted","grants":{"app-level0":[]},"visible":true}],"ratelimiting":{"proxy":{"timeunit":"minute","limit":20000},"app-default":{"timeunit":"minute","limit":20000}},"monitoring":true,"temporary":false,"depflag":false,"productidcheck":false},"x-spec-publication":{"operation-order":[{"operations":[{"method":"GET","path":"/Bundle"}]}]}}