The "patients" endpoint (api/integration/patients/) is typically called with the resident details - e.g. this type of payload:
{ "external_id": "123456", "first_name":"Fred", "last_name":"Smith", "gender":"m", "birth_date": "1940-01-20" }
It is, however, possible to supply either of the following fields in order to set (or update) the patients' avatar:
-
"image_from_url" - a URL pointing to an image
-
"image_encoded" - a base 64 encoded image
For example, to update a patients image using a URL, use:
{ "external_id": "123456", "image_from_url": "http://my_server.com/images/123456.jpg" }
For example, to update a patient's image using a base64 encoded image, use:
{ "external_id": "123456", "image_encoded": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAA21BMVEX////p6ene07v8/Pzb0Lby8vLYzrGvmnf29vbu7u7h1r3Hx8f27+bR0dH//+/m5ubu5Nj69e9UVVkjIyO8vLywnX/n3MA/QUfx4dL/+uY2NDVHR0k/PkHo28MrLTKWj4hlZWXOv6Wvppa+taf47t/n3cizoYbu48jPxrgkJCn88+H56tFPMytOTlDI4fBeXmDS7v+zp5PDspXLu6OooJhCPTxPTUzZ0MK4qaaGgn6+qIP//+ofHSDRvp54c3B3a1i4yNPg9/+musWkkHJFJx6gmZnq+v9AIxmXpK5mPfMCAAACaElEQVQ4jV2T7XaiMBCGQ5QiUISCFAhBRQIomHWlra0fa6vddXv/V7STgOfYfX7AzLxvmCQkCKHe1PNID6HBa6NJmtdBW51CVUSEkPFUbfy0jIZAVKZ+o07HUBYO0Ckl5H2XDCsWSlg1fNy9QJkKh+rFEH3+iqrQuX+Q3Dsh2x/BEMeeihSPx/GnEYUhyPcSeIfhcEtjzj0FKS7lrf6NMNxPYk5dBanW4v3XPmQwu4er+gAJq4fbDbdU1FNGu6h63niHw8szEzJ7fjkcvM2s2u9MRSy/SKLjmNCP0+l8ZMDxfDp9wMqPUVLAhiDdH04IJefL5XT62jK2/YLocobSZOjrsA/zNNrQmKA/f3+gC6kqchERIjHlUTrviQ4hLJii5fJnD9EqXLQRgVoleuhalQdcGpa/0YLl4zaiUKsrTUeKVtUB57H1tly+mXFdx6aILNilAAyKMJQr7nIX5qMEWZ5ngQIzdznnbtkZkgl3XdjwgM5qYEaDIBaVSXI1YFfAeZatOF9lGQwW4M7AjGQOgrvFNYzkcVDjLbhX88RgwlDg3EiSsizhMYY/T8dllxo5LhSkZ2mIsSFJZmSxILOkzTAO00xHA0tjuMMQI8vEuOZMswaoZ0OPfmcwrmMFfehgw9/UTc3BfYHx2GHIFDuaqYtTba8bpzUEHa3Bada2PPeq5afO7Sc6PfXhPMmLoZjgwHf9G+4w6PI8SYdt+o2T392QO41v2p0uHWu/7+S4VXHu9P31jS66WKPCf8KOBD/5xchSbnRwqLY5mhXt5S1mI9NWv+nCotuWOZKYlq3/L0vLQFck+uBG/gf0GFSpaPYy5wAAAABJRU5ErkJggg==" }
Note
The "image_from_url" and "image_encoded" parameters should only be passed in calls to the "patients" endpoint when the RCS has detected a change in the avatar.
Each time a call is made to the "patients" endpoint with one of those two parameters passed, PainChek will process the image, resulting in a significant load on both the RCS and PainChek systems (the RCS system has to stream the image and the PainChek system has to download that stream and save the resulting image). If such calls are only made when the avatar is known to have changed on the RCS, this load should not adversely impact either system.
The following limits and notes apply:
-
Images must be in jpeg or png format
-
Images are limited to 2MB in size. An error will be returned if the image downloaded from the URL or if the base64 encoded data exceeds this size.
-
When a URL is supplied (using "image_from_url"), it must publically accessible (without any form of authentication)
-
When a URL is supplied, PainChek will download the image from the public URL and store a local copy of it.
If the image stored at the URL were to change in future, PainChek would continue to serve its' original version. The "patients" endpoint would need to be called again in order to update PainChek to the new version of the image.
-
Use either "image_from_url" or "image_encoded" in a request, but not both. An error is returned if both are supplied.
-
When "image_from_url" is supplied, the base64 encoded data needs to be prefixed with "data:image/png;base64," or "data:image/jpeg;base64," as appropriate.
Supply either "image_from_url" or "image_encoded" with a value of null if you wish to delete the current avatar - e.g.:
{ "external_id": "123456", "image_from_url": null }
It is acceptable to pass both the standard patient details and the avatar details in the one call - e.g.:
{ "external_id": "123456", "first_name":"Fred", "last_name":"Smith", "gender":"m", "birth_date": "1940-01-20", "image_from_url": "htttp://my_server.com/images/123456.jpg" }
In this case, the patient record would be checked and updated (to ensure, for instance, the first name is "Fred") and the patients' image would be updated (to the image found at "http://my_server.com/images/123456.jpg").
The following table summarises the use of the "image_from_url" and "image_encoded" fields
Use Case |
Payload |
PainChek Impact |
Sample Payload |
---|---|---|---|
The RCS patient record has been updated, but the avatar is unchanged |
Neither field supplied in the payload |
The patient record is updated, but the avatar is not |
{ "external_id": "123456", "first_name":"Fred", "last_name":"Smith", "gender":"m", "birth_date": "1940-01-20" } |
The RCS avatar is updated and there is a publicly accessible URL for the avatar |
"image_from_url" is supplied (with a URL) |
Avatar is updated |
{ "external_id": "123456", "image_from_url": "http://my_server.com/images/123456.jpg" } |
The RCS avatar is updated, but there is no publicly accessible URL available |
"image_encoded" is supplied (with a base64 encoded image) |
Avatar is updated |
{ "external_id": "123456", "image_encoded": "data:image/jpeg;base64,base64_data..." } |
The RCS avatar is removed |
"image_from_url" or "image_encoded" is supplied with a null payload |
Existing avatar (if any) is deleted |
{ "external_id": "123456", "image_from_url": null } |
Both the RCS patient record and avatar are updated |
Resident details plus "image_from_url" or "image_encoded" |
The patient record and the avatar are updated |
{ "external_id": "123456", "first_name":"Fred", "last_name":"Smith", "gender":"m", "birth_date": "1940-01-20", "image_from_url": "http://my_server.com/images/123456.jpg" } |