---
title: "Update an existing contact"
method: PATCH
path: "/contacts/{contact_id}"
tags: ["Contacts"]
---

# Update an existing contact

`PATCH /contacts/{contact_id}`

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.

## Path parameters

- `contact_id` string, required

## Request body

- object
  - `contact` ContactUpdate, required
    - `external_id` string — 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".
    - `first_name` string — Contact's first name
    - `last_name` string — Contact's last name
    - `address_1` string — Primary address line
    - `address_2` string, nullable — Secondary address line
    - `birth_date` string — Contact's date of birth (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)
    - `city` string — City name
    - `state` string — Two-letter state code
    - `zip` string — ZIP code (5 digits)
    - `phone` string — Contact's phone number (10 digits without formatting)
    - `sex` 'male' | 'female' | 'M' | 'F' | 'm' | 'f' — Contact's sex
    - `email` string, email — Contact's email address
    - `medicare_number` string — Contact's Medicare number
    - `medicare_part_a_effective_date` string — Medicare Part A effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)
    - `medicare_part_b_effective_date` string — Medicare Part B effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)
    - `medicaid_eligible` boolean, nullable — Whether the contact is eligible for Medicaid
    - `medicaid_number` string — Contact's Medicaid number
    - `extra_help` boolean, nullable — Whether the contact receives Extra Help
    - `type` 'client' | 'lead' — Contact type
    - `notes` string[] — Array of notes about the contact. Notes are appended (not replaced) on update.
    - `authorized_representative_name` string — Name of the authorized representative
    - `authorized_representative_relationship` string — Relationship of the authorized representative to the contact
    - `authorized_representative_phone_number` string — Phone number of the authorized representative
    - `authorized_representative_email` string, email — Email address of the authorized representative
    - `authorized_representative_address` string — Street address of the authorized representative
    - `authorized_representative_city` string — City of the authorized representative
    - `authorized_representative_state` string — Two-letter state code of the authorized representative
    - `authorized_representative_zip_code` string — ZIP code of the authorized representative (5 digits)
    - `mailing_address_street` string — Street address for mailing
    - `mailing_address_unit_number` string, nullable — Unit number for mailing address
    - `mailing_address_city` string — City for mailing address
    - `mailing_address_state` string — Two-letter state code for mailing address
    - `mailing_address_zip_code` string — ZIP code for mailing address (5 digits)
    - `contact_drugs_attributes` ContactDrug[] — Array of drugs associated with the contact
      - `name` string, required — Drug name
      - `drug_type_id` 1 | 2 | 3 | 4 | 5 | 6 | 9, required — Drug type identifier (1=Brand, 2=Generic, 3=OTC Brand, 4=Branded Generic, 5=OTC Branded Generic, 6=OTC Generic, 9=OTC DME Brand)
      - `dosage_name` string, required — Full dosage name including strength
      - `ndc` string, required — National Drug Code
      - `frequency` 30 | 60 | 90 | 180 | 360, required — Frequency in days (e.g., 30 for monthly)
      - `user_quantity` integer, required — Quantity the user takes
      - `id` string, required — Drug identifier from source system
      - `id_source` 'connecture', required — Source system for the drug ID (must be "connecture")
      - `dosage_id` string, required — Dosage identifier from source system
      - `dosage_id_source` 'connecture', required — Source system for the dosage ID (must be "connecture")
      - `package_id` string — Package identifier from source system
      - `package_id_source` 'connecture' — Source system for the package ID (must be "connecture")
      - `package_description` string — Description of the package type
      - `package_size` integer — Size of the package
      - `package_quantity` number, float — Quantity of packages
      - `metric_quantity` integer — Metric quantity value
    - `contact_pharmacies_attributes` ContactPharmacy[] — Array of pharmacies associated with the contact
      - `id` string, required — Pharmacy identifier from source system
      - `id_source` 'connecture', required — Source system for the pharmacy ID (must be "connecture")
      - `name` string, required — Pharmacy name
      - `mode` 'retail' | 'digital', required — Pharmacy mode
      - `npi` string, required — National Provider Identifier
      - `primary` boolean — Whether this is the primary pharmacy
      - `phone_number` string — Pharmacy phone number
      - `address_street` string, required — Pharmacy street address
      - `address_unit_number` string — Pharmacy unit number
      - `address_city` string, required — Pharmacy city
      - `address_state` string, required — Pharmacy state (two-letter code)
      - `address_zip_code` string, required — Pharmacy ZIP code
    - `contact_providers_attributes` ContactProvider[] — Array of providers associated with the contact
      - `id` string, required — Provider identifier from source system
      - `id_source` 'connecture', required — Source system for the provider ID (must be "connecture")
      - `provider_type` 'individual' | 'organization', required — Type of provider
      - `presentation_name` string, required — Display name for the provider
      - `primary` boolean — Whether this is the primary provider
      - `first_name` string — Provider's first name (for individual providers)
      - `last_name` string — Provider's last name (for individual providers)
      - `organization_name` string — Organization name (for organization providers)
      - `phone_number` string — Provider's phone number
      - `npi` string — National Provider Identifier
      - `specialties` string[] — List of provider specialties
      - `contact_provider_addresses_attributes` ContactProviderAddress[], required — 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.
        - `id` string, required — Address identifier from source system
        - `id_source` 'connecture', required — Source system for the address ID (must be "connecture")
        - `street` string — Street address
        - `unit_number` string — Unit number
        - `city` string, required — City
        - `state` string, required — State (two-letter code)
        - `zip_code` string, required — ZIP code
        - `phone_numbers` string[] — List of phone numbers for this address
        - `selected` boolean — Whether this address is selected/preferred

