Convert - Combine FHIR Bundles (R4)

POST /convert/v1/combinefhirr4bundles

This operation aggregates multiple FHIR bundles from the same patient (including results from previous Convert API requests) into a single FHIR R4 bundle.

See the Aggregating Patient Data use case for more in-depth discussion of how to use this operation.

Contents

Inputs and Outputs
- Query Parameters
Processing Considerations
Example

Inputs and Outputs

The input is a newline-delimited JSON list of FHIR R4 Bundles for a single patient, with each entry a bundle retrieved from the conversion operations.

Note
The combine bundles operation uses ndjson format, so be sure to set content-type: application/x-ndjson in your request header. Also, be sure each bundle is on its own line, with no newlines interspersed.

The output is a FHIR R4 Bundle containing the data parsed from the input, along with an OperationOutcome resource detailing the results (including warnings or errors) of the conversion process. See Output FHIR R4 Bundles for details.

Query Parameters

patientId string

Optional identifier for the Patient resource. See programming guide for details.

Processing Considerations

The following nuances should be considered when using the Combine Bundles API:

Demographic Reconciliation

When there are conflicts in demographic data, the system will attempt to reconcile the values. For demographics that support multiple values (such as names, addresses, and telephone numbers), the value from the most recent bundle will be used as the current value. Others will be designated as prior values. For demographics that support only a single value, the system will store an ‘unknown’ code (e.g., gender) or blank value (e.g., race) if it cannot resolve the conflict.

De-Duplication

When combining bundles, the system will perform intelligent de-duplication. For example, if two bundles have an identical encounter (with the same source, date, condition, etc.), the combined bundle will only contain a single instance of that encounter. On the other hand, a combined bundle may contain multiple instances of a single condition (e.g., representing a progression of diabetes with different codes or from different sources over time).

Identifier Propagation

Whenever possible, the system maintains continuity of resource identifiers between the inputs and outputs. This allows traceability from the combined FHIR bundle back to the original records.

Embedded Binary Data

If a DiagnosticReport or DocumentReference resource has embedded binary data (based on its presentedForm field), Orchestrate will create a separate Binary resource in the output bundle containing that embedded data.

The Binary resource will have the same ID as the DocumentReference resource from which it is referenced.
The content_type field in the Binary resource contains MIME types, e.g., text/plain, application/pdf, etc.
The data field in the Binary resource contains base64 encoded data which must be decoded to view the contents (even if plain text).

Example

Try It
Try out the operations, with examples, in the Developer Portal Sandbox.

Sample Input

{"resourceType":"Bundle","type":"searchset","entry":[...]}
{"resourceType":"Bundle","type":"searchset","entry":[...]}

FHIR Bundles are verbose, so the output below just shows a small sample to illustrate how the data is structured. For a more complete example, try out the API in the Developer Portal Sandbox, or refer to the FHIR Specification.

Sample Output

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        ... (patient fields)
      }
    },
    {
      "resource": {
        "resourceType": "Encounter",
        ... (encounter fields)
      }
    },
    ...
    {
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          ... (any processing issues)
      }
    }
  ]
}