API Retrieval Guidance
Patient360 provides multiple API patterns for retrieving external clinical records, depending on workflow requirements, response expectations, and delivery models. Retrieval is asynchronous and returns a FHIR Bundle once aggregation, normalization, and deduplication are complete. Results are delivered through webhook callbacks or retrieved via polling.
Retrieval supports configurable options for scope, filtering, document handling, and follow-up retrieval based on workflow needs.
Retrieval Workflow
Retrieval follows a standard asynchronous pattern using the $p360-retrieve operation:
- Submit a retrieval request with
$p360-retrieve - Patient identity is validated through the MPI
- Record discovery and document retrieval occur across connected networks
- Data is normalized, deduplicated, and mapped to FHIR R4
- A FHIR Bundle is generated
- Results are returned through webhook callback or retrieved via polling
Retrieval does not return records inline or as part of the synchronous request.
Retrieval API Methods
Different retrieval models are supported through distinct API patterns.
| API Method | Purpose | Returns | Retrieval Alignment |
|---|---|---|---|
$p360-retrieve | Retrieve a full longitudinal record | Normalized FHIR Bundle + documents | Standard |
$everything | Retrieve source-system clinical content | Native C-CDA or partial normalized Bundle | National Network + EHR Reads |
FHIR Read APIs (GET Patient/{id}) | Retrieve individual resources | Single FHIR resource | Standard + Network |
DocumentReference queries | Retrieve metadata and document links | DocumentReference + binary pointer | Standard + Network + Federated |
Subscriptions | Receive notifications of newly available records | Event payload | Event-Driven |
Retrieval Behavior Across Models
Retrieval behavior varies based on data origin and response workflow.
| Attribute | Standard | National Network | Federated | Event-Driven |
|---|---|---|---|---|
| Normalization | Yes | Partial > Full | No | When applicable |
| Viewer visibility | Yes | Yes | No | Optional |
| Stored in Health Gorilla | Yes | Yes | No | Optional |
| Response timing | Sync + async | Sync + async | Sync relay | Async |
| Returned format | FHIR R4 + C-CDA | C-CDA + normalized FHIR | Source format | Notification payload |
Request Patterns
Example: Full Record Retrieval
POST /Patient/$p360-retrieve
Content-Type: application/json
{
"patient": "12345",
"includeDocuments": true
}
Example: Network Source Documents
GET /Patient/12345/$everything
Example: Retrieve by Document Type
GET /DocumentReference?patient=12345&code=18842-5
Example: Subscribe to Event Updates
POST /Subscription
Choosing the Appropriate Retrieval Method
| Objective | Recommended Approach |
|---|---|
| Full longitudinal record | $p360-retrieve |
| Targeted retrieval or specific document categories | DocumentReference + FHIR Reads |
| Direct source-content retrieval from networks | $everything |
| Continuous monitoring and incremental updates | Subscriptions |
Integration Considerations
Successful retrieval depends on identity matching and routing behavior shared across all models. Retrieval performance and completeness may vary by network source.
Key considerations across retrieval models:
- Requires MPI identity resolution
- May require Record Locator Service participation
- Response timing varies (network latency, document size, endpoint performance)
- Follow-up retrieval may be required depending on delivery method and resource completeness
Summary
Retrieval APIs provide flexible methods to access clinical documents and patient records across internal repositories, national exchange networks, private exchange models, and event-driven workflows. Selecting the appropriate method ensures alignment with workflow objectives, performance needs, and data completeness requirements.