NAV
Details

Introduction

Welcome to the SmartFlow API! The SmartFlow API is organized around REST and is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors.

By using the SmartFlow API the third-party software (hereinafter EMR) can create, edit and read patient data, as well as receive different events from the SmartFlow services.

Environment Setup

API Sandbox Endpoint:

https://sandbox.smartflowsheet.com/api/v3

API Production Endpoint:

https://www.smartflowsheet.com/api/v3

To make the SmartFlow API as explorable as possible, we provide test-mode API keys as well as live-mode API keys. The test-mode API keys should be used in our sandbox environment, while live-mode keys should be used in our production environment.

To retrieve the events from SmartFlow you should register two webhooks: one for sandbox environment, and another for production. SmartFlow then sends an HTTP POST request with the event object to the URLs you provided.

To receive your API keys, please prepare the urls that will be used for the webhooks, and send us a request at info@smartflowsheet.com.

Your API keys carry many privileges, so be sure to keep them secret!

You can find the API endpoints for sandbox and production in Details section in the right part of this page.

You may also register a custom webhook per each clinic account (see Register custom webhook for more information).

Clinic Setup

Sandbox Home and Settings pages:

https://sandbox.smartflowsheet.com
https://sandbox.smartflowsheet.com/Settings?page=emr

Production Home and Settings pages:

https://www.smartflowsheet.com
https://www.smartflowsheet.com/Settings?page=emr

Our API is intended for use with a registered clinic account. You can register a clinic account on the Home page both in sandbox and production environments.

After a new clinic account has been registered in SmartFlow, there is a clinic API Key automatically generated. This key should be used to authenticate against our API (see Authentication for more information). It is also used with the Events sent to EMR to identify the account.

The clinic API key can be obtained by user from Settings page on our web-site after registration. We assume that SmartFlow user will be able to register this key in EMR's user interface.

Basic Use-Cases

Sample Project: https://github.com/IDEXX/public-sfs

This section describes the basic integration workflows.

Please download a sample project from GitHub that contains several examples of the SmartFlow API usage.

Creating Patients

Creating patients from EMR into SmartFlow has two obvious benefits:

  1. Saving the clinic's staff time. Almost always the information required to create a patient in SmartFlow has been already entered into EMR user interface upon patient addmission to the hospital. Using /hospitalization API method it is possible to transfer that information into SmartFlow and we will automatically create a new patient record for the user.

  2. Automatically collecting charges for the patient. SmartFlow will not send medical records for the patients created from SmartFlow user interface. To receive medical records for the patient you will need to create a patient in SmartFlow explicitly using /hospitalization API method.

Usually, what we recommend is that you place 'SmartFlow' button on your user interface. Clinic staff could then press it when they are ready to create a patient's flowsheet (usually when a doctor decides to leave a patient in the hospital). Before creating a patient in SmartFlow, you may want to allow a user to select a treatment template and department for the patient. After the required treatment template and department has been selected, you should use this API to create patient record in SmartFlow.

After the patient has been submitted to SmartFlow, you may want to query the patient's hospitalization status using this API. With its help, you can get some additional information, e.g. patient image file to update your user interface. Or you may track the status of the patient, and as soon as the patient has been discharged, you could download and attach to your medical records the set of files related to the patient, e.g. the flowsheet report.

Discharging Patients

At the end of hospitalization, the clinic staff will usually discharge the patient. During this step, SmartFlow generates a set of documents (in pdf format) that your practice management software might want to attach to the patient record. The list of documents to attach is determined by the user on the Settings/Documents Management page.

Documents Management in Smart Flow

From Settings / Documents Management page (see image below) the user will be able to turn on/off exporting of the documents after patient discharge. If the user disables EXPORT DOCUMENTS TO EMR option then:

If the user sets MERGE REPORTS INTO ONE PDF setting to YES, then hospitalization.reportPath as well as download the flowsheet report API will return the merged pdf file, that will include all the documents specified in Files To Retain After Discharge section. This option allows you download only one pdf file that will include all documents chosen by the user rather than implementing all Smart Flow APIs mentioned above to access each document separately. More detail about this functionality is available in the Clinic Settings section.

Discharging Patients

There are two options for discharging the patient in SmartFlow:

  1. The user initiates discharge of the patient from SmartFlow user interface. In this case, SmartFlow will prepare all pdf reports and send the hospitalization.discharged event that your EMR may consume, download the appropriate pdf files from SmartFlow and attach them to the patient records.

  2. The user initiates discharge operation from the EMR side. In this case, the EMR should call discharge API to initiate discharging of the patient in SmartFlow. After the successful call to this API, the response will include the hospitalization object with the status field equal to discharged, but the reportPath field will be empty. At this point, all patient reports are not generated yet - SmartFlow only initiated the document generation process. To download the files, you have a couple of implementation strategies:

    • wait for the hospitalization.discharged event and then start downloading the documents
    • wait at least 15 seconds and then call the get hospitalization API. If the reportPath is not empty, then you may start downloading the reports
    • add some sort of "Download patient documents" button that will call the get hospitalization API, and if the reportPath is not empty, then the download may start. Otherwise, propose to repeat the operation later because the documents are not ready yet

Working with the Forms

Smart Flow provides a feature called Customised Hospitalization Forms. These give the user the ability to digitalize the majority of your paper forms, such as:

To make use of these forms and understand how this feature works, please read this article. There are two types of forms in Smart Flow that can be created as follows:

  1. those that could be used to create a patient in Smart Flow (e.g. Admission form). These forms have Show on Main Screen setting set to YES on Settings/Forms web page
  2. those that do not provide such an option, but rather can be added to the existing patient from the Smart Flow user interface

Creating Patients from Forms

By default SmartFlow provides a couple of forms that allow you to create patients from the “Smart Flow” iPad app. This means clients have the ability from the iPad to fill out their own information, take a photo of their pet, enter a reason for their visit and update and/or enter the name of their regular clinic from the waiting room. Upon completion of the form, the patient is created in Smart Flow and appears on the whiteboard.

As soon as the patient is created from the form, SmartFlow will notify the EMR by sending hospitalizations.created and forms.created events. You might want to consume and handle these events to:

There are three steps that should be followed to get client’s data entered on the form:

  1. The EMR should consume the hospitalizations.created event that is sent from SmartFlow as soon as a patient is added from the form. The hospitalization object will be provided with the event. When the event is received both the client and patient records should be created in the EMR.

  2. In a second step, you should attach your internal records to SmartFlow hospitalization. This is required to receive all other types of events related to this patient, as well as to be able to use any hospitalization API.

  3. Finally, SmartFlow will send the forms.created event that you should consume to get the rest of the data entered by the client during the check-in process.

Editing Forms Notifications

When the user edits (changes the content of the form or its status to finalized) or deletes a form then SmartFlow fires the forms.updated event. When the user finalizes the form then SmartFlow generates a pdf report for this form.

Parsing Custom Forms and Properties

SmartFlow allows users to create a custom set of forms and properties from the Settings/Forms web page. If you want to parse the data from these custom forms then you should utilize Internal Name attributes when creating forms and properties.

The value of Internal Name attribute ('checkinform' on a picture above) of the form will be transferred with the name property of the form object.

The value of Internal Name attribute of the property ('pet_name' on a picture above) will be transferred with the name property of the formfield object.

Inventory Import

The most common reason to integrate with the SmartFlow services is to be able to receive medical records from SmartFlow upon treatment execution. This information can be used to automatically collect charges for the inventory items stored in EMR database.

In order to accomplish this goal the SmartFlow API provides a possibility to import inventory items from the EMR system into SmartFlow. We will store external identifiers for the inventory items during inventory import, and will provide these identifiers back to EMR with the medical records information entered during treatment execution. In this way EMR will be able to associate entered medical record with the correct inventory item, and create a charge.

To import inventory you may use next API methods:

The later API method works asynchronously and sends inventoryitems.imported event to the url specified with the webhook.

