Start a care flow

Reference for the mutations themselves is in Care flows. This page covers what you need to know around them.

Prerequisites

A care flow can only be started for a patient, so create the patient first. See Patients.

Creating a patient returns an Awell patient ID. If you created the patient using your own business identifiers, you can start a care flow with those instead, which means your system never has to store an Awell ID. Identifiers must be set up at tenant level first. See Patient identifiers.

Which start mutation

The two mutations differ only in how the patient is identified:

Prefer the identifier version if your system is the source of truth for patients; it removes a whole class of "which ID is this" bugs.

Which version starts

Awell automatically starts the most recent published version of the care flow definition.

You can pass a release_id to start a specific version instead. A patient stays on the version they started on for the life of their care flow, so the version passed at start determines their experience months later. See Versions and releases.

Baseline data at start

If the care flow defines required baseline data points, supply them at start or the request is rejected.

If the care flow's logic reads an optional baseline data point and the value is missing, the flow halts at that logic with no error. See Enrich your care flow with baseline data.

Starting a hosted-pages session at the same time

If a patient should immediately interact with their first activity, one mutation both starts the care flow and returns a hosted-pages session URL. Use it for self-enrollment, where the person is present and waiting.

See Hosted sessions, and Trigger with a Hosted Pages link for the no-code equivalent.

Sessions expire. Generate the session at the moment you hand the patient over, not in advance.

Next steps

Next: Query activities to find out what the care flow produced.