Employees

Employees are not required to onboard since all employees are auto-enrolled. If no action is taken they will remain with the auto-enrollment set by their employer. If an employee does decide to make custom elections they will need to go through the following steps:

• Set contribution configuration
• Select and allocate investments
• Sign agreements
  • The amount of agreements to sign are determined based on investment selection.

• Deferral: refers only to Roth and Traditional contributions coming from the employee that count towards the IRS deferral limit.
• Contribution: any amount going into an employees 401k account including:
  • deferral (employee contribution into Traditional and Roth 401k accounts)
  • MBDR (a voluntary after-tax employee contribution)
  • employer match (employer contribution into an employee’s traditional 401k)
    • employer match contributions cannot go into Roth 401k accounts

• Employer selected: these are the investment options that the employer hand picks (or BC picks in the case of a fully managed plan) during plan configuration.
• Brokerage Window: includes the ability to search and add single name stocks (think AAPL, KO, NVDA). Please note that these are not employer selected and it should be clear that the user has not been recommended these investment options by their employer or 401k provider.
• Note: We currently have a requirement that the user puts 10% of its allocation into employer selected options. This will be going away soon and could change in the future, but we ask you still utilize ListEmployerSelectedInvestmentOptions.min_employer_selected_allocation_bps in your code to enforce this even though it could be 0.

• Today, we apply the same investment selections to both Traditional and Roth accounts if the user is contributing to both. It is fine to do this although technically you could allow a user to allocate differently to Traditional and Roth during onboarding and there is an optional account_id in the set investment endpoints if you would like to do so.

We enforce SSN uniqueness in our system over persons; we therefore cannot complete KYC for an employee if there is an SSN collision. If an onboarding employee already has an account in our system, they will need to add that employee to their existing account instead of creating a new one. This must be done before the employee can take any actions that require KYC to be complete, even if making updates via the PartnerAPI.

Employee accounts can be linked as follows:

1. PartnerEmployeeIngressSystem.getEmployeeOnboardingStatus will return a MUST_LINK_ACCOUNT status for KYC. This indicates that the user must log into their existing Basic Capital account.

2. Fetch an employee_invite_token from the PartnerEmployeeIngressSystem:

   See GetEmployeeInviteToken (gRPC) in the API reference.

3. Initiate SSO with query params employeeInviteToken={token} and action=link_account, as described in Single sign-on:

   REDIRECT /oauth/{provider}/sso?employeeInviteToken={token}&action=link_account

   Note that you do not need to call GetOrCreateUser in this case. The employeeInviteToken replaces the inviteToken you would get from the GetOrCreateUser call.

4. The user will be prompted to sign into their account and accept the invitation to add this new employment. We will verify that the user's DOB and SSN match to confirm they are linking the correct account. On success, we will add the employment to the account.

• Rebalance: the ability to sell your current holdings and reallocate your existing balance into a different allocation of investments.
  • Example: I have $100K in my 401k. All of it is in a Vanguard 2070 target date fund. If I want to reallocate $50K into NVDA, I would need to rebalance instead of changing my ongoing investment contributions.
    • Note that there are some situations where a rebalance request will fail. We will provide a validate endpoint so you can determine this.
• Future allocation: the ability to change any future contribution from your paycheck, this can be done at any time.
  • Example: I contribute 10% of my paycheck to my traditional 401k. My initial investment allocations are 75% Vanguard 2070 target date fund and 25% NVDA. I can update my future allocations to divvy up my paycheck contributions to 60% Vanguard 2070 target date fund and 40% NVDA.
• A user can rebalance or update future allocation per account. If you are going to update both accounts at the same time you should give a clear indication and allow the user to only update future or rebalance one specific account at a time.

These are all actions, statistics and performance for the employee post onboarding experience.

Contribution rates

• SetEmployeeContributionRates
• GetEmployeeContributionRates

Investment options and selections

• ListEmployerSelectedInvestmentOptions
• ListRetirementMortgageInvestmentOptions
• SearchBrokerageWindowInvestmentOptions
• GetAccount
• ListAccounts
• SetAccountInvestmentSelections
• SetRetirementMortgageInvestmentSelections
• GetInvestmentSelections
• GetInvestmentUpdateAvailability
• RebalanceAccountInvestmentSelection
• RebalanceRetirementMortgageInvestmentSelections

Account and portfolio state

• GetEmployeeInviteToken
• GetEmployeeSummary
• GetAccountHoldingsSummary
• ListAccountHoldingsPerformance
• ListAggregateHoldingsPerformance

Beneficiaries

• CreateBeneficiaries
• GetBeneficiary
• UpdateBeneficiaries
• ListBeneficiaries
• DeleteBeneficiary

• This is your annual deferral limit set by the IRS, as mentioned this only includes contributions to your Roth or Traditional (aka deferrals) accounts but does not include employer match or MBDR.
• You may miss out on the full employer match if you max out the IRS deferral limit in less than 12 months and your employer provides a match.
• Example:
  • In 2026, my salary is $245K and my employer does a 5% match. I contribute 20% of my paycheck. This results in me hitting the 2026 IRS deferral limit ($24.5K) in 6 months. Since the employer match is calculated per paycheck where I make a deferral, I will only get a match for 6 months ($6,125).
  • If I were to have set my contribution as 10% for every paycheck in 2026, then it will take me the full year to hit the 2026 IRS deferral limit of $24.5K. This results in an employer match contribution for every paycheck in 2026, yielding $12,250 in employer match contributions.
  • Some companies offer a true up reconciliation where they would calculate at the end of the year if you maxed out your deferral limit early in the year and did not receive the full employer match had you not maxed out the deferral limit early.
  • True up reconciliation is not guaranteed or required by law. As a result, we recommend the employee set their contribution rate to ensure that they have a deferral in every paycheck of the year. You can check GetEmployeeSetupEstimates.max_out_month to figure if an employee is maxing out too early.

MBDR is effectively the advanced mode ‘final boss’ for US retirement savers, allowing employees to contribute far in excess of the IRS deferral limit. In 2026, the MBDR limit is $72K. This limit comprises three buckets: the IRS deferral limit ($24.5K), the employer match contributions, and a voluntary after-tax bucket. In the example of a 5% employer match where the employee earns $245K, the employee can contribute an additional $35,250.

The voluntary after-tax contribution should only be enabled if the user is on track to contribute the full IRS deferral limit ($24.5K). You will be able to determine this with GetEmployeeSetupEstimates.est_annual_mbdr.