After the import is finished, the user can start using the inventory immediately by adding imported items to the patients` flowsheets. For the inventory items being added for the first time, Smart Flow will display a popup window. In this window, the user can adjust the display name of the item, and which SmartFlow section (monitoring, activity, fluid, medication, or procedure) it should be attached to. If you have included a concentration with the item, the concentration will automatically populate, making it much easier for the user to set these items. The concentration number will automatically be appended to the beginning of the medication name. This facilitates differentiating concentrations of the same item from screens in Smart Flow where there is a character limit.

View on the web interface: View on the iPad:

Receiving Medical Records

Receiving medical records information from SmartFlow provides an opportunity to automatically collect charges for the inventory items stored in your database. Please make sure to import inventory into SmartFlow before that.

Medical record information is sent to EMR with the treatment.record_entered event (or treatments.records_entered event when multiple records has been entered).

Here is an example:

Example inventoryitem object imported with /inventoryitem API:

{
    "id": "external-inventory-id",
    "name": "Cefazolin 100",
    "concentration": 100,
    "concentrationUnits": "mg",
    "concentrationVolume": "ml"
}

Example treatment.record_entered event object sent to webhook:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "treatment.record_entered",
    "object": {
        "objectType": "treatment",
        "name": "Cefazolin 100",
        "inventoryId": "external-inventory-id",
        "hospitalizationId": "external-hospitalization-id",
        "treatmentGuid": "internal-sfs-treatment-guid",
        "time":"2013-03-28T14:23:56.000+00:00",
        "status": "added",
        "qty": 2.25,
        "volume": 2.25,
        "value": "IZ",
        "units": "ml",
        "doctorName": "Dr. Ivan Zak"
    }
}
  1. EMR imports Cefazolin 100 mg/ml inventory item with the /invetoryitem API method.

  2. Then doctor creates a patient in the EMR, the patient record is transferred into SmartFlow with the /hospitalization API method and new patient automatically appears on a SmartFlow whiteboard.

  3. After the patient is created in SmartFlow, doctor adds Cefazolin 100 mg/ml to the flowsheet, and sets the dosage to 25 mg/kg (see image below).

  4. When Cefazolin 100 mg/ml is given to the patient, SmartFlow sends medical record information with the treatment.record_entered event to the EMR webhook, and transfer the volume of the medication dispensed. In this case it will be 2.25 ml.

You can find the example JSONs in Details section in the right part of this page. As you can notice the object transferred with the treatment.record_entered event contains the inventoryId field that is equal to the id field of the inventory item imported into SmartFlow with the /inventoryitem API method. In this way EMR is able to associate entered medical record with the correct inventory item, and create a charge.

Billing for a Surgery

When the patient is admitted for surgery, SmartFlow provides access to the electronic anesthetic sheet feature. The anesthetic sheet allows medical staff to map the patient’s vitals and calculate pre-op and emergency drugs. After the surgery is over, the clinic staff finalizes the anesthetic sheet to:

To make it easier for your EMR to calculate billing for the surgery, SmartFlow sends the anesthetics.finalized event with the included anesthetic object as soon as the user presses the 'Finalize Anesthetiс Sheet' button on the iPad.

Authentication

GET /inventoryitems HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

You authenticate to the SmartFlow API by providing both EMR API key and clinic API key in all API requests to the server in a header.

emrApiKey: emr-api-key-received-from-sfs

clinicApiKey: clinic-api-key-taken-from-account-web-page

You must replace emr-api-key-received-from-sfs with your personal emr API key and clinic-api-key-taken-from-account-web-page with the clinic API key taken from the Settings web-page.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

We also recommend providing the time zone name with the timezoneName header of the HTTP request (e.g. timezoneName: Europe/Helsinki). Please visit this web-page for the complete list of the time zone names.

Errors

HTTP Status Code Summary

200 OK - Everything worked as expected.

204 No Content - May happen when trying to access the patient report that was not generated for the patient.

400 Bad Request - Often missing a required parameter.

401 Unauthorized - No valid emrApiKey or clinicApiKey provided.

402 Payment Required - If reached clinic`s patient limit. This may happen when trying to create a new patient, but clinic`s subscription expired.

403 Forbidden - If trying to update clinic with different clinicApiKey.

404 Not Found - The requested item doesn`t exist.

409 Conflict - If the request with the same “id“ (e.g. “inventoryitems.id“) has been already received and is currenly under processing. Normally means that second request is not needed.

429 Too Many Requests - May happen when trying to upload a lot of inventory items. Need to slown down. 

465 Access to the Document Denied - Heppens when manager turns off the document on the `Settings / Documents Management` page.

