mesh-api.yaml

openapi: 3.0.2
info:
  title: Message Exchange for Social Care and Health - REST API
  description: |-
    ## Overview

    You interact with MESH by making calls to this API from your application.

    With the API, you can:

    - check the number of messages in your inbox
    - send a message, or a larger message as series of chunks
    - download a message, or a larger message which was sent to you as a series of chunks
    - acknowledge the successful download of a message, which removes it from your inbox
    - get the identifiers of messages in your inbox that are ready for download
    - track the status of messages that you sent from your outbox
    - look up the mailbox of an organisation you want to send data to
    - validate your mailbox every 24 hours to let Spine know it's still active

    ## Who can use this API

    This API can only be used where there is a legal basis to do so. We'll ask you to demonstrate this as part of the digital onboarding process before your software goes live.

    ## Requirements for using this API
    There are 2 parts to getting the MESH API, these are:

    1. developing and integrating your software
    2. getting your software approved to go live

    ### 1. Developing and integrating your software

    You'll need some things at different stages of your development to integrate with the MESH API.
    For each environment you use, you'll need a:
    - MESH mailbox ID and password
    - Transport Layer Security (TLS) certificate
    - shared secret to include in the MESH authorization header

    ### 2. Getting your software approved to go live

    This is also called digital onboarding. You'll need to submit information that demonstrates:
    - you have a valid use case
    - you can manage risks
    - your software conforms technically with the requirements for this API

    ## End-to-end process to integrate with MESH API

    The length of time it takes to get your software live depends on the resources your organisation puts into:
    - developing your software
    - getting things you need for your integration like TLS certificates
    - completing onboarding processes and waiting for approval

    You can do some things while you wait, but expect the end-to-end integration process to take 1 month or more.

    ### Get started

    To get started, sign in or create a developer account for digital onboarding, complete the 'Setup and eligibility' section and submit it.

    If you're new to digital onboarding, add your product and select 'MESH' from the 'APIs to be used' list.
    Submitting this information shows us that you have a legal basis to use the MESH API. We'll review the information you submit and respond within 5 to 10 working days.

    If we approve your request to use the MESH API, we'll also email you a supplier pack within 10 working days. Read through this as it contains the testing requirements you'll need to fulfil later on.

    You should get your use case approved before you go too far with development. You can choose to proceed with your integration while you wait for approval, but you'll be doing this at your own risk.

     [Sign in or create a developer account for digital onboarding](https://onboarding.prod.api.platform.nhs.uk)


    You will receive a response within 10 working days.

    If you have been approved to use the MESH API, our assurance team will contact you via email with a supplier pack containing the testing requirements you will need to fulfill. You will work alongside this team to get your solution assured.

    ### Request a mailbox

    Once we've approved your request to use the MESH API, you'll need to request a MESH Mailbox to use in a 'Path to Live integration environment'. This is how you'll interact with the MESH API. A MESH Mailbox is secure and only your organisation can access it.

    To request a MESH Mailbox, you'll need to fill in an online form. It takes 5 to 10 minutes to complete.

    You'll need to know:
    - your [ODS code](https://odsportal.digital.nhs.uk/)
    - the [workflow groups or IDs](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/workflow-groups-and-workflow-ids) for the files you plan to send or receive
    - the contact details of the person who will be managing the mailbox in your organisation

    [Request a 'Path to Live integration' MESH Mailbox](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/messaging-exchange-for-social-care-and-health-apply-for-a-mailbox)

    ### Receive your credentials for the 'Path to Live integration' environment

    Once you've requested a MESH Mailbox, we will email you your Mailbox ID and password within 5 working days. Keep these details safe as we'll also ask you for this if you need help from our support teams.

    You will also receive the shared secret. You'll need to include this in the [MESH authorization header](#overview--mesh-authorization-header) when you develop this part of your software.

    ### Get a TLS certificate

    You'll need a TLS certificate to establish a secure connection to MESH.

    How to get a TLS certificate

    1. Generate a private key using your preferred method, with the naming convention cn=mailboxid.odscode.api.mesh-client.nhs.uk
    2. Generate a certificate signing request (CSR) based on the private key and your Mailbox ID.
    3. Email the CSR to [itoc.supportdesk@nhs.net](mailto:itoc.supportdesk@nhs.net) - this needs to contain the common name from your CSR 'Subject' using the format local_id.ods_code.api.mesh-client.nhs.uk

    The local_id is a local identifier such as a server name and ods_code is your ODS code, for example, SERVER001.X26.api.mesh-client.nhs.uk.

    Once we receive your CSR, we'll send you a TLS certificate within 5 working days.

    Depending on how you implement MESH API, you may also need to [download a RootCA and SubCA certificate](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates). These are also required to establish a secure connection.

    ### Develop and test your software

    Now that you have a MESH Mailbox for a 'Path to Live integration' environment and a TLS certificate, start developing your software using the MESH API.

    When you're ready to go live, you'll need to:
    - request a TLS certificate for the production environment
    - request a MESH mailbox for the production environment
    - get a conformance certificate
    - sign a connection agreement

    ### Submit non-functional requirements

    Once you've developed your software, you'll need to answer some questions in digital onboarding about the processes you use for:
    - handling data securely
    - managing clinical risk
    - using our production environment

    This shows that your software meets our non-functional requirements.

    [Sign in to the digital onboarding to answer questions on 'non-functional' requirements](https://onboarding.prod.api.platform.nhs.uk)

    ### Demonstrate technical conformance

    Before you can go live, in digital onboarding, you'll need to:
    - answer some questions to show you conform to the technical requirements of our APIs
    - upload a conformance certificate

    To get a technical conformance certificate, you'll need to complete the testing requirements in the supplier pack we sent to you.

    Some of these tests have to be witnessed by us. To arrange a witness test, reply to the email that contains the supplier pack. The witness testing takes 2 to 3 hours.

    In some cases, we may ask you to prepare test data a few days before the day of the witness testing.

    When you've completed a witness test, we'll email a technical conformance certificate to you within 5 working days. You can then upload it to digital onboarding.

    [Sign in to the digital onboarding to upload a technical conformance certificate](https://onboarding.prod.api.platform.nhs.uk)

    ### Get a MESH Mailbox for your live software

    When you're ready to send or receive real data, you'll need a MESH Mailbox in the production environment. We'll ask to see the conformance certificate for your software before we issue this.

    MESH Mailboxes are specific to environments, this means you'll need a different MESH Mailbox ID for each environment you use.

    To request a MESH Mailbox, you'll need to fill in an online form. It takes 5 to 10 minutes to complete.

    You'll need to know:
    - your [ODS code](https://odsportal.digital.nhs.uk/)
    - the [workflow groups or IDs](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/workflow-groups-and-workflow-ids) for the files you plan to send or receive
    - the contact details of the person who will be managing the mailbox in your organisation

    [Request a 'Live' MESH Mailbox](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/messaging-exchange-for-social-care-and-health-apply-for-a-mailbox)

    ### Get a TLS certificate for the production environment

    Once you have a Mailbox ID, you'll need to get a TLS certificate. This allows you to establish a secure connection to MESH in the production environment.

    How to get a TLS certificate
    1. Generate a private key using your preferred method, with the naming convention cn=mailboxid.odscode.api.mesh-client.nhs.uk
    2. Generate a CSR based on the private key and your Mailbox ID
    3. Email the CSR and technical conformance certificate to [ssd.nationalservicedesk@nhs.net](mailto:ssd.nationalservicedesk@nhs.net) - this needs to contain the common name from your CSR 'Subject' using the format local_id.ods_code.api.mesh-client.nhs.uk

    The local_id is a local identifier such as a server name and ods_code is your ODS code, for example, SERVER001.X26.api.mesh-client.nhs.uk.

    Once we receive your CSR and technical conformance certificate, we'll send you a TLS certificate for the production environment within 5 working days.

    Depending on how you implement MESH API, you may also need to [download a RootCA and SubCA certificate](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates). These are also required to establish a secure connection.


    ### Sign connection agreement

    You'll need to sign a connection agreement before your software can go live. Once you've signed it, you need to upload it to the 'Legal agreement' section in digital onboarding. We'll email your connection agreement to you within 5 working days of completing your witness test.

    [Sign in to the digital onboarding to upload your connection agreement](https://onboarding.prod.api.platform.nhs.uk)

    ### Go live with your software

    You have now completed all integration and onboarding steps. This means you can use the MESH API with your live software.

    ## Related APIs
    A number of our APIs are messaging APIs that use MESH as the transport layer. For a full list, see [our API catalogue, filtered on MESH APIs](https://digital.nhs.uk/developer/api-catalogue?filter=mesh).

    In particular, this includes [National Event Management Service - FHIR API](https://digital.nhs.uk/developer/api-catalogue/national-events-management-service-fhir) -
    our API for publishing and subscribing to healthcare events such as updates to patient demographic details.

    ## API status and roadmap
    This API is [in production](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).

    ## Service level
    This API is a platinum service, meaning it is operational and supported 24 hours a day, 365 days a year.

    For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).

    ## Technology
    This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest).

    ## Network access
    This API is available on the internet.

    For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).

    ## Errors
    We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

    * 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
    * 400 to 499 if it failed because of a client error by your application
    * 500 to 599 if it failed because of an error on our server

    Errors 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.

    ## Open source
    We have a number of open source resources that you might find useful:

    | Resource                   | Description                                                                                                                                                                    | Links                                                                                                                                                  |
    |----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
    | MESH sandbox               | For early developer testing, a realistic MESH experience that runs locally in docker or as an embedded python package. For more details, see 'Environments and testing' below. | [GitHub repo](https://github.com/NHSDigital/mesh-sandbox) \| [Python Package Index](https://pypi.org/project/mesh-sandbox/)                            |
    | MESH Python client         | A fully-featured Python client library that conforms to our technical integration requirements. This is not the same as the MESH Java client.                                  | [GitHub repo](https://github.com/NHSDigital/mesh-client) \| [Python Package Index](https://pypi.org/project/Mesh-Client)                               |
    | MESH AWS Serverless client | A fully-featured MESH client built using terraform and AWS serverless components.                                                                                              | [GitHub repo](https://github.com/NHSDigital/terraform-aws-mesh-client)                                                                                 |
    | MESH Validate Auth Header  | A tool for validating the construction of the MESH authentication token.                                                                                                       | [GitHub repo](https://github.com/NHSDigital/mesh_validate_auth_header) \| [GitHub pages UI](https://nhsdigital.github.io/mesh_validate_auth_header/#/) |


    For more details, see [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source).

    ## Environments and testing
    There are multiple externally accessible instances of MESH that can be used for testing, each with a different root URL.


    | Purpose       | Network availability | URL                                       |
    |---------------|----------------------|-------------------------------------------|
    | Integration   | Internet             | `https://msg.intspineservices.nhs.uk/`    |
    | Production    | Internet             | `https://mesh-sync.spineservices.nhs.uk/` |

    **Note** - each environment has the same shared secret but requires different client TLS certificates.

    For any questions about our testing environments, contact our support mailbox [itoc.supportdesk@nhs.net](mailto:itoc.supportdesk@nhs.net).

    ### Develop against a local MESH sandbox server
    There is a basic sandbox implementation of the MESH API available [mesh-sandbox](https://github.com/NHSDigital/mesh-sandbox).

    This sandbox can be used for local development and currently does not require a client certificate

    ## API Versioning

    MESH API now has `live-beta` support for versioning on certain endpoints in order to allow us to safely make new features and capabilities available to API consumers.

    MESH uses the `Accept` header to support different versions in the same API, sending a different `Accept` header will vary the response, refer to individual API endpoints for more detail.

    If not specified `Accept: application/json` will be assumed and the lowest supported response version for that particular endpoint will be returned.

    **Note:** please refer to the table below for more detail on the status of a given API version.

    | Version | Accept                                               | Status |
    |---------|------------------------------------------------------|--------|
    | 1       | `application/json` or `application/vnd.mesh.v1+json` | live   |
    | 2       | `application/vnd.mesh.v2+json`                       | live   |

    ## MESH Authorization header
    Requests to the MESH API require an authorisation token in the HTTP `Authorization` header.
    To be valid, the authorisation token must match the schema described below. The token includes cryptographic hashes of your organisation's MESH mailbox password and the environment-wide shared secret.
    As an additional security measure each token which matches the schema is valid for one request only, so you must generate a new token for every request. Any repeated use of a token results in a `403: Not Authorized` response from the MESH API.

    The authorisation token is made up of six elements. Except for the first and second elements, each element is separated from the next by a colon (:).

    | Name          | Description                                                                                    |
    |---------------|------------------------------------------------------------------------------------------------|
    | `NHSMESH`     | The name of the Custom Authentication Schema. The space at the end of the schema is important. |
    | `mailbox_id`  | The mailbox identifier sending the HTTP Request. Must be uppercase.                            |
    | `nonce`       | A GUID used as an encryption nonce.                                                            |
    | `nonce_count` | The number of times that the same nonce has been used.                                         |
    | `timestamp`   | The current UTC date and time in `yyyyMMddHHmm` format.                                        |
    | `hash`        | HMAC-SHA256 hash - see the list below.                                                         |

    The `hash` is compiled of the following items:

    * The `shared_key` is the MESH environment shared secret, provided by [itoc.supportdesk@nhs.net](mailto:itoc.supportdesk@nhs.net) as part of onboarding to the PTL environment.
    * The `message` is the concatenation of the 5 following elements, joined by a colon (:):
      - `mailbox_id`
      - `nonce`
      - `nonce_count`
      - `mailbox_password`
      - `timestamp`

    Changing the `nonce` and/or `nonce_count` elements between requests ensures the Authorization header is unique and valid.

    **Notes**
    - the API rejects the request if the `timestamp` supplied is not within 2 hours of the server time
    - in the example below `SHARED_KEY` has been `[REDACTED_SHARED_KEY]`, this is the 'environment shared secret' which you received as part of creating your mailbox
    - in the example below `MAILBOX_PASSWORD` has been `[REDACTED_PASSWORD]`, this is the 'mesh mailbox password' which you received as part of creating your mailbox

    ### Example implementation
    Here is an implementation of the above in `python3`.
    ```python
    """ Python code to generate a valid authorization header. """
    import hmac
    import uuid
    import datetime
    from hashlib import sha256

    AUTH_SCHEMA_NAME = "NHSMESH "  # Note: Space at the end of the schema.
    SHARED_KEY = "[REDACTED_SHARED_KEY]"  # Note: Don't hard code your passwords in a real implementation.


    def build_auth_header(mailbox_id: str, password: str = "password",  nonce: str = None, nonce_count: int = 0):
        """ Generate MESH Authorization header for mailboxid. """
        # Generate a GUID if required.
        if not nonce:
            nonce = str(uuid.uuid4())
        # Current time formatted as yyyyMMddHHmm
        # for example, 4th May 2020 13:05 would be 202005041305
        timestamp = datetime.datetime.utcnow().strftime("%Y%m%d%H%M")

        # for example, NHSMESH AMP01HC001:bd0e2bd5-218e-41d0-83a9-73fdec414803:0:202005041305
        hmac_msg = mailbox_id + ":" + nonce + ":" + str(nonce_count) + ":" + password + ":" + timestamp

        # HMAC is a standard crypto hash method built in the python standard library.
        hash_code = hmac.HMAC(SHARED_KEY.encode(), hmac_msg.encode(), sha256).hexdigest()
        return (
                AUTH_SCHEMA_NAME # Note: No colon between 1st and 2nd elements.
                + mailbox_id + ":"
                + nonce + ":"
                + str(nonce_count) + ":"
                + timestamp+ ":"
                + hash_code
        )


    # example usage
    MAILBOX_ID = "X26AB1234" # Note: Don't hard code your mailbox id in a real implementation.
    MAILBOX_PASSWORD = "[REDACTED_PASSWORD]"  # Note: Don't hard code your passwords in a real implementation.

    # send a new nonce each time
    print(build_auth_header(MAILBOX_ID, MAILBOX_PASSWORD))

    # or reuse the nonce and increment the nonce_count
    my_nonce = str(uuid.uuid4())

    print(build_auth_header(MAILBOX_ID, MAILBOX_PASSWORD, my_nonce, nonce_count=1))
    print(build_auth_header(MAILBOX_ID, MAILBOX_PASSWORD, my_nonce, nonce_count=2))


    ```

    ## MESH API pseudocode
    To use MESH effectively, use the following flow of API calls:

    - inbox poll cycle
    - outbox workflow

    Validate your mailbox once every 24 hours using the 'Validate a mailbox' endpoint.

    ### Inbox poll cycle
    Spine gives each message a unique message identifier after you post it to your outbox. It is the primary identifier for the message during MESH transit.

    It is suggested to poll your mailbox every 5 minutes, but at least every 24 hours. The pseudocode for a mailbox poll is:

    1. Poll to get the messageIds of messages ready to download from the 'Check an inbox' endpoint.
    2. For each message identifier returned in step 1:
        * download the message with the 'Download message' endpoint
        * if it's identified as a chunked message, download all remaining chunks with the 'Download message chunk' endpoint
        * acknowledge receipt of the message via the 'Acknowledge message' endpoint
    3. Repeat step 2 until you have processed the number of messages returned in step 1.
    4. If you received exactly 500 messages in step 1 then repeat from step 1, immediately polling again and downloading, until you receive 0 messages in step 1.

    ### Asynchronous error reporting
    Most problems with message transfer are indicated synchronously (immediately) when you call the 'Send Message' endpoint. However, some errors might occur after a successful request (asynchronously). You get any error reports as messages in your inbox, which you need to receive as part of your inbox poll cycle.
    Error reports differ from regular messages in these ways:
    - the 'Download message endpoint' has a different value for the `Mex-MessageType` header:
      * DATA for a normal organisation-to-organisation message
      * REPORT for an error report
    - the Download message response body of an error report message is empty

    We strongly recommend you check the value of `Mex-MessageType` after downloading each message, so that you can take appropriate action if needed.

    | Error Report Header     | Description                                                              |
    |-------------------------|--------------------------------------------------------------------------|
    | `Mex-StatusEvent`       | Step in the MESH server side process when the error occurred             |
    | `Mex-LinkedMsgID`       | The message identifier of the undelivered message                        |
    | `Mex-WorkflowID`        | The workflow identifier of the undelivered message                       |
    | `Mex-StatusTimestamp`   | Time the error occurred                                                  |
    | `Mex-LocalID`           | Sender assigned local identifier of the unacknowledged message           |
    | `Mex-StatusCode`        | Indicate the status of the message, non-00 indicates error               |
    | `Mex-MessageID`         | The message identifier of the error report (not the undelivered message) |
    | `Mex-StatusSuccess`     | SUCCESS or ERROR (is always ERROR in an error report)                    |
    | `Mex-StatusDescription` | Indicate the status the message, non-00 indicates error                  |
    | `Mex-To`                | Intended receiver of the undelivered message                             |
    | `Mex-MessageType`       | REPORT                                                                   |
    | `Mex-Subject`           | The subject of the undelivered message                                   |

    **Note:** Headers should be treated case insensitively, most http clients will do this for you automatically, but please do not rely on explicit case.

    ### Error codes
    Some of the below errors are only applicable for some API calls. For example, error code 15 would only be found when calling 'Child Protection Information Services' (CP-IS).

    | Error code | Typical description                                                       |
    |------------|---------------------------------------------------------------------------|
    | 02         | Data file is missing or inaccessible                                      |
    | 06         | Malformed headers                                                         |
    | 07         | Invalid From Address, the mailbox does not match the authorization header |
    | 08         | Missing Mex-To header                                                     |
    | 11         | Invalid Message Type for the transfer, should be DATA                     |
    | 12         | Unregistered to address                                                   |
    | 14         | Undelivered message                                                       |
    | 15         | Bad 'Child Protection - Information Sharing' (CP-IS) File                 |
    | 16         | Sender is not allowed to send messages of this type                       |
    | 17         | Workflow ID not registered for mailbox                                    |


    ### Outbox workflow
    The maximum amount of data allowed by MESH in a single request message is 100MB. You can send larger messages by breaking them into \"chunks\" that are transmitted as a single message over multiple requests. The upper limit of a single chunked message is 100GB (20GB if using the java client).

    The [MESH UI](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/compare-mesh-services#mesh-user-interface) and older versions of the MESH client do not support chunking. Check that the receiver's interface to MESH for your workflow identifier handles chunked messages prior to sending. To do this:

    1. Determine the size of your message data (after compression) with a standard algorithm (such as `gzip`). If the compressed message is larger than 100MB, is smaller than 100GB, and the receiving mailbox / workflow identifier supports chunking, then you can send a chunked message. To prepare for this:
        *  split the **uncompressed** data into ordered chunks
        * **independently** compress each chunk with the **same** compression algorithm (such as `gzip`) such that each chunk is smaller than 100MB
        * use the first chunk (after compression) as the initial message data
    2. Send a message with appropriate workflow identifier and `Mex-To` (recipient mailbox) header. To do this:
        * optionally include a local identifier from step 2 for tracking.  This field must not contain PID.
        * if sending a chunked message, include an extra header to indicate that this is the first in a series of chunks, then submit the subsequent chunks via the 'Send Chunked Message' endpoint
    3. A message identifier will be returned which is the unique identifier and can be used for tracking and helping with incident resolution. It would be good practice to log this identifier.

    ### Message expiration
    Messages that are not downloaded and acknowledged within five days of delivery are removed from your inbox. The sending organisation receives an error report explaining that the receiver did not collect the message. Uncollected messages are completely deleted from the MESH server 30 days after the initial delivery. If the sending organisation cannot re-send the message within the intervening time, it may contact our [national service desk](https://digital.nhs.uk/developer/help-and-support) with the error report details and ask for the message to be placed in your inbox again.

    ## Onboarding

    You 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.

    You can view a read-only version of the digital application form on the <a href="https://onboarding.prod.api.platform.nhs.uk/Products/PreviewOverview?apiId=34">MESH assurance questions</a> page. 

    To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding). This is where you can demonstrate that you can manage risks and that your software conforms technically with the requirements for this API. You can also manage onboarding for other APIs in your account.

    <div class="nhsd-m-emphasis-box nhsd-m-emphasis-box--emphasis nhsd-!t-margin-bottom-6" aria-label="Highlighted Information">
        <div class="nhsd-a-box nhsd-a-box--border-blue">
            <div class="nhsd-m-emphasis-box__image-box">
                <figure class="nhsd-a-image">
                    <picture class="nhsd-a-image__picture">
                        <img src="http://digital.nhs.uk/binaries/content/gallery/icons/play-circle.svg?colour=231f20" alt="" style="object-fit:fill">
                    </picture>
                </figure>
            </div>
            <div class="nhsd-m-emphasis-box__content-box">
                <div data-uipath="website.contentblock.emphasis.content" class="nhsd-t-word-break">
                    <p class="nhsd-t-body">To get started, sign in or create a <a href="https://onboarding.prod.api.platform.nhs.uk/">developer account</a>, then select 'product onboarding'.</p>
                </div>
            </div>
        </div>
    </div>

    ## Contact us
    For help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support).
    
  contact:
    name: National Service Desk
    email: ssd.nationalservicedesk@nhs.net
  version: 2.0.0
paths:
  /messageexchange/{mailbox_id}:
    post:
      tags:
      - Handshake
      summary: Validate a mailbox (Handshake)
      description: |-
        ## Overview
        Use this endpoint to check that MESH can be reached and that the authentication you are using is correct.  This endpoint only needs to be called once every 24 hours.
        This endpoint updates the details of the connection history held for your mailbox and is similar to a keep-alive or ping message, in that it allows monitoring on the Spine to be aware of the active use of a mailbox despite a lack of traffic.

        ### Request

        ```shell
        curl -k \
        --request 'GET' \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC005:1c820cd4-be3e-43ff-807f-e65362892722:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        --header 'mex-clientversion: ApiDocs==0.0.1' \
        --header 'mex-osarchitecture: x86_64' \
        --header 'mex-osname: Linux' \
        --header 'mex-osversion: #44~18.04.2-Ubuntu' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005
        ```
      operationId: handshake_messageexchange__mailbox_id__post
      parameters:
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: User agent string
        required: false
        schema:
          title: User-Agent
          type: string
          description: User agent string
          default: ''
        example: my-client;windows-10;
        name: user-agent
        in: header
      - description: Client version number
        required: true
        schema:
          title: mex-ClientVersion
          type: string
          description: Client version number
        example: ApiDocs==0.0.1
        name: mex-clientversion
        in: header
      - description: Operating system name
        required: true
        schema:
          title: mex-OSName
          type: string
          description: Operating system name
        example: Linux
        name: mex-osname
        in: header
      - description: Operating system version
        required: true
        schema:
          title: mex-OSVersion
          type: string
          description: Operating system version
        example: '#44~18.04.2-Ubuntu'
        name: mex-osversion
        in: header
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      - description: the accepts header can be used to vary the response type
        required: false
        schema:
          title: Accept
          type: string
          description: the accepts header can be used to vary the response type
          default: application/json
        example: application/vnd.mesh.v2+json
        name: accept
        in: header
      responses:
        '200':
          description: Successful Response
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: &id001
                  detail:
                    title: Detail
                    type: array
                    items:
                      title: ValidationError
                      required:
                      - loc
                      - msg
                      - type
                      type: object
                      properties:
                        loc:
                          title: Location
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: integer
                        msg:
                          title: Message
                          type: string
                        type:
                          title: Error Type
                          type: string
        '403':
          description: Authentication failed
  /messageexchange/{mailbox_id}/inbox:
    get:
      tags:
      - Inbox
      summary: Check an inbox
      description: |-
        ## Overview
        Use this endpoint to return the message identifier of messages in the mailbox inbox ready for download.
        Client systems MUST poll their assigned inbox a minimum of once a day and a maximum of once every five minutes for messages (unless there are more messages waiting to download).

        A maximum of 500 message identifier are returned in every request.  Continue the polling and download cycle until you empty the mailbox and you receive less than 500 messages in the response.

        ### Request

        ```shell
        curl -k \
        --request 'GET' \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC005:66eef28b-e097-421d-998d-ea0c92c2c2fb:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox
        ```


        ### Response

        for `accept: application/vnd.mesh.v2+json` and later if the inbox contains more than 500 messages, then 'links.next' will provide a way to page through all the messages in the inbox
        ```json
        {
          "messages": ["20220228174323222_ABCDEF", "20220228174323333_ABCDEF"],
          "links": {
            "self": "/messageexchange/mb12345/inbox?max_results=10",
            "next": "/messageexchange/mb12345/inbox?max_results=10&continue_from=eyJwayI6ICJNQiNNU0cjTUIjMTIzNEhDMTIzNCMiLCAic2siOiAiTUIjTVNHIzIwMjIwMjI4MTc0MzIzMTIzX0FDREVEMSMifQ%3D%3D"
          }
        }
        ```
        for `accept: application/vnd.mesh.v1+json` or `accept: application/json`
        ```json
        {
          "messages" : ["20200529155357895317_3573F8", "20220228174323333_ABCDEF"]
        }
        ```
      operationId: list_messages_messageexchange__mailbox_id__inbox_get
      parameters:
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: 'maximum results to return when using `accept: application/vnd.mesh.v2+json` if more results exist, `links.next` will be populated'
        required: false
        schema:
          title: Max results
          maximum: 5000.0
          minimum: 10.0
          type: integer
          description: 'maximum results to return when using `accept: application/vnd.mesh.v2+json` if more results exist, `links.next` will be populated'
          default: 500
        example: '100'
        name: max_results
        in: query
      - description: if more results exist than `max_results`, use `continue_from` to continue retrieving results from `links.next`
        required: false
        schema:
          title: Continue From
          maxLength: 1000
          minLength: 24
          type: string
          description: if more results exist than `max_results`, use `continue_from` to continue retrieving results from `links.next`
        examples:
          'accept: application/vnd.mesh.v2+json':
            value: eyJwayI6ICJNQiNNU0cjTUIjMTIzNEhDMTIzNCMiLCAic2siOiAiTUIjTVNHIzIwMjIwMjI4MTc0MzIzMTIzX0FDREVEMSMifQ%3D%3D
          'accept: application/json':
            value: 20220228174323123_ACDED1
        name: continue_from
        in: query
      - description: |-
          filter inbox by workflow id, conditions:
          * equals: =WORKFLOW1
          * does not equal: =!WORKFLOW1
          * begins with: =WORKFL\*
          * does not begin with: =!WORKFL\*
          * contains: =\*_ACK\*
          * does not contain: =!\*_ACK\*
        required: false
        schema:
          title: Workflow Id filter
          maxLength: 255
          minLength: 2
          type: string
          description: |-
            filter inbox by workflow id, conditions:
            * equals: =WORKFLOW1
            * does not equal: =!WORKFLOW1
            * begins with: =WORKFL\*
            * does not begin with: =!WORKFL\*
            * contains: =\*_ACK\*
            * does not contain: =!\*_ACK\*
        example: '!*_ACK*'
        name: workflow_filter
        in: query
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      - description: the accepts header can be used to vary the response type
        required: false
        schema:
          title: Accept
          type: string
          description: the accepts header can be used to vary the response type
          default: application/json
        example: application/vnd.mesh.v2+json
        name: accept
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/vnd.mesh.v2+json:
              schema:
                title: Inbox
                required:
                - messages
                type: object
                properties:
                  messages:
                    title: Messages
                    type: array
                    items:
                      type: string
                    description: list of message ids in the inbox, up to `max_results`
                  links:
                    title: Links
                    type: object
                    additionalProperties:
                      type: string
                    description: map of links, e.g. `links.next` if more results exist
                  approx_inbox_count:
                    title: Approx Inbox Count
                    type: integer
                    description: approximate inbox count, this is eventually consistent and should be used as an indication of inbox size only
                example:
                  messages:
                  - 20220228174323222_ABCDEF
                  - 20220228174323333_ABCDEF
                  links:
                    self: /messageexchange/mb12345/inbox?max_results=10
                    next: /messageexchange/mb12345/inbox?max_results=10&continue_from=eyJwayI6ICJNQiNNU0cjTUIjMTIzNEhDMTIzNCMiLCAic2siOiAiTUIjTVNHIzIwMjIwMjI4MTc0MzIzMTIzX0FDREVEMSMifQ%3D%3D
                  approx_inbox_count: 100
            application/json:
              schema:
                title: Inbox
                required:
                - messages
                type: object
                properties:
                  messages:
                    title: Messages
                    type: array
                    items:
                      type: string
                    description: list of message ids in the inbox, up to `max_results`
                example:
                  messages:
                  - 20220228174323222_ABCDEF
                  - 20220228174323333_ABCDEF
        '403':
          description: Authentication failed
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
  /messageexchange/{mailbox_id}/inbox/{message_id}:
    get:
      tags:
      - Inbox
      summary: Get Message
      description: |-
        ## Overview
        Use this endpoint to retrieve a message based on the message identifier obtained from the 'Check Inbox' endpoint.

        **Note:** Headers should be treated case insensitively, most http clients will do this for you automatically, but please do not rely on explicit case.

        ### Message expiration
        Messages you do not download and acknowledge within five days of delivery are removed from your inbox. The sending organisation receives an error report explaining that the receiver did not collect the message. Uncollected messages are completely deleted from the MESH server 30 days after initial delivery. If the sending organisation cannot re-send the message within the intervening time, they can contact the [NHS Digital national service desk](https://digital.nhs.uk/developer/help-and-support) with the error report details and ask for the message to be re-sent.

        ### Report Messages
        The `Mex-MessageType` header indicates if the payload is a `DATA` message or a `REPORT`.
        Error reports differ from regular messages in these ways:
        - the Download message endpoint has a different value for the Mex-MessageType header
          * DATA for a normal organisation-to-organisation message
          * REPORT for an error report
        - the Download message response body of an error report message is empty

        ### Request

        ```shell
          curl -k \
          --request 'GET' \
          --cacert 'mesh-ca.pem' \
          --key 'mesh-client-key.pem' \
          --cert 'mesh-client-cert.pem' \
          --header 'accept: application/vnd.mesh.v2+json' \
          --header 'authorization: NHSMESH X26HC005:2942264f-46e5-450f-90fc-22a0c09efa37:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
          https://msg.int.spine2.ncrs.nhs.uk/messageexchange/X26HC005/inbox/20200529155357895317_3573F8
        ```

        ### Response

        ```shell
        HTTP/1.1 200 OK
        content-type: application/octet-stream
        content-length: 27
        mex-content-compressed: N
        mex-addresstype: ALL
        mex-localid: api-docs-bob-sends-alice-a-chunked-file
        mex-chunk-range: 2:2
        etag: "866243ab74e0107a4d5835f8d6552e7f20c39ee1"
        mex-filename: message.txt.gz
        mex-version: 1.0
        mex-workflowid: API-DOCS-TEST
        mex-to: X26HC005
        mex-messagetype: DATA
        mex-messageid: 20200601122152994285_D59900
        mex-from: X26HC006

        m you in the future,

        Bob.
        ```
      operationId: retrieve_message_messageexchange__mailbox_id__inbox__message_id__get
      parameters:
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: message identifier
        required: true
        schema:
          title: message_id
          minLength: 1
          type: string
          description: message identifier
        example: 20210311101813838554_1B8F53
        name: message_id
        in: path
      - description: client accepted content encoding(s)
        required: false
        schema:
          title: Accept-Encoding
          type: string
          description: client accepted content encoding(s)
          default: ''
        example: gzip
        name: accept-encoding
        in: header
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      responses:
        '200':
          description: OK, full message retrieved
          content:
            application/octet-stream:
              schema:
                format: binary
        '403':
          description: Authentication failed
        '206':
          description: Partial Content - Indicates that chunk has been downloaded successfully and that there are further chunks.
          content:
            application/octet-stream:
              schema:
                format: binary
        '404':
          description: Not Found, message does not exist
        '410':
          description: Gone, message has expired or otherwise failed
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
    head:
      tags:
      - Inbox
      summary: Head Message
      description: |-
        ## Overview
        Use this endpoint to retrieve a message metadata based on the `message_id` obtained from the 'Check Inbox' endpoint.

        ### Message expiration
        Messages you do not download and acknowledge within five days of delivery are removed from your inbox. The sending organisation receives an error report explaining that the receiver did not collect the message. Uncollected messages are completely deleted from the MESH server 30 days after initial delivery. If the sending organisation cannot re-send the message within the intervening time, they can contact the [NHS Digital national service desk](https://digital.nhs.uk/developer/help-and-support) with the error report details and ask for the message to be re-sent.

        ### Report Messages
        The `Mex-MessageType` header indicates if the payload is a `DATA` message or a `REPORT`.
        Error reports differ from regular messages in these ways:
        - the Download message endpoint has a different value for the `Mex-MessageType` header
          * DATA for a normal organisation-to-organisation message
          * REPORT for an error report

        **Note:** Headers should be treated case insensitively, most http clients will do this for you automatically, but please do not rely on explicit case.

        ### Request

        ```shell
          curl -k \
          --request 'HEAD' \
          --cacert 'mesh-ca.pem' \
          --key 'mesh-client-key.pem' \
          --cert 'mesh-client-cert.pem' \
          --header 'accept: application/vnd.mesh.v2+json' \
          --header 'authorization: NHSMESH X26HC005:2942264f-46e5-450f-90fc-22a0c09efa37:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
          https://msg.int.spine2.ncrs.nhs.uk/messageexchange/{mailbox_id}/inbox/{message_id}
        ```

        ### Response

        ```shell
        HTTP/1.1 200 OK
        content-type: application/vnd.mesh.v2+json
        content-length: 0
        mex-content-compressed: N
        mex-addresstype: ALL
        mex-localid: api-docs-bob-sends-alice-a-chunked-file
        mex-chunk-range: 2:2
        etag: "866243ab74e0107a4d5835f8d6552e7f20c39ee1"
        mex-filename: message.txt.gz
        mex-version: 1.0
        mex-workflowid: API-DOCS-TEST
        mex-to: X26HC005
        mex-messagetype: DATA
        mex-messageid: 20200601122152994285_D59900
        mex-from: X26HC006
        ```
      operationId: head_message_messageexchange__mailbox_id__inbox__message_id__head
      parameters:
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: message identifier
        required: true
        schema:
          title: message_id
          minLength: 1
          type: string
          description: message identifier
        example: 20210311101813838554_1B8F53
        name: message_id
        in: path
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      responses:
        '200':
          description: Successful Response
        '403':
          description: Authentication failed
        '404':
          description: Not Found, message does not exist
        '410':
          description: Gone, message has expired or otherwise failed
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
  /messageexchange/{mailbox_id}/inbox/{message_id}/status/acknowledged:
    put:
      tags:
      - Inbox
      summary: Acknowledge message
      description: |-
        ## Overview
        Use this endpoint to acknowledge the successful download of a message.

        This operation:

        * closes the message transaction on Spine
        * removes the message from your mailbox inbox, which means that the `message_id` does not appear in subsequent calls to the 'Check inbox' endpoint and cannot be downloaded again

        **Note:** If you fail to acknowledge a message after five days in the inbox this sends a non-delivery report to the sender's inbox.

        ### Request

        ```shell
        curl -k \
        --request 'PUT' \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC005:bb59be38-e50b-4e5a-9f11-e566e7509552:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox/20200529155357895317_3573F8/status/acknowledged
        ```

        ### Response

        for `accept: application/vnd.mesh.v2+json` no response body will be returned

        for `accept: application/vnd.mesh.v1+json` or `accept: application/json`
        ```json
        { "messageId" : "20200529155357895317_3573F8" }
        ```
      operationId: acknowledge_message_messageexchange__mailbox_id__inbox__message_id__status_acknowledged_put
      parameters:
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: message identifier
        required: true
        schema:
          title: message_id
          minLength: 1
          type: string
          description: message identifier
        example: 20210311101813838554_1B8F53
        name: message_id
        in: path
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      - description: the accepts header can be used to vary the response type
        required: false
        schema:
          title: Accept
          type: string
          description: the accepts header can be used to vary the response type
          default: application/json
        example: application/vnd.mesh.v2+json
        name: accept
        in: header
      responses:
        '200':
          description: Successful Response
        '403':
          description: Authentication failed
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
  /messageexchange/{mailbox_id}/inbox/{message_id}/{chunk_number}:
    get:
      tags:
      - Inbox
      summary: Get Message chunk
      description: |-
        Use this endpoint to download a chunked message. Initially, call the 'Download Message' endpoint with the message identifier given by the 'Check Inbox' endpoint as usual. When the message is chunked, the 'Download message' endpoint response differs in two ways:
        * the response code is '206: Partial Content' (instead of '200: OK')
        * the response headers contain Mex-Chunk-Range: 1:n


        This endpoint is used to download the remaining n-1 chunks.

        **Note:** Headers should be treated case insensitively, most http clients will do this for you automatically, but please do not rely on explicit case.

        ### Request

        Following on from the example in the 'Send chunked message' endpoint, Alice checks her inbox and sees a new message.


        ```shell
        curl -k \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --request 'GET' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC005:142b8a1e-e953-4e5e-98a8-b27741e15747:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox
        ```

        She downloads the first part of the message. **Note** this use of `curl` uses the `--include` argument, to show the value of the HTTP headers in the MESH response.

        ```shell
        curl -k \
        --include \
        --request 'GET' \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC005:777670ce-02f7-44fe-a53b-eb33eb1cb564:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox/20200601122152994285_D59900
        ```

        ```shell
        HTTP/1.1 206 Partial Content
        content-type: application/octet-stream
        content-length: 100
        mex-chunk-range: 1:2
        mex-workflowid: API-DOCS-TEST
        mex-content-compressed: N
        mex-addresstype: ALL
        mex-statussuccess: SUCCESS
        mex-statusdescription: Transferred to recipient mailbox
        nex-messagetype: DATA
        mex-statusevent: TRANSFER
        mex-to: X26HC005
        mex-statustimestamp: 20200601122152
        mex-localid: api-docs-bob-sends-alice-a-chunked-file
        mex-statuscode: 00
        mex-filename: message.txt.gz
        mex-messageid: 20200601122152994285_D59900
        mex-from: X26HC006

        Hi Alice,

        This is Bob. It's really nice that we can communicate via SPINE!

        I hope to hear more fro
        ```

        Here we have added the `--include` argument to `curl` which prints more response information, including the HTTP response code and response headers. (`tr -d '\r'` invokes a linux utility to strip carriage returns from the end of each of the lines added to the `curl` `--include` argument).

        Alice notes that the response code is `206 Partial Content` - meaning it is the first part of a chunked message. How much of the message remains is given by the `Mex-Chunk-Range` header, `1:2` indicating the response body is the first of two parts.

        Alice makes another call to retrieve the second part of the message.

        ```shell
        curl -k \
        --include \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC005:71139532-9215-4ff8-8a74-d602386bac30:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox/20200601122152994285_D59900/2 | tr -d '\r'
        ```

        ```shell
        HTTP/1.1 200 OK
        content-type: application/octet-stream
        content-length: 27
        mex-content-compressed: N
        mex-addresstype: ALL
        mex-localid: api-docs-bob-sends-alice-a-chunked-file
        mex-chunk-range: 2:2
        etag: "866243ab74e0107a4d5835f8d6552e7f20c39ee1"
        mex-filename: message.txt.gz
        mex-version: 1.0
        mex-workflowid: API-DOCS-TEST
        mex-to: X26HC005
        mex-messagetype: DATA
        mex-messageid: 20200601122152994285_D59900
        mex-from: X26HC006

        m you in the future,

        Bob.
        ```

        That this is the final part of the message is indicated in two ways:

        -   the response code is `200 OK` rather than `206 Partial Content`
        -   the `Mex-Chunk-Range` response header is `2:2`
      operationId: retrieve_chunk_messageexchange__mailbox_id__inbox__message_id___chunk_number__get
      parameters:
      - description: The index number of the chunk
        required: true
        schema:
          title: chunk_number
          minimum: 1.0
          type: integer
          description: The index number of the chunk
        example: '1'
        name: chunk_number
        in: path
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: message identifier
        required: true
        schema:
          title: message_id
          minLength: 1
          type: string
          description: message identifier
        example: 20210311101813838554_1B8F53
        name: message_id
        in: path
      - description: client accepted content encoding(s)
        required: false
        schema:
          title: Accept-Encoding
          type: string
          description: client accepted content encoding(s)
          default: ''
        example: gzip
        name: accept-encoding
        in: header
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      responses:
        '200':
          description: OK - chunk downloaded and no further chunks exist
          content:
            application/octet-stream:
              schema:
                format: binary
        '403':
          description: Authentication failed
        '206':
          description: Partial Content - Indicates that chunk has been downloaded successfully and that there are further chunks.
          content:
            application/octet-stream:
              schema:
                format: binary
        '404':
          description: Not Found, message does not exist
        '410':
          description: Gone, message has expired or otherwise failed
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
  /messageexchange/{mailbox_id}/count:
    get:
      tags:
      - Inbox
      summary: Check an inbox count (deprecated)
      description: |-
        ## Overview
        Use this endpoint to check the number of messages currently held in the MESH mailbox that are ready to download.

        This endpoint is now deprecated as it is not needed as part of the polling cycle.
      operationId: count_messages_in_inbox_messageexchange__mailbox_id__count_get
      deprecated: true
      parameters:
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/vnd.mesh.v2+json:
              schema:
                title: InboxCount
                required:
                - count
                type: object
                properties:
                  count:
                    title: Count
                    type: integer
                    description: number of messages in the inbox
                example:
                  count: 1234
            application/json:
              schema:
                title: InboxCount
                required:
                - count
                - internalID
                - allResultsIncluded
                type: object
                properties:
                  count:
                    title: Count
                    type: integer
                    description: number of messages in the inbox
                  internalID:
                    title: Internalid
                    type: string
                    description: internal identifier to help error diagnosis, be aware the format of this may change in line withinternal system changes and the format should not be parsed or validated or otherwise depended on
                  allResultsIncluded:
                    title: Allresultsincluded
                    type: boolean
                    description: indicates if the count was based on a partial result
                example:
                  count: 1234
                  internalID: 20200601122152994285_af20cED
                  allResultsIncluded: true
        '403':
          description: Forbidden
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
  /messageexchange/{mailbox_id}/outbox:
    post:
      tags:
      - Outbox
      summary: Send message
      description: |-
        ## Overview
        Use this endpoint to send a message via MESH. Use the POST command to your virtual outbox. Specify the message recipient in the request headers, with the message contained in the request body.

        ### Messages larger than 100MB
        The largest data payload the MESH API accepts in a single request is 100MB. Compress larger messages to reduce bandwidth and data storage on Spine. If compression does not sufficiently reduce the message size enough for transmission in a single request then you can break it up into smaller chunks and transmit them separately provided:
          1.  The total compressed size of the message is < 100MB - this is the Spine upper limit for a single message.
          2.  The receiver mailbox and workflow identifier support the downloading of chunked messages. MESH UI and older versions of the MESH client do not support this.

        To correctly break the outbound message into valid chunks:
          1.  Split the **uncompressed** message into `n` ordered chunks such that each (compressed) chunk is smaller than 100MB.
          2.  **Independently** compress each chunk with the same compression algorithm (e.g. `gzip`).
          3.  The first (compressed) chunk of the message should be transmitted using this endpoint (the normal send message endpoint). Include the optional `Mex-Chunk-Range` header with a value `1:n` to tell Spine that this is a chunked message and to wait for `n-1` other requests before delivering the message. The message identifier of this initial server response **must** be captured as it is a required path element of the Send chunked message URL.

        Always set the workflow identifier as some workflows are restricted which means the mailbox sender and recipient must be configured for the workflow identifier you send.

        To discover the recipient mailbox either use the `endpointlookup` endpoint or for certain workflows you can include [demographic details](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/mesh-guidance-hub/endpoint-lookup-service-and-workflowids#using-the-to_dts-field-of-a-mesh-message-to-find-a-mailbox-) in the `Mex-To` field.

        It is good practice to capture the returned message identifier as this provides a unique identifier which you can use for message tracking.

        ### Request

        ```shell
        curl -k \
        --request 'POST' \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC006:c1f2df9c-fe9e-4d11-ba78-49a8bc705eb4:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        --header 'content-type: application/octet-stream' \
        --header 'mex-from: X26HC006' \
        --header 'mex-to: X26HC005' \
        --header 'mex-workflowid: API-DOCS-TEST' \
        --header 'mex-filename: None' \
        --header 'mex-localid: api-docs-bob-greets-alice' \
        --data 'This is a message' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC006/outbox
        ```

        ### Response

        for `accept: application/vnd.mesh.v2+json`
        ```json
        {"message_id": "20200529155357895317_3573F8"}
        ```
        for `accept: application/vnd.mesh.v1+json` or `accept: application/json`
        ```json
        {"messageID": "20200529155357895317_3573F8"}
        ```
      operationId: send_message
      parameters:
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      - description: Recipient mailbox ID
        required: true
        schema:
          title: mex-To
          maxLength: 100
          type: string
          description: Recipient mailbox ID
          default: ''
        example: MAILBOX01
        name: mex-to
        in: header
      - description: Identifies the type of message being sent e.g. Pathology, GP Capitation.
        required: true
        schema:
          title: mex-WorkflowID
          maxLength: 300
          type: string
          description: Identifies the type of message being sent e.g. Pathology, GP Capitation.
          default: ''
        name: mex-workflowid
        in: header
      - description: chunk range
        required: false
        schema:
          title: mex-Chunk-Range
          maxLength: 20
          type: string
          description: chunk range
          default: ''
        example: '1:2'
        name: mex-chunk-range
        in: header
      - description: additional message subject
        required: false
        schema:
          title: mex-Subject
          maxLength: 500
          type: string
          description: additional message subject
          default: ''
        name: mex-subject
        in: header
      - description: local identifier, your reference
        required: false
        schema:
          title: mex-LocalID
          maxLength: 300
          type: string
          description: local identifier, your reference
          default: ''
        name: mex-localid
        in: header
      - description: local filename
        required: false
        schema:
          title: mex-FileName
          maxLength: 300
          type: string
          description: local filename
          default: ''
        name: mex-filename
        in: header
      - description: Checksum of the original message contents, as provided by the message sender
        required: false
        schema:
          title: mex-Content-Checksum
          maxLength: 100
          type: string
          description: Checksum of the original message contents, as provided by the message sender
          default: ''
        example: b10a8db164e0754105b7a99be72e3fe5
        name: mex-content-checksum
        in: header
      - description: content type of the message when decoded
        required: false
        schema:
          title: Content-Type
          type: string
          description: content type of the message when decoded
          default: ''
        example: text/csv
        name: content-type
        in: header
      - description: content encoding
        required: false
        schema:
          title: Content-Encoding
          type: string
          description: content encoding
          default: ''
        example: gzip
        name: content-encoding
        in: header
      - description: the accepts header can be used to vary the response type
        required: false
        schema:
          title: Accept
          type: string
          description: the accepts header can be used to vary the response type
          default: application/json
        example: application/vnd.mesh.v2+json
        name: accept
        in: header
      responses:
        '202':
          description: Successful Response
          content:
            application/vnd.mesh.v2+json:
              schema:
                title: SendMessage
                required:
                - message_id
                type: object
                properties:
                  message_id:
                    title: Message Id
                    type: string
                    description: message identifier of the accepted message
                example:
                  message_id: 20220228174323222_ABCDEF
            application/json:
              schema:
                title: SendMessage
                required:
                - messageID
                type: object
                properties:
                  messageID:
                    title: Messageid
                    type: string
                    description: message identifier of the accepted message
                example:
                  messageID: 20220228174323222_ABCDEF
        '403':
          description: Forbidden
        '417':
          description: Expectation Failed
          content:
            application/vnd.mesh.v2+json:
              schema:
                title: MeshError
                type: object
                properties:
                  message_id:
                    title: Message Id
                    type: string
                    description: message id associated with the error
                  internal_id:
                    title: Internal Id
                    type: string
                    description: internal id associated with the error
                  detail:
                    title: Detail
                    type: array
                    items:
                      type: object
                    description: error detail
                example:
                  message_id: 20220228174323222_ABCDEF
                  internal_id: 20220228174323222_ABCDEF
                  detail:
                  - event: SEND
                    code: '01'
                    msg: send failed for some reason
            application/json:
              schema:
                title: MeshError
                type: object
                properties:
                  messageID:
                    title: Messageid
                    type: string
                    description: message_id associated with the error
                  errorEvent:
                    title: Errorevent
                    type: string
                    description: message error phase
                    default: ''
                  errorCode:
                    title: Errorcode
                    type: string
                    description: message error code
                    default: ''
                  errorDescription:
                    title: Errordescription
                    type: string
                    description: message error description
                    default: ''
                example:
                  messageID: 20220228174323222_ABCDEF
                  errorEvent: SEND
                  errorCode: '01'
                  errorDescription: send failed for some reason
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
      requestBody:
        description: message payload or chunk, optionally encoded with content-encoding
        required: true
        content:
          application/octet-stream:
            schema:
              format: binary
            example: '... message payload bytes...'
          '*/*':
            schema:
              format: any
            example: |-
              message content....
                                      any content type is acceptable but use application/octet-stream if you want a single default
  /messageexchange/{mailbox_id}/outbox/{message_id}/{chunk_number}:
    post:
      tags:
      - Outbox
      summary: Send chunked message
      description: |-
        ## Overview
        Use this endpoint to send a chunked message. The 'Send Message' endpoint has a maximum single request message payload size of 100MB. However, you can send much larger messages (up to 20GB) by breaking up the message into chunks and transmitting it over multiple requests.

        **Note**: Some workflow ids do not support chunking because it is not currently supported in the MESH UI and older versions of the MESH client. Check with your receiving organisation before sending messages with this endpoint.

        To send a chunked message:

        1. Split it into separate files
        2. Compress the individual chunks **separately** with the **same** compression program (e.g. `gzip`).
           - **DO NOT** compress a large file and then split the compressed version
        3. Upload the first file using the normal 'Send message' endpoint.
           - include the `Mex-Chunk-Range` header with a value of `1:n` where `n` is the number of separate files your big data is split into
           - capture the message identifier field in the returned JSON
        4. Upload subsequent files in the correct order using the chunked message endpoint

        **Note:** fewer headers are required for the chunked message endpoint because Spine uses the relevant metadata from the initial (`Mex-Chunk-Header=1:n`) call to the 'Send message' endpoint.

        ### Request

        Suppose Bob has a large file to send to Alice. In this example we will use **message.txt**. It is easily small enough to send in a single request, but we will chunk it anyway to illustrate the API calls.
        ```shell
        ls -sh message.txt
        4.0kb message.txt
        ```
        ```shell
        cat message.txt

        Hi Alice,

        This is Bob. It's really nice that we can communicate via SPINE!

        I hope to hear more from you in the future,

        Bob.
        ```

          First we break up our one "large" file into two smaller files. We will transmit one per request.

        ```shell
        split -b 100 message.txt message.txt_
        ls -sh message.txt_*
        ```

        Large messages should be compressed to reduce the bandwidth and storage requirements for Spine.
        ```shell
        for chunk_file in message.txt_*; do
          gzip -k -f $chunk_file;
        done
        ls -sh message.txt_*.gz

        4.0kb message.txt_aa.gz
        4.0kb message.txt_ab.gz
        ```
        ```shell
        curl -k \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --request 'POST' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC006:2c6e938e-9a72-4a7a-9664-96ac1f341331:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        --header 'content-type: application/octet-stream' \
        --header 'mex-from: X26HC006' \
        --header 'mex-to: X26HC005' \
        --header 'mex-workflowid: API-DOCS-TEST' \
        --header 'mex-filename: message.txt.gz' \
        --header 'mex-localid: api-docs-bob-sends-alice-a-chunked-file' \
        --header 'mex-chunk-range: 1:2' \
        --header 'content-encoding: gzip' \
        --data-binary '@message.txt_aa.gz' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC006/outbox
        ```
        ```shell
        curl -k \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --request 'POST' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC006:06bf0527-ba77-47f0-b22f-d7d08a88ad26:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        --header 'mex-chunk-range: 2:2' \
        --data-binary '@./message.txt_ab.gz' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC006/outbox/20200601122152994285_D59900/2
        ```
      operationId: send_chunk
      parameters:
      - description: The index number of the chunk
        required: true
        schema:
          title: chunk_number
          type: integer
          description: The index number of the chunk
        example: '1'
        name: chunk_number
        in: path
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: message identifier
        required: true
        schema:
          title: message_id
          minLength: 1
          type: string
          description: message identifier
        example: 20210311101813838554_1B8F53
        name: message_id
        in: path
      - description: chunk range for the current chunk
        required: false
        schema:
          title: mex-Chunk-Range
          maxLength: 20
          type: string
          description: chunk range for the current chunk
          default: ''
        example: '2:3'
        name: mex-chunk-range
        in: header
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      - description: content encoding
        required: false
        schema:
          title: Content-Encoding
          type: string
          description: content encoding
          default: ''
        example: gzip
        name: content-encoding
        in: header
      - description: the accepts header can be used to vary the response type
        required: false
        schema:
          title: Accept
          type: string
          description: the accepts header can be used to vary the response type
          default: application/json
        example: application/vnd.mesh.v2+json
        name: accept
        in: header
      responses:
        '202':
          description: Successful Response
          content:
            application/vnd.mesh.v2+json:
              schema:
                title: SendMessage
                required:
                - message_id
                type: object
                properties:
                  message_id:
                    title: Message Id
                    type: string
                    description: message identifier of the accepted message
                example:
                  message_id: 20220228174323222_ABCDEF
            application/json:
              schema:
                title: SendMessage
                required:
                - messageID
                type: object
                properties:
                  messageID:
                    title: Messageid
                    type: string
                    description: message identifier of the accepted message
                example:
                  messageID: 20220228174323222_ABCDEF
        '403':
          description: Forbidden
        '417':
          description: Expectation Failed
          content:
            application/vnd.mesh.v2+json:
              schema:
                title: MeshError
                type: object
                properties:
                  message_id:
                    title: Message Id
                    type: string
                    description: message id associated with the error
                  internal_id:
                    title: Internal Id
                    type: string
                    description: internal id associated with the error
                  detail:
                    title: Detail
                    type: array
                    items:
                      type: object
                    description: error detail
                example:
                  message_id: 20220228174323222_ABCDEF
                  internal_id: 20220228174323222_ABCDEF
                  detail:
                  - event: SEND
                    code: '01'
                    msg: send failed for some reason
            application/json:
              schema:
                title: MeshError
                type: object
                properties:
                  messageID:
                    title: Messageid
                    type: string
                    description: message_id associated with the error
                  errorEvent:
                    title: Errorevent
                    type: string
                    description: message error phase
                    default: ''
                  errorCode:
                    title: Errorcode
                    type: string
                    description: message error code
                    default: ''
                  errorDescription:
                    title: Errordescription
                    type: string
                    description: message error description
                    default: ''
                example:
                  messageID: 20220228174323222_ABCDEF
                  errorEvent: SEND
                  errorCode: '01'
                  errorDescription: send failed for some reason
        '404':
          description: Not Found, message does not exist
        '423':
          description: Messages has been finalised; no more chunks can be uploaded
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
      requestBody:
        description: message payload or chunk, optionally encoded with content-encoding
        required: true
        content:
          application/octet-stream:
            schema:
              format: binary
            example: '... message payload bytes...'
          '*/*':
            schema:
              format: any
            example: |-
              message content....
                                      any content type is acceptable but use application/octet-stream if you want a single default
    post:
      tags:
      - Outbox
      summary: Carbon Copy (CC) a message
      description: |-
        ## Overview
        CC creates an additional copy of a message and delivers it to another mailbox. The copied message will produce a new message with a different MESH message ID. The original recipient still receives the message. CC is configured by the MESH service team, to learn more about CC see our [Service Page](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh#mesh-cc-and-redirect).
        
        ### To CC a message:

        The required field is:
        - cc_to_mailbox_id (target mailbox)
        
        Plus at least one of:
        - cc_if_sender
        - cc_if_recipient
        - workflow_id
        
    post:
      tags:
      - Outbox
      summary: Redirect a message
      description: |-
        ## Overview
        Redirect replaces the original recipient with a different mailbox. The original recipient does not receive the message. Redirects are configured by the MESH service team, to learn more about redirects see our [Service Page](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh#mesh-cc-and-redirect).
        
        ### To redirect a message:

        The required fields are:
        - redirect_to_mailbox_id (replacing mailbox)
        - redirect_if_recipient (original intended recipient)
 
  /messageexchange/{mailbox_id}/outbox/tracking:
    get:
      tags:
      - Tracking
      summary: Track outbox
      description: |-
        ## Overview
        Use this endpoint to enquire about the status of messages sent from your outbox. When determining the frequency of the calling of this endpoint consider that MESH is asynchronous, and it might be some hours until the recipient downloads your message. You must not poll this endpoint frequently.

        The message identifier is the value returned in the response to a message upload.

        Do not use this endpoint to replace a business ack message. If the business process requires confirmation that the recipient has processed the message then send a business ACK over MESH. The convention is to use the same workflow identifier appended with `_ACK`.

        ### Request
        It is possible for Bob to check the status of the chunked message he sent to Alice. (Note that in this example, Alice has not acknowledged the chunked message she received from Bob).


        ```shell
        curl -k \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC006:1f6c9442-eb9a-440c-b4ed-ee4fd525e176:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC006/outbox/tracking?messageID=20210311101813838554_1B8F53
        ```

        ### Response

        for `accept: application/vnd.mesh.v2+json`

        ```json
        {
          "message_id": "20210311101813838554_1B8F53",
          "local_id": "api-docs-bob-sends-alice-a-chunked-file",
          "workflow_id": "API-DOCS-TEST",
          "filename": "message.txt.gz",
          "expiry_time": "20200606122153",
          "upload_timestamp": "20200601122152",
          "recipient": "X26HC005",
          "recipient_name": "APIM bebop",
          "recipient_ods_code": "X26",
          "recipient_org_code": "TestOrg",
          "recipient_org_name": "TEST Org Partnership Trust",
          "status_success": true,
          "status": "accepted",
          "status_event": "TRANSFER",
          "status_timestamp": "2020-06-01T12:21:52",
          "status_description": "Success",
          "status_code": "01"
        }
        ```
        for `accept: application/vnd.mesh.v1+json` or `accept: application/json`

        ```json
        {
          "addressType": "ALL",
          "checksum": null,
          "compressFlag": null,
          "contentEncoding": "gzip",
          "contentsBase64": true,
          "dtsId": "20210311101813838554_1B8F53",
          "encryptedFlag": null,
          "expiryTime": "20200606122153",
          "fileName": "message.txt.gz",
          "fileSize": 187,
          "isCompressed": null,
          "localId": "api-docs-bob-sends-alice-a-chunked-file",
          "meshRecipientOdsCode": "X26",
          "messageId": "20210311101813838554_1B8F53",
          "messageType": "DATA",
          "partnerId": null,
          "processId": null,
          "recipient": "X26HC005",
          "recipientBillingEntity": "England",
          "recipientName": "APIM bebop",
          "recipientOrgCode": "TestOrg",
          "recipientOrgName": "TEST Org Partnership Trust",
          "recipientSmtp": "x26hc005@dts.nhs.uk",
          "sender": "X26HC006",
          "senderBillingEntity": "England",
          "senderName": "APIM bebop",
          "senderOdsCode": "X26",
          "senderOrgCode": "TestOrg",
          "senderOrgName": "TEST Org Partnership Trust",
          "senderSmtp": "x26hc006@dts.nhs.uk",
          "status": "Accepted",
          "statusCode": null,
          "statusDescription": null,
          "statusEvent": null,
          "statusSuccess": null,
          "statusTimestamp": null,
          "subject": null,
          "uploadTimestamp": "20200601122152",
          "version": "1.0",
          "workflowId": "API-DOCS-TEST"
        }
        ```

        Suppose Alice only now acknowledges the message Bob sent.

        ### Request

        ```shell
        curl -k \
        --request 'PUT' \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC005:57db9dd2-2156-4c02-90d4-66e7082179db:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox/20210311101813838554_1B8F53/status/acknowledged
        ```

        ### Response

        ```json
        {"message_id" : "20210311101813838554_1B8F53" }
        ```

        The next call to Track outbox by Bob

        ### Request

        ```shell
        curl -k \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --header 'accept: application/vnd.mesh.v2+json' \
        --header 'authorization: NHSMESH X26HC006:dd3f8609-b2c3-4f5a-aa62-c456579b8f77:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC006/outbox/tracking?messageID=20210311101813838554_1B8F53
        ```

        ### Response

        ```json
        {
          "status_timestamp": "2020-06-01T12:21:52",
          "status": "acknowledged",
          "message_id": "20210311101813838554_1B8F53"
        }
        ```

        This shows the `status` field of the response has changed from `Accepted` to `Acknowledged`.  All the fields in the previous response are also included.
      operationId: tracking_by_message_id_messageexchange__mailbox_id__outbox_tracking_get
      parameters:
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: message identifier
        required: true
        schema:
          title: message identifier
          minLength: 1
          type: string
          description: message identifier
        example: 20210311101813838554_1B8F53
        name: messageID
        in: query
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      - description: the accepts header can be used to vary the response type
        required: false
        schema:
          title: Accept
          type: string
          description: the accepts header can be used to vary the response type
          default: application/json
        example: application/vnd.mesh.v2+json
        name: accept
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/vnd.mesh.v2+json:
              schema:
                title: Tracking
                required:
                - message_id
                type: object
                properties:
                  message_id:
                    title: Message Id
                    type: string
                    description: message identifier
                  local_id:
                    title: Local Id
                    type: string
                    description: local identifier supplied by sender
                  workflow_id:
                    title: Workflow Id
                    type: string
                    description: message workflow identifier
                  filename:
                    title: Filename
                    type: string
                    description: local filename as supplied by the sender
                  expiry_time:
                    title: Expiry Time
                    type: string
                    description: iso timestamp that the message will expire from the inbox
                    format: date-time
                  upload_timestamp:
                    title: Upload Timestamp
                    type: string
                    description: iso timestamp that the message was accepted
                    format: date-time
                  recipient:
                    title: Recipient
                    type: string
                    description: recipient mailbox identifier
                  recipient_name:
                    title: Recipient Name
                    type: string
                    description: recipient mailbox name
                  recipient_ods_code:
                    title: Recipient Ods Code
                    type: string
                    description: recipient organisation ODS code
                  recipient_org_code:
                    title: Recipient Org Code
                    type: string
                    description: recipient organisation organisation code
                  recipient_org_name:
                    title: Recipient Org Name
                    type: string
                    description: recipient organisation name
                  status_success:
                    title: Status Success
                    type: boolean
                    description: SUCCESS or ERROR if the message accepted
                  status:
                    title: Status
                    type: string
                    description: message status e.g. 'accepted' 'acknowledged'
                  status_event:
                    title: Status Event
                    type: string
                    description: status event
                  status_timestamp:
                    title: Status Timestamp
                    type: string
                    description: iso timestamp last status change
                    format: date-time
                  status_description:
                    title: Status Description
                    type: string
                    description: status description
                  status_code:
                    title: Status Code
                    type: string
                    description: status code
            application/json:
              schema:
                title: Tracking
                required:
                - dtsId
                - fileSize
                - messageId
                type: object
                properties:
                  addressType:
                    title: Addresstype
                    type: string
                    default: ALL
                  checksum:
                    title: Checksum
                    type: string
                    description: message status e.g. 'accepted' 'acknowledged'
                  chunkCount:
                    title: Chunkcount
                    type: integer
                    description: number of message chunks
                  compressFlag:
                    title: Compressflag
                    type: string
                  contentEncoding:
                    title: Contentencoding
                    type: string
                    default: ''
                  downloadTimestamp:
                    title: Downloadtimestamp
                    type: string
                    description: timestamp the message was acknowledged
                  dtsId:
                    title: Dtsid
                    type: string
                    description: message identifier of the sent message
                  encryptedFlag:
                    title: Encryptedflag
                    type: string
                  expiryTime:
                    title: Expirytime
                    type: string
                    description: timestamp that the message will expire from the inbox
                  failureDate:
                    title: Failuredate
                    type: string
                  failureDiagnostic:
                    title: Failurediagnostic
                    type: string
                  fileName:
                    title: Filename
                    type: string
                    description: local filename as supplied by the sender
                  fileSize:
                    title: Filesize
                    type: integer
                    description: the uploaded file size
                  isCompressed:
                    title: Iscompressed
                    type: string
                    default: ''
                  linkedMsgId:
                    title: Linkedmsgid
                    type: string
                    description: related message id
                  localId:
                    title: Localid
                    type: string
                    description: local identifier supplied by sender
                  meshRecipientOdsCode:
                    title: Meshrecipientodscode
                    type: string
                    description: recipient organisation ODS code
                  messageId:
                    title: Messageid
                    type: string
                    description: message identifier of the sent message
                  messageType:
                    title: Messagetype
                    type: string
                    description: DATA or REPORT
                  partnerId:
                    title: Partnerid
                    type: string
                    default: ''
                  recipient:
                    title: Recipient
                    type: string
                    description: recipient mailbox identifier
                  recipientName:
                    title: Recipientname
                    type: string
                    description: recipient mailbox name
                  recipientOrgCode:
                    title: Recipientorgcode
                    type: string
                    description: recipient organisation code
                  recipientOrgName:
                    title: Recipientorgname
                    type: string
                    description: recipient organisation name
                  recipientSmtp:
                    title: Recipientsmtp
                    type: string
                    default: ''
                  sender:
                    title: Sender
                    type: string
                    description: sender mailbox identifier
                  senderName:
                    title: Sendername
                    type: string
                    description: sender mailbox name
                  senderOdsCode:
                    title: Senderodscode
                    type: string
                    description: sender ods code
                  senderOrgCode:
                    title: Senderorgcode
                    type: string
                    description: sender organisation code
                  senderOrgName:
                    title: Senderorgname
                    type: string
                    description: sender organisation name
                  senderSmtp:
                    title: Sendersmtp
                    type: string
                    default: ''
                  status:
                    title: Status
                    type: string
                    description: message status e.g. 'accepted' 'acknowledged'
                  statusCode:
                    title: Statuscode
                    type: string
                    description: status code
                  statusDescription:
                    title: Statusdescription
                    type: string
                    description: status description
                  statusEvent:
                    title: Statusevent
                    type: string
                    description: status event
                  statusSuccess:
                    title: Statussuccess
                    type: string
                    description: SUCCESS or ERROR if the message accepted
                  statusTimestamp:
                    title: Statustimestamp
                    type: string
                    description: timestamp of the status change
                  subject:
                    title: Subject
                    type: string
                    description: message subject
                  uploadTimestamp:
                    title: Uploadtimestamp
                    type: string
                    description: timestamp that the message was accepted
                  version:
                    title: Version
                    type: string
                    default: '1.0'
                  workflowId:
                    title: Workflowid
                    type: string
                    description: message workflow identifier
        '403':
          description: Forbidden
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
  /messageexchange/{mailbox_id}/outbox/tracking/{local_id}:
    get:
      tags:
      - Tracking
      summary: Track outbox (deprecated)
      description: |-
        ## Overview
        This endpoint is now `deprecated` `tracking?messageID` should be used instead.
      operationId: tracking_by_local_id_messageexchange__mailbox_id__outbox_tracking__local_id__get
      parameters:
      - description: The user supplied (local ID) of the message
        required: true
        schema:
          title: The local ID of the message
          minLength: 1
          type: string
          description: The user supplied (local ID) of the message
        example: api-docs-bob-sends-alice-a-chunked-file
        name: local_id
        in: path
      - description: mailbox identifier
        required: true
        schema:
          title: mailbox_id
          minLength: 1
          type: string
          description: mailbox identifier
        example: MAILBOX01
        name: mailbox_id
        in: path
      - description: Authorisation header
        required: true
        schema:
          title: Authorization
          type: string
          description: Authorisation header
          default: ''
        example: 'authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced'
        name: authorization
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Tracking
                required:
                - dtsId
                - fileSize
                - messageId
                type: object
                properties:
                  addressType:
                    title: Addresstype
                    type: string
                    default: ALL
                  checksum:
                    title: Checksum
                    type: string
                    description: message status e.g. 'accepted' 'acknowledged'
                  chunkCount:
                    title: Chunkcount
                    type: integer
                    description: number of message chunks
                  compressFlag:
                    title: Compressflag
                    type: string
                  contentEncoding:
                    title: Contentencoding
                    type: string
                    default: ''
                  downloadTimestamp:
                    title: Downloadtimestamp
                    type: string
                    description: timestamp the message was acknowledged
                  dtsId:
                    title: Dtsid
                    type: string
                    description: message identifier of the sent message
                  encryptedFlag:
                    title: Encryptedflag
                    type: string
                  expiryTime:
                    title: Expirytime
                    type: string
                    description: timestamp that the message will expire from the inbox
                  failureDate:
                    title: Failuredate
                    type: string
                  failureDiagnostic:
                    title: Failurediagnostic
                    type: string
                  fileName:
                    title: Filename
                    type: string
                    description: local filename as supplied by the sender
                  fileSize:
                    title: Filesize
                    type: integer
                    description: the uploaded file size
                  isCompressed:
                    title: Iscompressed
                    type: string
                    default: ''
                  linkedMsgId:
                    title: Linkedmsgid
                    type: string
                    description: related message id
                  localId:
                    title: Localid
                    type: string
                    description: local identifier supplied by sender
                  meshRecipientOdsCode:
                    title: Meshrecipientodscode
                    type: string
                    description: recipient organisation ODS code
                  messageId:
                    title: Messageid
                    type: string
                    description: message identifier of the sent message
                  messageType:
                    title: Messagetype
                    type: string
                    description: DATA or REPORT
                  partnerId:
                    title: Partnerid
                    type: string
                    default: ''
                  recipient:
                    title: Recipient
                    type: string
                    description: recipient mailbox identifier
                  recipientName:
                    title: Recipientname
                    type: string
                    description: recipient mailbox name
                  recipientOrgCode:
                    title: Recipientorgcode
                    type: string
                    description: recipient organisation code
                  recipientOrgName:
                    title: Recipientorgname
                    type: string
                    description: recipient organisation name
                  recipientSmtp:
                    title: Recipientsmtp
                    type: string
                    default: ''
                  sender:
                    title: Sender
                    type: string
                    description: sender mailbox identifier
                  senderName:
                    title: Sendername
                    type: string
                    description: sender mailbox name
                  senderOdsCode:
                    title: Senderodscode
                    type: string
                    description: sender ods code
                  senderOrgCode:
                    title: Senderorgcode
                    type: string
                    description: sender organisation code
                  senderOrgName:
                    title: Senderorgname
                    type: string
                    description: sender organisation name
                  senderSmtp:
                    title: Sendersmtp
                    type: string
                    default: ''
                  status:
                    title: Status
                    type: string
                    description: message status e.g. 'accepted' 'acknowledged'
                  statusCode:
                    title: Statuscode
                    type: string
                    description: status code
                  statusDescription:
                    title: Statusdescription
                    type: string
                    description: status description
                  statusEvent:
                    title: Statusevent
                    type: string
                    description: status event
                  statusSuccess:
                    title: Statussuccess
                    type: string
                    description: SUCCESS or ERROR if the message accepted
                  statusTimestamp:
                    title: Statustimestamp
                    type: string
                    description: timestamp of the status change
                  subject:
                    title: Subject
                    type: string
                    description: message subject
                  uploadTimestamp:
                    title: Uploadtimestamp
                    type: string
                    description: timestamp that the message was accepted
                  version:
                    title: Version
                    type: string
                    default: '1.0'
                  workflowId:
                    title: Workflowid
                    type: string
                    description: message workflow identifier
        '403':
          description: Forbidden
        '300':
          description: Multiple Choices, the `local_id` is not unique
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
      deprecated: true
  /messageexchange/endpointlookup/{ods_code}/{workflow_id}:
    get:
      tags:
      - Lookup
      summary: Look up MESH address
      description: |-
        ## Overview
        Use this endpoint to search for the mailbox of the organisation you want to send data to, using their unique [Organisation Data Service (ODS) code](https://odsportal.hscic.gov.uk/Organisation/Search), their MESH mailbox and the agreed workflow identifier for the data.

        An example call:

        ### Request

        ```shell
        curl -k \
        --cacert 'mesh-ca.pem' \
        --key 'mesh-client-key.pem' \
        --cert 'mesh-client-cert.pem' \
        --header 'accept: application/vnd.mesh.v2+json' \
        https://mesh-sync.spineservices.nhs.uk/messageexchange/endpointlookup/SCREEN2/SPINE_GPCAPITATION_EXTRACT
        ```

        ### Response

        for `accept: application/vnd.mesh.v2+json`

        ```json
        {
          "results": [
            {"mailbox_id": "X2612345", "mailbox_name": "this is a test mailbox"},
            {"mailbox_id": "X2612346", "mailbox_name": "this is a test mailbox too"}
          ]
        }
        ```

        for `accept: application/vnd.mesh.v1+json` or `accept: application/json`
        ```json
        {
          "query_id": "20200601131040203367_A441C2_1573484974",
          "results": [
            {
              "endpoint_type": "MESH",
              "description": "Breast Cancer Screening Services",
              "address": "X26HC022"
            },
            {
              "endpoint_type": "MESH",
              "description": "AAA Screening Services",
              "address": "X26HC021"
            },
            {
              "endpoint_type": "MESH",
              "description": "Bowel Cancer Screening Services (England, DMS)",
              "address": "X26HC020"
            }
          ]
        }
        ```

        **Note:** neither the ODS code or workflow identifier in this example are real.
      operationId: get_receiving_mailbox_ids_messageexchange_endpointlookup__ods_code___workflow_id__get
      parameters:
      - description: The ODS code of the organisation
        required: true
        schema:
          title: ods_code
          type: string
          description: The ODS code of the organisation
        name: ods_code
        in: path
      - description: The Workflow ID of the message
        required: true
        schema:
          title: workflow_id
          type: string
          description: The Workflow ID of the message
        name: workflow_id
        in: path
      - description: the accepts header can be used to vary the response type
        required: false
        schema:
          title: Accept
          type: string
          description: the accepts header can be used to vary the response type
          default: application/json
        example: application/vnd.mesh.v2+json
        name: accept
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/vnd.mesh.v2+json:
              schema:
                title: lookup_v2
                required:
                - results
                type: object
                properties:
                  results:
                    title: Results
                    type: array
                    items:
                      title: LookupItem
                      type: object
                      properties:
                        mailbox_id:
                          title: Mailbox Id
                          description: mailbox identifier
                          type: string
                        mailbox_name:
                          title: Mailbox Name
                          description: mailbox name
                          type: string
                      required:
                      - mailbox_id
                      - mailbox_name
                    description: list of matched mailboxes
                example:
                  results:
                  - mailbox_id: X2612345
                    mailbox_name: this is a test mailbox
            application/json:
              schema:
                title: EndpointLookup
                required:
                - query_id
                - results
                type: object
                properties:
                  query_id:
                    title: Query Id
                    type: string
                    description: unique query identifier
                  results:
                    title: Results
                    type: array
                    items:
                      title: LookupItem
                      type: object
                      properties:
                        address:
                          title: Address
                          description: mailbox identifier
                          type: string
                        description:
                          title: Description
                          description: mailbox name
                          type: string
                        endpoint_type:
                          title: Endpoint Type
                          description: mailbox endpoint type, this will always be MESH
                          type: string
                      required:
                      - address
                      - description
                      - endpoint_type
                    description: list of matched mailboxes
                example:
                  query_id: 20220228174323222_ABCDEF
                  results:
                  - address: X2612345
                    description: this is a test mailbox
                    endpoint_type: MESH
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
  /messageexchange/workflowsearch/{workflow_id}:
    get:
      tags:
      - Lookup
      summary: Lookup by workflow
      operationId: get_receiving_mailbox_ids_messageexchange_workflowsearch__workflow_id__get
      parameters:
      - description: The Workflow ID of the message
        required: true
        schema:
          title: workflow_id
          type: string
          description: The Workflow ID of the message
        name: workflow_id
        in: path
      - description: the accepts header can be used to vary the response type
        required: false
        schema:
          title: Accept
          type: string
          description: the accepts header can be used to vary the response type
          default: application/json
        example: application/vnd.mesh.v2+json
        name: accept
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/vnd.mesh.v2+json:
              schema:
                title: lookup_v2
                required:
                - results
                type: object
                properties:
                  results:
                    title: Results
                    type: array
                    items:
                      title: LookupItem
                      type: object
                      properties:
                        mailbox_id:
                          title: Mailbox Id
                          description: mailbox identifier
                          type: string
                        mailbox_name:
                          title: Mailbox Name
                          description: mailbox name
                          type: string
                      required:
                      - mailbox_id
                      - mailbox_name
                    description: list of matched mailboxes
                example:
                  results:
                  - mailbox_id: X2612345
                    mailbox_name: this is a test mailbox
            application/json:
              schema:
                title: lookup_v2
                required:
                - results
                type: object
                properties:
                  results:
                    title: Results
                    type: array
                    items:
                      title: LookupItem
                      type: object
                      properties:
                        mailbox_id:
                          title: Mailbox Id
                          description: mailbox identifier
                          type: string
                        mailbox_name:
                          title: Mailbox Name
                          description: mailbox name
                          type: string
                      required:
                      - mailbox_id
                      - mailbox_name
                    description: list of matched mailboxes
                example:
                  results:
                  - mailbox_id: X2612345
                    mailbox_name: this is a test mailbox
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                title: HTTPValidationError
                type: object
                properties: *id001
servers:
- url: https://msg.int.spine2.ncrs.nhs.uk
  description: Integration
- url: https://msg.intspineservices.nhs.uk
  description: Integration
- url: https://mesh-sync.national.ncrs.nhs.uk
  description: Production
- url: https://mesh-sync.spineservices.nhs.uk
  description: Production
x-spec-publication:
  try-this-api:
    disabled: true