Establishing a Transactional API Connection Agreement

Overview

Third-party applications wishing to use the Transactional API must have a "Connection Agreement" in place with the tenant.

A Connection Agreement exists between:

the Medicus tenant
the app
the requesting organisation (this isn't the same as the requesting app's organisation)

A Connection Agreement is requested by the app by making a request to the Request Connection Agreement endpoint.

After the request is made, staff at the healthcare organisation can approve or reject the app’s Connection Agreement.

If the Connection Agreement is approved, then the app is free to make requests to the Transactional API on behalf of an organisation.

Prerequisites

An app can only make requests for Accredited Interactions that have been pre-approved by Medicus

Making a Request

HTTP method: POST

https://{{medicusTenant}}.{{medicusBaseURL}}/transactional-api/v1/request-connection-agreement

Request Headers

Header	Value	Description
`Authorization`	`Bearer [token]`	The JWT token for the API Consumer.
`Idempotency-Key`	UUID	Idempotency Key so that if the same request is made twice, a duplicate note is not created.

URL Parameters

Parameter

Description

Validation Rules

patientId

Patient ID

e.g. e9af860e-cf8e-4272-b81a-a95cc8a531f7

Mandatory

UUID

Body Parameters

Parameter	Type	Description
`requestedInteractions`	An array of requested Interactions	Example: CODE `["TRANSACTIONAL_SEARCH_FOR_A_PATIENT", "TRANSACTIONAL_CHECK_IN_PATIENT_ON_ARRIVAL"]`
`organisationName`	string	The organisation’s name
`organisationIdentifierType`	string (required)	Possible values: `nhs-england-ods-code`
`organisationIdentifierValue`	string (required)	The organisation identifier (NHS ODS Code for NHS England organisations)

Example Request

JSON

POST https://a10001.api.staging.medicus.health/transactional-api/v1/request-connection-agreement
Idempotency-Key: dfaf7fef-6120-465b-8a3a-8825e498a58d
Authorization: Bearer [JWT Token]

{
    "requestedInteractions": ["TRANSACTIONAL_RETRIEVE_PATIENT_JOURNAL","TRANSACTIONAL_DOWNLOAD_FILE"],
    "organisationName": "Bakers Hill Medical Centre",
    "organisationIdentifierType": "nhs-england-ods-code",
    "organisationIdentifierValue": "YGMYW"
}

Response details

Specific Response Codes

HTTP Code	Error Code	Detail
`200`		Connection Agreement Request created
`400`	`MISSING_REQUESTED_INTERACTIONS`	The request does not contain any requested interactions
`400`	`MISSING_ORGANISATION_IDENTIFIER_VALUE`	The request did not contain an Organisation Identifier Value
`400`	`MISSING_ORGANISATION_IDENTIFIER`	The request did not contain an Organisation Identifier
`401`	`NO_CONNECTION_AGREEMENT`	The Transactional API Agreement has not been approved by the practice
`405`	`REQUESTED_INTERACTIONS_NOT_ACCREDITED`	Medicus has not accredited this app for one or more of the requested interactions
`409`	`AGREEMENT_ALREADY_APPROVED`	A connection agreement has already been approved for the App, Organisation & Requested Interactions

Example Response (Bad Format Error):

JSON

HTTP/1.1 400 Unprocessable Entity
Content-Type: application/json

{
  "errors": [
    {
      "code": "MISSING_REQUESTED_INTERACTIONS"
      "title": "Missing requested interactions",
      "detail": "The request does not contain any requested interactions"
    }
  ]
}

Example Response (Connection Agreement Request Created)

JSON

{
    "success": true
}

Connection Agreement States

Once requested, a Connection Agreement can have the following states:

Pending - the Connection Agreement is waiting to be approved or rejected.
Approved - the requesting app is free to make requests to endpoints governed by the requested Interactions on behalf of the specified organisation.
Rejected - the app is blocked from making requests for the requested Interactions on behalf of the specified organisation.
Revoked - the healthcare organisation has revoked a previously “Active” Connection Agreement. The app can no longer make requests for the requested Interactions on behalf of the specified organisation.

If the Connection Agreement has been “Rejected” or “Revoked”, the app must request a new Connection Agreement via the Request Connection Agreement endpoint.