500, 502, 503, 504 Server errors - something went wrong on SmartFlow`s end.

SmartFlow uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with SmartFlow's servers.

Not all errors map cleanly onto HTTP response codes, however. Please refer to the documentation on a particular API method for the details on possible HTTP codes and responses.

The Error object

GET /inventoryitem HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
HTTP/1.1 404 Not Found
Accept: application/json

{
   "Message" : "Inventory item not found"
}

SmartFlow may send the Error object in the response to the API methods that failed with the 4xx HTTP status codes.

Also, SFS expects EMR to send the Error object (optionally) in the response to the event calls that fail together with the 4xx HTTP status codes.

Attributes

Parameter Type Description
Message String The message describing the cause of fail

Clinic Settings

This API allows to get the settings of a particular clinic. You may want to use this API to check these settings before downloading reports for discharged patients.

The clinicSettings object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events. Should be assigned clinicSettings value
documentsManagement documentsManagement The object containing the details of the clinic's documentsManagement settings

The documentsManagement object

The documentsManagement object gives you access to the clinic's settings on the Documents Management settings page.

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events. Should be assigned documentsManagementSettings value
exportToEmr Boolean True if the setting to "Export documents to EMR" is set as "Yes" in the SmartFlow UI. See Documents Management in Smart Flow for more information.
merge Boolean True if the setting to "Merge reports into one PDF" is set as "Yes" in the SmartFlow UI. See Documents Management in Smart Flow for more information.
retain Object Lists each document possibly generated for any hospitalization in SmartFlow, and whether the "FILES TO RETAIN AFTER DISCHARGE" setting is set to Yes (true) or No (false) for each.

Based on these details, you can determine what to do next.

Here are the reports that will be created for every hospitalization, with references to their API documentation:

For the following real-time reports, it's best practice to download the reports when the Finalized event is sent, which includes the reportPath (and recordsReportPath for anesthetic) if the documentsManagement settings indicate you can download those reports.

Retreive clinicSettings

Example Request:

GET /clinicsettings HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
{
    "objectType":"clinicsettings",
    "documentsManagement":
    {
        "objectType":"documentsmanagementsettings",
        "exportToEmr":true,
        "merge":true,
        "retain":
        {
            "medical_records":true,
            "billing":true,
            "notes":true,
            "flowsheet":true,
            "anesthetic":true,
            "anesthetic_records":true,
            "checkinform":true,
            "surgicalconsentform":true,
            "Allergy Form":true,
            "dentalcharts":true
        }
    }
}

Anesthetics

Anesthetic is an abstraction used in SmartFlow to represent the anesthetic sheet data. The main purpose of this abstraction is to provide the possibility to download anesthetic sheet report when it is finalized or after the patient discharge event.

The anesthetics object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object returned with the SmartFlow API. Equals to anesthetics
id String Required. Identificator of the object.
anesthetics Array The array of anesthetic objects. See description of the anesthetic object below

The anesthetic object

Attributes

Parameter Type Description
objectType String Describes the type of the object transferred with the SmartFlow API. Equals to anesthetic
hospitalizationId String EMR internal ID of the hospitalization
surgeryGuid String A unique internal identifier of the surgery. This field will be transferred with the SmartFlow events.
dateStarted Date Optional. Anesthesia start time. Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
dateEnded Date Optional. Anesthesia end time. Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
reportPath String Optional. The path to the anesthetic sheet report file that has been generated during finalization of the anesthetic sheet.
surgeon Medic Optional. The medic object that corresponds to the doctor assigned to the anesthetic sheet.
anesthetist Medic Optional. The medic object that corresponds to the anesthetist assigned to the anesthetic sheet.
assistant Medic Optional. The medic object that corresponds to the assistant assigned to the anesthetic sheet.

Finalize anesthetic event

Example of anesthetics.finalized event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "anesthetics.finalized",
    "object": {
        "objectType": "anesthetics",
        "id": "sfs-operation-id",
        "anesthetics": [
            {
                "objectType": "anesthetic",
                "hospitalizationId": "emr-hospitalization-id",
                "surgeryGuid": "sfs-surgery-guid",
                "dateStarted": "2015-11-04T17:23:07.707+00:00",
                "dateEnded": "2015-11-04T19:17:03.463+00:00",
                "reportPath": "https://pdf-anesthetic-sheet-report-webfile-path",
                "recordsReportPath": "https://pdf-anesthetic-records-report-webfile-path",
                "surgeon": {
                    "objectType": "medic",
                    "medicId": "emrIdm4",
                    "name": "Dr. George",
                    "medicType": "doctor"
                },
                "anesthetist": {
                    "objectType": "medic",
                    "medicId": "emrIdm3",
                    "name": "Ivan",
                    "medicType": "doctor"
                },
                "assistant": {
                    "objectType": "medic",
                    "medicId": "emrIdm4",
                    "name": "Dr. George",
                    "medicType": "doctor"
                }
            }
        ]
    }
}

As soon as one or several anesthetic sheets have been finalized in the SmartFlow app on an iPad, SmartFlow will notify the EMR by sending anesthetics.finalized event. The anesthetics object will be transferred with the event.

Retreive anesthetic sheet and anesthetic records reports

Example Request:

GET /hospitalization/{hospitalizationId}/anesthetics HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
{
    "objectType": "anesthetics",
    "id": "sfs_operation_id",
    "anesthetics": [
        {
            "objectType": "anesthetic",
            "hospitalizationId": "emr-hospitalization-id",
            "surgeryGuid": "sfs-surgery-guid",
            "dateStarted": "2015-11-04T17:23:07.707+00:00",
            "dateEnded": "2015-11-04T19:17:03.463+00:00",
            "reportPath": "https://pdf-anesthetic-sheet-report-webfile-path",
            "recordsReportPath": "https://pdf-anesthetic-records-report-webfile-path",
            "surgeon": {
                "objectType": "medic",
                "medicId": "emrIdm4",
                "name": "Dr. George",
                "medicType": "doctor"
            },
            "anesthetist": {
                "objectType": "medic",
                "medicId": "emrIdm3",
                "name": "Ivan",
                "medicType": "doctor"
            },
            "assistant": {
                "objectType": "medic",
                "medicId": "emrIdm4",
                "name": "Dr. George",
                "medicType": "doctor"
            }
        },
        {
            "objectType": "anesthetic",
            "hospitalizationId": "emr-hospitalization-id",
            "surgeryGuid": "sfs-surgery-guid",          
            "dateStarted": "2015-11-04T17:23:07.707+00:00",
            "dateEnded": null,
            "reportPath": null,
            "recordsReportPath": null,
            "surgeon": {
                "objectType": "medic",
                "medicId": "emrIdm4",
                "name": "Dr. George",
                "medicType": "doctor"
            },
            "anesthetist": {
                "objectType": "medic",
                "medicId": "emrIdm3",
                "name": "Ivan",
                "medicType": "doctor"
            },
            "assistant": null
        }
    ]
}

This method allows to download all anesthetic sheet reports and anesthetic records reports related to some hospitalization from SmartFlow.

Specify the hospitalizationId of the hospitalization object in the EMR. Use the same hospitalizationId that was supplied when hospitalization had been created.

Dental Charts

Dental Chart is an abstraction used in SmartFlow to represent the Dental Chart data. The main purpose of this abstraction is to provide the possibility to download dental chart report when it is finalized or after the patient discharge event.

The dentalcharts object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object returned with the SmartFlow API. Equals to dentalcharts
id String Required. Identificator of the object.
dentalcharts Array The array of dentalchart objects. See description of the dentalchart object below

The dentalchart object

Example of dentalchart object:

{

    "objectType": "dentalchart",
    "hospitalizationId": "emr-hospitalization-id",
    "dentalChartGuid": "sfs-dental-guid",
    "dateFinalized": "2019-11-04T17:23:07.707+00:00",
    "reportPath": "https://pdf-dental-chart-report-webfile-path",
    "media": [ 
        {
            "dentalChartMediaGuid": "sfs-dental-guid",
            "section": "before",
            "dateCreated": "2020-03-13T16:21:19.193+00:00",
            "filePath": "https://pdf-dental-chart-photo-1-webfile-path",
            "contentType": "image/jpg"
        }
    ],
}

Attributes

Parameter Type Description
objectType String Describes the type of the object transferred with the SmartFlow API. Equals to dentalchart
hospitalizationId String EMR internal ID of the hospitalization
dentalChartGuid String A unique internal identifier of the chart. This field will be transferred with the SmartFlow events.
dateFinalized Date Dental chart finalization time. Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
reportPath String The path to the dental chart report file that has been generated during finalization of the dental chart.
media Array Optional. The array of dental-media objects that correspond to the photos taken by the user on the dental chart.

The dental media object

Example of dental media object:

{
    "dentalChartMediaGuid": "sfs-dental-guid",
    "section": "before",
    "dateCreated": "2020-03-13T16:21:19.193+00:00",
    "filePath": "https://pdf-dental-chart-photo-1-webfile-path",
    "contentType": "image/jpg"
}

Attributes

Parameter Type Description
dentalChartMediaGuid String Describes the type of the object transferred with the SmartFlow API. Equals to dentalchart
section String "before" or "after", denoting the section where the user took the photo. This indicates whether the photo was taken before or after the dental procedures were performed.
dateFinalized Date Time photo was taken. Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
filePath String The path to the dental media file (photo) that has been taken by the user.
contentType string The content type of media file (e.g. image/jpg, video/mp4, etc...). For Dental, this is currently limited to image/jpg

Finalize Dentalchart event

Example of dentalcharts.finalized event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "dentalcharts.finalized",
    "object": {
        "objectType": "dentalcharts",
        "id": "sfs-operation-id",
        "dentalcharts": [
            {
                "objectType": "dentalchart",
                "hospitalizationId": "emr-hospitalization-id",
                "dentalChartGuid": "sfs-dental-guid",
                "dateFinalized": "2019-11-04T17:23:07.707+00:00",
                "reportPath": "https://pdf-dental-chart-report-webfile-path",
                "media": [ 
                    {
                        "dentalChartMediaGuid": "sfs-dental-guid",
                        "section": "before",
                        "dateCreated": "2020-03-13T16:21:19.193+00:00",
                        "filePath": "https://pdf-dental-chart-photo-1-webfile-path",
                        "contentType": "image/jpg"
                    }
                ],
            }
        ]
    }
}

As soon as a dental chart has been finalized in the SmartFlow app on an iPad, SmartFlow will notify the EMR by sending a dentalcharts.finalized event. The dentalcharts object will be transferred with the event.

Retreive dental chart and associated media

Example Request:

GET /hospitalization/{hospitalizationId}/dentalcharts HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"

This method allows to download all dental chart reports and associated media related to some hospitalization from SmartFlow.

Specify the hospitalizationId of the hospitalization object in the EMR. Use the same hospitalizationId that was supplied when hospitalization had been created.

Departments

This API allows to get the list of departments in the clinic. You may want to use this API to allow users to select a department before submitting a new patient into SmartFlow.

The department object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events. Should be assigned department value
departmentId Integer Required. The ID of the department. You should use this value to specify the department when creating a new hospitalization
name String Required. The unique name of department

Retreive existing departments

Example Request:

GET /departments HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
[
{
     "objectType":"department",
     "name":"Treatment Room",
     "departmentId":0
},
{
     "objectType":"department",
     "name":"Internal Medicine",
     "departmentId":1
}
]

Forms

The are three objects used by SmartFlow to notify EMR when forms are filled in:

All objects are sent with the asynchronous forms.created or forms.udpated events when one or several forms has been entered or changed.

The forms object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events (e.g. forms.created). Should be assigned forms value
id String Identificator of the object. Will be transferred to EMR with the forms.created event.
forms Array The array of form objects. See description of the form object below

The form object

Attributes

Parameter Type Description
objectType String Describes the type of the object transferred with the SmartFlow events (e.g. forms.created). Should be assigned form value
formGuid String Required. A unique internal identifier of the form
hospitalizationId String Hospitalization external id (which was provided with hospitalization creation)
name String A unique identifier of the form type. This value is specified on the Settings/Forms web page in the Internal Name attribute of the form (e.g. 'checkinform' on a picture below)
deleted Boolean True - if the form has been deleted by the user; otherwise - false
finalized Boolean True - if the form has been finalized by the user; otherwise - false. If the patient is created from the form, then this field will return true
reportPath String The path to the form pdf report file that has been generated during form finalization
title String The title of the form (e.g. "Admission form")
fields Array The array of formfield objects. See description of the formfield object below

<%= image_tag "images/formsetting.png" %>

The formfield object

Attributes

Parameter Type Description
objectType String Describes the type of the object transferred with the SmartFlow events (e.g. forms.created). Should be assigned formfield value
name String A unique identifier of the form field. This value is specified on the Settings/Forms web page in the Internal Name attribute of the property (e.g. 'pet_name' on a picture below)
title String Field label (the one that users sees while filling in the form field)
contentType String This field describes the type of content of the value field (e.g. text/plain, image/jpg)
value String The string value of the form field
values Array The array of string values selected from drop-down list with multiple selection option (If the array is not empty that value field above should be ignored.)

<%= image_tag "images/propertysetting.png" %>

Get patient`s forms

Example Request:

GET /hospitalization/emr-hospitalization-id/forms HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method allows getting all forms for the patient specified by hospitalizationId. This method returns the list of forms objects with empty fields. To get the form fields for each form please use the get form values API.

Get form values

Example Request:

GET /hospitalization/emr-hospitalization-Id/form/form-guid HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method allows getting all fields for the form determined by formGuid and hospitalizationId.

Retreive forms with events

Example of forms.created event JSON:

{
  "clinicApiKey": "clinic-api-key",
  "eventType": "forms.created",
  "object": {
    "objectType": "forms",
    "id": "sfs-operation-id"
    "forms": [
      {
        "objectType": "form",
        "formGuid": "sfs-form-guid",
        "hospitalizationId": "external-hospitalization-id",
        "name": "checkinform",
        "title": "Client Self Check-in",
        "fields": [
          {
            "objectType": "formfield",
            "name": "avatar",
            "title": "Avatar",
            "value": "https://attached-image-webfile-path",
            "contentType": "image/jpg"
          },
          {
            "objectType": "formfield",
            "name": "email",
            "title": "Your email",
            "value": "me@example.com",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "first_name",
            "title": "Your name",
            "value": "John",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "last_name",
            "title": "Last name",
            "value": "Doe",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "address",
            "title": "Address",
            "value": "105, 11th Ave",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "city",
            "title": "City",
            "value": "New York",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "state",
            "title": "State",
            "value": "NY",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "zip",
            "title": "Zip",
            "value": "10001",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "phone_home",
            "title": "Home phone",
            "value": "(111) 111-1111",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "phone_work",
            "title": "Work phone",
            "value": "(222) 222-2222",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "phone_cell",
            "title": "Owner's cell phone",
            "value": "(333) 333-3333",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "phone_co_owner",
            "title": "Co-Owner's cell phone",
            "value": "(444) 444-4444",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "phone_number_to_reach",
            "title": "Best number to reach you today",
            "value": "Home phone",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "pet_name",
            "title": "Your Pet's Name",
            "value": "Fluffy",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "weight",
            "title": "Weight (kg)",
            "value": "3.5",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "birth_date",
            "title": "Birth date",
            "value": "2016-07-16T19:20:30.000+00:00",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "breed",
            "title": "Breed",
            "value": "English Cocker Spaniel",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "sex",
            "title": "Sex",
            "value": "Male",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "family_veterinarian",
            "title": "Family veterinarian",
            "value": "Dr. Ivan Zak",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "clinic",
            "title": "Clinic",
            "value": "Best Pet Vet",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "visit_reason",
            "title": "What is the reason for your visit today?",
            "value": "Vaccination",
            "contentType": "text/plain"
          },
          {
            "objectType": "formfield",
            "name": "signature",
            "title": "Consent Form",
            "value": "https://attached-image-webfile-path",
            "contentType": "image/jpg"
          }
        ]
      }
    ]
  }
}

