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.