> 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
## 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.
```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","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"}}},"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"},"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"}}}}}}}}}
```
---
# 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, and the optional `goal` query parameter:
```
GET https://docs.medicare.healthsherpa.com/api-reference/version-2-oauth/endpoints/search-contact.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.