The forms.created and form.updated events are sent from SmartFlow when one or several forms were created or updated. SmartFlow will send forms object with all information entered into the forms.

Download the form report

Example Request:

GET /hospitalization/emr-hospitalization-id/formreport/form-guid HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method allows to download the form pdf report generated upon form finalization.

All the dates in the downloaded report will be represented in the time zone that you must explicitly specify in the timezoneName header of the HTTP request (e.g. timezoneName: Europe/Helsinki). Please visit this web-page for the complete list of the time zone names.

Specify the hospitalizationId of the hospitalization object in the EMR. Use the same hospitalizationId that was supplied when hospitalization had been created. Also specify the formGuid value that uniquely identifies the form. This value can be obtained from forms.created event or by fetching all the forms for the patient with this API.

Hospitalizations

Hospitalization is an abstraction used in SmartFlow to represent the patient record. As soon as patient is admitted in the hospital the Hospitalization object is created. In turn, the hospitalization object nests patient and client information. This information can be transferred and retrieved from SmartFlow using the patient object and the client object.

There are the hospitalizations and hospitalization objects used to create hosptitalizations in SmartFlow and receiving events from the SmartFlow services.

The hospitalizations object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events. Should be assigned hospitalizations value
id String Optional. Identificator of the object. Will be transferred to EMR with the SmartFlow events
hospitalizations Array The array of hospitalization objects.

This object will be sent with the hospitalizations.discharged event in case when multiple patients were discharged from the SmartFlow whiteboard.

The hospitalization object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events. Should be assigned hospitalization value
hospitalizationId String Required. EMR internal ID of the hospitalization
departmentIds Array Optional. Array of integers. A collection of departmentIds of the departments patient should be created at. If not specified then hospitalization will be created in the default department
hospitalizationGuid String Optional. A unique internal identifier of the hospitalization. This field will be transferred with the SmartFlow events.
dateCreated Date Required. Specifies the date and time of the patient arrival in the hospital. Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
treatmentTemplateName String Optional The name of the treatment template to be used for created hospitalization. If not specified then the "Default" template will be used.
temperatureUnits String Optional. Units for the temperature. Can be F or C. If not specified then clinic’s default temperature units will be used
weightUnits String Optional. Units for the weight. Can be kg or lbs. If not specified then clinic’s default weight units will be used
weight Double Optional. Weight of the patient
estimatedDaysOfStay Integer Optional. This value will be used to create requested number of days of hospitalization. If this value is not specified then by default 2 days will be created
fileNumber String Optional. The value of emr file number, that will be shown on a flowsheet. If not specified SmartFlow will populate it with hospitalizationId
caution Boolean Optional. Whether to show caution stripe on a flowsheet or not
deposit String Optional. Client deposit
doctorName String Optional. The name of the doctor on duty
medicId String Optional. Alternatively to specifying the doctorName field, you can provide the id of the medic object that corresponds to the doctor on duty, and has been registered with the appropriate API call
diseases Array Optional. Array of strings. A collection of diseases
cageNumber String Optional. The cage number. This value will be shown on the whiteboard near patient name.
color String Optional. The RGB hex color code (eg. #439FE0). This value is used to color patient`s info panel on the whiteboard and flowsheets.
reportPath String Optional. The path to the flowsheet report or the merged report file that has been generated during patient discharge. Please read about Documents Management in Smart Flow for more information
status String Optional. The status of the hospitalization. This field will be transferred with the SmartFlow events. Can be active, deleted or discharged.
patient Patient Required when creating new hospitalization. Optional if used to update existing hospitalization. The patient object
resuscitate String Optional Can be dnr, bls or als. Default value is bls.

The patient object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events. Should be assigned patient value
patientId String Optional. EMR internal ID of the patient
name String Required. The name of the patient
birthday Date Optional. Patient`s birthday. Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
sex String Required (use "U" for Unknown instead of sending blank). Patient's sex type. There is a set of standard predefined strings that specify the sex type of a patient: M, F, MN, FS, U
species String Optional. Patient's species
color String Optional. Patient's color
breed String Optional. Patient's breed
criticalNotes String Optional. The value of the critical notes that will be shown on a flowsheet.
customField String Optional. The value of the custom field that will be shown on a flowsheet.
imagePath String Optional. The path to the patient`s image file.
owner Client Required when creating new hospitalization. Optional if used to update existing hospitalization. The client object

The client object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events. Should be assigned client value
ownerId String Optional. EMR internal ID of the client
nameLast String Optional. Pet owner's last name
nameFirst String Optional. Pet owner's first name
homePhone String Optional. Pet owner's home phone
workPhone String Optional. Pet owner's work phone

Create a patient

Example Typical Request:

POST /hospitalization HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki
{
    "objectType": "hospitalization",
    "hospitalizationId": "emr-hospitalization-id",
    "dateCreated": "2014-11-03T17:54:55.221+00:00",
    "temperatureUnits": "C",
    "weightUnits": "kg",
    "weight": 5.8,
    "estimatedDaysOfStay": 1,
    "fileNumber": "# 123",
    "caution": false,
    "color": "#439FE0",
    "doctorName": "Dr. Ivan",
    "medicId": "dr-ivan-emr-id",
    "diseases": [
        "high temperature",
        "vomiting"
    ],
    "patient": {
        "objectType": "patient",
        "patientId": "emr-patient-id",
        "name": "Jordi Alba",
        "species": "Canin",
        "owner": {
            "objectType": "client",
            "ownerId": "emr-client-id",
            "nameLast": "Dow",
            "nameFirst": "Jack",
            "workPhone": "555-55-55"
        },
        "color": "Brown",
        "sex": "M",
        "criticalNotes": "Cefazolin allergy",
        "customField": "some notes"
    }
}

Example Minimal Request (only including required fields):

POST /hospitalization HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki
    {"hospitalizationId": "emr-hospitalization-id",
"dateCreated": "2014-11-03T17:54:55.221+00:00",
"patient": {
"objectType": "patient",
"sex": "U",
"owner":{
"objectType": "client"
}
}
}

The Smart Slow Sheet API does not allow to create several hospitalizations with the same hospitalizationId. However, it may happen that the user needs to re-submit the hospitalization that has been previously created (and then deleted or discharged from SmartFlow user interface). In this case, the second call of this API will return the error with the message Hospitalization already exists. If this happens, we advise to show the user the error message and prompt them if they would like to re-submit the patient. If user selects the option to re-submit the patient, then EMR should:

  1. Make a call to delete hospitalization API first;
  2. Call create a patient API again to re-submit the patient information.

Get active hospitalizations

Example Request:

GET /hospitalizations HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method allows to get all hospitalizations that have active value of the status field.

Get hospitalization

Example Request:

GET /hospitalization/emr-hospitalization-id HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method allows to get information about hospitalization by id. Specify the hospitalizationId of the hospitalization object in the EMR. Use the same hospitalizationId that was supplied when hospitalization had been created.

Attach to existing hospitalization

Example Request:

POST /hospitalization/sfs-hospitalization-guid/attach/emr-hospitalization-id HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

When a patient is created manually by the user with SmartFlow user interface, the hospitalization will be sent to EMR with hospitalizations.created event. The hospitalizationId field of the object will be empty, however, hospitalizationGuid field (a unique internal identifier of the hospitalization) will be provided. You may want to attach your EMR internal ID to this hospitalization to be able to receive any other type of events, as well as download patient reports and use any other API that requires hospitalizationId. The HTTP request below provides such possibility. It takes hospitalizationGuid value as one part of Url, while your internal hospializationId is included in another part of Url.

Upon attachment to the existing hospitalization, Smart Flow will collect all treatments recorded so far for this hospitalization and send them with the treatments.records_entered event.

Delete hospitalization

Example Request:

DELETE /hospitalization/emr-hospitalization-id HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method deletes hospitalization by id. Specify the hospitalizationId of the hospitalization object in the EMR. Use the same hospitalizationId that was supplied when hospitalization had been created. This method also "unmaps" the hospitalizationId from the internal hospitalization record - this allows to submit the patient to SmartFlow again afterward.

Discharge hospitalization

Example Request:

POST /hospitalization/discharge/emr-hospitalization-id HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method initiates the patient discharge operation. Specify the hospitalizationId of the hospitalization object in the EMR. Use the same hospitalizationId that was supplied when hospitalization had been created. This API requires the valid timezoneName header specified in the request.

Discharge hospitalization event

Example of hospitalizations.discharged event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "hospitalizations.discharged",
    "object": {
        "objectType": "hospitalizations",
        "id": "sfs-operation-id",
        "hospitalizations": [
            {
                "objectType": "hospitalization",
                "hospitalizationId": "emr-hospitalization-id",
                "hospitalizationGuid": "sfs-hospitalization-guid",
                "dateCreated": "2014-11-05T10:20:19.000+00:00",
                "fileNumber": "#File number",
                "reportPath": "https://pdf-report-webfile-path"
            }
        ]
    }
}

