Scheduling Future Orders

Overview

The Health Gorilla Lab Network allows you to schedule future orders by using an extension to the RequestGroup FHIR Resource. The orders are created inside Health Gorilla and sent to labs at the scheduled times specified in the request payload.

Creating the RequestGroup-timing Extension

You can use the following attributes to schedule future orders.

Attribute NameDescription
eventDescribes a specific date or dates for the order
repeat.countSets the number of times the order will repeat
repeat.frequencyDescribes how many times the order will be submitted per period. (Should always = 1)
repeat.periodDescribes the period of time between orders.
repeat.periodUnitDescribes the units of measure for the time periods (mo = month, wk = week, d = day)

The complete extension is then included inside the RequestGroup.extension field in the RequestGroup request payload.

You can use the above attributes to create custom scheduling. The table below describes examples of common scheduling periods.

Intervalrepeat.frequencyrepeat.periodrepeat.periodUnit
daily11d
everyOtherDay12d
everyThirdDay13d
weekly11wk
monthly11mo
quarterly13mo
semiannual16mo

Extension examples

One order scheduled for a single day

{
			"url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-timing",
			"valueTiming": {
				"event": [
					"2023-01-28"
				]
			}
		}

Multiple orders scheduled for specific future dates

{
			"url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-timing",
			"valueTiming": {
				"event": [
					"2023-01-28","2023-02-29","2023-03-30"
				]
			}
		}

Order submitted every 3rd day starting on 2022-12-14, repeated 5 times

{
			"url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-timing",
			"valueTiming": {
				"event": ["2022-12-14"],
				"repeat": {
						"count": 5,
						"frequency": 1,
						"period": 3,
						"periodUnit": "d"
			}
		}
}

Order submitted weekly starting on 2022-12-10, repeated 5 times

{
			"url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-timing",
			"valueTiming": {
				"event": ["2022-12-10"],
				"repeat": {
						"count": 5,
						"frequency": 1,
						"period": 1,
						"periodUnit": "wk"
			}
		}
}

Order submitted every other day starting on 2022-12-14, repeated 15 times

{
			"url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-timing",
			"valueTiming": {
				"event": ["2022-12-14"],
				"repeat": {
						"count": 15,
						"frequency": 1,
						"period": 2,
						"periodUnit": "d"
			}
		}
}

Full order example

Order submitted every 6 months, repeated 3 times

{
    "resourceType": "RequestGroup",
    "meta": {
        "profile": [
            "https://healthgorilla.com/fhir/StructureDefinition/hg-order"
        ]
    },
    "contained": [
        {
            "resourceType": "Account",
            "id": "1",
            "meta": {
                "profile": [
                    "https://healthgorilla.com/fhir/StructureDefinition/hg-order-account"
                ]
            },
            "type": {
                "coding": [
                    {
                        "system": "https://www.healthgorilla.com/order-billto",
                        "code": "patient",
                        "display": "Patient"
                    }
                ],
                "text": "Patient"
            },
            "guarantor": [
                {
                    "party": {
                        "reference": "Patient/<PATIENT ID>",
                        "display": "John Doe"
                    }
                }
            ]
        },
    {
      "resourceType": "Practitioner",
      "id": "2",
      "meta": {
        "profile": [
          "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner"
        ]
      },
      "identifier": [
        {
          "system": "https://www.healthgorilla.com",
          "value": "<PRACTITIONER FHIR ID>"
        },
        {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                "code": "PRN",
                "display": "Passport number"
              }
            ],
            "text": "Passport number"
          },
          "system": "http://hl7.org/fhir/sid/us-npi",
          "value": "<PROVIDER NPI>"
        },
        {
            "type": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                        "code": "AN",
                        "display": "Account number"
                    }
                ],
                "text": "Account Number"
            },
            "value": "<LAB ACCOUNT NUMBER>"
        }
      ],
      "name": [
        {
          "use": "official",
          "text": "<PROVIDER FULL NAME>",
          "family": "<PROVIDER LAST NAME>",
          "given": [
            "<PROVIDER FIRST NAME>"
          ]
        }
      ]
    },
        {
            "resourceType": "Organization",
            "id": "organization",
            "identifier": [
                {
                    "system": "https://www.healthgorilla.com",
                    "value": "t-<TENANT ID>"
                },
                {
                    "type": {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                "code": "AN",
                                "display": "Account number"
                            }
                        ],
                        "text": "Account_number"
                    },
                    "value": "<ORGANIZATION'S LAB NUMBER>"
                }
            ],
            "active": "true"
        },
        [
            {
                "resourceType": "ServiceRequest",
                "id": "labtest0",
                "status": "active",
                "intent": "order",
                "note": "test org",
                "priority": "",
                "category": [
                    {
                        "coding": [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "103693007",
                                "display": "Diagnostic procedure"
                            }
                        ]
                    }
                ],
                "code": {
                    "coding": [
                        {
                            "code": "01013",
                            "display": "Cholesterol"
                        }
                    ],
                    "text": "01013-CHOLESTEROL"
                }
            }
        ]
    ],
    "extension": [
        {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-authorizedBy",
            "valueReference": {
                "reference": "Organization/t-<ORGANIZATION ID>",
                "display": "<ORGANIZATION NAME>"
            }
        },
        {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-account",
            "valueReference": {
                "reference": "#1"
            }
        },
        {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-performer",
            "valueReference": {
                "reference": "Organization/f-<LAB FACILITY ID>",
                "display": "<LAB FACILITY NAME>"
            }
        },
        {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-requester",
            "extension": [
                {
                    "url": "agent",
                    "valueReference": {
                        "reference": "#2"
                    }
                },
                {
                    "url": "onBehalfOf",
                    "valueReference": {
                        "reference": "#3"
                    }
                }
            ]
        },
        {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-deliveryOptions",
            "extension": [
                {
                    "url": "electronic",
                    "valueBoolean": "true"
                }
            ]
        },
        {
			"url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-timing",
			"valueTiming": {
				"event": [
					"2022-12-20"
				],
				"repeat": {
					"count": 3,
					"frequency": 1,
					"period": 6,
					"periodUnit": "mo"
				}
			}
		}
    ],
    "status": "active",
    "intent": "order",
    "subject": {
        "reference": "Patient/<PATIENT ID>",
        "display": "John Doe"
    },
    "note": [
        {
            "text": "test org an"
        }
    ],
    "author": {
        "reference": "Practitioner/<PRACTITIONER ID>"
    },
    "action": [
        {
            "resource": {
                "reference": "#labtest0",
                "display": "005041 Hemoglobin"
            }
        }
    ]
}

Response to POST

If the POST is successful, the RequestGroup API will respond with a payload consisting of a list of IDs for all created orders.

Response Example

{
    "resourceType": "List",
    "identifier": [
        {
            "value": "d1baac6378249e4edb1f6741"
        },
        {
            "value": "d1baac6382fd5d2b02b2f2a1"
        },
        {
            "value": "d1baac638a1a8c0cbec8b129"
        }
    ]
}

Retrieving a Future Order

You can retrieve future orders using a GET request to this RequestGroup endpoint.

Future orders can be identified by the presence of the requestgroup-timing extension. The extension includes the date the future order will automatically be placed by Health Gorilla.

"extension":[
  			{
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-timing",
            "valueTiming": {
                "event": [
                    "2023-01-12T12:00:00+00:00"
                ]
            }
        }
  ]