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.
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.
- : Access to Partner API v2 endpoints
OAuth 2.0 authentication with partner_api_v2 scope
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.
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.
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.
Agent not found for the authenticated user
Invalid search parameters
POST /v2/contacts/search HTTP/1.1
Host: api.medicare.healthsherpa.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 160
{
"params": {
"medicare_number": "1EG4TE5MK73",
"first_name": "Alex",
"last_name": "Lee",
"birth_date": "01/15/1955",
"email": "alex.lee@example.com",
"phone": "8557722663"
}
}{
"data": {
"contact": null,
"redirect_url": null
}
}Last updated