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 |
{ |
{ |
first_name, |
Managing Patients |
api/integration/sites/ |
Check, Create and Update a Site (or Facility) record |
{ |
{ |
name | Managing Sites |
api/integration/admissions/ |
Check, Create and Update an Admission record |
{ |
{ |
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:
- Ending an admission: The "admissions" endpoint can also be used to end the current admission - see Integration Endpoints - Ending an Admission.
- Archiving Residents: The "patients" endpoint can also be used to archive (or unarchive) the current admission - see Integration Endpoints - Archiving a Resident
- Updating a Residents Avatar: The "patients" endpoint can also be used to update (or remove) the avatar (profile image) for a resident - see Integration Endpoints - Updating Avatars