Directed Spend

Directed Spend accounts are employer-funded post tax benefits that allow employees to pay for specific expenses related to Health and Wellness. Directed Spend benefit accounts are designed by the Employer to provide additional benefits to the employee in setting aside funds to be spent in a manner specific to the plan design.

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 Directed Spend benefit, add it to organizations, and then enroll individuals.

Once the Directed Spend is established using this guide, partners and organizations can control the benefit design and restrict eligible items using First Dollar's Health Wallet Manager web application.

Setup and Enrollment

Getting the Directed Spend benefit template ID

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

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 Directed Spend 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 employer in our system. This allows you to create unique benefit programs per employer, and enroll employees 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 Directed spend to the benefit program for the organization. This call is where you will use the Directed Spend 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 Directed Spend 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 Directed Spend benefit:

First and Last Name
Physical Address (required for card carriers, mail, etc.)
Date of Birth

The following data is optional for all users:

Mailing address (physical address will be used if unspecified)
Phone number
Email address
SSN

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.

Enroll the Individuals in a Benefit

Finally, use the enrollIndividualInBenefit API to enroll each eligible individual into a specific benefit.

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 queue the process to send a card and marketing communications to the individual, but only on the specified start date of the benefits program.

Unenrolling Individuals From a DSA

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. This operation is implemented by the unenrollIndividualFromBenefit API.

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
    }
  }
}

Note

The transferBenefitForIndividual API is not available to non-HSA benefits. Attempting to call this API for a non-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.

Directed Spend

Setup and Enrollment​

Getting the Directed Spend benefit template ID​

Create Organizations​

Create a Benefits Program​

Create a Benefit​

Create Individuals​

Required Data for Individual Enrollment​

Enroll the Individuals in a Benefit​

Unenrolling Individuals From a DSA​

Note​

Making changes​