> 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"]},"status":{"type":"string","description":"Contact's workflow status. Unsupported values are treated as `new`.","enum":["new","contacted","in_progress","enrolled","not_interested","inactive","do_not_contact","deceased"]},"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"}}}}}}
```