Awell Health Developer Hub
Developer Hub

All of the interactions with Awell Orchestration are accessible through our API. For full detail, see our API Reference.

Below is a typical, although very basic, lifecycle of interacting with our API.

  1. Create a Patient in Awell
  2. Start a Pathway for this patient
  3. Get the pending activities for this Pathway
  4. Request the details of the next activity, e.g. get form details
  5. Complete the next activity, e.g. submit form response
  6. Request the details of the next activity, e.g. get message details
  7. Complete the next activity (e.g. mark the message as read
  8. ... and so on until the pathway is completed, at which point you can receive a pathway completed webhook

Core concepts

The core concepts of our API domain model are the following:

  • Patient and other stakeholders
  • Pathway
  • Activity
  • Data Point

Patient and other stakeholders

A patient refers to a user that can be enrolled in a care flow. Activities in those care flows can be assigned to that patient but also other stakeholders: physician, nurse, care coordinator, therapist, coach, you name it.

Awell Orchestration does not need to know anything about a patient when orchestrating pathways. Any information saved in a patient profile can be used inside pathway definitions (to customise message content, or enrich api calls / webhook payloads for example), but none of it is required. This means there is no requirement to store PII in Awell.

  • graphql
01type User {
02  id: ID!                         # Unique identifier of the patient
03  profile: UserProfile            # Optional profile information
04}
05

06type UserProfile {
07  patient_code: String            # Optional custom identifier
08  [...]
09}

The only recommended property to set when creating patients is the patient_code, which can be used as a unique identifier to match data in Awell with your own patient records.

Awell does not enforce the uniqueness of the patient_code amongst your patients. If you use unique identifiers, you can use the searchPatientsByPatientCode query before creating patients to enforce the uniqueness constraint on your end.

See the API Reference for more information about the user type.

Pathway

In our documentation and software, we are evolving towards use of the term "care flow". However, in our API this is currently called a "Pathway".

A pathway definition is what's automatically created by the Awell Platform when publishing a care flow. A pathway refers to an instance of a pathway definition in which a patient has been enrolled.

  • graphql
01type Pathway {
02  id: ID!                         # Unique identifier of the pathway
03  patient_id: String!             # Unique identifier of the patient
04  pathway_definition_id: String!  # Unique identifier of the pathway definition
05                                  # this pathway is derived from
06  start_date: SafeDate            # Start date in ISO8601 format
07  status: PathwayStatus!          # Current status of the pathway
08  [...]
09}

See the API Reference for more information about the pathway type.

Activities

Activities are the atomic build blocks in an orchestrated pathway. Each activity describes a specific task that needs to be performed by a specific stakeholder at a given point in time.

Awell Orchestration uses the pathway definition to automatically create and schedule activities and assign them to the right stakeholder. Your responsibility is therefore not to schedule individual activities, but to dispatch activities we create to your own users or use them as triggers for additional logic in your system.

Awell Orchestration currently supports the following activity types:

  • API Call
  • Calculation
  • Checklist
  • Form
  • Message
  • Reminder

Generic structure

Activities use a generic structure (subject + action + object + indirect object) to describe any action that needs to be performed by a human or system.

  • graphql
01{
02  id          # Unique identifier of the activity
03  stream_id   # Pathway identifier
04  date        # Creation date in ISO8601 format
05  subject {   # User or system that created the activity
06              # Currently only the Awell system creates activities
07    type
08    name
09  }
10  action      # Action performed by the subject when creating
11              # the activity.
12  object {    # Object that the activity relates to.
13    id
14    type
15    name
16  }
17  indirect_object { # User or stakeholder this activity was
18                    # assigned to. Is omitted when the activity
19                    # is assigned to the Awell system.
20    id
21    type
22    name
23  }
24  [...]
25}

When an activity is explicitly assigned to a patient or clinical stakeholder, the indirect_object property has the following data:

  • graphql
01# Assigned to patient
02indirect_object {
03  id: '<PATIENT_ID>'     # Unique identifier of the patient
04  type: 'patient'
05  name: '<PATIENT_NAME>' # Patient full name, if known
06}
07# Assigned to clinical stakeholder
08indirect_object {
09  id: '<STAKEHOLDER_ID>'      # Unique identifier of the stakeholder
10  type: 'stakeholder'
11  name: '<STAKEHOLDER_NAME>'  # Stakeholder name
12}

See the API Reference for more information about the activity type.

Example: API Call activity

  • graphql
01{
02  subject {
03    type: 'awell'
04    name: 'Awell'
05  }
06  action: 'assigned'
07  object {
08    id: '<API_CALL_ID>'   # Unique identifier of the api call
09    type: 'api_call'
10    name: '<ACTION_TITLE>' # Title defined in pathway definition
11  }
12  [...]
13}

Example: Calculation activity

  • graphql
01{
02  subject {
03    type: 'awell'
04    name: 'Awell'
05  }
06  action: 'assigned'
07  object {
08    id: '<CALCULATION_ID>'      # Unique identifier of the calculation
09    type: 'calculation'
10    name: '<CALCULATION_NAME>'  # Calculation name
11  }
12  [...]
13}

Example: Form activity

  • graphql
01{
02  subject {
03    type: 'awell'
04    name: 'Awell'
05  }
06  action: 'assigned'
07  object {
08    id: '<FORM_ID>'       # Unique version-specific identifier of the form
09    type: 'form'
10    name: '<FORM_TITLE>'  # Form title
11  }
12  indirect_object { ... }
13  [...]
14}

Example: Reminder activity

  • graphql
01{
02  subject {
03    type: 'awell'
04    name: 'Awell'
05  }
06  action: 'send'
07  object {
08    type: 'reminder'
09  }
10  indirect_object { ... }
11  [...]
12}

Data point definition

Data point definitions describes and qualify each and every atomic piece of data that can be captured in the lifecycle of a pathway.

  • graphql
01{
02  id # Unique identifier
03  category # Where the data points will come from
04  # Example: form, calculation, patient_profile, ...
05  key # Human and machine friendly identifier
06  value_type # Data type of the captured values
07  # One of: boolean / date / number / string / numbers_array
08  possible_values # List of accepted (value,label) pairs, when relevant.
09  range # Min / Max value, when relevant
10}

See the API Reference for more information about the data point definition type.

GraphQL APIEndpoints