Getting Patient Flow Progress

This endpoint provides comprehensive information about the patient's progress through consent and data retrieval flows. This API is useful in two cases:

• For users who are currently in the process of completing the flow, this allows you to see how far they've gotten, and what healthcare locations, if any, are in the process of being retrieved. This can be used to "check in" on a user's progress after you've sent them over to HealthEx, or can be used to detect users who abandoned the flow, so that you can send your own nudges.
• For users who have completed the flow, this allows you to see all of the locations that they retrieved data from, as well as locations they skipped. This can be useful to display a summary to your user of what data they got in your own application.

How Patient Flow Status Works

When a patient starts the HealthEx data retrieval flow for the first time, the first thing they will need to do is consent to sharing their data. This API allows you to detect users who have not completed this step yet.

After a patient consents to share their health data, HealthEx initiates a data retrieval process that may fetch records from multiple healthcare locations. This API allows you to monitor the progress of that retrieval, what locations are or were being retrieved, and see the vectorization status (which indicates whether the data is completely ready for AI-powered queries).

Authentication

This endpoint accepts either a valid Patient Token, usually issued by HealthEx's OAuth flow, or an organization API token, which is generated from an API Key and Secret.

Note that if you wish to monitor the status of an in-progress retrieval, an OAuth flow will not yet have completed, meaning a Patient Token will not be available. For this use case, you will almost always want to use an API token.

See the Authentication guide for more information on obtaining tokens.

Example Values

For this example, we will use the following values:

• Project ID: 694d61c2-3f1b-4dc8
• Patient External ID: 9832cdf-73e8

Making the API Call

To get the patient flow progress:

GET https://api.healthex.io/v1/projects/694d61c2-3f1b-4dc8/patient-flow-progress?externalId=9832cdf-73e8
Accept: application/json
Authorization: Bearer <JWT token>

This API requires you to pass a patient or API JWT token to authenticate. See the Authentication guide for more info.

Response Format

If the request is successful, we will respond with a 200 status code. The response body will look something like this:

{
    "consentStatus": "CONSENTED",
    "retrieval": {
        "patientId": "17d4513f-73e8-4b2a-9c1d-5e6f7a8b9c0d",
        "retrievalId": "batch-abc123-def456",
        "dataRetrievalStatus": "IN_PROGRESS",
        "vectorizationStatus": "IN_PROGRESS",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T11:45:00.000Z",
        "locations": [
            {
                "locationId": "loc-hospital-123",
                "locationName": "General Hospital",
                "locationLogoUrl": "https://example.com/logo.png",
                "locationSource": "TEFCA_DOCUMENT",
                "dataRetrievalStatus": "COMPLETE",
                "updatedAt": "2024-01-15T11:30:00.000Z",
                "documentCount": 5
            },
            {
                "locationId": "loc-clinic-456",
                "locationName": "Downtown Clinic",
                "locationLogoUrl": null,
                "locationSource": "USER_SELECTED",
                "dataRetrievalStatus": "IN_PROGRESS",
                "updatedAt": "2024-01-15T11:45:00.000Z",
                "documentCount": 0
            }
        ]
    }
}

Response Fields

Field	Description
consentStatus	Patient consent state. Allowed values: CONSENTED, NOT_CONSENTED.
retrieval	Details of the patient's most recent retrieval. Returns null if consentStatus is NOT_CONSENTED.

Retrieval Object (retrieval)

Field	Description
patientId	Unique identifier for the patient.
retrievalId	Unique identifier for this retrieval batch.
dataRetrievalStatus	Overall retrieval status. See Overall Data Retrieval Status Values.
vectorizationStatus	AI query vectorization status. See Vectorization Status Values.
createdAt	ISO 8601 timestamp when retrieval was initiated.
updatedAt	ISO 8601 timestamp of most recent update across all locations. null if never updated.
locations	List of location-specific retrieval statuses. See Location Object.

Location Object (locations[])

Field	Description
locationId	Unique identifier for the healthcare location.
locationName	Human-readable name of the location.
locationLogoUrl	URL to the location's logo image.
locationSource	How the location was discovered. See Location Source Values.
dataRetrievalStatus	Retrieval status for this specific location. See Location Data Retrieval Status Values.
updatedAt	ISO 8601 timestamp of last update for this location.
documentCount	Number of documents retrieved from this location.

Overall Data Retrieval Status Values

Value	Description
IN_PROGRESS	Retrieval is currently active and processing.
COMPLETE	Retrieval is finalized (excludes vectorization).

Location Data Retrieval Status Values

Value	Description
NOT_STARTED	Retrieval has not yet begun.
AUTHENTICATION_EXPIRED	Connection expired; patient must re-authenticate.
AUTHENTICATION_NEEDED_NEW_FACILITY	Facility added since last retrieval; requires patient authentication.
IN_PROGRESS	Data is currently being retrieved from this facility.
COMPLETE	Data retrieval completed successfully.
PARTIAL_COMPLETE	Some documents were retrieved, but issues occurred.
SKIPPED	Location skipped (e.g., patient opted out).
ERROR	An error occurred during retrieval.

Location Source Values

Value	Description
TEFCA_DOCUMENT	Discovered through a TEFCA document query.
TEFCA_ENDPOINT	Discovered through a TEFCA endpoint query.
USER_SELECTED	Manually selected by the patient.

Vectorization Status Values

Value	Description
IN_PROGRESS	Data is being prepared for AI queries (queued, waiting, or processing).
COMPLETE	Vectorization complete; ready for AI-powered queries.
FAILED	Vectorization encountered an error.

Error Responses

Response Code	Reason
400 Bad Request	Input validation error (e.g., missing required parameter).
401 Unauthorized	Authentication token is missing, invalid, or expired.
403 Forbidden	Insufficient permissions in the specific project.
404 Not Found	The specified project does not exist.

Usage Notes

• This endpoint only returns the most recent data retrieval batch for the patient. This could be an in-progress (incomplete) retrieval. If you want the most recent completed retrieval, pass the completedRetrievalsOnly=true query param.
• You can pass either referenceId or externalId as query parameters to identify the patient, depending on what ID you have available. For a patient added by link, you will likely not yet know the reference ID, so you will likely want to use an external ID here.
• The updatedAt timestamp reflects the latest update across all locations and vectorization processing
• When dataRetrievalStatus is COMPLETE, the patient's data has been ingested into HealthEx and is ready for querying. This includes for AI-powered queries by the MCP server with the exception of the search tool. If you need to wait for this tool to be ready, you should wait for vectorizationStatus to be COMPLETE.

See Also

• Authentication: Learn how to set up API credentials and manage tokens
• Accessing Patient Data: Understand how to access patient data once retrieval is complete
• HealthEx MCP Server: Use the MCP server for AI-powered queries once vectorization is complete