---
title: Standardized API for Patient and Population Services
description: "# **Standardized API for Patient and Population Services** ## **Overview** LegendEHR provides standardized **FHIR-based RESTful APIs** to enable third-party applications and authorized users to securely access and exchange **Electronic Health Information (EHI)**. The implementation uses **AWS HealthLake** as the backend…"
url: "https://legendehr.com/docs/standardized-api-for-patient-and-population-services/"
updated: "2025-10-20"
category: LegendEHR
---

# Standardized API for Patient and Population Services

# **Standardized API for Patient and Population Services**

## **Overview**

LegendEHR provides standardized **FHIR-based RESTful APIs** to enable third-party applications and authorized users to securely access and exchange **Electronic Health Information (EHI)**.
  The implementation uses **AWS HealthLake** as the backend FHIR datastore, conforming to **HL7® FHIR® Release 4 (R4)** and **SMART on FHIR** standards for interoperability, authorization, and data security.

All API interactions occur via **HTTPS (TLS 1.2 or higher)** and use **OAuth 2.0** authorization managed through **AWS Cognito**.

## **1. API Syntax**

All API requests follow the RESTful pattern defined by HL7 FHIR:

[resourceType]/[id]?[parameters]

**Base URL (FHIR endpoint):**

https://healthlake.us-east-1.amazonaws.com/.healthlake.amazonaws.com/datastore/8d8ae0ebc52744d8d9c6af8009bef7e6/r4

 

**Example:**

https://healthlake.us-east-1.amazonaws.com/.healthlake.amazonaws.com/datastore/8d8ae0ebc52744d8d9c6af8009bef7e6/r4/Patient?name=John

## **2. Supported FHIR Resource Endpoints**

| **Function Name** | **HTTP Method** | **Description** |
| --- | --- | --- |
| /Patient | GET | Retrieve a list of patients or search by parameters |
| /Patient/{id} | GET | Retrieve a specific patient resource |
| /Observation | GET | Retrieve laboratory results, vitals, or clinical observations |
| /Condition | GET | Retrieve problem/diagnosis lists |
| /Encounter | GET | Retrieve clinical encounter or visit records |
| /MedicationRequest | GET | Retrieve medication prescription records |
| /Appointment | GET | Retrieve patient appointment data |
| /$export | POST | Initiate population-level export (FHIR Bulk Data Access) |

## **3. Required and Optional Parameters**

| **Parameter** | **Required** | **Type** | **Description** |
| --- | --- | --- | --- |
| id | Yes (for specific resource requests) | String | Unique FHIR resource ID |
| _count | No | Integer | Limit the number of results per page |
| _since | No | DateTime | Retrieve data updated since a given date |
| patient | No | String | Filter results for a specific patient |
| category | No | String | Filter observations by category |
| status | No | String | Filter conditions or encounters by status |

All parameters follow **FHIR R4 REST API conventions**.

 

## **4. Response Format**

All responses are returned as **FHIR JSON** resources.
  Each resource includes a resourceType attribute and conforms to HL7 FHIR R4 schema.

**Example – GET /Patient/{id}:**

{

  "resourceType": "Patient",

  "id": "12345",

  "name": [{ "given": ["John"], "family": "Doe" }],

  "gender": "male",

  "birthDate": "1980-05-15"

}

 

**Example – GET /Observation:**

{

  "resourceType": "Observation",

  "id": "obs001",

  "status": "final",

  "code": { "text": "Heart rate" },

  "valueQuantity": { "value": 72, "unit": "beats/minute" }

}

## **5. Exceptions and Error Handling**

The API follows FHIR standard **OperationOutcome** responses for errors.

| **HTTP Status** | **Meaning** | **Response Behavior** |
| --- | --- | --- |
| 400 | Bad Request | Invalid or missing parameters |
| 401 | Unauthorized | Token missing or invalid |
| 403 | Forbidden | User lacks access rights |
| 404 | Not Found | Resource unavailable |
| 500 | Server Error | Internal system error |

**Example Error Response:**

{

  "resourceType": "OperationOutcome",

  "issue": [

    {

      "severity": "error",

      "code": "invalid",

      "diagnostics": "Invalid query parameter value."

    }

  ]

}

## **6. Software Components and Configuration Requirements**

To successfully connect and process responses, client applications must support:

- **FHIR R4 JSON serialization**
- **HTTP/HTTPS REST operations** (GET, POST, PUT, DELETE)
- **OAuth 2.0 authorization (SMART on FHIR profile)**
- **TLS 1.2 or higher**

**Mandatory configurations:**

- Application registered with the **AWS Cognito Authorization Server**

Authorization header with Bearer token:

  Authorization: Bearer <access_token>

 

## **7. Application Registration Process**

Third-party applications must register with the LegendEHR authorization server to obtain access tokens.

**Required Registration Information:**

- Client ID
- Client Secret
- Redirect URI
- Client Type (Public / Confidential)
- Requested Scopes (launch, openid, profile, patient/*.read, user/*.read)
- Grant Type: authorization_code or client_credentials

### **Authorization Server Details**

**Authorization Server URL:**

https://healthlakeoauth.auth.us-east-1.amazoncognito.com

 

**SMART on FHIR Discovery Endpoints:**

- https://healthlake.us-east-1.amazonaws.com/datastore/8d8ae0ebc52744d8d9c6af8009bef7e6/r4/.well-known/smart-configuration
- https://healthlake.us-east-1.amazonaws.com/datastore/8d8ae0ebc52744d8d9c6af8009bef7e6/r4/metadata

These endpoints define the supported scopes, grant types, and capabilities required for ONC §170.315(g)(10) compliance.

## **8. Security and TLS Enforcement**

All API connections are **encrypted using TLS 1.2 or higher**.
  The LegendEHR API does **not** permit or support any connections below TLS 1.2.
  This enforcement aligns with **NIST SP 800-52 Rev. 2** and **ONC Health IT Certification** standards.

No additional documentation is required for lower TLS versions as they are not supported or implemented.

## **9. Bulk Data and Population-Level Access**

The API supports the **FHIR Bulk Data Access ("Flat FHIR")** specification for population-level exports.

**Endpoint:**

POST [baseURL]/$export

 

**Supported Parameters:**

- _type – Specify resource types to export
- _since – Export data updated since a given timestamp
- _outputFormat – Defaults to application/fhir+ndjson

**Example Request:**

POST https://<your-base-url>/$export

Authorization: Bearer <access_token>

Accept: application/fhir+json

 

## **10. Developer Support and Access Policy**

LegendEHR provides open, standardized API documentation to promote interoperability and innovation.
  This documentation and endpoints are **publicly accessible** for developers, implementers, and ONC certification testers.

Developers can:

- Access the documentation at any time without preconditions
- Create an account (if required) through an **automatically approved registration process**
- Obtain test credentials via the developer portal to connect and validate API access

**Developer Contact:** support@legendehr.com