Frequently requested APIs

Additional detail for the most frequently requested APIs

The tables below provide some general information about the APIs most commonly utilised by organisations extracting data from the PKB data warehouse. We recommend that customers pursuing an integration, begin by looking at utilising a combination of these as a starting point.

NB - where the scope is co-ordinator or clinician the API will only return data for which the user has team / privacy access to view.

Measurement data

Whether measurements have been added manually by a patient or clinician, directly from a device integration or via an integrated data feed, the API will return all the current and historical data for any patient that grants the organisation API access to their record.

API

Brief Description

API Type

Scope

Parameters

Output Overview





GET /v2-beta/measurements



Returns all current and historical measurement data for a patient.

Utilises authorisation code granted by a patient



Option of selecting results for specific measurement(s) or returning all.

Dates of when taken and entered into PKB, along with measurement value(s) and the PKB measurement reference value..

REST

Patient

GET /v2-beta/measurements/{patientId}



The current and historical measurement field data  can be extracted for a patient.

Patient PKB ID

Measurement API Ref (e.g. medication compliance)

Dates of when taken and entered into PKB, along with measurement percentage.

REST

Clinician

GET /v2-beta/measurements/apiRefs



Returns a list of all the measurement types PKB supports within the User Interface.

n/a

Information about every measurement, such as the name, PKB reference, category and measurement unit(s) 

REST

Public

See our help manual for details on measurement support within PKB:

https://manual.patientsknowbest.com/patient/measurements

Technical information on how data can be sent via an HL7 message feed can be found here:

https://pkbdev.atlassian.net/wiki/spaces/api/pages/3364848908/Laboratory

Care plans

Whether a care plan has been created manually (e.g. by a patient or clinician) or via an integrated data feed, the API will return data for all the plans (including any older versions) associated with the chosen patient.

API Name

Brief Description

API Type

Scope

Parameters

Output Overview





GET /v2-beta/careplans/{patientId}



For a selected patient it returns data for all available care plans and care plan versions.

Patient PKB ID

For each care plan it will return general information such as: date created, care plan name, version No., date last edited, next review data and the associated patient id.

Data will also be provided on which user created the plan and who last edited it.

REST

Clinician



Coordinator

See our help manual for information on how Care plans are supported within PKB:

https://manual.patientsknowbest.com/patient/plans

Technical information on how data can be sent via an HL7 message feed can be found here:

https://pkbdev.atlassian.net/wiki/spaces/api/pages/3365012559/Care+Plan

Allergies

Whether allergy information has been added manually (e.g. by the patient) or via an integrated data feed, the API will return all related data for a chosen patient that the API authorising clinician has medical record access for.

API Name

Brief Description

API Type

Scope

Parameters

Output Overview





GET /v2-beta/allergies/forPatient/{patientId}



Returns all recorded allergies for a chosen patient

Patient PKB ID

Information for every recorded allergy.  Including the code, name, date of onset, date entered, reactions and severity. 

REST

Clinician

See our help manual for information on how Allergy information is supported within PKB:

https://manual.patientsknowbest.com/patient/allergies

Technical information on how data can be sent via an HL7 message feed can be found here:

https://pkbdev.atlassian.net/wiki/spaces/api/pages/3365078168/ADT+A28

Diagnosis

Whether diagnosis information has been added manually (e.g. by the patient) or via an integrated data feed, the API will return all related data for a chosen patient that the API authorising clinician has medical record access for. There is also the option to only return diagnosis data for entries entered after a chosen date.

API Name

Brief Description

API Type

Scope

Parameters

Output Overview





GET /v2-beta/diagnoses/forPatient/{patientId}



Returns all recorded diagnosis for a chosen patient (past and current)

Patient PKB ID



Optionally, a date can be given to only return diagnosis with an entered date from that point forward.

Information for every recorded diagnosis.  Including the code, name, date of onset, date entered, reactions and severity. 

REST

Clinician

See our help manual for information on how Diagnosis information is supported within PKB:

