---
title: "Search for a contact"
method: POST
path: "/contacts/search"
tags: ["Contacts"]
---

# Search for a contact

`POST /contacts/search`

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.

## Request body

- object
  - `params` object, required — 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).
    - `medicare_number` string — Contact's Medicare number
    - `first_name` string — Contact's first name
    - `last_name` string — Contact's last name
    - `birth_date` string — Contact's date of birth
    - `email` string, email — Contact's email address
    - `phone` string — Contact's phone number

## Response `200`

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`.

- object
  - `data` object
    - `contact` union
      - 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
      - object, nullable
    - `redirect_url` string, nullable — URL to access the contact's quote page on HealthSherpa; `null` when no contact is found.

## Other responses

- `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` — Invalid search parameters

---

[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)