October 24, 2022 Release: API Change: Update on FHIR R4 Patient APIs to return record restrictions and blocked patients


We have updated read and search FHIR R4 Patient endpoints to allow the return of record restrictions and blocked patients in the API response for 2-legged requests. In addition, we have added new security labels to the metadata of the FHIR R4 Patient resource to indicate whether the record is restricted or blocked. 


athenaCollector, athenaClinicals, athenaClinicals for Hospitals & Health Systems




October 24, 2022


  • N/A

Is this a breaking change

No, this is not a breaking change

Endpoints affected

This change will affect the following endpoints associated with FHIR Patient R4 resource:

  • GET /fhir/r4/Patient/{logicalId}
  • GET /fhir/r4/Patient
  • POST /fhir/r4/Patient/_search

New Endpoints

  • N/A


Refer to the following documentation on FHIR Patient R4 resource and new security labels:

What is changing and Why we’re making the change

Practice users can mark a patient record as “restricted” and/or “blocked” in the Patient QuickView in athenaOne.

Currently, athenaOne patient endpoints (GET /patients/{patientid}, GET /patients/enhancedbestmatch, GET /patients) allow 2-legged API consumers to retrieve restricted and blocked records by passing an “ignorerestrictions” parameter. 

However, FHIR R4 Patient endpoints do not follow this behavior. See below for current state: 

  • For 2-legged requests (existing):
    • Record restriction: return HTTP 404 not found.
    • Blocked patients: return HTTP 200 with redacted patient demographics.
  • For 3-legged requests (existing):
    • Record restriction: return HTTP 404 not found.
    • Blocked patients: return HTTP 200 with unredacted patient demographics.
    • When a patient is both "blocked" and "restricted", the "restricted" behavior is invoked.

As we’re making steps to have feature parity between different API types, we have updated FHIR R4 Patient endpoints when requested through 2-legged OAuth to always return restricted or blocked patient records in the API response.

Patient records are tagged with the following meta.security labels:

  • R - record restriction
  • PDS - blocked patients

Note: A record can be marked as record restriction and blocked, and thus can have both “R” and “PDS” tags.

The behavior for 3-legged requests for FHIR R4 Patient resource remain unchanged.

These updates also allow athenahealth to support CCDA workflows that use certified FHIR R4 APIs and USCDIv1 data set to fulfill 21st Century Cures requirements.

What will current users of the endpoint need to update in their code

Please note this is not a breaking change.

There is no change to how you’re currently making API requests. Moving forward, record restrictions and blocked patients will always be included in the response for 2-legged calls on the FHIR R4 Patient resource.

Since these records are marked by your practice users in athenaOne, please continue following your organization’s/practice’s guidance in handling these records. Depending on your application/system workflow after retrieving patient demographics data from athena, you may need to update your code to properly handle restricted and blocked records (as a reminder, these records will be tagged appropriately in the response).

What will happen if users of the endpoint do not update their code

This is not a breaking change, so nothing will happen if changes are not made.

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others

On this Page