https://manual.patientsknowbest.com/patient/diagnoses

Technical information on how data can be sent via an HL7 message feed can be found here:

https://pkbdev.atlassian.net/wiki/spaces/api/pages/3365078168/ADT+A28

Test Results

Whether test results have been added manually (e.g. by the patient) or have been sent in via an integrated data feed, the API will return all the available results for a chosen patient. The test result data contains identifying information for the test, along with all the related result(s) values (there may be multiple returns where a test is undertaken multiple times) and any identifying codes.

API Name

Brief Description

API Type

Scope

Parameters

Output





GET /v1/tests/results/all



Returns all tests results for a patient



Patient selected is defined from the access code used to generate the API token.

Returns all data for every test result recorded in PKB for the patient.

Each individual test is returned and for each one the fields providing name, description, notes, result and code data are displayed.

REST

Patient

GET /v1/tests/results/forPatient/byTestIds



Returns all tests results for a patient.  NB - Filtering of results by LOINC id is supported

Patient PKB ID



Optionally - LOINC id (singular or multiple)

REST

Clinician

See our help manual for information on how Test result information is supported within PKB:

https://manual.patientsknowbest.com/patient/tests

Technical information on how Test result data can be sent via an HL7 message feed can be found here:

https://pkbdev.atlassian.net/wiki/spaces/api/pages/3364848908/Laboratory

Messages

Returns the messages sent between a patient and clinician(s) via the PKB interface. Messages are returned within the context of a conversation, which ensures that the whole conversation thread is provided.

An additional API (GET /attachments/{id}) is also available to enable the extraction of any document attachments linked to a message.

API Name

Brief Description

API Type

Scope

Parameters

Output





GET /messages/after/{timestamp}



Returns conversations between a patient and clinician.  Includes all messages in the thread, along with attachment details.

Message Date -  returns any conversations where a message has been sent after the specified date.



Set a limit for the number of conversation threads returned.

Conversations between the patient and all clinicians



Returns all messages in the conversation, displaying content, attachment details, sender and recipient info (including name) and message status 

REST

Patient

Conversations between the clinician and any patients. Returns the same message data as above.

Clinician

See our help manual for information on how Test result information is supported within PKB:

Patient perspective - https://manual.patientsknowbest.com/patient/events-messages

Clinician perspective - https://manual.patientsknowbest.com/professional/messages

Finding Patient PKB ID with Demographics

The API calls below make it possible to extract the demographics, basic metrics and the internal PKB ID information for an individual patient or all patients a clinician or coordinator have access to.

The internal PKB ID is a parameter required for a number of the PKB APIs, so the use of the below APIs often form part of data extraction workflows.

API Name

Brief Description

API Type

Scope

Parameters

Output





GET /v2-beta/users/byNationalId/{nationalId}/{nationalIdType}



Returns the PKB id, patient metrics and demographics for a chosen patient. Note - can support searching across the whole org or network with coordinator scoped access.

Patient national identifier (e.g. NHS number)

Internal PKB ID



Patient metrics such as height and weight.



Patient demographics including name, dob, address, contact details (i.e. email, phone number), gender, date deceased (where applicable)

REST

Patient



Clinician



Coordinator

GET /v1/users/self/patients



Returns the PKB id, patient metrics and demographics for all patient records in their list of accessible patient records.

n/a - as derived by the access to data defined by the Scope (e.g all patient records a coordinator has access to).

Internal PKB ID



Patient metrics such as height and weight.



Patient demographics including name, dob, address, contact details (i.e. email, phone number), gender, date deceased (where applicable)

REST

Clinician



Coordinator

Technical information on how patient demographic data can be sent via an HL7 message feed can be found here:

https://pkbdev.atlassian.net/wiki/spaces/api/pages/3365078168/ADT+A28

 

© Patients Know Best, Ltd. Registered in England and Wales Number: 6517382. VAT Number: GB 944 9739 67.

This API specification and design is licensed under a Creative Commons Attribution 4.0 International License.