Skip to main content

Huma Platform Play (1.23.0)

Welcome to API documentation for Platform Play product. Download the spec here.

Introduction

This API is written in OpenAPI v3 and is based on existing functionalities of Huma Portal And Huma App.

Authentication

There are two ways to authenticate to the API:

  • End user authentication: Using username, password flow. It may ask to setup 2FA based of deployment configuration.
  • Machine user authencation: Using Hawk method to authenticate into system.

For Hawk authentication, Huma staffs provides you with the necessary credentials.

Python / export de-identified data

Download from the export.py file here. Make sure to have python3 (>= 3.7) and pip on your system.

  1. Install dependencies:

    $ pip install requests mohawk

  1. Set AUTH_ID, AUTH_KEY, DEPLOYMENT_ID in code and call export.py:

    $ python3 export.py

  2. Or alternatively to step 2, set the env variable and call export.py:

    $ AUTH_ID=<ID> AUTH_KEY=<KEY> DEPLOYMENT_ID=<DEP_ID> python3 export.py

    Step 2 or 3 generates an export.json based on the input parameters.

Note

OpenAPI syntax we use a few vendor extensions.

Export

Export module is used by clinicians to export the patient data in CSV/JSON format.

Export

post
URL: /api/extensions/v1beta/export/

The users with any these roles can access the export API: Admin, OrganizationStaff, AccessController and Contributor

If you are using End user authentication
  1. Sign in for clinician user:
    • API /api/auth/{version}/signin will return the authToken and user_id in response.
  2. Get deploymentId:
    • Using the Bearer {authToken} do call /api/extensions/{version}/user/{user_id}/configuration to get deploymentId
  3. Export patients data in CSV/JSON format(for that clinician):
    • For given deploymentId the data can be exported using /api/extensions/{version}/export/
If you are using Hawk authentication
  1. Sign in Api Key and Api ID:
    • Huma staffs provides you with Api credentials
  2. Get deploymentId:
    • Huma staffs provides you with necessary deployment ID(s)
  3. Export patients data in CSV/JSON format:
    • For given deploymentId the data can be exported using /api/extensions/{version}/export/
Request Body schema: application/json

Export request

deIdentified
boolean
Default: false

Identified information type:

  • true - excluding identified information
  • false - including identified information
format
string
Default: "JSON"
Enum: "JSON" "CSV" "JSON_CSV"

Exported files format

fromDate
string <yyyy-mm-dd>

Export data starting date fromDate

toDate
string <yyyy-mm-dd>

Export data ending date toDate

deploymentId
string

Export data for specific deploymentId

deploymentIds
Array of strings

Export data from multiple deployments by its deploymentIds

userIds
Array of strings

Export data only for specific users specified by thier id

moduleNames
Array of strings

Export only specific modules specific by module names

excludedModuleNames
Array of strings

Export all modules but not these

includeUserMetaData
boolean
Default: true

User's meta data type:

  • true - excluding user's meta data
  • false - including user's meta data
includeNullFields
boolean
Default: true
  • true - Include fields which have null values
  • false - Remove fields which have null values
useFlatStructure
boolean
Default: false
  • true - Will use flat structure.
  • false - Will use hierarchical structure.
view
string
Default: "USER"

Export the data according to the selected view.

  • "USER" - Per user (user data will be first on the CSV/JSON)
  • "DAY" - Per date
  • "MODULE_CONFIG" - Per module
binaryOption
string
Default: "BINARY_INCLUDE"

Binary options type:

  • "BINARY_INCLUDE" - Include primitive's binaries
  • "SIGNED_URL" - Generate signed urls to download primitive's binaries
  • "NONE" - Keep as it is
layer
string
Default: "NESTED"

Export files based on below layer type:

  • "NESTED" - Export files will be in the separate folders based on the view
  • "FLAT" - Export files will be in one folder based on the view
quantity
string
Default: "MULTIPLE"

Export files based on below quantity type:

  • "MULTIPLE" - Exported files will be in the separate files according to the module/day/user per file
  • "SINGLE" - Exported files should be in one file (CSV does not support single file option)
