Overview
The MDI integration connects Tellescope with MD Integrations' telemedicine platform. When configured, form submissions automatically create cases in MDI, including patient information, uploaded files, and questionnaire responses. The integration also supports bidirectional messaging as patient chat messages are forwarded to MDI, and provider responses are synced back to Tellescope.
Prerequisites
Before setting up the MDI integration, ensure you have:
- An MD Integrations account
- Admin access to your Tellescope organization
- Your MDI Client ID, API Key, and Webhooks Secret (generated in the MDI partners portal)
- A configured form in Tellescope that will sync to MDI
1. Enable the MDI Integration
In the Integrations page in Tellescope, find the MD Integrations card. Click the card and provide:
- Client ID and Client Secret — your MDI API credentials. These can be generated in the MDI partner platform under Integration > Resources > Credentials.
- Webhooks Secret — the authorization token used to authenticate inbound webhook events from MDI. This value must match what you configure in MDI (see step 2). You can use any randomly generated string; we recommend a minimum of 12 characters.
- Environment — Sandbox or Production
Tellescope will validate your credentials against the MDI API before saving. Once saved, the integration is active for your organization.
2. Enable Webhooks in the MDI partner platform
In the MDI Partner Platform:
- Navigate to Integration > Resources > Webhooks
- Select your Environment (Sandbox or Live)
- Set the Webhook URL to:
https://api.tellescope.com/v1/webhooks/mdi - Enter the Webhook Authorization Secret you defined in step 1
3. Configure Your Form in Tellescope
On any form you want to sync to MDI, navigate to the form's Integrations settings and add one or more Case Offerings. Each offering corresponds to an MDI offering_id, which you obtain from the MDI partner platform by navigating to Operations > Offerings.
Offerings tell MDI what service or treatment this form submission represents and are required for a case to be created successfully. Each offering can optionally have conditions attached. If conditions are configured, that offering is only sent to MDI when the form response matches those conditions. Offerings without conditions are always sent.
Note: If you are submitting forms via the Tellescope API rather than through a Tellescope-hosted form, additional configuration is required. See MDI Custom Form Submissions for details.
4. Set Up Required Form Fields
Tellescope uses standard enduser profile fields for patient demographics — these are populated automatically if the enduser record is complete:
| Field | Notes |
|---|---|
| First Name (fname) | |
| Last Name (lname) | |
| Email (email) | |
| Date of Birth (dateOfBirth) | Automatically converted to YYYY-MM-DD format for MDI |
| Phone (phone) | Cell phone type is assumed |
| Address Line 1 (addressLineOne) | |
| City (city) | |
| State (state) | |
| ZIP Code (zipCode) | |
| Height (height) | Full height in inches (e.g. 74 for 6'2") — converted to cm automatically |
| Weight (weight) | Weight in pounds — converted to kg automatically |
In addition, the following medical intake fields can be captured on your form using the corresponding External IDs:
| Field Purpose | External ID | Field Type |
|---|---|---|
| Allergies | allergies | Text |
| Current Medications | current_medications | Text |
| Medical Conditions | medical_conditions | Text |
| Special Necessities | special_necessities | Text |
| Pregnancy Status | pregnancy | Yes/No |
| Intro Video | intro_video_id | File Upload (video) |
To set an External ID on a form field, open the field in the form editor and enter the value in the External ID field.
5. Add File Upload Fields
MDI supports a range of document types. Tellescope determines the correct MDI file type automatically based on the field's External ID, using the following prefix format:
mdi:<file-type>
For example, a field with External ID mdi:driver-license will be uploaded to MDI as a driver's license document. Supported file types:
| MDI File Type | External ID |
|---|---|
| Driver's License | mdi:driver-license |
| Insurance Policy | mdi:insurance-policy |
| Lab Result | mdi:lab-result |
| Auth Form | mdi:auth-form |
| iPledge Document | mdi:ipledge-document |
| Full Body Photo | mdi:full-body-photo |
| Back Photo | mdi:back-photo |
| Face Photo | mdi:face-photo |
| Avatar Photo | mdi:avatar-photo |
| Photo (generic) | mdi:photo |
| Document (generic) | mdi:document |
If no mdi: prefix is set, Tellescope will infer the file type from the field's title keywords or the uploaded file's MIME type (images → photo, videos → av-video, PDFs/other → document).
6. Add Optional Questionnaire Fields
Any other form fields will be synced to MDI as case questions — no additional configuration is required. Each question's title and the patient's response are sent as a question/answer pair.
For multiple choice or dropdown questions, all available answer options are included alongside the selected response.
Empty responses are automatically excluded from the sync.
Patient Workflow
When a patient completes an MDI-enabled form:
- Form Submission — Patient fills out the form with all required information
- File Upload — Any uploaded files are transferred to MDI and associated with the case
- Patient Upsert — Tellescope checks whether a patient record already exists in MDI (matched by Tellescope enduser ID). If not, a new patient is created; if so, their record is updated
- Case Creation — A case is created in MDI with the patient's information, uploaded files, questionnaire responses, and configured offerings
- Reference Storage — The MDI case ID is stored on the Tellescope form response for traceability
- Ongoing Messaging — Subsequent patient chat messages are automatically forwarded to MDI, and provider replies are synced back to the patient in Tellescope
Webhooks
Tellescope receives real-time status updates from MDI via webhooks. These updates allow Tellescope to reflect the current state of a case without polling.
Supported Events
Case Status Updates — When a case status changes in MDI (e.g., Created, Assigned to Clinician, Approved, Completed, Cancelled, Support, Waiting, Processing), Tellescope automatically updates:
- The enduser's MDI Case Status custom field
- The enduser's MDI Case Updated At custom field
- The associated form response's status
Prescription / Offering Submissions — When a clinician submits a prescription offering, Tellescope creates or updates an Enduser Medication record with details including medication name, NDC, dosage, refills, and days supply.
Order Updates — Order status changes and tracking number updates are reflected in Tellescope as Enduser Order records.
Lab Results — When lab results are processed in MDI, the file is automatically downloaded and stored in Tellescope's Files for the associated enduser.
Messages — Inbound messages from MDI providers are delivered to the patient's Tellescope chat thread.
Error Handling
If errors occur during case creation or file upload, they are logged as background errors in Tellescope and will not block the form submission from completing. Common errors include:
- Missing required patient fields — Ensure the enduser's profile is complete before form submission
- File upload failure — The case will still be created; the file will be skipped and the error logged
- Invalid credentials — Re-verify your Client ID and API Key in the Integrations settings
- Invalid webhook secret — Events from MDI will be rejected; verify the Webhooks Secret matches what MDI has configured
- Case/form response not found — May occur if a webhook event arrives before Tellescope has finished processing the form submission
Troubleshooting
Form not syncing to MDI:
- Verify that at least one Case Offering is configured on the form's Integrations settings
- Confirm that the integration is active and credentials are valid in the Integrations page
- Check that required enduser fields (name, email, date of birth, address) are populated
Files not appearing in MDI:
- Confirm the field's External ID uses the
mdi:<type>prefix format - Ensure uploaded files are in a supported format (images, video, or PDF)
Patient not found or duplicate patients:
- MDI matches patients using the Tellescope enduser ID stored in the patient's metadata field — avoid creating duplicate enduser records in Tellescope for the same patient
Case status not updating in Tellescope:
- Verify your Webhooks Secret is correctly configured in both Tellescope and MDI
- Confirm MDI has your Tellescope webhook URL on file
Messages not syncing:
- Ensure the enduser has an active chat room in Tellescope
- Messages authored by the patient in Tellescope are not re-forwarded to MDI to prevent duplicate messages
Comments
0 comments
Article is closed for comments.