Identity & tracking user journeys

A Capable Health identity represents an end user taking actions in our system. This identity allows you to track a user's journey by giving each action an identity ID, even if a user has not yet signed up on your platform.

Capable offers integrations with customer data platforms Freshpaint and Segment to track user actions and pass the event data to third-party tools. Capable includes the identity ID in any user-generated events sent to Freshpaint and Segment.

Capable identities allow you to:

  • Analyze funnels by visualizing user streams in downstream analytics platforms such as Amplitude
  • Track the end-to-end journeys of specific users
  • Use events to trigger actions such as sending an email or an SMS in communications platforms (e.g., Iterable). This allows you to send specific messaging to users depending on the actions they have taken or actions you want them to take

An example user event stream in Amplitude. Using the Capable identity ID, you get a coherent stream of events all tied to the correct user, allowing you to follow their end-to-end journey and analyze funnel health.

How to use a Capable Health identity

There are three ways to create a new identity ID in Capable Health:

  1. Using the Leads endpoint: When you create an anonymous Lead, the response from Capable Health will include an identity object with an id property. This id represents a new Capable identity ID. You may want to create a Lead when a new user lands on your website for the first time, or at any point before they sign up for an account. You can then include this ID as the value for the identity_id parameter when creating a Submission or a Patient in Capable, tying them together.
  2. Using an anonymous Submission: A user of your application can take a Capable Health Questionnaire anonymously. If they do, the response returned when you create the initial Submission will include an identity_id. Alternatively, if you have already created a Lead, you can pass the existing Lead's identity ID to the Submission. Then, if a user creates an account, you can pass the identity_id from the anonymous Submission as a parameter in the Patient object.
  3. Create a Patient: If you create a Patient without passing an identity_id from an anonymous Lead or Submission, a new identity_id will be assigned to the Patient.

Once you have an identity ID for a user, you should store it in client-side storage or in a database for future interactions with Capable Health, at least until the user becomes a Patient, at which point you can retrieve their identity_id from the Patient object.

The identity ID will allow you to track the lifecycle of a user. It will also let you save a partially completed Submission, allowing a user to leave their browser and retain their progress when they return, all without needing to sign up for an account.

You can also use the identity ID to track frontend interactions with Freshpaint or Segment. By doing so, a user's frontend actions are attributed to the same identity as their actions tracked in Capable Health.

Adding an external identity ID

If your application already generates an ID associated with each user or session — an ID provided by an analytics tool, for instance — you can link that ID to identity in Capable Health by passing it to the identity_external_id parameter. You can pass this parameter when creating a Lead, a Submission, and when updating a Patient.

The identity_external_id will be available in Freshpaint, Segment and any other downstream platforms together with the Capable Health identity ID. Tying the identity_external_id to Capable entities allows you to combine multiple user event streams in analytics platforms.

Adding user properties to an identity

The following user properties are added to an identity when a Patient is created:

  • first_name
  • last_name
  • email

If you want to add these user properties to the Freshpaint identity prior to the patient being created in Capable Health (e.g., when a user submits their email address on your frontend), you can follow instructions in Freshpaint's documentation.

You can also add to your Freshpaint user properties, but you should ensure compliance standards for your company and downstream platforms by using the Freshpaint HIPAA ALLOW LIST to filter PHI.