As soon as one or several patients have been discharged from the SmartFlow whiteboard, SmartFlow will notify EMR by sending one of the following events:

  1. The hospitalization.discharged event in case if single patient was discharged. In this case the hospitalization object will be transferred with the event.

  2. The hospitalizations.discharged event in case if multiple patients were discharged. In this case the hospitalizations object will be transferred with the event.

Every hospitalization object transferred with these events will contain the path to the flowsheet report pdf file in the reportPath field. If for some reason the value of this field is empty then you may explicitly download the flowsheet report.

Get notified about new hospitalizations

Example of hospitalizations.created event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "hospitalizations.created",
    "object": {
        "objectType": "hospitalizations",
        "id": "sfs-operation-id",
        "hospitalizations": [
            {
                "objectType": "hospitalization",
                "hospitalizationGuid": "sfs-hospitalization-guid",
                "dateCreated": "2014-11-05T10:20:19.000+00:00",
                "weight": 5.8,
                "estimatedDaysOfStay": 1,
                "fileNumber": "# 123",
                "caution": false,
                "color": "#439FE0",
                "doctorName": "Dr. Ivan",
                "medicId": "dr-ivan-emr-id",
                "diseases": [
                    "high temperature",
                    "vomiting"
                ],
                "patient": {
                    "objectType": "patient",
                    "name": "Jordi Alba",
                    "species": "Canin",
                    "owner": {
                        "objectType": "client",
                        "nameLast": "Dow",
                        "nameFirst": "Jack",
                        "workPhone": "555-55-55"
                    },
                    "color": "Brown",
                    "sex": "M",
                    "criticalNotes": "Cefazolin allergy",
                    "customField": "some notes"
                }
            }
        ]
    }
}

When hospitalization is created in SmartFlow (both through the user interface and create patient API) the hospitalizations.created event will be sent to EMR. The hospitalization object will be included in the payload.

The hospitalizationId field would be empty in case if the patient were created manually from SmartFlow user interface. You may want to attach your EMR internal ID to this hospitalization to be able to receive any other type of events, as well as download patient reports and use any other API that requires hospitalizationId.

You may find more details about attaching hospitalizations API here.

Download the Flowsheet report

Example Request:

GET /hospitalization/emr-hospitalization-id/flowsheetreport HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method allows to download the flowsheet report from SmartFlow.

All the dates in the downloaded report will be represented in the time zone that you must explicitly specify in the timezoneName header of the HTTP request (e.g. timezoneName: Europe/Helsinki). Please visit this web-page for the complete list of the time zone names.

Specify the hospitalizationId of the hospitalization object in the EMR. Use the same hospitalizationId that was supplied when hospitalization had been created.

For more information about merging reports functionality please take a look at Documents Management in Smart Flow section.

Download the Medical Records report

Example Request:

GET /hospitalization/emr-hospitalization-id/medicalrecordsreport HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method allows to download the medical record report from SmartFlow. Use this method when receiving hospitalizations.discharged event, as at this point the report should contain all medical records of the specified hospitalization.

All the dates in the downloaded report will be represented in the time zone that you must explicitly specify in the timezoneName header of the HTTP request (e.g. timezoneName: Europe/Helsinki). Please visit this web-page for the complete list of the time zone names.

Specify the hospitalizationId of the hospitalization object in the EMR. Use the same hospitalizationId that was supplied when hospitalization had been created.

Download the Billing report

Example Request:

GET /hospitalization/emr-hospitalization-id/billingreport HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: America/Chicago

This method allows to download the billing report from SmartFlow. Use this method when receiving hospitalizations.discharged event, as at this point the report should contain the complete inventory usage information of the specified hospitalization.

All the dates in the downloaded report will be represented in the time zone that you must explicitly specify in the timezoneName header of the HTTP request (e.g. timezoneName: America/Chicago). Please visit this web-page for the complete list of the time zone names.

Specify the hospitalizationId of the hospitalization object in the EMR. Use the same hospitalizationId that was supplied when hospitalization had been created.

Download the Notes report

Example Request:

GET /hospitalization/emr-hospitalization-id/notesreport HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method allows to download the notes report from SmartFlow. Use this method when receiving hospitalizations.discharged event, as at this point the report should contain all the tech notes of the specified hospitalization.

All the dates in the downloaded report will be represented in the time zone that you must explicitly specify in the timezoneName header of the HTTP request (e.g. timezoneName: Europe/Helsinki). Please visit this web-page for the complete list of the time zone names.

Specify the hospitalizationId of the hospitalization object in the EMR. Use the same hospitalizationId that was supplied when hospitalization had been created.

Estimates

Estimates created in the PIMS can be sent to SmartFlow, which allows a user to easily add these items to their treatment sheet. The estimate ID, if applicable, will be included with the treatment object if the item was added from an estimate.

There are the estimate and inventoryItems objects used to populate the estimate information in SmartFlow. This functionality is dependent on the inventory being set up by the user in the SmartFlow UI.

The estimates object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object. Should be assigned estimates value
id String Required. Unique identifier of the estimate group.
estimates Array The array of estimate objects.

The estimate object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object. Should be assigned estimate value
externalId String Required. Unique identifier of the estimate.
hospitalizationId String Required. EMR internal ID of the hospitalization
description String Required. A description of the estimate that will be useful for the user to view when deciding what estimate items to add to that patient's visit.
createdByName String Optional. User who created the estimate.
dateCreated Date Required. Specifies the date and time of the estimate creation. Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
dateExpires Date Required. Specifies the date and time that the estimate expires. Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
inventoryItems Array The array of inventoryItems objects.

The ID of this object will be sent with treatments.records_entered events for you to associate with charges as needed.

The inventoryItems object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object . Should be assigned inventoryItems value
id String Required. The EMR internal ID of the inventory item
name String Required. The name of the inventory item

Create an estimate

Example Typical Request:

POST /hospitalization/emr-hospitalization-id/estimate HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki
{
    "objectType": "estimate",
    "hospitalizationId": "emr-hospitalization-id",
    "dateCreated": "2020-8-03T17:54:55.221+00:00",
    "description": "OVH with nail trim and pre-op bloodwork",
    "createdByName": "Dr Jones",
    "dateExpires": "2020-11-03T17:54:55.221+00:00",
    "externalId": "estimate-1234",
    "inventoryItems": [
        {
            "id": "some-emr-internal-id",
            "name": "Chem 17",
        },
        {
            "id": "some-emr-internal-id2",
            "name": "Nail Trim"
        }
    ]
}

Create multiple estimates

Example Typical Request:

POST /hospitalization/emr-hospitalization-id/estimates HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki
{   "objectType": "estimates",
    "id":"all-todays-estimates-for-fluffy",
    "estimates": [
        {
        "objectType": "estimate",
        "HospitalizationId": "emr-hospitalization-id",
        "dateCreated": "2020-8-03T17:54:55.221+00:00",
        "Description": "OVH with nail trim and pre-op bloodwork",
        "CreatedBy": "Dr Jones",
        "DateExpires": "2020-11-03T17:54:55.221+00:00",
        "ExternalId": "estimate-1234",
        "InventoryItems": [
            {
                "id": "some-emr-internal-id",
                "name": "Chem 17",
            },
            {
                "id": "some-emr-internal-id2",
                "name": "Nail Trim"
            }
        ]
        },
        {
        "objectType": "estimate",
        "HospitalizationId": "emr-hospitalization-id2",
        "dateCreated": "2020-8-03T17:50:55.221+00:00",
        "Description": "Castration with nail trim",
        "CreatedBy": "Dr Jones",
        "DateExpires": "2020-11-03T17:50:55.221+00:00",
        "ExternalId": "estimate-1235",
        "InventoryItems": [
            {
                "id": "some-emr-internal-id4",
                "name": "Castration",
            },
            {
                "id": "some-emr-internal-id2",
                "name": "Nail Trim"
            }
        ]
        }
    ]
}

Get estimates associatd with a hospitalization

Example Request:

GET /hospitalization/emr-hospitalization-id/estimates HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method allows to get all estimates associated with a hospitalization.

Update estimate

Example Typical Request:

PUT /hospitalization/emr-hospitalization-id/estimate HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki
{
    "objectType": "estimate",
    "hospitalizationId": "emr-hospitalization-id",
    "dateCreated": "2020-8-03T17:54:55.221+00:00",
    "description": "OVH with nail trim and pre-op bloodwork",
    "createdByName": "Dr Jones",
    "dateExpires": "2020-11-03T17:54:55.221+00:00",
    "externalId": "estimate-1234",
    "inventoryItems": [
        {
            "id": "some-emr-internal-id",
            "name": "Chem 17",
        },
        {
            "id": "some-emr-internal-id2",
            "name": "Nail Trim"
        },
        {
            "id": "some-emr-internal-id3",
            "name": "CBC (in-house)"
        }
    ]
}

Delete estimate

Example Request:

DELETE /hospitalization/emr-hospitalization-id/estimate/estimate-1234 HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
timezoneName: Europe/Helsinki

This method deletes estimates by id. Specify the estimateId of the estimate object in the EMR. Use the same estimateId that was supplied when estimate had been created.

Inventory Items

There are the inventoryitems and inventoryitem objects used to import inventory from EMR to SmartFlow.

The inventoryitems object

Example inventoryitems object with 2 nested inventoryitem objects:

