Search Contact

Search for a contact

post

https://api.medicare.healthsherpa.com/v2https://api.medicare-staging.healthsherpa.com/v2

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

Required scopes

This endpoint requires the following scopes:

• : Access to Partner API v2 endpoints

Authorizations

OAuth2

OAuth2authorizationCodeRequired

OAuth 2.0 authentication with partner_api_v2 scope

Authorization URL: Token URL:

Body

application/json

Responses

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.

application/json

401

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.

application/json

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.

application/json

404

Agent not found for the authenticated user

application/json

422

Invalid search parameters

application/json

post

/contacts/search

HTTPcURLJavaScriptPython

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": "[email protected]",
    "phone": "8557722663"
  }
}

{
  "data": {
    "contact": null,
    "redirect_url": null
  }
}