Formsort

Flows and Variants

Each "Flow" in Formsort should map to a single Form in Tellescope. If you want multiple forms to sync from Formsort to Tellescope, they should each have their own Flow. 

Response handling logic

Handling Multiple Submissions of the Same Form

If you expect users to submit the same form multiple times (e.g. one of your team members submits on behalf of patients), make sure to turn on "Start each session as a new responder" in the Settings for each Flow. If this setting is off, users who submit the same form multiple times in the same browser will only be recorded once in Tellescope.

NOTE: If users will only be submitting a form once and you plan on utilizing the responder UUID to allow users to return to the point they left off in the form, you will need to disable the "Start each session as a new responder" setting (more on responder UUIDs below).

Incomplete Form (Unfinalized Webhook)

• We must have at least one of "email" or "phone" (see Patient Matching / Insert) below, or we will ignore the webhook
• We will attempt to match an existing Enduser by matching on email or phone, and if there is no match, will insert a new one
• Will will store the form response in an "unsubmitted" state (submittedAt is not defined)
• Each "unfinalized" webhook notification for the same responder_uuid will update the incomplete form with the new responses
• We will not post webhooks or leverage a Form Submitted trigger
• Forms which stay in an unsubmitted state are candidates for our Form Unsubmitted trigger to fire

Submitted Form (Finalized Webhook)

• We will attempt to match an existing patient by matching on email or phone, and if there is no match, will insert a new one
  • If email and phone are not provided, we will always create a new Enduser record for handling this response
• Will will store the form response in an "submitted" state (submittedAt is set)
• Future webhooks for the same responder_uuid will be ignored
• Tellescope will emit our own Webhook for "create" "form_responses"
• Form Submitted triggers will be handled

Patient Matching / Insert

Form submissions from Formsort will create a new patient or match an existing patient in Tellescope. Matching to an existing patient is done by email or phone number, and the Formsort form must have questions with keys “email” and “phone” accordingly. Keys “first_name” and “last_name” will also be recognized when inserting a new patient/contact to Tellescope by populating our First Name and Last Name fields. Keys show in the Formsort editor as “Variable”.

 

Stripe Matching

It is common to use Stripe to collect a payment during forms. The stripeCustomerId field on Tellescope's Enduser model should be set to ensure that Stripe Webhooks match the correct Enduser in Tellescope. If no Enduser matches to the Stripe Customer ID, customer email will be used for matching instead. This field should be set in Tellescope before any Stripe payments (or other webhook events) have processed. 

Variable Mapping to Tellescope Fields

Per the above section, defining specific "Variables" in FormSort allows Tellescope to sync responses as built-in and custom fields. The following table demonstrates which FormSort variables map to Tellescope fields. For secondary insurance, you can use "secondaryInsurance" instead of "insurance". 

Variables are automatically saved as "externalId" in Tellescope responses, which are passed through to OpenLoop integration. To prevent syncing a variable as an externalId on a Tellescope question, prefix the variable with "ts_ignore" in FormSort.

FormSort Variable (case sensitive)	Tellescope Field / Details
email	Email
phone	Phone Number
first_name	First Name
last_name	Last Name
dateOfBirth	Date of Birth
gender	Gender
healthie_dietitian_id	The provider ID that should be used if syncing the patient (creating) in Healthie
height	The patient's full height in inches as a number (e.g. a 6'2'' patient would be 74)
weight	The patient's weight in pounds as a number
timezone	Must be a valid timezone like "US/Central" or it will not sync
address	Must use "Address" question type in FormSort. Syncs to addressLineOne, zipCode, state, etc.
defaultFromPhone	A phone number (if your account has more than 1) to use as the default
useDefaultFromPhoneInAutomations	boolean, use the above phone number for all automated messages
defaultFromEmail	An email address (if your account has multiple senders) to use as the default
useDefaultFromEmailInAutomations	boolean, use the above email for all automated messages
language	To sync with Healthie, currently only "Spanish" is supported
termsVersion	Version of terms a patient has consented to. A string value "1.0" is the default version for our portal. If the value is "1.0", our portal will not prompt patients to re-consent when they first open it. If you set a different version value in the portal settings, you will want to match the current version value.
ts_enduser_customField	A custom field called "customField"
insurance.memberId	Primary insurance member ID
insurance.payerId	Payer ID
insurance.payerName	Payer (Name)
insurance.groupNumber	Group Number
insurance.relationship	Relationship to Subscriber
insurance.relationshipDetails.fname	Subscriber first name
insurance.relationshipDetails.lname	Subscriber last name
insurance.relationshipDetails.dateOfBirth	Subscriber date of birth
insurance.relationshipDetails.gender	Subscriber gender

If an existing enduser is matched, these fields will be updated upon form submission

Webhook Setup

When a form is submitted in Formsort, you’ll have it post a Webhook to Tellescope in order to store the response. To proceed, you will need an API Key (secret key) from your Tellescope Settings and a placeholder form created in Tellescope to represent responses from Formsort.

