Health Savings

Health savings accounts (HSAs) are tax-advantaged accounts designed to help individuals save and pay for qualified medical expenses.

Given a top level understanding of First Dollar's domain objects provided in the Health Wallet Introduction and Terminology, the following section will take you through the steps required to setup your HSA benefit, add it to organizations, and then enroll individuals.

Getting the HSA benefit template ID

One prerequisite to setup your HSA plan is to fetch the HSA benefit template ID. This can be done using the benefitsTemplate query. This will return an array of benefit templates, and you can find the HSA benefit template ID by finding the object with the type property of HSA.

query BenefitTemplates {
  benefitTemplates {
    ... on BenefitTemplatesResults {
      nodes {
        id
        name
        description
        type
        configuration {
          funding {
            limits {
              individual {
                currency
                lowestDenominationAmount
                amount
                display
              }
            }
            initialFunding {
              individual {
                currency
                lowestDenominationAmount
                amount
                display
              }
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

While we are specifically focused on the HSA in this guide, First Dollar is architected this way to allow for maximum flexibility in composing a benefit design across all benefit account types, and even allowing partners to create their own templates to create new types of lifestyle and wellness spending accounts.

Create Organizations

Next, use the createOrganization API to create an organization in our system. This allows you to create unique benefit programs per organization, and enroll members in those programs as appropriate.

mutation CreateOrganization($input: CreateOrganizationInput!) {
  createOrganization(input: $input) {
    ... on CreateOrganizationResult {
      organization {
        id
        name
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Create a Benefits Program

For each organization, you can then create a top level benefits program using the createBenefitsProgram API. A Benefits Program groups multiple Benefits together, enabling all of them to operate against a single Card, and defines shared settings that control Payment and Operational concerns for the grouped benefits.

mutation CreateBenefitsProgram($input: CreateBenefitsProgramInput!) {
  createBenefitsProgram(input: $input) {
    ... on CreateBenefitsProgramResult {
      benefitsProgram {
        id
        name
        organizationId
        benefits {
          id
          name
          description
          type
        }
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Create a Benefit

Then, use the createBenefit API to add the HSA to the benefit program for the organization. This call is where you will use the HSA benefit template ID.

mutation CreateBenefit($input: CreateBenefitInput!) {
  createBenefit(input: $input) {
    ... on CreateBenefitResult {
      benefit {
        id
        name
        description
        type
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

You can also set parameters such as the start date the HSA will begin. This way, you can set up and enroll individuals in the benefit weeks ahead of the start date, and individuals will not be able to access their accounts or receive card or marketing communications until the start date.

Create Individuals

Next, you'll create all individuals that need to be enrolled in these benefits. This can be done using the createIndividual API - call this API for each individual who should be enrolled in the benefit.

mutation CreateIndividual($input: CreateIndividualInput!) {
  createIndividual(input: $input) {
    ... on CreateIndividualResult {
      individual {
        ... on Individual {
          id
        }
      }
    }
  }
}

Required Data for Individual Enrollment

First Dollar's philosophy on data collection is to collect the minimal amount of data required to administer accounts for our users while maintaining compliance. Clients of First Dollar's API should provide the maximum amount of data the client system has available for an individual.

The following data is required for all individuals being added to an HSA benefit:

1. First and Last Name
2. Physical Address (required for card carriers, mail, used for KYC, etc.)
3. Date of Birth
4. SSN

The following data is optional for all users:

1. Mailing address (physical address will be used if unspecified)
2. Phone number
3. Email address

Note, if an email address is provided for a user, the email address must be globally unique (must not correspond to an existing user). If the provided email address is already in use, the request will be rejected as invalid.

Verify the Individual

Some Benefit types (currently just the HSA) require account holders to pass a Customer Identification Program (CIP/KYC) prior to allowing enrollment. Verification requires valid name, address, date of birth, and social security number, and will fail if any are missing or are invalid. If the user does not pass CIP/KYC checks, a status and corresponding verification codes will be available on the response.

Use the verifyIndividual API to verify your Individuals prior to enrolling them in the HSA Benefit.

mutation VerifyIndividual($input: VerifyIndividualInput!) {
  verifyIndividual(input: $input) {
    ... on VerifyIndividualResult {
      individual {
        id
      }
      verification {
        id
        status
        verificationCodes
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

When this API is called, First Dollar will run KYC checks on the individual. If the individual passes KYC, they are then eligible for enrollment into the HSA offering, which is accomplished via the enrollIndividualInBenefit API, discussed below. If the individual does not pass KYC, enrollIndividualInBenefit must still be called after this verification step to store a record of the enrollment request and to allow KYC administration processes to continue.

For a user in KYC review, First Dollar's Health Wallet Manager application allows uploading supporting evidence, modifying user details, re-running KYC, and manually approving KYC where required. After KYC is resolved successfully and in the affirmative, enrollment and account opening will happen automatically.

Enroll the Individuals in a Benefit

Finally, use the enrollIndividualInBenefit API to enroll each eligible individual into a specific benefit. This API must be called regardless of the outcome of verifyIndividual. This is necessary to ensure that a user who did not pass KYC can be appropriately administered in First Dollar's system.

mutation EnrollIndividualInBenefit($input: EnrollIndividualInBenefitInput!) {
  enrollIndividualInBenefit(input: $input) {
    ... on EnrollIndividualInBenefitResult {
      individual {
        id
      }
      benefit {
        id
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

This API call will also queue the process to send a card and marketing communications to the individual, but only on the specified start date of the benefits program.

HSA Benefits: Transfer Individuals From a Benefit Program

When an individual's coverage changes or ends, the benefit may require a state change. HSA Benefits are a unique case. Individuals own the account backing an HSA Benefit and must retain access to the HSA Benefit across the lifecycle of the account. When coverage changes for an HSA Benefit, the HSA Benefit must be transferred. Transferring an HSA to a new Organization and Offering communicates the management change to the account while simultaneously ensuring Individual account access is retained.

Use the transferBenefitForIndividual API to transfer an Individuals HSA Benefit enrollment from one Offering (one Organization) to a second Offering/Organization pair.

mutation TransferBenefitForIndividual($input: TransferBenefitForIndividualInput!) {
  transferBenefitForIndividual(input: $input) {
    ... on TransferBenefitForIndividualResult {
      individual {
        id
      }
      benefit {
        id
      }
      transferBenefit {
        id
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Note

The unenrollIndividualFromBenefit API is not available to HSA benefits. Attempting to call this API for an HSA benefit will fail with error.

Making changes

All of the APIs cited above have complimentary APIs to update and make changes to benefits programs, organizations, and individuals. See our full API reference for additional endpoints that you can use to manage changes to an organization's benefits.