Awell Health Developer Hub
Dev Hub


Care flows or pathways can only be started for patients so you need to create a patient first before you can start a pathway. You can create a new patient with the createPatient mutation.

When you create a new patient, we will return you an Awell patient ID, which you can use to start a pathway. However, if you have created a patient using your own business identifiers, you can also utilize these identifiers to start a pathway.

To use identifiers, they need to be set up on the tenant level. Learn more about how to set up identifiers.

Selecting the version

When starting a pathway, Awell Orchestration automatically chooses the most recent published version of the specified pathway definition.

Improved support for versioning is coming soon, with the ability to select a specific version when starting a new pathway and upgrading started pathways to newer version.


There are two mutations to start a care flow for a patient, they only differ by how to provide information for which patient to start a care flow, via Awell patient ID or via a business identifier.

StartPathway mutation

This mutation allows you to start a pathway for a patient using the Awell patient ID.





StartPathwayWithPatientIdentifier mutation

This mutation allows you to start a pathway for a patient using a business identifier.





Pathway definition ID


The pathway_definition_id can be located either by using the publishedPathwayDefinitions query or by checking the URL bar while working in Awell Studio. It's important to remember that your care flow must be published and have an active version set before you can start it.

How to find the pathway definition ID in Awell Studio

How to find the pathway definition ID in Awell Studio

Baseline info

You have the ability to pass some initial data when starting a pathway with baseline data points. What data you can pass on pathway start needs to be configured in Awell Studio. When your baseline data points are configured and your pathway is published, you can query the available baseline data points via the publishedPathwayDefinitions query (see documentation here).


There are required and optional baseline data points. A pathway will not be started if not all required baseline data points have a value.


Given data point values are polymorphic, the value for a data point should always be sent as a string. Values are validated and deserialized on the Awell side and we will throw an error if a value does not match the corresponding data point value type.

In table below you can find an overview of all baseline data point types and the value type you should be sending to the Awell API.

Data point value typeValue type to sendExamples
dateISO8601 string"2023-01-01"
stringstring"Awell is great"

How to use