> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.medicare.healthsherpa.com/integration-guide/integration-patterns/sync-from-healthsherpa-to-your-crm.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.