Skip to main content

Nearby Record Locations

The Nearby Record Locations API returns record locations — healthcare organizations and their patient portals — near a location, so you can proactively offer them as places to connect. It is location-based only: it requires no prior record retrieval and no consent. Each suggestion carries the same brandId/portalId/endpointId identifiers as Record Location Search, which you hand off to the consent flow.

Overview​

Suggestions are derived purely from location, with the most specific signal taking precedence:

  • Organization tokens: the zipcode you supply (recommended), otherwise the approximate location of the request.
  • Patient tokens: the zipcode you supply, otherwise the patient's verified (IAL2) location, otherwise the approximate location of the request.

The client IP is used solely to derive an approximate ZIP code when no zipcode is supplied; it is not stored or used for anything else. Because server-to-server callers present their own server's IP, supplying zipcode is recommended.

When no location can be determined (or suggestions are disabled), the endpoint returns an empty list rather than an error.

Authorization​

Accepts a Bearer token belonging to an organization or a patient. See Authentication for how to obtain a token.

The brandId, portalId, and endpointId returned for a suggestion are the identifiers you pass to the consent flow to let a patient connect the selected record location. Retain them and forward them when initiating consent.

Rate Limiting​

This endpoint is rate limited to 3,000 requests per minute. Requests beyond this limit receive a 429 response.

Error Responses​

Bad Request​

HTTP 400 — The zipcode query parameter is not a valid 5-digit USA ZIP code.

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 query parameters, response schema, and error responses, see the Get Nearby Record Locations API reference.