> 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/endpoints/search-contact.md).

# Search Contact

Solves for "Contact created in HealthSherpa"

The search endpoint solves the "started in HealthSherpa Medicare" problem. When an agent creates a contact directly in HealthSherpa Medicare rather than in your system, your system has no HealthSherpa contact ID on file – which means webhook updates for that contact can't sync to the right record, and pushing the contact from your system into HealthSherpa Medicare would create a duplicate.

Use this endpoint to find the existing HealthSherpa Medicare contact – by MBI (the strongest match) or a combination of name, phone, and email – retrieve its HealthSherpa Medicare contact ID, and link it to your record. Once linked, webhooks sync correctly and updates flow to the existing contact instead of creating duplicates.

A common pattern is a "Sync from HealthSherpa Medicare" action in your UI: the agent triggers a search, and your system either links the match it finds or, if there's no match, creates a new contact in HealthSherpa Medicare. You can also build this as fallback logic inside a quote flow, for cases when a contact ID isn't found. Search results are scoped to the acting agent's assigned/owned contacts.

## 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.<br>

```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. This must match the CMS valid MBI format described in the [CMS MBI format guide](https://www.cms.gov/Medicare/New-Medicare-Card/Understanding-the-MBI-with-Format.pdf) - otherwise, the Contact sync will fail.","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"}}},"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. This must match the CMS valid MBI format described in the [CMS MBI format guide](https://www.cms.gov/Medicare/New-Medicare-Card/Understanding-the-MBI-with-Format.pdf) - otherwise, the Contact sync will fail."},"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"}}}}}}}}}
```