Account retrieval

Overview

Account Retrieval APIs are used to fetch member and account information required for wallet eligibility, payment setup, and account-based experiences. These APIs support multiple response shapes depending on consumer needs, ranging from full member profiles to lightweight account-only responses.

Supported Retrieval Scenarios

The Account Retrieval APIs can return:

• Member demographic details
• Member + plan details
• Account-only details (lightweight response)

Common Characteristics

All account retrieval queries:

• Require a UUID as input
• Internally invoke the Faro lookup endpoint
• Return wallet-eligible account data when applicable

Member + Account Retrieval

Description

Returns member demographic information along with all associated wallet-eligible accounts and related plan data. This is the most comprehensive retrieval option.

Available Queries

type Query {
  # Returns full member details including demographics, accounts, and plan-level data
  memberByUuid(uuid: ID!): Member

  # Identical to memberByUuid, explicitly used when planDetails
  # are required alongside member fields
  memberAccountDetails(uuid: ID!): Member

  # Returns only the accounts array (with plan details)
  # Skips member demographic fields for a lighter response
  accountDetails(uuid: ID!): [Account]
}


type Member @key(fields: "faroId") {
  faroId
  firstName
  middleName
  lastName
  preferredName
  birthDate
  gender
  maritalStatus
  webBrandId
  bankHold
  debitCardInd
  optumFinancialEligible
  cycUUID
  cycPersonId
  userKey
  addresses
  phones
  emails
  accounts
}


type Phone {
  type
  number
  preferred
}

type Email {
  type
  address
}

type Address {
  type
  line1
  line2
  line3
  line4
  line5
  city
  state
  zip
  country
  foreignAddress
  undeliverable
  preferred
}
``


type Account {
  accountId
  syntheticId
  accountCode
  platformCode
  accountType
  accountAlias
  employerId
  employerGroupName
  employerAlias
  employeeNumber
  hireDate
  payerNumber
  webBrandId
  accountName
  accountNameShort
  employStatusDesc
  nonExpiringPlan
  interestRate
  interestRatePrecise
  tcDate
  wcParticipant
  branchNumber
  employStatusCode
  tcFlag
  employerHSAEligible
  platformExtAccountHolderId
  tpaCompanyId
  tpaEmployeeId
  wexParticipantId
  employerPaidPlan
  benefitPlanInd
  stackedCardFl
  accountStatus
  currentBalance
  currentBalancePrecise
  availableBalance
  availableBalancePrecise
  totalBalance
  totalBalancePrecise
  planDetails
  notionalPlanDetails
}


type PlanDetail {
  accountStatus
  planId
  acctOpenedDate
  acctTerminationDate
  currentBalance
  currentBalancePrecise
  availableBalance
  availableBalancePrecise
  totalBalance
  totalBalancePrecise
  projectedBalance
  projectedBalancePrecise
  cashBalance
  cashBalancePrecise
  cyEmployeeContribution
  cyEmployeeContributionPrecise
  cyEmployerContribution
  cyEmployerContributionPrecise
  cyContributionLimit
  cyContributionLimitPrecise
  cyFilingStatus
  pyEmployeeContribution
  pyEmployeeContributionPrecise
  pyEmployerContribution
  pyEmployerContributionPrecise
  pyContributionLimit
  pyContributionLimitPrecise
  pyFilingStatus
  pyEmployeeContributionForCy
  pyEmployerContributionForCy
  accountStage
  accountStageDesc
  acctUpdatedDate
  platformAccountId
  platformDisplayName
  debitCardFl
  dependentDebitCardInd
  invstCurrStatusCode
  invstCurrStatusDesc
  invstCurrPlanName
  invstCurrSrtId
  invstCurrBalance
  invstCurrThresholdAmt
  invstCurrMinTransferAmt
  invstTotalBalance
  invstHSBAStatusCode
  invstHSBAStatusDesc
  invstHSBATotalBalance
  invstHSBACashBalance
  invstBMTStatusCode
  invstBMTStatusDesc
  invstBMTTotalBalance
  branding
}
``

type Branding {
  activationPhone
  bankPhone
  website
}

type NotionalPlanDetail {
  accountStatus
  planId
  postDeductPlanId
  acctOpenedDate
  acctTerminationDate
  acctCoverageStartDate
  acctCoverageEndDate
  acctPlanYearEffectiveDate
  acctPlanYearExpirationDate
  acctPlanYearGracePeriodExpirationDate
  acctPlanYearFinalServiceDate
  annualElection
  availableBalance
  remainingElection
  submittedClaims
  deniedClaims
  pendingClaims
  paidClaims
  ytdPayrollDeduction
  ytdContribution
  ytdPayments
  acctUpdatedDate
  platformDisplayName
  allowRecurringClaims
  debitCardFl
  dependentDebitCardInd
}