{"openapi":"3.0.0","info":{"contact":{"email":"ssd.nationalservicedesk@nhs.net","name":"API Management Support"},"description":"## Overview\nUse this API to submit ambulance data to our Data Processing Service (DPS) so that it can be made available for analysis and review by NHS England and ambulance trusts.\n\nAmbulance data is information relating to emergency calls (999, 111 and others), received at an Emergency Operations Centre (EOC) and processed into a Computer Aided Despatch (CAD) system, including:\n  - call details\n  - response details - including response times and episode outcome times patient\n  - contact details - including patient demographics, patient response details, patient information, injury information, patient assessment, medication, observations, diagnoses, conveying outcome, safeguarding and public health information\n\nYou can:\n  - post ambulance data individually or in batches\n\nYou cannot:\n  - read any of the records stored in DPS\n\nThe API is asynchronous - when you submit data, it acknowledges receipt without validating or processing the data first. To receive error notifications, you need to use [MESH](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh). The following diagram illustrates the end-to-end process:\n\n![Ambulance Overview](https://github.com/NHSDigital/ambulance-analytics-api/blob/master/specification/diagrams/ADSOverview2.svg?raw=true)\n\nThe following describes the end-to-end process:\n1. The ambulance trust system sends the ambulance data to the Ambulance Data Submission API.\n2. The Ambulance Data Submission (ADS) API forwards the ambulance data to our Data Processing System (DPS).\n3. If there is an error, DPS sends an error notification to MESH.\n4. The ambulance trust system retrieves the error notification from MESH.\n5. An ADS User views the ambulance data in our ADS Dashboards.\n6. The ADS Dashboards get the ambulance data from DPS.\n\n## Who can use this API\nThis API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. You must do this before you can go live (see ‘Onboarding’ below).\n\n## Related APIs\nThe following API is related to this one:\n* [Messaging Exchange for Social care and Health (MESH)](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh) - use this API to receive error notifications from DPS\n\n## API status and roadmap\nThis API is [in production](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\n\nTo see our roadmap, or to suggest, comment or vote on features for this API, see our [interactive product backlog](https://nhs-digital-api-management.featureupvote.com/?order=popular&filter=allexceptdone&tag=ambulance-analytics&deleted=0#controls).\n\nIf you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support).\n\n## Service level\nThis API is a bronze service, meaning it is operational and supported only during business hours (8am to 6pm), Monday to Friday excluding bank holidays.\n\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Technology\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest) and uses HTTP POST to submit data.\n\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/), except that it does not support the [capabilities](http://hl7.org/fhir/R4/http.html#capabilities) interaction.\n\nIt includes some country-specific FHIR extensions, which are built against [FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core), specifically [UK.core.r4.v2/2.0.8](https://simplifier.net/packages/uk.core.r4.v2/2.0.8).\n\nFor details of FHIR message payload, see the [Ambulance Data Set FHIR Implementation Guide](https://simplifier.net/guide/ambulancedatasetadsfhirbundleimplementationguide?version=current).\n\n## Network access\nThis API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network).\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\n### Application-restricted access\nThis API is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis),\nmeaning we authenticate the calling application but not the end user.\n\nYou can use this access mode as follows:\n* unattended (end user not present), for example periodically submit ambulance data from ambulance trust systems to DPS\n\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\n## Environments and testing\n\n### Sandbox testing\n\n|Environment        | Base URL                                                           |\n| ----------------- | -------------------------------------------------------------------|\n| Sandbox           | `https://sandbox.api.service.nhs.uk/ambulance-data-submission/`    |\n| Integration test  | `https://int.api.service.nhs.uk/ambulance-data-submission/`        |\n\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\n\nFor more details on sandbox testing, or to try out the sandbox using our \"Try this API\" feature, see the documentation for each endpoint.\n\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 for receiving data quality reports of test data\n\n## Onboarding\n\nYou need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.\n\nTo onboard for this API, follow the [Supplier Conformance Assessment List](https://digital.nhs.uk/developer/guides-and-documentation/onboarding-process#onboard-using-the-supplier-conformance-assessment-list-scal-process) (SCAL) process.\n\nWhen following the SCAL process, note that:\n\n* In step 8: you need to review and complete the ADS API risk log to show that you have understood and mitigated the various risks. You might be asked to provide some evidence to prove that controls have been put in place. You’ll find the risk log embedded within the ADS API tab in the SCAL.\n* In step 10: when you complete the Service Desk Registration Form, send it to [ssd.nationalservicedesk@nhs.net](mailto:ssd.nationalservicedesk@nhs.net).\n* In step 11: submit your completed SCAL to [ssd.nationalservicedesk@nhs.net](mailto:ssd.nationalservicedesk@nhs.net).\n* In step 14: to request production access, contact us at [ssd.nationalservicedesk@nhs.net](mailto:ssd.nationalservicedesk@nhs.net).\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\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","title":"Ambulance Data Submission - FHIR API","version":"v1.0.450-alpha"},"servers":[{"description":"Sandbox environment.","url":"https://sandbox.api.service.nhs.uk/ambulance-data-submission"}],"paths":{"/$process-message":{"post":{"description":"## Overview\nUse this endpoint to submit ambulance data to DPS.\n## Request\nThis endpoint does not validate the submitted payload, it only acknowledges receipt of the payload.\nSee the [FHIR implementation guide](https://simplifier.net/guide/ambulancedatasetadsfhirbundleimplementationguide?version=current) for how to structure the payload data.\n","operationId":"postData","parameters":[],"responses":{"200":{"content":{"application/json":{"examples":{"Example":{"value":{"message":"6eeec54e-3d39-4bc4-a1d9-57615d258fpq"}}},"schema":{"$ref":"#/components/schemas/postData_200_response"}}},"description":"Data received and sent to DPS."}},"summary":"Submit Ambulance Data"}}},"components":{"schemas":{"postData_200_response":{"properties":{"message":{"description":"The submission ID for the message you sent.","type":"string"}},"type":"object"}},"securitySchemes":{}}}