{
    "objectType": "inventoryitems",
    "id": "some-operation-id",
    "inventoryitems": [
        {
            "objectType": "inventoryitem",
            "id": "some-emr-internal-id",
            "name": "Cefazolin 100",
            "concentration": 100,
            "concentrationUnits": "mg",
            "concentrationVolume": "ml"
        },
        {
            "objectType": "inventoryitem",
            "id": "some-emr-internal-id2",
            "name": "Ampicillin"
        }
    ]
}

This object should be sent with the /inventoryitems API method (POST or PUT method).

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events (e.g. inventory.imported). Should be assigned inventoryitems value
id String Optional. Identificator of the object. Will be transferred to EMR with the SmartFlow events (e.g. inventory.imported)
inventoryitems Array The array of inventoryitem objects. See description of the inventoryitem object below

The inventoryitem object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events (e.g. inventory.imported). Should be assigned inventoryitem value
id String Required. The EMR internal ID of the inventory item
name String Required. The unique name of the inventory item
customField String Optional. The custom string data that you may want to store with the inventory item
concentration Double Optional. The concentration value for the given medication. This value should not be specified if the inventory item is not a medication.
concentrationUnits String Required if the concentration value is specified. Otherwise it cannot be specified. Units that define the amount of drug. There is no limitation on what data will be transferred. This value should not be specified if inventory item is not a medication.
concentrationVolume String Required if the concentration value is specified. Otherwise it cannot be specified. Units for the volume. There is no limitation on what data will be transferred. This value should not be specified if inventory item is not a medication.
inDispensingMachine Boolean Optional. Pass true if you use an external dispensing machine (e.g. Cubex) to capture charges for this item. In this case, Smart Flow will not send treatment.records_entered events during treatment execution. Please be cautious in setting this for the user, as they may not have this item configured in their Dispensing Machine to send charges.
asyncOperationStatus Integer Returned. The status of the asynchronous operation for the inventory item. This will be filled in by SmartFlow when sending the inventoryitems.imported event. Should be: 1. less than 0 - error occured; 2. greater or equal 0 - operation succeed.
asyncOperationMessage String Returned. May contain the error message in case the asyncOperationStatus field represents the error (less than 0).

Review Use-case for details on how concentration affects the user

Create or update single inventory item

Example Request:

POST /inventoryitem HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-SmartFlow"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
{
    "id": "external-inventory-id",
    "name": "Cefazolin 100",
    "concentration": 100,
    "concentrationUnits": "mg",
    "concentrationVolume": "ml"
}

Creates or updates single inventory item sent in the request.

Create or update multiple inventory items

Example Request:

POST /inventoryitems HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-SmartFlow"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
{
    "id": "some-emr-operation-id",
    "inventoryitems": [
        {
            "id": "some-emr-internal-id",
            "name": "Cefazolin 100",
            "concentration": 100,
            "concentrationUnits": "mg",
            "concentrationVolume": "ml"
        },
        {
            "id": "some-emr-internal-id2",
            "name": "Ampicillin"
        }
    ]
}

Asynchronously creates or updates the inventory items sent with the request. Before creating an inventory item system tries to match it with any existing records by ID. If exact match is found then records are linked, otherwise a new inventory item is created.

After an import operation finishes SmartFlow will send the inventoryitems.imported event to the registered webhook. We will pass back the same inventoryitems object to EMR, and fill in the status of the import operation for every inventory item provided.

Retreive existing inventory items

Retreive single inventory item

Returns the inventory item. Specify the id of the inventory item in the EMR. The same id that was supplied when object was created

Delete single inventory item

This method deletes an inventory item by id.

Delete multiple inventory items

This method is available in our Sandbox environment as of Jan 2020, and will be available soon in production. This method deletes multiple inventory items by id.

Example Request:

DELETE /inventoryitems HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
clinicApiKey: "clinic-api-key-taken-from-account-web-page" 
emrApiKey: "emr-api-key-received-from-SmartFlow"
["id1", "id2", "id3", "...", "idN"]

Receiving the status of import operation

Example of inventoryitems.imported event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "inventoryitems.imported",
    "object": {
        "objectType": "inventoryitems",
        "id": "some-emr-internal-id",
        "inventoryitems": [
            {
                "objectType": "inventoryitem",
                "id": "some-emr-internal-id",
                "name": "Cefazolin 100",
                "concentration": 100,
                "concentrationUnits": "mg",
                "concentrationVolume": "ml",
                "asyncOperationStatus": 0
            },
            {
                "objectType": "inventoryitem",
                "id": "some-emr-internal-id2",
                "name": "Ampicillin",
                "asyncOperationStatus": -1,
                "asyncOperationMessage":  "Some error message"
            }
        ]
    }
}

SmartFlow will send the inventoryitems.imported event to the url provided by EMR at the end of asynchronous import operation. SmartFlow sends the inventoryitems object with this event. Every inventoryitem object will contain asyncOperationStatus and optionally asyncOperationMessage in case of errors.

Vitals

There are the vitaltypes and vitaltype objects used to tell SmartFlow what vital signs you have in the EMR.

The vitaltypes object

Example vitaltypes object with 2 nested vitaltype objects:

{
    "objectType": "vitaltypes",
    "id": "some-operation-id",
    "vitaltypes": [
        {
            "dataType": "text",
            "objectType": "vitaltype",
            "id": "vtype_3",
            "name": "CRT (Text)"
        },
        {
            "dataType": "list",
            "options": [
                {
                    "id": "vtype_4_opt1",
                    "name": "RR Option 1"
                },
                {
                    "id": "vtype_4_opt2",
                    "name": "RR Option 2"
                }
            ],
            "objectType": "vitaltype",
            "id": "vtype_4",
            "name": "Resp Rate (List)",
            "units": []
        }
    ]
}

This object should be sent with the /vitaltypes API method (POST or PUT method).

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events (e.g. inventory.imported). Should be assigned vitaltypes value
id String Optional. Identificator of the object. Will be transferred to EMR with the SmartFlow events (e.g. inventory.imported)
vitaltypes Array The array of vitaltype objects. See description of the vitaltype object below

The vitaltype object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events (e.g. inventory.imported). Should be assigned vitaltype value
id String Required. The EMR internal ID of the vital
name String Required. The unique name of the vital
dataType String Required. The type of data the user should enter. (one of "list","text","numeric")
options Array Optional. If the dataType is list, the list of options to display.
units Array Optional Units that the user can select if this vital might have multiple ways of recording it (ie: kg, lb)

Both the units and options arrays should include a dictionary with keys "id" and "name" for each item.

The vitals object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events (e.g. inventory.imported). Should be assigned vitals value
vitalTypeId String The EMR internal ID of the vital
name String The unique name of the vital
hospitalizationId String The external ID of the hospitalization.
vitalGuid String A generated unique identifier for the vital, created by SmartFlow.
time Date Time vital was recorded. Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
vitalGuid String A generated unique identifier for the vital, created by SmartFlow.
status String This field describes what have happened to the note. Can be one of the following: 1. added, 2. changed, 3. removed
value String The value entered by the user for this vital.
source String The source of the vital entry, should be one of following types: 0 - Flowsheet vital, 1 - Anesthetic vital
doctorName String The name of the doctor on duty. This value will be provided only in case if the name of the doctor is specified on a correspondent flowsheet
doctor Medic The medic object that corresponds to the doctor on duty. This value will be provided only in case if associated medic has been imported from EMR
unit Object Optional. Dictionary specifying the unit id and name for the vital entered.

Create or update single vital

Example Request:

POST /vitaltype HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-SmartFlow"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
{
    "dataType": "numeric",
    "min": null,
    "max": 120,
    "objectType": "vitaltype",
    "id": "vtype_5",
    "name": "Weight",
    "units": [
        {
            "id": "uid1",
            "name": "kg"
        },
        {
            "id": "uid2",
            "name": "lbs"
        }
    ]
}

Creates or updates single vital sent in the request.

Create or update multiple vitals

Example Request:

POST /vitaltypes HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-SmartFlow"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
{
    "id": "idd",
    "objectType": "vitaltypes",
    "vitaltypes": [
        {
            "dataType": "text",
            "objectType": "vitaltype",
            "id": "vtype_3",
            "name": "CRT (Text)"
        },
        {
            "dataType": "list",
            "options": [
                {
                    "id": "vtype_4_opt1",
                    "name": "RR Option 1"
                },
                {
                    "id": "vtype_4_opt2",
                    "name": "RR Option 2"
                }
            ],
            "objectType": "vitaltype",
            "id": "vtype_4",
            "name": "Resp Rate (List)",
            "units": []
        }
    ]
}

Asynchronously creates or updates the vitals sent with the request.

After an import operation finishes SmartFlow will send the vitaltypes.imported event to the registered webhook. We will pass back the same vitaltypes object to EMR, and fill in the status of the import operation for every vital provided.

Receiving the entered vitals for a patient

Example of vitals.records_entered event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "vitals.records_entered",
    "object": {
        "objectType": "vitals",
        "vitals": [
            {
                "objectType": "vital",
                "vitalTypeId": "vtype_3_5",
                "name": "Weight-V",
                "hospitalizationId": "ExtId",
                "vitalGuid": "GuidString",
                "time": "2018-10-26T23:00:00.000+03:00",
                "status": "added",
                "value": "7.1",
                "source": 0,
                "doctorName": "Doctor",
                "doctor": null,
                "unit": {
                    "id": "viUnit3-1",
                    "name": "kg"
                },
                "asyncOperationStatus": null,
                "asyncOperationMessage": null
            }
        ],
        "id": "idOfVitalRecord"
    }
}

