Skip to main content

Updating Patient Data

You can request for an updated data for 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 requires additional patient authorization.

How Patient Data Updates Work​

When you request a patient data update, HealthEx will determine whether we can fetch the latest patient data automatically or if additional patient authorization is required. The response will indicate the 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
  • Patient ID: 17d4513f-73e8

Making the API Call​

To update patient data, you would make the following API call:

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

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

Response Format​

If the request is successful, we will respond with a 201 status code and the following elements:

{
    "message": "IN_PROGRESS_NO_ACTION_NEEDED"
}

Response Fields​

  • code - A numeric status code indicating the result of the operation
  • message - A status message that will be one of two values:
    • "IN_PROGRESS_NO_ACTION_NEEDED" - We are able to fetch patient data without any additional authorization. You merely need to wait for the data to be delivered to your S3 bucket.
    • "PATIENT_ACTION_NEEDED" - Authorization is needed by the patient. You must reach out to the patient themselves with the same HealthEx link that was used to get the patient's data originally. The updated data will be delivered whenever the patient goes through the flow again.

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

Study Status Validation​

The API will validate that:

  • The study/project is not currently paused
  • The study 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:

Invalid Organization ID or Project ID​

HTTP 404 - The specified project could not be found or you don't have access to it.

Unknown Patient ID​

HTTP 404 - The patient ID was not found. Note: You will get this error if you try to Update Data on a patient ID that has never been added via Add/Update Patient.

Authorization Errors​

HTTP 403 - Insufficient permissions or unauthorized access.

In most cases, there should be a textual error in the response body to give you a detailed hint on what you did wrong.

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're unsure whether a patient ID exists, consider calling Add/Update Patient first - this is safe to do redundantly