Sync from HealthSherpa to your CRM

This pattern demonstrates how to sync contacts from HealthSherpa Medicare into your CRM using the contact search endpoint. You can run this one contact at a time from a button on the contact profile in your CRM, or loop through a contact list and call the search endpoint for each contact.

View the V1 Search Contact endpoint or V2 Search Contact endpoint documentation.

Overview

1. Initial Setup

   • Choose the API version your integration will use:

     • For v1 API key integrations:

       • Create an API client with your HealthSherpa API key

       • Store the API key securely in your system

       • Include the agent's email address in each search request - must match their HealthSherpa account

     • For v2 OAuth integrations:

       • Configure OAuth with HealthSherpa, request the partner_api_v2 scope

       • Store and refresh OAuth access tokens securely

       • Search requests are performed on behalf of the authenticated agent, so agent_email is not required

   • Store the HealthSherpa contact ID on CRM records when a match is found

2. Agent Authentication

   • Provide a "Login to HealthSherpa" button in your CRM

   • When clicked, open HealthSherpa login page in a new tab

   • Agent logs in to HealthSherpa separately

3. Contact Import Flow

   • When a user clicks "Sync from HealthSherpa" on a CRM contact profile:

     1. Build search parameters from the CRM contact

     2. Call the HealthSherpa contact search endpoint

     3. If a matching HealthSherpa contact is found:

        • Map the returned HealthSherpa fields to your CRM fields

        • Update the CRM contact

        • Store the returned HealthSherpa contact ID

     4. If no matching contact is found:

        • Leave the CRM contact unchanged

        • Show a user-friendly "No matching HealthSherpa contact found" message

4. Bulk Sync Flow

   • To sync a list of CRM contacts:

     1. Loop through the contacts in your CRM

     2. For each contact, call the HealthSherpa contact search endpoint

     3. Update only records where a matching HealthSherpa contact is returned

     4. Track sync status per contact so users can review matches, misses, and errors

5. Search Matching

   • You can search by medicare_number alone

   • Or search by first_name or last_name plus at least one of:

     • date_of_birth

     • email

     • phone

6. Data Mapping

   • Map HealthSherpa contact fields into your CRM fields

7. Error Handling

   • Handle API errors and validation errors

   • Log failed sync attempts for review

   • Avoid overwriting CRM data when the search response does not contain a match

   • Show clear messages for "no match", "invalid search parameters", and authentication errors