Making Requests to BFD

Making Requests to BFD

This page contains useful information for making requests to the BFD server.

BFD Audit Headers

This document details the HTTP headers that should be included when calling BFD, to ensure that proper audit information is available to the BFD team. Future versions of BFD may enforce/require some or all of these headers.

These fields allow engineers & operators to read the BFD logs and see exactly why data was requested.Some of this information is redundant with information already captured elsewhere, but experience has shown it to be very helpful when investigating issues.

Synchronous Requests

For synchronous (i.e. non-bulk) requests, BFD users SHALL include meaningful values for as many as possible of the following HTTP headers.

• BlueButton-OriginalQueryId: a unique ID (e.g. UUID) generated by the frontend system, per HTTP request to that frontend system.
  • This ID SHALL be included in all log events for the frontend system.
  • This allows requests to be traced across systems.
• BlueButton-OriginalQueryCounter: start at 1 and increment for every request to BFD with the same BlueButton-OriginalQueryId value.
• BlueButton-OriginalQueryTimestamp: an ISO-8601 UTC timestamp representing (roughly) when the original request reached the frontend system.
• BlueButton-DeveloperId: the unique ID in the frontend system for the developer/vendor of the third-party application.
• BlueButton-Developer: the human-readable name in the frontend system for the developer/vendor of the third-party application.
• BlueButton-ApplicationId: the unique ID in the frontend system for the application/client that will receive the data.
• BlueButton-Application: the human-readable name in the frontend system for the application/client that will receive the data.
• BlueButton-UserId: the unique ID in the frontend system for the user (e.g. beneficiary) that data is being requested on behalf of.
• BlueButton-User: the human-readable login ID (e.g. email address) in the frontend system for the user (e.g. beneficiary) that the data is being requested on behalf of.
• BlueButton-BeneficiaryId: the unique beneficiary ID (e.g. Patient.id) from BFD for the user the beneficiary whose data is being requested.
• x-forwarded-for: a standard header for identifying the originating IP address of a client connecting to a web server through an HTTP proxy or a load balancer.

Asynchronous Requests

For asynchronous (i.e. bulk) requests, BFD users SHALL include meaningful values for as many as possible of the following HTTP headers.

• BlueButton-OriginalQueryId: (see above; same thing)
  • For asynchronous jobs, users SHALL use the BlueButton-OriginalQueryId for the HTTP request that created/submitted/whatever the job.
• BULK-CLIENTID: a unique identifier of the bulk client for whom this request is for (i.e. UUID, ACO ID, NPI, Part D Contract)
• BULK-CLIENTNAME: a human readable name for the bulk client for whom this request is for to aid in tracing and debugging.
• BULK-JOBID: a unique identifier for the job (Job ID, UUID, etc.)

BFD Request Options

This document details the request options that can be used when calling BFD. Future versions of BFD may apply some of these options automatically, based on other request details (e.g. authentication/authorization).

Optional Data

Some data fields are optional; they're only included when the request is configured to do so.

• HTTP Header: IncludeIdentifiers
  • Note: This is only supported in v1; this header will have no effect in v2. V2 will always return unhashed MBIs, and does not return HICNs with or without the header.
  • Operations: all /Patient requests
  • Default value: false
  • Supported values: false, true, hicn, mbi
  • Description: Do not set this header more than once; an arbitrary value will be selected if that happens. When set to mbi, BFD will include all of the known MBIs for the requested beneficiary (unhashed). When set to hicn, BFD will include all of the known HICNs for the requested beneficiary (unhashed). When set to true, BFD will include all of the known MBIs and HICNs for the requested beneficiary (unhashed). When set to false, BFD will not include any (unhashed) MBIs or HICNs for the requested beneficiary.
• HTTP Header: IncludeAddressFields
  • Operations: all /Patient requests
  • Default value: false
  • Supported values: false, true
  • Description: When set to true, BFD will include all of the detailed address data for the requested beneficiary. When set to false, BFD will not include detailed address data for the requested beneficiary. Please note that, even when false county and ZIP/postal codes will still be included for the specified beneficiary.
• HTTP Header: IncludeTaxNumbers
  • Operations: all /ExplanationOfBenefit, /Claim, and /ClaimResponse requests
  • Default value: false
  • Supported values: false, true
  • Description: When set to true, BFD will include the National Provider Identifier (NPI) tax number(s) of the health care provider of services to a beneficiiary. When set to false, BFD will not include the tax numbers for the requested beneficiary.
• _elements parameter:
  • Operations: V2 /ExplanationOfBenefit requests using POST only
  • Supported values: Any element or element path in the response, starting below entry.resource
  • Description:
    • Must be passed as a POST body parameter to the supported operation request
      • Attempting to use _elements on GET request will result in a 400 error
    • Must be a comma separated list of elements to include in the response
    • All fields in the response below the specified elements will be returned
    • Element paths are permitted, and all fields below the final node in the path will be returned
    • Element value filtering is not supported (i.e. filtering on a specific extension url value)
    • Elements outside the specified requested paths will NOT be returned in the response, except for R4 FHIR spec required fields
    • In order to return a CARIN compliant response, it is recommended to use the following element paths in addition to your requested filters: identifier.value,identifier.type,status,use,billablePeriod.start,insurer,provider,related.relationship,related.reference,payee.type,payee.party,outcome,careTeam.provider,careTeam.role,supportingInfo,insurance.focal,insurance.coverage,item.sequence,item.noteNumber,item.adjudication,total,payment.type,processNote,patient.meta.lastUpdated,patient.identifier,patient.deceased,patient.address.country
    • See https://www.hl7.org/fhir/search.html#elements for an overview of the general functionality in the FHIR spec