> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/integrations-and-plugins/integrations/healthsherpa.md).

# HealthSherpa

Initiate Medicare quotes in HealthSherpa from Contact Records in AgentCRM, and synchronize enrollment data with HealthSherpa.

{% hint style="success" %}
**Audience:** Admins, Developers, Solution Architects

**Purpose:** Provides a high-level look at the features and capabilities of the HealthSherpa integration for AgentCRM.
{% endhint %}

## Overview

With the HealthSherpa integration for AgentCRM, you can:

* Launch HealthSherpa from a <code class="expression">space.vars.contact</code> <code class="expression">space.vars.entity</code> in AgentCRM to begin a Medicare quote for this <code class="expression">space.vars.contact</code>.
* Automatically receive Medicare enrollment submissions from HealthSherpa. The integration updates existing AgentCRM <code class="expression">space.vars.contacts</code> or creates new AgentCRM <code class="expression">space.vars.contacts</code> accordingly.

{% hint style="info" %}
**Note:** This integration is exclusive to AgentCRM. It doesn't appear in the general App Marketplace for <code class="expression">space.vars.Kizen\_company\_name</code>.
{% endhint %}

### What Is the HealthSherpa Integration?

The HealthSherpa integration connects HealthSherpa to AgentCRM. Once you establish the connection, you can initiate a Medicare quote for an AgentCRM <code class="expression">space.vars.contact</code> in HealthSherpa, while Medicare enrollments in HealthSherpa automatically update AgentCRM <code class="expression">space.vars.contacts</code> with new or missing information upon submission.

### When to Use the HealthSherpa Integration

Use the HealthSherpa integration when you want to start Medicare quotes in HealthSherpa from your <code class="expression">space.vars.contact</code> <code class="expression">space.vars.entities</code> in AgentCRM and automate the transfer of enrollment information from HealthSherpa to AgentCRM. Once the data exists in AgentCRM, you can work with it in <code class="expression">space.vars.automations</code>.

{% hint style="info" %}
**Note:** If you transform or update enrollment data in AgentCRM, you can't write it back to HealthSherpa at this time. To protect the integrity of the original data, the connection goes one way only.&#x20;
{% endhint %}

#### Common Use Cases

Here are some common use cases of the HealthSherpa integration:

* Starting a Medicare quote for an AgentCRM <code class="expression">space.vars.contact</code> in HealthSherpa while speaking with them over the phone
* Monitoring every downline agent's business from a single view in AgentCRM
* Triggering welcome automations for new members from HealthSherpa enrollment submissions

***

## How the HealthSherpa Integration Works

Before you configure the HealthSherpa integration, it's important to understand how it works.

### Connection Model

Each AgentCRM user must authorize their own HealthSherpa agent account through the integration using OAuth to be able to start Medicare quoting sessions from AgentCRM. However, the synchronization of Medicare enrollment data from HealthSherpa to AgentCRM happens by way of a single, agency-wide webhook URL and API key. For details on both, see [Connect HealthSherpa to AgentCRM](/docs/integrations-and-plugins/integrations/healthsherpa/connect-healthsherpa-to-agentcrm.md).

Enrollment synchronization runs through a webhook-triggered <code class="expression">space.vars.smartconnector</code> on the AgentCRM side. HealthSherpa sends a webhook each time an application is submitted, and the <code class="expression">space.vars.smartconnector</code> collects those webhooks and processes them in batches every 30 seconds. Each batch creates or updates the corresponding <code class="expression">space.vars.contact</code>s in AgentCRM, so a submitted application usually appears within a minute.

### Authorization

AgentCRM automatically handles the refresh process for HealthSherpa authentication tokens, so most agents don't need to reestablish their HealthSherpa connection under normal circumstances. If an agent loses access to HealthSherpa, they can re-authenticate through the integration. For more information, see [Connect HealthSherpa to AgentCRM](/docs/integrations-and-plugins/integrations/healthsherpa/connect-healthsherpa-to-agentcrm.md).&#x20;

### Client Identification

The integration matches an AgentCRM <code class="expression">space.vars.contact</code> with a HealthSherpa contact by first and last name plus Medicare number, date of birth, email, or phone. If more than one HealthSherpa contact meets these criteria, HealthSherpa sends back the most recent one, which may or may not be the correct person. To fix this, clean up the duplicate records in HealthSherpa. Add or remove values such as the Medicate number, date of birth, email, and phone so that only the correct contact matches.

### Failure Handling

If HealthSherpa sends a Medicare submission and the integration doesn't receive it because of a bad Internet connection, HealthSherpa retries three times: after 20 seconds, after 10 minutes, and after 1 hour. After that, the submission is lost. Re-initiate the quote through AgentCRM to restart the process.&#x20;

