Establishing a Patient App Linkage

Overview

Before a Patient Facing Application (the PFS application) can make requests on behalf of a patient via the PFS API, it required a Patient App Linkage to be established between the App’s User and the Medicus Patient.

The patient signals their intent to allow a PFS application to link with their patient record on Medicus by requesting a printed Patient App Linkage key from their healthcare organisation. The token takes the form of a Linkage Token string and a QR code representing the Patient App Linkage Token.

The Patient App Linkage Token makes the PFS app aware of:

• The patient's intent to link the app with their patient record on Medicus

• The Medicus Tenant ID

• The Medicus Patient ID

The Status of a Patient App Linkage Token

• Active - this token can be exchanged for a Patient App Linkage.

• Revoked - this token has been revoked by a member of staff and cannot be exchanged for a Patient App Linkage.

• Exchanged - this token has been changed for a Patient App Linkage.

Automatic Revocation of a Patient App Linkage Token

If a patient’s permanent registration at the Healthcare Organisation is ended, then any Patient App Linkage Tokens with a status of “active” will automatically be set to “revoked”.

If a patient is marked as “Deceased” then any Patient App Linkage Tokens with a status of “active” will automatically be set to “revoked”.

Patient App Linkage Token

A Patient App Linkage Token is generated by a Medicus user on behalf of a patient.

Patient App Linkage Token structure:

An example Patient App Linkage Token:

a10001-136930-721549

A Medicus user will generate a printed Patient App Linkage Token in the form of a QR code which can be read by the PFS app. The token is shown in a text format underneath the QR code.

Exchanging a Linkage Token for a Patient App Linkage

In order to create a Patient App Linkage, the PFS app must make a request to the Exchange Linkage Token API endpoint.

Step 1: Requesting a One Time Passcode

Before securing a linkage, the PFS app must first make a request to send a one time passcode (OTP) to the patient or contact’s email address. This is done via the Request Linkage OTP endpoint.

Method: POST

URL: https://{{medicusTenant}}.{{medicusBaseURL}}/pfs-api/v1/request-linkage-otp

Request Headers

 Body Parameters

Example Request

POST /pfs-api/v1/request-linkage-otp
Authorization: Bearer [token]

{
    "linkageCode": "a10001-258037-930450"
}

Response

Successful Response Body

Example Response (OK):

HTTP/1.1 200 OK

{
    "success": true
}

Response Codes

Step 2: Creating an App User Linkage

After the user has received the OTP, then they must enter it into the PFS app. The PFS app must provide a user interface for the user to enter the OTP. The OTP along with the linkage token is then sent to Medicus.

If the request is successful, a linkage is created by Medicus between the app user and the patient.

Making a Request

Method: POST

URL: https://{{medicusTenant}}.{{medicusBaseURL}}/pfs-api/v1/create-account-linkage

Request Headers

Body Parameters

Example Request

POST /pfs-api/v1/create-account-linkage
Authorization: Bearer [token]

{
    "linkageCode": "a1001-65837-58976",
    "oneTimePasscode": "12345678"
}

Response

Specific Response Codes

Example Response (OK):

HTTP/1.1 200 OK

{
    "success": true
}

Example Response (Association Exists Error):

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "errors": [
    {
      "code": "ASSOCIATION_EXISTS",
      "title": "Association Exists",
      "detail": "A linkage already exists between this Consumer App and the Account."
    }
  ]
}

Step 3: Follow Up Requests

After a linkage is made between the app, the app user and the patient, then follow up requests can be made to any of the PFS endpoints.

Note: to make a request to an endpoint, the PFS app must be accredited by Medicus to use that endpoint.