Reporting

Our platform offers an industry-first approach to reporting that empowers your teams to get the data they need through a modern API interface while supporting conventional CSV standards for plugging into your existing processes and business intelligence tools.

The sections below detail both the methods for report definition (eg. how we set up and organize the queries that serve as the basis for our reports) and report delivery (eg. how partners can access reports in a secure manner).

Report Definition

We have pre-authored a large library of common reports used in benefit administration, and continually add more as requested by our customers. A few of the out-of-box reports include:

• Partner Summary Information
• Organization Summary Information
• Wallet Balances
• Card Issuing & Status
• Card Transactions
• Benefit Participant Summary Information
• Contributions
• Benefit Account Spending
• Claims

The current library of available reports is detailed below in the Report Library section. If a report you need is missing or you need a new way to view your data, contact your account manager for more information about creating custom reports.

Report Delivery

Partners have multiple ways to incorporate reporting into their administration processes by leveraging our unique platform capabilities. A few of those methods include:

• By your account manager as a CSV download via secure link

• By your own team via the GraphQL API. Specifically, see the generateReport mutation and report query and the instructions below.

• Directly within the Health Wallet or Health Wallet Manager app

Reporting API

First Dollar's reporting API makes it easy and straightforward for partners to access data about their own customers as needed, without needing to contact an account manager for an ad-hoc report. The data returned by these reports can then be pulled into the BI or other analytics system of choice.

Report generation is an asynchronous process:

1. First, a partner will need to authenticate with the API using the OAuth Authentication Flow for the Partner API. The token returned by that call will then need to be passed as an Authentication: Bearer token on all subsequent requests, as outlined in the authentication flow documentation.
2. Report requests are initiated using the the generateReport mutation. Importantly, this mutation will not return the full data of the requested report synchronously. Instead, on success it returns a ReportExecution object which gives the status of the report request and an ID value that can be used to retrieve the report results.
3. Report status and results are retrieved with the report query. This query takes the report ID returned previously by a successfull call to generateReport and, on success, returns a Report object that includes both an execution field that will return the status of the report, and if the status is SUCCEEDED, the results field will contain the actual ReportResults for the report. If report generation has not yet finished, or the report generation failed, the results field will be null.

Here is a sample set of calls:

Sample generateReport mutation:

mutation {
  generateReport(
    input: {
      reportCode: "partner_info"
      # If the report takes parameters, they would be passed in the reportParameters field
      # reportParameters: { some_input_param: "value" }
    }
  ) {
    __typename
    ... on ReportExecution {
      id
      status
      reportCode
      reportTitle
      reportParameters
      requestedColumns
    }
    ... on Error {
      message
      code
      retryable
    }
  }
}

Sample generateReport response:

{
  "data": {
    "generateReport": {
      "__typename": "ReportExecution",
      "id": "21cd19cc-7c77-481d-8f21-3892b2a1c92e",
      "status": "NOT_STARTED",
      "reportCode": "partner_info",
      "reportTitle": "Reports one row for a partner with just some metadata about the partner.",
      "reportParameters": {
        "partner_code_param": "demopartner_000"
      },
      "requestedColumns": null
    }
  }
}

Sample report query:

query {
  # The id value here should be the id returned by the generateReport mutation
  # Note that large reports will be paginated
  report(where: { id: "21cd19cc-7c77-481d-8f21-3892b2a1c92e" }, page: 1) {
    __typename
    ... on Report {
      execution {
        id
        status
        reportCode
        reportTitle
        reportParameters
        requestedColumns
      }
      results {
        columnHeaders
        totalPages
        rows
      }
    }
    ... on Error {
      message
      code
      retryable
    }
  }
}

Sample report response:

{
  "data": {
    "report": {
      "__typename": "Report",
      "execution": {
        "id": "21cd19cc-7c77-481d-8f21-3892b2a1c92e",
        "status": "SUCCEEDED",
        "reportCode": "partner_info",
        "reportTitle": "Reports one row for a partner with just some metadata about the partner.",
        "reportParameters": {
          "partner_code_param": "demopartner_000"
        },
        "requestedColumns": null
      },
      # Since the execution status was SUCCEEDED, the results are shown below.
      "results": {
        "columnHeaders": [
          "partnerCode",
          "partnerName",
          "partnerCreatedAt"
        ],
        "totalPages": 1,
        # the rows field contains the actual data for the report
        "rows": [
          {
            "partnerCode": "demopartner_000",
            "partnerName": "A Demo Partner",
            "partnerCreatedAt": "2023-07-12 22:44:48.580723+00"
          }
        ]
      }
    }
  }
}

Report Library

The following list describes the current set of available reports. Again, if you need a report which is not listed here, please reach out to your account manager. Reports are listed by their reportCode, which is the value passed in to the generateReport mutation to specify the report to run. Unless otherwise specified, all reports take the following parameters:

• organization_code_param The code of an organization (i.e. employer) that belongs to the partner making the call. If passed, only rows relevant to this organization (e.g. participants who are employees of this employer) will be returned.
• uid_param The user ID of a participant that belongs to the partner making the call.

partner_info

Reports one row for a partner with just some metadata about the partner.

Parameters

• This report takes no parameters, as it just returns metadata about the calling partner.

organization_info

Reports one row for each organization within a partner with just some metadata about the org.

Parameters

• This report takes the organization_code_param, in which case only a row for that single organization is returned, as opposed to all the organizations that belong to a partner.

offering_participant_enrollments

Returns one row for every participant enrollment in an offering, either currently live or terminated/expired

Parameters

• This report takes both the organization_code_param and uid_params as outlined above.

program_cards

Returns one row for each card tied to a particular program

Parameters

• This report takes both the organization_code_param and uid_params as outlined above.
• program_public_ulid_param - pass this param to retrieve only cards that belong to the program specified by this ULID.

offering_card_transactions

Returns one row for each SUCCESSFUL card transaction tied to a particular offering

Parameters

• This report takes both the organization_code_param and uid_params as outlined above.
• offering_public_ulid_param - pass this param to retrieve only transactions for this offering.
• card_public_ulid_param - pass this param to retrieve only transactions that were from this card.

offering_spending_transactions

Returns one row for each spend (outgoing) transaction for a participant in an offering

Parameters

• This report takes both the organization_code_param and uid_params as outlined above.
• offering_public_ulid_param - pass this param to retrieve only transactions for this offering.
• min_transaction_date_param - pass this param to retrieve only transactions that were made after this date.
• max_transaction_date_param - pass this param to retrieve only transactions that were made before this date.

offering_participant_funding_events

Returns one row for each funding event for a participant in an offering

Parameters

• This report takes both the organization_code_param and uid_params as outlined above.
• offering_public_ulid_param - pass this param to retrieve only funding events for this offering.
• min_funding_event_date_param - pass this param to retrieve only funding events that were made after this date.
• max_funding_event_date_param - pass this param to retrieve only funding events that were made before this date.

offering_participant_summary_info

Returns one row for each offering participant, along with a bunch of summary data about their offering usage

Parameters

• This report takes both the organization_code_param and uid_params as outlined above.
• offering_public_ulid_param - pass this param to retrieve only information about participants for this offering.

hsa_ending_daily_balance

Returns the ending daily balance per HSA account for each day within a time span - the views default to year-to-date.

Parameters

• This report takes both the organization_code_param and uid_params as outlined above.
• min_date_param - pass this param to retrieve daily balances from this date onwards.
• max_date_param - pass this param to retrieve daily balances from before this date.

hsa_current_balance_info

Returns one row for each user HSA account with current balance info, including for associated investment accounts

Parameters

• This report takes both the organization_code_param and uid_params as outlined above.
• hsa_account_open_param - pass true for this param to only retrieve information about accounts that are currently open.
• hsa_account_funded_param - pass true for this param to only retrieve information about accounts that have been funded.