In the Integrations menu for a given flow in Formsort, select Webhooks

Make sure Tellescope is included as a destination with the following settings

• Webhook Posting Frequency
  • “When the flow is finalized” or “When the flow is finalized or abandoned”
    • We currently only handle finalized form submissions
• Webhook URL (no line break)
  • https://api.tellescope.com/v1/webhooks/formsort/API_KEY_HERE?formId=FORM_ID_HERE
  • Replace the API_KEY_HERE and FORM_ID_HERE values with the relevant details from your account
  • The formId is the value you find at the end of the URL when editing a form in Tellescope
• Webhook Posting Method (shouldn’t need to change from default)
  • POST_JSON
• Webhook Posting Security (shouldn’t need to change from default)
  • Default
• Responder UUID Alias (shouldn’t need to change from default)
  • responder_uuid
• Make sure to check “Nest answers” AND “Transpose answers into an array”

Automation

• Formsort submissions can cause Form Submitted triggers in Tellescope, when the formId from the webhook URL matches the corresponding placeholder form in Tellescope.
• For abandoned forms with at least one email or phone number, the Form Unsubmitted trigger will also work
• The placeholder form in Tellescope must have at least 1 question in order to show as available in a Trigger
• Conditional logic on the responses of a form are not supported for a Formsort submission, but conditional logic on patient/contact fields are supported

Supported Question Types

The following question types are explicitly supported

• Text
• Email
• Phone
• Select
  • Single or multiple choice
• File (see below)

All other responses should be coerced to a string value and stored

File Uploads

Add an S3 credential in Formsort with the bucket tellescope-formsort and the region us-east-2. The bucket is already configured to work with Formsort.

In the Integrations for a specific form, go to S3, and select this credential. In the base path, enter your businessId, found next to your organization name in Settings/Organization.

Leveraging Responder UUIDs

Formsort offers the ability to identify individual responders using a unique ID know as a responder UUID. You can leverage the responder UUID to allow a patient to return to the point at which they left off when completing a form with the previous data pre-populated.

Steps to Utilize the Responder UUID within Formsort

These steps are also outlined in Formsort's guide, though there are additional considerations outlined in the steps below:

1. Within the specific Formsort form variant, navigate to Variables > System Library > Browse Library.
2. Search for and add the responder UUID.
3. Once added, click the three dots to the right of the variable to access Options and select Edit.
4. Rename the variable to ts_enduser_responder_uuid.
5. Click the Settings tab and make sure the 'Start each session as a new responder' setting is disabled

Steps to Utilize the Responder UUID within Tellescope

1. Navigate to Settings > Organization, scroll to the bottom of the page and click the ADD button to create a custom field for all patients.
2. Click the 'pencil' icon to edit the field, name the field responder_uuid with an input type of 'Text' and click the SAVE button.
3. Navigate to the Templates page and click the CREATE TEMPLATE button.
4. Click the 'plus' icon, select the template type 'Link', choose your display text, and use the following URL as a guide to create the link, being sure to replace <FLOW-URL> with the URL specific to your form: https://<FLOW-URL>?responderUuid={{enduser.responder_uuid}}
   
5. Click the INSERT TEMPLATE VALUE button to insert the link in the template.
6. Build out the rest of the Template per your requirements.
7. You can now send this template via an automated step in a journey or manually via the Compose button in order for patients to pick up where they left off in the form.

Syncing to Healthie

Tellescope forms can sync directly to Healthie as chart notes (see the Charting section). 

If you're using Healthie through OpenLoop, you do not need to worry about Healthie form question IDs and can disregard this section. 

To sync from Formsort --> Tellescope --> Healthie

1. Make sure that the Formsort form is configured to sync to a Tellescope form which has the Healthie Form ID saved as its external ID (see our Healthie article for more details).

2. The Healthie question IDs must be saved in Formsort variables. The variable name must start with "healthie_" and end with the specific Healthie question ID. 

Here is how the above form shows up in Tellescope (all answers are synced):

And in Healthie (only the configured question in Formsort syncs to Healthie):

Patient Matching in Conjunction with Stripe

One common issue encountered when implementing a Formsort intake form with an embedded Stripe payment processor is 'split patients' being created. This is due to the fact that Tellescope receives a webhook from Formsort for the form response and a webhook from Stripe for the payment, both related to the same patient. This typically occurs due to a patient providing one email address in the intake form and a separate email address for the Stripe payment.

To address this issue, there are a couple of steps that can be followed:

• Ensure Webhook Posting Frequency is set to “When the flow is finalized or abandoned”
• Collect the patient's first name, last name, email address, and phone number as early as possible in the form flow
• When possible, avoid 'split intakes' (processing payments mid form flow) and instead process payment as the last step in the form
• Explicitly associate email and phone variables collected at an earlier point in the form flow with the Stripe payment question (Stripe question settings pictured below):