Batch

The Batch operation allows you to send a group of FHIR resources as a single request. Each resource is wrapped inside an entry within a bundle of the batch type. While these may be thought of as records, the technical structure includes entries that contain the actual resources. Each resource is processed independently, and the response is returned in an aggregated batch-response bundle.

1. Submit the Batch

Pack all records (entries containing FHIR resources) into a batch bundle and send a POST request to the Bundle endpoint.

Tip

To help you identify and track individual records within a batch request and response, add a fullUrl field to each entry in the request Bundle.

The value must be a unique URN-style UUID (e.g., _urn:uuid:UUIDV4_) to act as a stable reference, which also appears in the corresponding entry in the batch-response Bundle. This allows you to match requests to their results.

For example:
"entry": [
  {
    "fullUrl": "urn:uuid:7f9724ed-ef8d-4434-aacb-41869db83233",
    "resource": {
      ...
    }
  }
]

Each entry in the batch is processed independently, but the response is aggregated in a batch-response bundle.

For Observation resources, the related DiagnosticReport resources are automatically created, and individual observations are grouped by the observation date.

The response includes a reference to the batch-response bundle, which is available for 10 minutes. If the Create operation is not supported for a resource, the corresponding entry in the batch-response indicates an "operation not supported" error.

If creating all resources in the batch is expected to take longer than a minute, you should perform the request asynchronously.

Example Request
{
   "resourceType": "Bundle",
   "id": "batch",
   "type": "batch",
   "entry": [
      {
         "fullUrl": "urn:uuid:7f9724ed-ef8d-4434-aacb-41869db83233",
         "resource": {
            "resourceType": "Observation",
            "status": "final",
            "category": [{
               "coding": [
                  {
                     "code": "laboratory",
                     "system": "http://terminology.hl7.org/CodeSystem/observation-category"
                  }
               ],
               "text": "Laboratory"
            }],
            "code": {
               "coding": [
                  {
                     "code": "3043-7",
                     "system": "http://loinc.org"
                  }
               ],
               "text": "Triglycerides"
            },
            "issued": "2017-03-18T00:00:00Z",
            "referenceRange": [
               {
                  "high": {
                     "code": "mg/dL",
                     "system": "http://unitsofmeasure.org",
                     "unit": "mg/dL",
                     "value": 250
                  },
                  "low": {
                     "code": "mg/dL",
                     "system": "http://unitsofmeasure.org",
                     "unit": "mg/dL",
                     "value": 10
                  },
                  "text": "10 to 250 mg/dL"
               }
            ],
            "valueQuantity": {
               "code": "mg/dL",
               "system": "http://unitsofmeasure.org",
               "unit": "mg/dL",
               "value": 93
            },
            "subject": {
               "display": "James Ellroy"
            }
         }
      },
      {
         "fullUrl": "urn:uuid:d5d0848a-6610-4053-8663-42a8c9423a13",
         "resource": {
            "resourceType": "Observation",
            "status": "final",
            "category": [{
               "coding": [
                  {
                     "code": "laboratory",
                     "system": "http://terminology.hl7.org/CodeSystem/observation-category"
                  }
               ],
               "text": "Laboratory"
            }],
            "code": {
               "coding": [
                  {
                     "code": "3043-8",
                     "system": "http://loinc.org"
                  }
               ],
               "text": "Triglycerides - plasma"
            },
            "issued": "2017-03-18T00:00:00Z",
            "referenceRange": [
               {
                  "high": {
                     "code": "mg/dL",
                     "system": "http://unitsofmeasure.org",
                     "unit": "mg/dL",
                     "value": 250
                  },
                  "low": {
                     "code": "mg/dL",
                     "system": "http://unitsofmeasure.org",
                     "unit": "mg/dL",
                     "value": 10
                  },
                  "text": "10 to 250 mg/dL"
               }
            ],
            "valueQuantity": {
               "code": "mg/dL",
               "system": "http://unitsofmeasure.org",
               "unit": "mg/dL",
               "value": 25
            },
            "subject": {
               "display": "James Ellroy"
            }
         }
      }
   ]
}

Example Response (HTTP 201)
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Location: /fhir/R4/Bundle/7007aba0-4b2c-4ded-87e1-bbbf956675cb
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796
Content-Length: 0
Date: Tue, 6 Feb 2020 14:33:16 GMT

To retrieve the operation results, use the Location header value (e.g., fhir/R4/Bundle/7007aba0-4b2c-4ded-87e1-bbbf956675cb).

2. Read Operation Results

To check the outcome of the batch operation, send a GET request to the batch-response bundle URL provided in the Location header.

Example Request
GET /fhir/R4/Bundle/7007aba0-4b2c-4ded-87e1-bbbf956675cb HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787

Example Response (HTTP 200)
{
    "resourceType": "Bundle",
    "type": "batch-response",
    "entry": [
        {
            "fullUrl": "urn:uuid:7f9724ed-ef8d-4434-aacb-41869db83233",
            "response": {
                "status": "201 Created",
                "location": "/fhir/R4/Observation/4b87e05eb81b1461891a49cd-grp-7f9724ed-ef8d-4434-aacb-41869db83233",
                "etag": "1591773003694",
                "lastModified": "2020-06-10T10:10:03.694+03:00"
            }
        },
        {
            "fullUrl": "urn:uuid:d5d0848a-6610-4053-8663-42a8c9423a13",
            "response": {
                "status": "201 Created",
                "location": "/fhir/R4/Observation/4b87e05eb81b1461891a49cd-grp-d5d0848a-6610-4053-8663-42a8c9423a13",
                "etag": "1591773003694",
                "lastModified": "2020-06-10T10:10:03.694+03:00"
            }
        },
        {
            "fullUrl": "urn:uuid:046751b9-210c-4bbf-a914-ec742fd71fc5",
            "response": {
                "extension": [
                    {
                        "url": "http://hl7.org/fhir/StructureDefinition/http-response-header",
                        "extension": [
                            {
                                "url": "Existing-Resource-Id",
                                "valueString": "462bde5e608913edccadbbe0"
                            }
                        ]
                    }
                ],
                "status": "422",
                "outcome": {
                    "resourceType": "OperationOutcome",
                    "issue": [
                        {
                            "severity": "error",
                            "code": "duplicate",
                            "details": {
                                "text": "The supplied record duplicates the existing one."
                            },
                            "diagnostics": "Failed to create duplicate."
                        }
                    ]
                }
            }
        }
    ]
}

Key Notes

Batch Duration: The batch-response bundle is available for 10 minutes after creation.
Error Handling: If an operation in the batch fails, the corresponding entry will include an error message, such as "operation not supported" or a duplicate error.

Related Information

Refer to the Bundle resource documentation for overall structure and rules.