Updating Patient Data

You can request updated data for a specific patient using HealthEx APIs. This endpoint allows data requestors to trigger data updates for individual patients within their accessible projects. The API will indicate whether the update can proceed automatically or if it requires additional patient authorization.

How Patient Data Updates Work

When you request a patient data update, HealthEx determines whether we can fetch the latest patient data automatically or if additional patient authorization is required. The API response will indicate the exact next steps needed to complete the update process.

Identifying a Patient

You will need both the project ID and patient ID to update patient data. These identifiers are typically obtained from other API calls, such as patient listing or recruitment APIs.

Example Values

For this example, we will use the following values:

Project ID: 694d61c2-3f1b-4dc8
Patient ID: 17d4513f-73e8

Making the API Call

Authentication Required

This API requires a valid JWT token. See the Authentication guide for setup instructions.

To trigger a patient data update, make the following API call:

POST https://api.healthex.io/v1/projects/694d61c2-3f1b-4dc8/patients/17d4513f-73e8/$updateData
Accept: application/json
Content-Type: application/json
Authorization: Bearer <your JWT token>

Response Format

If the request is successful, we will respond with an HTTP 200 status and a JSON body. There are two typical response shapes depending on whether patient action is required.

1. When the update proceeds automatically — No patient action needed

{
    "message": "IN_PROGRESS_NO_ACTION_NEEDED",
    "skippedFacilitiesCount": 1,
    "counts": {
        "skippedExistingFacilities": 0,
        "changedExistingFacilities": 1,
        "unchangedExistingFacilities": 0,
        "retrievedNewFacilities": 0,
        "skippedNewFacilities": 1
    },
    "retrievalId": "<retrieval id>",
    "facilities": [
        {
            "locationId": "loc-hospital-123",
            "locationName": "General Hospital",
            "locationLogoUrl": "https://example.com/logo.png",
            "locationSource": "USER_SELECTED",
            "dataRetrievalStatus": "COMPLETE",
            "updatedAt": "2024-01-15T11:30:00.000Z",
            "documentCount": 5
        },
        {
            "locationId": "loc-clinic-456",
            "locationName": "Downtown Clinic",
            "locationLogoUrl": null,
            "locationSource": "USER_SELECTED",
            "dataRetrievalStatus": "AUTHENTICATION_NEEDED_NEW_FACILITY",
            "updatedAt": "2024-01-15T11:45:00.000Z",
            "documentCount": 0
        }
    ]
}

{
    "message": "PATIENT_ACTION_NEEDED",
    "patientActionNeededReason": "AUTHENTICATION_EXPIRED",
    "skippedFacilitiesCount": 0,
    "counts": {
        "skippedExistingFacilities": 0,
        "changedExistingFacilities": 0,
        "unchangedExistingFacilities": 0,
        "retrievedNewFacilities": 0,
        "skippedNewFacilities": 0
    },
    "facilities": [
        {
            "locationId": "loc-hospital-123",
            "locationName": "General Hospital",
            "locationLogoUrl": "https://example.com/logo.png",
            "locationSource": "USER_SELECTED",
            "dataRetrievalStatus": "AUTHENTICATION_EXPIRED",
            "updatedAt": "2024-01-15T11:30:00.000Z",
            "documentCount": 5
        },
        {
            "locationId": "loc-clinic-789",
            "locationName": "Uptown Clinic",
            "locationLogoUrl": null,
            "locationSource": "USER_SELECTED",
            "dataRetrievalStatus": "COMPLETE",
            "updatedAt": "2024-01-15T10:00:00.000Z",
            "documentCount": 2
        }
    ]
}

Response Fields

Click the arrows (▶) below to expand field details.

Field	Type	Description
`message`	`string`	Status indicating if patient action is required • `"IN_PROGRESS_NO_ACTION_NEEDED"`: We can fetch patient data without additional authorization. Data will be delivered to your S3 bucket or SFTP server. • `"PATIENT_ACTION_NEEDED"`: Authorization is needed. Reach out to the patient with the same HealthEx link originally used.
`patientActionNeededReason`	`string`	When `message` is `"PATIENT_ACTION_NEEDED"`, this indicates why the patient must act. (See the OpenAPI enum `PatientActionNeededReason`).
`skippedFacilitiesCount`	`integer`	Total number of facilities skipped for this update. (Equal to `counts.skippedExistingFacilities` + `counts.skippedNewFacilities`). May include facilities with expired/revoked authorization or new facilities requiring fresh authorization.
`counts`	`object`	Metrics for this retrieval • `skippedExistingFacilities`: Existing facilities that were skipped (e.g., due to an unretrievable status). • `changedExistingFacilities`: Existing facilities where an updated set of records was fetched. • `unchangedExistingFacilities`: Existing facilities that returned the exact same document set as the previous retrieval. • `retrievedNewFacilities`: New facilities for which documents were successfully fetched. • `skippedNewFacilities`: New facilities for which documents could not be fetched (likely because new authorization is needed).
`retrievalId`	`string`	Unique identifier for the data retrieval that was started. Present only when `message` is `"IN_PROGRESS_NO_ACTION_NEEDED"`. This ID is available as a path parameter and a manifest field upon delivery.
`facilities`	`array`	Per-facility retrieval status (optional) Shares the exact shape as the patient flow progress API `locations` entries. • On `"IN_PROGRESS_NO_ACTION_NEEDED"`: Reflects facility status before non-interactive flows downgrade locations that need auth to a skipped status. • On `"PATIENT_ACTION_NEEDED"` (due to token refresh failure): Describes the prior retrieval batch. `documentCount` and `updatedAt` reflect that prior batch. Facilities that failed refresh are marked `AUTHENTICATION_EXPIRED`.

Authorization Requirements

This endpoint requires:

User Type: External Researcher
API Client Type: External Researcher API Client
Project Access: You must have access to the specified project
Organization Access: You must be authorized for the patient's organization

Project Status Validation

The API will validate that:

The project is not currently paused.
The project is in an active status that allows patient data updates.

If these conditions are not met, the API will return an appropriate error response.

Error Responses

We may return errors in the following scenarios. In most cases, there will be a textual error in the response body giving you a detailed hint about what went wrong.

Response Code	Reason
403 Forbidden	Insufficient permissions or unauthorized access.
404 Not Found	Project not found, insufficient access, or patient ID not found.

Usage Notes

This endpoint is specifically designed for data requestors managing patient data within their authorized projects.
When the response indicates "IN_PROGRESS_NO_ACTION_NEEDED", simply wait for the updated data to appear in your S3 bucket or SFTP server.
When the response indicates "PATIENT_ACTION_NEEDED", you must contact the patient and direct them to use the same HealthEx link they used previously.
If you are unsure whether a patient ID exists, consider calling the Add/Update Patient API first. This is safe to do redundantly.
404 errors: You will receive a 404 if you attempt to update data for a patient ID that was never added via the Add/Update Patient API. Use the Add/Update Patient API first to ensure the patient exists.

How Patient Data Updates Work​

Identifying a Patient​

Example Values​

Making the API Call​

Response Format​

1. When the update proceeds automatically — No patient action needed​

2. When the patient must take action — Consent, authentication, etc. required​

Response Fields​

Authorization Requirements​

Project Status Validation​

Error Responses​

Usage Notes​