Add a Record Location

The "Add a Record Location" flow lets a patient add a new healthcare provider to their record without going through a full data refresh. Use this when a patient needs to fill a gap in their clinical history or connect a provider they have not previously added. This flow is offered in addition to the standard consent and Updating Patient Data flows — it does not replace them.

This flow is distinct from the Updating Patient Data flow:

	Update Patient Data	Add a Record Location
Triggers TEFCA/RLS scan	Yes	No
Refreshes existing locations	Yes	No
Preserves existing locations	Yes	Yes
Patient selects new provider	Optional	Always
Requires patient interaction	Only when auth expired	Always

What the Patient Experiences

Generic flow (no provider pre-selected):

Auth (if necessary) → Consent (if necessary) → Find a Record Location → Identify Record Location → Log into Patient Portal → Record Location added → Success

Specific flow (brandId, portalId, and endpointId provided):

Auth (if necessary) → Consent (if necessary) → Log into Record Location (or skip) → Log into Patient Portal → Record Location added → Success

On the generic flow, the patient may add another record location or return to the originating application after a successful add. On the specific flow, a failed add offers retry or go back. When redirectUri is provided, successful completion in either flow redirects the patient as described below.

Authentication and consent are always enforced:

• Logged-out patients are shown the login screen first, then proceed to the Find a Record Location flow.
• Logged-in patients with valid tokens (including CLEAR or social login) go directly to the add-a-provider screen — welcome, how-it-works, and full-network refresh steps are skipped.
• Patients who have not yet consented to the project are shown the participation signature screen before proceeding.
• Patients who have already consented skip the consent screen entirely.

On success, hosted integrations that pass redirectUri on the URL (same mechanism as the standard enrollment flow) redirect the patient back to the originating application or AI agent. If redirectUri is omitted, the patient lands on the standard HealthEx success screen.

If a patient attempts to add a record location they have already connected, they are warned that doing so may create duplicates and are directed to refresh their records instead.

How to Invoke

Direct the patient to a well-known URL for your project (similar to the first-time OAuth enrollment link) with addRecordLocationsDirectly=true.

Generic URL

No provider pre-selected — the patient searches for and selects a provider:

https://app.healthex.io/#/patient-consent/<projectId>/enrollment/link?addRecordLocationsDirectly=true

Replace <projectId> with your project's ID.

Specific URL

Known brandId, portalId, and endpointId values pre-select the provider, as though the patient had already chosen it in the Find a Record Location dialog. Use this in conjunction with the Search Health Records API for AI surfaces when a gap has been identified — for example, from the health wallet or by an AI partner that has identified a missing provider:

https://app.healthex.io/#/patient-consent/<projectId>/enrollment/link?addRecordLocationsDirectly=true&brandId=<brandId>&portalId=<portalId>&endpointId=<endpointId>

Replace <brandId>, <portalId>, and <endpointId> with the identifiers for the target provider, obtained from the Record Location Search or Recommendations APIs.

URL Parameters

Parameter	Required	Description
addRecordLocationsDirectly	Yes	Must be true. Activates this flow.
brandId	No	Brand identifier for the target provider. Required together with portalId and endpointId to pre-select a specific provider. If omitted, the patient searches manually.
portalId	No	Portal identifier for the target provider. Required together with brandId and endpointId.
endpointId	No	Endpoint identifier for the target provider. Required together with brandId and portalId.

What This Flow Does Not Do

• No TEFCA/RLS scan. The flow does not run a Record Location Scan to discover new locations automatically.
• No refresh of existing locations. Existing record locations are preserved as-is and are not re-fetched or updated.
• No "Use Existing Records" prompt. The patient goes directly to adding a provider.

Obtaining the URL

The generic URL follows a fixed pattern and can be constructed directly (see above).

You can also obtain it without constructing it yourself:

• Admin portal — A copyable generic link is available on the project details page in the admin portal.
• MCP Server — The update_records tool response includes an addRecordLocationUrl field alongside the existing reconnectUrl. The two links serve different purposes: reconnectUrl triggers a full data refresh, while addRecordLocationUrl opens this targeted add-a-provider flow.

To build a specific-provider URL, append brandId, portalId, and endpointId to the generic URL pattern using the identifiers obtained from the Record Location Search or Recommendations APIs.

Using This Flow With First-Time Users

The primary purpose of this flow is to allow an incremental update to an existing patient's record. However, this flow is also supported for first time users, if desired. If you know for certain that a first time user only need to add a single location, and you also know they don't want to use TEFCA/RLS, then you could choose to send them down this experience instead.

Non-OAuth Flow

If you're not using the OAuth flow, then you can use the same links described above. These links will work for both first time users and for data updates.

OAuth Flow

If you're using the OAuth flow, your application can initiate the OAuth Authentication Flow as normal, with one small adjustment: When calling the Authorization Request (/oauth/authorize) API, you will need to include the appropriate query parameters, as described in URL Parameters above, in the Authorization Request, rather than in a patient link as described above. An example request might look like:

https://api.healthex.io/oauth/authorize?response_type=code&...&addRecordLocationsDirectly=true&brandId=<brandId>&portalId=<portalId>&endpointId=<endpointId>

As described above, you can add all 4 of these query parameters or just addRecordLocationsDirectly depending on your use case.

Usage Notes

• This flow is intended as a secondary CTA alongside "Update My Records" — for example, labelled "Add a missing Record Location" in the Records section of your UX, or offered by an AI agent in chat when a patient asks to connect a provider.
• All providers added through this flow appear in the patient's unified health record alongside their existing locations.