### Medicare Enrollment Field Mapping

Medicare enrollment submission data in HealthSherpa maps to specific data structures in AgentCRM. When someone submits a Medicare enrollment on the HealthSherpa side, the integration passes the relevant data to the corresponding <code class="expression">space.vars.entities</code> and <code class="expression">space.vars.fields</code> on the AgentCRM side. Specifically:

* Client data in HealthSherpa maps to <code class="expression">space.vars.fields</code> of <code class="expression">space.vars.contacts</code> in AgentCRM.
* Enrollment data in HealthSherpa maps to <code class="expression">space.vars.fields</code> of Enrollment <code class="expression">space.vars.objects</code> in AgentCRM.
* Carrier data in HealthSherpa maps to <code class="expression">space.vars.fields</code> of Carrier <code class="expression">space.vars.objects</code> in AgentCRM.
* Pharmacy data in HealthSherpa maps to <code class="expression">space.vars.fields</code> of Pharmacy <code class="expression">space.vars.objects</code> in AgentCRM.
* Drug data in HealthSherpa maps to <code class="expression">space.vars.fields</code> of Drug <code class="expression">space.vars.objects</code> in AgentCRM.
* Provider data in HealthSherpa maps to <code class="expression">space.vars.fields</code> of Provider <code class="expression">space.vars.objects</code> in AgentCRM.

The following expandable sections describe these mappings in more detail.

<details>

<summary>Client Data Field Mapping</summary>

Client data in HealthSherpa maps to the following <code class="expression">space.vars.fields</code> of AgentCRM <code class="expression">space.vars.contacts</code>:

<table data-search="false"><thead><tr><th>Kizen Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>First Name</strong></td><td><code>String</code></td><td>The client's first name.</td></tr><tr><td><strong>Last Name</strong></td><td><code>String</code></td><td>The client's last name.</td></tr><tr><td><strong>Email</strong></td><td><code>String</code></td><td>The client's email address.</td></tr><tr><td><strong>Birthday</strong></td><td><code>String</code></td><td>The client's date of birth in <code>YYYY-MM-DD</code> format.</td></tr><tr><td><strong>Medicare Number</strong></td><td><code>String</code></td><td>The client's Medicare number.</td></tr><tr><td><strong>Mobile Phone</strong></td><td><code>String</code></td><td>The client's mobile phone number. This string must consist of digits only and be exactly 10 characters long.</td></tr><tr><td><strong>Home Phone</strong></td><td><code>String</code></td><td>The client's home phone number. This string must consist of digits only and be exactly 10 characters long.</td></tr><tr><td><strong>Business Phone</strong></td><td><code>String</code></td><td>The client's business phone number. This string must consist of digits only and be exactly 10 characters long.</td></tr><tr><td><strong>Gender</strong></td><td><code>String</code></td><td>The client's gender. AgentCRM supports multiple genders, but the integration doesn't send values other than <code>Male</code> and <code>Female</code> to HealthSherpa.</td></tr><tr><td><strong>Street Address</strong></td><td><code>String</code></td><td>The client's street address.</td></tr><tr><td><strong>Street Address 2</strong></td><td><code>String</code></td><td>The second line of the client's street address, if any.</td></tr><tr><td><strong>City</strong></td><td><code>String</code></td><td>The client's city of residence.</td></tr><tr><td><strong>State</strong></td><td><code>Object</code></td><td>The full name of the client's state of residence, mapped internally to the corresponding two-letter abbreviation.</td></tr><tr><td><strong>Zipcode</strong></td><td><code>String</code></td><td>The ZIP code associated with the client's street address.</td></tr><tr><td><strong>Pharmacies</strong></td><td><code>Array</code></td><td>An array of pharmacy IDs for the pharmacies associated with the client <code class="expression">space.vars.entity</code>.</td></tr><tr><td><strong>Medications</strong></td><td><code>Array</code></td><td>An array of the medication IDs for the medications associated with the client <code class="expression">space.vars.entity</code>.</td></tr><tr><td><strong>Providers</strong></td><td><code>Array</code></td><td>An array of the provider IDs for the providers associated with the client <code class="expression">space.vars.entity</code>.</td></tr></tbody></table>

</details>

<details>

<summary>Enrollment Data Field Mapping</summary>

Client data in HealthSherpa maps to the following <code class="expression">space.vars.fields</code> of AgentCRM Enrollment <code class="expression">space.vars.objects</code>:

