API Reference
Supported Operations
The two root types of a GraphQL schema are the Query type and the Mutation type. These types define the entry points for retrieving and modifying data, respectively. The fields under these types define the capabilities of our GraphQL API.
Queries
Data you can retrieve from our API
11 Queries
Mutations
Actions you can perform to modify data in our API
17 Mutations
Schema-Defined Types
All types in our GraphQL schema fall into one of the following categories:
Objects
The entities in our GraphQL schema
48 Objects
Interfaces
Abstract types that other types inherit from
1 Interfaces
Enums
The enumeration types
12 Enums
Unions
The unions in our GraphQL schema
27 Unions
Inputs
Used to provide data to an operation
35 Inputs
Scalars
The primitives in our GraphQL schema
30 Scalars
Directives
Directives are used to modify the behavior of the GraphQL schema. They are used to annotate fields, fragments, and operations.
auditLoggingEncryptionContext
No description
deprecated
Marks an element of a GraphQL schema as no longer supported.
idempotent
Marks a mutation as idempotent
include
Directs the executor to include this field or fragment only when the if argument is true.
noAuditLogging
No description
oneOf
Indicates exactly one field must be supplied and this field must not be null.
rateLimit
Controls the rate of traffic.
skip
Directs the executor to skip this field or fragment when the if argument is true.
specifiedBy
Exposes a URL that specifies the behavior of this scalar.
GraphQL Schema (SDL)
Download the schema at https://developer.firstdollar.com/partner.schema.graphqlschema.graphql
directive @auditLoggingEncryptionContext(machineUser: String!) on FIELD_DEFINITION
"""Marks a mutation as idempotent"""
directive @idempotent(key: String = "input.idempotencyKey") on FIELD_DEFINITION
directive @noAuditLogging on FIELD_DEFINITION
"""Controls the rate of traffic."""
directive @rateLimit(
"""Number of seconds before limit is reset."""
duration: Int! = 60
"""Number of occurrences allowed over duration."""
limit: Int! = 60
) on FIELD_DEFINITION | OBJECT
"""An Account belonging to a Health Wallet."""
type Account {
"""Whether or not the individual's enrollment in this offering is active"""
active: Boolean!
"""The amount of money that is available to be spent for this account"""
availableBalance: Money!
"""The Benefit this account belongs to."""
benefit: Benefit
"""When the Account was created"""
createdAt: DateTime!
"""
The total amount of money in this account.
Note that `currentBalance` and `availableBalance` may differ when there
are ongoing money movement processes.
"""
currentBalance: Money!
"""The end date of the offering for this individual"""
endsAt: DateTime
"""
A summary of the funding this account has received. Funding corresponds to deposit transactions
that increase the balance of the account.
"""
fundingSummary: AccountFundingSummary!
"""The ID of the account"""
id: ID!
"""The initial contribution for this account"""
initialContribution: InitialContribution
"""The recurring contributions for this account"""
recurringContribution: RecurringContribution
"""Transactions posted against this Account"""
transactions(
"""Return the Transaction that come after the specified cursor"""
after: String
"""The number of Transactions to retrieve per page"""
first: Int
"""Filter criteria used to match Transactions"""
where: TransactionsFilterInput
): TransactionResults!
}
"""The possible enrollment statuses for an Individual"""
enum AccountEnrollmentStatus {
"""The Individual has an active enrollment in at least one offering"""
ENROLLED
"""The Individual has no active enrollments in any offerings"""
UNENROLLED
}
"""
A summary of the funding an account has received. Funding corresponds only to deposit transactions
that increase the balance of the account.
"""
type AccountFundingSummary {
"""
The total amount of funds this account has received across its lifecycle.
"""
total: Money!
}
"""
Banking account number is a string of 5 to 17 alphanumeric values for representing an generic account number
"""
scalar AccountNumber
"""Returned when there is an error in the request."""
type BadRequestError implements Error {
"""An alphanumeric identifier for this error."""
code: String!
"""A user-facing error message."""
message: String!
"""
Returns true if the client can safely retry the request, false otherwise.
"""
retryable: Boolean!
}
"""A Benefit offered to an individual in a Benefits Program"""
type Benefit {
"""The configuration of the Benefit."""
configuration: BenefitConfiguration!
"""A description of the Benefit"""
description: String!
"""The end date of the Benefit"""
endDate: LocalDate
"""A unique identifier for the Benefit"""
id: ID!
"""A human-readable name for the Benefit"""
name: String!
"""The start date of the Benefit"""
startDate: LocalDate!
"""The type of Benefit"""
type: BenefitType!
}
"""
The Benefit Configuration describes the parameters and controls all aspects of the Benefit.
"""
type BenefitConfiguration {
"""Describes the controls and behaviors around Benefit Funding."""
funding: BenefitFundingConfiguration!
}
"""Filter criteria used when querying for a benefit"""
input BenefitFilterInput {
"""The ID of the benefit"""
id: ID!
}
"""Describes the parameters and behaviors of Funding for the Benefit."""
type BenefitFundingConfiguration {
"""
The Initial Funding for a Benefit defines the initial amount of Funds made available to an Individual.
"""
initialFunding: BenefitInitialFundingConfiguration!
"""
The Funding Limits for a Benefit govern the maximum amount of funds that can be made available
to a given account.
"""
limits: BenefitFundingLimitsConfiguration!
}
"""
The Funding Limits for a Benefit govern the maximum amount of funds that can be made available
to a given account.
"""
type BenefitFundingLimitsConfiguration {
"""
The maximum amount of funding permitted for an account belonging an Individual. If the value is null,
no maximum limit is applied to funding for accounts created against this benefit.
"""
individual: Money
}
"""
The Initial Funding for a Benefit defines the initial amount of Funds made available to an Individual.
"""
type BenefitInitialFundingConfiguration {
"""
The initial amount of funds made available to an account belonging an Individual. If the value is $0.00 or null,
no initial funding will occur for Individuals enrolled in the Benefit.
"""
individual: Money
}
"""
A union representing the possible return types when querying for a benefit
"""
union BenefitResponse = BadRequestError | Benefit | InternalServerError
"""Represents a template used when creating a benefit"""
type BenefitTemplate {
"""
If defined, Benefits created from this template inherit (and may override) this configuration.
"""
configuration: BenefitConfiguration
"""A description of the benefit provided by this template"""
description: String!
"""A unique identifier for the benefit template"""
id: ID!
"""
A human-readable name for the benefit template (e.g. 'Health Savings Account')
"""
name: String!
"""The type of benefit the template represents"""
type: BenefitType!
}
"""Filter criteria used when querying for benefit templates"""
input BenefitTemplatesFilterInput {
"""If specified, only returns Benefit Templates matching this ID"""
id: ID
"""If specified, only returns Benefit Templates matching this name"""
name: String
"""If specified, only returns Benefit Templates matching this type"""
type: BenefitType
}
"""
A union representing the possible return types when querying for benefit templates
"""
union BenefitTemplatesResponse = BadRequestError | BenefitTemplatesResults | InternalServerError
"""Represents a page of benefit templates"""
type BenefitTemplatesResults {
nodes: [BenefitTemplate!]!
pageInfo: PageInfo!
}
"""Enumerates the possible types of benefits"""
enum BenefitType {
"""Commuter/Transit Account"""
COMMUTER
"""Dependent Care Flexible Spending Account"""
DCFSA
"""Directed Spend Account"""
DIRECTED_SPEND
"""General Purpose Flexible Spending Arrangement"""
FSA
"""Health Reimbursement Arrangement"""
HRA
"""Health Savings Account"""
HSA
"""Limited Purpose Flexible Spending Arrangement"""
LPFSA
"""Lifestyle Spending Account"""
LSA
"""Remote Work Account"""
REMOTE_WORK
"""Rewards Account"""
REWARDS
}
"""A program containing benefits offered to individuals"""
type BenefitsProgram {
"""Benefits offered by this program"""
benefits: [Benefit!]!
"""A unique identifier for the program"""
id: ID!
"""The name of the program"""
name: String!
"""The ID for the organization to which this program belongs"""
organizationId: ID!
}
"""Filter criteria used when querying for a benefits program"""
input BenefitsProgramFilterInput {
"""ID of the program"""
id: ID!
}
"""
A union representing the possible return types when querying for a benefits program
"""
union BenefitsProgramResponse = BadRequestError | BenefitsProgram | InternalServerError
"""Filter criteria used when querying for benefits programs"""
input BenefitsProgramsFilterInput {
"""
If specified, only returns Benefits Programs associated with these Organization IDs
"""
organizationIds: [ID!]
}
"""
A union representing the possible return types when querying for benefits programs
"""
union BenefitsProgramsResponse = BadRequestError | BenefitsProgramsResults | InternalServerError
"""Represents a page of benefits programs"""
type BenefitsProgramsResults {
nodes: [BenefitsProgram!]!
pageInfo: PageInfo!
}
"""
The `BigInt` scalar type represents non-fractional signed whole numeric values.
"""
scalar BigInt
"""A country code as defined by ISO 3166-1 alpha-2"""
scalar CountryCode
"""An input type used when creating a benefit"""
input CreateBenefitInput {
"""The ID of the benefits program to which the benefit belongs"""
benefitsProgramId: ID!
"""
The description of the benefit. If unspecified, defaults to the description from the template.
"""
description: String
"""The end date of the Benefit."""
endDate: LocalDate
"""
The name of the benefit. If unspecified, defaults to the name from the template.
"""
name: String
"""The start date of the Benefit."""
startDate: LocalDate!
"""The ID of the template to use when creating the benefit"""
templateId: ID!
}
"""A union representing the possible return types when creating a benefit"""
union CreateBenefitResponse = BadRequestError | CreateBenefitResult | InternalServerError
"""The successful result of creating a benefit"""
type CreateBenefitResult {
"""The benefit that was created"""
benefit: Benefit!
}
"""An input type used when creating a benefits program"""
input CreateBenefitsProgramInput {
"""The name of the program"""
name: String!
"""The ID for the organization to which this program belongs"""
organizationId: ID!
}
"""
A union representing the possible return types when creating a benefits program
"""
union CreateBenefitsProgramResponse = BadRequestError | CreateBenefitsProgramResult | InternalServerError
"""The successful result of creating a benefits program"""
type CreateBenefitsProgramResult {
"""The program that was created"""
benefitsProgram: BenefitsProgram!
}
"""An input type used for creating an Individual"""
input CreateIndividualInput {
"""The Individual to create"""
individual: IndividualInput!
}
"""
A union representing the possible return types when creating an Individual
"""
union CreateIndividualResponse = BadRequestError | CreateIndividualResult | InternalServerError
"""The successful result of creating an Individual"""
type CreateIndividualResult {
"""The Individual that was created"""
individual: Individual!
}
"""An input type used when creating an Organization"""
input CreateOrganizationInput {
"""The user-displayable name of the Organization"""
name: String!
}
"""
A union representing the possible return types when creating an Organization
"""
union CreateOrganizationResponse = BadRequestError | CreateOrganizationResult | InternalServerError
"""The successful result of creating an Organization"""
type CreateOrganizationResult {
"""The Organization that was created"""
organization: Organization!
}
"""
A field whose value is a Currency: https://en.wikipedia.org/wiki/ISO_4217.
"""
scalar Currency
"""
A date-time string, such as 2007-12-03T10:15:30Z, compliant with the `date-time` format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.This scalar is serialized to a string in ISO 8601 format and parsed from a string in ISO 8601 format.
"""
scalar DateTime
"""A secure link to download a page of content."""
type DownloadLink {
"""The URL string that should be used to retrieve the content"""
downloadUrl: String!
"""
The date and time that this download link will expire in ISO 8601 format.
"""
expires: String!
"""
These are request headers, where the keys are the header names and the values the header values, that MUST be
passed along when GETting files with the downloadUrl. Note these headers may contain decryption keys to use
when pulling down content and thus should be considered sensitive.
"""
requestHeaders: JSONObject!
}
"\n A string representing a duration conforming to the ISO8601 standard,\n such as: P1W1DT13H23M34S\n P is the duration designator (for period) placed at the start of the duration representation.\n Y is the year designator that follows the value for the number of years.\n M is the month designator that follows the value for the number of months.\n W is the week designator that follows the value for the number of weeks.\n D is the day designator that follows the value for the number of days.\n T is the time designator that precedes the time components of the representation.\n H is the hour designator that follows the value for the number of hours.\n M is the minute designator that follows the value for the number of minutes.\n S is the second designator that follows the value for the number of seconds.\n\n Note the time designator, T, that precedes the time value.\n\n Matches moment.js, Luxon and DateFns implementations\n ,/. is valid for decimal places and +/- is a valid prefix\n "
scalar Duration
"""
A field whose value conforms to the standard internet email address format as specified in HTML Spec: https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address.
"""
scalar EmailAddress
"""An input type used when enrolling an Individual in a Benefit"""
input EnrollIndividualInBenefitInput {
"""The ID of the Benefit to enroll the Individual in"""
benefitId: ID!
"""
The amount of funds from an employee to be used as an initial contribution upon Benefit Enrollment. If provided, this must be positive, non-zero amount.
"""
employeeInitialContributionAmount: MoneyInput
"""
The amount of funds from an employee to be contributed on a recurring schedule to the Benefit. If provided, this must be positive, non-zero amount.
"""
employeeRecurringContributionAmount: MoneyInput
"""
The amount of funds from an employer to be used as an initial contribution upon Benefit Enrollment. If provided, this must be positive, non-zero amount.
"""
employerInitialContributionAmount: MoneyInput
"""
The amount of funds from an employer to be contributed on a recurring schedule to the Benefit. If provided, this must be positive, non-zero amount.
"""
employerRecurringContributionAmount: MoneyInput
"""
The End Date of the Individual Enrollment. If unspecified, defaults to the End Date of the Benefit.
"""
endDate: LocalDate
"""The ID of the Individual to enroll in the program"""
individualId: ID!
"""
The Start Date of the Individual Enrollment. If unspecified, defaults to the Start Date of the Benefit.
"""
startDate: LocalDate
"""
For Benefits that require verification, the ID of a Verification to validate prior to enrollment. The associated
Verification must be in a valid state for enrollment and must belong to the Individual specified by `individualId`.
For Benefits that do not require verification, this attribute is ignored.
"""
verificationId: ID
}
"""
A union representing the possible return types when enrolling an Individual in a Benefit
"""
union EnrollIndividualInBenefitResponse = BadRequestError | EnrollIndividualInBenefitResult | InternalServerError
"""The successful result of enrolling an Individual in a Benefit"""
type EnrollIndividualInBenefitResult {
"""The Benefit"""
benefit: Benefit!
"""The Individual that was enrolled in the Benefit"""
individual: Individual!
}
"""All errors extend this core `Error` interface."""
interface Error {
"""An alphanumeric identifier for this error."""
code: String!
"""A user-facing error message."""
message: String!
"""
Returns true if the client can safely retry the request, false otherwise.
"""
retryable: Boolean!
}
"""An input type used when funding a benefit for an individual"""
input FundBenefitForIndividualInput {
"""
The amount of funds to make available to the individual. This must be positive, non-zero amount
in USD currency or the request will be rejected as invalid.
"""
amount: MoneyInput!
"""The ID of the benefit the individual is enrolled in"""
benefitId: ID!
"""A unique idempotency key for this request."""
idempotencyKey: String!
"""The ID of the individual who should receive these funds"""
individualId: ID!
}
"""
A union representing the possible return types when funding an individual in a benefit
"""
union FundBenefitForIndividualResponse = BadRequestError | FundBenefitForIndividualResult | InternalServerError
"""The successful result of funding an individual in a benefit"""
type FundBenefitForIndividualResult {
"""The ID of the benefit that was funded"""
benefitId: ID!
"""The ID of the individual who was funded"""
individualId: ID!
"""The ID of the transaction corresponding to this funding request"""
transactionId: ID!
}
"""The input type used to request the generation of new report results."""
input GenerateReportInput {
"""
Uniquely identifies which report should be generated. The set of possible values for `reportCode` is outlined
in the First Dollar API documentation.
"""
reportCode: String!
"""
The set of parameters to pass with this report generation request. This keys in this field are the
parameter names and the values are the parameter values. The possible parameters for each individual `reportCode`
are specified in the First Dollar API documentation.
"""
reportParameters: JSONObject
"""
This field allows the caller to specify a subset of columns in the report for generation. If this value is not
specified, all requested columns will be returned.
"""
requestedColumns: [String!]
}
"""The possible return types when submitting a report generation request."""
union GenerateReportResponse = BadRequestError | InternalServerError | ReportExecution
"""A Health Wallet belonging to an Individual"""
type HealthWallet {
"""The accounts belonging to this Health Wallet"""
accounts: [Account!]!
"""
A summary object describing Balance aggregates across all accounts in a Health Wallet.
"""
balanceSummary: HealthWalletBalanceSummary!
"""The ID of the Health Wallet"""
id: ID!
}
"""
A summary object describing Balance aggregates across all accounts in a Health Wallet.
"""
type HealthWalletBalanceSummary {
"""
The total available balance across all accounts belonging to this Health Wallet
"""
totalAvailableBalance: Money!
"""
The total current balance across all accounts belonging to this Health Wallet.
Note that `currentBalance` and `availableBalance` may differ when there
are ongoing money movement processes.
"""
totalCurrentBalance: Money!
}
"""Filter criteria used when querying for Health Wallet Accounts"""
input HealthWalletFilterInput {
"""
If specified, returns a filtered list of accounts based on the specified statuses
If not specified or array is empty, returns full lost of accounts
"""
statuses: [AccountEnrollmentStatus!]
}
"""An Individual"""
type Individual {
"""The Individual's primary address"""
address: PhysicalAddress
"""The Individual's date of birth"""
dateOfBirth: LocalDate
"""The Individual's email address"""
email: EmailAddress
"""The Individual's Health Wallet"""
healthWallet(where: HealthWalletFilterInput): HealthWallet
"""The ID of the Individual"""
id: ID!
"""The Individual's language preference for all communications"""
language: SupportedLanguage
"""The Individual's mailing address"""
mailingAddress: PhysicalAddress
"""The Individual's name"""
name: IndividualName!
"""The Individual's phone number"""
phoneNumber: PhoneNumber
"""The Individual's Tax Identification Number"""
tin: String
"""The Individual's Verifications"""
verifications: [Verification!]!
}
"""Filter criteria used when querying for an Individual"""
input IndividualFilterInput {
"""The ID of the Individual"""
id: ID!
}
"""An Individual"""
input IndividualInput {
"""The Individual's primary address"""
address: PhysicalAddressInput
"""The Individual's date of birth"""
dateOfBirth: LocalDate
"""The Individual's email address"""
email: EmailAddress
"""The Individual's external user ID"""
externalUserId: String
"""The Individual's language preference for all communications"""
language: SupportedLanguage
"""The Individual's mailing address"""
mailingAddress: PhysicalAddressInput
"""The Individual's name"""
name: IndividualNameInput!
"""The Individual's phone number"""
phoneNumber: PhoneNumber
"""The Individual's Tax Identification Number"""
tin: String
}
"""An Individual's name"""
type IndividualName {
"""The Individual's first name"""
firstName: String!
"""The Individual's last name"""
lastName: String!
"""The Individual's middle name, if any"""
middleName: String
}
"""An Individual's name"""
input IndividualNameInput {
"""The Individual's first name"""
firstName: String!
"""The Individual's last name"""
lastName: String!
"""The Individual's middle name, if any"""
middleName: String
}
"""
A union representing the possible return types when querying for an Individual
"""
union IndividualResponse = BadRequestError | Individual | InternalServerError
"""Filter criteria used when querying for Individuals"""
input IndividualsFilterInput {
"""
If specified, only returns Individuals who are enrolled in these Benefits
"""
benefitIds: [ID!]
"""
If specified, only returns Individuals who are enrolled in these Benefits Programs
"""
benefitsProgramIds: [ID!]
"""If specified, only returns Individuals matching these Individual IDs"""
ids: [ID!]
"""
If specified, only returns Individuals who are members of these Organizations
"""
organizationIds: [ID!]
"""
If specified, returns a filtered list of Individuals based on the specified statuses
"""
statuses: [AccountEnrollmentStatus!]
}
"""
A union representing the possible return types when querying for Individuals
"""
union IndividualsResponse = BadRequestError | IndividualsResults | InternalServerError
"""Represents a page of Individuals"""
type IndividualsResults {
nodes: [Individual!]!
pageInfo: PageInfo!
}
"""An initial contribution for an account"""
type InitialContribution {
"""The amount of the employee's initial contribution"""
employeeContributionAmount: Money!
"""
The amount of the employer's initial contribution on behalf of the employee
"""
employerContributionAmount: Money!
}
"""Returned when an error is encountered that is not expected."""
type InternalServerError implements Error {
"""An alphanumeric identifier for this error."""
code: String!
"""A user-facing error message."""
message: String!
"""
Returns true if the client can safely retry the request, false otherwise.
"""
retryable: Boolean!
}
"""
The `JSON` scalar type represents JSON values as specified by [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf).
"""
scalar JSON
"""
The `JSONObject` scalar type represents JSON objects as specified by [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf).
"""
scalar JSONObject
"""
A local date string (i.e., with no associated timezone) in `YYYY-MM-DD` format, e.g. `2020-01-01`.
"""
scalar LocalDate
"""
A local time string (i.e., with no associated timezone) in 24-hr `HH:mm[:ss[.SSS]]` format, e.g. `14:25` or `14:25:06` or `14:25:06.123`. This scalar is very similar to the `LocalTime`, with the only difference being that `LocalEndTime` also allows `24:00` as a valid value to indicate midnight of the following day. This is useful when using the scalar to represent the exclusive upper bound of a time block.
"""
scalar LocalEndTime
"""
A local time string (i.e., with no associated timezone) in 24-hr `HH:mm[:ss[.SSS]]` format, e.g. `14:25` or `14:25:06` or `14:25:06.123`.
"""
scalar LocalTime
"""The locale in the format of a BCP 47 (RFC 5646) standard string"""
scalar Locale
"""
Represents an amount of money, e.g. an account balance which may be positive or negative.
"""
type Money {
"""
The amount of money in the standard denomination of the target currency.
In `USD`, for example, this represents dollars, where `$1.00` is represented as `1`, and $1.50 is represented as `1.50`.
"""
amount: Float!
"""
The ISO-4217 currency associated with this money. Note that only `USD` is supported at this time.
"""
currency: Currency!
"""The amount and currency formatted for display e.g. $10.00"""
display(
"""Used to change the format when displaying money as a formatted string"""
format: MoneyDisplayFormat = DEFAULT
): String!
"""
The amount of money in the smallest denomination of the target currency.
In `USD`, for example, this represents cents. However, for zero-decimal currencies, this will match the `amount`.
"""
lowestDenominationAmount: Int!
}
"""Used to change the format when displaying money as a formatted string"""
enum MoneyDisplayFormat {
"""
The accounting format, where negative numbers will be wrapped in parentheses instead of prefixed with a `-` sign.
"""
ACCOUNTING
"""
The default format, where negative numbers are prefixed with a `-` sign.
"""
DEFAULT
}
"""
Represents an amount of money, e.g. an account balance which may be positive or negative.
"""
input MoneyInput {
"""
The ISO-4217 currency associated with this money. Note that only `USD` is supported at this time.
"""
currency: Currency!
"""
The amount of money in the smallest denomination of the target currency.
In `USD`, for example, this represents cents.
"""
lowestDenominationAmount: Int!
}
"""
Mutations describe the actions you can perform to modify data in our GraphQL API.
"""
type Mutation {
"""Create a new Benefit"""
createBenefit(input: CreateBenefitInput!): CreateBenefitResponse
"""Create a new Benefits Program"""
createBenefitsProgram(input: CreateBenefitsProgramInput!): CreateBenefitsProgramResponse
"""Create Individual"""
createIndividual(input: CreateIndividualInput!): CreateIndividualResponse
"""Create a new Organization"""
createOrganization(input: CreateOrganizationInput!): CreateOrganizationResponse
"""Enroll an Individual in a Benefit"""
enrollIndividualInBenefit(input: EnrollIndividualInBenefitInput!): EnrollIndividualInBenefitResponse
"""
Adds an amount of funds to a Benefit for an Individual. On success, the total funds available to the Individual
in this Benefit is increased by the amount specified in the request.
"""
fundBenefitForIndividual(input: FundBenefitForIndividualInput!): FundBenefitForIndividualResponse
"""
Submits a report generation request. Report generation is asynchronous, so the generated reports can be retrieved
by polling the `report` query for updated status and results.
"""
generateReport(input: GenerateReportInput!): GenerateReportResponse
"""
Sets the initial contributions for a Benefit and Individual. This operation is only available for Benefits with a pending status.
"""
setInitialContributionsForBenefitAndIndividual(input: SetInitialContributionsForBenefitAndIndividualInput!): SetInitialContributionsForBenefitAndIndividualResponse
"""
Sets the recurring contribution schedule for a Benefit. This operation is only available for Benefits
that support recurring contributions.
"""
setRecurringContributionScheduleForBenefit(input: SetRecurringContributionScheduleForBenefitInput!): SetRecurringContributionScheduleForBenefitResponse
"""
Sets the recurring contributions for a Benefit and Individual. This operation is only available for Benefits
that support recurring contributions.
"""
setRecurringContributionsForBenefitAndIndividual(input: SetRecurringContributionsForBenefitAndIndividualInput!): SetRecurringContributionsForBenefitAndIndividualResponse
"""
Transfers an Individual's Benefit Enrollment from one Organization to another. This operation is only available
for HSA Benefits.
"""
transferBenefitForIndividual(input: TransferBenefitForIndividualInput!): TransferBenefitForIndividualResponse
"""
Unenroll an individual from a Benefit.
If the Benefit Enrollment is an HSA, this API is unavailable. 'transferBenefitForIndividual' should be
used instead.
"""
unenrollIndividualFromBenefit(input: UnenrollIndividualFromBenefitInput!): UnenrollIndividualFromBenefitResponse
"""Update an existing Benefit"""
updateBenefit(input: UpdateBenefitInput!): UpdateBenefitResponse
"""Update an existing Benefits Program"""
updateBenefitsProgram(input: UpdateBenefitsProgramInput!): UpdateBenefitsProgramResponse
"""Update an existing Individual"""
updateIndividual(input: UpdateIndividualInput!): UpdateIndividualResponse
"""Update an existing Organization"""
updateOrganization(input: UpdateOrganizationInput!): UpdateOrganizationResponse
"""Creates a new Verification for an Individual"""
verifyIndividual(input: VerifyIndividualInput!): VerifyIndividualResponse
}
"""A string that cannot be passed as an empty value"""
scalar NonEmptyString
"""
The directions in which a list of items can be ordered when providing an `orderBy` argument.
"""
enum OrderDirection {
"""Sort by ascending order."""
ASC
"""Sort by descending order."""
DESC
}
"""
An Organization manages Benefits Programs on behalf of Individuals. An example of an Organization
is an employer, a charity, etc. An Organization has a relationship (e.g. employer-employee) with Individuals.
Organizations are typically customers of the API consumer.
"""
type Organization {
"""The unique ID for the Organization"""
id: ID!
"""The user-displayable name of the Organization"""
name: String!
"""A short code that uniquely identifies the Organization"""
shortCode: String! @deprecated(reason: "Use id instead")
}
"""Filter criteria used when querying for an Organization"""
input OrganizationFilterInput {
"""The ID of the Organization"""
id: ID!
}
"""
A union representing the possible return types when querying for an Organization
"""
union OrganizationResponse = BadRequestError | InternalServerError | Organization
"""Filter criteria used when querying for Organizations"""
input OrganizationsFilterInput {
"""If specified, only returns Organizations matching these IDs"""
ids: [ID!]
"""If specified, only returns Organizations matching these names"""
names: [String!]
}
"""
A union representing the possible return types when querying for Organizations
"""
union OrganizationsResponse = BadRequestError | InternalServerError | OrganizationsResults
"""Represents a page of Organizations"""
type OrganizationsResults {
nodes: [Organization!]!
pageInfo: PageInfo!
}
"""Metadata used when paging over a list of items"""
type PageInfo {
"""
When paging forward, this cursor is used to continue. It should be the cursor belonging to the last item in the previous page
"""
endCursor: String
"""
When paging forward, this flag indicates whether there are more items in the list
"""
hasNextPage: Boolean!
}
"""Input type used when paging over a list of items"""
input PageInput {
"""When paging forward, retrieve items after this cursor"""
after: String
"""
When paging forward, indicates the number of items to retrieve after the cursor
"""
first: Int
}
"""
A field whose value conforms to the standard E.164 format as specified in: https://en.wikipedia.org/wiki/E.164. Basically this is +17895551234.
"""
scalar PhoneNumber
"""A physical address"""
type PhysicalAddress {
"""The first line of an address e.g. `123 Main St`"""
addressLine1: String!
"""The second line of an address e.g. `Apt 111`"""
addressLine2: String
"""The city e.g. `Austin`"""
city: String!
"""The country e.g. `USA`"""
country: CountryCode
"""The state e.g. `Texas`"""
state: String!
"""The zip code e.g. `78704`"""
zip: PostalCode!
}
"""A physical address"""
input PhysicalAddressInput {
"""The first line of an address e.g. `123 Main St`"""
addressLine1: String!
"""The second line of an address e.g. `Apt 111`"""
addressLine2: String
"""The city e.g. `Austin`"""
city: String!
"""The country e.g. `USA`"""
country: CountryCode
"""The two letter state code e.g. `TX`"""
state: String!
"""The zip code e.g. `78704`"""
zip: PostalCode!
}
"""
A field whose value conforms to the standard postal code formats for United States, United Kingdom, Germany, Canada, France, Italy, Australia, Netherlands, Spain, Denmark, Sweden, Belgium, India, Austria, Portugal, Switzerland or Luxembourg.
"""
scalar PostalCode
"""Queries describe the data you can retrieve from our GraphQL API."""
type Query {
"""Returns a Benefit by ID"""
benefit(where: BenefitFilterInput!): BenefitResponse
"""Returns Benefit Templates"""
benefitTemplates(
"""Return the elements in the list that come after the specified cursor"""
after: String
"""The number of elements to retrieve per page"""
first: Int = 100
"""Filter criteria used to match benefit templates"""
where: BenefitTemplatesFilterInput
): BenefitTemplatesResponse
"""Returns a Benefits Program by ID"""
benefitsProgram(where: BenefitsProgramFilterInput!): BenefitsProgramResponse
"""Returns Benefits Programs matching the filter criteria"""
benefitsPrograms(
"""Return the elements in the list that come after the specified cursor"""
after: String
"""The number of elements to retrieve per page"""
first: Int = 100
"""Filter criteria used to match Benefits Programs"""
where: BenefitsProgramsFilterInput
): BenefitsProgramsResponse
"""Returns an Individual by ID"""
individual(where: IndividualFilterInput!): IndividualResponse
"""Returns an Individual by ID"""
individuals(
"""Return the elements in the list that come after the specified cursor"""
after: String
"""The number of elements to retrieve per page"""
first: Int = 100
"""Filter criteria used to match Individuals"""
where: IndividualsFilterInput
): IndividualsResponse
"""Returns an Organization by ID"""
organization(where: OrganizationFilterInput!): OrganizationResponse
"""Returns Organizations matching the filter criteria"""
organizations(
"""Return the elements in the list that come after the specified cursor"""
after: String
"""The number of elements to retrieve per page"""
first: Int = 100
"""Filter criteria used to match Organizations"""
where: OrganizationsFilterInput
): OrganizationsResponse
"""A simple ping query to test the API."""
ping: String
"""
Retrieves a report that was previously generated with the `generateReport` mutation. Note that if the report is still
being processed that the status field on the `ReportExecution` object will indicate this, and the data in the
`results` field will be null. Thus, this method can be polled to determine when report generation is complete.
"""
report(
"""
Specifies the page of the report to be returned, if report generation is complete. Since reports may be large, they
are generated page-by-page with a standard row count and and thus don't use cursor-based paging, instead they use
page-number based retrieval to return the specified pre-generated page. The page number is 1-based. If this value is
not specified, the first page will be returned in the `results` field if report generation is complete.
"""
page: Int
"""The ReportFilterInput specifies which report execution to retrieve."""
where: ReportFilterInput!
): ReportResponse
"""Returns a Verification by ID"""
verification(where: VerificationFilterInput!): VerificationResponse
}
"""A recurring contribution for an account"""
type RecurringContribution {
"""The amount of the employee's recurring contribution"""
employeeContributionAmount: Money!
"""
The amount of the employer's recurring contribution on behalf of the employee
"""
employerContributionAmount: Money!
}
enum RecurringContributionScheduleEnablementStatus {
"""The recurring contribution schedule is active"""
ACTIVE
"""The recurring contribution schedule is not active"""
INACTIVE
}
input RecurringContributionScheduleInput {
"""
The day of the month on which the contributions will be made. Required if the strategy is 'MONTHLY'.
"""
dayOfMonth: Int
"""
The earliest date on which the recurring contributions can begin. The schedule will run the first date that corresponds to the schedule strategy and strategyOption that is on or after this date. If this is before the benefit start date, the contributions will not begin until on or after the benefit start date.
"""
minRunDate: LocalDate!
"""The frequency at which the contributions will be made"""
strategy: RecurringContributionStrategy!
"""
Determines the days of the month on which the contributions will be made. Required if the strategy is 'SEMI_MONTHLY'. Do not set otherwise.
"""
strategyOption: RecurringContributionStrategyOption
}
"""
An enum representing the possible options for the strategy used to schedule recurring contributions
"""
enum RecurringContributionStrategy {
"""Contributions are made on a monthly basis"""
MONTHLY
"""
Contributions are made 2 times each month. When this option is set, the 'strategyOption' field must also be set.
"""
SEMI_MONTHLY
}
"""
An enum representing the possible options for the strategy used to schedule recurring contributions
"""
enum RecurringContributionStrategyOption {
"""Contributions are made on the 15th and last day of each month"""
FIFTEENTH_AND_LAST_DAY
"""Contributions are made on the 1st and 15th of each month"""
FIRST_AND_FIFTEENTH
}
"""Report contains information about a generated report."""
type Report {
"""
If requested, this field will be populated with links to download the individual CSV pages of the report. Importantly,
the behavior of this field is a bit different compared to the `results` field based on the `page` input parameter.
If the `page` input parameter was not specified at all, this field will include links for ALL pages of the report
(as these are just links, paging is not as much of a concern here). If the page number WAS specified, this field
will only include the link to that single page.
"""
downloadLinks: [DownloadLink!]
"""
This field contains metadata about the current status of report generation, and fields originally passed in to
generate the report.
"""
execution: ReportExecution!
"""
Contains the actual data result rows for the report. Note that if `reportExecution.status` is not `SUCCEEDED`, this
field will be null. The results here will only be for the page requested (if page was not specified, the
first page will be returned).
"""
results: ReportResults
}
"""
This is the success return type from `generateReport`, and it contains metadata that uniquely identifies the
report generation request, as well as the current status of report generation.
"""
type ReportExecution {
"""
A unique identifier for this report generation request. This value is also passed back to the `report` query
endpoint to retrieve the results for a report.
"""
id: ID!
"""
The original value for the code that was passed in with the report generation request, which identifies which
report was run.
"""
reportCode: String!
"""
The original parameters, if any, passed in to this report generation request.
"""
reportParameters: JSONObject
"""The human-readable descriptive title of this report."""
reportTitle: String!
"""
The original requested columns, if specified, for this report generation request.
"""
requestedColumns: [String!]
"""The current status of the report generation request."""
status: ReportExecutionStatus!
}
"""
The enum states the possible values for the status of the generated report.
"""
enum ReportExecutionStatus {
"""Report execution has completed, but has failed."""
FAILED
"""
Report execution has not yet begun processing, e.g. it may be queued and waiting to run.
"""
NOT_STARTED
"""Report execution is currently processing."""
PROCESSING
"""Report execution has successfully completed processing."""
SUCCEEDED
}
"""
Filter criteria used when retrieving the results for a generated report.
"""
input ReportFilterInput {
"""
The ID of the report execution whose results are to be retrieved, originally returned by the `generateReport` mutation.
"""
id: ID!
}
"""The possible return types when retrieving a generated report."""
union ReportResponse = BadRequestError | InternalServerError | Report
"""
ReportResults represents a single result page containing the data output from a report generation.
"""
type ReportResults {
"""The column header names in the report."""
columnHeaders: [String!]!
"""
The report data is returned as an array of JSON objects. The keys in the object will match the
`columnHeader` names.
"""
rows: [JSONObject!]!
"""The total number of pages for this generated report"""
totalPages: Int!
}
"""
In the US, an ABA routing transit number (`ABA RTN`) is a nine-digit code to identify the financial institution.
"""
scalar RoutingNumber
"""
The `SafeInt` scalar type represents non-fractional signed whole numeric values that are considered safe as defined by the ECMAScript specification.
"""
scalar SafeInt
"""
An input type used when setting initial contributions for a benefit and individual
"""
input SetInitialContributionsForBenefitAndIndividualInput {
"""
The ID of the Benefit for which the initial contributions are being set
"""
benefitId: ID!
"""
The amount of funds from an employee to be made as an initial contribution to the Benefit. This must be positive, non-zero amount.
"""
employeeInitialContributionAmount: MoneyInput!
"""
The amount of funds from an employer to be made as an initial contribution to the Benefit. This must be positive, non-zero amount.
"""
employerInitialContributionAmount: MoneyInput!
"""
The ID of the Individual who will be receiving the initial contributions
"""
individualId: ID!
}
"""
A union representing the possible return types when setting initial contributions for a benefit and individual
"""
union SetInitialContributionsForBenefitAndIndividualResponse = BadRequestError | InternalServerError | SetInitialContributionsForBenefitAndIndividualResult
"""
The successful result of setting initial contributions for a benefit and individual
"""
type SetInitialContributionsForBenefitAndIndividualResult {
"""The ID of the Benefit for which the initial contributions were set"""
benefitId: ID!
"""
The ID of the Individual who will be receiving the initial contributions
"""
individualId: ID!
}
input SetRecurringContributionScheduleForBenefitInput {
"""
The ID of the Benefit for which the recurring contributions are being set
"""
benefitId: ID!
"""
Whether or not to enable the recurring contribution schedule. Defaults to 'ACTIVE'.
"""
enablementStatus: RecurringContributionScheduleEnablementStatus
"""The schedule for the recurring contributions"""
schedule: RecurringContributionScheduleInput!
}
"""
A union representing the possible return types when setting the recurring contribution schedule for a benefit
"""
union SetRecurringContributionScheduleForBenefitResponse = BadRequestError | InternalServerError | SetRecurringContributionScheduleForBenefitResult
"""
The successful result of setting the recurring contribution schedule for a benefit
"""
type SetRecurringContributionScheduleForBenefitResult {
"""
The ID of the Benefit for which the recurring contribution schedule was set
"""
benefitId: ID!
}
"""
An input type used when setting recurring contributions for a benefit and individual
"""
input SetRecurringContributionsForBenefitAndIndividualInput {
"""
The ID of the Benefit for which the recurring contributions are being set
"""
benefitId: ID!
"""
The amount of funds from an employee to be contributed on a recurring schedule to the Benefit. This must be positive, non-zero amount.
"""
employeeRecurringContributionAmount: MoneyInput!
"""
The amount of funds from an employer to be contributed on a recurring schedule to the Benefit. This must be positive, non-zero amount.
"""
employerRecurringContributionAmount: MoneyInput!
"""
The ID of the Individual who will be receiving the recurring contributions
"""
individualId: ID!
}
"""
A union representing the possible return types when setting recurring contributions for a benefit and individual
"""
union SetRecurringContributionsForBenefitAndIndividualResponse = BadRequestError | InternalServerError | SetRecurringContributionsForBenefitAndIndividualResult
"""
The successful result of setting recurring contributions for a benefit and individual
"""
type SetRecurringContributionsForBenefitAndIndividualResult {
"""The ID of the Benefit for which the recurring contributions were set"""
benefitId: ID!
"""
The ID of the Individual who will be receiving the recurring contributions
"""
individualId: ID!
}
"""
Languages supported by First Dollar
These are cased according to the ISO standard language format.
"""
enum SupportedLanguage {
"""English"""
en
"""Spanish (United States)"""
es_US
}
"""
A time string at UTC, such as 10:15:30Z, compliant with the `full-time` format outlined in section 5.6 of the RFC 3339profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.
"""
scalar Time
"""
A field whose value exists in the standard IANA Time Zone Database: https://www.iana.org/time-zones
"""
scalar TimeZone
"""
The javascript `Date` as integer. Type represents date and time as number of milliseconds from start of UNIX epoch.
"""
scalar Timestamp
"""A Transaction posted against an Account."""
type Transaction {
"""
The amount of the Transaction. Positive values indicate a credit while negative values indicate a debit
"""
amount: Money!
"""The balance of the Account immediately after this Transaction"""
balance: Money!
"""The Date of the Transaction"""
date: LocalDate!
"""A description of the Transaction"""
description: String!
"""The ID of the Transaction"""
id: ID!
"""A timestamp of the Transaction, if available"""
timestamp: DateTime
"""The `type` of the Transaction"""
type: TransactionType!
}
"""Represents a page of Transactions against an Account"""
type TransactionResults {
"""The Transactions in this page"""
nodes: [Transaction!]!
"""Pagination metadata"""
pageInfo: PageInfo!
}
"""
Transactions are labeled with a `type` attribute, categorizing the transaction according to its purpose and features.
"""
enum TransactionType {
"""
A Deposit is a settled transaction that increases the current and available balance of a Ledger Account.
"""
DEPOSIT
"""
A Hold is a pending transaction that has, by definition, not settled. A Hold increases or reduces the current balance of
a Ledger Account, leaving available balance unchanged.
"""
HOLD
"""
A Hold Release is a pending transaction that releases (reverses) a Hold. Since it is a pending transaction type, it alters
the current balance of a Ledger Account, leaving available balance unchanged.
"""
HOLD_RELEASE
"""
A Withdrawal is a settled transaction that decreases the current and available balance of a Ledger Account.
"""
WITHDRAWAL
}
"""Filter criteria used when querying for Transactions"""
input TransactionsFilterInput {
"""
When specified, only returns transactions that occurred after the specified DateTime.
"""
after: DateTime
"""
When specified, only returns transactions that occurred before the specified DateTime.
"""
before: DateTime
"""
The `view` to use when returning transactions. If unspecified, defaults to "pending and settled" transactions.
"""
view: TransactionsFilterView = PENDING_AND_SETTLED
}
"""
A `TransactionsFilterView` defines the "view" of returned transactions. Depending on the selected "view",
certain transactions may be included or excluded from the results.
"""
enum TransactionsFilterView {
"""Includes all transactions for the specified account."""
ALL
"""
Includes "pending" transactions (holds which have not been released) and "settled" transactions.
"""
PENDING_AND_SETTLED
}
"""An input type used when transferring a Benefit for an Individual"""
input TransferBenefitForIndividualInput {
"""The ID of the Benefit the Individual is currently enrolled in"""
benefitId: ID!
"""The ID of the Individual whose enrollment will be transferred"""
individualId: ID!
"""The ID of the Benefit receiving the enrollment transfer"""
transferBenefitId: ID!
}
"""
A union representing the possible return types when transferring a Benefit for an Individual
"""
union TransferBenefitForIndividualResponse = BadRequestError | InternalServerError | TransferBenefitForIndividualResult
"""The successful result of transferring a Benefit for an Individual"""
type TransferBenefitForIndividualResult {
"""The Benefit that the enrollment was transferred out of"""
benefit: Benefit!
"""The Individual whose enrollment was transferred"""
individual: Individual!
"""The Benefit that the enrollment was transferred to"""
transferBenefit: Benefit!
}
"""
A field whose value conforms to the standard URL format as specified in RFC3986: https://www.ietf.org/rfc/rfc3986.txt.
"""
scalar URL
"""
A field whose value is a generic Universally Unique Identifier: https://en.wikipedia.org/wiki/Universally_unique_identifier.
"""
scalar UUID
"""An input type used when unenrolling an individual from a benefit"""
input UnenrollIndividualFromBenefitInput {
"""The ID of the benefit the individual is enrolled in"""
benefitId: ID!
"""
The date (YYYY-MM-DD) when unenrollment becomes effective. If unspecified, this request is immediately
effective as of the current date.
"""
effectiveAt: LocalDate
"""The ID of the individual to unenroll from the benefit"""
individualId: ID!
}
"""
A union representing the possible return types when unenrolling an individual from a benefit
"""
union UnenrollIndividualFromBenefitResponse = BadRequestError | InternalServerError | UnenrollIndividualFromBenefitResult
"""The successful result of unenrolling an individual from a benefit"""
type UnenrollIndividualFromBenefitResult {
"""The benefit"""
benefit: Benefit!
"""The individual that was unenrolled from the benefit"""
individual: Individual!
}
"""An input type used when updating a benefit"""
input UpdateBenefitInput {
"""The ID of the benefit to update"""
id: ID!
"""A human-readable name for the benefit"""
name: String
}
"""A union representing the possible return types when updating a benefit"""
union UpdateBenefitResponse = BadRequestError | InternalServerError | UpdateBenefitResult
"""The successful result of updating a benefit"""
type UpdateBenefitResult {
"""The benefit that was updated"""
benefit: Benefit!
}
"""An input type used when updating a benefits program"""
input UpdateBenefitsProgramInput {
"""The ID of the program to update"""
id: ID!
"""The name of the program"""
name: String
}
"""
A union representing the possible return types when updating a benefits program
"""
union UpdateBenefitsProgramResponse = BadRequestError | InternalServerError | UpdateBenefitsProgramResult
"""The successful result of updating a benefits program"""
type UpdateBenefitsProgramResult {
"""The program that was updated"""
benefitsProgram: BenefitsProgram!
}
"""An input type used for updating an Individual"""
input UpdateIndividualInput {
"""A new address for the Individual, if applicable"""
address: PhysicalAddressInput
"""A new date of birth for the Individual, if applicable"""
dateOfBirth: LocalDate
"""A new email address for the Individual, if applicable"""
email: EmailAddress
"""The ID of the Individual to update"""
id: ID!
"""A new language preference for the Individual, if applicable"""
language: SupportedLanguage
"""A new mailing address for the Individual, if applicable"""
mailingAddress: PhysicalAddressInput
"""A new name for the Individual, if applicable"""
name: IndividualNameInput
"""A new phone number for the Individual, if applicable"""
phoneNumber: PhoneNumber
"""A new Tax Identification Number for the Individual, if applicable"""
tin: String
}
"""
A union representing the possible return types when updating an Individual
"""
union UpdateIndividualResponse = BadRequestError | InternalServerError | UpdateIndividualResult
"""The successful result of updating an Individual"""
type UpdateIndividualResult {
"""The Individual that was updated"""
individual: Individual!
}
"""An input type used when updating an Organization"""
input UpdateOrganizationInput {
"""The ID of the Organization to update"""
id: ID!
"""The user-displayable name of the Organization to update"""
name: String!
}
"""
A union representing the possible return types when updating an Organization
"""
union UpdateOrganizationResponse = BadRequestError | InternalServerError | UpdateOrganizationResult
"""The successful result of updating an Organization"""
type UpdateOrganizationResult {
"""The Organization that was updated"""
organization: Organization!
}
"""
A field whose value is a UTC Offset: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
"""
scalar UtcOffset
"""A Verification"""
type Verification {
"""The ID of the Verification"""
id: ID!
"""The status of the Verification."""
status: VerificationStatus!
"""
If present, these verification codes indicate specific facts about the verification and can be used to understand
how it entered its current state.
"""
verificationCodes: [String!]!
}
"""Filter criteria used when querying for a Verification"""
input VerificationFilterInput {
"""The ID of the Verification"""
id: ID!
}
"""
A union representing the possible return types when querying for a Verification
"""
union VerificationResponse = BadRequestError | InternalServerError | Verification
"""A status that summarizes the state of a verification for an entity."""
enum VerificationStatus {
"""
The entity was verified, and aspects of automated verification require review.
"""
NEEDS_REVIEW
"""
The entity was verified, and based on the results, was "rejected' by the system.
Any system component requiring a valid verification will not accept a verification
in this status.
"""
REJECTED
"""The entity has not yet been verified."""
UNVERIFIED
"""
The entity was successfully verified, either via automation or manual review.
"""
VERIFIED
}
"""A request to Verify an Individual"""
input VerifyIndividualInput {
"""A unique idempotency key for this request."""
idempotencyKey: String!
"""The ID of the Individual to Verify."""
individualId: ID!
}
"""
A union representing the possible return types when verifying an Individual
"""
union VerifyIndividualResponse = BadRequestError | InternalServerError | VerifyIndividualResult
"""The successful result of Verifying an Individual."""
type VerifyIndividualResult {
"""The Individual under verification."""
individual: Individual!
"""The verification created for the Individual."""
verification: Verification!
}
"""Represents NULL values"""
scalar Void