> For the complete documentation index, see [llms.txt](https://docs.medicare.healthsherpa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.medicare.healthsherpa.com/api-reference/version-2-oauth/schema.md).

# 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"}}}}}}
```


---

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

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

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

```
GET https://docs.medicare.healthsherpa.com/api-reference/version-2-oauth/schema.md?ask=<question>
```

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

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