<table data-search="false"><thead><tr><th>Kizen Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>Enrollment Name</strong></td><td><code>String</code></td><td>The name of the enrollment</td></tr><tr><td><strong>Carrier</strong></td><td><code>String</code></td><td>The carrier associated with the enrollment</td></tr><tr><td><strong>Stage</strong></td><td><code>String</code></td><td>The stage of the enrollment</td></tr><tr><td><strong>Plan Year</strong></td><td><code>String</code></td><td>The plan year associated with the enrollment</td></tr><tr><td><strong>Product</strong></td><td><code>String</code></td><td>The product associated with the enrollment</td></tr><tr><td><strong>Product Detail</strong></td><td><code>String</code></td><td>Additional information about the product associated with the enrollment</td></tr><tr><td><strong>Effective Date</strong></td><td><code>DateTime</code></td><td>The effective date of the enrollment</td></tr><tr><td><strong>Enrollment Code</strong></td><td><code>String</code></td><td>The enrollment code</td></tr><tr><td><strong>Premium</strong></td><td><code>Decimal</code></td><td>The premium price associated with the enrollment</td></tr><tr><td><strong>Agent NPN</strong></td><td><code>String</code></td><td>The National Product Number of the agent associated with the enrollment</td></tr><tr><td><strong>Description</strong></td><td><code>String</code></td><td>The description of the enrollment</td></tr></tbody></table>

The plan types in HealthSherpa correspond to the following products in AgentCRM:

| HealthSherpa plan type | AgentCRM product |
| ---------------------- | ---------------- |
| `mapd`                 | `MAPD`           |
| `ma`                   | `MA`             |
| `pdp`                  | `PDP`            |
| `med_supp`             | `MSUP`           |

The plan subtypes in HealthSherpa correspond to the following product details in AgentCRM:

| HealthSherpa plan subtypes    | AgentCRM product    |
| ----------------------------- | ------------------- |
| `hmo`, `hmopos`, `cost`       | `HMO`               |
| `ppo`, `lppo`, `rppo`, `pffs` | `PPO`               |
| `pdp`                         | `PDP`               |
| `msa`                         | `MA`                |
| `dsnp/csnp/isnp`              | `D-SNP/C-SNP/I-SNP` |

{% hint style="info" %}
**Note:** For any other HealthSherpa plan subtype, AgentCRM converts the lowercase value from HealhSherpa to an uppercase value. For example, `epo` becomes `EPO`.
{% endhint %}

</details>

<details>

<summary>Carrier Data Field Mapping</summary>

Carrier data in HealthSherpa maps to the following <code class="expression">space.vars.fields</code> of AgentCRM Carrier <code class="expression">space.vars.objects</code>:

<table data-search="false"><thead><tr><th>Kizen Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>Carrier Name</strong></td><td><code>String</code></td><td>The name of the carrier</td></tr></tbody></table>

</details>

<details>

<summary>Pharmacy Data Field Mapping</summary>

Pharmacy data in HealthSherpa maps to the following <code class="expression">space.vars.fields</code> of AgentCRM Pharmacy <code class="expression">space.vars.objects</code>:

<table data-search="false"><thead><tr><th>Kizen Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td><code>String</code></td><td>The NPI or name of the pharmacy.</td></tr><tr><td><strong>Pharmacy Name</strong></td><td><code>String</code></td><td>The name of the pharmacy.</td></tr><tr><td><strong>Type</strong></td><td><code>String</code></td><td>The type of the pharmacy, either <code>Retail Pharmacy</code> or <code>Digital Pharmacy</code>.</td></tr><tr><td><strong>NPI</strong></td><td><code>String</code></td><td>The NPI of the pharmacy.</td></tr><tr><td><strong>Phone Number</strong></td><td><code>String</code></td><td>The pharmacy's phone number. This string must consist of digits only.</td></tr><tr><td><strong>Street Address</strong></td><td><code>String</code></td><td>The pharmacy's street address.</td></tr><tr><td><strong>Street Address 2</strong></td><td><code>String</code></td><td>The second line of the pharmacy's street address, if any.</td></tr><tr><td><strong>City</strong></td><td><code>String</code></td><td>The city in which the pharmacy is located.</td></tr><tr><td><strong>State</strong></td><td><code>String</code></td><td>The two-letter abbreviation corresponding to the state in which the pharmacy is located.</td></tr><tr><td><strong>Zip</strong></td><td><code>String</code></td><td>The ZIP code associated with the pharmacy's street address.</td></tr></tbody></table>

</details>

<details>

<summary>Drug Data Field Mapping</summary>

Drug data in HealthSherpa maps to the following <code class="expression">space.vars.fields</code> of AgentCRM Drug <code class="expression">space.vars.objects</code>:

