> For the complete documentation index, see [llms.txt](https://docs.medicare.healthsherpa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.medicare.healthsherpa.com/integration-guide/integration-patterns/sync-from-healthsherpa-to-your-crm.md).

# 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.

{% hint style="info" %}
View the [V1 Search Contact](/api-reference/version-1-api-keys/endpoints/search-contact.md) endpoint or [V2 Search Contact](/api-reference/version-2-oauth/endpoints/search-contact.md) endpoint documentation.
{% endhint %}

### 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](https://medicare.healthsherpa.com/sessions/new) 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