{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Employees"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"employees","__idx":0},"children":["Employees"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"onboarding","__idx":1},"children":["Onboarding"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set contribution configuration"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select and allocate investments"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sign agreements",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The amount of agreements to sign are determined based on investment selection."]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"contributions","__idx":2},"children":["Contributions"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"deferral-vs-contribution","__idx":3},"children":["Deferral vs Contribution"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deferral"]},": refers only to Roth and Traditional contributions coming from the employee that count towards the IRS deferral limit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contribution"]},": ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["any"]}," amount going into an employees 401k account including:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["deferral (employee contribution into Traditional and Roth 401k accounts)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["MBDR (a voluntary after-tax employee contribution)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["employer match (employer contribution into an employee’s ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["traditional"]}," 401k)",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["employer match contributions cannot go into Roth 401k accounts"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"investment-selection-and-allocation","__idx":4},"children":["Investment selection and allocation"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"employer-selected-v-brokerage-window","__idx":5},"children":["Employer Selected v. Brokerage Window"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Brokerage Window: includes the ability to search and add single name stocks (think ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AAPL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KO"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NVDA"]},"). Please note that these are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," employer selected and it should be clear that the user has not been recommended these investment options by their employer or 401k provider."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ListEmployerSelectedInvestmentOptions.min_employer_selected_allocation_bps"]}," in your code to enforce this even though it could be 0."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"onboarding-investment-selection-and-allocation","__idx":6},"children":["Onboarding investment selection and allocation"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_id"]}," in the set investment endpoints if you would like to do so."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"employee-account-linking-on-ssn-collision","__idx":7},"children":["Employee Account Linking on SSN Collision"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Employee accounts can be linked as follows:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PartnerEmployeeIngressSystem.getEmployeeOnboardingStatus"]}," will return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MUST_LINK_ACCOUNT"]}," status for KYC. This indicates that the user must log into their existing Basic Capital account."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fetch an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["employee_invite_token"]}," from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PartnerEmployeeIngressSystem"]},":"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetEmployeeInviteToken"]}," (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#getemployeeinvitetoken"},"children":["gRPC"]},") in the API reference."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Initiate SSO with query params ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["employeeInviteToken={token}"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action=link_account"]},", as described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/integration-guide/single-sign-on#initiate-sso"},"children":["Single sign-on"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"REDIRECT /oauth/{provider}/sso?employeeInviteToken={token}&action=link_account\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that you do not need to call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetOrCreateUser"]}," in this case. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["employeeInviteToken"]}," replaces the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inviteToken"]}," you would get from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetOrCreateUser"]}," call."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"post-onboarding","__idx":8},"children":["Post onboarding"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"post-onboarding-updates-to-investment-selection","__idx":9},"children":["Post-onboarding updates to investment selection"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rebalance: the ability to sell your current holdings and reallocate your existing balance into a different allocation of investments.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Note that there are some situations where a rebalance request will fail. We will provide a validate endpoint so you can determine this."]}]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Future allocation: the ability to change any future contribution from your paycheck, this can be done at any time.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"post-onboarding-apis","__idx":10},"children":["Post onboarding APIs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are all actions, statistics and performance for the employee post onboarding experience."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contribution rates"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#setemployeecontributionrates"},"children":["SetEmployeeContributionRates"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#getemployeecontributionrates"},"children":["GetEmployeeContributionRates"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Investment options and selections"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#listemployerselectedinvestmentoptions"},"children":["ListEmployerSelectedInvestmentOptions"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#listretirementmortgageinvestmentoptions"},"children":["ListRetirementMortgageInvestmentOptions"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#searchbrokeragewindowinvestmentoptions"},"children":["SearchBrokerageWindowInvestmentOptions"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#getaccount"},"children":["GetAccount"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#listaccounts"},"children":["ListAccounts"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#setaccountinvestmentselections"},"children":["SetAccountInvestmentSelections"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#setretirementmortgageinvestmentselections"},"children":["SetRetirementMortgageInvestmentSelections"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#getinvestmentselections"},"children":["GetInvestmentSelections"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#getinvestmentupdateavailability"},"children":["GetInvestmentUpdateAvailability"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#rebalanceaccountinvestmentselection"},"children":["RebalanceAccountInvestmentSelection"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#rebalanceretirementmortgageinvestmentselections"},"children":["RebalanceRetirementMortgageInvestmentSelections"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account and portfolio state"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#getemployeeinvitetoken"},"children":["GetEmployeeInviteToken"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#getemployeesummary"},"children":["GetEmployeeSummary"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#getaccountholdingssummary"},"children":["GetAccountHoldingsSummary"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#listaccountholdingsperformance"},"children":["ListAccountHoldingsPerformance"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#listaggregateholdingsperformance"},"children":["ListAggregateHoldingsPerformance"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Beneficiaries"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#createbeneficiaries"},"children":["CreateBeneficiaries"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#getbeneficiary"},"children":["GetBeneficiary"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#updatebeneficiaries"},"children":["UpdateBeneficiaries"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#listbeneficiaries"},"children":["ListBeneficiaries"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/grpc/partneremployeeingressservice#deletebeneficiary"},"children":["DeleteBeneficiary"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"limits","__idx":11},"children":["Limits"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"irs-deferral-limit","__idx":12},"children":["IRS deferral limit"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["does not"]}," include employer match or MBDR."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You may miss out on the full employer match ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["if"]}," you max out the IRS deferral limit in less than 12 months and your employer provides a match."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Example:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["per paycheck"]}," where I make a deferral, I will only get a match for 6 months ($6,125)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Some companies offer a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["every"]}," paycheck of the year. You can check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetEmployeeSetupEstimates.max_out_month"]}," to figure if an employee is maxing out too early."]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"mega-backdoor-roth-mbdr","__idx":13},"children":["Mega Backdoor Roth (MBDR)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The voluntary after-tax contribution should ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetEmployeeSetupEstimates.est_annual_mbdr"]},"."]}]},"headings":[{"value":"Employees","id":"employees","depth":1},{"value":"Onboarding","id":"onboarding","depth":2},{"value":"Contributions","id":"contributions","depth":3},{"value":"Deferral vs Contribution","id":"deferral-vs-contribution","depth":4},{"value":"Investment selection and allocation","id":"investment-selection-and-allocation","depth":3},{"value":"Employer Selected v. Brokerage Window","id":"employer-selected-v-brokerage-window","depth":4},{"value":"Onboarding investment selection and allocation","id":"onboarding-investment-selection-and-allocation","depth":4},{"value":"Employee Account Linking on SSN Collision","id":"employee-account-linking-on-ssn-collision","depth":3},{"value":"Post onboarding","id":"post-onboarding","depth":2},{"value":"Post-onboarding updates to investment selection","id":"post-onboarding-updates-to-investment-selection","depth":3},{"value":"Post onboarding APIs","id":"post-onboarding-apis","depth":3},{"value":"Limits","id":"limits","depth":2},{"value":"IRS deferral limit","id":"irs-deferral-limit","depth":3},{"value":"Mega Backdoor Roth (MBDR)","id":"mega-backdoor-roth-mbdr","depth":3}],"frontmatter":{"title":"Employees","seo":{"title":"Employees"}},"lastModified":"2026-09-14T19:48:02.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/integration-guide/employees","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}