Find Patient (Transactional)

Overview

The Find Patient Transactional API endpoint allows 3rd Party Transactional Consumer apps to find a patient according to specific fields.

The Find Patient Transactional API endpoint can be used for the following:

to determine if a patient exists on a Medicus tenant
to retrieve the patient’s Medicus patientId which is used to make further requests against that patient (e.g. to retrieve the Patient’s Journal)
to retrieve basic demographic details about the patient

Note: The Find Patient endpoint does not return inactive patients

Making a Request

HTTP method: GET

URL: https://{{medicusTenant}}.{{medicusBaseURL}}/transactional-api/v1/patient/find?query={{query}}

Request Headers

Header	Value	Description
`Authorization`	`Bearer [token]`	The JWT token for the API Consumer.

Query Parameters

Parameter

Type

Description

query

string

The search query

Search queries can be performed against the following properties:

A Medicus Patient ID
A patient identifier (in England, this is NHS number)
Any part of the patient’s name
The patient’s date of birth, in the format DD.MM.YYYY. For example: 11.02.2017

Example Request

CODE

GET /transactional-api/v1/patient/search?query=smith
Authorization: Bearer [token]

Response Details

Properties

All results are contained within a searchResults array

Search Results

Field	Type	Description
`id`	UUID	The patient’s Medicus identifier
`name`	string	The patient’s name
`age`	string	The patient’s age
`genderIdentity`	string	The patient’s gender identity
`homeAddress`	Address	See below
`dateOfBirth`	date	The patient’s date of birth
`nhsNumber`	string	The patient’s NHS number

Search Results: Address

Field	Type	Description
`line1`	string	The first line of the patient’s address
`line2`	string	The second line of the patient’s address
`line3`	string	The third line of the patient’s address
`locality`	string	The patient’s address locality (a Town/city)
`administrativeArea`	string	The administrative area (the County)
`postalCode`	string	The patient’s address postcode
`country`	string	The patient’s country

Specific Response Codes

HTTP Code	Error Code	Scenario
`200`		The search request was successful
`400`	`MISSING_REQUIRED_PROPERTY`	The `query` parameter is not present in the request payload

Example Response (Multiple Matching Patients)

JSON

HTTP/1.1 200 OK
Content-Type: application/json

{
    "searchResults": [
        {
            "id": "f9f143e0-360c-11ed-ae66-060b232f1aa2",
            "name": "Mark TUNNEY",
            "age": "50y",
            "genderIdentity": "Male",
            "homeAddress": {
                "line2": "13 BRADLEY ROAD",
                "locality": "ENFIELD",
                "administrativeArea": "MIDDX",
                "postalCode": "EN3 6ES",
                "country": "GBR"
            },
            "dateOfBirth": "1972-05-07",
            "nhsNumber": "969 314 2551"
        },
        {
            "id": "f5eb6d66-360c-11ed-bb14-060b232f1aa2",
            "name": "Pamela TUNNEY",
            "age": "61y",
            "genderIdentity": "Female",
            "homeAddress": {
                "line1": "1 WINDMILL GARDENS",
                "line2": "ENFIELD",
                "line3": "MIDDX",
                "postalCode": "EN2 7DZ",
                "country": "GBR"
            },
            "dateOfBirth": "1960-12-09",
            "nhsNumber": "969 314 2322"
        }
    ]
}

Example Response (Zero Matches)

JSON

HTTP/1.1 200 OK
Content-Type: application/json

{
    "searchResults": []
}