Articles in this section

Introduction

  • Updated

Background

Using the standard API endpoints, this type of logic is often required when integrating with PainChek:

if RCS record is updated:  
  get details from RCS
  get details from PainChek (get)

  if record not in PainChek:
    create record in PainChek (post)

  else:
    if rcs details <> PainCheck details
      update PainChek record (patch)
    else:
      Nothing to do, records are in sync

This pattern tends to repeat, regardless if we are referring to residents/patients, sites/facilities, admissions or other entities.  It requires that the RCS (Residential Care System) make three different calls to PainChek and also to make decisions about which PainChek record is the appropriate one to update (if any). 

Proposed Pattern

To simplify integrations with PainChek, we provide custom integration endpoints that allow a partner to call PainChek as follows:

if RCS record is updated:  
  get details from RCS
  post to the appropriate integration endpoint   # this is a single call the the PainChek API

Under this approach, a single call to the PainChek API is required.  The responsibility for determining if there is an existing PainChek record, and if so, detecting which details have changed, resides with PainChek. 

If the RCS has any reason to suspect that the RCS record is not up-to-date, they can simply invoke the check/create/update call and let PainChek figure out what to do.

Endpoints

The following endpoints have been created to support PainChek integration:

endpoint
 Main Purpose
Payload sample
Response sample
Soft-Matching
More details

api/integration/patients/

Check, Create and Update a Resident (or Patient) record 

 
{
  "external_id": "123456",
  "first_name":"Fred",
  "last_name":"Smith",
  "gender":"m",
  "birth_date": "1940-01-20",
  "deleted_reason": null
}
 
{
  "update_status": "no_change",
  "description" = "Record up to the date.",
  "data": {`
    "uuid": "b416d163-2e6e-4fdb-9a22-c1f0f9ae6b26",
    "license": "a89e0cc1-fd90-4721-b09b-7f527f5ff626",
   "license_name": "A89E0CC1-FD90/ePAT Technologies Ltd/2018-08-25",
    "first_name": "Fred",
    "last_name": "Smith",
    "nickname": null,
    "gender": "m",
    "birth_date": "1940-01-20",
    "death_date": null,
    "created_at": "2017-11-13T07:07:58.267644Z",
    "modified_at": "2017-11-13T07:07:58.268769Z",
    "deleted_at": null,
    "deleted_reason": null,
    "update_stamp": 767,
    "image": null,
    "external_id": "123456",
    "training_record": false
  }
}

first_name,
last_name,
birth_date

 Managing Patients

api/integration/sites/

Check, Create and Update a Site (or Facility) record 

 
{
  "external_id": "112233",
  "type": 1,
  "name": "St George Hospital",
  "phone":"(02) 9999 8000",
  "email": "info@stgeorge-hospital.com.au",
  "address": "10 Jones Road",
  "city": "Kogarah",
  "postcode" : "2999",
  "country": "AU"
}
 
{
  "update_status": "record_created",
  "description": "Record created in PainChek",
  "data": {
    "uuid": "c186cf8e-708c-479e-acbd-d534f54b7e89",
    "license": "a89e0cc1-fd90-4721-b09b-7f527f5ff626",
    "license_name": "A89E0CC1-FD90/ePAT Technologies Ltd/2018-08-25",
    "type": 1,
    "name": "St George Hospital",
    "phone": "(02) 9999 8000",
    "email": "info@stgeorge-hospital.com.au",
    "address": "10 Jones Road",
    "postcode": "2999",
    "city": "Kogarah",
    "state": null,
    "country": "AU",
    "num_beds": null,
    "created_at": "2017-11-17T04:47:43.034893Z",
    "modified_at": "2017-11-17T04:47:43.035970Z",
    "deleted_at": null,
    "update_stamp": 68,
    "external_id": "112233"
  }
}
 name Managing Sites

api/integration/admissions/

Check, Create and Update an Admission record 

 
{
 "patient_external_id":"123456",
 "site_external_id": "112233",
 "start": "2017-11-24T08:21:00+10",
 "room": "123",
 "bed": "A",
 "ward": "East"
 }
 
{
  "update_status": "record_updated",
  "description": "Record updated in PainChek",
  "data": {
    "uuid": "2b752af7-59ca-4e69-bbf0-2b1d7877bd49",
    "patient": "e1b2b350-23f1-4b8b-a98f-fff9b04ee604",
    "user": "c5fff8fd-e022-4ba4-a35d-ddee6b9fa276",
    "site": "c186cf8e-708c-479e-acbd-d534f54b7e89",
    "institution": "c186cf8e-708c-479e-acbd-d534f54b7e89",
    "start": "2017-11-24T08:21:00+10:00",
    "end": null,
    "unit": null,
    "room": "123",
    "bed": "A",
    "ward": "East",
    "created_at": "2017-11-23T22:45:44.521774Z",
    "modified_at": "2017-11-23T22:45:44.522816Z",
    "deleted_at": null,
    "update_stamp": 283
  }
}
 n/a Managing Admissions

Supported Methods

The integration endpoints on support the POST method.  Other methods (PATCH, DELETE, etc) are not supported.

Payloads

The payload used to call the endpoints is the same as would be used to call when POSTing a new record using the regular API endpoints (see the links in the "More details" column in the table above).  

However, the "external_id" field is mandatory with the integration endpoints (they are optional with "regular" endpoints).  The "external_id" is the unique identifier for the record, as recorded in the RCS.  In the case of the api/integration/admissions/ endpoint, both the patient (patient_external_id) and the site (site_external_id) external_ids must be supplied.  See Using External Ids for more details on external_ids.

Responses

The response returned from calling these endpoints is similar to that returned when POSTing a new record using the regular API endpoints (see the links in the "More details" column in the table above).  

However, that standard response is returned in a "data" object.  We also add 2 root-level return items:

  • "update_status" to indicate if PainChek performed an update (or not). One of:
    - no_change
    - record_created
    - record_updated

  • "description" which corresponds to the "update_status"

Special Use Cases

There are a number of special use cases that apply to the integration endpoints: