---
updatedAt: 2026-10-21T19:45:40.000Z
agentTools:
  projectIndex: https://developer.healthgorilla.com/llms.txt
---

# $p360-Retrieval Operation

The `$p360-retrieve` operation initiates the Patient360 Structured Retrieval workflow, retrieving and processing patient data from networks your organization is licensed to access and storing the results in your Health Gorilla tenant.

## Endpoint

```
GET /fhir/R4/DocumentReference/$p360-retrieve?patient={hg_patient_id}
```

### Parameters

| Name        | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| `patient`   | Health Gorilla patient ID (required)                                      |
| `startDate` | Earliest service date of the documents to retrieve, YYYY-MM-DD (optional) |
| `endDate`   | Latest service date of the documents to retrieve, YYYY-MM-DD (optional)   |

The `patient` parameter must reference a valid Health Gorilla patient. Documents are filtered on their service date after they are retrieved, so a date range reduces the documents returned but not the networks queried.

## Patient Requirements

Before initiating retrieval:

* The patient must exist in your tenant
* The request must use a valid Health Gorilla patient ID
* Patient demographics must be sufficiently complete for matching

Required demographics for network queries:

* First name
* Last name
* Date of birth
* Gender
* Address

Incomplete or inaccurate demographics may reduce retrieval results. A request for a patient with no ZIP Code on any address is refused with HTTP 400.

## How to Execute

The `$p360-retrieve` operation must be executed asynchronously.

Required header:

```
Prefer: respond-async
```

### Example Request

```http
GET /fhir/R4/DocumentReference/$p360-retrieve?patient=12345 HTTP/1.1
Host: api.healthgorilla.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Prefer: respond-async
```

### Initial Response

```http
HTTP/1.1 202 Accepted
Location: https://api.healthgorilla.com/fhir/RequestResult/abc123
```

Response details: HTTP status 202 indicates processing has started, Location header provides the RequestResult URL.

## Asynchronous Processing

The operation is asynchronous.

* The initial request starts the workflow
* Processing continues in the background
* Results become available after completion

Processing includes network queries, document retrieval, parsing, normalization, and storage.

## Checking Retrieval Status

Use the RequestResult URL returned in the `Location` header to check progress.

### Example Polling Request

```http
GET /fhir/RequestResult/abc123 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Possible Responses

* **202 Accepted** — Processing is still in progress
* **200 OK** — Retrieval has finished. Check the `failed` and `partial` parameters to learn whether any networks didn't respond
* **4xx** — An error occurred

Polling should be performed using an appropriate retry strategy (for example, exponential backoff).

## Retrieval Outcome

When complete, the response includes summary information about the retrieval.

### Example Response

```
{
  "organizationsTotal": 25,
  "documentsFound": 120,
  "documentsImported": 95,
  "documentsSkipped": 20,
  "documentsFailed": 5
}
```

Field descriptions:

* `organizationsTotal`: Total organizations queried
* `documentsFound`: Total documents identified
* `documentsImported`: Documents successfully stored in your tenant
* `documentsSkipped`: Documents identified as duplicates and not stored
* `documentsFailed`: Documents that could not be retrieved or processed

The response is a bundle whose first entry is a `Parameters` resource with three values that describe the request as a whole:

* `inProgress`: True when retrieval is still running
* `partial`: True when at least one network was unavailable while another returned results. These results may be incomplete, and missing records do not mean the patient has none
* `failed`: True when retrieval finished without any network completing successfully. This is different from a request that found no records

Failures may occur due to:

* Invalid or unsupported document formats
* Errors returned by responding systems
* Retrieval timeouts or network issues

## What This Operation Does

Calling `$p360-retrieve` triggers a multi-stage workflow, allowing your system to interact with structured FHIR data instead of raw documents.

The operation:

* Queries networks your organization is licensed to access
* Identifies available patient records
* Retrieves source documents
* Processes documents through normalization pipelines
* Extracts structured clinical data
* Deduplicates and reconciles overlapping data
* Stores the resulting dataset in your tenant

## Output Model

`$p360-retrieve` does not return the final dataset in the response.

Instead:

* The request initiates processing
* Data is stored in your tenant after processing completes
* Results are accessed through standard FHIR queries

## What Gets Stored

After processing completes, the tenant dataset may include:

* Retrieved source documents
* Structured FHIR resources derived from those documents
* Reconciled patient data across multiple sources

The level of structured data depends on the content and format of source documents.

## Relationship to Other Retrieval Methods

| Capability                | `$p360-search` | `$p360-retrieve`     | HIN Document Query |
| ------------------------- | -------------- | -------------------- | ------------------ |
| Queries external networks | Yes            | Yes                  | Yes                |
| Returns document metadata | Yes            | Included in workflow | Yes                |
| Retrieves documents       | No             | Yes                  | Yes                |
| Normalizes data           | No             | Yes                  | No                 |
| Deduplicates data         | No             | Yes                  | No                 |
| Stores data               | No             | Yes                  | No                 |
| Populates Patient Chart   | No             | Yes                  | No                 |
| Synchronous               | No             | No                   | Yes                |

`$p360-retrieve` replaces older multi-step workflows by combining retrieval and processing into a single operation.

## Retrieval Scope and Variability

Results depend on external systems and are not guaranteed to be complete.

Factors include:

* Data availability at responding organizations
* Patient matching accuracy
* Network participation
* Consent enforcement
* Source data quality

Results may vary between patients and across retrieval attempts.

## Triggering Retrieval

### API-triggered

Call `$p360-retrieve` directly for a patient.

### Workflow-triggered

Retrieval can be initiated automatically through configured workflows, such as HL7 v2 ADT message triggers during patient registration.

## Bulk Retrieval Patterns

Bulk workflows should account for processing time and system limits.

For multiple patients:

1. Create or update patient records
2. Identify patients requiring retrieval
3. Initiate `$p360-retrieve` for each patient
4. Manage asynchronous processing

## Limitations

* The response does not contain the full dataset
* Data depends on external systems and matching quality
* Not all documents produce structured data
* Results may vary across networks and attempts

## Key Takeaways

* `$p360-retrieve` initiates structured data retrieval
* The operation must be executed asynchronously
* Retrieval results are accessed through FHIR after completion
* The workflow retrieves, processes, normalizes, and stores data
* `$p360-retrieve` is required for Patient Chart population