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
34 Queries
Mutations
Actions you can perform to modify data in our API
54 Mutations
Schema-Defined Types
All types in our GraphQL schema fall into one of the following categories:
Objects
The entities in our GraphQL schema
130 Objects
Interfaces
Abstract types that other types inherit from
1 Interfaces
Enums
The enumeration types
44 Enums
Unions
The unions in our GraphQL schema
77 Unions
Inputs
Used to provide data to an operation
90 Inputs
Scalars
The primitives in our GraphQL schema
31 Scalars
GraphQL Schema (SDL)
Download the schema at https://developer.firstdollar.com/partner.schema.graphqlschema.graphql
"""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 annual election amount for this account enrollment.
Null for enrollments without an election amount set.
Only applicable for HSA and FSA account types, for now.
This will change when we add support for additional account types.
"""
electionAmount: 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 full, unmasked account number associated with the HSA account for the individual, if available
"""
hsaAccountNumber: String
"""
The routing number associated with the HSA account for the individual, if available
"""
hsaRoutingNumber: String
"""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
input ActivateCardInput {
"""The ID of the card to activate."""
cardId: ID!
"""
When specified, the operation only proceeds if the card belongs to this
Individual; otherwise it returns the standard not-found response.
"""
individualId: ID
}
union ActivateCardResponse = ActivateCardResult | BadRequestError | InternalServerError
type ActivateCardResult {
"""The activated card."""
card: Card!
}
input AddBrokerToFirmInput {
brokerageFirmUlid: ID!
email: EmailAddress!
firstName: String!
isFirmAdmin: Boolean!
lastName: String!
phone: PhoneNumber
}
union AddBrokerToFirmResponse = AddBrokerToFirmResult | BadRequestError | InternalServerError
type AddBrokerToFirmResult {
brokerUid: ID
brokerageFirmUlid: ID!
inviteStatus: BrokerInviteStatus
status: AddBrokerToFirmStatus!
}
enum AddBrokerToFirmStatus {
"""
The email is already an active member of this firm. A non-null invite status means this active broker has never signed in and an invite was attempted, independently of whether claims needed repair.
"""
ALREADY_ACTIVE_MEMBER
"""The broker identity and active firm membership were created."""
CREATED
"""
The email belongs to an existing First Dollar identity that cannot be added to this firm.
"""
EMAIL_ALREADY_EXISTS
"""
The email has an inactive membership in this firm; it is not reactivated automatically.
"""
INACTIVE_MEMBERSHIP
}
"""An Individual's tax forms for a single tax year."""
type AnnualTaxForms {
"""Informational forms, not filed with the IRS."""
informationalForms: [IndividualTaxForm!]!
"""Forms that are (or will be) filed with the IRS."""
requiredForms: [IndividualTaxForm!]!
"""The tax year these forms cover (e.g. "2026")."""
taxYear: YearString!
}
input ApproveClaimInput {
"""
The portion of the expense approved as eligible, in `USD`. Defaults to the full `amount`. Must be
positive and no more than `amount`. A lower amount is a partial approval, which requires
`partialDenial`. Partial approval returns `FEATURE_NOT_ENABLED` unless it is enabled for this
partner.
"""
approvedAmount: MoneyInput
"""The ID of the claim to approve."""
claimId: ID!
"""
A note added to the claim's notes, which the Individual and administrators can read.
"""
note: String
"""
Why the portion of the expense above `approvedAmount` is denied. Required for a partial approval, and not accepted otherwise.
"""
partialDenial: ClaimDenialInput
}
"""The possible results of approving a claim."""
union ApproveClaimResponse = ApproveClaimResult | BadRequestError | InternalServerError
type ApproveClaimResult {
"""The approved claim."""
claim: Claim!
}
"""An input type used when assigning organizations to a brokerage firm"""
input AssignOrganizationsToFirmInput {
"""The brokerage firm's identifier, as returned by `BrokerageFirm.id`"""
firmId: ID!
"""
Public ULIDs of the organizations to assign. Matched exactly and case-sensitively; organization
short codes are not accepted. Duplicates are collapsed to a single write but still produce one
result element each. Maximum 250 per request.
"""
organizationUlids: [ID!]!
}
"""
Union representing possible return types when assigning organizations to a brokerage firm
"""
union AssignOrganizationsToFirmResponse = AssignOrganizationsToFirmResult | BadRequestError | InternalServerError
"""
The result of assigning organizations to a brokerage firm. Returned even when every element failed —
the per-element `status` carries the outcome.
"""
type AssignOrganizationsToFirmResult {
"""
One element per submitted organization, in the order they were submitted. A duplicate identifier
produces one element per occurrence, each carrying the outcome of the single write it caused.
"""
organizationAssignments: [OrganizationAssignmentResult!]!
}
"""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!
"""
Active coverage levels configured for this offering, ordered by displayOrder.
"""
coverageLevels: [CoverageLevel!]!
"""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 product code recorded for this Benefit's type on an external platform, such as the code the
platform uses to identify the account type in its own systems. Null when no code is recorded for
that platform. Codes are shared by every Benefit created from the same template.
Without `platformId`, the code on your only linked external platform is returned. If your account
is linked to no platform or to more than one, `platformId` is required and its omission is
rejected as a GraphQL error with extension code `BAD_USER_INPUT`, with this field resolving to
null.
"""
productCode(
"""
The external platform whose product code to return, as an `id` returned by
`linkedExternalPlatforms`. A value that is not one of your linked platform IDs is rejected as
a GraphQL error with extension code `BAD_USER_INPUT`, and the field resolves to null. May be
omitted when exactly one platform is linked to your account.
"""
platformId: ID
): 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
"""
Traditional Health Reimbursement Arrangement with per-participant funding limits
"""
TRADITIONAL_HRA
}
"""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
"""Filter criteria used when querying for a single brand"""
input BrandFilterInput {
"""The brand identifier to look up, as returned by the `brands` query"""
name: ID!
}
"""
A union representing the possible return types when querying for a single brand
"""
union BrandResponse = BadRequestError | InternalServerError | PartnerBrand
"""
A union representing the possible return types when querying for the calling partner's brands
"""
union BrandsResponse = BrandsResults | InternalServerError
"""The set of brands available to the calling partner"""
type BrandsResults {
"""
The brands available to the calling partner. Each distinct brand appears exactly once.
"""
nodes: [PartnerBrand!]!
}
enum BrokerInviteStatus {
"""Provisioning succeeded, but the selected invitation route failed."""
FAILED
"""
The selected invitation route returned success; this does not mean the email was delivered.
"""
SENT
"""No broker invitation route was enabled."""
SKIPPED
}
"""
A brokerage firm. The Broker-of-Record relationship is with the firm, not with individual brokers.
"""
type BrokerageFirm {
"""
The Employer Identification Number of the firm, in canonical `XX-XXXXXXX` form.
For a firm created without an EIN this is a placeholder: `18-` followed by seven digits, issued by
First Dollar. The IRS does not issue EINs starting with 18, so a placeholder never equals a real EIN.
It identifies the firm but is not a tax identifier. See `einIsPlaceholder`.
"""
ein: String!
"""
True when `ein` is a placeholder issued for a firm created without an EIN, not a real EIN
"""
einIsPlaceholder: Boolean!
"""The unique identifier of the brokerage firm"""
id: ID!
"""The date and time the firm was deactivated, or null if it is active"""
inactiveAt: DateTime
"""The legal or display name of the firm"""
name: String!
}
type BrokerageFirmBroker {
email: EmailAddress!
firstName: String!
isFirmAdmin: Boolean!
lastName: String!
}
"""How `createBrokerageFirm` found a firm that already existed"""
enum BrokerageFirmMatchedBy {
"""The firm holds the EIN the request supplied."""
EIN
"""
The request had no EIN, and its normalized name matched exactly this firm. Nothing was attached;
confirm the match with `assignOrganizationsToFirm`.
"""
NAME
}
type BrokerageFirmOrganization {
id: ID!
name: String!
}
union BrokerageFirmsResponse = BadRequestError | BrokerageFirmsResults | InternalServerError
type BrokerageFirmsResults {
nodes: [VisibleBrokerageFirm!]!
pageInfo: PageInfo!
}
"""An input type used when cancelling a benefit"""
input CancelBenefitInput {
"""The ID of the benefit to cancel"""
benefitId: ID!
"""
A unique idempotency key for this request. Repeated calls with the same key return the prior result.
"""
idempotencyKey: String!
}
"""
A union representing the possible return types when cancelling a benefit
"""
union CancelBenefitResponse = BadRequestError | CancelBenefitResult
"""The successful result of cancelling a benefit"""
type CancelBenefitResult {
"""The benefit that was cancelled"""
benefit: Benefit!
}
input CancelCardInput {
"""The ID of the card to cancel."""
cardId: ID!
"""A key for ensuring request idempotency."""
idempotencyKey: String!
individualId: ID
"""The reason the card is being cancelled."""
reason: CardActionReason!
"""When true, issues a replacement card in the same operation."""
reissue: Boolean! = false
}
union CancelCardResponse = BadRequestError | CancelCardResult | InternalServerError
type CancelCardResult {
"""The ID of the cancelled card."""
cancelledCardId: ID!
"""
The ID of the replacement card, when `reissue` was true; otherwise null.
"""
reissuedCardId: ID
}
"""
A physical or virtual card issued to an Individual for a Benefits Program.
"""
type Card {
"""The Benefits Program this card draws from."""
benefitsProgramId: ID!
"""The full name of the cardholder."""
cardholderName: PersonName!
"""The card expiration in MMYY format."""
expiration: String!
"""
Where a physical card is on its journey to the cardholder, or DIGITAL for virtual cards.
"""
fulfillmentStatus: CardFulfillmentStatus!
"""The ID of the card, used for all operations against the card."""
id: ID!
"""The Individual this card belongs to."""
individualId: ID!
"""The last four digits of the card number."""
last4: String!
"""The current status of the card."""
status: CardStatus!
"""Whether the card is physical or virtual."""
type: CardType!
"""Whether the cardholder is the account holder or a dependent."""
userType: CardUserType!
}
"""The reason a card is being locked or cancelled."""
enum CardActionReason {
"""
The cardholder reports one or more transactions as fraudulent. A lock with
this reason is permanent: the card cannot be unlocked afterwards and must be
cancelled (optionally with a replacement via `cancelCard`'s `reissue`).
"""
FRAUDULENT_CHARGES
"""The cardholder lost physical access to the card."""
LOST
"""Another, unlisted reason."""
OTHER
"""The cardholder reports the card as stolen."""
STOLEN
}
input CardFilterInput {
"""The ID of the card."""
id: ID!
"""
When specified, the card is only returned if it belongs to this Individual.
A card that exists but belongs to a different Individual returns the same
not-found response as a card that does not exist.
"""
individualId: ID
}
"""Where a card is on its journey to the cardholder."""
enum CardFulfillmentStatus {
"""A virtual card is available digitally."""
DIGITAL
"""The card has been issued."""
ISSUED
"""A physical card has been ordered."""
ORDERED
"""Physical card fulfillment was rejected."""
REJECTED
"""A physical card has been re-ordered."""
REORDERED
"""A physical card has been shipped."""
SHIPPED
}
union CardResponse = BadRequestError | Card | InternalServerError
"""The lifecycle status of a card."""
enum CardStatus {
"""Active and usable."""
ACTIVE
"""Temporarily locked; transactions are blocked until unlocked."""
SUSPENDED
"""Permanently cancelled; cannot be reactivated."""
TERMINATED
"""Issued but not yet activated by the cardholder."""
UNACTIVATED
}
"""Whether a card is physical or virtual."""
enum CardType {
"""A physical card mailed to the cardholder for point-of-sale use."""
PHYSICAL
"""A virtual card for digital use."""
VIRTUAL
}
"""Whether the cardholder is the account holder or a dependent."""
enum CardUserType {
ACCOUNT_HOLDER
DEPENDENT
}
"""Controls which cardholders' cards a list query returns."""
enum CardUserTypeFilter {
"""Only the account holder's own cards (default)."""
ACCOUNT_HOLDER_ONLY
"""Only dependents' cards."""
DEPENDENTS_ONLY
"""Both the account holder's and their dependents' cards."""
INCLUDE_DEPENDENTS
}
input CardsFilterInput {
"""
When specified, only returns cards associated with these Benefits. A card
matches when the Benefit belongs to the same Benefits Program as the card.
"""
benefitIds: [ID!]
"""
When specified, only returns cards associated with Benefits of these types
(e.g. HSA). A card matches when its Benefits Program contains a Benefit of
one of these types.
"""
benefitTypes: [BenefitType!]
"""
When specified, only returns cards associated with these Benefits Programs.
"""
benefitsProgramIds: [ID!]
"""When specified, only returns these specific cards."""
cardIds: [ID!]
"""When specified, only returns cards belonging to these Individuals."""
individualIds: [ID!]
"""
When specified, only returns cards whose last four digits match one of these values.
"""
last4: [String!]
"""When specified, only returns cards in these statuses."""
statuses: [CardStatus!]
"""
When specified, only returns cards of these types (physical or virtual).
"""
types: [CardType!]
"""
Controls whether account-holder cards, dependent cards, or both are
returned. Defaults to account-holder cards only. A value other than
`ACCOUNT_HOLDER_ONLY` requires `individualIds`.
"""
userType: CardUserTypeFilter
}
union CardsResponse = BadRequestError | CardsResults | InternalServerError
type CardsResults {
nodes: [Card!]!
pageInfo: PageInfo!
}
"""
A request from an Individual to be reimbursed from a Benefit for an expense they paid. Amounts describe
the expense and the eligible portion of it; they are not a record of payments.
Errors returned by claim operations carry one of these codes:
- `NOT_FOUND`: the claim, Individual, Benefit, or document group does not exist or belongs to another
partner.
- `FEATURE_NOT_ENABLED`: claims, or the requested operation, are not enabled for this partner.
- `FORBIDDEN`: the credential is not permitted to perform the operation.
- `INVALID_CLAIM_STATUS`: the claim's current status does not allow the operation.
- `LINKED_BANK_ACCOUNT_REQUIRED`: the Individual has no verified primary linked bank account that is
ready to use; an account that must be relinked does not qualify.
- `BAD_REQUEST`: the input is not valid, or a claim rule rejected it, such as a date outside the
Benefit's claim period. The message describes the problem.
- `INTERNAL_SERVER_ERROR`: an unexpected error occurred.
"""
type Claim {
"""
The amount of the expense. Null, with an error for this field, when a stored amount includes a
fraction of a cent.
"""
amount: Money
"""
The portion of the expense approved as eligible. Null until the claim is approved. It can be less than
`amount` after a partial approval, and the reimbursement can be less than it when the Benefit
reimburses a percentage or applies a deductible.
"""
approvedAmount: Money
"""The Benefit the claim is reimbursed from."""
benefitId: ID!
"""
The Individual who received the service: the account holder or one of their dependents. Null for
some claims submitted before claimants were recorded.
"""
claimantId: ID
"""
Why the claim was denied. On an approved claim, why the portion of the expense above
`approvedAmount` was denied. Null when nothing was denied.
"""
denial: ClaimDenial
"""
The document group that holds the claim's documents. Null when the claim has no documents.
"""
documentGroupId: ID
"""The ID of the claim, used for all operations on the claim."""
id: ID!
"""The Individual (account holder) who is reimbursed for the claim."""
individualId: ID!
"""
The most recent request for more information about the claim. Null when none was made.
"""
informationRequest: ClaimInformationRequest
"""
The merchant for the expense. Null when the claim has a care provider instead.
"""
merchant: ClaimMerchant
"""
The Organization of the Individual's enrollment. For a member of a division, this is the division's
Organization.
"""
organizationId: ID!
"""
The care provider for the expense, such as a daycare. Null when the claim has a merchant instead.
"""
provider: ClaimProvider
"""The last date of the service, when recorded."""
serviceEndDate: LocalDate
"""The first date of the service, when recorded."""
serviceStartDate: LocalDate
"""The current status of the claim."""
status: ClaimStatus!
"""
When the claim's status last changed to a status other than `IN_REVIEW`. Null when that has not
happened since submission.
"""
statusUpdatedAt: DateTime
"""When the claim was submitted."""
submittedAt: DateTime!
"""The date the expense was paid."""
transactionDate: LocalDate!
}
"""Why a claim, or part of a claim, was denied."""
type ClaimDenial {
"""
More detail about the denial. Recorded for every reason on a partial approval, and only for `OTHER` on a denial.
"""
comment: String
"""The reason for the denial."""
reason: ClaimDenialReason!
}
"""Why a claim, or part of a claim, is denied."""
input ClaimDenialInput {
"""More detail about the denial. Required when `reason` is `OTHER`."""
comment: String
"""The reason for the denial. `UNSPECIFIED` is not accepted."""
reason: ClaimDenialReason!
}
"""
Why a claim, or part of a claim, is denied. New values can be added; handle an unknown value without failing.
"""
enum ClaimDenialReason {
"""The claim amount does not match the amount on the receipt."""
CLAIM_AMOUNT_RECEIPT_AMOUNT_MISMATCH
"""The claim date does not match the date on the receipt."""
CLAIM_DATE_RECEIPT_DATE_MISMATCH
"""The expense falls outside the Benefit's plan year."""
CLAIM_OUTSIDE_OF_PLAN_YEAR
"""The claimant is not covered by the Benefit."""
DEPENDENT_NOT_COVERED
"""The Individual is not eligible for the Benefit."""
INELIGIBLE_EMPLOYEE
"""The expense is not eligible for the Benefit."""
INELIGIBLE_EXPENSE
"""Another reason, described in the comment."""
OTHER
"""The receipt is missing or not valid."""
RECEIPT_MISSING_OR_INVALID
"""
No reason was recorded. Appears only on some earlier claims, and is not accepted as input.
"""
UNSPECIFIED
}
"""The file formats accepted for claim documents."""
enum ClaimDocumentContentType {
"""A HEIC image (`image/heic`)."""
HEIC
"""A HEIF image (`image/heif`)."""
HEIF
"""A JPEG image (`image/jpeg`)."""
JPEG
"""A PDF document (`application/pdf`)."""
PDF
"""A PNG image (`image/png`)."""
PNG
}
"""A file to upload."""
input ClaimDocumentFileInput {
"""
The format of the file. The upload must send the matching `Content-Type` header, which `requestHeaders` contains.
"""
contentType: ClaimDocumentContentType!
"""
The name of the file, without a path, such as `receipt.pdf`. At most 255 characters.
"""
fileName: NonEmptyString!
}
"""
A link for uploading one file. Treat the URL and headers as secrets: together they can write the file.
"""
type ClaimDocumentUpload {
"""When the link expires."""
expiresAt: DateTime!
"""The name of the file this link uploads."""
fileName: String!
"""
The headers to send with the `PUT` request, where the keys are header names and the values are header
values. Send every header unchanged; they include the file's content type and encryption key.
"""
requestHeaders: JSONObject!
"""The URL to `PUT` the file's bytes to."""
uploadUrl: URL!
}
input ClaimFilterInput {
"""The ID of the claim."""
id: ID!
}
"""A request for more information about a claim."""
type ClaimInformationRequest {
"""More detail about the request. Recorded only for `OTHER`."""
comment: String
"""The reason for the request."""
reason: ClaimInformationRequestedReason!
}
"""
What information is needed about a claim. New values can be added; handle an unknown value without failing.
"""
enum ClaimInformationRequestedReason {
"""The claim amount does not match the amount on the receipt."""
CLAIM_AMOUNT_RECEIPT_AMOUNT_MISMATCH
"""The claim date does not match the date on the receipt."""
CLAIM_DATE_RECEIPT_DATE_MISMATCH
"""The name on the receipt does not match the claimant."""
CLAIM_NAME_MISMATCH
"""Another reason, described in the comment."""
OTHER
"""The receipt cannot be read."""
RECEIPT_ILLEGIBLE
"""The receipt is missing or not valid."""
RECEIPT_MISSING_OR_INVALID
}
"""The merchant recorded for a claim."""
type ClaimMerchant {
"""The name of the merchant."""
name: String!
}
"""The merchant for a claim's expense."""
input ClaimMerchantInput {
"""The name of the merchant."""
name: NonEmptyString!
}
"""
A care provider recorded for a claim. A provider belongs to the Individual and can be used on several of their claims.
"""
type ClaimProvider {
"""
The ID of the provider. Use it in `ClaimProviderInput.id` to record the same provider on another claim for this Individual.
"""
id: ID!
"""The name of the provider."""
name: String!
"""
The kind of care the provider gives. Null for some providers recorded before categories existed.
"""
serviceCategory: ClaimProviderServiceCategory
}
"""
The care provider for a claim's expense. Specify `id` to use a provider already recorded for this
Individual, or `name` and `serviceCategory` to record a new one.
"""
input ClaimProviderInput {
"""
A provider already recorded for this Individual, from `ClaimProvider.id`. When specified, omit the other fields.
"""
id: ID
"""
The name of a new provider. In a correction, the corrected name for the claim's provider.
"""
name: NonEmptyString
"""
The kind of care the provider gives. Required for a new provider. In a correction, omit it to keep the
current category.
"""
serviceCategory: ClaimProviderServiceCategory
}
"""
The kind of care a provider gives. New values can be added; handle an unknown value without failing.
"""
enum ClaimProviderServiceCategory {
"""Daycare for adults."""
ADULT_DAYCARE
"""A program before or after school hours."""
BEFORE_AFTER_SCHOOL_PROGRAM
"""A caretaker, such as a nanny or babysitter."""
CARETAKER
"""Daycare for children."""
DAYCARE
"""A day camp."""
DAY_CAMP
"""A nursery school."""
NURSERY_SCHOOL
"""Another kind of care."""
OTHER
"""An overnight camp."""
OVERNIGHT_CAMP
"""A preschool."""
PRESCHOOL
}
"""The possible results of querying for a claim."""
union ClaimResponse = BadRequestError | Claim | InternalServerError
"""
The status of a claim. New values can be added; handle an unknown value without failing.
"""
enum ClaimStatus {
"""Approved, with reimbursement not yet started."""
APPROVED
"""Cancelled. Nothing is reimbursed. This API does not cancel claims."""
CANCELLED
"""Waiting for the Individual to supply more information."""
INFORMATION_REQUESTED
"""
Approved and waiting for Benefit funds to accrue before it is reimbursed. It can be partly reimbursed in the meantime.
"""
IN_ACCRUAL
"""Being reviewed."""
IN_REVIEW
"""
Approved as eligible, but the Benefit reimburses none of it, for example because a deductible is not yet met.
"""
OUT_OF_POCKET
"""Approved, with reimbursement complete."""
PAID
"""Approved, with reimbursement in progress."""
PAYMENT_PENDING
"""Submitted and waiting for review."""
PENDING
"""Denied. Nothing is reimbursed."""
REJECTED
"""Resubmitted with more information and waiting for review."""
RESUBMITTED
}
input ClaimsFilterInput {
"""
When specified, only returns claims reimbursed from these Benefits, including claims of their divisions' members.
"""
benefitIds: [ID!]
"""
When specified, only returns claims reimbursed to these Individuals. Returns an empty list if any of
them is not one of this partner's members.
"""
individualIds: [ID!]
"""
When specified, only returns claims whose enrollment belongs to these Organizations. Matches each
Organization exactly: a parent Organization's ID does not match claims of its divisions' members.
"""
organizationIds: [ID!]
"""When specified, only returns claims in these statuses."""
statuses: [ClaimStatus!]
}
"""The possible results of querying for claims."""
union ClaimsResponse = BadRequestError | ClaimsResults | InternalServerError
"""A page of claims."""
type ClaimsResults {
"""The claims on this page."""
nodes: [Claim!]!
"""Information used to fetch the next page."""
pageInfo: PageInfo!
}
"""
Box-level data for a 5498-SA (HSA contributions), matching the values printed on the member's form. Only the
member-specific boxes are exposed: Box 1 (Archer MSA contributions) is always $0.00 since these are HSAs, and
Box 6 (the HSA / Archer MSA / MA MSA checkbox) is always HSA, as indicated by the form's `formType`. Money
boxes render as $0.00 on the PDF when null here.
"""
type ContributionsTaxFormData {
"""
Box 3: contributions deposited after the end of the tax year (through the tax-filing deadline of the
following year) that were designated for this tax year, net of corrections. On PRELIMINARY versions produced
before the contribution window closes, this value may not yet be final.
"""
contributionsMadeInSubsequentYear: Money
"""
Box 2: the total contributions deposited during the tax (calendar) year, whether designated for that tax
year or for the prior tax year, plus any qualified HSA funding distributions, net of corrections. Excludes
rollovers (reported in Box 4).
"""
contributionsMadeInTaxYear: Money
"""
Box 5: the fair market value of the HSA (cash plus any investments) at the end of the tax year.
"""
fmv: Money
"""
Box 4: rollover contributions received for the tax year. Not included in Box 2. Direct trustee-to-trustee
transfers are not reported on the form, consistent with IRS instructions.
"""
rolloverContributions: Money
}
"""A country code as defined by ISO 3166-1 alpha-2"""
scalar CountryCode
"""A coverage level configured for a Benefit offering."""
type CoverageLevel {
"""Coverage amount; null when none is configured for this level."""
amount: Money
"""Relative order for UI display; null when not configured."""
displayOrder: Int
"""
The public ULID of this coverage level. Pass this value as coverageLevelId when enrolling.
"""
id: ID!
"""Human-readable name, e.g. "Employee Only" or "Family"."""
name: String!
}
"""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!
}
"""The first administrator of a brokerage firm"""
input CreateBrokerageFirmAdminInput {
"""
The administrator's email address. Must not already belong to a First Dollar user; this
operation creates a new identity and does not attach a broker role to an existing one.
"""
email: EmailAddress!
"""The administrator's first name"""
firstName: String!
"""The administrator's last name"""
lastName: String!
"""
The administrator's US mobile phone number. Optional. Must reduce to exactly 10 digits;
punctuation is stripped.
"""
phone: PhoneNumber
}
"""
An input type used when creating a brokerage firm and its first firm admin
"""
input CreateBrokerageFirmInput {
"""
The Employer Identification Number of the brokerage firm. Accepted either punctuated
(`12-3456789`) or bare (`123456789`); both resolve to the same firm. When supplied, it is validated
and canonicalized, and the shared firm registry is deduplicated on it. An EIN starting with 18 is
refused: the IRS does not issue that prefix, and it is reserved for placeholders.
Optional for a limited period. When it is omitted, the firm is matched on its normalized name: the
name lowercased, punctuation removed, runs of whitespace collapsed to one space, and trimmed. Business
suffixes such as Inc, LLC or Corp are kept, so `Acme Benefits` and `Acme Benefits LLC` are different
names. Exactly one match is returned as `ALREADY_EXISTED` with `matchedBy: NAME`, and nothing is
attached; no match creates the firm with a placeholder EIN; more than one match is refused with a
`BadRequestError` asking for the EIN. An empty or blank value is refused, not treated as omitted.
"""
ein: String
"""
The first administrator of the firm. Ignored when a firm is returned as `ALREADY_EXISTED`, whether
it was matched by EIN or by name — see `CreateBrokerageFirmResult.status` and `matchedBy`.
"""
firmAdmin: CreateBrokerageFirmAdminInput!
"""The legal or display name of the brokerage firm"""
name: String!
"""
Public ULIDs of the organizations this firm services, assigned as part of creating it. Matched
exactly and case-sensitively; organization short codes are not accepted. Maximum 250 per request.
All-or-nothing here, unlike the standalone assign operation: if any identifier is malformed or is
not one you control, the whole call is rejected and no firm is created. Results appear in
`CreateBrokerageFirmResult.organizationAssignments`.
"""
organizationUlids: [ID!]
}
"""
Union representing possible return types when creating a brokerage firm
"""
union CreateBrokerageFirmResponse = BadRequestError | CreateBrokerageFirmResult | InternalServerError
"""The successful result of creating a brokerage firm"""
type CreateBrokerageFirmResult {
"""
The brokerage firm, whether newly created or already present in the shared registry
"""
firm: BrokerageFirm!
"""
The First Dollar user ID of the newly created firm administrator. Null when no administrator was
provisioned, which is the case for `ALREADY_EXISTED`.
"""
firmAdminUid: ID
"""
How an existing firm was found. Set only when `status` is `ALREADY_EXISTED`, and null for `CREATED`.
`NAME` means the request had no EIN and its normalized name matched this firm. Nothing was attached:
`organizationAssignments` is null even when `organizationUlids` was supplied. Confirm the match by
calling `assignOrganizationsToFirm` with `firm.id`. Do not re-drive a `NAME` result automatically;
confirming that it is the right firm is a decision for a person.
"""
matchedBy: BrokerageFirmMatchedBy
"""
One element per organization supplied in `organizationUlids`, in the order they were submitted.
Absent when `organizationUlids` was absent or empty. Also absent — with a non-empty
`organizationUlids` — in two cases that must be handled differently:
- `matchedBy: NAME`: nothing was attached, because a firm matched by name is not assumed to be the
right one. Do not re-drive this automatically. A person confirms the match, then attaches the
organizations with `assignOrganizationsToFirm`.
- `CREATED` or `matchedBy: EIN`: the firm was returned successfully but the assignment could not be
completed afterwards; the firm and its administrator are intact, and the fix is to call
`assignOrganizationsToFirm`, which is idempotent. Only this case is safe to re-drive.
Expect every element to be `CREATED` or `ALREADY_ASSIGNED`: identifiers are validated before the
firm is created, so a request that reaches this point had every one of them resolve. Treat that as a
strong expectation rather than a guarantee — scope is resolved twice on this path, and an
organization that leaves your scope between the two resolutions comes back `FAILED`. Read `status`
per element rather than assuming the array is failure-free, and recover any `FAILED` element with
`assignOrganizationsToFirm`, which is idempotent.
"""
organizationAssignments: [OrganizationAssignmentResult!]
"""
Which outcome occurred. Distinguishes a firm and administrator that were newly provisioned from
an existing firm that was returned unchanged.
"""
status: CreateBrokerageFirmStatus!
}
"""The outcome of a createBrokerageFirm operation"""
enum CreateBrokerageFirmStatus {
"""
A firm with this EIN, or without an EIN a firm with this normalized name, already existed and was
returned unchanged — see `matchedBy`. No administrator was provisioned. A deactivated firm is also
returned unchanged — check `inactiveAt` on the firm.
The registry is not partitioned by partner, so the firm returned here may have been registered by
a different partner. Its name and identifier are returned regardless of who onboarded it: firm
existence, EIN, name and ULID are not treated as partner-confidential.
"""
ALREADY_EXISTED
"""The firm was created and its first administrator was provisioned"""
CREATED
}
"""Input for creating a new enrollment for a dependent in a benefit"""
input CreateDependentBenefitEnrollmentInput {
"""Public ULID of the offering"""
benefitId: ID!
"""First Dollar User ID of the dependent"""
dependentId: ID!
"""
End datetime of eligibility. Optional. When omitted, defaults to the end of the account holder's
enrollment in the Benefit, or no end date if that enrollment has none. Cannot be later than the
end of the account holder's enrollment.
"""
eligibilityEndDate: DateTime
"""
Start datetime of eligibility. Optional. When omitted, the enrollment is stored without a start
date: `eligibilityStartDate` is null. It does not default to the current datetime.
"""
eligibilityStartDate: DateTime
"""
Idempotency key. A request sent again with the same key returns the first successful result. Keys
do not expire. The request body is not compared, so use a new key for a different request. The
value is also stored as the enrollment's `externalReferenceId`.
"""
externalReferenceId: String
}
"""Union response for createDependentBenefitEnrollment mutation"""
union CreateDependentBenefitEnrollmentResponse = BadRequestError | CreateDependentBenefitEnrollmentResult | InternalServerError
"""Successful result of creating a new enrollment"""
type CreateDependentBenefitEnrollmentResult {
"""The benefit enrollment that was created"""
enrollment: DependentBenefitEnrollment!
}
"""Input for creating a new dependent"""
input CreateDependentInput {
"""First Dollar User ID of the account holder"""
accountHolderUid: ID!
"""The dependent's physical address"""
address: PhysicalAddressInput
"""
Optional benefit enrollments to create with the dependent. This is not atomic: the dependent is
created first, then each enrollment. If an enrollment fails, the mutation returns an error, but
the dependent and any enrollments created before the failure are kept. Use the `dependents` query
to find them, and `createDependentBenefitEnrollment` to add a missing enrollment.
"""
benefitEnrollments: [DependentBenefitEnrollmentInput!]
"""The dependent's date of birth"""
dateOfBirth: LocalDate!
"""The dependent's email address"""
email: EmailAddress
"""
Idempotency key. A request sent again with the same key returns the first successful result and
does not create another dependent. Keys do not expire. The request body is not compared, so use a
new key for a different request. This value is not stored on the dependent or its enrollments.
"""
externalReferenceId: String
"""The dependent's first name"""
firstName: String!
"""The dependent's last name"""
lastName: String!
"""The dependent's phone number"""
phoneNumber: PhoneNumber
"""Relationship type between dependent and account holder"""
relationshipType: DependentRelationshipType!
"""The dependent's SSN for user creation"""
ssn: String
}
"""Union response for createDependent mutation"""
union CreateDependentResponse = BadRequestError | CreateDependentResult | InternalServerError
"""Successful result of creating a dependent"""
type CreateDependentResult {
"""The dependent that was created"""
dependent: Dependent!
}
"""An input type used when creating a Division"""
input CreateDivisionInput {
"""The physical address of the Division"""
address: PhysicalAddressInput
"""The Employer Identification Number (EIN) of the Division"""
ein: String
"""
A partner-scoped external identifier for the Division. Must be unique within the partner.
"""
externalId: String
"""The user-displayable name of the Division"""
name: String!
"""The ID of the parent Organization"""
organizationId: ID!
"""
The ID of the parent Division. If provided, the new Division is nested under this Division
rather than directly under the Organization.
"""
parentDivisionId: ID
}
"""
A union representing the possible return types when creating a Division
"""
union CreateDivisionResponse = BadRequestError | CreateDivisionResult | InternalServerError
"""The successful result of creating a Division"""
type CreateDivisionResult {
"""The Division that was created"""
division: Division!
}
"""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!
}
"""Input for creating or updating a single organization membership"""
input CreateOrUpdateOrganizationMembershipInput {
"""The Individual's external user ID from the organization's system"""
externalUserId: String
"""The ID of the Individual"""
individualId: ID!
"""The ID of the Organization"""
organizationId: ID!
}
"""
Union representing possible return types when creating or updating an organization membership
"""
union CreateOrUpdateOrganizationMembershipResponse = BadRequestError | CreateOrUpdateOrganizationMembershipResult | InternalServerError
"""
The successful result of creating or updating an organization membership
"""
type CreateOrUpdateOrganizationMembershipResult {
"""The organization membership data"""
membership: OrganizationMembership!
"""The status of the operation"""
status: OrganizationOperationStatus!
"""The ID of the individual"""
uid: ID!
}
"""An input type used when creating an Organization Group"""
input CreateOrganizationGroupInput {
"""The physical address of the Organization Group"""
address: PhysicalAddressInput
"""
Optionally identifies the bank this organization group is placed on, by the ID First Dollar gave
you or one returned in a shard-resolution error's `extensions.custodians`. Supplied together
with brand, it selects the (partner, bank, brand) shard; supplied on its own, the bank's shard,
which requires that bank to carry exactly one brand. Omit both to place the organization group
on the bank that your API credentials belong to. If that bank carries more than one of the
partner's brands, the mutation fails with a top-level AMBIGUOUS_SHARD error; pass `brand` to
choose one. An ID that is not a bank is rejected with `BAD_USER_INPUT`, with the accepted IDs in
`extensions.custodians`.
"""
bank: ID
"""
Optionally identifies the brand this organization group belongs to. Only needed to
disambiguate when the partner has more than one brand; single-brand callers may omit it.
Supplied without a bank, it resolves across every bank the partner holds, so it must
identify exactly one shard.
"""
brand: String
"""The Employer Identification Number (EIN) of the Organization Group"""
ein: String
"""
A partner-scoped external identifier for the Organization Group. Must be unique within the partner.
"""
externalId: String
"""The user-displayable name of the Organization Group"""
name: String!
"""
The US phone number of the Organization Group (10 digits, no punctuation)
"""
phone: PhoneNumber
}
"""
A union representing the possible return types when creating an Organization Group
"""
union CreateOrganizationGroupResponse = BadRequestError | CreateOrganizationGroupResult | InternalServerError
"""The successful result of creating an Organization Group"""
type CreateOrganizationGroupResult {
"""The Organization Group that was created"""
organizationGroup: OrganizationGroup!
}
"""An input type used when creating an Organization"""
input CreateOrganizationInput {
"""The physical address of the Organization"""
address: PhysicalAddressInput
"""
The ID of the bank for shard placement, as given to you by First Dollar or returned in a
shard-resolution error's `extensions.custodians`. Supply with `brand` to place on that exact
`(partner, bank, brand)` shard, or alone to place on the partner's shard for that bank, which requires
the bank to hold exactly one brand for the partner. Omitted == placement is resolved from `brand` alone,
or left to the default. An ID that is not a bank is rejected with `BAD_USER_INPUT`, with the accepted
IDs in `extensions.custodians`.
"""
bank: ID
"""
Brand name for shard placement. Supply with `bank` to place on that exact `(partner, bank, brand)` shard,
or alone to place on the partner's shard for that brand across whichever bank holds it. Omitted ==
placement is resolved from `bank` alone, or left to the default.
"""
brand: String
"""The Employer Identification Number (EIN) of the Organization"""
ein: String
"""
A partner-scoped external identifier for the Organization. Must be unique within the partner.
"""
externalId: String
"""The user-displayable name of the Organization"""
name: String!
"""The ID of the Organization Group this Organization belongs to"""
organizationGroupId: ID
}
"""
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!
}
input CreateWebhookEndpointInput {
"""Your label for the endpoint, at most 500 characters."""
description: String
"""From 1 to 20 types from webhookEventTypes."""
eventTypes: [String!]!
"""An https URL on port 443 at a hostname you control."""
url: String!
}
"""
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
"""An enum representing the days of the week"""
enum DaysOfWeek {
FRIDAY
MONDAY
SATURDAY
SUNDAY
THURSDAY
TUESDAY
WEDNESDAY
}
"""Input for deactivating a single organization membership"""
input DeactivateOrganizationMembershipInput {
"""The ID of the Individual"""
individualId: ID!
"""The ID of the Organization"""
organizationId: ID!
}
"""
Union representing possible return types when deactivating an organization membership
"""
union DeactivateOrganizationMembershipResponse = BadRequestError | DeactivateOrganizationMembershipResult | InternalServerError
"""The successful result of deactivating an organization membership"""
type DeactivateOrganizationMembershipResult {
"""Whether the deactivation was successful"""
success: Boolean!
}
input DenyClaimInput {
"""The ID of the claim to deny."""
claimId: ID!
"""
More detail about the denial, shown to the Individual. Required when `reason` is `OTHER`, and not accepted otherwise.
"""
comment: String
"""
A note added to the claim's notes, which the Individual and administrators can read.
"""
note: String
"""The reason for the denial. `UNSPECIFIED` is not accepted."""
reason: ClaimDenialReason!
}
"""The possible results of denying a claim."""
union DenyClaimResponse = BadRequestError | DenyClaimResult | InternalServerError
type DenyClaimResult {
"""The denied claim."""
claim: Claim!
}
"""A dependent associated with an account holder"""
type Dependent {
"""First Dollar User ID of the account holder (parent/spouse)"""
accountHolderUid: ID!
"""
All benefit enrollments for this dependent
Uses DataLoader for N+1 prevention
"""
benefitEnrollments: [DependentBenefitEnrollment!]!
"""When this dependent was created"""
createdAt: DateTime
"""The dependent's date of birth"""
dateOfBirth: LocalDate
"""The dependent's email address"""
email: EmailAddress
"""The dependent's first name"""
firstName: String!
"""First Dollar User ID for the dependent user"""
id: ID!
"""The dependent's last name"""
lastName: String!
"""The dependent's phone number"""
phoneNumber: PhoneNumber
"""Relationship type between this dependent and the account holder"""
relationshipType: DependentRelationshipType
}
"""Association between a dependent and a benefit offering"""
type DependentBenefitEnrollment {
"""Public ULID of the offering"""
benefitId: ID!
"""Name of the benefit"""
benefitName: String
"""Type of the benefit (HSA, FSA, etc.)"""
benefitType: String
"""When this enrollment was created"""
createdAt: DateTime!
"""How this enrollment was created"""
createdVia: DependentCreationSource!
"""End datetime of eligibility (NULL = currently active)"""
eligibilityEndDate: DateTime
"""Start datetime of eligibility"""
eligibilityStartDate: DateTime
"""Partner-provided ID for reconciliation and idempotency"""
externalReferenceId: String
"""Internal database ID"""
id: ID!
"""When this enrollment was last updated"""
updatedAt: DateTime!
}
"""Input for creating a benefit enrollment as part of dependent creation"""
input DependentBenefitEnrollmentInput {
"""Public ULID of the offering"""
benefitId: ID!
"""
End datetime of eligibility. Optional. When omitted, defaults to the end of the account holder's
enrollment in the Benefit, or no end date if that enrollment has none. Cannot be later than the
end of the account holder's enrollment.
"""
eligibilityEndDate: DateTime
"""
Start datetime of eligibility. Optional. When omitted, the enrollment is stored without a start
date: `eligibilityStartDate` is null. It does not default to the current datetime.
"""
eligibilityStartDate: DateTime
}
"""How the dependent-benefit association was created"""
enum DependentCreationSource {
"""Created via admin API"""
ADMIN_API
"""Created via Partner API"""
API
"""Created via consumer app (Health Wallet)"""
CONSUMER_API
"""Created via historic data migration"""
MIGRATION
}
"""Filter criteria for querying a single dependent"""
input DependentFilterInput {
"""First Dollar User ID of the dependent"""
id: ID!
}
"""The relationship type between dependent and account holder"""
enum DependentRelationshipType {
"""Child (biological, adopted, or stepchild)"""
CHILD
"""Other eligible dependent"""
OTHER
"""Spouse or domestic partner"""
SPOUSE
}
"""Union response for dependent query"""
union DependentResponse = BadRequestError | Dependent | InternalServerError
"""Filter criteria for querying multiple dependents"""
input DependentsFilterInput {
"""
First Dollar User ID of the account holder
If specified, only returns dependents for this account holder
"""
accountHolderUid: ID!
}
"""Union response for dependents query"""
union DependentsResponse = BadRequestError | DependentsResults | InternalServerError
"""Paginated list of dependents"""
type DependentsResults {
"""List of dependents in this page"""
nodes: [Dependent!]!
"""Pagination metadata"""
pageInfo: PageInfo!
}
"""
Box-level data for a 1099-SA (HSA distributions), matching the values printed on the member's form. Only the
member-specific boxes are exposed: Box 5 (the HSA / Archer MSA / MA MSA checkbox) is always HSA, as indicated
by the form's `formType`. Money boxes render as $0.00 on the PDF when null here.
"""
type DistributionsTaxFormData {
"""
Box 3: the one-character IRS distribution code printed on the form. "1" (normal), "2" (excess
contributions), "3" (disability), "4" (death), "5" (prohibited transaction), or "6" (death distribution
after the year of death to a nonspouse beneficiary).
"""
distributionCode: String
"""
Box 2: earnings on excess contributions that were distributed along with a return of excess contributions
(these earnings are also included in Box 1). Populated only when such a distribution occurred; null otherwise.
"""
earningsOnExcessContributions: Money
"""
Box 4: the fair market value of the account on the owner's date of death. Populated only on
death-distribution forms; null otherwise.
"""
fmvOnDateOfDeath: Money
"""
Box 1: the total distributions taken from the HSA during the tax year, net of any returned (reimbursed)
distributions and reversals.
"""
grossDistribution: Money
}
"""
A Division is a subdivision of an Organization — for example, a department, office,
or business unit that needs its own benefit packages, members, or bank accounts.
"""
type Division {
"""The physical address of the Division"""
address: PhysicalAddress
"""Child Divisions nested under this Division"""
divisions: [Division!]!
"""The Employer Identification Number (EIN) of the Division"""
ein: String
"""A partner-scoped external identifier for the Division"""
externalId: String
"""The unique ID for the Division"""
id: ID!
"""The user-displayable name of the Division"""
name: String!
"""The parent Organization that this Division belongs to"""
parentOrganization: Organization!
}
"""Filter criteria used when querying for a Division"""
input DivisionFilterInput {
"""The external ID of the Division (unique per partner)"""
externalId: String
"""The ID of the Division"""
id: ID
}
"""
A union representing the possible return types when querying for a Division
"""
union DivisionResponse = BadRequestError | Division | InternalServerError
"""Filter criteria used when querying for Divisions"""
input DivisionsFilterInput {
"""If specified, only returns Divisions matching these external IDs"""
externalIds: [String!]
"""If specified, only returns Divisions matching these IDs"""
ids: [ID!]
"""If specified, only returns Divisions matching these names"""
names: [String!]
"""The ID of the parent Organization whose Divisions to list"""
organizationId: ID!
}
"""
A union representing the possible return types when querying for Divisions
"""
union DivisionsResponse = BadRequestError | DivisionsResults | InternalServerError
"""Represents a page of Divisions"""
type DivisionsResults {
nodes: [Division!]!
pageInfo: PageInfo!
}
"""A secure link to download a page of content."""
type DownloadLink {
"""
The size of the file in bytes as it is downloaded, a whole number. Null means unknown; it is never 0 as a stand-in.
"""
byteSize: Float
"""
The name to show for the file. Null when it was not recorded, which is the case for reports generated before
per-file details were stored.
"""
displayFilename: String
"""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!
"""
The 1-based position of the file this link downloads within the report. It is the `page` number that selects it.
"""
ordinal: Int
"""
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!
"""
The number of data rows in the file, not counting the header. Null means unknown; it is never 0 as a stand-in.
"""
rowCount: Int
"""
Whether the file can be downloaded right now. A file with a link here is AVAILABLE.
"""
status: ReportFileStatus
"""
How many files the report has in total. Fewer links than this means some files have none; see `Report.files`.
"""
totalFiles: Int
}
"""
A string representing a duration conforming to the ISO8601 standard,
such as: P1W1DT13H23M34S
P is the duration designator (for period) placed at the start of the duration representation.
Y is the year designator that follows the value for the number of years.
M is the month designator that follows the value for the number of months.
W is the week designator that follows the value for the number of weeks.
D is the day designator that follows the value for the number of days.
T is the time designator that precedes the time components of the representation.
H is the hour designator that follows the value for the number of hours.
M is the minute designator that follows the value for the number of minutes.
S is the second designator that follows the value for the number of seconds.
Note the time designator, T, that precedes the time value.
Matches moment.js, Luxon and DateFns implementations
,/. is valid for decimal places and +/- is a valid prefix
"""
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!
"""
Coverage level public ULID. Must reference an active coverage level configured for this offering.
Required for TRADITIONAL_HRA enrollments — the resolver derives `employerInitialContributionAmount`,
`employerRecurringContributionAmount`, and the per-period final-remainder amount from the coverage
level record, so partners do not pass those amounts directly for Traditional HRA.
"""
coverageLevelId: ID
"""
The health insurance coverage type for HSA accounts. This field is optional and only applies to HSA offerings.
"""
coverageType: HealthInsuranceCoverageType
"""
The annual election amount for the benefit enrollment.
Subject to IRS contribution limits based on benefit type and coverage type.
Amount should be provided in cents (lowestDenominationAmount).
Required and must be greater than $0 for FSA and LPFSA enrollments; may be omitted when re-enrolling a participant
who already has an election persisted for the benefit. Optional for HSA enrollments.
Not used for TRADITIONAL_HRA enrollments: omit this field or pass zero. A non-zero amount returns a
BadRequestError.
This will change when we add support for additional benefit types.
"""
electionAmount: MoneyInput
"""
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.
Not used for TRADITIONAL_HRA enrollments, whose contribution amounts come from the selected `coverageLevelId`. For a TRADITIONAL_HRA enrollment, omit this field or pass zero. A non-zero amount returns a BadRequestError.
"""
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.
Not used for TRADITIONAL_HRA enrollments, whose contribution amounts come from the selected `coverageLevelId`. For a TRADITIONAL_HRA enrollment, omit this field or pass zero. A non-zero amount returns a BadRequestError.
"""
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.
Not used for TRADITIONAL_HRA enrollments, whose contribution amounts come from the selected `coverageLevelId`. For a TRADITIONAL_HRA enrollment, omit this field or pass zero. A non-zero amount returns a BadRequestError.
"""
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.
Not used for TRADITIONAL_HRA enrollments, whose contribution amounts come from the selected `coverageLevelId`. For a TRADITIONAL_HRA enrollment, omit this field or pass zero. A non-zero amount returns a BadRequestError.
"""
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`.
This field is optional - if omitted, the system will attempt to find an existing valid verification for the Individual.
If no valid verification is found, enrollment will fail. 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 external platform named by enum value. Use the IDs returned by `linkedExternalPlatforms` instead.
"""
enum ExternalPlatform {
"""An external platform"""
AETNA @deprecated(reason: "Use the IDs returned by linkedExternalPlatforms")
"""An external platform"""
HCSC @deprecated(reason: "Use the IDs returned by linkedExternalPlatforms")
"""An external platform"""
WEX @deprecated(reason: "Use the IDs returned by linkedExternalPlatforms")
}
"""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 deposit this funding request created. It is the 'id' of that deposit's Transaction on the
Individual's Account.transactions, and the 'fundingTransactionId' to pass to 'reverseBenefitFundingForIndividual'.
"""
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
enum HealthInsuranceCoverageType {
FAMILY
INDIVIDUAL
NONE
}
"""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 {
"""
The external platform whose product codes `productCodes` are matched against, as an `id`
returned by `linkedExternalPlatforms`. Rejected without `productCodes`, and rejected when the
value is not one of your linked platform IDs, in both cases as a GraphQL error with extension
code `BAD_USER_INPUT`. May be omitted when exactly one platform is linked to your account.
"""
platformId: ID
"""
If specified, returns only accounts whose Benefit carries one of these product codes on the
external platform named by `platformId` (see `Benefit.productCode`). Values are matched exactly.
An explicitly empty list matches no accounts. Composes with `statuses`.
Without `platformId`, the codes are matched on your only linked external platform. If your
account is linked to no platform or to more than one, `platformId` is required and its omission
is rejected as a GraphQL error with extension code `BAD_USER_INPUT`.
"""
productCodes: [String!]
"""
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 dependents for whom this Individual is the account holder, in the same order as the
`dependents` query. An empty list when dependents are not enabled for your organization, or when
the dependents cannot be read; the `dependents` query reports the error. On an `individuals` page,
the dependents of all the Individuals are read together.
"""
dependents: [Dependent!]!
"""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!
"""Organization memberships for this individual"""
organizationMemberships(
"""Return the memberships that come after the specified cursor"""
after: String
"""The number of memberships to retrieve per page"""
first: Int = 100
"""Filter criteria used to match organization memberships"""
where: OrganizationMembershipsFilterInput
): OrganizationMembershipsResults!
"""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 initial claimed status for the member. Optional. When omitted, the server defaults to
UNCLAIMED so the member is claimable via the claim-account flow. Pass an explicit null to
leave claimed_status NULL and opt the member out of the claim flow entirely.
"""
claimedStatus: UserClaimedStatus
"""The Individual's date of birth"""
dateOfBirth: LocalDate
"""The Individual's email address"""
email: EmailAddress
"""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
"""Metadata for a single tax form version."""
type IndividualTaxForm {
"""The date this form version was produced."""
formDate: LocalDate!
"""The IRS form name, e.g. "1099-SA"."""
formName: String!
formType: TaxFormType!
id: ID!
status: TaxFormStatus!
taxYear: YearString!
"""The date through which the form's values are valid."""
validAsOfDate: LocalDate!
}
"""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 who hold one of these values as an external identifier.
Without `platformIds`, the values are matched against the external user ID on the Individual's
organization memberships — the member identifier supplied through
`createOrUpdateOrganizationMembership`. With `platformIds`, they are matched against the
identifiers recorded for those external platforms instead, and membership external user IDs are
not searched at all; see `platformIds` for how that lookup differs.
In both cases an explicitly empty list matches no Individuals (it is not treated as "no filter"),
a maximum of 100 values may be supplied (more than that is rejected as a top-level GraphQL error
with extension code `BAD_USER_INPUT`, not as the `BadRequestError` member of this query's result
union), and Individuals without a resolvable first and last name are never returned by this
query, so an Individual whose profile never captured a name will not be found by an external
identifier. The rest of this description covers the membership lookup.
Matching ignores case, whitespace and punctuation, so values differing only in those respects are
treated as the same identifier (`AB-123-456` and `ab123456` match the same Individual). A value
consisting only of punctuation or whitespace matches no Individuals. A value that is already a
64-character lowercase hexadecimal string is looked up as sent and, unlike other values, matched
case-sensitively: a member identifier supplied to `createOrUpdateOrganizationMembership` in that
form is found by that same string.
A membership matches regardless of employment status: an Individual whose membership has been
terminated is still returned, so that looking up an identifier you hold on file never reports
"not found" for a former member. Compose `statuses` to narrow to current members.
An external user ID is unique within an organization, not across them, and this filter searches
every organization you can see. One value can therefore return more than one Individual when
separate organizations independently use the same member identifier. Compose `organizationIds`
to scope a lookup to a single organization.
"""
externalUserIds: [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, qualifies `externalUserIds` with one or more external platforms linked to your
account: only Individuals holding one of the supplied values as their identifier on one of the
supplied platforms are returned. Each value is an `id` returned by `linkedExternalPlatforms`.
Values within `externalUserIds` are ORed, values within `platformIds` are ORed, and the two lists
are ANDed; they are not paired positionally.
A platform qualifies a lookup and is not a filter on its own: supplying `platformIds` without
`externalUserIds` is rejected as a top-level GraphQL error with extension code `BAD_USER_INPUT`.
An explicitly empty `platformIds` beside a non-empty `externalUserIds` matches no Individuals.
Omitting `platformIds` (or passing `null`) keeps the membership lookup described on
`externalUserIds`; the two sources are never combined in one query. A value that is not one of
your linked platform IDs is rejected as a top-level GraphQL error with extension code
`BAD_USER_INPUT`.
Matching ignores case, whitespace and punctuation, as for the membership lookup, and a value of
only punctuation or whitespace matches no Individuals. Every value is matched as an identifier;
a 64-character lowercase hexadecimal value is not treated as a pre-hashed identifier.
An identifier is not unique on a platform: one value can return more than one Individual, even
within one organization, and one Individual can match through several platforms in one query.
The response does not say which platform or identifier matched. To resolve a single Individual,
send one platform per query and compose `ids` or `organizationIds` when more than one is
returned. `organizationIds` filters the Individuals returned; it does not restrict which
organization an identifier was recorded for.
Terminated members are still returned here too; compose `statuses` to narrow. The 100-value
maximum on `externalUserIds` applies unchanged.
"""
platformIds: [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!
}
input IssueCardInput {
"""The Benefits Program to issue the card for."""
benefitsProgramId: ID!
"""A key for ensuring request idempotency."""
idempotencyKey: String!
"""
The Individual to issue the card to (an account holder or a dependent).
"""
individualId: ID!
"""
The type of card to issue. Dependent cards support physical cards only.
"""
type: CardType!
}
union IssueCardResponse = BadRequestError | InternalServerError | IssueCardResult
type IssueCardResult {
"""The newly issued card."""
card: Card!
}
"""
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
"""An external platform linked to your account"""
type LinkedExternalPlatform {
"""
The ID of the external platform. IDs are specific to your account and are stable for its lifetime.
"""
id: ID!
"""
The platform code First Dollar records for the link, for telling linked platforms apart. It is
not an identifier in this API and carries no stability guarantee; `id` is the only supported key.
"""
name: String!
}
"""
A union representing the possible return types when querying for the calling partner's linked external platforms
"""
union LinkedExternalPlatformsResponse = InternalServerError | LinkedExternalPlatformsResults
"""The set of external platforms linked to the calling partner"""
type LinkedExternalPlatformsResults {
"""
The external platforms linked to the calling partner. Each platform appears exactly once.
"""
platforms: [LinkedExternalPlatform!]!
}
"""
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
input LockCardInput {
"""The ID of the card to lock."""
cardId: ID!
individualId: ID
"""The reason the card is being locked."""
reason: CardActionReason!
}
union LockCardResponse = BadRequestError | InternalServerError | LockCardResult
type LockCardResult {
"""The locked card."""
card: Card!
}
"""
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: SafeInt!
}
"""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: SafeInt!
}
"""
Mutations describe the actions you can perform to modify data in our GraphQL API.
"""
type Mutation {
"""Activates a card that an Individual has received."""
activateCard(input: ActivateCardInput!): ActivateCardResponse
"""
Adds a broker to an existing active brokerage firm in the caller's partner scope.
The firm must have at least one active organization assignment owned by the caller's partner.
A missing, inactive, unassigned, or other-partner firm returns the same generic `NOT_FOUND` denial.
"""
addBrokerToFirm(input: AddBrokerToFirmInput!): AddBrokerToFirmResponse
"""
Approves a claim, in full or in part. The claim must be in `PENDING`, `IN_REVIEW`,
`INFORMATION_REQUESTED`, or `RESUBMITTED` status. A `RESUBMITTED` claim first moves to `IN_REVIEW`,
and stays there if the approval is then refused. Reimbursement then follows the Benefit's
configuration, so the claim moves on through `APPROVED`, `IN_ACCRUAL`, `PAYMENT_PENDING`, `PAID`, or
`OUT_OF_POCKET`. The Individual is notified of the approval.
"""
approveClaim(input: ApproveClaimInput!): ApproveClaimResponse
"""
Assigns organizations to a brokerage firm, so the firm services them.
Idempotent and partially successful: every submitted identifier gets its own result element, and one
that cannot be resolved fails only its own row. A request in which every row failed is still a
successful response — read `status` per element rather than branching on the union alone.
Request-level failures return `BadRequestError`, whose `code` is one of:
`FORBIDDEN` (the caller may not perform this operation), `NOT_FOUND` (no firm has this identifier),
`FIRM_INACTIVE` (the firm has been deactivated; reactivating it is a manual step) or `BAD_REQUEST`
(the request itself is malformed, for example more than 250 organizations).
"""
assignOrganizationsToFirm(input: AssignOrganizationsToFirmInput!): AssignOrganizationsToFirmResponse
"""
Cancels a Benefit. This operation cannot be undone.
Cancelling unenrolls every Individual currently enrolled in the Benefit and closes the Benefit to further
enrollment and funding. A Benefit that has already been cancelled, or that has been terminated, cannot be
cancelled.
For an Organization with Divisions, cancel the Benefit belonging to the parent Organization; the Benefits held
by its Divisions are cancelled along with it. Passing a Division's Benefit directly is rejected.
"""
cancelBenefit(input: CancelBenefitInput!): CancelBenefitResponse
"""
Permanently cancels a card. Optionally issues a replacement card in the same
operation by setting `reissue: true`; the replacement's ID is returned as
`reissuedCardId`.
"""
cancelCard(input: CancelCardInput!): CancelCardResponse
"""Create a new Benefit"""
createBenefit(input: CreateBenefitInput!): CreateBenefitResponse
"""Create a new Benefits Program"""
createBenefitsProgram(input: CreateBenefitsProgramInput!): CreateBenefitsProgramResponse
"""
Creates a brokerage firm and its first firm admin.
The firm registry is shared across partners and deduplicated on EIN: if a firm with this EIN
already exists it is returned rather than duplicated, and no second firm admin is provisioned.
Check `status` to tell the two outcomes apart.
For a limited period `ein` may be omitted. The firm is then matched on its normalized name instead
(see `CreateBrokerageFirmInput.ein`). A single name match is returned as `ALREADY_EXISTED` with
`matchedBy: NAME` and nothing attached: none of `organizationUlids` is assigned, and no firm admin is
provisioned. Confirm that it is the right firm, then attach your organizations by calling
`assignOrganizationsToFirm` with its `firm.id`. A name that matches no firm creates the firm with a
placeholder EIN (see `BrokerageFirm.einIsPlaceholder`).
Request-level failures return `BadRequestError`, whose `code` is `FIRM_INACTIVE` (the EIN or, without
an EIN, the name matched an authorized firm that has been deactivated and `organizationUlids` was
non-empty; reactivating the firm is a manual step), `NOT_FOUND` (the EIN matched a firm outside the
caller's current firm-side authority and `organizationUlids` was non-empty), or `BAD_REQUEST` for a
malformed request. A request without an EIN whose name matches more than one firm is also refused
with a `BadRequestError` whose `code` is `BAD_REQUEST`, asking for the EIN; nothing is written. Neither
domain code can occur when `organizationUlids` is absent or empty: that request returns the existing
firm as `ALREADY_EXISTED`, including its `inactiveAt` state.
"""
createBrokerageFirm(input: CreateBrokerageFirmInput!): CreateBrokerageFirmResponse
"""
Create a new dependent with optional benefit enrollments
Supports idempotency via externalReferenceId
"""
createDependent(input: CreateDependentInput!): CreateDependentResponse
"""
Create a new enrollment for a dependent in a benefit offering.
Returns error if dependent is already enrolled in this offering.
Use updateDependentBenefitEnrollment to modify existing enrollments.
Supports idempotency via externalReferenceId
"""
createDependentBenefitEnrollment(input: CreateDependentBenefitEnrollmentInput!): CreateDependentBenefitEnrollmentResponse
"""Create a new Division within an Organization"""
createDivision(input: CreateDivisionInput!): CreateDivisionResponse
"""Create Individual"""
createIndividual(input: CreateIndividualInput!): CreateIndividualResponse
"""Create or update an organization membership for a single individual"""
createOrUpdateOrganizationMembership(input: CreateOrUpdateOrganizationMembershipInput!): CreateOrUpdateOrganizationMembershipResponse
"""Create a new Organization"""
createOrganization(input: CreateOrganizationInput!): CreateOrganizationResponse
"""Create a new Organization Group"""
createOrganizationGroup(input: CreateOrganizationGroupInput!): CreateOrganizationGroupResponse
"""
Registers an HTTPS endpoint. Store the returned signingSecret; reads never return it.
"""
createWebhookEndpoint(input: CreateWebhookEndpointInput!): WebhookSigningSecret!
"""Deactivate an organization membership for a single individual"""
deactivateOrganizationMembership(input: DeactivateOrganizationMembershipInput!): DeactivateOrganizationMembershipResponse
"""
Deletes an endpoint. Its pending deliveries are skipped instead of sent, and it no longer appears in reads.
"""
deleteWebhookEndpoint(
"""The endpoint to delete."""
endpointId: ID!
): Boolean!
"""
Denies a claim, which moves it to `REJECTED` and releases any amount held on the Individual's Benefit
balance. The claim must be in `PENDING`, `IN_REVIEW`, `INFORMATION_REQUESTED`, or `RESUBMITTED`
status; a `RESUBMITTED` claim first moves to `IN_REVIEW`. The Individual is notified of the denial and
its reason.
"""
denyClaim(input: DenyClaimInput!): DenyClaimResponse
"""
Enroll an Individual in a Benefit
Returns `BadRequestError` with code `BENEFIT_NOT_READY` and `retryable: true` when the Benefit is still provisioning
for the Individual's division, typically right after `createBenefit`. Nothing was written; retry the same request
after a short delay.
"""
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
"""
Issues a new card to an Individual for a Benefits Program. The Individual may
be an account holder or a dependent; pass the dependent's own Individual ID
to issue a dependent card. Card availability depends on the Program's
configuration and the member's enrollment and account state.
"""
issueCard(input: IssueCardInput!): IssueCardResponse
"""
Temporarily locks a card, blocking new transactions. Locks with reason `LOST`,
`STOLEN`, or `OTHER` are reversible with `unlockCard`. A lock with reason
`FRAUDULENT_CHARGES` is permanent: the card cannot be unlocked afterwards and
must be cancelled (optionally with a replacement via `cancelCard`'s `reissue`).
"""
lockCard(input: LockCardInput!): LockCardResponse
"""
Prepares secure upload links for claim documents, such as receipts and invoices. Specify exactly one
target:
- `individualId` creates a new document group owned by that Individual. Upload the files, then pass
the returned `documentGroupId` to `submitClaim`.
- `claimId` adds files to the document group of a claim in `INFORMATION_REQUESTED` status. Call
`resubmitClaim` after the files are uploaded.
For each entry in `uploads`, send the file's bytes in an HTTP `PUT` request to `uploadUrl`, with every
header in `requestHeaders` and no other changes. The links expire at `expiresAt`. Prepare a new upload
if a link expires before it is used. First Dollar encrypts the files; the request headers carry the
file's encryption key, so treat the URL and headers as secrets and do not log them.
"""
prepareClaimDocumentUpload(input: PrepareClaimDocumentUploadInput!): PrepareClaimDocumentUploadResponse
"""
Starts a new retry cycle with the same webhook-id. The delivery must be finished or waiting for a retry.
"""
redeliverWebhook(
"""The delivery to send again."""
deliveryId: ID!
): WebhookDelivery!
"""
Redelivers finished deliveries whose occurredAt is in the range, newest first.
"""
redeliverWebhooks(
"""The endCursor of the previous call with the same arguments."""
after: String
"""The endpoint whose deliveries to resend."""
endpointId: ID!
"""Earliest occurredAt, as an ISO 8601 timestamp."""
from: String!
"""At most 100 per call; 50 by default."""
limit: Int
"""FAILED, SKIPPED, or SUCCEEDED; PENDING deliveries are already queued."""
status: WebhookDeliveryStatus!
"""Latest occurredAt, as an ISO 8601 timestamp."""
through: String!
): RedeliverWebhooksResult!
"""
Remove a dependent from a benefit offering (soft delete).
Sets eligibility_end_date to current date.
"""
removeDependentBenefitEnrollment(input: RemoveDependentBenefitEnrollmentInput!): RemoveDependentBenefitEnrollmentResponse
"""
Asks the Individual for more information about a claim, which moves it to `INFORMATION_REQUESTED`.
The claim must be in `PENDING`, `IN_REVIEW`, `INFORMATION_REQUESTED`, or `RESUBMITTED` status; a
`RESUBMITTED` claim first moves to `IN_REVIEW`. The Individual is notified of the request and its
reason. Respond with `resubmitClaim`.
"""
requestClaimInformation(input: RequestClaimInformationInput!): RequestClaimInformationResponse
"""
Resubmits a claim in `INFORMATION_REQUESTED` status, which moves it to `RESUBMITTED` for review. To
supply new documents for a claim that has a document group, first add them with
`prepareClaimDocumentUpload` and the claim's ID; a claim submitted without documents cannot receive
them later. The resubmission can also correct the same details as `updateClaim`; omitted fields keep
their current values.
"""
resubmitClaim(input: ResubmitClaimInput!): ResubmitClaimResponse
"""
Reverses a funding deposit for an Individual. A deposit can be reversed whether it was made by
'fundBenefitForIndividual' or by a payroll contribution. The deposit is identified by its Transaction.id, as listed
on the Individual's Account.transactions. On success, the total funds available to the Individual in this Benefit
is decreased by the amount specified in the request (or, when 'amount' is omitted, the full original funding
amount). Supports partial reversals. The reversals of one deposit cannot exceed its amount in total, so after a
partial reversal, name the remaining 'amount' explicitly.
Reversed funds are returned to the funding source for the Benefit. Subsequent return of funds further
upstream, where applicable, is handled separately and is not in the scope of this mutation.
Available for all Benefit types.
"""
reverseBenefitFundingForIndividual(input: ReverseBenefitFundingForIndividualInput!): ReverseBenefitFundingForIndividualResponse
"""
Issues a new signing secret. The previous one keeps signing for 24 hours; rotating again in that window revokes it.
"""
rotateWebhookSigningSecret(
"""The endpoint to rotate."""
endpointId: ID!
): WebhookSigningSecret!
"""Queues webhook.test. Poll webhookDelivery for attempts."""
sendTestWebhook(
"""An ACTIVE endpoint to test."""
endpointId: ID!
): WebhookDelivery!
"""
Sets the election amount for a Benefit and Individual. This operation is only available for PENDING enrollments.
Returns an error for ACTIVE enrollments. Subject to IRS contribution limits.
"""
setElectionAmountForBenefitAndIndividual(input: SetElectionAmountForBenefitAndIndividualInput!): SetElectionAmountForBenefitAndIndividualResponse
"""
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. It is not available for Traditional HRA Benefits, whose recurring
contribution schedule is managed through coverage levels.
"""
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
"""
Submits a reimbursement claim on behalf of an Individual. The claim is reimbursed to the Individual's
primary linked bank account, which must be verified. Submission holds the claim amount on the
Individual's Benefit balance until the claim is decided. A Benefit that reimburses claims as its funds
accrue accepts a claim larger than the available balance, and does not hold that claim.
Once a request completes, the same `idempotencyKey` returns its response, including a returned error,
without submitting again. A retry sent while the first request is still running can submit a second
claim, so after a lost response, query `claims` for the Individual before retrying. After correcting the cause of a `BAD_REQUEST`, retry with a new key. After an `INTERNAL_SERVER_ERROR`,
query `claims` for the Individual before retrying with a new key, because the claim may have been
submitted.
"""
submitClaim(input: SubmitClaimInput!): SubmitClaimResponse
"""
Transfers an Individual's Benefit Enrollment from one Organization to another. This operation is only available
for HSA Benefits.
Returns `BadRequestError` with code `BENEFIT_NOT_READY` and `retryable: true` when the target Benefit is still
provisioning for the Individual's division. Nothing was changed; retry the same request after a short delay.
"""
transferBenefitForIndividual(input: TransferBenefitForIndividualInput!): TransferBenefitForIndividualResponse
"""
Removes organizations from a brokerage firm, so the firm no longer services them.
Scoped to your own organizations: it never affects another partner's assignments to the same firm.
It also does not deactivate the broker or the firm — it revokes only the named organizations. The
firm's brokers keep their accounts and every other organization they service.
Idempotent and partially successful, on the same terms as `assignOrganizationsToFirm`.
Request-level failures return `BadRequestError`, whose `code` is one of:
`FORBIDDEN`, `NOT_FOUND` or `BAD_REQUEST`. Unlike assignment this operation succeeds against a
deactivated firm, so `FIRM_INACTIVE` is never returned: revoking access must not be blocked by the
state of the firm being revoked from.
"""
unassignOrganizationsFromFirm(input: UnassignOrganizationsFromFirmInput!): UnassignOrganizationsFromFirmResponse
"""
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
"""
Removes a temporary lock from a card, allowing transactions again. A card
locked with reason `FRAUDULENT_CHARGES` cannot be unlocked; cancel the card
instead (optionally with a replacement via `cancelCard`'s `reissue`).
"""
unlockCard(input: UnlockCardInput!): UnlockCardResponse
"""Update an existing Benefit"""
updateBenefit(input: UpdateBenefitInput!): UpdateBenefitResponse
"""Update an existing Benefits Program"""
updateBenefitsProgram(input: UpdateBenefitsProgramInput!): UpdateBenefitsProgramResponse
"""
Corrects details of a claim before it is decided. The claim must be in `PENDING`, `IN_REVIEW`,
`INFORMATION_REQUESTED`, or `RESUBMITTED` status. Omitted fields keep their current values. The amount,
Individual, and Benefit cannot be changed. A correction does not change the claim's status.
"""
updateClaim(input: UpdateClaimInput!): UpdateClaimResponse
"""
Update an existing dependent's information
Does NOT update benefit enrollments - use separate enroll/unenroll mutations
"""
updateDependent(input: UpdateDependentInput!): UpdateDependentResponse
"""
Update an existing enrollment for a dependent in a benefit offering.
Returns error if dependent is not enrolled in this offering.
Use createDependentBenefitEnrollment to create new enrollments.
"""
updateDependentBenefitEnrollment(input: UpdateDependentBenefitEnrollmentInput!): UpdateDependentBenefitEnrollmentResponse
"""Update an existing Division"""
updateDivision(input: UpdateDivisionInput!): UpdateDivisionResponse
"""Update an existing Individual"""
updateIndividual(input: UpdateIndividualInput!): UpdateIndividualResponse
"""Update an existing Organization"""
updateOrganization(input: UpdateOrganizationInput!): UpdateOrganizationResponse
"""Update an existing Organization Group"""
updateOrganizationGroup(input: UpdateOrganizationGroupInput!): UpdateOrganizationGroupResponse
"""Changes the fields you pass; omitted fields keep their values."""
updateWebhookEndpoint(input: UpdateWebhookEndpointInput!): WebhookEndpoint!
"""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 physical address of the Organization"""
address: PhysicalAddress
"""Divisions belonging to this Organization"""
divisions(
"""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 Divisions"""
where: OrganizationDivisionsFilterInput
): DivisionsResults!
"""The Employer Identification Number (EIN) of the Organization"""
ein: String
"""A partner-scoped external identifier for the Organization"""
externalId: String
"""The unique ID for the Organization"""
id: ID!
"""The user-displayable name of the Organization"""
name: String!
"""The Organization Group this Organization belongs to, if any"""
organizationGroup: OrganizationGroup
"""A short code that uniquely identifies the Organization"""
shortCode: String! @deprecated(reason: "Use id instead")
}
"""The outcome of assigning one organization to a brokerage firm"""
type OrganizationAssignmentResult {
"""
The submitted identifier, echoed verbatim — including when it resolved to nothing, and including a
value that is not a well-formed ULID. Use it to correlate a result back to what you sent.
"""
organizationUlid: ID!
"""
Populated only when `status` is `FAILED`, and null otherwise. A machine-readable constant, never a
sentence about a resource you cannot otherwise see. One of:
`ORGANIZATION_ULID_MALFORMED` — the value you sent is not a well-formed ULID. Decided before any
lookup, so it describes only your input.
`ORGANIZATION_NOT_FOUND_OR_NOT_PERMITTED` — the organization does not exist, belongs to another
partner, or is otherwise not one you control. These are deliberately indistinguishable: the single
fact behind this value is that the identifier was absent from the set of organizations you control.
"""
reason: String
"""What happened to this organization"""
status: OrganizationAssignmentStatus!
}
"""The outcome of assigning one organization to a brokerage firm"""
enum OrganizationAssignmentStatus {
"""An active assignment already existed. Nothing was written."""
ALREADY_ASSIGNED
"""
A new active assignment was written, or a previously removed one was restored. The two are reported
identically because the resulting state is identical.
"""
CREATED
"""
This organization was not assigned. See `reason`. Other elements in the same request are unaffected.
"""
FAILED
}
"""Filter criteria for querying Divisions on an Organization"""
input OrganizationDivisionsFilterInput {
"""If specified, only returns Divisions matching these IDs"""
ids: [ID!]
"""If specified, only returns Divisions matching these names"""
names: [String!]
}
"""Filter criteria used when querying for an Organization"""
input OrganizationFilterInput {
"""The external ID of the Organization (unique per partner)"""
externalId: String
"""The ID of the Organization"""
id: ID
}
"""
An Organization Group is an administrative container that groups related Organizations
under one umbrella. For example, a holding company with multiple subsidiaries.
"""
type OrganizationGroup {
"""The physical address of the Organization Group"""
address: PhysicalAddress
"""The Employer Identification Number (EIN) of the Organization Group"""
ein: String
"""A partner-scoped external identifier for the Organization Group"""
externalId: String
"""The unique ID for the Organization Group"""
id: ID!
"""The user-displayable name of the Organization Group"""
name: String!
"""The Organizations that belong to this group"""
organizations(after: String, first: Int = 100): OrganizationGroupOrganizationsResults!
"""
The US phone number of the Organization Group (10 digits, no punctuation)
"""
phone: PhoneNumber
}
"""Filter criteria used when querying for an Organization Group"""
input OrganizationGroupFilterInput {
"""The external ID of the Organization Group (unique per partner)"""
externalId: String
"""The ID of the Organization Group"""
id: ID
}
"""A page of Organizations belonging to an Organization Group"""
type OrganizationGroupOrganizationsResults {
nodes: [Organization!]!
pageInfo: PageInfo!
}
"""
A union representing the possible return types when querying for an Organization Group
"""
union OrganizationGroupResponse = BadRequestError | InternalServerError | OrganizationGroup
"""Filter criteria used when querying for Organization Groups"""
input OrganizationGroupsFilterInput {
"""
If specified, only returns Organization Groups matching these external IDs
"""
externalIds: [String!]
"""If specified, only returns Organization Groups matching these IDs"""
ids: [ID!]
"""If specified, only returns Organization Groups matching these names"""
names: [String!]
}
"""
A union representing the possible return types when querying for Organization Groups
"""
union OrganizationGroupsResponse = BadRequestError | InternalServerError | OrganizationGroupsResults
"""Represents a page of Organization Groups"""
type OrganizationGroupsResults {
nodes: [OrganizationGroup!]!
pageInfo: PageInfo!
}
"""Organization membership details including external user ID"""
type OrganizationMembership {
"""The Individual's external user ID"""
externalUserId: String
"""The unique ID for this organization membership"""
id: ID!
"""The date and time when this membership was marked as inactive"""
inactiveAt: DateTime
"""The organization this membership belongs to"""
organization: Organization!
"""The roles the user has for this organization"""
roles: [OrganizationRole!]!
"""The status of this organization membership"""
status: OrganizationMembershipStatus!
"""The unique public ULID for this organization membership"""
ulid: String
}
"""The status of an organization membership"""
enum OrganizationMembershipStatus {
"""The organization membership is active"""
ACTIVE
"""The organization membership is inactive"""
INACTIVE
}
"""Filter criteria for organization memberships"""
input OrganizationMembershipsFilterInput {
"""
If true, returns only active memberships. If false, returns all memberships (both active and inactive).
Defaults to true (active only).
"""
activeOnly: Boolean
"""Filter by organization IDs"""
organizationIds: [ID!]
}
"""Results for organization memberships query with pagination"""
type OrganizationMembershipsResults {
"""List of organization memberships"""
nodes: [OrganizationMembership!]!
"""Pagination information"""
pageInfo: PageInfo!
}
"""The status of an organization membership operation"""
enum OrganizationOperationStatus {
"""The membership was created"""
CREATED
"""The operation failed"""
FAILED
"""The membership was updated"""
UPDATED
}
"""
A union representing the possible return types when querying for an Organization
"""
union OrganizationResponse = BadRequestError | InternalServerError | Organization
"""The role of the organization member."""
enum OrganizationRole {
"""
An Admin role indicates that the user is an administrator of an organization. The administrator
role is distinct and independent from the Member role. An Admin may also be a Member, but in general
it is expected that admins and members will be distinct.
"""
ADMIN
"""
Agent is a limited-scope organization administrator with a curtailed permission set, scoped to an organization (and
its descendant divisions) via an AGENT membership. It is intentionally not part of the ADMIN/OWNER role-set.
"""
AGENT
"""
A Member role indicates that the user has consumer accounts associated with this organization. A Member
may also hold admin roles.
"""
MEMBER
"""
Owner is an Organization Administrator with elevated permissions.
and can be granted to additional admins as required.
"""
OWNER
}
"""The outcome of removing one organization from a brokerage firm"""
type OrganizationUnassignmentResult {
"""
The submitted identifier, echoed verbatim — including when it resolved to nothing, and including a
value that is not a well-formed ULID. Use it to correlate a result back to what you sent.
"""
organizationUlid: ID!
"""
Populated only when `status` is `FAILED`, and null otherwise. Carries the same two machine-readable
constants as `OrganizationAssignmentResult.reason`, on the same terms.
"""
reason: String
"""What happened to this organization"""
status: OrganizationUnassignmentStatus!
}
"""The outcome of removing one organization from a brokerage firm"""
enum OrganizationUnassignmentStatus {
"""
No active assignment existed, either because it was already removed or because it was never
assigned. The two are reported identically: both mean there was nothing to revoke.
"""
ALREADY_UNASSIGNED
"""
This organization was not removed. See `reason`. Other elements in the same request are unaffected.
"""
FAILED
"""An active assignment was found and removed."""
REMOVED
}
"""Filter criteria used when querying for Organizations"""
input OrganizationsFilterInput {
"""
If specified, only returns Organizations matching these Employer Identification Numbers (EINs)
"""
eins: [String!]
"""If specified, only returns Organizations matching these external IDs"""
externalIds: [String!]
"""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 brand available to the calling partner. `name` is the value to pass as `brand` on brand-aware
mutations to disambiguate a partner that operates more than one brand. A single-brand partner has
exactly one, with `isDefault` true.
"""
type PartnerBrand {
"""
Human-friendly display name for this brand, localized to the request language, if one is
configured. Null when the brand has no configured display name. Not unique: two brands of the
same partner may share a display name, so `name` is the identifier to key on.
"""
displayName: String
"""
True if this is the partner's default brand. A brand-aware mutation uses the default brand when
`brand` is omitted only if the partner has one brand. If the partner has more than one brand, an
omitted `brand` does not fall back to the default brand, and the mutation can fail with a
top-level AMBIGUOUS_SHARD error. Pass `brand` if the partner has more than one brand.
"""
isDefault: Boolean!
"""
The brand identifier; the value to pass as `brand` on brand-aware mutations
"""
name: ID!
}
"""The full name of a cardholder."""
type PersonName {
firstName: String!
lastName: String!
middleName: String
}
"""
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
input PrepareClaimDocumentUploadInput {
"""
A claim in `INFORMATION_REQUESTED` status whose document group receives the files. Specify either this or `individualId`.
"""
claimId: ID
"""The files to upload, from 1 to 10."""
files: [ClaimDocumentFileInput!]!
"""
The Individual (account holder) who will own a new document group. Specify either this or `claimId`.
"""
individualId: ID
}
"""The possible results of preparing a claim document upload."""
union PrepareClaimDocumentUploadResponse = BadRequestError | InternalServerError | PrepareClaimDocumentUploadResult
type PrepareClaimDocumentUploadResult {
"""
The document group that holds the files. When the group is new, pass it to `submitClaim` after the files are uploaded.
"""
documentGroupId: ID!
"""One upload link for each file, in the order of `input.files`."""
uploads: [ClaimDocumentUpload!]!
}
"""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 a single brand available to the calling partner, by name. A name that does not belong
to the calling partner is reported as not found.
"""
brand(where: BrandFilterInput!): BrandResponse
"""
Returns the brands available to the calling partner. Use the returned `name` as the `brand`
value on brand-aware mutations (for example `createOrganizationGroup`) when your partner
operates more than one brand. A single-brand partner receives exactly one entry.
"""
brands: BrandsResponse
"""
Lists the active brokerage firms that service at least one of your Organizations, with their
active brokers and the Organizations assigned to them.
An invalid cursor or a non-positive `first` returns a `BadRequestError`.
"""
brokerageFirms(
"""Return the elements after this cursor."""
after: String
"""The number of elements to retrieve per page."""
first: Int = 100
): BrokerageFirmsResponse
"""
A single card, specified by ID, belonging to one of this partner's members.
"""
card(where: CardFilterInput!): CardResponse
"""
Cards for this partner's members, newest first. Returns cards across all of
the partner's members by default; narrow to specific members with
`where.individualIds`. Filters that match nothing return an empty list, not
an error.
"""
cards(after: String, first: Int = 25, where: CardsFilterInput): CardsResponse
"""
A single reimbursement claim, specified by ID, belonging to one of this partner's members. A claim that
does not exist, belongs to another partner, or is a card-transaction substantiation returns the same
`NOT_FOUND` error.
"""
claim(where: ClaimFilterInput!): ClaimResponse
"""
Reimbursement claims for this partner's members, newest first. Returns claims across all of the
partner's members by default; narrow the results with `where`. Filters that match nothing, including
an empty list or IDs outside this partner, return an empty list, not an error. Card-transaction
substantiations are not included.
"""
claims(after: String, first: Int = 25, where: ClaimsFilterInput): ClaimsResponse
"""Fetch a single dependent by ID"""
dependent(where: DependentFilterInput!): DependentResponse
"""
List all dependents of an account holder.
`first` and `after` are not applied yet: every dependent is returned in one page, with
`hasNextPage` false.
"""
dependents(
"""Return the elements in the list that come after the specified cursor"""
after: String
"""The number of elements to retrieve per page (default: 25, max: 100)"""
first: Int = 25
"""Filter criteria used to match dependents"""
where: DependentsFilterInput!
): DependentsResponse
"""Returns a Division by ID"""
division(where: DivisionFilterInput!): DivisionResponse
"""Returns Divisions for an Organization matching the filter criteria"""
divisions(
"""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 Divisions"""
where: DivisionsFilterInput!
): DivisionsResponse
"""Returns an Individual by ID"""
individual(where: IndividualFilterInput!): IndividualResponse
"""Lists Individuals based on the specified filter criteria"""
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 the external platforms linked to your account. Pass an `id` as `platformIds` on
`individuals`, as `platformId` on `Individual.healthWallet`, or as `platformId` on
`Benefit.productCode`. An account linked to no platform receives an empty list.
"""
linkedExternalPlatforms: LinkedExternalPlatformsResponse
"""Returns an Organization by ID"""
organization(where: OrganizationFilterInput!): OrganizationResponse
"""Returns an Organization Group by ID"""
organizationGroup(where: OrganizationGroupFilterInput!): OrganizationGroupResponse
"""Returns Organization Groups matching the filter criteria"""
organizationGroups(
"""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 Organization Groups"""
where: OrganizationGroupsFilterInput
): OrganizationGroupsResponse
"""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.
The `results` field returns data inline and is intended for bounded responses only. A page that is too large to
return inline is rejected with a `BadRequestError` whose `code` is `REPORT_RESULTS_TOO_LARGE`. Select `downloadLinks`
instead to retrieve large pages and large exports as CSV files.
"""
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.
The `results` field is intended for bounded pages only. If the requested page is larger than the inline limit, the
query returns a `BadRequestError` instead; see the `results` field for details.
"""
page: Int
"""The ReportFilterInput specifies which report execution to retrieve."""
where: ReportFilterInput!
): ReportResponse
"""A single statement, specified by ID, belonging to an Individual."""
statement(where: StatementFilterInput!): StatementResponse
"""
Statements for an Individual, ordered by period start date, most recent first
(fixed order; no orderBy parameter). Today only HSA Benefits produce statements;
filters selecting other Benefit types return an empty list.
"""
statements(
"""Return the elements in the list that come after the specified cursor"""
after: String
"""The number of elements to retrieve per page (default: 25)"""
first: Int = 25
"""Filter criteria used to match statements"""
where: StatementsFilterInput!
): StatementsResponse
"""A single tax form, with box-level data, specified by ID."""
taxForm(where: TaxFormFilterInput!): TaxFormResponse
"""
Issues a secure, expiring download link for the rendered PDF of a tax form (the member copy). Perform a GET
against the returned link's `downloadUrl`, passing along all of the returned `requestHeaders`. Links expire;
issue a fresh link per download rather than storing them.
"""
taxFormDownloadLink(where: TaxFormFilterInput!): TaxFormDownloadLinkResponse
"""
Tax forms for an Individual, grouped by tax year. Today only HSA Benefits produce tax forms (1099-SA, 5498-SA);
filters selecting other Benefit types return an empty list.
"""
taxForms(where: TaxFormsFilterInput!): TaxFormsResponse
"""Returns a Verification by ID"""
verification(where: VerificationFilterInput!): VerificationResponse
"""
Deliveries to one endpoint, newest first. Query webhookDelivery for attempts.
"""
webhookDeliveries(
"""The endpoint whose deliveries to list."""
endpointId: ID!
"""Earliest occurredAt, as an ISO 8601 timestamp."""
from: String
"""At most 200 per page; 50 by default."""
page: PageInput
"""Only deliveries with this status."""
status: WebhookDeliveryStatus
"""Latest occurredAt, as an ISO 8601 timestamp."""
through: String
"""An event type, or webhook.test."""
type: String
): WebhookDeliveriesResults!
"""One delivery with its attempts, newest first."""
webhookDelivery(
"""The delivery id, the webhook-id header."""
deliveryId: ID!
): WebhookDelivery!
"""Your webhook endpoints, newest first."""
webhookEndpoints(
"""At most 200 per page; 50 by default."""
page: PageInput
): WebhookEndpointsResults!
"""The event types an endpoint can subscribe to."""
webhookEventTypes: [WebhookEventType!]!
}
"""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 days of the week on which the contributions will be made. Required if the strategy is 'WEEKLY' or 'BI_WEEKLY'. Do not set otherwise.
"""
daysOfWeek: [DaysOfWeek!]
"""
The date from which the schedule starts. The first contribution is scheduled on 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.
A scheduled date on a weekend or bank holiday moves to the previous business day, so a contribution can run before this date. For example, a scheduled date on a Sunday runs on the Friday before. If the previous business day is before today or before the benefit start date, the contribution runs on the next business day instead.
"""
minRunDate: LocalDate!
"""
Skips the third pay cycle in months that contain three biweekly cycles ("Biweekly 24"), yielding 24 contributions per year instead of 26. Only supported when the strategy is 'BI_WEEKLY' with exactly one entry in 'daysOfWeek'. Omitting this yields the standard 26-per-year biweekly schedule.
"""
skipThirdCycleOfMonth: Boolean
"""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 bi-weekly basis on the days specified by the 'daysOfWeek' field.
"""
BI_WEEKLY
"""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
"""
Contributions are made on a weekly basis on the days specified by the 'daysOfWeek' field.
"""
WEEKLY
}
"""
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
}
type RedeliverWebhooksResult {
"""The deliveries queued again."""
deliveries: [WebhookDelivery!]!
"""Pass as after to continue past the deliveries this call handled."""
endCursor: String
"""
More deliveries match. Call again with the same arguments and after: endCursor.
"""
hasMore: Boolean!
}
"""Input for removing a dependent from a benefit offering"""
input RemoveDependentBenefitEnrollmentInput {
"""Public ULID of the offering to remove enrollment from"""
benefitId: ID!
"""First Dollar User ID of the dependent"""
dependentId: ID!
}
"""Union response for removeDependentBenefitEnrollment mutation"""
union RemoveDependentBenefitEnrollmentResponse = BadRequestError | InternalServerError | RemoveDependentBenefitEnrollmentResult
"""Successful result of removing an enrollment"""
type RemoveDependentBenefitEnrollmentResult {
"""Success confirmation"""
success: Boolean!
}
"""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. Use this field, not `results`, to retrieve any page that is too large
to be returned inline.
"""
downloadLinks: [DownloadLink!]
"""
This field contains metadata about the current status of report generation, and fields originally passed in to
generate the report.
"""
execution: ReportExecution!
"""
If requested, this field lists EVERY file of the report in ordinal order, whatever the `page` input parameter was,
with each file's size, row count and download status. Unlike `downloadLinks`, it also includes files that could
not be given a link, so use it to tell a file that is unavailable from a file you did not request. It is null
when `execution.status` is not `SUCCEEDED`.
"""
files: [ReportFile!]
"""
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).
Inline results are intended for bounded responses. A page is returned here only if it has no more than the
configured maximum number of data rows (10,000 by default; the CSV header is not counted) and is within the configured
maximum size in bytes. These limits can differ between environments. The limits apply to the single page
requested, not to the whole report. A page that exceeds either limit is not returned, and the query responds with a
`BadRequestError` whose `code` is `REPORT_RESULTS_TOO_LARGE` and whose `retryable` is false, so repeating the same
request will not succeed.
To get a page that is too large, run the `report` query again for the same `page` without selecting `results`, and
select `downloadLinks` instead. Each link downloads that page as a CSV file. Select `files` (or the `rowCount` and
`byteSize` fields on `downloadLinks`) to see how large each page is before you request it. Large reports should
always be retrieved through `downloadLinks`.
"""
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
}
"""
One output file of a report. Reports generated before per-file details were recorded still list every file, with
the unknown fields null.
"""
type ReportFile {
"""
The size of this file in bytes as it is downloaded, a whole number. Null means unknown; it is never 0 as a
stand-in.
"""
byteSize: Float
"""
The name to show for this file. Null when it was not recorded, which is the case for reports generated before
per-file details were stored.
"""
displayFilename: String
"""
The 1-based position of this file within the report. It is the `page` number that selects this file.
"""
ordinal: Int
"""
The number of data rows in this file, not counting the header. Null means unknown; it is never 0 as a stand-in.
"""
rowCount: Int
"""Whether this file can be downloaded right now."""
status: ReportFileStatus
"""How many files the report has in total."""
totalFiles: Int
}
"""
Whether one file of a report can be downloaded right now. Only an AVAILABLE file is ever given a download link.
"""
enum ReportFileStatus {
"""The report succeeded and this file can be downloaded."""
AVAILABLE
"""
Storage marked this file as failed on a report that succeeded. A report that failed lists no files. It cannot be downloaded.
"""
FAILED
"""
Reserved. No file is listed while a report is generating, because the file count is only known once it succeeds. Read `execution.status` to tell a report that is still generating.
"""
PENDING
"""
The report succeeded but this file cannot be read: it is missing, deleted, past retention or superseded.
"""
UNAVAILABLE
}
"""
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. A `BadRequestError` with the code
`REPORT_RESULTS_TOO_LARGE` means the requested page is too large to return in `results`; it is not retryable. Request
that page through `downloadLinks` instead.
"""
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!
}
input RequestClaimInformationInput {
"""The ID of the claim."""
claimId: ID!
"""
More detail about the request, shown to the Individual. Required when `reason` is `OTHER`, and not accepted otherwise.
"""
comment: String
"""
A note added to the claim's notes, which the Individual and administrators can read.
"""
note: String
"""What information is needed."""
reason: ClaimInformationRequestedReason!
}
"""The possible results of requesting information about a claim."""
union RequestClaimInformationResponse = BadRequestError | InternalServerError | RequestClaimInformationResult
type RequestClaimInformationResult {
"""The claim after the request."""
claim: Claim!
}
input ResubmitClaimInput {
"""The ID of the claim to resubmit."""
claimId: ID!
"""
The Individual who received the service: the account holder or one of their dependents.
"""
claimantId: ID
"""
A response to the information request, added to the claim's notes, which the Individual and administrators can read.
"""
description: String
"""The corrected merchant name. Applies only to a claim with a merchant."""
merchant: ClaimMerchantInput
"""
Another of this Individual's providers, by `id`, or corrected details, by `name` and
`serviceCategory`. Corrected details are recorded as a new provider for this claim, keeping the current
provider's other details; the Individual's other claims are unchanged. Applies only to a claim with a
provider.
"""
provider: ClaimProviderInput
"""The last date of the service."""
serviceEndDate: LocalDate
"""The first date of the service."""
serviceStartDate: LocalDate
"""The date the expense was paid."""
transactionDate: LocalDate
}
"""The possible results of resubmitting a claim."""
union ResubmitClaimResponse = BadRequestError | InternalServerError | ResubmitClaimResult
type ResubmitClaimResult {
"""The resubmitted claim."""
claim: Claim!
}
"""
An input type used when reversing a previous funding transaction for a benefit and individual.
"""
input ReverseBenefitFundingForIndividualInput {
"""
Optional partial reversal amount. When provided, must be a positive USD amount no greater than the part of the
funding not yet reversed. For an HSA Benefit, it also cannot exceed the Individual's available balance. When
omitted, defaults to the full original funding amount. After a partial reversal, omitting the amount requests the
full original funding amount again, which exceeds what remains and is rejected, so pass the remainder explicitly.
"""
amount: MoneyInput
"""The ID of the benefit the individual is enrolled in"""
benefitId: ID!
"""Optional human-readable description recorded on the reversal entry."""
description: String
"""
The Transaction.id of the funding deposit to reverse, as listed on the Individual's Account.transactions. For a
deposit made by 'fundBenefitForIndividual', this is also the 'transactionId' on its FundBenefitForIndividualResult.
Deposits made by payroll contributions are reversed the same way, by their Transaction.id. Only funding deposits are
supported: a withdrawal, including a prior reversal, is rejected, and the ids of other credits (such as interest or
refunds) are not supported.
"""
fundingTransactionId: ID!
"""
A unique idempotency key for this reversal request. Repeated calls with the same key return the
prior result.
"""
idempotencyKey: String!
"""The ID of the individual whose funding is being reversed"""
individualId: ID!
}
"""
A union representing the possible return types when reversing a benefit funding for an individual.
"""
union ReverseBenefitFundingForIndividualResponse = BadRequestError | InternalServerError | ReverseBenefitFundingForIndividualResult
"""
The successful result of reversing a benefit funding for an individual.
"""
type ReverseBenefitFundingForIndividualResult {
"""The ID of the benefit whose funding was reversed"""
benefitId: ID!
"""The Transaction.id of the funding deposit that was reversed"""
fundingTransactionId: ID!
"""The ID of the individual whose funding was reversed"""
individualId: ID!
"""
The ID of the new reversal transaction recorded on the Individual's Benefit. It is the Transaction.id of the
reversal's withdrawal on the Individual's Account.transactions.
"""
reversalTransactionId: ID!
}
"""
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 the election amount for a benefit and individual
"""
input SetElectionAmountForBenefitAndIndividualInput {
"""The ID of the Benefit for which the election amount is being set"""
benefitId: ID!
"""
The annual election amount. Subject to IRS contribution limits.
Amount should be provided in cents (lowestDenominationAmount).
"""
electionAmount: MoneyInput!
"""The ID of the Individual for whom the election amount is being set"""
individualId: ID!
}
"""
A union representing the possible return types when setting the election amount for a benefit and individual
"""
union SetElectionAmountForBenefitAndIndividualResponse = BadRequestError | InternalServerError | SetElectionAmountForBenefitAndIndividualResult
"""
The successful result of setting the election amount for a benefit and individual
"""
type SetElectionAmountForBenefitAndIndividualResult {
"""The ID of the Benefit for which the election amount was set"""
benefitId: ID!
"""The ID of the Individual for whom the election amount was set"""
individualId: ID!
}
"""
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!
}
"""Structured data for a single account statement."""
type Statement {
"""The masked account number of the underlying account."""
accountNumberForDisplay: String!
"""The type of the Benefit whose account this statement covers."""
benefitType: BenefitType!
"""The account balance at the end of the statement period."""
endingBalance: Money!
id: ID!
"""
Interest earned by the account over the statement period, when available.
"""
interestEarnedForPeriod: Money
"""
Interest paid to the account during the statement period, when available.
"""
interestPaidForPeriod: Money
"""The last day of the statement period."""
periodEndDate: LocalDate!
"""The first day of the statement period."""
periodStartDate: LocalDate!
"""The account balance at the start of the statement period."""
startingBalance: Money!
"""All transactions that occurred during the statement period."""
transactions: [StatementTransaction!]!
}
"""Filter criteria for querying a single statement"""
input StatementFilterInput {
"""The ID of the statement."""
id: ID!
"""The ID of the Individual who owns the statement."""
individualId: ID!
}
"""Union response for statement query"""
union StatementResponse = BadRequestError | InternalServerError | Statement
"""
A summary of a single statement. Fetch full data with the `statement` query.
"""
type StatementSummary {
id: ID!
"""The last day of the statement period."""
periodEndDate: LocalDate!
"""The first day of the statement period."""
periodStartDate: LocalDate!
}
"""A single transaction appearing on a statement."""
type StatementTransaction {
"""
The amount of the transaction. Positive amounts are credits; negative amounts are debits.
"""
amount: Money!
"""The account balance immediately after this transaction."""
balance: Money!
"""
Optional category providing additional data about this transaction, e.g. a
contribution type for deposits.
"""
category: String
"""The date the transaction occurred."""
date: LocalDate!
"""The description of the transaction."""
description: String!
id: ID!
"""The type of this transaction."""
type: StatementTransactionType!
}
"""The type of a transaction appearing on a statement."""
enum StatementTransactionType {
CHARGE
DEPOSIT
HOLD
HOLD_RELEASE
INTEREST
INTERNAL
INVESTMENTS_DIVIDEND
INVESTMENTS_FEE
INVESTMENTS_INTEREST
INVESTMENTS_ORDER_BUY
INVESTMENTS_ORDER_SELL
INVESTMENTS_TRANSFER_INCOMING
INVESTMENTS_TRANSFER_OUTGOING
PAYMENT
REMOTE_DEPOSIT_CAPTURE
REVERSAL
UNKNOWN
WITHDRAWAL
}
"""Filter criteria for querying multiple statements"""
input StatementsFilterInput {
"""
When specified, only returns statements for accounts associated with these
Benefits. Yields an empty list when the Individual has no statement-bearing
account under any of these Benefits.
"""
benefitIds: [ID!]
"""
When specified, only returns statements for accounts of these Benefit types.
Today only HSA accounts produce statements; other types yield an empty list.
"""
benefitTypes: [BenefitType!]
"""The ID of the Individual whose statements to list."""
individualId: ID!
"""
When specified, only returns statements whose period ends on or before this date.
"""
periodEndsOnOrBefore: LocalDate
"""
When specified, only returns statements whose period starts on or after this date.
"""
periodStartsOnOrAfter: LocalDate
}
"""Union response for statements query"""
union StatementsResponse = BadRequestError | InternalServerError | StatementsResults
"""Paginated list of statement summaries"""
type StatementsResults {
"""List of statement summaries in this page"""
nodes: [StatementSummary!]!
"""Pagination metadata"""
pageInfo: PageInfo!
}
input SubmitClaimInput {
"""The amount of the expense. Must be positive, in `USD`."""
amount: MoneyInput!
"""
The Benefit to reimburse the claim from. The Individual must be enrolled in it.
"""
benefitId: ID!
"""
The Individual who received the service: the account holder or one of their dependents. Defaults to the account holder.
"""
claimantId: ID
"""
A description of the expense. It is added to the claim's notes, which the Individual and administrators
can read.
"""
description: String
"""
A document group from `prepareClaimDocumentUpload` for this Individual, holding the claim's documents.
"""
documentGroupId: ID
"""A key for ensuring request idempotency."""
idempotencyKey: String!
"""The Individual (account holder) to reimburse."""
individualId: ID!
"""
The merchant for the expense. Specify exactly one of `merchant` and `provider`.
"""
merchant: ClaimMerchantInput
"""
The care provider for the expense. Specify exactly one of `merchant` and `provider`.
"""
provider: ClaimProviderInput
"""
The last date of the service. Requires `serviceStartDate`, and must be on or after it.
"""
serviceEndDate: LocalDate
"""
The first date of the service. Defaults to `transactionDate`. Must fall within the Benefit's claim period.
"""
serviceStartDate: LocalDate
"""The date the expense was paid. Must not be in the future."""
transactionDate: LocalDate!
}
"""The possible results of submitting a claim."""
union SubmitClaimResponse = BadRequestError | InternalServerError | SubmitClaimResult
type SubmitClaimResult {
"""The submitted claim."""
claim: Claim!
}
"""
Languages supported by First Dollar
These are cased according to the ISO standard language format.
"""
enum SupportedLanguage {
"""English"""
en
"""Spanish (United States)"""
es_US
}
"""
The box-level data for a tax form; the concrete type depends on the form's `formType`.
"""
union TaxFormData = ContributionsTaxFormData | DistributionsTaxFormData
"""A tax form with its box-level data."""
type TaxFormDetail {
data: TaxFormData!
taxForm: IndividualTaxForm!
}
"""The possible return types when requesting a tax form download link."""
union TaxFormDownloadLinkResponse = BadRequestError | InternalServerError | TaxFormDownloadLinkResult
"""The success result for the `taxFormDownloadLink` query."""
type TaxFormDownloadLinkResult {
"""A secure, expiring link to download the rendered PDF."""
downloadLink: DownloadLink!
"""The tax form this link serves."""
taxForm: IndividualTaxForm!
}
"""Filter criteria identifying a single tax form."""
input TaxFormFilterInput {
"""
The ID of the tax form version, as returned by the `taxForms` or `taxForm` queries. Each correction is a
distinct version with its own ID.
"""
id: ID!
"""The ID of the Individual who owns the tax form."""
individualId: ID!
}
"""The possible return types when retrieving a single tax form."""
union TaxFormResponse = BadRequestError | InternalServerError | TaxFormDetail
"""The lifecycle status of a tax form."""
enum TaxFormStatus {
"""A correction to a previously fileable version."""
CORRECTED
"""The version filed (or fileable) with the IRS."""
FILEABLE
"""An early, informational version; final values may differ."""
PRELIMINARY
}
"""The kind of tax form."""
enum TaxFormType {
"""Form 5498-SA: contributions to an HSA."""
HSA_CONTRIBUTIONS
"""Form 1099-SA: distributions from an HSA."""
HSA_DISTRIBUTIONS
}
"""Filter criteria used when listing an Individual's tax forms."""
input TaxFormsFilterInput {
"""
When specified, only returns tax forms arising from accounts of these Benefit types. Today only HSA accounts
produce tax forms; other types yield an empty list.
"""
benefitTypes: [BenefitType!]
"""When specified, only returns tax forms of these types."""
formTypes: [TaxFormType!]
"""The ID of the Individual whose tax forms to list."""
individualId: ID!
"""
When specified, only returns tax forms for these tax years (e.g. ["2026"]).
"""
taxYears: [YearString!]
}
"""The possible return types when listing an Individual's tax forms."""
union TaxFormsResponse = BadRequestError | InternalServerError | TaxFormsResults
"""The success result for the `taxForms` query."""
type TaxFormsResults {
"""Tax forms grouped by tax year, most recent year first."""
annualTaxForms: [AnnualTaxForms!]!
}
"""
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. For a deposit that funded a Benefit, this is the 'fundingTransactionId' that
'reverseBenefitFundingForIndividual' accepts.
"""
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 removing organizations from a brokerage firm"""
input UnassignOrganizationsFromFirmInput {
"""The brokerage firm's identifier, as returned by `BrokerageFirm.id`"""
firmId: ID!
"""
Public ULIDs of the organizations to remove. Matched exactly and case-sensitively; organization
short codes are not accepted. Duplicates are collapsed to a single write but still produce one
result element each. Maximum 250 per request.
Only organizations you control are affected. Naming one you do not control fails that row alone and
changes nothing.
"""
organizationUlids: [ID!]!
}
"""
Union representing possible return types when removing organizations from a brokerage firm
"""
union UnassignOrganizationsFromFirmResponse = BadRequestError | InternalServerError | UnassignOrganizationsFromFirmResult
"""
The result of removing organizations from a brokerage firm. Returned even when every element failed —
the per-element `status` carries the outcome.
"""
type UnassignOrganizationsFromFirmResult {
"""
One element per submitted organization, in the order they were submitted. A duplicate identifier
produces one element per occurrence, each carrying the outcome of the single write it caused.
"""
organizationUnassignments: [OrganizationUnassignmentResult!]!
}
"""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!
}
input UnlockCardInput {
"""The ID of the card to unlock."""
cardId: ID!
individualId: ID
}
union UnlockCardResponse = BadRequestError | InternalServerError | UnlockCardResult
type UnlockCardResult {
"""The unlocked card."""
card: Card!
}
"""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!
}
input UpdateClaimInput {
"""The ID of the claim to correct."""
claimId: ID!
"""
The Individual who received the service: the account holder or one of their dependents.
"""
claimantId: ID
"""
A further description of the expense, added to the claim's notes, which the Individual and administrators can read.
"""
description: String
"""The corrected merchant name. Applies only to a claim with a merchant."""
merchant: ClaimMerchantInput
"""
Another of this Individual's providers, by `id`, or corrected details, by `name` and
`serviceCategory`. Corrected details are recorded as a new provider for this claim, keeping the current
provider's other details; the Individual's other claims are unchanged. Applies only to a claim with a
provider.
"""
provider: ClaimProviderInput
"""The last date of the service."""
serviceEndDate: LocalDate
"""The first date of the service."""
serviceStartDate: LocalDate
"""The date the expense was paid."""
transactionDate: LocalDate
}
"""The possible results of correcting a claim."""
union UpdateClaimResponse = BadRequestError | InternalServerError | UpdateClaimResult
type UpdateClaimResult {
"""
Whether any value differed from the claim's current values. False means nothing was changed.
"""
changed: Boolean!
"""The claim after the correction."""
claim: Claim!
}
"""Input for updating an existing enrollment for a dependent in a benefit"""
input UpdateDependentBenefitEnrollmentInput {
"""Public ULID of the offering"""
benefitId: ID!
"""First Dollar User ID of the dependent"""
dependentId: ID!
"""
New end datetime of eligibility (optional - omit to keep current value)
"""
eligibilityEndDate: DateTime
"""
New start datetime of eligibility (optional - omit to keep current value)
"""
eligibilityStartDate: DateTime
}
"""Union response for updateDependentBenefitEnrollment mutation"""
union UpdateDependentBenefitEnrollmentResponse = BadRequestError | InternalServerError | UpdateDependentBenefitEnrollmentResult
"""Successful result of updating an existing enrollment"""
type UpdateDependentBenefitEnrollmentResult {
"""The benefit enrollment that was updated"""
enrollment: DependentBenefitEnrollment!
}
"""Input for updating an existing dependent"""
input UpdateDependentInput {
"""New physical address (optional - omit to keep current value)"""
address: PhysicalAddressInput
"""New date of birth (optional - omit to keep current value)"""
dateOfBirth: LocalDate
"""New email address (optional - omit to keep current value)"""
email: EmailAddress
"""New first name (optional - omit to keep current value)"""
firstName: String
"""First Dollar User ID of the dependent to update"""
id: ID!
"""New last name (optional - omit to keep current value)"""
lastName: String
"""New phone number (optional - omit to keep current value)"""
phoneNumber: PhoneNumber
"""New relationship type (optional - omit to keep current value)"""
relationshipType: DependentRelationshipType
}
"""Union response for updateDependent mutation"""
union UpdateDependentResponse = BadRequestError | InternalServerError | UpdateDependentResult
"""Successful result of updating a dependent"""
type UpdateDependentResult {
"""The dependent that was updated"""
dependent: Dependent!
}
"""An input type used when updating a Division"""
input UpdateDivisionInput {
"""The physical address of the Division"""
address: PhysicalAddressInput
"""The Employer Identification Number (EIN) of the Division"""
ein: String
"""
A partner-scoped external identifier for the Division. Must be unique within the partner.
"""
externalId: String
"""The ID of the Division to update"""
id: ID!
"""The user-displayable name of the Division"""
name: String
}
"""
A union representing the possible return types when updating a Division
"""
union UpdateDivisionResponse = BadRequestError | InternalServerError | UpdateDivisionResult
"""The successful result of updating a Division"""
type UpdateDivisionResult {
"""The Division that was updated"""
division: Division!
}
"""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 Group"""
input UpdateOrganizationGroupInput {
"""The physical address of the Organization Group"""
address: PhysicalAddressInput
"""The Employer Identification Number (EIN) of the Organization Group"""
ein: String
"""
A partner-scoped external identifier for the Organization Group. Must be unique within the partner.
"""
externalId: String
"""The ID of the Organization Group to update"""
id: ID!
"""The user-displayable name of the Organization Group"""
name: String
"""
The US phone number of the Organization Group (10 digits, no punctuation)
"""
phone: PhoneNumber
}
"""
A union representing the possible return types when updating an Organization Group
"""
union UpdateOrganizationGroupResponse = BadRequestError | InternalServerError | UpdateOrganizationGroupResult
"""The successful result of updating an Organization Group"""
type UpdateOrganizationGroupResult {
"""The Organization Group that was updated"""
organizationGroup: OrganizationGroup!
}
"""An input type used when updating an Organization"""
input UpdateOrganizationInput {
"""The physical address of the Organization"""
address: PhysicalAddressInput
"""The Employer Identification Number (EIN) of the Organization"""
ein: String
"""
A partner-scoped external identifier for the Organization. Must be unique within the partner.
"""
externalId: String
"""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!
}
input UpdateWebhookEndpointInput {
"""A new label, at most 500 characters."""
description: String
"""The endpoint to change."""
endpointId: ID!
"""Replaces the subscribed types, from 1 to 20."""
eventTypes: [String!]
"""
Setting ACTIVE on a PAUSED or DISABLED endpoint also clears its failure counters.
"""
status: WebhookEditableEndpointStatus
"""A new https URL on port 443 at a hostname you control."""
url: String
}
"""An individual's account claim status."""
enum UserClaimedStatus {
CLAIMED
UNCLAIMED
}
"""
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 checks did not pass automatically, the verification could not be completed, or the case is in
manual review. A verification that the automated checks rejected has this status, not REJECTED.
"""
NEEDS_REVIEW
"""
A reviewer manually rejected the verification. Any system component requiring a valid
verification will not accept a verification in this status.
"""
REJECTED
"""
Verification is in progress: the checks have not finished. Read the Verification again later. If
it is still UNVERIFIED after some time, call `verifyIndividual` again.
"""
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!
}
type VisibleBrokerageFirm {
"""
Active brokers, with active sign-in credentials, who can reach at least one of `organizations`. A broker who serves none of your organizations is not listed.
"""
brokers: [BrokerageFirmBroker!]!
firm: BrokerageFirm!
"""
Only organizations in the authenticated partner's scope that are actively assigned to this firm.
"""
organizations: [BrokerageFirmOrganization!]!
}
"""Represents NULL values"""
scalar Void
"""One POST of a delivery to its endpoint."""
type WebhookAttempt {
"""Increases across redeliveries; numbers can have gaps."""
attemptNumber: Int!
"""An ISO 8601 UTC timestamp."""
createdAt: String!
"""
TIMEOUT, CONNECTION, TLS, BLOCKED_ADDRESS, HTTP_STATUS, or null on success.
"""
fault: String
id: ID!
latencyMs: Int!
"""The first 1 KiB of a failed attempt's response body; null on success."""
responseBody: String
"""The HTTP status, or null when no response arrived."""
responseStatus: Int
}
"""A page of webhook deliveries, newest first."""
type WebhookDeliveriesResults {
nodes: [WebhookDelivery!]!
pageInfo: PageInfo!
}
"""
One event sent to one endpoint. Its id is the webhook-id header and is stable across retries.
"""
type WebhookDelivery {
attemptCount: Int!
"""
Newest first. Select this on webhookDelivery; a list returns BAD_USER_INPUT.
"""
attempts: [WebhookAttempt!]!
"""An ISO 8601 UTC timestamp."""
createdAt: String!
endpointId: ID!
id: ID!
"""An ISO 8601 UTC timestamp. When PENDING, when the next attempt is due."""
nextAttemptAt: String!
"""An ISO 8601 UTC timestamp."""
occurredAt: String!
resourceId: ID!
resourceType: String!
status: WebhookDeliveryStatus!
type: String!
}
enum WebhookDeliveryStatus {
"""A terminal response, or every retry in the cycle failed."""
FAILED
"""An attempt is due, in flight, or waiting for a retry."""
PENDING
"""
The endpoint was paused, disabled, or deleted when the attempt was due.
"""
SKIPPED
"""The endpoint answered 2xx."""
SUCCEEDED
}
"""The endpoint statuses a caller can set."""
enum WebhookEditableEndpointStatus {
ACTIVE
PAUSED
}
"""An HTTPS receiver for webhook events."""
type WebhookEndpoint {
"""Attempts that failed since the last success."""
consecutiveFailedAttempts: Int!
"""Deliveries that failed since the last success."""
consecutiveFailedDeliveries: Int!
"""An ISO 8601 UTC timestamp."""
createdAt: String!
description: String!
"""Subscribed types from webhookEventTypes."""
eventTypes: [String!]!
"""An ISO 8601 UTC timestamp. The first failure after the last success."""
failingSince: String
id: ID!
"""
An ISO 8601 UTC timestamp. Refreshed at most hourly while deliveries keep succeeding.
"""
lastSuccessAt: String
status: WebhookEndpointStatus!
url: String!
}
"""
ACTIVE endpoints receive events. PAUSED and DISABLED endpoints skip them.
"""
enum WebhookEndpointStatus {
"""Receives subscribed events."""
ACTIVE
"""Disabled automatically after repeated failures. Set ACTIVE to resume."""
DISABLED
"""Paused by the partner. Events that occur while paused are SKIPPED."""
PAUSED
}
"""A page of webhook endpoints, newest first."""
type WebhookEndpointsResults {
nodes: [WebhookEndpoint!]!
pageInfo: PageInfo!
}
type WebhookEventType {
description: String!
type: String!
}
"""
Store signingSecret securely. It is returned only by creation and rotation.
"""
type WebhookSigningSecret {
endpoint: WebhookEndpoint!
"""A whsec_ secret for Standard Webhooks verification."""
signingSecret: String!
}
"""A year date string in YYYY format"""
scalar YearString