R4 Ballot #1 (Mixed Normative/Trial use) Current Build
This page was published as part of FHIR v3.3.0: R4 Ballot #1 : Mixed Normative/Trial use (First Normative ballot). It has been superceded by R4 . For a full list of available versions, see the Directory of published versions .
FHIR Infrastructure Work Group Maturity Level : 2 Ballot Standards Status : Trial Use Draft

The Implementation Note: the FHIR Asynchronous API and the $export Operation are under active development. development:

All of the interactions defined in the RESTful API are described as synchronous operations - that is, the client makes a query, query and waits for the server to respond with the outcome in the HTTP response. This pattern is not suitable once significant server side processing becomes necessary, necessary or when substantial amounts of data must be returned.

A good example of this is the $everything $export operation , though where simple searches may result in large amounts of data. In order

The asynchronous request pattern, based on rfc 7240 , caters to cater for this use case, an asynchronous request pattern is defined. This pattern case and is applicable for all the defined interactions , Defined Interactions and for Operations , though although for many of these interactions uses it brings no benefit. Servers may choose which interactions the pattern should be supported on (if at all), and servers may choose to only support some of the operations using the asynchronous pattern.


The asynchronous use pattern follows request will have whatever URL and other parameters would normally apply, but must include the pattern defined in rfc 7240 headers described below.

GET [FHIR API Request] .

  • The client initiates the pattern using the Prefer header: (required)

    GET [base]/[request]?_outputFormat=[media-type] Accept: application/fhir+json Prefer: respond-async

    The Specifies whether the response is immediate or asynchronous. Setting this to _outputFormat respond-async format specifies triggers the format in which async pattern.

  • Accept (required)

    Specifies the final return is requested. This may be any format of defined Serialization formats, including the bulk data formats. The accept header describes optional OperationOutcome response to the format in which OperationOutcomes are returned if kick-off request. Any of the request fails. Serialization Format Representations The request will have whatever URL and other parameters would normally apply. Typical requests that are made using the asynchronous pattern are for all data on many patients: supported.

  • GET [fhir base]/Group/[id]/$export

    _outputFormat (string, optional, defaults to application/fhir+ndjson )

    The format for the generated bulk data files. Currently, ndjson must be supported, though servers may choose to also support other output formats. Servers should support the full content type of application/fhir+ndjson as well as abbreviated representations including application/ndjson and ndjson .

  • HTTP Status Code of 202 Accepted
  • Content-Location header with a url for subsequent status requests
  • Optionally an a FHIR OperationOutcome in the body
  • HTTP Status Code of 4XX or 5XX
  • A Optionally a FHIR OperationOutcome in the body

After a bulk data request has been kicked-off, clients can send a delete request to the url provided in the Content-Location header to cancel the request.

DELETE [polling content location]

  • HTTP Status Code of 202 Accepted
  • Optionally a FHIR OperationOutcome in the body
  • HTTP status code of 4XX or 5XX
  • Optionally a FHIR OperationOutcome in the body

After a bulk data request has been kicked-off, clients can poll the url provided in the Content-Location header to obtain the status of the request.

Note: Clients SHOULD should follow an exponential backoff approach when polling for status. Servers may supply a Retry-After header with a http date or a delay time in seconds. When provided, clients should use this information to inform the timing of future polling requests.

GET [content-location] Accept: application/json

Note: The Accept header for this request should be application/json . In the case that errors prevent the export from completing, the response will contain a JSON-encoded FHIR OperationOutcome resource.