questionnairePerName
boolean
Default: false
  • true - Split questionnaire primitives into separate files as per their name
  • false - Can not split questionnaire primitives into separate files as per their name
splitMultipleChoice
boolean
Default: false
  • true - Split multiple questionnaire choices based on a module config
  • false - Can not split multiple questionnaire choices based on a module config
splitSymptoms
boolean
Default: false
  • true - Split symptoms in CSV format
  • false - Can not split symptoms in CSV format
translatePrimitives
boolean
Default: false
  • true - Translate primitive values into keywords based on provided CSV in export deployment config
  • false - Can not translate primitive values into keywords based on provided CSV in export deployment config
singleFileResponse
boolean
Default: false
  • true - Get response into single file format (CSV/JSON)
  • false - Get response into multiple files
translationShortCodesObjectFormat
string
Default: "JSON"
Enum: "JSON" "CSV" "JSON_CSV"

Translation Short Codes Object files format

doTranslate
boolean
baseProfile
string

Export data for created profile

organizationId
string

Export data for specific organization by organizationId

Responses

Request samples

Content type
application/json
Example
Single deployment with all modules (except step) and de-identified in JSON
Single deployment with all modules (except step) and de-identified in JSON
Single deployment with all modules (except step) and identified in JSON
Single patient data excluding identifiable information for all modules and export to JSON format
Single patient data excluding identifiable information for specific modules and export to CSV & JSON both formats
Multiple patients data including identifiable information for all modules and export CSV format
Multiple patients data including identifiable information for selected module and export JSON format
All patients data excluding identifiable information identifiable for all modules and export CSV & JSON both formats
Export patients data for specific deployment using base profile
Export multiple patients data for specific deployment with all objects
All deployments data excluding identifiable information identifiable for all modules and export JSON format as an access controller (AC)
Multiple deployments data excluding identifiable information identifiable for all modules and export CSV format as an access controller (AC)
Export multiple deployments data for specific organization with all objects
{
  • "userExportProfile": false,
  • "deIdentified": true,
  • "excludedModuleNames": [
    ],
  • "binaryOption": "NONE",
  • "includeNullFields": false,
  • "format": "JSON",
  • "singleFileResponse": true,
  • "fromDate": "2021-07-15",
  • "toDate": "2021-08-12",
  • "deploymentId": "{{deploymentId}}"
}

Response samples

Content type
application/json
{
  • "BloodPressure": {
    }
}

Create export profile

post
URL: /api/extensions/v1beta/export/profile

Using Export Profile API endpoint you can perform basic CRUD operations against Export Profile data

For example, To export the data using created export profile we can call below APIs:

  1. Create export profile for patients(for that clinician)/deployments(for that organization) data :
  • For given deploymentId/organizationId, content and name the export profile can be created using /api/extensions/{version}/export/profile
  1. Export patients/deployments data in CSV/JSON format(for that clinician/organization) by using created profile:
  • For given baseProfile and deploymentId/organizationId the data can be exported using /api/extensions/{version}/export/
Request Body schema: application/json

Create export profile request

name
string

Name of the export profile

deploymentId
string

Export data for specific deploymentId

organizationId
string

Export data for specific organization by organizationId

deploymentIds
Array of strings

Export data from multiple deployments by its deploymentIds

object

Responses

Request samples

Content type
application/json
Example
Create profile for all patients data with Identifiable information
Create profile for all patients data with Identifiable information
Create profile for multiple patients data without Identifiable information
Create profile for all deployment data with single file format (JSON)
Create profile for single deployment data with nested layer
Create profile for single patient data with including user metadata
Create profile for single patient data view like per date
Create profile for multiple patients data of specific deployment with all objects
Create profile for multiple deployments data of specific organization with all objects
{
  • "name": "{{profile name}}",
  • "deploymentId": "{{deploymentId}}",
  • "content": {
    }
}

Response samples

Content type
application/json
{
  • "id": "60fa5ce3ee36446d38825f11"
}
Authorization
Authorization type:
  • Hawk