Skip to main content

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
  • Patient External ID: 9832cdf-73e8

Making the API Call​

To get the patient flow progress:

GET https://api.healthex.io/v1/projects/694d61c2-3f1b/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​

  • consentStatus: Either CONSENTED or NOT_CONSENTED depending on whether the user has consented
  • retrieval: An object containing details of the patient's most recent retrieval (which could be in-progress). Note this will be null if the patient has not consented.

Retrieval Fields​

  • patientId: The patient's unique identifier
  • retrievalId: Unique identifier for this retrieval batch
  • dataRetrievalStatus: Overall status of the data retrieval (see values below)
  • vectorizationStatus: Status of data vectorization for AI queries (see values below)
  • createdAt: ISO 8601 timestamp of when the retrieval was initiated
  • updatedAt: ISO 8601 timestamp of the most recent update across all locations and vectorization (null if never updated)
  • locations: Array of location-specific retrieval statuses

Location Fields​

Each location in the locations array contains:

  • locationId: Unique identifier for the healthcare location
  • locationName: Human-readable name of the location (may be null)
  • locationLogoUrl: URL to the location's logo image (may be null)
  • locationSource: How this location was discovered (see values below)
  • dataRetrievalStatus: Retrieval status for this specific location
  • updatedAt: ISO 8601 timestamp of the last update for this location (may be null)
  • documentCount: Number of documents retrieved from this location

Overall Data Retrieval Status Values​

The overall dataRetrievalStatus field indicates the status of the current retrieval:

  • IN_PROGRESS: The retrieval is still active and not yet finalized
  • COMPLETE: The retrieval has been finalized, meaning all processing is complete, excluding vectorization

Location Data Retrieval Status Values​

Each location's dataRetrievalStatus field indicates the retrieval progress for that specific healthcare location:

  • NOT_STARTED: Retrieval has not begun for this location
  • AUTHENTICATION_EXPIRED: The patient previously connected to this location, but the connection must be re-established (for example, refresh tokens expired)
  • AUTHENTICATION_NEEDED_NEW_FACILITY: This location was added since the last retrieval and requires patient authentication before data can be fetched
  • IN_PROGRESS: Data is currently being retrieved from this location
  • COMPLETE: Data retrieval completed successfully for this location
  • PARTIAL_COMPLETE: Some documents were retrieved, but the process encountered issues
  • SKIPPED: This location was skipped (e.g., patient opted out)
  • ERROR: An error occurred during retrieval from this location

Location Source Values​

The locationSource field indicates how the healthcare location was discovered:

  • 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​

The vectorizationStatus field indicates whether the retrieved data has been processed for AI-powered queries:

  • IN_PROGRESS: Data is being prepared for AI queries (includes queued, waiting, and actively processing states)
  • COMPLETE: Vectorization completed successfully - data is ready for AI-powered queries
  • FAILED: Vectorization encountered an error

Error Responses​

We may return errors in the following scenarios:

Not Found​

HTTP 404 - The specified project does not exist.

Unauthorized​

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

Forbidden​

HTTP 403 - The token does not have permission to access this endpoint. The token might be for the wrong patient or the wrong organization.

Bad Request​

HTTP 400 - Input validation error, such as not providing a required parameter.

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​