Patient Referral Service - API v1

Refer patients to the Doccla Platform using the Patient Referral Service API.

Security and Authentication

The API currently only supports service-to-service authentication, which means that Cross-Origin Resource Sharing (CORS) is not implemented.

The client key and client secret will be provided by Doccla on request.

Client Authentication

To authenticate a request with basic authentication:

Combine the client key and client secret with a colon. Example: someClientKey123:someClientSecret987
Base64-encode the resulting string. Example: c29tZUNsaWVudEtleTEyMzpzb21lQ2xpZW50U2VjcmV0OTg3
Include the base64-encoded string in a HTTP Authorization header as follows:
```
Authorization: Basic {base64-encoded-string}
```

Example:

Authorization: Basic c29tZUNsaWVudEtleTEyMzpzb21lQ2xpZW50U2VjcmV0OTg3

SSL requirements

All connections to the API must support the TLS 1.2 protocol.

Environments

Environment	Base URL
Demo	https://demo.doccla.net/api/referral/v1
Production	https://app.doccla.com/api/referral/v1

Overview

POST /referrals

Use this endpoint to refer a patient to the Doccla platform.

This is a 'POST' operation to create a new referral.

When you make a POST request with your application, the endpoint will respond with a successful (201) response code, or, an unsuccessful (4xx/5xx) response.

Most requests should complete in under 5 seconds. If a request takes longer than 5 seconds, the endpoint responds with an HTTP status of 503 (Gateway Timeout).

Request

Headers

NAME	DESCRIPTION
Authorization	String `(^Basic\\ [[:ascii:]]+\$)` A basic auth token.
X-Correlation-ID	String An optional ID which you can use to track transaction across multiple systems.

Body

Content type: application/json

Name	Description
`patient` (object) required	see Patient data fields below
`monitoring` (object) required	see Monitoring data fields below
`nextOfKin` (object)	see Next of kin data fields below
`additionalNotes` (string)	Any additional information about the patient, including any special requirements, such as the size of the blood pressure cuff, any impairments or disabilities that is helpful for Doccla to be aware of.
`kitReferenceNumber` (string)	The ID of the Doccla Box if the patient has been discharged with one
`deliveryNotes` (string)	If the patient hasn't been discharged with a Doccla Box, this is an optional field to capture any delivery notes (e.g. "leave with neighbour" etc).
`referrer` (string) required	The email address of the person submitting the referral.
`groupEmail` (string) required	The clinical team group email address to send the referral confirmation email to.
`referringPartyReference` (string)	An optional identifier that describes the referred patient for the duration of their referral. This is an add-on feature, which must be configured on a per organisation basis. It is disabled by default.

Patient data fields

Name	Description
`healthcareId` (string) required	A unique identifier for the patient. In most cases this would be the patient's NHS number but where a patient does not have an NHS number this could be the patient's EHR ID, Case Reference Number or similar.
`firstName` (string) required	The first name(s) of the patient.
`surname` (string) required	The surname or family name of the patient.
`dateOfBirth` (Date) required	The patient's date of birth in the ISO 8601 format - `YYYY-MM-DD`
`gender` (`male`\|`female`\|`other`\|`unknown`) required	The administrative gender that the patient wishes to be known as.
`contactNumber` (array) required	The first element in the array should be the primary contact phone number for the patient. See Contact number fields below.
`address` (array) required	The first element in the array should be the address which the Doccla box should be delivered to (if not handed to the patient) and collected from. See Address fields below.

Contact number fields

Name	Description
`value` (string) required	Phone number.

Address fields

Name	Description
`line` (string) required	Full address without postcode. Example: `153 Craddocks Avenue, Ashtead, Surrey`
`postcode` (string) required	The postcode associated with the address.

Monitoring data fields

Name	Description
`pathway` (array) required	The pathway(s) which the patient is being referred to. See Pathway fields below.
`thresholdAmendments` (string)	Any amendments to the default thresholds used for monitoring alerts. Refer to TRUST SOP for more information.

Pathway fields

Name	Description
`name` (string) required	The name of the pathway.
`frequency` (string\|null) required	The frequency at which the patient should submit readings for this pathway. Can be null if frequency is not applicable to the pathway.

Next of kin data fields

Name	Description
`name` required	The name of the patient's emergency contact.
`relation` required	The person's relationship to the patient.
`contactNumber` required	The person's contact number.

Example

{
  "patient": {
    "healthcareId": "9449310416",
    "firstName": "Lise",
    "surname": "Hebron",
    "gender": "female",
    "contactNumber": [
      {
        "value": "07801548007"
      }
    ],
    "address": [
      {
        "line": "153 Craddocks Avenue, Ashtead, Surrey",
        "postcode": "KT21 1NT"
      }
    ],
    "dateOfBirth": "2007-03-28"
  },
  "kitReferenceNumber": "TESTING-LH-1",
  "deliveryNotes": "",
  "monitoring": {
    "pathway": [
      {
        "name": "Asthma",
        "frequency": "TDS"
      }
    ],
    "thresholdAmendments": "BP Diastolic low threshold at 70"
  },
  "nextOfKin": {
    "name": "Larry",
    "relation": "brother",
    "contactNumber": "98761234"
  },
  "referrer": "referrer@doccla.com",
  "additionalNotes": "Patient is hard of hearing",
  "groupEmail": "group@doccla.com",
  "referringPartyReference": "1241234"
}

Response

HTTP status: 201

Referral successfully created.

HTTP status: 4XX

These errors indicate that the request failed due a client error by your application:

HTTP status	Error Code	Description
400	`VALIDATION_ERROR`	The request was not succcessful. See description in the response body.
401	`ACCESS_DENIED`	The authentication token is either missing or invalid.
403	`ACCESS_DENIED`	The application is not permitted to submit referral.

Example Validation Error

{
  "issue": [
    {
      "code": "VALIDATION_ERROR",
      "validationDiagnostics": {
        "patient": { "firstName": ["missing required key"] }
      }
    }
  ]
}

HTTP status: 5XX

These errors indicate a server error.

Example Error with description

{
  "issue": [
    {
      "code": "UNABLE_TO_SUBMIT_REFERRAL",
      "description": "Request timed out"
    }
  ]
}