## Response `200`

Contact updated successfully. May return partial_success status if any of the sub-records (drugs, pharmacies, providers) failed to save.

- object
  - `data` object
    - `status` 'success' | 'partial_success' — 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.
    - `errors` object[] — Array of errors for sub-records that failed to save. Empty when status is "success".
      - `type` 'drug' | 'pharmacy' | 'provider' | 'provider_address' — The type of sub-record that failed
      - `source` string, nullable — The id_source value provided. Null for provider-level errors.
      - `identifier` string — The ID of the record that failed
      - `message` string — Human-readable error message
    - `contact` Contact
      - `id` string — HealthSherpa system ID for the contact
      - `slug` string — URL-friendly identifier for the contact
      - `external_id` string — Your system's unique identifier for this contact
      - `first_name` string — Contact's first name
      - `last_name` string — Contact's last name
      - `address_1` string — Primary address line
      - `address_2` string, nullable — Secondary address line
      - `birth_date` string — Contact's date of birth (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)
      - `city` string — City name
      - `state` string — Two-letter state code
      - `zip` string — ZIP code (5 digits)
      - `phone` string — Contact's phone number (10 digits without formatting)
      - `sex` 'male' | 'female' | 'M' | 'F' | 'm' | 'f' — Contact's sex
      - `email` string, email — Contact's email address
      - `medicare_number` string — Contact's Medicare number
      - `medicare_part_a_effective_date` string — Medicare Part A effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)
      - `medicare_part_b_effective_date` string — Medicare Part B effective date (MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD, or YYYY/MM/DD)
      - `medicaid_eligible` boolean, nullable — Whether the contact is eligible for Medicaid
      - `medicaid_number` string — Contact's Medicaid number
      - `extra_help` boolean, nullable — Whether the contact receives Extra Help
      - `type` 'client' | 'lead' — Contact type
      - `authorized_representative_name` string — Name of the authorized representative
      - `authorized_representative_relationship` string — Relationship of the authorized representative to the contact
      - `authorized_representative_phone_number` string — Phone number of the authorized representative
      - `authorized_representative_email` string, email — Email address of the authorized representative
      - `authorized_representative_address` string — Street address of the authorized representative
      - `authorized_representative_city` string — City of the authorized representative
      - `authorized_representative_state` string — Two-letter state code of the authorized representative
      - `authorized_representative_zip_code` string — ZIP code of the authorized representative (5 digits)
      - `mailing_address_street` string — Street address for mailing
      - `mailing_address_unit_number` string, nullable — Unit number for mailing address
      - `mailing_address_city` string — City for mailing address
      - `mailing_address_state` string — Two-letter state code for mailing address
      - `mailing_address_zip_code` string — ZIP code for mailing address (5 digits)
      - `contact_drugs_attributes` ContactDrug[] — Array of drugs associated with the contact
        - `name` string, required — Drug name
        - `drug_type_id` 1 | 2 | 3 | 4 | 5 | 6 | 9, required — Drug type identifier (1=Brand, 2=Generic, 3=OTC Brand, 4=Branded Generic, 5=OTC Branded Generic, 6=OTC Generic, 9=OTC DME Brand)
        - `dosage_name` string, required — Full dosage name including strength
        - `ndc` string, required — National Drug Code
        - `frequency` 30 | 60 | 90 | 180 | 360, required — Frequency in days (e.g., 30 for monthly)
        - `user_quantity` integer, required — Quantity the user takes
        - `id` string, required — Drug identifier from source system
        - `id_source` 'connecture', required — Source system for the drug ID (must be "connecture")
        - `dosage_id` string, required — Dosage identifier from source system
        - `dosage_id_source` 'connecture', required — Source system for the dosage ID (must be "connecture")
        - `package_id` string — Package identifier from source system
        - `package_id_source` 'connecture' — Source system for the package ID (must be "connecture")
        - `package_description` string — Description of the package type
        - `package_size` integer — Size of the package
        - `package_quantity` number, float — Quantity of packages
        - `metric_quantity` integer — Metric quantity value
      - `contact_pharmacies_attributes` ContactPharmacy[] — Array of pharmacies associated with the contact
        - `id` string, required — Pharmacy identifier from source system
        - `id_source` 'connecture', required — Source system for the pharmacy ID (must be "connecture")
        - `name` string, required — Pharmacy name
        - `mode` 'retail' | 'digital', required — Pharmacy mode
        - `npi` string, required — National Provider Identifier
        - `primary` boolean — Whether this is the primary pharmacy
        - `phone_number` string — Pharmacy phone number
        - `address_street` string, required — Pharmacy street address
        - `address_unit_number` string — Pharmacy unit number
        - `address_city` string, required — Pharmacy city
        - `address_state` string, required — Pharmacy state (two-letter code)
        - `address_zip_code` string, required — Pharmacy ZIP code
      - `contact_providers_attributes` ContactProvider[] — Array of providers associated with the contact
        - `id` string, required — Provider identifier from source system
        - `id_source` 'connecture', required — Source system for the provider ID (must be "connecture")
        - `provider_type` 'individual' | 'organization', required — Type of provider
        - `presentation_name` string, required — Display name for the provider
        - `primary` boolean — Whether this is the primary provider
        - `first_name` string — Provider's first name (for individual providers)
        - `last_name` string — Provider's last name (for individual providers)
        - `organization_name` string — Organization name (for organization providers)
        - `phone_number` string — Provider's phone number
        - `npi` string — National Provider Identifier
        - `specialties` string[] — List of provider specialties
        - `contact_provider_addresses_attributes` ContactProviderAddress[], required — 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.
          - `id` string, required — Address identifier from source system
          - `id_source` 'connecture', required — Source system for the address ID (must be "connecture")
          - `street` string — Street address
          - `unit_number` string — Unit number
          - `city` string, required — City
          - `state` string, required — State (two-letter code)
          - `zip_code` string, required — ZIP code
          - `phone_numbers` string[] — List of phone numbers for this address
          - `selected` boolean — Whether this address is selected/preferred
    - `redirect_url` string — URL to access the contact's quote page on HealthSherpa

## Other responses

- `400` — Validation error
- `401` — Unauthorized - Invalid, missing, or expired OAuth token
- `403` — 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.
- `404` — Agent not found for the authenticated user
- `422` — The request was well-formed but could not be processed

---

[API](https://skmtc.net/healthsherpa/apis/health-insurance-quotes-api.md) · [All operations](https://skmtc.net/healthsherpa/apis/health-insurance-quotes-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/healthsherpa/health-insurance-quotes-api/revisions/3cbfff4e5929/schema)