Call the $davinci-data-export Operation

 

Once the provider system is registered, the DaVinci Data Exchange module is enabled, Organization and Group resources are created, and consent is properly configured, the provider system can perform a $davinci-data-export to retrieve member data.

Steps to Call the Operation

  1. Obtain an OAuth 2.0 Access Token
    • Use SMART on FHIR to authenticate the provider system.
    • Ensure the token includes the appropriate scopes (e.g., patient/*.read or user/*.read).
  2. Prepare the Export Request
    • Endpoint: [FHIR base]/Group/[id]/$davinci-data-export
      • [FHIR base]: base URL of the payer's FHIR server
      • [id]: ID of the Group resource representing the provider's attributed members
    • Request Parameters:
      • exportType (required): e.g., hl7.fhir.us.davinci-pdex#provider-download
      • _since (optional, valueInstant): include only resources updated after this time
      • _until (optional, valueInstant): include only resources updated before this time
      • patient (optional, multiple): filter by specific patient(s)
      • _type (optional, comma-separated): filter by resource type
      • _typeFilter (optional, multiple): filter resources with a FHIR search query
      • _outputFormat (optional): desired format, e.g., NDJSON
      • Which parameters each export type accepts is listed in Supported Parameters per Export Type. For example, the Delta export rejects _since, _type and _typeFilter, and the ATR export requires _type.
    • Method: POST
  3. Execute the Export Request
    • Send the POST request with the access token in the Authorization header.
    • HTTP 202 Accepted indicates the export job has been successfully initiated.
    • Locate the Content-Location header in the response. This URL is the export job status (polling) endpoint.
    • e.g., Content-Location: https://api.payer.com/fhir/$export-poll-status?_jobId=67890
    • Use this URL to poll the job until it completes (see Step 4).
  4. Poll the Export Job URL
    • Continue polling until the job completes.
    • Once finished, the response provides a list of NDJSON file URLs containing the exported data.
  5. Retrieve and Process the Data
    • Download the NDJSON files.
    • Parse and process the resources as needed.

Sample Request

POST https://api.payer.com/fhir/Group/12345/$davinci-data-export
Authorization: Bearer <access_token>
Content-Type: application/fhir+json
Accept: application/fhir+json
Prefer: respond-async

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "exportType",
      "valueString": "hl7.fhir.us.davinci-pdex#provider-delta"
    },
    {
      "name": "patient",
      "valueReference": { "reference": "Patient/1553" }
    },
    {
      "name": "_outputFormat",
      "valueString": "application/fhir+ndjson"
    }
  ]
}

Sample Response

HTTP/1.1 202 Accepted
Content-Location: https://api.payer.com/fhir/$export-poll-status?_jobId=67890
X-Request-ID: abc123

Notes:

  • Only members included in the attributed Group will be exported.
  • Members who opted out are excluded by removing them from the Group (see Consent Management).
  • Supported export types include ATR, Download, Delta, and Snapshot. See the tutorials for a sample request for each export type.