Setup & Enrollment
This guide is an overview demonstrating how you can build a benefits program and enroll members. We support enrollment through our API or via SFTP file exchange. You can also see this flow applied to specific benefit types in our account specific guides:
1. Create Organizations
First, use the createOrganization API to create an employer 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
}
}
}
2. Create Benefits Program
For each organization, you can then create a top level benefits program using the createBenefitsProgram API. A benefits program is a suite of complimentary benefit types that you'd like the organization to be able to offer members for a given benefits enrollment cycle.
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
}
}
}
3. Create Benefit
Then, use the createBenefit API to create individual benefits that should be in each program. An example benefit lineup might include an HSA, an FSA, and a Commuter Stipend.
mutation CreateBenefit($input: CreateBenefitInput!) {
createBenefit(input: $input) {
... on CreateBenefitResult {
benefit {
id
name
description
type
}
}
... on BadRequestError {
code
message
}
... on InternalServerError {
code
message
}
}
}
4. Create Individuals
Next, you'll create all individuals that need to be enrolled in these benefits. This can be done using the createIndividual API.
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.
mutation CreateIndividual($input: CreateIndividualInput!) {
createIndividual(input: $input) {
... on CreateIndividualResult {
individual {
id
name {
firstName
middleName
lastName
}
address {
addressLine1
addressLine2
city
state
zip
}
}
}
... on BadRequestError {
code
message
}
... on InternalServerError {
code
message
}
}
}
Required Identification Data
The data required to successfully enroll an individual in a Benefit depends in part on the underlying Benefit. For example, Benefits that require per-user KYC will not allow enrollment unless a user has name, address, DOB, and SSN defined. On the other hand, Benefits that do not require KYC per account holder only need to specify the minimum amount of user-data.
The following data is required for all Individuals:
- First and Last Name
- Physical Address (required for card carriers, mail, used for KYC, etc.)
The following data is conditionally required, depending on the account type:
- Date of Birth
- SSN
The following data is optional for all users:
- Mailing address (physical address will be used if unspecified)
- Phone number
- 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.
4a. Verify Individuals (*Required for HSAs)
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 does not pass KYC, partners can use First Dollar's Health Wallet Manager application to upload supporting evidence and manually approve KYC cases, which will then be propagated to the individual user record. Enrollment can occur after verification is approved, either automatically or via a manual approval process available in the Health Wallet Manager application.
5. Enroll Individuals In Benefit Program
Use the enrollIndividualInBenefit API to enroll these individual into the benefits program that was also created earlier. This will kick off the appropriate steps in First Dollar's system depending on the benefit - such as card issuing and marketing outreach - depending on the specifications laid out in your implementation.
mutation EnrollIndividualInBenefit($input: EnrollIndividualInBenefitInput!) {
enrollIndividualInBenefit(input: $input) {
... on EnrollIndividualInBenefitResult {
individual {
id
}
benefit {
id
}
}
... on BadRequestError {
code
message
}
... on InternalServerError {
code
message
}
}
}
6. View Individual Health Wallet Balance(s) & History
An id property is returned from the createIndividual mutation called out above. This id property can then be passed into the individual query to get the member's Health Wallet details. The Individual object contains a healthWallet property with the balance and transaction data for each benefit the member is enrolled in. You can see what fields are available here by inspecting the Account object for each benefit type.
Below is an example GraphQL query for all available Health Wallet data for an individual:
query IndividualsWalletsAndTransactions($where: IndividualsFilterInput!) {
individuals(where: $where) {
... on IndividualsResults {
pageInfo {
endCursor
hasNextPage
}
nodes {
id
healthWallet {
id
accounts {
id
availableBalance {
currency
lowestDenominationAmount
amount
display
}
currentBalance {
currency
lowestDenominationAmount
amount
display
}
fundingSummary {
total {
currency
lowestDenominationAmount
amount
display
}
}
benefit {
id
configuration {
funding {
limits {
individual {
currency
lowestDenominationAmount
amount
display
}
}
initialFunding {
individual {
currency
lowestDenominationAmount
amount
display
}
}
}
}
}
createdAt
transactions {
nodes {
id
amount {
currency
lowestDenominationAmount
amount
display
}
balance {
currency
lowestDenominationAmount
amount
display
}
date
description
timestamp
}
pageInfo {
hasNextPage
endCursor
}
}
}
balanceSummary {
totalAvailableBalance {
currency
lowestDenominationAmount
amount
display
}
totalCurrentBalance {
currency
lowestDenominationAmount
amount
display
}
}
}
}
}
... on BadRequestError {
code
message
}
... on InternalServerError {
code
message
}
}
}
7. Unenrolling or Transferring Individuals From Benefit Program
When an individual's coverage changes or ends, the benefit may require a state change. In the general case, when coverage ends, the individual should lose access to the Benefit.
HSA Benefits are a unique case, and when coverage changes for an HSA Benefit, the HSA Benefit must be transferred rather than unenrolled. Individuals own the account backing an HSA Benefit and must retain access to the HSA Benefit across the lifecycle of the account. Transferring the HSA to a new Organization and Offering communicates the management change to the account while simultaneously ensuring Individual account access is retained.
7a. Non-HSA Benefits: Unenrolling Individuals From a Benefit Program
Use the unenrollIndividualFromBenefit API to unenroll individuals from benefits programs when necessary.
mutation UnenrollIndividualFromBenefit(
$input: UnenrollIndividualFromBenefitInput!
) {
unenrollIndividualFromBenefit(input: $input) {
... on UnenrollIndividualFromBenefitResult {
individual {
id
}
benefit {
id
}
}
... on BadRequestError {
code
message
}
... on InternalServerError {
code
message
}
}
}
7b. HSA Benefits: Transfer Individuals From a Benefit Program
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
}
}
}
8. Additional Queries & Mutations
All of the mutations mentioned above have complimentary Update* mutations used to make changes to benefits programs, organizations, and individuals. See our full API reference for additional endpoints that you can use to modify an organization's benefits.