{"openapi":"3.0.3","info":{"title":"Custom Prescription Status Update API","description":"## Overview\nThe Custom Prescription Status Update API is restricted to dispensing suppliers with an existing prescription\nstatus update solution, who can onboard to provide updates to patients on a national scale via the NHS App\n(and other third parties in the future) by September 2024.\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 Custom Prescription Status Update API is intended for those dispensing suppliers who have signed the MOU to\nsupply status updates by September 2024, so they can provide and push the information required to a central NHS data store.\n## Related APIs\nThe following APIs are related to the \"Custom 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 development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning the API will soon be available for testing via a sandbox service or an integration environment - but we expect to make breaking changes based on developer feedback.\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).\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-restful-apis-api-key-authentication), 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\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\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/custom-prescription-status-update`     |\n| Integration test | `https://int.api.service.nhs.uk/custom-prescription-status-update`         |\n| Production       | `https://api.service.nhs.uk/custom-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":"Custom 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/custom-prescription-status-update"}],"paths":{"/format-1":{"post":{"summary":"Format 1 update prescription status","description":"## Overview\nStatus updates will 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":"format-1-prescription-status-update","parameters":[{"name":"API-KEY","in":"header","description":"API Key used to authenticate with the system\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}],"requestBody":{"content":{"application/json":{"examples":{"multiple-items":{"summary":"multiple-items","description":"A request message contains multiple items.","value":{"$ref":"examples/format-1-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| 202         | `informational` | The request was accepted, but no change occurred due to a duplicate update.                                 |\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.","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-level0":[]}]}}},"components":{"schemas":{"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"},"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":"API-KEY","in":"header","description":"API Key used to authenticate with the system\n","required":true,"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-level0":[]}],"x-nhsd-apim":{"target-attributes":[{"name":"DisplayName","required":true,"header":"attribute-name"}],"target":{"type":"external","healthcheck":"/_status","url":"https://psu.int.eps.national.nhs.uk","security":{"type":"mtls","secret":"psu-mtls-1"}},"access":[{"title":"Application Restricted with API key","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}}