<table data-search="false"><thead><tr><th>Kizen Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>Drug Name</strong></td><td><code>String</code></td><td>The NDC or name of the medication in the following format: <code>{ndc_or_drug name}-{quantity}.0-{frequency}</code></td></tr><tr><td><strong>Name and Dosage</strong></td><td><code>String</code></td><td>The prescription name and dosage of the medication in the following format: <code>{prescription_name} {dosage_name}</code></td></tr><tr><td><strong>NDC</strong></td><td><code>String</code></td><td>The medication's National Drug Code</td></tr><tr><td><strong>Quantity</strong></td><td><code>Number</code></td><td>The quantity prescribed of the medication</td></tr><tr><td><strong>Frequency</strong></td><td><code>Number</code></td><td>The supply of the medication in days: <code>30</code>, <code>60</code>, <code>90</code>, <code>180</code>, or <code>365</code></td></tr><tr><td><strong>Connecture Drug ID</strong></td><td><code>String</code></td><td>The ID of the medication in ConnectureDRX</td></tr><tr><td><strong>Connecture Dosage ID</strong></td><td><code>String</code></td><td>The ID of the medication's dosage in ConnectureDRX</td></tr></tbody></table>

</details>

<details>

<summary>Provider Data Field Mapping</summary>

Provider data in RetireFlo maps to the following <code class="expression">space.vars.fields</code> of AgentCRM Provider <code class="expression">space.vars.objects</code>:

<table data-search="false"><thead><tr><th>Kizen Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><strong>Provider Name</strong></td><td><code>String</code></td><td>The NPI or name of the provider or hospital.</td></tr><tr><td><strong>Full Name</strong></td><td><code>String</code></td><td>The full name of the provider or hospital.</td></tr><tr><td><strong>Last Name</strong></td><td><code>String</code></td><td>The last name of the provider.</td></tr><tr><td><strong>NPI</strong></td><td><code>String</code></td><td>The National Provider Identifier of the provider or hospital.</td></tr><tr><td><strong>Address</strong></td><td><code>String</code></td><td>The street address of the provider or hospital.</td></tr><tr><td><strong>City</strong></td><td><code>String</code></td><td>The city in which the provider or hospital is located.</td></tr><tr><td><strong>State</strong></td><td><code>Object</code></td><td>The full name of the state in which the provider or hospital is located, mapped internally to the corresponding two-letter abbreviation.</td></tr></tbody></table>

</details>

***

## How to Use the HealthSherpa Integration

For step-by-step instructions on using the HealthSherpa integration, see the following topics:

* [Connect HealthSherpa to AgentCRM](/docs/integrations-and-plugins/integrations/healthsherpa/connect-healthsherpa-to-agentcrm.md)
* [Start a Medicare Quote in HealthSherpa from AgentCRM](/docs/integrations-and-plugins/integrations/healthsherpa/start-a-medicare-quote-in-healthsherpa-from-agentcrm.md)
* [Synchronize Medicare Enrollments from HealthSherpa to AgentCRM](/docs/integrations-and-plugins/integrations/healthsherpa/synchronize-medicare-enrollments-from-healthsherpa-to-agentcrm.md)
* [Troubleshoot HealthSherpa](/docs/integrations-and-plugins/integrations/healthsherpa/troubleshoot-healthsherpa.md)

***

## What's Next

Continue to [Connect HealthSherpa to AgentCRM](/docs/integrations-and-plugins/integrations/healthsherpa/connect-healthsherpa-to-agentcrm.md) to authorize agent accounts and set up the webhook.

<details>

<summary><strong>Related Topics</strong></summary>

* [Connect HealthSherpa to AgentCRM](/docs/integrations-and-plugins/integrations/healthsherpa/connect-healthsherpa-to-agentcrm.md)
* [Start a Medicare Quote in HealthSherpa from AgentCRM](/docs/integrations-and-plugins/integrations/healthsherpa/start-a-medicare-quote-in-healthsherpa-from-agentcrm.md)
* [Synchronize Medicare Enrollments from HealthSherpa to AgentCRM](/docs/integrations-and-plugins/integrations/healthsherpa/synchronize-medicare-enrollments-from-healthsherpa-to-agentcrm.md)
* [Troubleshoot HealthSherpa](/docs/integrations-and-plugins/integrations/healthsherpa/troubleshoot-healthsherpa.md)

</details>

***

*HealthSherpa's name, logo, and all related names, logos, product and service names, designs and slogans are trademarks of HealthSherpa. Kizen's HealthSherpa integration is not affiliated with, sponsored by, or endorsed by HealthSherpa.*


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.kizen.com/docs/integrations-and-plugins/integrations/healthsherpa.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.