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
The Resource Hierarchy
A record location is modeled as a brand → portal → endpoint hierarchy, following the SMART App Launch: User-access Brands and Endpoints specification:
- Brand: The top-level healthcare organization (e.g., "General Hospital").
- Portal: The patient-facing portal through which records are retrieved (e.g., "MyChart").
- Endpoint: The specific connection point, backed by an EHR platform.
This hierarchy maps directly to a selection UI:
- Single match: When a result resolves to a single brand → portal → endpoint combination, present it as one ready-to-connect option.
- Multiple matches: When a brand has multiple portals (or a portal has multiple endpoints), surface a picker letting the patient choose the relevant portal or endpoint.
Whichever path the patient takes, you will end up with exactly one brandId/portalId/endpointId combination.
Search & Service Areas
You can search by free-text name and optionally filter results toward a location (ZIP, city, or state) or restrict them to a specific EHR platform. Results are paginated.
Each result reports how it matched your query (by primary name, alias, or EHR platform name) and an approximate service area:
type | Meaning | Additional Fields |
|---|---|---|
single | Serves a single city/state area. | city (optional), state (optional) |
regional | Serves a small set of areas spanning one or two states. | locationCount, states[] |
nationwide | Serves locations across the country. | None |
The serviceArea object is omitted when the service area is unknown. Always check for the presence of serviceArea and branch on type before reading variant-specific fields.
Authorization
Accepts a Bearer token belonging to an organization or a patient. Because the catalog is not patient-scoped, both token types return identical results. See Authentication for details on obtaining a token.
Rate Limiting
This endpoint is rate limited to 10,000 requests per minute. Requests exceeding this limit receive a 429 response.
Error Responses
| Response Code | Reason |
|---|---|
| 400 Bad Request | Search input failed validation (e.g., malformed filter or invalid pagination value). |
| 401 Unauthorized | Token is missing, invalid, or expired. |
| 403 Forbidden | Token is valid, but lacks permission to use this endpoint. |
| 503 Service Unavailable | Service is temporarily unavailable. Retry shortly. |
Next Steps: Starting a Consent Flow
The brandId, portalId, and endpointId returned in a search result are the exact identifiers required to initiate the patient consent flow. Retain these IDs from the search response and forward them when initiating consent.
For query parameters, request headers, and full payload schemas, see the Search Record Locations API reference.