Record Location Search
The Record Location Search API lets you find record locations — healthcare organizations and their patient portals — by name, with optional location and EHR platform filters. Use it to look up a provider, then hand the result off to the consent flow so the patient can connect that record location.
Overview
A record location is modeled as a brand → portal → endpoint hierarchy, following the SMART App Launch: User-access Brands and Endpoints specification:
- A brand is the top-level healthcare organization (for example, "General Hospital").
- Each brand exposes one or more portals — the patient-facing portals through which records are retrieved (for example, "MyChart").
- Each portal exposes one or more endpoints — the specific connection points, each backed by an EHR platform.
This hierarchy maps directly onto a selection UI. When a result resolves to a single brand → portal → endpoint combination, you can present it as one ready-to-connect option. When a brand has multiple portals (or a portal has multiple endpoints), surface a picker: the patient first selects the brand, then the relevant portal, and finally the endpoint if more than one applies. Whichever path the patient takes, you end up with exactly one brandId/portalId/endpointId combination to hand to the consent flow.
You search by free-text name and can optionally filter results toward a location (ZIP, city, or state) or restrict them to a specific EHR platform. Results are paginated.
Each result also reports how it matched your query (by primary name, a known alias, or an EHR platform name) and an approximate service area to help you present a recognizable location label. The service area comes in a few different shapes, and its type field tells you which one you're looking at:
type | Meaning | Additional fields |
|---|---|---|
single | Serves a single city/state area. | city, state (both optional) |
regional | Serves a small set of areas spanning one or two states. | locationCount, states[] |
nationwide | Serves locations across the country. | (none) |
The serviceArea field is omitted when the area is unknown, so always branch on type before reading the variant-specific fields.
Authorization
Accepts a Bearer token belonging to an organization or a patient. The catalog is not patient-scoped, so both token types return the same results. See Authentication for how to obtain a token.
Starting a Consent Flow
The brandId, portalId, and endpointId returned for a result are the identifiers you pass to the consent flow to let a patient connect the selected record location. Retain them from the search result and forward them when initiating consent.
Rate Limiting
This endpoint is rate limited to 10,000 requests per minute. Requests beyond this limit receive a 429 response.
Error Responses
Bad Request
HTTP 400 — The search input failed validation (for example, a malformed filter or pagination value).
Unauthorized
HTTP 401 — The token is missing, invalid, or expired.
Forbidden
HTTP 403 — The token is valid but its type is not permitted to use this endpoint.
Service Unavailable
HTTP 503 — Service unavailable, retry shortly.
API Reference
For the request body, filters, pagination, the full response schema, the supported ehrPlatform values, and error responses, see the Search Record Locations API reference.