SmartFlow will send the vitals.records_entered event to the url provided by EMR each time a treatment is completed on a hospitalization, where that treatment is mapped to a Vital by the SmartFlow user. SmartFlow sends the vitals object with this event. The EMR should use the vitalTypeId and value, taking note of the status, unit, time and hospitalizationId to correctly action on this data.

Retreive existing vitals

If you need to check what vitals are in SmartFlow already, you can get a list with this call. Returns a list of all vitals.

Retreive single vital

If you need to check one specific vital is in SmartFlow already, you can do that with this call. Returns the specified vital. Specify the id of the vital in the EMR, the same id that was supplied when object was created.

Delete single vital

This method deletes an vital by id.

Delete multiple vitals

This method deletes multiple vitals by id. Pass IDs as URL query parameters

Receiving the status of import operation

Example of vitaltypes.imported event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "vitaltypes.imported",
    "object": {
        "objectType": "vitaltypes",
        "id": "some-emr-internal-id",
        "vitaltypes": [
            {
                "dataType": "list",
                "options": [
                    {
                        "id": "vtype_4_opt1",
                        "name": "RR Option 1"
                    },
                    {
                        "id": "vtype_4_opt2",
                        "name": "RR Option 2"
                    }
                ],
                "objectType": "vitaltype",
                "id": "vtype_4",
                "name": "Resp Rate (List)",
                "units": [],
                "asyncOperationStatus": null,
                "asyncOperationMessage": null
            }
        ]
    }
}

SmartFlow will send the vitaltypes.imported event to the url provided by EMR at the end of asynchronous import operation. SmartFlow sends the vitaltypes object with this event. Every vitaltype object will contain asyncOperationStatus and optionally asyncOperationMessage in case of errors.

Medics

There are the medics and medic objects used to import the list of clinic stuff from EMR to SmartFlow.

The medics object

Example medics object with 2 nested medic objects:

{
    "objectType": "medics",
    "id": "some-operation-id",
    "medics": [
        {
            "objectType": "medic",
            "medicId": "some-emr-internal-id-1",
            "name": "Dr. Jackson",
            "medicType": "doctor"
        },
        {
            "objectType": "medic",
            "medicId": "some-emr-internal-id-2",
            "name": "Dr. Smith",
            "medicType": "doctor"
        }
    ]
}

This object should be sent with the /medics API method (POST or PUT method).

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events (e.g. medics.imported). Should be assigned medics value
id String Optional. Identificator of the object. Will be transferred to EMR with the SmartFlow events (e.g. medics.imported)
medics Array The array of medic objects. See description of the medic object below

The medic object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events (e.g. medics.imported). Should be assigned medic value.
medicId String Required. The EMR internal ID of the medic.
name String Required. The unique name of the medic for a particular medicType.
medicType String Required. The type of the medic imported in SmartFlow. Can be one of the following: 1. doctor, 2. technician, 3. anesthetist.
asyncOperationStatus Integer Optional. The status of the asynchronous operation for the medic object. This will be filled in by SmartFlow when sending the medics.imported event. Should be: 1. less than 0 - error occured; 2. greater or equal 0 - operation succeed.
asyncOperationMessage String Optional. May contain the error message in case the asyncOperationStatus field represents the error (less than 0).

Create or update single medic

Example Request:

POST /medic HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
{
    "medicId": "some-emr-internal-id-1",
    "name": "Dr. Jackson",
    "medicType": "doctor"
}

Creates or updates single medic object sent in the request. SmartFlow will attempt to link the transferred medic object with the internal SmartFlow items by name.

Create or update multiple medics

Example Request:

POST /medics HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
{
    "id": "some-operation-id",
    "medics": [
        {
            "medicId": "some-emr-internal-id-1",
            "name": "Dr. Jackson",
            "medicType": "doctor"
        },
        {
            "medicId": "some-emr-internal-id-2",
            "name": "Dr. Smith",
            "medicType": "doctor"
        }
    ]
}

Asynchronously creates or updates the medics objects sent with the request. Before creating a medic object system tries to match it with any existing records by name. If exact match is found then records are linked, otherwise a new medic is created.

After an import operation finishes SmartFlow will send the medics.imported event to the registered webhook. We will pass back the same medics object to EMR, and fill in the status of the import operation for every object provided.

Retreive existing medics

Retreive single medic

Returns the medic object. Specify the id of the medic in the EMR. The same id that was supplied when the object was created

Delete single medic

This method deletes a medic by id.

Delete multiple medics

This method is available in our Sandbox environment as of Jan 2020, and will be available soon in production. This method deletes multiple inventory items by id.

Example Request:

DELETE /medics HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
clinicApiKey: "clinic-api-key-taken-from-account-web-page" 
emrApiKey: "emr-api-key-received-from-sfs"
["id1", "id2", "id3", "...", "idN"]

Receiving the status of the import operation

Example of medics.imported event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "medics.imported",
    "object": {
        "objectType": "medics",
        "id": "some-emr-internal-id",
        "medics": [
            {
                "objectType": "medic",
                "medicId": "some-emr-internal-id-1",
                "name": "Dr. Jackson",
                "medicType": "doctor",
                "asyncOperationStatus": 0
            },
            {
                "objectType": "medic",
                "medicId": "some-emr-internal-id-2",
                "name": "Dr. Smith",
                "medicType": "doctor",
                "asyncOperationStatus": -1,
                "asyncOperationMessage":  "Some error message"
            }
        ]
    }
}

SmartFlow will send the medics.imported event to the url provided by EMR at the end of asynchronous import operation. SmartFlow sends the medics object with this event. Every medic object will contain asyncOperationStatus and optionally asyncOperationMessage in case of errors.

Notes

The are two objects used by SmartFlow to notify EMR when notes entered into the flowsheet or anesthetic:

Both objects are sent with the asynchronous notes.entered event when one or several tech notes has been entered/removed.

The notes object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events (e.g. notes.entered). Should be assigned notes value
id String Identificator of the object. Will be transferred to EMR with the notes.entered event.
notes Array The array of note objects. See description of the note object below

The note object

Attributes

Parameter Type Description
objectType String Describes the type of the object transferred with the SmartFlow events (e.g. notes.entered). Should be assigned note value
noteGuid String Required. A unique internal identifier of the note item
hospitalizationId String Hospitalization external id (which was provided with hospitalization creation)
time Date Note creation time (UTC time that corresponds to an hour on a flowsheet). Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
text String The string value that was entered during note creation
status String This field describes what have happened to the note. Can be one of the following: 1. added, 2. changed, 3. removed
type Integer The type of note. Should be 0 - Flowsheet note, 1 - Anesthetic note or 2 - Dental Chart note
anestheticGuid String A unique internal identifier of the anesthetic sheet, required if type = 1, otherwise is equal to null

Retreive multiple notes

Example of notes.entered event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "notes.entered",
    "object": {
        "objectType": "notes",
        "id": "sfs-operation-id",
        "notes":[
            {
                "objectType": "note",
                "noteGuid": "sfs-note-guid1",
                "hospitalizationId": "external-hosp-id1",
                "time":"2013-03-28T14:23:56.000+00:00",
                "status": "changed",
                "text": "Lorem ipsum...",
                "type": 0,
                "anestheticGuid": null
            },
            {
                "objectType": "note",
                "noteGuid": "sfs-note-guid2",
                "hospitalizationId": "external-hosp-id1",
                "time":"2013-03-28T14:23:56.000+00:00",
                "status": "added",
                "text": "Donec eu mattis diam...",
                "type": 1,
                "anestheticGuid": "sfs-anesthetic-guid"
            }       
        ]
    }
}

Treatments

The are two objects used by SmartFlow to notify EMR when medical records entered into the flowsheet:

The treatments object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events (e.g. treatment.record_entered). Should be assigned treatments value
id String Required if sent to /treatments API method. Identificator of the object. Will be transferred to EMR with the treatments.records_entered event. EMR should return this field with the /treatments API method
treatments Array The array of treatment objects. See description of the treatments object below

The treatment object

Attributes