GET [polling content location]

  • HTTP Status Code of 202 Accepted
  • Optionally an X-Progress header with a text description of the status of the request that's less than 100 characters. The format of this description is at the server's discretion and may be a percentage complete value or a more general status such as "in progress". Clients can try to parse this value, display it to the user, or log it.
  • Optionally an OperationOutcome in the body
  • HTTP status code of 5XX
  • An Optionally a JSON FHIR OperationOutcome in the body
  • Even if some resources cannot successfully be exported, the overall export operation may still succeed. In this case, the Response.error array of the completion Response must be populated (see below) with one or more files in ndjson format containing OperationOutcome resources to indicate what went wrong.
  • HTTP status of 200 OK

  • Content-Type header of application/json

  • Optionally an Expires header indicating when the files listed will no longer be available available.

  • A body containing a json object providing metadata and links to the generated bulk data files files.

    Required Fields:

  • transactionTime - an a FHIR instant type that indicates the server's time when the query is run. No resources that have a modified data after this instant should be in the response.

  • request - the full url of the original bulk data kick-off request

  • secure requiresAccessToken - boolean value indicating whether downloading the generated files will require an authentication token. Note: This may be false in the case of signed S3 urls or an internal file server within an organization's firewall.

  • output - array of bulk data file items with one entry for each generated file. Note: If no data is returned from the kick-off request, the server should return an empty array.

  • error - array of error file items following the same structure as the output array. Note: If no errors occurred, the server should return an empty array. Note: Only the OperationOutcome resource type is currently supported, so a server will generate ndjson files where each row is an OperationOutcome resource.

    Each file item should contain the following fields:

  • type - the FHIR resource type that is contained in the file. Note: Each file may only contain resources of one type, but a server may create more than one file for each resource resources type returned. The number of resources contained in a file is may vary between servers. If no data is found for a resource, the server should not return an output item for it in the response.

  • url - the path to the file. The format of the file should reflect that of requested in the _outputFormat parameter of the initial kick-off request.

    Each file item may optionally contain the following field:

  • Note: no extensions count - the number of resources in this json object. the file, represented as a JSON number.

    Example response body:

    { "transactionTime": "[instant]", "request" : "[base]/Patient/$everything?_type=Patient,Observation", "secure" : true, "output" : [{ "type" : "Patient", "url" : "http://serverpath2/patient_file_1.ndjson" },{ "type" : "Patient", "url" : "http://serverpath2/patient_file_2.ndjson" },{ "type" : "Observation", "url" : "http://serverpath2/observation_file_1.ndjson" }] }
    {
      "transactionTime": "[instant]",
      "request" : "[base]/Patient/$export?_type=Patient,Observation", 
      "requiresAccessToken" : true,
      "output" : [{
        "type" : "Patient",
        "url" : "http://serverpath2/patient_file_1.ndjson"
      },{
        "type" : "Patient",
        "url" : "http://serverpath2/patient_file_2.ndjson"
      },{
        "type" : "Observation",
        "url" : "http://serverpath2/observation_file_1.ndjson"
      }],
      "error" : [{
        "type" : "OperationOutcome",
        "url" : "http://serverpath2/err_file_1.ndjson"
      }]
    }
    
    
    Once the client receives this response, it can retrieve the individual files listed in the response.

Using the urls supplied in the completed status request body, clients can download the generated bulk data files (one or more per resource type). Note: These files may be served by a file server rather than a FHIR specific server. Also, if the secure requiresAccessToken field in the status body is set to true the request must include a valid access token in the Authorization header in these requests. requests (i.e., Authorization: Bearer {{token}} ).

GET [url from status request output field]

  • Accept (optional, but must match the original _outputFormat defaults to application/fhir+ndjson ): )

Specifies the format of the file being returned returned. Optional, but currently only application/fhir+ndjson is supported.

  • HTTP status of 200 OK
  • Content-Type header of application/fhir+ndjson
  • Body - the requested content 3.1.6.3.4 Response - Error HTTP Status Code of 4XX or 5XX 3.1.6.4 Bulk Data Delete Request: After a bulk data request has been kicked-off, clients can send a delete request to the url provided FHIR resources in the Content-Location header to cancel the request. 3.1.6.4.1 Endpoint DELETE [polling content location] 3.1.6.4.2 Response newline delimited json - Success HTTP Status Code of 202 Accepted ndjson Optionally a OperationOutcome in the body format
  • HTTP status code Status Code of 4XX or 5XX
  • Optionally a OperationOutcome in the body