# Introduction The **HealthSherpa Medicare Partner API** enables agencies and partners to integrate their CRM systems with HealthSherpa’s Medicare platform. This API currently supports: * **Creating** new Contacts in the HealthSherpa system * **Updating** existing Contact information * **Keeping your CRM in sync** with HealthSherpa’s contact database Each Contact is associated with a specific agent within your agency, ensuring proper attribution and access control. The fields for the Contact cover basic demographic info, contact info, and eligibility info. The API uses standard JSON for data exchange and returns clear, structured error messages to help you maintain data integrity. **Questions?** Email # Overview
EnvironmentBase URL
Productionhttps://api.medicare.healthsherpa.com/
Staginghttps://api.medicare-staging.healthsherpa.com/
## API Versioning The HealthSherpa Medicare Partner API currently has two versions, `v1` which authenticates with **API keys** and `v2` which authenticates via **OAuth**. In addition, `v2` has support for passing **provider**, **drug**, and **pharmacy** data from your CRM to HealthSherpa for Medicare if you can guarantee data with Connecture IDs. # Version 1 (API Keys) # Getting Started To integrate with the HealthSherpa Partner API, you'll need to: 1. Create a HealthSherpa agency account ([guide](https://intercom.help/healthsherpa-medicare-help-center/en/articles/11077791-agency-accounts#h_20e92a6688)) 1. If you have downline agents, they'll link to your agency account using your join code. 2. Go to your Integrations tab, and generate a production API key ([guide](https://intercom.help/healthsherpa-medicare-help-center/en/articles/12039092-partner-api#h_059cc8d70f)) 3. Begin the [authentication process](https://docs.medicare.healthsherpa.com/authentication). {% hint style="info" %} If you'd like a **Staging** API key, email {% endhint %} # Authentication Version 1 of the HealthSherpa Partner API uses API key authentication to secure all requests. Each partner organization is provided with an unique API key that must be included in all API requests. These API keys are tied to your agency. Additionally, each endpoint requires an `agent_email` parameter which is used to authenticate individual downline agents within your agency. # API Keys ## Using Your API Key Include your API key in the `X-API-Key` header with every request: ```http X-API-Key: your_api_key_here ``` Example using cURL: ```bash curl -X POST https://api.medicare.healthsherpa.com/v1/contacts \ -H "X-API-Key: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{"first_name": "Alex", "last_name": "Lee", ...}' ``` ## API Key Management Best Practices 1. **Secure Storage** * Store API keys in environment variables or secure secret management systems * Never commit API keys to version control * Rotate keys immediately if they are accidentally exposed 2. **Access Control** * Limit access to API keys to only necessary personnel * Use different API keys for different environments (test vs production) 3. **Implementation** * Use HTTPS for API requests * Don't log API keys in error messages ## Troubleshooting If you receive a `401 Unauthorized` response: 1. Verify the API key is correctly formatted 2. Confirm you're using the correct key for your environment 3. Contact support if issues persist # Agent Authentication Each agent in your agency must have a HealthSherpa Medicare agent account that is associated with your agency account. See [this guide](https://intercom.help/healthsherpa-medicare-help-center/en/articles/11077791-agency-accounts) to learn how to create agency and downline agent accounts. If you need help, email . {% hint style="info" %} **Note:** The email account associated with the agent's HealthSherpa account **must** **match** the `agent_email` you use in API requests {% endhint %} # Endpoints # Create Contact ## Create a new contact > Creates a new contact in the HealthSherpa system. The contact will be associated with the agent specified in the request. All contacts must have an external ID, first name, and last name.
```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API","version":"1.0.0"},"servers":[{"url":"https://api.medicare.healthsherpa.com/v1","description":"Production environment"},{"url":"https://api.medicare-staging.healthsherpa.com/v1","description":"Staging environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication"}},"schemas":{"Contact":{"type":"object","required":["external_id","first_name","last_name"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":100,"description":"Your system's unique identifier for this contact. Can be set on create or updated if the current value is null."},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":100},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":100},"address_1":{"type":"string","description":"Primary address line","minLength":1,"maxLength":100},"address_2":{"type":"string","nullable":true,"description":"Secondary address line","minLength":1,"maxLength":100},"birth_date":{"type":"string","description":"Contact's date of birth","enum":["01-15-1955","01/15/1955","1955-01-15","1955/01/15"]},"city":{"type":"string","description":"City name","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","description":"Contact's email address"},"extra_help":{"type":["boolean","string"],"nullable":true,"description":"Whether the contact receives Extra Help","enum":[true,false,null]},"medicaid_eligible":{"type":["boolean","string"],"nullable":true,"description":"Whether the contact is eligible for Medicaid","enum":[true,false,null]},"medicaid_number":{"type":"string","description":"Contact's Medicaid number"},"medicare_number":{"type":"string","description":"Contact's Medicare number","minLength":1,"maxLength":1000},"medicare_part_a_effective_date":{"type":"string","description":"Medicare Part A effective date","enum":["01-01-2024","01/01/2024","2024-01-01","2024/01/01"]},"medicare_part_b_effective_date":{"type":"string","description":"Medicare Part B effective date","enum":["01-01-2024","01/01/2024","2024-01-01","2024/01/01"]},"notes":{"type":"array","description":"Array of notes about the contact. Each item in the notes array will be added as a note on the contact record. When updating, it will append to the existing notes and not overwrite any of the existing notes.","items":{"type":"string","minLength":1,"maxLength":1000},"minItems":1,"maxItems":50},"phone":{"type":"string","description":"Contact's phone number"},"sex":{"type":"string","description":"Contact's sex","enum":["male","female","M","F","m","f"]},"state":{"type":"string","description":"Two-letter state code"},"type":{"type":"string","description":"Contact type","enum":["client","lead"]},"zip":{"type":"string","description":"ZIP code"},"authorized_representative_name":{"type":"string","description":"Name of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_relationship":{"type":"string","description":"Relationship of the authorized representative to the contact","enum":["natural_child","spouse","mother","father","power_of_attorney","other"]},"authorized_representative_phone_number":{"type":"string","description":"Phone number of the authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email address of the authorized representative"},"authorized_representative_address":{"type":"string","description":"Street address of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_city":{"type":"string","description":"City of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_state":{"type":"string","description":"Two-letter state code of the authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of the authorized representative"},"mailing_address_street":{"type":"string","description":"Street address for mailing","minLength":1,"maxLength":100},"mailing_address_unit_number":{"type":"string","nullable":true,"description":"Unit number for mailing address","minLength":1,"maxLength":100},"mailing_address_city":{"type":"string","description":"City for mailing address","minLength":1,"maxLength":100},"mailing_address_state":{"type":"string","description":"Two-letter state code for mailing address"},"mailing_address_zip_code":{"type":"string","description":"ZIP code for mailing address"}}},"RedirectUrl":{"type":"string","description":"URL to access the contact's quote page on HealthSherpa"},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","code"],"properties":{"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code","enum":["invalid_api_key","resource_not_found","validation_error","agent_not_found","unprocessable_entity"]},"details":{"type":"array","description":"Detailed validation errors","items":{"type":"object","properties":{"field":{"type":"string","description":"The field that failed validation"},"message":{"type":"string","description":"The validation error message"}}}}}}}}},"responses":{"ValidationError":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized - Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AgentNotFound":{"description":"Agent not found or not associated with the agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"The request was well-formed but could not be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/contacts":{"post":{"summary":"Create a new contact","description":"Creates a new contact in the HealthSherpa system. The contact will be associated with the agent specified in the request. All contacts must have an external ID, first name, and last name.\n","operationId":"createContact","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_email","contact"],"properties":{"agent_email":{"type":"string","format":"email","description":"Email of the agent who will own this contact"},"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"responses":{"200":{"description":"Contact created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"redirect_url":{"$ref":"#/components/schemas/RedirectUrl"}}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AgentNotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}} ``` # Update Contact ## Update an existing contact > Updates an existing contact in the HealthSherpa system. The contact must be owned by the agent specified in the request. Only fields that are included in the request will be updated.
```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API","version":"1.0.0"},"servers":[{"url":"https://api.medicare.healthsherpa.com/v1","description":"Production environment"},{"url":"https://api.medicare-staging.healthsherpa.com/v1","description":"Staging environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication"}},"schemas":{"Contact":{"type":"object","required":["external_id","first_name","last_name"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":100,"description":"Your system's unique identifier for this contact. Can be set on create or updated if the current value is null."},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":100},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":100},"address_1":{"type":"string","description":"Primary address line","minLength":1,"maxLength":100},"address_2":{"type":"string","nullable":true,"description":"Secondary address line","minLength":1,"maxLength":100},"birth_date":{"type":"string","description":"Contact's date of birth","enum":["01-15-1955","01/15/1955","1955-01-15","1955/01/15"]},"city":{"type":"string","description":"City name","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","description":"Contact's email address"},"extra_help":{"type":["boolean","string"],"nullable":true,"description":"Whether the contact receives Extra Help","enum":[true,false,null]},"medicaid_eligible":{"type":["boolean","string"],"nullable":true,"description":"Whether the contact is eligible for Medicaid","enum":[true,false,null]},"medicaid_number":{"type":"string","description":"Contact's Medicaid number"},"medicare_number":{"type":"string","description":"Contact's Medicare number","minLength":1,"maxLength":1000},"medicare_part_a_effective_date":{"type":"string","description":"Medicare Part A effective date","enum":["01-01-2024","01/01/2024","2024-01-01","2024/01/01"]},"medicare_part_b_effective_date":{"type":"string","description":"Medicare Part B effective date","enum":["01-01-2024","01/01/2024","2024-01-01","2024/01/01"]},"notes":{"type":"array","description":"Array of notes about the contact. Each item in the notes array will be added as a note on the contact record. When updating, it will append to the existing notes and not overwrite any of the existing notes.","items":{"type":"string","minLength":1,"maxLength":1000},"minItems":1,"maxItems":50},"phone":{"type":"string","description":"Contact's phone number"},"sex":{"type":"string","description":"Contact's sex","enum":["male","female","M","F","m","f"]},"state":{"type":"string","description":"Two-letter state code"},"type":{"type":"string","description":"Contact type","enum":["client","lead"]},"zip":{"type":"string","description":"ZIP code"},"authorized_representative_name":{"type":"string","description":"Name of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_relationship":{"type":"string","description":"Relationship of the authorized representative to the contact","enum":["natural_child","spouse","mother","father","power_of_attorney","other"]},"authorized_representative_phone_number":{"type":"string","description":"Phone number of the authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email address of the authorized representative"},"authorized_representative_address":{"type":"string","description":"Street address of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_city":{"type":"string","description":"City of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_state":{"type":"string","description":"Two-letter state code of the authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of the authorized representative"},"mailing_address_street":{"type":"string","description":"Street address for mailing","minLength":1,"maxLength":100},"mailing_address_unit_number":{"type":"string","nullable":true,"description":"Unit number for mailing address","minLength":1,"maxLength":100},"mailing_address_city":{"type":"string","description":"City for mailing address","minLength":1,"maxLength":100},"mailing_address_state":{"type":"string","description":"Two-letter state code for mailing address"},"mailing_address_zip_code":{"type":"string","description":"ZIP code for mailing address"}}},"RedirectUrl":{"type":"string","description":"URL to access the contact's quote page on HealthSherpa"},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","code"],"properties":{"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code","enum":["invalid_api_key","resource_not_found","validation_error","agent_not_found","unprocessable_entity"]},"details":{"type":"array","description":"Detailed validation errors","items":{"type":"object","properties":{"field":{"type":"string","description":"The field that failed validation"},"message":{"type":"string","description":"The validation error message"}}}}}}}}},"responses":{"ValidationError":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized - Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AgentNotFound":{"description":"Agent not found or not associated with the agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"The request was well-formed but could not be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/contacts/{contact_id}":{"patch":{"summary":"Update an existing contact","description":"Updates an existing contact in the HealthSherpa system. The contact must be owned by the agent specified in the request. Only fields that are included in the request will be updated.\n","operationId":"updateContact","tags":["Contacts"],"parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"},"description":"The HealthSherpa system ID of the contact to update"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_email","contact"],"properties":{"agent_email":{"type":"string","format":"email","description":"Email of the agent who owns this contact"},"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"responses":{"200":{"description":"Contact updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"redirect_url":{"$ref":"#/components/schemas/RedirectUrl"}}}}}}}},"204":{"description":"No changes were made to the contact","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/responses/NotFound"},{"$ref":"#/components/responses/AgentNotFound"}]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}} ``` # Search Contact ## Search for a contact > Searches for a contact in the HealthSherpa system created by the agent matching the provided agent\_email. You can search by medicare number alone, OR by using a combination of name (first name or last name) with at least one of: date of birth, email, or phone.
```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API","version":"1.0.0"},"servers":[{"url":"https://api.medicare.healthsherpa.com/v1","description":"Production environment"},{"url":"https://api.medicare-staging.healthsherpa.com/v1","description":"Staging environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication"}},"schemas":{"Contact":{"type":"object","required":["external_id","first_name","last_name"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":100,"description":"Your system's unique identifier for this contact. Can be set on create or updated if the current value is null."},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":100},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":100},"address_1":{"type":"string","description":"Primary address line","minLength":1,"maxLength":100},"address_2":{"type":"string","nullable":true,"description":"Secondary address line","minLength":1,"maxLength":100},"birth_date":{"type":"string","description":"Contact's date of birth","enum":["01-15-1955","01/15/1955","1955-01-15","1955/01/15"]},"city":{"type":"string","description":"City name","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","description":"Contact's email address"},"extra_help":{"type":["boolean","string"],"nullable":true,"description":"Whether the contact receives Extra Help","enum":[true,false,null]},"medicaid_eligible":{"type":["boolean","string"],"nullable":true,"description":"Whether the contact is eligible for Medicaid","enum":[true,false,null]},"medicaid_number":{"type":"string","description":"Contact's Medicaid number"},"medicare_number":{"type":"string","description":"Contact's Medicare number","minLength":1,"maxLength":1000},"medicare_part_a_effective_date":{"type":"string","description":"Medicare Part A effective date","enum":["01-01-2024","01/01/2024","2024-01-01","2024/01/01"]},"medicare_part_b_effective_date":{"type":"string","description":"Medicare Part B effective date","enum":["01-01-2024","01/01/2024","2024-01-01","2024/01/01"]},"notes":{"type":"array","description":"Array of notes about the contact. Each item in the notes array will be added as a note on the contact record. When updating, it will append to the existing notes and not overwrite any of the existing notes.","items":{"type":"string","minLength":1,"maxLength":1000},"minItems":1,"maxItems":50},"phone":{"type":"string","description":"Contact's phone number"},"sex":{"type":"string","description":"Contact's sex","enum":["male","female","M","F","m","f"]},"state":{"type":"string","description":"Two-letter state code"},"type":{"type":"string","description":"Contact type","enum":["client","lead"]},"zip":{"type":"string","description":"ZIP code"},"authorized_representative_name":{"type":"string","description":"Name of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_relationship":{"type":"string","description":"Relationship of the authorized representative to the contact","enum":["natural_child","spouse","mother","father","power_of_attorney","other"]},"authorized_representative_phone_number":{"type":"string","description":"Phone number of the authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email address of the authorized representative"},"authorized_representative_address":{"type":"string","description":"Street address of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_city":{"type":"string","description":"City of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_state":{"type":"string","description":"Two-letter state code of the authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of the authorized representative"},"mailing_address_street":{"type":"string","description":"Street address for mailing","minLength":1,"maxLength":100},"mailing_address_unit_number":{"type":"string","nullable":true,"description":"Unit number for mailing address","minLength":1,"maxLength":100},"mailing_address_city":{"type":"string","description":"City for mailing address","minLength":1,"maxLength":100},"mailing_address_state":{"type":"string","description":"Two-letter state code for mailing address"},"mailing_address_zip_code":{"type":"string","description":"ZIP code for mailing address"}}},"RedirectUrl":{"type":"string","description":"URL to access the contact's quote page on HealthSherpa"},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","code"],"properties":{"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code","enum":["invalid_api_key","resource_not_found","validation_error","agent_not_found","unprocessable_entity"]},"details":{"type":"array","description":"Detailed validation errors","items":{"type":"object","properties":{"field":{"type":"string","description":"The field that failed validation"},"message":{"type":"string","description":"The validation error message"}}}}}}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AgentNotFound":{"description":"Agent not found or not associated with the agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/contacts/search":{"post":{"summary":"Search for a contact","description":"Searches for a contact in the HealthSherpa system created by the agent matching the provided agent_email. You can search by medicare number alone, OR by using a combination of name (first name or last name) with at least one of: date of birth, email, or phone.\n","operationId":"searchContact","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_email","params"],"properties":{"agent_email":{"type":"string","format":"email","description":"Email of the agent performing the search"},"params":{"type":"object","description":"Search parameters. Provide either medicare_number alone, OR a combination of (first_name or last_name) with at least one of (date_of_birth, email, or phone).\n","properties":{"medicare_number":{"type":"string","description":"Contact's Medicare number"},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":500},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":500},"date_of_birth":{"type":"string","description":"Contact's date of birth"},"email":{"type":"string","format":"email","description":"Contact's email address"},"phone":{"type":"string","description":"Contact's phone number"}}}}}}}},"responses":{"200":{"description":"Contact found successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"redirect_url":{"$ref":"#/components/schemas/RedirectUrl"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/AgentNotFound"},"422":{"description":"Invalid search parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` # Schema # Contact ## The Contact object ```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API","version":"1.0.0"},"components":{"schemas":{"Contact":{"type":"object","required":["external_id","first_name","last_name"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":100,"description":"Your system's unique identifier for this contact. Can be set on create or updated if the current value is null."},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":100},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":100},"address_1":{"type":"string","description":"Primary address line","minLength":1,"maxLength":100},"address_2":{"type":"string","nullable":true,"description":"Secondary address line","minLength":1,"maxLength":100},"birth_date":{"type":"string","description":"Contact's date of birth","enum":["01-15-1955","01/15/1955","1955-01-15","1955/01/15"]},"city":{"type":"string","description":"City name","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","description":"Contact's email address"},"extra_help":{"type":["boolean","string"],"nullable":true,"description":"Whether the contact receives Extra Help","enum":[true,false,null]},"medicaid_eligible":{"type":["boolean","string"],"nullable":true,"description":"Whether the contact is eligible for Medicaid","enum":[true,false,null]},"medicaid_number":{"type":"string","description":"Contact's Medicaid number"},"medicare_number":{"type":"string","description":"Contact's Medicare number","minLength":1,"maxLength":1000},"medicare_part_a_effective_date":{"type":"string","description":"Medicare Part A effective date","enum":["01-01-2024","01/01/2024","2024-01-01","2024/01/01"]},"medicare_part_b_effective_date":{"type":"string","description":"Medicare Part B effective date","enum":["01-01-2024","01/01/2024","2024-01-01","2024/01/01"]},"notes":{"type":"array","description":"Array of notes about the contact. Each item in the notes array will be added as a note on the contact record. When updating, it will append to the existing notes and not overwrite any of the existing notes.","items":{"type":"string","minLength":1,"maxLength":1000},"minItems":1,"maxItems":50},"phone":{"type":"string","description":"Contact's phone number"},"sex":{"type":"string","description":"Contact's sex","enum":["male","female","M","F","m","f"]},"state":{"type":"string","description":"Two-letter state code"},"type":{"type":"string","description":"Contact type","enum":["client","lead"]},"zip":{"type":"string","description":"ZIP code"},"authorized_representative_name":{"type":"string","description":"Name of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_relationship":{"type":"string","description":"Relationship of the authorized representative to the contact","enum":["natural_child","spouse","mother","father","power_of_attorney","other"]},"authorized_representative_phone_number":{"type":"string","description":"Phone number of the authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email address of the authorized representative"},"authorized_representative_address":{"type":"string","description":"Street address of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_city":{"type":"string","description":"City of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_state":{"type":"string","description":"Two-letter state code of the authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of the authorized representative"},"mailing_address_street":{"type":"string","description":"Street address for mailing","minLength":1,"maxLength":100},"mailing_address_unit_number":{"type":"string","nullable":true,"description":"Unit number for mailing address","minLength":1,"maxLength":100},"mailing_address_city":{"type":"string","description":"City for mailing address","minLength":1,"maxLength":100},"mailing_address_state":{"type":"string","description":"Two-letter state code for mailing address"},"mailing_address_zip_code":{"type":"string","description":"ZIP code for mailing address"}}}}}} ``` # Version 2 (OAuth) # Getting Started To integrate with the HealthSherpa Partner API, you'll need to: 1. Create a HealthSherpa [agent](https://intercom.help/healthsherpa-medicare-help-center/en/articles/9667552-setting-up-your-account) or [agency](https://intercom.help/healthsherpa-medicare-help-center/en/articles/11077791-agency-accounts#h_2c2e2de1b2) account. 2. Email to register your application 1. Note that you'd like to set up **Version 2** of our API 2. Provide your **application name** and **redirect URL** 3. Receive your **Client ID** and **Client Secret** 3. Follow [Authentication](/api-reference/version-2-oauth/authentication) steps to begin implementing {% hint style="warning" %} **Important**: Keep your Client Secret confidential. Never share it or commit it to version control. {% endhint %} # Authentication The HealthSherpa for Medicare Partner API v2 uses **OAuth 2.0** **Authorization Code** flow for authentication. **Production**
EndpointURL
ProductionAuthorization:https://medicare.healthsherpa.com/oauth/authorize
Token: https://medicare.healthsherpa.com/oauth/token
StagingAuthorization:https://medicare-staging.healthsherpa.com/oauth/authorize
Token: https://medicare-staging.healthsherpa.com/oauth/token
### 1. Redirect User to Authorization Endpoint Direct the user to: ``` https://medicare.healthsherpa.com/oauth/authorize? client_id=YOUR_CLIENT_ID& redirect_uri=YOUR_REDIRECT_URI& response_type=code& scope=partner_api_v2 ``` **Parameters:** * `client_id` (required): Your application's Client ID * `redirect_uri` (required): Must match the URIs registered with HealthSherpa * `response_type` (required): Always `code` * `scope` (required): `partner_api_v2` - grants access to the Partner API v2 ### **2. User Authorizes Your Application** The user will see a consent screen asking to authorize your application. Upon approval, they are redirected to your `redirect_uri` with an authorization code: ``` YOUR_REDIRECT_URI?code=AUTH_CODE&state=STATE_VALUE ``` ### **3. Exchange Authorization Code for Access Token** Your server exchanges the authorization code for an access token: ``` curl -X POST https://medicare.healthsherpa.com/oauth/token -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code" -d "code=AUTH_CODE" -d "client_id=YOUR_CLIENT_ID" -d "client_secret=YOUR_CLIENT_SECRET" -d "redirect_uri=YOUR_REDIRECT_URI" ``` **Response**: ``` { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "def50200b7a9c3e4f1d2a6b8c9e0f123456789abcdef...", "scope": "partner_api_v2" } ``` **Parameters**: * `access_token`: Use this token to make API requests * `token_type`: Always Bearer * `expires_in`: Token lifetime in seconds, applies to the access token * `refresh_token`: Use this token to obtain a new access token * `scope`: Granted permissions, always "partner\_api\_v2" ### **4. Use the Access Token** Include the access token in the Authorization header of your API requests: {% code overflow="wrap" %} ```bash curl https://api.medicare.healthsherpa.com/v2/contacts \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"contact": {"external_id": "CRM123", "first_name": "John", "last_name": "Doe"}}' ``` {% endcode %} ### 5. Refresh Tokens When your access token expires, use the refresh token to get a new one : ``` curl -X POST https://medicare.healthsherpa.com/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=refresh_token" \ -d "refresh_token=YOUR_REFRESH_TOKEN" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" ``` **Response:** ``` { "access_token": "NEW_ACCESS_TOKEN", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "NEW_REFRESH_TOKEN", "scope": "partner_api_v2" } ``` Refresh tokens are rotated: when refreshing, store the newly returned `refresh_token` and discard the previous one. *** ### Troubleshooting #### Invalid or Expired Token ``` { "error": { "message": "The access token is invalid.", "code": "invalid_token" } } ``` **Response**: 401 Unauthorized **Solution**: Obtain a new access token by repeating the OAuth flow. #### Missing Authorization Header ``` { "error": { "message": "Missing authorization header", "code": "missing_authorization" } } ``` **Response**: 401 Unauthorized **Solution**: Include the Authorization: Bearer YOUR\_ACCESS\_TOKEN header in all requests. *** ### Security Best Practices * Store Client Secret securely (use environment variables or secrets management) * Use HTTPS for all requests * Validate redirect URIs * Rotate access tokens regularly * Use short-lived access tokens * Store tokens securely on your backend (never in frontend code) # Endpoints # Create Contact ## Create a new contact > Creates a new contact in the HealthSherpa system. The contact will be associated with the authenticated agent. All contacts must have an external ID, first name, and last name. This endpoint also supports creating nested resources including drugs, pharmacies, and providers.
```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API v2","version":"2.0.0"},"servers":[{"url":"https://api.medicare.healthsherpa.com/v2","description":"Production environment"},{"url":"https://api.medicare-staging.healthsherpa.com/v2","description":"Staging environment"}],"security":[{"OAuth2":["partner_api_v2"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication with partner_api_v2 scope","flows":{"authorizationCode":{"authorizationUrl":"https://api.medicare.healthsherpa.com/oauth/authorize","tokenUrl":"https://api.medicare.healthsherpa.com/oauth/token","scopes":{"partner_api_v2":"Access to Partner API v2 endpoints"}}}}},"schemas":{"ContactCreate":{"type":"object","required":["external_id","first_name","last_name"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":100,"description":"Your system's unique identifier for this contact"},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":100},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":100},"address_1":{"type":"string","description":"Primary address line","minLength":1,"maxLength":100},"address_2":{"type":"string","nullable":true,"description":"Secondary address line","minLength":1,"maxLength":100},"birth_date":{"type":"string","description":"Contact's date of birth (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"city":{"type":"string","description":"City name","minLength":1,"maxLength":100},"state":{"type":"string","description":"Two-letter state code"},"zip":{"type":"string","description":"ZIP code (5 digits)"},"phone":{"type":"string","description":"Contact's phone number (10 digits without formatting)"},"sex":{"type":"string","description":"Contact's sex","enum":["male","female","M","F","m","f"]},"email":{"type":"string","format":"email","description":"Contact's email address"},"medicare_number":{"type":"string","description":"Contact's Medicare number","minLength":1,"maxLength":100},"medicare_part_a_effective_date":{"type":"string","description":"Medicare Part A effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicare_part_b_effective_date":{"type":"string","description":"Medicare Part B effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicaid_eligible":{"type":"boolean","nullable":true,"description":"Whether the contact is eligible for Medicaid"},"medicaid_number":{"type":"string","description":"Contact's Medicaid number","minLength":1,"maxLength":100},"extra_help":{"type":"boolean","nullable":true,"description":"Whether the contact receives Extra Help"},"type":{"type":"string","description":"Contact type","enum":["client","lead"]},"notes":{"type":"array","description":"Array of notes about the contact. Notes are appended (not replaced) on update.","items":{"type":"string","minLength":1,"maxLength":1000},"minItems":1,"maxItems":50},"authorized_representative_name":{"type":"string","description":"Name of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_relationship":{"type":"string","description":"Relationship of the authorized representative to the contact","minLength":1,"maxLength":100},"authorized_representative_phone_number":{"type":"string","description":"Phone number of the authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email address of the authorized representative"},"authorized_representative_address":{"type":"string","description":"Street address of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_city":{"type":"string","description":"City of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_state":{"type":"string","description":"Two-letter state code of the authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of the authorized representative (5 digits)"},"mailing_address_street":{"type":"string","description":"Street address for mailing","minLength":1,"maxLength":100},"mailing_address_unit_number":{"type":"string","nullable":true,"description":"Unit number for mailing address","minLength":1,"maxLength":100},"mailing_address_city":{"type":"string","description":"City for mailing address","minLength":1,"maxLength":100},"mailing_address_state":{"type":"string","description":"Two-letter state code for mailing address"},"mailing_address_zip_code":{"type":"string","description":"ZIP code for mailing address (5 digits)"},"contact_drugs_attributes":{"type":"array","description":"Array of drugs associated with the contact","items":{"$ref":"#/components/schemas/ContactDrug"}},"contact_pharmacies_attributes":{"type":"array","description":"Array of pharmacies associated with the contact","items":{"$ref":"#/components/schemas/ContactPharmacy"}},"contact_providers_attributes":{"type":"array","description":"Array of providers associated with the contact","items":{"$ref":"#/components/schemas/ContactProvider"}}}},"ContactDrug":{"type":"object","required":["frequency","dosage_id","dosage_id_source","user_quantity","ndc","id","id_source","dosage_name","name","drug_type_id"],"properties":{"name":{"type":"string","description":"Drug name"},"drug_type_id":{"type":"integer","description":"Drug type identifier (1=Brand, 2=Generic, 3=OTC Brand, 4=Branded Generic, 5=OTC Branded Generic, 6=OTC Generic, 9=OTC DME Brand)","enum":[1,2,3,4,5,6,9]},"dosage_name":{"type":"string","description":"Full dosage name including strength"},"ndc":{"type":"string","description":"National Drug Code"},"frequency":{"type":"integer","description":"Frequency in days (e.g., 30 for monthly)","enum":[30,60,90,180,360]},"user_quantity":{"type":"integer","description":"Quantity the user takes"},"id":{"type":"string","description":"Drug identifier from source system"},"id_source":{"type":"string","description":"Source system for the drug ID (must be \"connecture\")","enum":["connecture"]},"dosage_id":{"type":"string","description":"Dosage identifier from source system"},"dosage_id_source":{"type":"string","description":"Source system for the dosage ID (must be \"connecture\")","enum":["connecture"]},"package_id":{"type":"string","description":"Package identifier from source system"},"package_id_source":{"type":"string","description":"Source system for the package ID (must be \"connecture\")","enum":["connecture"]},"package_description":{"type":"string","description":"Description of the package type"},"package_size":{"type":"integer","description":"Size of the package"},"package_quantity":{"type":"number","format":"float","description":"Quantity of packages"},"metric_quantity":{"type":"integer","description":"Metric quantity value"}}},"ContactPharmacy":{"type":"object","required":["id","id_source","name","mode","npi","address_street","address_city","address_state","address_zip_code"],"properties":{"id":{"type":"string","description":"Pharmacy identifier from source system"},"id_source":{"type":"string","description":"Source system for the pharmacy ID (must be \"connecture\")","enum":["connecture"]},"name":{"type":"string","description":"Pharmacy name"},"mode":{"type":"string","description":"Pharmacy mode","enum":["retail","digital"]},"npi":{"type":"string","description":"National Provider Identifier"},"primary":{"type":"boolean","description":"Whether this is the primary pharmacy"},"phone_number":{"type":"string","description":"Pharmacy phone number"},"address_street":{"type":"string","description":"Pharmacy street address"},"address_unit_number":{"type":"string","description":"Pharmacy unit number"},"address_city":{"type":"string","description":"Pharmacy city"},"address_state":{"type":"string","description":"Pharmacy state (two-letter code)"},"address_zip_code":{"type":"string","description":"Pharmacy ZIP code"}}},"ContactProvider":{"type":"object","required":["id","id_source","provider_type","presentation_name","contact_provider_addresses_attributes"],"properties":{"id":{"type":"string","description":"Provider identifier from source system"},"id_source":{"type":"string","description":"Source system for the provider ID (must be \"connecture\")","enum":["connecture"]},"provider_type":{"type":"string","description":"Type of provider","enum":["individual","organization"]},"presentation_name":{"type":"string","description":"Display name for the provider"},"primary":{"type":"boolean","description":"Whether this is the primary provider"},"first_name":{"type":"string","description":"Provider's first name (for individual providers)"},"last_name":{"type":"string","description":"Provider's last name (for individual providers)"},"organization_name":{"type":"string","description":"Organization name (for organization providers)"},"phone_number":{"type":"string","description":"Provider's phone number"},"npi":{"type":"string","description":"National Provider Identifier"},"specialties":{"type":"array","description":"List of provider specialties","items":{"type":"string"}},"contact_provider_addresses_attributes":{"type":"array","description":"Array of addresses for this provider. At least one valid address is required; providers with no valid addresses are rejected and reported in the partial_success errors array.\n","minItems":1,"items":{"$ref":"#/components/schemas/ContactProviderAddress"}}}},"ContactProviderAddress":{"type":"object","required":["id","id_source","city","state","zip_code"],"properties":{"id":{"type":"string","description":"Address identifier from source system"},"id_source":{"type":"string","description":"Source system for the address ID (must be \"connecture\")","enum":["connecture"]},"street":{"type":"string","description":"Street address"},"unit_number":{"type":"string","description":"Unit number"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State (two-letter code)"},"zip_code":{"type":"string","description":"ZIP code"},"phone_numbers":{"type":"array","description":"List of phone numbers for this address","items":{"type":"string"}},"selected":{"type":"boolean","description":"Whether this address is selected/preferred"}}},"Contact":{"type":"object","properties":{"id":{"type":"string","description":"HealthSherpa system ID for the contact"},"slug":{"type":"string","description":"URL-friendly identifier for the contact"},"external_id":{"type":"string","minLength":1,"maxLength":100,"description":"Your system's unique identifier for this contact"},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":100},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":100},"address_1":{"type":"string","description":"Primary address line","minLength":1,"maxLength":100},"address_2":{"type":"string","nullable":true,"description":"Secondary address line","minLength":1,"maxLength":100},"birth_date":{"type":"string","description":"Contact's date of birth (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"city":{"type":"string","description":"City name","minLength":1,"maxLength":100},"state":{"type":"string","description":"Two-letter state code"},"zip":{"type":"string","description":"ZIP code (5 digits)"},"phone":{"type":"string","description":"Contact's phone number (10 digits without formatting)"},"sex":{"type":"string","description":"Contact's sex","enum":["male","female","M","F","m","f"]},"email":{"type":"string","format":"email","description":"Contact's email address"},"medicare_number":{"type":"string","description":"Contact's Medicare number","minLength":1,"maxLength":100},"medicare_part_a_effective_date":{"type":"string","description":"Medicare Part A effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicare_part_b_effective_date":{"type":"string","description":"Medicare Part B effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicaid_eligible":{"type":"boolean","nullable":true,"description":"Whether the contact is eligible for Medicaid"},"medicaid_number":{"type":"string","description":"Contact's Medicaid number","minLength":1,"maxLength":100},"extra_help":{"type":"boolean","nullable":true,"description":"Whether the contact receives Extra Help"},"type":{"type":"string","description":"Contact type","enum":["client","lead"]},"authorized_representative_name":{"type":"string","description":"Name of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_relationship":{"type":"string","description":"Relationship of the authorized representative to the contact","minLength":1,"maxLength":100},"authorized_representative_phone_number":{"type":"string","description":"Phone number of the authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email address of the authorized representative"},"authorized_representative_address":{"type":"string","description":"Street address of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_city":{"type":"string","description":"City of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_state":{"type":"string","description":"Two-letter state code of the authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of the authorized representative (5 digits)"},"mailing_address_street":{"type":"string","description":"Street address for mailing","minLength":1,"maxLength":100},"mailing_address_unit_number":{"type":"string","nullable":true,"description":"Unit number for mailing address","minLength":1,"maxLength":100},"mailing_address_city":{"type":"string","description":"City for mailing address","minLength":1,"maxLength":100},"mailing_address_state":{"type":"string","description":"Two-letter state code for mailing address"},"mailing_address_zip_code":{"type":"string","description":"ZIP code for mailing address (5 digits)"},"contact_drugs_attributes":{"type":"array","description":"Array of drugs associated with the contact","items":{"$ref":"#/components/schemas/ContactDrug"}},"contact_pharmacies_attributes":{"type":"array","description":"Array of pharmacies associated with the contact","items":{"$ref":"#/components/schemas/ContactPharmacy"}},"contact_providers_attributes":{"type":"array","description":"Array of providers associated with the contact","items":{"$ref":"#/components/schemas/ContactProvider"}}}},"RedirectUrl":{"type":"string","description":"URL to access the contact's quote page on HealthSherpa"},"Error":{"type":"object","description":"Standard error envelope used for application-level errors (validation, not found, etc.). OAuth 2.0 errors (401 Unauthorized, 403 Forbidden) use a different format — see the Unauthorized and Forbidden response components.\n","required":["error"],"properties":{"error":{"type":"object","required":["message","code"],"properties":{"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code","enum":["resource_not_found","validation_failed","agent_not_found","unprocessable_entity"]},"details":{"type":"array","description":"Detailed per-field errors. For 400 validation errors, each entry is a single-key map of `field_name -> message`. For 422 errors raised from model validations, each entry is a `{ field, message }` object.\n","items":{"type":"object","additionalProperties":{"type":"string"}}}}}}}},"responses":{"ValidationError":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized - Invalid, missing, or expired OAuth access token. 401 responses for token problems are produced by the OAuth layer and follow the OAuth 2.0 Bearer Token error format (`{\"error\": \"...\", \"error_description\": \"...\"}`) rather than the standard `{error: {code, message}}` envelope used by the rest of the API.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"OAuth 2.0 error code (e.g. \"invalid_token\")"},"error_description":{"type":"string","description":"Human-readable explanation of the error"}}}}}},"Forbidden":{"description":"The access token does not have the required `partner_api_v2` scope. Like other OAuth errors, this response uses the OAuth 2.0 Bearer Token error format.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"},"scope":{"type":"string"}}}}}},"AgentNotFound":{"description":"Agent not found for the authenticated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"The request was well-formed but could not be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/contacts":{"post":{"summary":"Create a new contact","description":"Creates a new contact in the HealthSherpa system. The contact will be associated with the authenticated agent. All contacts must have an external ID, first name, and last name. This endpoint also supports creating nested resources including drugs, pharmacies, and providers.\n","operationId":"createContact","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact"],"properties":{"contact":{"$ref":"#/components/schemas/ContactCreate"}}}}}},"responses":{"201":{"description":"Contact created successfully. May return partial_success status if any of the sub-records (drugs, pharmacies, providers) failed to save.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","description":"Indicates whether the operation was fully successful or partially successful. \"success\" means all data (including sub-records) was saved. \"partial_success\" means the contact was saved but one or more sub-records failed. In this case, a note describing the failures is also added to the contact record and is visible in the HealthSherpa Medicare UI.\n","enum":["success","partial_success"]},"errors":{"type":"array","description":"Array of errors for sub-records that failed to save. Empty when status is \"success\".\n","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of sub-record that failed","enum":["drug","pharmacy","provider","provider_address"]},"source":{"type":"string","nullable":true,"description":"The id_source value provided. Null for provider-level errors."},"identifier":{"type":"string","description":"The ID of the record that failed"},"message":{"type":"string","description":"Human-readable error message"}}}},"contact":{"$ref":"#/components/schemas/Contact"},"redirect_url":{"$ref":"#/components/schemas/RedirectUrl"}}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/AgentNotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}} ``` # Update Contact ## Update an existing contact > Updates an existing contact in the HealthSherpa system. The contact must be owned by the authenticated agent. Only fields that are included in the request will be updated. When updating nested resources (drugs, pharmacies, providers), the existing nested records are replaced with the new ones. \`external\_id\` cannot be changed once it has a value; submitting a different \`external\_id\` returns a 422.
```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API v2","version":"2.0.0"},"servers":[{"url":"https://api.medicare.healthsherpa.com/v2","description":"Production environment"},{"url":"https://api.medicare-staging.healthsherpa.com/v2","description":"Staging environment"}],"security":[{"OAuth2":["partner_api_v2"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication with partner_api_v2 scope","flows":{"authorizationCode":{"authorizationUrl":"https://api.medicare.healthsherpa.com/oauth/authorize","tokenUrl":"https://api.medicare.healthsherpa.com/oauth/token","scopes":{"partner_api_v2":"Access to Partner API v2 endpoints"}}}}},"schemas":{"ContactUpdate":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":100,"description":"Your system's unique identifier for this contact. Cannot be changed once it already has a value; submitting a different `external_id` returns a 422 with message \"external_id cannot be updated because it already has a value\".\n"},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":100},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":100},"address_1":{"type":"string","description":"Primary address line","minLength":1,"maxLength":100},"address_2":{"type":"string","nullable":true,"description":"Secondary address line","minLength":1,"maxLength":100},"birth_date":{"type":"string","description":"Contact's date of birth (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"city":{"type":"string","description":"City name","minLength":1,"maxLength":100},"state":{"type":"string","description":"Two-letter state code"},"zip":{"type":"string","description":"ZIP code (5 digits)"},"phone":{"type":"string","description":"Contact's phone number (10 digits without formatting)"},"sex":{"type":"string","description":"Contact's sex","enum":["male","female","M","F","m","f"]},"email":{"type":"string","format":"email","description":"Contact's email address"},"medicare_number":{"type":"string","description":"Contact's Medicare number","minLength":1,"maxLength":100},"medicare_part_a_effective_date":{"type":"string","description":"Medicare Part A effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicare_part_b_effective_date":{"type":"string","description":"Medicare Part B effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicaid_eligible":{"type":"boolean","nullable":true,"description":"Whether the contact is eligible for Medicaid"},"medicaid_number":{"type":"string","description":"Contact's Medicaid number","minLength":1,"maxLength":100},"extra_help":{"type":"boolean","nullable":true,"description":"Whether the contact receives Extra Help"},"type":{"type":"string","description":"Contact type","enum":["client","lead"]},"notes":{"type":"array","description":"Array of notes about the contact. Notes are appended (not replaced) on update.","items":{"type":"string","minLength":1,"maxLength":1000},"minItems":1,"maxItems":50},"authorized_representative_name":{"type":"string","description":"Name of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_relationship":{"type":"string","description":"Relationship of the authorized representative to the contact","minLength":1,"maxLength":100},"authorized_representative_phone_number":{"type":"string","description":"Phone number of the authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email address of the authorized representative"},"authorized_representative_address":{"type":"string","description":"Street address of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_city":{"type":"string","description":"City of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_state":{"type":"string","description":"Two-letter state code of the authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of the authorized representative (5 digits)"},"mailing_address_street":{"type":"string","description":"Street address for mailing","minLength":1,"maxLength":100},"mailing_address_unit_number":{"type":"string","nullable":true,"description":"Unit number for mailing address","minLength":1,"maxLength":100},"mailing_address_city":{"type":"string","description":"City for mailing address","minLength":1,"maxLength":100},"mailing_address_state":{"type":"string","description":"Two-letter state code for mailing address"},"mailing_address_zip_code":{"type":"string","description":"ZIP code for mailing address (5 digits)"},"contact_drugs_attributes":{"type":"array","description":"Array of drugs associated with the contact","items":{"$ref":"#/components/schemas/ContactDrug"}},"contact_pharmacies_attributes":{"type":"array","description":"Array of pharmacies associated with the contact","items":{"$ref":"#/components/schemas/ContactPharmacy"}},"contact_providers_attributes":{"type":"array","description":"Array of providers associated with the contact","items":{"$ref":"#/components/schemas/ContactProvider"}}}},"ContactDrug":{"type":"object","required":["frequency","dosage_id","dosage_id_source","user_quantity","ndc","id","id_source","dosage_name","name","drug_type_id"],"properties":{"name":{"type":"string","description":"Drug name"},"drug_type_id":{"type":"integer","description":"Drug type identifier (1=Brand, 2=Generic, 3=OTC Brand, 4=Branded Generic, 5=OTC Branded Generic, 6=OTC Generic, 9=OTC DME Brand)","enum":[1,2,3,4,5,6,9]},"dosage_name":{"type":"string","description":"Full dosage name including strength"},"ndc":{"type":"string","description":"National Drug Code"},"frequency":{"type":"integer","description":"Frequency in days (e.g., 30 for monthly)","enum":[30,60,90,180,360]},"user_quantity":{"type":"integer","description":"Quantity the user takes"},"id":{"type":"string","description":"Drug identifier from source system"},"id_source":{"type":"string","description":"Source system for the drug ID (must be \"connecture\")","enum":["connecture"]},"dosage_id":{"type":"string","description":"Dosage identifier from source system"},"dosage_id_source":{"type":"string","description":"Source system for the dosage ID (must be \"connecture\")","enum":["connecture"]},"package_id":{"type":"string","description":"Package identifier from source system"},"package_id_source":{"type":"string","description":"Source system for the package ID (must be \"connecture\")","enum":["connecture"]},"package_description":{"type":"string","description":"Description of the package type"},"package_size":{"type":"integer","description":"Size of the package"},"package_quantity":{"type":"number","format":"float","description":"Quantity of packages"},"metric_quantity":{"type":"integer","description":"Metric quantity value"}}},"ContactPharmacy":{"type":"object","required":["id","id_source","name","mode","npi","address_street","address_city","address_state","address_zip_code"],"properties":{"id":{"type":"string","description":"Pharmacy identifier from source system"},"id_source":{"type":"string","description":"Source system for the pharmacy ID (must be \"connecture\")","enum":["connecture"]},"name":{"type":"string","description":"Pharmacy name"},"mode":{"type":"string","description":"Pharmacy mode","enum":["retail","digital"]},"npi":{"type":"string","description":"National Provider Identifier"},"primary":{"type":"boolean","description":"Whether this is the primary pharmacy"},"phone_number":{"type":"string","description":"Pharmacy phone number"},"address_street":{"type":"string","description":"Pharmacy street address"},"address_unit_number":{"type":"string","description":"Pharmacy unit number"},"address_city":{"type":"string","description":"Pharmacy city"},"address_state":{"type":"string","description":"Pharmacy state (two-letter code)"},"address_zip_code":{"type":"string","description":"Pharmacy ZIP code"}}},"ContactProvider":{"type":"object","required":["id","id_source","provider_type","presentation_name","contact_provider_addresses_attributes"],"properties":{"id":{"type":"string","description":"Provider identifier from source system"},"id_source":{"type":"string","description":"Source system for the provider ID (must be \"connecture\")","enum":["connecture"]},"provider_type":{"type":"string","description":"Type of provider","enum":["individual","organization"]},"presentation_name":{"type":"string","description":"Display name for the provider"},"primary":{"type":"boolean","description":"Whether this is the primary provider"},"first_name":{"type":"string","description":"Provider's first name (for individual providers)"},"last_name":{"type":"string","description":"Provider's last name (for individual providers)"},"organization_name":{"type":"string","description":"Organization name (for organization providers)"},"phone_number":{"type":"string","description":"Provider's phone number"},"npi":{"type":"string","description":"National Provider Identifier"},"specialties":{"type":"array","description":"List of provider specialties","items":{"type":"string"}},"contact_provider_addresses_attributes":{"type":"array","description":"Array of addresses for this provider. At least one valid address is required; providers with no valid addresses are rejected and reported in the partial_success errors array.\n","minItems":1,"items":{"$ref":"#/components/schemas/ContactProviderAddress"}}}},"ContactProviderAddress":{"type":"object","required":["id","id_source","city","state","zip_code"],"properties":{"id":{"type":"string","description":"Address identifier from source system"},"id_source":{"type":"string","description":"Source system for the address ID (must be \"connecture\")","enum":["connecture"]},"street":{"type":"string","description":"Street address"},"unit_number":{"type":"string","description":"Unit number"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State (two-letter code)"},"zip_code":{"type":"string","description":"ZIP code"},"phone_numbers":{"type":"array","description":"List of phone numbers for this address","items":{"type":"string"}},"selected":{"type":"boolean","description":"Whether this address is selected/preferred"}}},"Contact":{"type":"object","properties":{"id":{"type":"string","description":"HealthSherpa system ID for the contact"},"slug":{"type":"string","description":"URL-friendly identifier for the contact"},"external_id":{"type":"string","minLength":1,"maxLength":100,"description":"Your system's unique identifier for this contact"},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":100},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":100},"address_1":{"type":"string","description":"Primary address line","minLength":1,"maxLength":100},"address_2":{"type":"string","nullable":true,"description":"Secondary address line","minLength":1,"maxLength":100},"birth_date":{"type":"string","description":"Contact's date of birth (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"city":{"type":"string","description":"City name","minLength":1,"maxLength":100},"state":{"type":"string","description":"Two-letter state code"},"zip":{"type":"string","description":"ZIP code (5 digits)"},"phone":{"type":"string","description":"Contact's phone number (10 digits without formatting)"},"sex":{"type":"string","description":"Contact's sex","enum":["male","female","M","F","m","f"]},"email":{"type":"string","format":"email","description":"Contact's email address"},"medicare_number":{"type":"string","description":"Contact's Medicare number","minLength":1,"maxLength":100},"medicare_part_a_effective_date":{"type":"string","description":"Medicare Part A effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicare_part_b_effective_date":{"type":"string","description":"Medicare Part B effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicaid_eligible":{"type":"boolean","nullable":true,"description":"Whether the contact is eligible for Medicaid"},"medicaid_number":{"type":"string","description":"Contact's Medicaid number","minLength":1,"maxLength":100},"extra_help":{"type":"boolean","nullable":true,"description":"Whether the contact receives Extra Help"},"type":{"type":"string","description":"Contact type","enum":["client","lead"]},"authorized_representative_name":{"type":"string","description":"Name of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_relationship":{"type":"string","description":"Relationship of the authorized representative to the contact","minLength":1,"maxLength":100},"authorized_representative_phone_number":{"type":"string","description":"Phone number of the authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email address of the authorized representative"},"authorized_representative_address":{"type":"string","description":"Street address of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_city":{"type":"string","description":"City of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_state":{"type":"string","description":"Two-letter state code of the authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of the authorized representative (5 digits)"},"mailing_address_street":{"type":"string","description":"Street address for mailing","minLength":1,"maxLength":100},"mailing_address_unit_number":{"type":"string","nullable":true,"description":"Unit number for mailing address","minLength":1,"maxLength":100},"mailing_address_city":{"type":"string","description":"City for mailing address","minLength":1,"maxLength":100},"mailing_address_state":{"type":"string","description":"Two-letter state code for mailing address"},"mailing_address_zip_code":{"type":"string","description":"ZIP code for mailing address (5 digits)"},"contact_drugs_attributes":{"type":"array","description":"Array of drugs associated with the contact","items":{"$ref":"#/components/schemas/ContactDrug"}},"contact_pharmacies_attributes":{"type":"array","description":"Array of pharmacies associated with the contact","items":{"$ref":"#/components/schemas/ContactPharmacy"}},"contact_providers_attributes":{"type":"array","description":"Array of providers associated with the contact","items":{"$ref":"#/components/schemas/ContactProvider"}}}},"RedirectUrl":{"type":"string","description":"URL to access the contact's quote page on HealthSherpa"},"Error":{"type":"object","description":"Standard error envelope used for application-level errors (validation, not found, etc.). OAuth 2.0 errors (401 Unauthorized, 403 Forbidden) use a different format — see the Unauthorized and Forbidden response components.\n","required":["error"],"properties":{"error":{"type":"object","required":["message","code"],"properties":{"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code","enum":["resource_not_found","validation_failed","agent_not_found","unprocessable_entity"]},"details":{"type":"array","description":"Detailed per-field errors. For 400 validation errors, each entry is a single-key map of `field_name -> message`. For 422 errors raised from model validations, each entry is a `{ field, message }` object.\n","items":{"type":"object","additionalProperties":{"type":"string"}}}}}}}},"responses":{"ValidationError":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized - Invalid, missing, or expired OAuth access token. 401 responses for token problems are produced by the OAuth layer and follow the OAuth 2.0 Bearer Token error format (`{\"error\": \"...\", \"error_description\": \"...\"}`) rather than the standard `{error: {code, message}}` envelope used by the rest of the API.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"OAuth 2.0 error code (e.g. \"invalid_token\")"},"error_description":{"type":"string","description":"Human-readable explanation of the error"}}}}}},"Forbidden":{"description":"The access token does not have the required `partner_api_v2` scope. Like other OAuth errors, this response uses the OAuth 2.0 Bearer Token error format.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"},"scope":{"type":"string"}}}}}},"AgentNotFound":{"description":"Agent not found for the authenticated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"The request was well-formed but could not be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/contacts/{contact_id}":{"patch":{"summary":"Update an existing contact","description":"Updates an existing contact in the HealthSherpa system. The contact must be owned by the authenticated agent. Only fields that are included in the request will be updated. When updating nested resources (drugs, pharmacies, providers), the existing nested records are replaced with the new ones. `external_id` cannot be changed once it has a value; submitting a different `external_id` returns a 422.\n","operationId":"updateContact","tags":["Contacts"],"parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"},"description":"The HealthSherpa system ID of the contact to update"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact"],"properties":{"contact":{"$ref":"#/components/schemas/ContactUpdate"}}}}}},"responses":{"200":{"description":"Contact updated successfully. May return partial_success status if any of the sub-records (drugs, pharmacies, providers) failed to save.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","description":"Indicates whether the operation was fully successful or partially successful. \"success\" means all data (including sub-records) was saved. \"partial_success\" means the contact was saved but one or more sub-records failed. In this case, a note describing the failures is also added to the contact record and is visible in the HealthSherpa Medicare UI.\n","enum":["success","partial_success"]},"errors":{"type":"array","description":"Array of errors for sub-records that failed to save. Empty when status is \"success\".\n","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of sub-record that failed","enum":["drug","pharmacy","provider","provider_address"]},"source":{"type":"string","nullable":true,"description":"The id_source value provided. Null for provider-level errors."},"identifier":{"type":"string","description":"The ID of the record that failed"},"message":{"type":"string","description":"Human-readable error message"}}}},"contact":{"$ref":"#/components/schemas/Contact"},"redirect_url":{"$ref":"#/components/schemas/RedirectUrl"}}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/AgentNotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}} ``` # Search Contact ## Search for a contact > Searches for a contact in the HealthSherpa system created by the authenticated agent. You can search by medicare number alone, OR by using a combination of name (first name or last name) with at least one of: date of birth, email, or phone.
```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API v2","version":"2.0.0"},"servers":[{"url":"https://api.medicare.healthsherpa.com/v2","description":"Production environment"},{"url":"https://api.medicare-staging.healthsherpa.com/v2","description":"Staging environment"}],"security":[{"OAuth2":["partner_api_v2"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication with partner_api_v2 scope","flows":{"authorizationCode":{"authorizationUrl":"https://api.medicare.healthsherpa.com/oauth/authorize","tokenUrl":"https://api.medicare.healthsherpa.com/oauth/token","scopes":{"partner_api_v2":"Access to Partner API v2 endpoints"}}}}},"schemas":{"Contact":{"type":"object","properties":{"id":{"type":"string","description":"HealthSherpa system ID for the contact"},"slug":{"type":"string","description":"URL-friendly identifier for the contact"},"external_id":{"type":"string","minLength":1,"maxLength":100,"description":"Your system's unique identifier for this contact"},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":100},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":100},"address_1":{"type":"string","description":"Primary address line","minLength":1,"maxLength":100},"address_2":{"type":"string","nullable":true,"description":"Secondary address line","minLength":1,"maxLength":100},"birth_date":{"type":"string","description":"Contact's date of birth (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"city":{"type":"string","description":"City name","minLength":1,"maxLength":100},"state":{"type":"string","description":"Two-letter state code"},"zip":{"type":"string","description":"ZIP code (5 digits)"},"phone":{"type":"string","description":"Contact's phone number (10 digits without formatting)"},"sex":{"type":"string","description":"Contact's sex","enum":["male","female","M","F","m","f"]},"email":{"type":"string","format":"email","description":"Contact's email address"},"medicare_number":{"type":"string","description":"Contact's Medicare number","minLength":1,"maxLength":100},"medicare_part_a_effective_date":{"type":"string","description":"Medicare Part A effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicare_part_b_effective_date":{"type":"string","description":"Medicare Part B effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicaid_eligible":{"type":"boolean","nullable":true,"description":"Whether the contact is eligible for Medicaid"},"medicaid_number":{"type":"string","description":"Contact's Medicaid number","minLength":1,"maxLength":100},"extra_help":{"type":"boolean","nullable":true,"description":"Whether the contact receives Extra Help"},"type":{"type":"string","description":"Contact type","enum":["client","lead"]},"authorized_representative_name":{"type":"string","description":"Name of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_relationship":{"type":"string","description":"Relationship of the authorized representative to the contact","minLength":1,"maxLength":100},"authorized_representative_phone_number":{"type":"string","description":"Phone number of the authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email address of the authorized representative"},"authorized_representative_address":{"type":"string","description":"Street address of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_city":{"type":"string","description":"City of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_state":{"type":"string","description":"Two-letter state code of the authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of the authorized representative (5 digits)"},"mailing_address_street":{"type":"string","description":"Street address for mailing","minLength":1,"maxLength":100},"mailing_address_unit_number":{"type":"string","nullable":true,"description":"Unit number for mailing address","minLength":1,"maxLength":100},"mailing_address_city":{"type":"string","description":"City for mailing address","minLength":1,"maxLength":100},"mailing_address_state":{"type":"string","description":"Two-letter state code for mailing address"},"mailing_address_zip_code":{"type":"string","description":"ZIP code for mailing address (5 digits)"},"contact_drugs_attributes":{"type":"array","description":"Array of drugs associated with the contact","items":{"$ref":"#/components/schemas/ContactDrug"}},"contact_pharmacies_attributes":{"type":"array","description":"Array of pharmacies associated with the contact","items":{"$ref":"#/components/schemas/ContactPharmacy"}},"contact_providers_attributes":{"type":"array","description":"Array of providers associated with the contact","items":{"$ref":"#/components/schemas/ContactProvider"}}}},"ContactDrug":{"type":"object","required":["frequency","dosage_id","dosage_id_source","user_quantity","ndc","id","id_source","dosage_name","name","drug_type_id"],"properties":{"name":{"type":"string","description":"Drug name"},"drug_type_id":{"type":"integer","description":"Drug type identifier (1=Brand, 2=Generic, 3=OTC Brand, 4=Branded Generic, 5=OTC Branded Generic, 6=OTC Generic, 9=OTC DME Brand)","enum":[1,2,3,4,5,6,9]},"dosage_name":{"type":"string","description":"Full dosage name including strength"},"ndc":{"type":"string","description":"National Drug Code"},"frequency":{"type":"integer","description":"Frequency in days (e.g., 30 for monthly)","enum":[30,60,90,180,360]},"user_quantity":{"type":"integer","description":"Quantity the user takes"},"id":{"type":"string","description":"Drug identifier from source system"},"id_source":{"type":"string","description":"Source system for the drug ID (must be \"connecture\")","enum":["connecture"]},"dosage_id":{"type":"string","description":"Dosage identifier from source system"},"dosage_id_source":{"type":"string","description":"Source system for the dosage ID (must be \"connecture\")","enum":["connecture"]},"package_id":{"type":"string","description":"Package identifier from source system"},"package_id_source":{"type":"string","description":"Source system for the package ID (must be \"connecture\")","enum":["connecture"]},"package_description":{"type":"string","description":"Description of the package type"},"package_size":{"type":"integer","description":"Size of the package"},"package_quantity":{"type":"number","format":"float","description":"Quantity of packages"},"metric_quantity":{"type":"integer","description":"Metric quantity value"}}},"ContactPharmacy":{"type":"object","required":["id","id_source","name","mode","npi","address_street","address_city","address_state","address_zip_code"],"properties":{"id":{"type":"string","description":"Pharmacy identifier from source system"},"id_source":{"type":"string","description":"Source system for the pharmacy ID (must be \"connecture\")","enum":["connecture"]},"name":{"type":"string","description":"Pharmacy name"},"mode":{"type":"string","description":"Pharmacy mode","enum":["retail","digital"]},"npi":{"type":"string","description":"National Provider Identifier"},"primary":{"type":"boolean","description":"Whether this is the primary pharmacy"},"phone_number":{"type":"string","description":"Pharmacy phone number"},"address_street":{"type":"string","description":"Pharmacy street address"},"address_unit_number":{"type":"string","description":"Pharmacy unit number"},"address_city":{"type":"string","description":"Pharmacy city"},"address_state":{"type":"string","description":"Pharmacy state (two-letter code)"},"address_zip_code":{"type":"string","description":"Pharmacy ZIP code"}}},"ContactProvider":{"type":"object","required":["id","id_source","provider_type","presentation_name","contact_provider_addresses_attributes"],"properties":{"id":{"type":"string","description":"Provider identifier from source system"},"id_source":{"type":"string","description":"Source system for the provider ID (must be \"connecture\")","enum":["connecture"]},"provider_type":{"type":"string","description":"Type of provider","enum":["individual","organization"]},"presentation_name":{"type":"string","description":"Display name for the provider"},"primary":{"type":"boolean","description":"Whether this is the primary provider"},"first_name":{"type":"string","description":"Provider's first name (for individual providers)"},"last_name":{"type":"string","description":"Provider's last name (for individual providers)"},"organization_name":{"type":"string","description":"Organization name (for organization providers)"},"phone_number":{"type":"string","description":"Provider's phone number"},"npi":{"type":"string","description":"National Provider Identifier"},"specialties":{"type":"array","description":"List of provider specialties","items":{"type":"string"}},"contact_provider_addresses_attributes":{"type":"array","description":"Array of addresses for this provider. At least one valid address is required; providers with no valid addresses are rejected and reported in the partial_success errors array.\n","minItems":1,"items":{"$ref":"#/components/schemas/ContactProviderAddress"}}}},"ContactProviderAddress":{"type":"object","required":["id","id_source","city","state","zip_code"],"properties":{"id":{"type":"string","description":"Address identifier from source system"},"id_source":{"type":"string","description":"Source system for the address ID (must be \"connecture\")","enum":["connecture"]},"street":{"type":"string","description":"Street address"},"unit_number":{"type":"string","description":"Unit number"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State (two-letter code)"},"zip_code":{"type":"string","description":"ZIP code"},"phone_numbers":{"type":"array","description":"List of phone numbers for this address","items":{"type":"string"}},"selected":{"type":"boolean","description":"Whether this address is selected/preferred"}}},"Error":{"type":"object","description":"Standard error envelope used for application-level errors (validation, not found, etc.). OAuth 2.0 errors (401 Unauthorized, 403 Forbidden) use a different format — see the Unauthorized and Forbidden response components.\n","required":["error"],"properties":{"error":{"type":"object","required":["message","code"],"properties":{"message":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code","enum":["resource_not_found","validation_failed","agent_not_found","unprocessable_entity"]},"details":{"type":"array","description":"Detailed per-field errors. For 400 validation errors, each entry is a single-key map of `field_name -> message`. For 422 errors raised from model validations, each entry is a `{ field, message }` object.\n","items":{"type":"object","additionalProperties":{"type":"string"}}}}}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Invalid, missing, or expired OAuth access token. 401 responses for token problems are produced by the OAuth layer and follow the OAuth 2.0 Bearer Token error format (`{\"error\": \"...\", \"error_description\": \"...\"}`) rather than the standard `{error: {code, message}}` envelope used by the rest of the API.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"OAuth 2.0 error code (e.g. \"invalid_token\")"},"error_description":{"type":"string","description":"Human-readable explanation of the error"}}}}}},"Forbidden":{"description":"The access token does not have the required `partner_api_v2` scope. Like other OAuth errors, this response uses the OAuth 2.0 Bearer Token error format.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"},"scope":{"type":"string"}}}}}},"AgentNotFound":{"description":"Agent not found for the authenticated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/contacts/search":{"post":{"summary":"Search for a contact","description":"Searches for a contact in the HealthSherpa system created by the authenticated agent. You can search by medicare number alone, OR by using a combination of name (first name or last name) with at least one of: date of birth, email, or phone.\n","operationId":"searchContact","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["params"],"properties":{"params":{"type":"object","description":"Search parameters. Provide either medicare_number alone, OR a combination of (first_name or last_name) with at least one of (birth_date, email, or phone).\n","properties":{"medicare_number":{"type":"string","description":"Contact's Medicare number"},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":500},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":500},"birth_date":{"type":"string","description":"Contact's date of birth"},"email":{"type":"string","format":"email","description":"Contact's email address"},"phone":{"type":"string","description":"Contact's phone number"}}}}}}}},"responses":{"200":{"description":"Search completed. When a matching contact is found, `data.contact` is the contact and `data.redirect_url` is populated. The response includes the full contact payload with nested drugs, pharmacies, providers, and provider addresses. When no contact is found, both `data.contact` and `data.redirect_url` are `null`.\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact":{"oneOf":[{"$ref":"#/components/schemas/Contact"},{"type":"object","nullable":true}],"nullable":true},"redirect_url":{"type":"string","nullable":true,"description":"URL to access the contact's quote page on HealthSherpa; `null` when no contact is found."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/AgentNotFound"},"422":{"description":"Invalid search parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` # Schema ## The Contact object ```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API v2","version":"2.0.0"},"components":{"schemas":{"Contact":{"type":"object","properties":{"id":{"type":"string","description":"HealthSherpa system ID for the contact"},"slug":{"type":"string","description":"URL-friendly identifier for the contact"},"external_id":{"type":"string","minLength":1,"maxLength":100,"description":"Your system's unique identifier for this contact"},"first_name":{"type":"string","description":"Contact's first name","minLength":1,"maxLength":100},"last_name":{"type":"string","description":"Contact's last name","minLength":1,"maxLength":100},"address_1":{"type":"string","description":"Primary address line","minLength":1,"maxLength":100},"address_2":{"type":"string","nullable":true,"description":"Secondary address line","minLength":1,"maxLength":100},"birth_date":{"type":"string","description":"Contact's date of birth (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"city":{"type":"string","description":"City name","minLength":1,"maxLength":100},"state":{"type":"string","description":"Two-letter state code"},"zip":{"type":"string","description":"ZIP code (5 digits)"},"phone":{"type":"string","description":"Contact's phone number (10 digits without formatting)"},"sex":{"type":"string","description":"Contact's sex","enum":["male","female","M","F","m","f"]},"email":{"type":"string","format":"email","description":"Contact's email address"},"medicare_number":{"type":"string","description":"Contact's Medicare number","minLength":1,"maxLength":100},"medicare_part_a_effective_date":{"type":"string","description":"Medicare Part A effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicare_part_b_effective_date":{"type":"string","description":"Medicare Part B effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)"},"medicaid_eligible":{"type":"boolean","nullable":true,"description":"Whether the contact is eligible for Medicaid"},"medicaid_number":{"type":"string","description":"Contact's Medicaid number","minLength":1,"maxLength":100},"extra_help":{"type":"boolean","nullable":true,"description":"Whether the contact receives Extra Help"},"type":{"type":"string","description":"Contact type","enum":["client","lead"]},"authorized_representative_name":{"type":"string","description":"Name of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_relationship":{"type":"string","description":"Relationship of the authorized representative to the contact","minLength":1,"maxLength":100},"authorized_representative_phone_number":{"type":"string","description":"Phone number of the authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email address of the authorized representative"},"authorized_representative_address":{"type":"string","description":"Street address of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_city":{"type":"string","description":"City of the authorized representative","minLength":1,"maxLength":100},"authorized_representative_state":{"type":"string","description":"Two-letter state code of the authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of the authorized representative (5 digits)"},"mailing_address_street":{"type":"string","description":"Street address for mailing","minLength":1,"maxLength":100},"mailing_address_unit_number":{"type":"string","nullable":true,"description":"Unit number for mailing address","minLength":1,"maxLength":100},"mailing_address_city":{"type":"string","description":"City for mailing address","minLength":1,"maxLength":100},"mailing_address_state":{"type":"string","description":"Two-letter state code for mailing address"},"mailing_address_zip_code":{"type":"string","description":"ZIP code for mailing address (5 digits)"},"contact_drugs_attributes":{"type":"array","description":"Array of drugs associated with the contact","items":{"$ref":"#/components/schemas/ContactDrug"}},"contact_pharmacies_attributes":{"type":"array","description":"Array of pharmacies associated with the contact","items":{"$ref":"#/components/schemas/ContactPharmacy"}},"contact_providers_attributes":{"type":"array","description":"Array of providers associated with the contact","items":{"$ref":"#/components/schemas/ContactProvider"}}}},"ContactDrug":{"type":"object","required":["frequency","dosage_id","dosage_id_source","user_quantity","ndc","id","id_source","dosage_name","name","drug_type_id"],"properties":{"name":{"type":"string","description":"Drug name"},"drug_type_id":{"type":"integer","description":"Drug type identifier (1=Brand, 2=Generic, 3=OTC Brand, 4=Branded Generic, 5=OTC Branded Generic, 6=OTC Generic, 9=OTC DME Brand)","enum":[1,2,3,4,5,6,9]},"dosage_name":{"type":"string","description":"Full dosage name including strength"},"ndc":{"type":"string","description":"National Drug Code"},"frequency":{"type":"integer","description":"Frequency in days (e.g., 30 for monthly)","enum":[30,60,90,180,360]},"user_quantity":{"type":"integer","description":"Quantity the user takes"},"id":{"type":"string","description":"Drug identifier from source system"},"id_source":{"type":"string","description":"Source system for the drug ID (must be \"connecture\")","enum":["connecture"]},"dosage_id":{"type":"string","description":"Dosage identifier from source system"},"dosage_id_source":{"type":"string","description":"Source system for the dosage ID (must be \"connecture\")","enum":["connecture"]},"package_id":{"type":"string","description":"Package identifier from source system"},"package_id_source":{"type":"string","description":"Source system for the package ID (must be \"connecture\")","enum":["connecture"]},"package_description":{"type":"string","description":"Description of the package type"},"package_size":{"type":"integer","description":"Size of the package"},"package_quantity":{"type":"number","format":"float","description":"Quantity of packages"},"metric_quantity":{"type":"integer","description":"Metric quantity value"}}},"ContactPharmacy":{"type":"object","required":["id","id_source","name","mode","npi","address_street","address_city","address_state","address_zip_code"],"properties":{"id":{"type":"string","description":"Pharmacy identifier from source system"},"id_source":{"type":"string","description":"Source system for the pharmacy ID (must be \"connecture\")","enum":["connecture"]},"name":{"type":"string","description":"Pharmacy name"},"mode":{"type":"string","description":"Pharmacy mode","enum":["retail","digital"]},"npi":{"type":"string","description":"National Provider Identifier"},"primary":{"type":"boolean","description":"Whether this is the primary pharmacy"},"phone_number":{"type":"string","description":"Pharmacy phone number"},"address_street":{"type":"string","description":"Pharmacy street address"},"address_unit_number":{"type":"string","description":"Pharmacy unit number"},"address_city":{"type":"string","description":"Pharmacy city"},"address_state":{"type":"string","description":"Pharmacy state (two-letter code)"},"address_zip_code":{"type":"string","description":"Pharmacy ZIP code"}}},"ContactProvider":{"type":"object","required":["id","id_source","provider_type","presentation_name","contact_provider_addresses_attributes"],"properties":{"id":{"type":"string","description":"Provider identifier from source system"},"id_source":{"type":"string","description":"Source system for the provider ID (must be \"connecture\")","enum":["connecture"]},"provider_type":{"type":"string","description":"Type of provider","enum":["individual","organization"]},"presentation_name":{"type":"string","description":"Display name for the provider"},"primary":{"type":"boolean","description":"Whether this is the primary provider"},"first_name":{"type":"string","description":"Provider's first name (for individual providers)"},"last_name":{"type":"string","description":"Provider's last name (for individual providers)"},"organization_name":{"type":"string","description":"Organization name (for organization providers)"},"phone_number":{"type":"string","description":"Provider's phone number"},"npi":{"type":"string","description":"National Provider Identifier"},"specialties":{"type":"array","description":"List of provider specialties","items":{"type":"string"}},"contact_provider_addresses_attributes":{"type":"array","description":"Array of addresses for this provider. At least one valid address is required; providers with no valid addresses are rejected and reported in the partial_success errors array.\n","minItems":1,"items":{"$ref":"#/components/schemas/ContactProviderAddress"}}}},"ContactProviderAddress":{"type":"object","required":["id","id_source","city","state","zip_code"],"properties":{"id":{"type":"string","description":"Address identifier from source system"},"id_source":{"type":"string","description":"Source system for the address ID (must be \"connecture\")","enum":["connecture"]},"street":{"type":"string","description":"Street address"},"unit_number":{"type":"string","description":"Unit number"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State (two-letter code)"},"zip_code":{"type":"string","description":"ZIP code"},"phone_numbers":{"type":"array","description":"List of phone numbers for this address","items":{"type":"string"}},"selected":{"type":"boolean","description":"Whether this address is selected/preferred"}}}}}} ``` ## The ContactDrug object ```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API v2","version":"2.0.0"},"components":{"schemas":{"ContactDrug":{"type":"object","required":["frequency","dosage_id","dosage_id_source","user_quantity","ndc","id","id_source","dosage_name","name","drug_type_id"],"properties":{"name":{"type":"string","description":"Drug name"},"drug_type_id":{"type":"integer","description":"Drug type identifier (1=Brand, 2=Generic, 3=OTC Brand, 4=Branded Generic, 5=OTC Branded Generic, 6=OTC Generic, 9=OTC DME Brand)","enum":[1,2,3,4,5,6,9]},"dosage_name":{"type":"string","description":"Full dosage name including strength"},"ndc":{"type":"string","description":"National Drug Code"},"frequency":{"type":"integer","description":"Frequency in days (e.g., 30 for monthly)","enum":[30,60,90,180,360]},"user_quantity":{"type":"integer","description":"Quantity the user takes"},"id":{"type":"string","description":"Drug identifier from source system"},"id_source":{"type":"string","description":"Source system for the drug ID (must be \"connecture\")","enum":["connecture"]},"dosage_id":{"type":"string","description":"Dosage identifier from source system"},"dosage_id_source":{"type":"string","description":"Source system for the dosage ID (must be \"connecture\")","enum":["connecture"]},"package_id":{"type":"string","description":"Package identifier from source system"},"package_id_source":{"type":"string","description":"Source system for the package ID (must be \"connecture\")","enum":["connecture"]},"package_description":{"type":"string","description":"Description of the package type"},"package_size":{"type":"integer","description":"Size of the package"},"package_quantity":{"type":"number","format":"float","description":"Quantity of packages"},"metric_quantity":{"type":"integer","description":"Metric quantity value"}}}}}} ``` ## The ContactPharmacy object ```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API v2","version":"2.0.0"},"components":{"schemas":{"ContactPharmacy":{"type":"object","required":["id","id_source","name","mode","npi","address_street","address_city","address_state","address_zip_code"],"properties":{"id":{"type":"string","description":"Pharmacy identifier from source system"},"id_source":{"type":"string","description":"Source system for the pharmacy ID (must be \"connecture\")","enum":["connecture"]},"name":{"type":"string","description":"Pharmacy name"},"mode":{"type":"string","description":"Pharmacy mode","enum":["retail","digital"]},"npi":{"type":"string","description":"National Provider Identifier"},"primary":{"type":"boolean","description":"Whether this is the primary pharmacy"},"phone_number":{"type":"string","description":"Pharmacy phone number"},"address_street":{"type":"string","description":"Pharmacy street address"},"address_unit_number":{"type":"string","description":"Pharmacy unit number"},"address_city":{"type":"string","description":"Pharmacy city"},"address_state":{"type":"string","description":"Pharmacy state (two-letter code)"},"address_zip_code":{"type":"string","description":"Pharmacy ZIP code"}}}}}} ``` ## The ContactProvider object ```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API v2","version":"2.0.0"},"components":{"schemas":{"ContactProvider":{"type":"object","required":["id","id_source","provider_type","presentation_name","contact_provider_addresses_attributes"],"properties":{"id":{"type":"string","description":"Provider identifier from source system"},"id_source":{"type":"string","description":"Source system for the provider ID (must be \"connecture\")","enum":["connecture"]},"provider_type":{"type":"string","description":"Type of provider","enum":["individual","organization"]},"presentation_name":{"type":"string","description":"Display name for the provider"},"primary":{"type":"boolean","description":"Whether this is the primary provider"},"first_name":{"type":"string","description":"Provider's first name (for individual providers)"},"last_name":{"type":"string","description":"Provider's last name (for individual providers)"},"organization_name":{"type":"string","description":"Organization name (for organization providers)"},"phone_number":{"type":"string","description":"Provider's phone number"},"npi":{"type":"string","description":"National Provider Identifier"},"specialties":{"type":"array","description":"List of provider specialties","items":{"type":"string"}},"contact_provider_addresses_attributes":{"type":"array","description":"Array of addresses for this provider. At least one valid address is required; providers with no valid addresses are rejected and reported in the partial_success errors array.\n","minItems":1,"items":{"$ref":"#/components/schemas/ContactProviderAddress"}}}},"ContactProviderAddress":{"type":"object","required":["id","id_source","city","state","zip_code"],"properties":{"id":{"type":"string","description":"Address identifier from source system"},"id_source":{"type":"string","description":"Source system for the address ID (must be \"connecture\")","enum":["connecture"]},"street":{"type":"string","description":"Street address"},"unit_number":{"type":"string","description":"Unit number"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State (two-letter code)"},"zip_code":{"type":"string","description":"ZIP code"},"phone_numbers":{"type":"array","description":"List of phone numbers for this address","items":{"type":"string"}},"selected":{"type":"boolean","description":"Whether this address is selected/preferred"}}}}}} ``` ## The ContactProviderAddress object ```json {"openapi":"3.0.3","info":{"title":"HealthSherpa for Medicare Partner API v2","version":"2.0.0"},"components":{"schemas":{"ContactProviderAddress":{"type":"object","required":["id","id_source","city","state","zip_code"],"properties":{"id":{"type":"string","description":"Address identifier from source system"},"id_source":{"type":"string","description":"Source system for the address ID (must be \"connecture\")","enum":["connecture"]},"street":{"type":"string","description":"Street address"},"unit_number":{"type":"string","description":"Unit number"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State (two-letter code)"},"zip_code":{"type":"string","description":"ZIP code"},"phone_numbers":{"type":"array","description":"List of phone numbers for this address","items":{"type":"string"}},"selected":{"type":"boolean","description":"Whether this address is selected/preferred"}}}}}} ``` # Introduction A webhook allows for one-way data sharing triggered by events. Currently, we support the enrollment **submission** event, meaning partners can use our webhook system to receive application and contact data after an enrollment is submitted. [Get started](https://docs.medicare.healthsherpa.com/webhooks/getting-started) *** # Getting Started **To set up a webhook:** 1. [Create](https://intercom.help/healthsherpa-medicare-help-center/en/articles/13876230-webhook) a HealthSherpa Medicare account 2. Go to the **Integrations** tab and in the **Webhook** card, click **Add webhook**. 3. Enter your **Destination URL**. This is the URL where we’ll send enrollment submission payloads. Your CRM should provide this to you. 4. Choose an **Authentication** method: * **API Key:** Enter the API key from your CRM or destination system. We’ll send it as an X-API-Key header. * **None:** Use this only if your destination URL already includes authentication or your endpoint does not require authentication. 5. Click **Save webhook**. 6. You'll then implement your destination URL to ingest the [Submission Payload Schema](https://intercom.help/healthsherpa-medicare-help-center/en/articles/13876230-webhook). Use our Test button to send a sample payload to your destination URL that you can test with. See our [Video Tutorials](https://intercom.help/healthsherpa-medicare-help-center/en/articles/13876230-webhook#h_aeeda76633) for guidance on connecting your webhook your CRM. {% hint style="info" %} If you use an authentication method other than api keys, contact to let us know {% endhint %} # Event Types # Submission This event is sent to the configured destination URL when an application is submitted via HealthSherpa for Medicare. **Details:** * The webhook includes automatic retries – three attempts at 20 seconds, 10 minutes, and 1 hour after the initial delivery, if it fails. * If you're connecting to a HealthSherpa Medicare **agency** account, then any connected downline **agent** accounts will be included in the scope of this webhook. * Enrollments from accounts joined to you as **captive** agents send all application and contact fields in the payload. * Enrollments from accounts joined to you as **independent** agents receive all application fields and a limited subset of contact fields. * See the `SubmissionPayload` section below for details.
Example Payload ``` { "medicare_application": { "carrier_name": "Devoted Health", "cms_plan_id": "H1290-001-000", "confirmation_number": "A92946987696546M", "created_at": "2026-01-21T19:54:21.186Z", "effective_date": "2026-02-01", "fips_code": "12086", "plan_name": "DEVOTED CORE 001 FL (HMO)", "plan_sub_type": "hmo", "plan_type": "mapd", "plan_year": 2026, "send_to_beneficiary": false, "sep": "NEW", "signature": "voice_signature", "state": "FL", "submitted_at": "2026-01-21T19:56:43.302Z", "submitting_agent_first_name": "Heath", "submitting_agent_last_name": "Sherpa", "submitting_agent_npn": "1234567890", "total_premium_cents": 5000, "updated_at": "2026-01-21T19:56:52.627Z", "zip_code": "33101" }, "medicare_application_riders": [ { "plan_name": "Dental Plus", "premium_cents": 2500, "created_at": "2026-01-21T19:54:21.186Z", "updated_at": "2026-01-21T19:54:21.186Z" }, { "plan_name": "Vision Coverage", "premium_cents": 2500, "created_at": "2026-01-21T19:54:21.186Z", "updated_at": "2026-01-21T19:54:21.186Z" } ], "contact": { "id": "8b420678-2c58-4f56-9c0b-9ccb605e5e85", "external_id": "CRM789012", "first_name": "Test", "middle_name": "Person", "last_name": "Enrollment", "suffix": "Jr.", "birth_date": "1960-09-09", "email": "test.enrollment@example.com", "phone_number": "3055551234", "language": "English", "lead_source": "Website", "primary_address_street": "123 Main Street", "primary_address_unit_number": "Apt 101", "primary_address_city": "Miami", "primary_address_state": "FL", "primary_address_zip_code": "33101", "primary_address_county": "Miami-Dade", "primary_address_fips_code": "12086", "authorized_representative_name": "Child of Test Enrollment", "authorized_representative_relationship": "natural_child", "authorized_representative_address": "123 Main Street", "authorized_representative_city": "Miami", "authorized_representative_state": "FL", "authorized_representative_zip_code": "33101", "authorized_representative_phone_number": "3055551235", "authorized_representative_email": "child.enrollment@example.com", "medicaid_eligible": false, "medicaid_enrolled": false, "medicaid_number": null, "medicare_number": "1EG4TE5MK73", "needs_extra_help": false, "part_a_effective_date": "2020-07-01", "part_b_effective_date": "2020-07-01", "created_at": "2026-01-21T19:53:25.236Z", "updated_at": "2026-01-21T19:54:15.234Z", "contact_drugs_attributes": [ { "frequency": 30, "dosage_id": "dosage-cx-001", "dosage_id_source": "connecture", "metric_quantity": null, "ndc": "00093-7150-01", "package_description": null, "package_size": null, "package_quantity": null, "user_quantity": 1, "id": "drug-cx-001", "id_source": "connecture", "dosage_name": "10 mg tablet", "name": "Lisinopril", "drug_type_id": 2 } ], "contact_pharmacies_attributes": [ { "address_city": "Miami", "address_state": "FL", "address_street": "456 Pharmacy Lane", "address_unit_number": null, "address_zip_code": "33101", "npi": "1234567890", "primary": true, "id": "pharm-cx-001", "id_source": "connecture", "name": "CVS Pharmacy #1234", "mode": "retail", "phone_number": "+13055559876" } ], "contact_providers_attributes": [ { "external_id": "prov-001", "primary": true, "provider_type": "individual", "first_name": "Sarah", "last_name": "Johnson", "organization_name": null, "presentation_name": "Dr. Sarah L Johnson", "phone_number": "3055554321", "npi": "9876543210", "specialties": ["Internal Medicine"], "contact_provider_addresses_attributes": [ { "id": "addr-cx-001", "id_source": "connecture", "street": "789 Medical Center Dr", "unit_number": "Suite 200", "city": "Miami", "state": "FL", "zip_code": "33101", "selected": true, "phone_numbers": ["3055554321"] } ] } ] } } ```
## The SubmissionPayload object ```json {"openapi":"3.0.3","info":{"title":"Medicare Webhook Payload Reference","version":"1.0.0"},"components":{"schemas":{"SubmissionPayload":{"type":"object","required":["medicare_application","medicare_application_riders","contact"],"properties":{"medicare_application":{"$ref":"#/components/schemas/MedicareApplication"},"medicare_application_riders":{"type":"array","items":{"$ref":"#/components/schemas/MedicareApplicationRider"},"description":"Array of Medicare application riders"},"contact":{"$ref":"#/components/schemas/Contact"}}},"MedicareApplication":{"type":"object","required":["carrier_name","cms_plan_id","plan_name","plan_type","plan_sub_type","submitting_agent_email","submitting_agent_first_name","submitting_agent_last_name","submitting_agent_npn","created_at","updated_at","submitted_at"],"properties":{"carrier_name":{"type":"string","description":"Name of the insurance carrier"},"cms_plan_id":{"type":"string","description":"CMS plan identifier"},"confirmation_number":{"type":"string","description":"Confirmation number for the submission"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the application was created"},"effective_date":{"type":"string","format":"date","description":"Effective date of the enrollment"},"fips_code":{"type":"string","description":"Federal Information Processing Standard code for county"},"plan_name":{"type":"string","description":"Name of the insurance plan"},"plan_sub_type":{"type":"string","enum":["cost","hmo","hmopos","lppo","msa","pffs","ppo","rppo","high_deductible","high_deductible_plan","plan_a","plan_b","plan_c","plan_d","plan_e","plan_f","plan_f_high_deductible","plan_f_innovative","plan_g","plan_g_high_deductible","plan_g_innovative","plan_h","plan_i","plan_j","plan_j_high_deductible","plan_k","plan_l","plan_m","plan_n","plan_n_innovative","supplement_1_plan","supplement_1a_plan","waiver_state_plan"],"description":"Sub-category of the plan"},"plan_type":{"type":"string","enum":["mapd","pdp","ma","med_supp"],"description":"Type of Medicare plan"},"plan_year":{"type":"integer","description":"Year of the plan enrollment"},"send_to_beneficiary":{"type":"boolean","description":"Flag indicating whether the application was sent to the beneficiary for signature or completed via voice signature"},"state":{"type":"string","description":"State code (2-letter)"},"sep":{"type":"string","description":"SEP reason code"},"signature":{"type":"string","description":"Signature type","enum":["e_signature","voice_signature"]},"submitted_at":{"type":"string","format":"date-time","description":"Timestamp when the application was submitted"},"submitting_agent_email":{"type":"string","description":"The email associated with the submitting agent"},"submitting_agent_first_name":{"type":"string","description":"First name of the submitting agent"},"submitting_agent_last_name":{"type":"string","description":"Last name of the submitting agent"},"submitting_agent_npn":{"type":"string","description":"National Producer Number of the submitting agent"},"total_premium_cents":{"type":"integer","description":"Total premium in cents, including the premium for all riders."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the application was last updated"},"zip_code":{"type":"string","description":"ZIP code for the enrollment address"}}},"MedicareApplicationRider":{"type":"object","required":["plan_name","created_at","updated_at"],"properties":{"plan_name":{"type":"string","description":"Name of the rider plan"},"premium_cents":{"type":"integer","description":"Premium amount for the rider in cents"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the rider was created"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the rider was last updated"}}},"Contact":{"oneOf":[{"$ref":"#/components/schemas/ContactFull"},{"$ref":"#/components/schemas/ContactLimited"}],"discriminator":{"propertyName":"contact_type"}},"ContactFull":{"type":"object","description":"Full contact fields, provided when the submitting agent is a captive downline agent of your agency.","required":["id","first_name","last_name"],"properties":{"id":{"type":"string","format":"uuid","description":"HealthSherpa system unique identifier for the contact"},"first_name":{"type":"string","description":"First name"},"middle_name":{"type":"string","description":"Middle name"},"last_name":{"type":"string","description":"Last name"},"suffix":{"type":"string","description":"Name suffix (Jr., Sr., etc.)"},"birth_date":{"type":"string","format":"date","description":"Date of birth"},"email":{"type":"string","format":"email","description":"Email address"},"phone_number":{"type":"string","description":"Phone number"},"language":{"type":"string","description":"Preferred language"},"lead_source":{"$ref":"#/components/schemas/LeadSource"},"external_id":{"type":"string","description":"External system identifier"},"primary_address_street":{"type":"string","description":"Street address"},"primary_address_unit_number":{"type":"string","description":"Unit number (apartment, suite, etc.)"},"primary_address_city":{"type":"string","description":"City"},"primary_address_state":{"type":"string","description":"State code (2-letter)"},"primary_address_zip_code":{"type":"string","description":"ZIP code"},"primary_address_county":{"type":"string","description":"County name"},"primary_address_fips_code":{"type":"string","description":"Federal Information Processing Standard code"},"authorized_representative_name":{"type":"string","description":"Name of authorized representative"},"authorized_representative_relationship":{"type":"string","enum":["natural_child","spouse","mother","father","power_of_attorney","other"],"description":"Relationship to the contact"},"authorized_representative_address":{"type":"string","description":"Address of authorized representative"},"authorized_representative_city":{"type":"string","description":"City of authorized representative"},"authorized_representative_state":{"type":"string","description":"State of authorized representative"},"authorized_representative_zip_code":{"type":"string","description":"ZIP code of authorized representative"},"authorized_representative_phone_number":{"type":"string","description":"Phone number of authorized representative"},"authorized_representative_email":{"type":"string","format":"email","description":"Email of authorized representative"},"medicaid_eligible":{"type":"boolean","description":"Whether contact is eligible for Medicaid"},"medicaid_enrolled":{"type":"boolean","description":"Whether contact is enrolled in Medicaid"},"medicaid_level":{"type":"string","description":"Medicaid level/category"},"medicaid_number":{"type":"string","description":"Medicaid identification number"},"medicare_number":{"type":"string","description":"Medicare identification number"},"needs_extra_help":{"type":"boolean","description":"Whether contact qualifies for Extra Help program"},"part_a_effective_date":{"type":"string","format":"date","description":"Effective date of Medicare Part A"},"part_b_effective_date":{"type":"string","format":"date","description":"Effective date of Medicare Part B"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when contact was created"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when contact was last updated"},"contact_drug_attributes":{"type":"array","description":"Array of drugs associated with the contact","items":{"$ref":"#/components/schemas/ContactDrug"}},"contact_pharmacy_attributes":{"type":"array","description":"Array of pharmacies associated with the contact","items":{"$ref":"#/components/schemas/ContactPharmacy"}},"contact_provider_attributes":{"type":"array","description":"Array of providers associated with the contact","items":{"$ref":"#/components/schemas/ContactProvider"}}}},"LeadSource":{"type":"string","description":"Lead source","nullable":true,"enum":["client_referral","community_networking","company_lead","direct_mail","event","in_store_kiosk","lead_list","office_walk_in","paid_advertising","professional_referral","social_media","website"]},"ContactDrug":{"type":"object","required":["name","drug_type_id","dosage_name","ndc","frequency","user_quantity","id","id_source","dosage_id","dosage_id_source"],"properties":{"name":{"type":"string","description":"Name of the drug"},"drug_type_id":{"type":"string","description":"Drug type identifier"},"dosage_name":{"type":"string","description":"Name of the dosage"},"ndc":{"type":"string","description":"National Drug Code"},"frequency":{"type":"integer","description":"Frequency of the drug"},"user_quantity":{"type":"integer","description":"User quantity of the drug"},"id":{"type":"string","description":"HealthSherpa system unique identifier for the drug"},"id_source":{"type":"string","description":"Source system for the drug ID"},"dosage_id":{"type":"string","description":"HealthSherpa system unique identifier for the dosage"},"dosage_id_source":{"type":"string","description":"Source system for the dosage ID"},"package_description":{"type":"string","description":"Description of the package type"},"package_size":{"type":"integer","description":"Size of the package"},"package_quantity":{"type":"integer","description":"Quantity of the package"},"metric_quantity":{"type":"integer","description":"Metric quantity value"}}},"ContactPharmacy":{"type":"object","required":["name","mode","npi","primary"],"properties":{"id":{"type":"string","description":"HealthSherpa system unique identifier for the pharmacy"},"id_source":{"type":"string","description":"Source system for the pharmacy ID"},"name":{"type":"string","description":"Name of the pharmacy"},"mode":{"type":"string","description":"Mode of the pharmacy","enum":["retail","digital"]},"npi":{"type":"string","description":"National Provider Identifier"},"address_street":{"type":"string","description":"Pharmacy street address"},"address_unit_number":{"type":"string","description":"Pharmacy unit number"},"address_city":{"type":"string","description":"Pharmacy city"},"address_state":{"type":"string","description":"Pharmacy state"},"address_zip_code":{"type":"string","description":"Pharmacy ZIP code"},"primary":{"type":"boolean","description":"Whether this is the primary pharmacy"},"phone_number":{"type":"string","description":"Pharmacy phone number"}}},"ContactProvider":{"type":"object","required":["id","id_source","npi","specialties","contact_provider_addresses_attributes","primary"],"properties":{"id":{"type":"string","description":"HealthSherpa system unique identifier for the provider"},"id_source":{"type":"string","description":"Source system for the provider ID"},"provider_type":{"type":"string","description":"Type of provider","enum":["individual","organization"]},"presentation_name":{"type":"string","description":"Display name for the provider"},"npi":{"type":"string","description":"National Provider Identifier"},"organization_name":{"type":"string","description":"Organization name of the provider"},"phone_number":{"type":"string","description":"Provider phone number"},"first_name":{"type":"string","description":"Provider first name"},"last_name":{"type":"string","description":"Provider last name"},"specialties":{"type":"array","description":"List of provider specialties","items":{"type":"string"}},"contact_provider_addresses_attributes":{"type":"array","description":"Array of addresses for this provider","items":{"$ref":"#/components/schemas/ContactProviderAddress"}},"primary":{"type":"boolean","description":"Whether this is the primary provider"}}},"ContactProviderAddress":{"type":"object","required":["id","id_source","city","state","zip_code","phone_numbers","selected"],"properties":{"id":{"type":"string","description":"HealthSherpa system unique identifier for the address"},"id_source":{"type":"string","description":"Source system for the address ID"},"street":{"type":"string","description":"Street address"},"unit_number":{"type":"string","description":"Unit number"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State code (2-letter)"},"zip_code":{"type":"string","description":"ZIP code"},"selected":{"type":"boolean","description":"Whether this address is selected/preferred"},"phone_numbers":{"type":"array","description":"List of phone numbers for this address","items":{"type":"string"}}}},"ContactLimited":{"type":"object","description":"Limited contact fields, provided when the submitting agent is an independent agent.","required":["id","first_name","last_name"],"properties":{"id":{"type":"string","format":"uuid","description":"HealthSherpa system unique identifier for the contact"},"first_name":{"type":"string","description":"First name"},"middle_name":{"type":"string","description":"Middle name"},"last_name":{"type":"string","description":"Last name"},"suffix":{"type":"string","description":"Name suffix"},"primary_address_state":{"type":"string","description":"State code (2-letter)"},"primary_address_zip_code":{"type":"string","description":"ZIP code"},"lead_source":{"$ref":"#/components/schemas/LeadSource"},"external_id":{"type":"string","description":"External system identifier"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when contact was created"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when contact was last updated"}}}}}} ``` # Use Cases ### Typical uses of our API **Sync your CRM records into HealthSherpa to avoid dual data entry** * Create and update contact records in HealthSherpa so that dual data entry is eliminated across the quoting and enrollment flow. * Data entered in your CRM flows all the way from quoting through to the enrollment form. * This also reduces errors or typos across systems. **Add a “Quote in HealthSherpa” button to your CRM** * Launch the HealthSherpa quoting session for a specific contact using our `redirect_url`
### Typical uses of our Webhook **Sync your HealthSherpa enrollment records into your CRM to avoid dual data entry** * Enrollment and contact data syncs from our system to yours. * Triggered by our enrollment submission event. * Avoid copying and pasting enrollment data from our system to yours, it's automatic.
# Integration Patterns {% content-ref url="/pages/pkPYN5NsUVcuvm1kW1pA" %} [Sync from your CRM to HealthSherpa](/integration-guide/integration-patterns/sync-from-your-crm-to-healthsherpa) {% endcontent-ref %} # Sync from your CRM to HealthSherpa This pattern demonstrates how to synchronize contacts between your CRM and HealthSherpa's system. The flow ensures that each contact in your CRM has a corresponding record in HealthSherpa, and stays up-to-date. ## 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 2. **Agent Authentication** * Provide a "Login to HealthSherpa" button in your CRM * When clicked, opens [HealthSherpa login page](https://medicare.healthsherpa.com/sessions/new) in a new tab * Agent logs in to HealthSherpa separately 3. **Contact Synchronization Flow** * When a user clicks the "Sync to HealthSherpa" button in your CRM: 1. Check if the contact has a HealthSherpa ID stored in your CRM 1. If no HealthSherpa ID exists: * Create a new contact in HealthSherpa * Store the returned HealthSherpa ID in your CRM 2. If HealthSherpa ID exists: * Update the existing contact in HealthSherpa 2. Redirect the user to the quote page in HealthSherpa (the redirect URL will be returned from both the create and update contact endpoints). 1. If a zip code was provided, it will be pre-populated. If not, the agent will be prompted to provide one. In either case, the agent has to confirm the county in order to access the quote. 4. **Data Mapping** * Map your CRM fields to HealthSherpa fields * Required fields: `external_id`, `first_name`, `last_name` * Optional fields: email, phone, address, Medicare information 5. **Error Handling** * Handle API errors and show user-friendly error messages # 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) endpoint or [V2 Search Contact](/api-reference/version-2-oauth/endpoints/search-contact) 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 # AI Agents & MCP The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) lets AI assistants and development tools pull documentation and context from external sources. With MCP, an AI can answer questions and generate code using up-to-date API details instead of relying only on its training data. ## HealthSherpa Medicare MCP server This documentation site includes a built-in MCP server that exposes the full Medicare API documentation for AI-assisted search. You send a natural-language or keyword query and receive relevant excerpts with links back to the source pages. {% hint style="info" %} No API key or OAuth token is required to use the documentation via MCP. Authentication is only necessary for using the API. {% endhint %} **MCP server URL:** ``` https://docs.medicare.healthsherpa.com/~gitbook/mcp ``` ## How to add the MCP server {% stepper %} {% step %} ### Add the HealthSherpa Medicare MCP server In your AI or development environment (e.g. Cursor, Claude Code, or another MCP-compatible client), add the HealthSherpa Medicare API MCP server. #### Cursor Add to `.cursor/mcp.json` in your project root, or go to **Cursor Settings → MCP → Add new global MCP server**: ```json { "mcpServers": { "HealthSherpa-Medicare-Docs": { "url": "https://docs.medicare.healthsherpa.com/~gitbook/mcp" } } } ``` #### Claude Code From your terminal: ```bash claude mcp add --transport http HealthSherpa-Medicare-Docs https://docs.medicare.healthsherpa.com/~gitbook/mcp ``` Add `--scope user` to make it available across all projects, or `--scope project` to share it with your team via `.mcp.json`. #### Claude Desktop Open **Settings → Developer → Edit Config** and add the server to `claude_desktop_config.json`: ```json { "mcpServers": { "HealthSherpa-Medicare-Docs": { "url": "https://docs.medicare.healthsherpa.com/~gitbook/mcp" } } } ``` #### VS Code (Copilot) **CLI:** bash ```bash code --add-mcp '{"name":"HealthSherpa-Medicare-Docs","type":"http","url":"https://docs.medicare.healthsherpa.com/~gitbook/mcp"}' ``` **Or** add to `.vscode/mcp.json` in your project root: ```json { "servers": { "HealthSherpa-Medicare-Docs": { "url": "https://docs.medicare.healthsherpa.com/~gitbook/mcp" } } } ``` #### Windsurf Add to `.windsurf/mcp.json` in your project root: ```json { "mcpServers": { "HealthSherpa-Medicare-Docs": { "url": "https://docs.medicare.healthsherpa.com/~gitbook/mcp" } } } ``` #### Other MCP clients Any tool that supports MCP over HTTP can connect using the server URL above. Refer to your tool's documentation for the specific configuration format. For general MCP setup, see the [Model Context Protocol docs](https://modelcontextprotocol.io). {% endstep %} {% step %} ### Verify and use Once configured, ask your AI assistant questions about the Medicare API in natural language. The assistant will search the documentation and return relevant excerpts with links to the full pages. {% endstep %} {% endstepper %} ## Usage #### Planning your integration Use MCP to explore the API surface and plan your integration before writing any code. * "What endpoints does the HealthSherpa Medicare API offer, and how do they fit together in a contact syncing workflow?" * "What's the difference between v1 and v2 of the API, and which should I use?" * "How do I set up and test against the staging environment before going to production?" #### Building contact synchronization flow These prompts help when you're actively building the contact synchronization workflow in your product * "Implement a `/search` endpoint that accepts medicare number alone, OR a combination of name (first name or last name) with at least one of: date of birth, email, or phone, and returns a contact" * "What fields are required vs optional when creating a contact, and what are the validation rules?" * "How does agent\_email work and what happens if it doesn't match a HealthSherpa account email?" #### Handling webhooks Use these when building the backend that tracks application submission events. * "Generate a webhook handler that processes the Submission event and maps the payload to our internal application model." * "What does the webhook submission payload look like and what fields does it include?" #### Troubleshooting and edge cases When you hit something unexpected during development, MCP can surface the relevant docs fast. * "What error responses can the Create Contact endpoint return, and how should I handle them?"