Parameter Type Description
objectType String Describes the type of the object transferred with the SmartFlow events (e.g. treatment.record_entered). Should be assigned treatment value
inventoryId String Inventory item external id (which was provided with inventory upload). If “Null” then there is no inventory item for this treatment found in SmartFlow
name String Name of the treatment parameter as it is shown on the flowsheet
hospitalizationId String Hospitalization external id (which was provided with hospitalization creation)
treatmentGuid String Required. A unique internal identifier of the treatment item (which corresponds to the treatment at particular hour on a flowsheet). You can use this ID to connect different events (ie: if you receive a "removed" treatment object, you'll be able to know which was removed by this unique identifier.) This property is unique across all hospitalizations.
parameterGuid String A unique internal identifier of the parameter item (which corresponds to the treatment line on a flowsheet)
flowsheetSectionName String The section of the flowsheet where the parameter was entered. Will be one of: "Agent", "Monitoring", "Activity", "Procedure", "Fluid", "Medication", "Task"
time Date Treatment time (UTC time that corresponds to an hour on a flowsheet). Time format: YYYY-MM-DDThh:mm:ss.sssTZD (e.g. 1997-07-16T19:20:30.000+00:00)
status String This field describes what have happened to the medical record. Can be one of the following: 1. changed, 2. added, 3. removed, 4. not_changed
qty Double Quantity. In case if the medication has been given to a patient this value will be equal to the volume field (described below). Otherwise it will be 1
volume Double The volume of the medication that has been given to a patient. In case of non-medication treatment this value will not be provided.
units String The units of the medication volume (ml, tab, etc). For non-medication items this value will not be provided
value String The string value that was entered during treatment execution
mediaPath String The path to the media file that has been attached to the treatment
mediaContentType String The content type of media file (e.g. image/jpg, video/mp4, etc...)
doctorName String The name of the doctor on duty. This value will be provided only in case if the name of the doctor is specified on a correspondent flowsheet
doctor Medic The medic object that corresponds to the doctor on duty. This value will be provided only in case if associated medic has been imported from EMR
type Integer The type of the treatment, should be one of following types: 0 - Flowsheet treatment, 1 - Anesthetic treatment, 2 - Treatment task.
billed Boolean If true then treatment should be included in the billing (more information here)
estimateId String If the treatment was added from an estimate, the estimate ID will be included in the treatment event. (more information here)
asyncOperationStatus Integer Required if sent to /treatments API method. This field should be filled in by EMR when sending the treatments object with the /treatments API method. This is usually happens in response to the treatments.records_entered async event. This field describes the status of the asynchronous operation for each treatment. Should be: 1. less than 0 - error occured; 2. greater or equal 0 - operation succeed.
asyncOperationMessage String Optional. May contain the error message in case the asyncOperationStatus field represents the error (less than 0).

Including treatments in the billing

SmartFlow provides a user interface option for the user to explicitly include or exclude the treatment from being included in the billing (see image below). This option is only shown for the parameters mapped to the EMR inventory items. If the user sets "Billing" option to ON, then true is provided with the billed field. Otherwise, Smart Flow sends false. If you receive a treatments.records_entered event where a treatment object has billed set as false, you should not enter this item on the invoice in your EMR. This generally means the item was not performed by the user.

Retreive single medical record

Example of treatment.record_entered event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "treatment.record_entered",
    "object": {
        "objectType": "treatmet",
        "name": "Cefazolin 100",
        "inventoryId": "external-inventory-id",
        "hospitalizationId": "external-hospitalization-id1",
        "treatmentGuid": "sfs-treatment-guid1",
        "time":"2013-03-28T14:23:56.000+00:00",
        "status": "changed",
        "qty": 3.5,
        "volume": 3.5,
        "value": "IZ",
        "mediaPath": "https://attached-image-webfile-path",
        "mediaContentType": "image/jpg",
        "units": "ml",
        "doctorName": "name-of-the-doctor",
        "doctor": {
            "objectType": "medic",
            "medicId": "some-emr-internal-id-2",
            "name": "name-of-the-doctor",
            "medicType": "doctor"
            }
    }
}

The treatment.record_entered event is sent from SmartFlow when one medical record has been entered/removed. SmartFlow will send treatment object with all information about medical record.

Retrieve multiple medical records

Example of treatments.records_entered event JSON:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "treatments.records_entered",
    "object": {
        "objectType": "treatments",
        "id": "sfs-operation-id",
        "treatments":[
            {
                "objectType": "treatment",
                "name": "Cefazolin 100",
                "inventoryId": "external-inventory-id",
                "hospitalizationId": "external-hosp-id1",
                "treatmentGuid": "sfs-treatment-guid1",
                "time":"2013-03-28T14:23:56.000+00:00",
                "status": "changed",
                "qty": 3.5,
                "volume": 3.5,
                "value": "IZ",
                "units": "ml",
                "doctorName": "name-of-the-doctor",
                "doctor": {
                    "objectType": "medic",
                    "medicId": "some-emr-internal-id",
                    "name": "name-of-the-doctor",
                    "medicType": "doctor"
                    }               
            },
            {
                "objectType": "treatment",
                "name": "Temperature",
                "inventoryId": null,
                "hospitalizationId": "external-hosp-id2",
                "treatmentGuid": "sfs-treatment-guid2",
                "time":"2013-03-28T14:23:56.000+00:00",
                "status": "added",
                "qty": 1,
                "volume": null,
                "value": "36.6",
                "units": null,
                "doctorName": "name-of-the-doctor-2",
                "doctor": null
            }       
        ]
    }
}

The treatments.records_entered event is sent from SmartFlow when one or several medical record has been entered/removed. SmartFlow will send treatments object with all information about medical records. It is required that this event handled asynchronously by EMR. SmartFlow expects EMR to make a call to the treatments API method and transfer back treatments objects with the all original information, plus including the results of processing.

It is very important that you call the /treatments API method, after you finish processing the medical records that SmartFlow sends to EMR with this event. Make sure to preserve and send back the id field received with the treatments object.

Send medical records processing results

Example Request:

POST /treatments HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
{
    "id": "sfs_operation_id",
    "treatments": [
        {
            "objectType": "treatment",
            "name": "Cefazolin 100",
            "inventoryId": "external-inventory-id",
            "hospitalizationId": "external-hosp-id1",
            "treatmentGuid": "sfs-treatment-guid1",
            "time":"2013-03-28T14:23:56.000+00:00",
            "status": "changed",
            "qty": 3.5,
            "volume": 3.5,
            "value": "IZ",
            "units": "ml",
            "doctorName": "name-of-the-doctor",
            "asyncOperationStatus": -1,
            "asyncOperationMessage": "Some error message"
        },
        {
            "objectType": "treatment",
            "name": "Temperature",
            "inventoryId": null,
            "hospitalizationId": "external-hosp-id2",
            "treatmentGuid": "sfs-treatment-guid2",
            "time":"2013-03-28T14:23:56.000+00:00",
            "status": "added",
            "qty": 1,
            "volume": null,
            "value": "36.6",
            "units": null,
            "doctorName": "name-of-the-doctor",
            "asyncOperationStatus": 0
        }
    ]
}

With this request SmartFlow will receive the results of medical records processing by EMR. SmartFlow then will update medical records with the appropriate status transferred with asyncOperationStatus field. Call this method after asynchronous processing of the treatments.records_entered event finished.

Treatment Templates

This API allows to get the list of active treatment templates in the clinic. You may want to use this API to allow users to select a treatment template before submitting a new patient into SmartFlow.

The treatment template object

Attributes

Parameter Type Description
objectType String Optional. Describes the type of the object transferred with the SmartFlow events. Should be assigned treatmenttemplate value
name String Required. The unique name of treatment template. You should use this value to specify the treatment template when creating a new hospitalization

Retreive active treatment templates

Example Request:

GET /treatmenttemplates HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"
[
{
     "objectType":"treatmenttemplate",
     "name":"FLUTD"
},
{
     "objectType":"treatmenttemplate",
     "name":"Seizure"
}
]

Events

SmartFlow will send events to EMR on different occasions:

  1. Inventory import finished
  2. When single medical record has been entered or removed
  3. When mutliple medical records have been entered or removed
  4. When patient has been created in SmartFlow
  5. When patient has been discharged from the whiteboard
  6. When mutliple notes have been entered or removed
  7. When anesthetic sheet has been finalized
  8. When the form has been filled in for a patient

In the future there can be other events added to this, e.g. sending flowsheet report or medical records report on patient discharge, etc…

Events will be sent only for those hospitalizations that have been created from EMR. The only exception is the hospitalizations.created event that is sent even for the patients created manually with SmartFlow user interface. Events on hospitalizations created directly from SmartFlow won't be sent to EMR webhook.

Sending events require webhook to be registered in SmartFlow. You may register a webhook that will receive all the events associated with your EMR, or you may register a custom webhook for each clinic account. Requirements to webhook:

The event object

Example of the event object:

{
    "clinicApiKey": "clinic-api-key",
    "eventType": "treatments.records_entered",
    "object": {

    }
}

Attributes

Parameter Type Description
clinicApiKey String Clinic api key to associate clinic on EMR`s side
eventType String The type of the event
object Object Object of one of the following type: treatment, treatments, inventoryitems, hospitalization, etc... This list can expand as soon as new objects will be sent with the API.

Types of events

SmartFlow will send several events on different occasions. Below is short description of the events.

Event Description
anesthetics.finalized Sent from SmartFlow when clinic stuff finalizes anesthetic sheet(s)
forms.created Sent from SmartFlow when the form(s) is created and filled in for the patient (e.g. client self check-in form)
forms.updated Sent from SmartFlow when the form's content is updated or form changes its status to finalized or deleted
hospitalizations.created Sent after a patient(s) has been created in SmartFlow
hospitalization.discharged Sent after a patient has been discharged from the SmartFlow whiteboard
hospitalizations.discharged Sent after multiple patients have been discharged from the SmartFlow whiteboard
inventoryitems.imported Sent after importing of emr inventory items finished
notes.entered Sent from SmartFlow when multiple notes have been entered/removed
medics.imported Sent after importing of emr medics finished
treatment.record_entered Sent from SmartFlow when one medical record has been entered/removed
treatments.records_entered Sent from SmartFlow when multiple medical records have been entered/removed

Register custom webhook

Example Request:

POST /account/webhook?url=your_custom_url HTTP/1.1
User-Agent: MyClient/1.0.0
Content-Type: application/json
emrApiKey: "emr-api-key-received-from-sfs"
clinicApiKey: "clinic-api-key-taken-from-account-web-page"

You may use this API to register a custom HTTPS webhook that will receive events only for the specified clinic account. You may use this webhook for a group of clinics also.