Skip to main content

Record Location Recommendations

The Record Location Recommendations API returns personalized record location recommendations for the authenticated patient — record locations HealthEx has discovered are likely relevant to them. Each recommendation carries the same brandId/portalId/endpointId identifiers as Record Location Search, which you hand off to the consent flow.

Overview​

Recommendations are personalized to the authenticated patient, in contrast to the location-only Nearby Record Locations endpoint:

  • They are scoped to a project (projectId) and require the patient to have an active consent on it; requests without consent are rejected.
  • They are derived from a record retrieval initiated under that project: supply a retrievalId (which must belong to the same project), or omit it to use the patient's most recent eligible retrieval for the project.

When the patient has no eligible retrieval for the project (and none is supplied), or a valid retrieval yields nothing, the endpoint returns an empty list rather than an error.

Authorization​

Accepts a patient Bearer token only; the patient is identified by the token itself. The patient must also have an active patient-data-sharing consent on the supplied projectId. See Authentication for how to obtain a token.

The brandId, portalId, and endpointId returned for a recommendation 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 60 requests per minute. Requests beyond this limit receive a 429 response.

Error Responses​

Bad Request​

HTTP 400 — A required query parameter is missing or malformed (for example, projectId is absent, or retrievalId is blank).

Unauthorized​

HTTP 401 — The token is missing, invalid, or expired.

Forbidden​

HTTP 403 — The token is not a patient token, the patient has no active patient-data-sharing consent on the supplied projectId, or the supplied retrievalId does not belong to the patient or to this project.

Not Found​

HTTP 404 — No project exists for the supplied projectId.

API Reference​

For the query parameters, response schema, and error responses, see the Get Record Location Recommendations API reference.