Skip to content

PartnerEmployeeIngressService

API to take actions on behalf of an employee.

Authorization: Bearer <token>
x-identity-uuid: <employee_uuid>
x-identity-type: EMPLOYEE

ListContributionTypesAvailableForSetup

Provides list of available contribution types for the employee to configure contribution percentages for based on the company's plan configuration. I.e. if an employer does not enable Roth, then only Traditional would be available for the employee to contribute to.

service PartnerEmployeeIngressService {
  rpc ListContributionTypesAvailableForSetup(ListContributionTypesAvailableForSetupRequest) returns (ListContributionTypesAvailableForSetupResponse);
}

message ListContributionTypesAvailableForSetupRequest {}

message ListContributionTypesAvailableForSetupResponse {
  repeated ContributionType contribution_types = 1;
}

Data types: ContributionType

GetEmployeeSetupLimits

Provides the contributions to date and the employer match.

service PartnerEmployeeIngressService {
  rpc GetEmployeeSetupLimits(GetEmployeeSetupLimitsRequest) returns (GetEmployeeSetupLimitsResponse);
}

message GetEmployeeSetupLimitsRequest {}

message GetEmployeeSetupLimitsResponse {
  Money annual_deferrals_to_date = 1;
  optional Money annual_match_to_date = 2;
  optional Money annual_post_tax_contributions_to_date = 3;
  repeated EmployerMatchTier employer_match_tiers = 4;
}

Data types: EmployerMatchTier, Money

GetEmployeeSetupEstimates

Provides estimates that can be used to help a user determine how much to contribute. Note: these are estimates with assumptions and this should be made clear to the employee.

service PartnerEmployeeIngressService {
  rpc GetEmployeeSetupEstimates(GetEmployeeSetupEstimatesRequest) returns (GetEmployeeSetupEstimatesResponse);
}

message GetEmployeeSetupEstimatesRequest {
  Money est_annual_income = 1;
  repeated ContributionInfo potential_contributions = 2;
  optional Date as_of_date = 3;
}

message GetEmployeeSetupEstimatesResponse {
  Money est_annual_employer_match = 1;
  Money est_annual_employer_match_remaining = 2;
  Money est_annual_deferral = 3;
  optional Money est_annual_mbdr = 4;
  Money est_retirement = 5;
  Money est_per_paycheck_deferral = 6;
  Money est_per_paycheck_employer_match = 7;
  int32 max_out_month = 8;
  optional Money est_per_paycheck_mbdr = 9;
}

Data types: ContributionInfo, Date, Money

SetEmployeeContributionRates

Sets contribution rates when initiated by an employee.

service PartnerEmployeeIngressService {
  rpc SetEmployeeContributionRates(SetEmployeeContributionRatesRequest) returns (SetEmployeeContributionRatesResponse);
}

message SetEmployeeContributionRatesRequest {
  repeated ContributionInfo employee_contributions = 1;
}

message SetEmployeeContributionRatesResponse {
  EmployeeDetails.OnboardingStatus onboarding_status = 1;
}

Data types: ContributionInfo, EmployeeDetails

GetEmployeeContributionRates

Returns contribution rates for an employee.

service PartnerEmployeeIngressService {
  rpc GetEmployeeContributionRates(GetEmployeeContributionRatesRequest) returns (GetEmployeeContributionRatesResponse);
}

message GetEmployeeContributionRatesRequest {}

message GetEmployeeContributionRatesResponse {
  repeated ContributionInfo employee_contributions = 1;
  bool has_set_custom_rates = 2;
}

Data types: ContributionInfo

ListEmployerSelectedInvestmentOptions

List of employer suggested investment options to provide as options to the employee. This corresponds to the investment options the employer selected during their onboarding.

service PartnerEmployeeIngressService {
  rpc ListEmployerSelectedInvestmentOptions(ListEmployerSelectedInvestmentOptionsRequest) returns (ListEmployerSelectedInvestmentOptionsResponse);
}

message ListEmployerSelectedInvestmentOptionsRequest {}

message ListEmployerSelectedInvestmentOptionsResponse {
  repeated AssetMetadata employer_selected_investment_options = 1;
  bool has_bw = 2;
  bool has_trm = 3;
  int32 min_employer_selected_allocation_bps = 4;
}

Data types: AssetMetadata

ListRetirementMortgageInvestmentOptions

List of investment options available for the Retirement Mortgage.

service PartnerEmployeeIngressService {
  rpc ListRetirementMortgageInvestmentOptions(ListRetirementMortgageInvestmentOptionsRequest) returns (ListRetirementMortgageInvestmentOptionsResponse);
}

message ListRetirementMortgageInvestmentOptionsRequest {}

message ListRetirementMortgageInvestmentOptionsResponse {
  repeated AssetMetadata retirement_mortgage_investment_options = 1;
}

Data types: AssetMetadata

SearchBrokerageWindowInvestmentOptions

Search within brokerage window, i.e. for a specific funds.

service PartnerEmployeeIngressService {
  rpc SearchBrokerageWindowInvestmentOptions(SearchBrokerageWindowInvestmentOptionsRequest) returns (SearchBrokerageWindowInvestmentOptionsResponse);
}

message SearchBrokerageWindowInvestmentOptionsRequest {
  Search search = 1;
}

message SearchBrokerageWindowInvestmentOptionsResponse {
  repeated AssetMetadata brokerage_window_investment_options = 1;
}

Data types: AssetMetadata, Search

DefaultBrokerageWindowInvestmentOptions

Provides two lists that can be used wherever you are displaying the Brokerage Window search. One is a default list of common investment options and the other is the list of most popular selections in Brokerage Window within Basic Capital participants.

service PartnerEmployeeIngressService {
  rpc DefaultBrokerageWindowInvestmentOptions(DefaultBrokerageWindowInvestmentOptionsRequest) returns (DefaultBrokerageWindowInvestmentOptionsResponse);
}

message DefaultBrokerageWindowInvestmentOptionsRequest {}

message DefaultBrokerageWindowInvestmentOptionsResponse {
  repeated AssetMetadata default_brokerage_window_investment_options = 1;
  repeated AssetMetadata most_popular_brokerage_window_investment_options = 2;
}

Data types: AssetMetadata

GetAccount

Returns the account for a given account_uuid.

service PartnerEmployeeIngressService {
  rpc GetAccount(GetAccountRequest) returns (GetAccountResponse);
}

message GetAccountRequest {
  string account_id = 1;
}

message GetAccountResponse {
  optional Account account = 1;
}

Data types: Account

ListAccounts

List accounts for the employee.

service PartnerEmployeeIngressService {
  rpc ListAccounts(ListAccountsRequest) returns (ListAccountsResponse);
}

message ListAccountsRequest {}

message ListAccountsResponse {
  repeated string account_ids = 1 [deprecated = true];
  repeated Account accounts = 2;
}

Data types: Account

SetAccountInvestmentSelections

Set the investment allocations for an employee. For each selection you must provide if the selection is part of EMPLOYER_SELECTED or BROKERAGE_WINDOW (if has_bw is true). If has_trm is true you will need to allow the employee to put a portion of their allocation towards the Retirement Mortgage — has_trm is currently false for every company while the Retirement Mortgage is unavailable. This is the only investment selection that does not require an asset_uuid.

Errors:

  • MIN_EMPLOYER_SELECTED_UNMET: if total selections with investment selection type EMPLOYER_SELECTED is less than min_employer_selected_allocation_bps.
  • ACCOUNT_ALLOCATION_REQUIREMENT_UNMET: if total allocation across all selections is not equal to 100.
  • MISSING_ASSET_UUID: If you provide a BROKERAGE_WINDOW or EMPLOYER_SELECTED investment selection without an asset_uuid.
  • EMPTY_SELECTIONS: tried to make a selection with an empty list.
  • PLAN_ACCOUNT_NOT_FOUND: account you are trying to update cannot be found.
service PartnerEmployeeIngressService {
  rpc SetAccountInvestmentSelections(SetAccountInvestmentSelectionsRequest) returns (SetAccountInvestmentSelectionsResponse);
}

message SetAccountInvestmentSelectionsRequest {
  optional string account_id = 1;
  repeated AccountInvestmentSelection selections = 2;
}

message SetAccountInvestmentSelectionsResponse {
  EmployeeDetails.OnboardingStatus onboarding_status = 1;
}

Data types: AccountInvestmentSelection, EmployeeDetails

SetRetirementMortgageInvestmentSelections

Set the retirement mortgage investment allocations for an employee. These are the allocations for funds within the retirement mortgage bucket that is part of the full account allocation.

Errors:

  • TRM_ALLOCATION_REQUIREMENT_UNMET: if total allocation across all selections is not equal to 100.
service PartnerEmployeeIngressService {
  rpc SetRetirementMortgageInvestmentSelections(SetRetirementMortgageInvestmentSelectionsRequest) returns (SetRetirementMortgageInvestmentSelectionsResponse);
}

message SetRetirementMortgageInvestmentSelectionsRequest {
  optional string account_id = 1;
  repeated TrmInvestmentSelection selections = 2;
}

message SetRetirementMortgageInvestmentSelectionsResponse {
  EmployeeDetails.OnboardingStatus onboarding_status = 1;
}

Data types: EmployeeDetails, TrmInvestmentSelection

GetInvestmentSelections

This can be used to fetch employee's currently set investment selections and includes the AssetMetadata for each investment.

service PartnerEmployeeIngressService {
  rpc GetInvestmentSelections(GetInvestmentSelectionsRequest) returns (GetInvestmentSelectionsResponse);
}

message GetInvestmentSelectionsRequest {
  optional string account_id = 1;
}

message GetInvestmentSelectionsResponse {
  repeated AccountInvestmentSelections accounts = 1;
}

Data types: AccountInvestmentSelections

GetEmployeeOnboardingStatus

This contains information about where the employee is in onboarding and if agreements are ready to sign.

service PartnerEmployeeIngressService {
  rpc GetEmployeeOnboardingStatus(GetEmployeeOnboardingStatusRequest) returns (GetEmployeeOnboardingStatusResponse);
}

message GetEmployeeOnboardingStatusRequest {}

message GetEmployeeOnboardingStatusResponse {
  EmployeeDetails.OnboardingStatus onboarding_status = 1;
}

Data types: EmployeeDetails

GetEmployeeInviteToken

Returns an invite token for the employee.

service PartnerEmployeeIngressService {
  rpc GetEmployeeInviteToken(GetEmployeeInviteTokenRequest) returns (GetEmployeeInviteTokenResponse);
}

message GetEmployeeInviteTokenRequest {}

message GetEmployeeInviteTokenResponse {
  string employee_invite_token = 1;
}

GetEmployeeSummary

Returns an employee's account summary.

Note: This is per account. To get the aggregate across Traditional and Roth you will need to do the addition on your side.

service PartnerEmployeeIngressService {
  rpc GetEmployeeSummary(GetEmployeeSummaryRequest) returns (GetEmployeeSummaryResponse);
}

message GetEmployeeSummaryRequest {
  optional Date on_date = 1;
  optional string account_id = 2;
}

message GetEmployeeSummaryResponse {
  message AccountEmployeeSummary {
    string account_id = 1;
    Money account_balance = 2;
    Money deferrals_ytd = 3;
    optional Money mbdr_contributions_ytd = 4;
    Money total_contributions_ytd = 5;
    optional Money employer_match_ytd = 6;
  }

  repeated AccountEmployeeSummary account_summary = 1;
}

Data types: Date, Money

GetAccountHoldingsSummary

Returns the holdings summary for a given account.

Note: This is per account. To get the aggregate across traditional and Roth you will need to do the addition on your side.

service PartnerEmployeeIngressService {
  rpc GetAccountHoldingsSummary(GetAccountHoldingsSummaryRequest) returns (GetAccountHoldingsSummaryResponse);
}

message GetAccountHoldingsSummaryRequest {
  optional Date on_date = 1;
  optional string account_id = 2;
}

message GetAccountHoldingsSummaryResponse {
  message AccountHoldingsSummary {
    message HoldingMetadata {
      AssetMetadata metadata = 1;
      int32 allocation_bps = 2;
      int32 gain_or_loss_bps = 3;
    }

    Money net_asset_value = 2;
    repeated HoldingMetadata holding_metadata = 3;
    optional Date first_contribution_date = 4;
  }

  repeated AccountHoldingsSummary account_holdings_summary = 1;
}

Data types: Date, Money

ListAccountHoldingsPerformance

Returns the holdings performance for a specific account over a given interval.

Note: This is per-account. Because these are percentages, they are not additive. Use ListAggregateHoldingsPerformance for the aggregated performance across accounts. If no account id is provided, we will paginate over the union of all accounts.

service PartnerEmployeeIngressService {
  rpc ListAccountHoldingsPerformance(ListAccountHoldingsPerformanceRequest) returns (ListAccountHoldingsPerformanceResponse);
}

message ListAccountHoldingsPerformanceRequest {
  NonDiscreteIntervalRequest interval = 1;
  optional string account_id = 2;
  optional LookbackType lookback = 3;
  optional com.basiccapital.common.external.PaginationRequest pagination = 4;
}

message ListAccountHoldingsPerformanceResponse {
  message AccountDatedHoldingsPerformance {
    repeated DatedHoldingsPerformance holdings_performance = 1;
    string account_id = 2;
  }

  repeated AccountDatedHoldingsPerformance accounts = 1;
  optional string next_page_token = 2;
}

Data types: DatedHoldingsPerformance, LookbackType, NonDiscreteIntervalRequest

See also: Performance and data querying

ListAggregateHoldingsPerformance

Return holdings performance aggregated across all accounts over a given interval.

Note: This aggregates across all accounts the employee has.

service PartnerEmployeeIngressService {
  rpc ListAggregateHoldingsPerformance(ListAggregateHoldingsPerformanceRequest) returns (ListAggregateHoldingsPerformanceResponse);
}

message ListAggregateHoldingsPerformanceRequest {
  NonDiscreteIntervalRequest interval = 1;
  optional LookbackType lookback = 2;
  optional com.basiccapital.common.external.PaginationRequest pagination = 3;
}

message ListAggregateHoldingsPerformanceResponse {
  repeated DatedHoldingsPerformance holdings_performance = 1;
  optional string next_page_token = 2;
}

Data types: DatedHoldingsPerformance, LookbackType, NonDiscreteIntervalRequest

See also: Performance and data querying

GetInvestmentUpdateAvailability

Call this to determine if an account can be rebalanced.

service PartnerEmployeeIngressService {
  rpc GetInvestmentUpdateAvailability(GetInvestmentUpdateAvailabilityRequest) returns (GetInvestmentUpdateAvailabilityResponse);
}

message GetInvestmentUpdateAvailabilityRequest {
  string account_id = 1;
}

message GetInvestmentUpdateAvailabilityResponse {
  bool plan_account_rebalance_enabled = 1;
  bool trm_rebalance_enabled = 2;
  repeated string liquidate_only_asset_uuids = 3;
}

RebalanceAccountInvestmentSelection

Rebalance a user's account holdings. Note: that in order to rebalance we sell all the holdings and reinvest them this is a different action than updating investment allocations for future contributions.

service PartnerEmployeeIngressService {
  rpc RebalanceAccountInvestmentSelection(RebalanceAccountInvestmentSelectionRequest) returns (RebalanceAccountInvestmentSelectionResponse);
}

message RebalanceAccountInvestmentSelectionRequest {
  string account_id = 1;
  repeated AccountInvestmentSelection selections = 2;
}

message RebalanceAccountInvestmentSelectionResponse {}

Data types: AccountInvestmentSelection

RebalanceRetirementMortgageInvestmentSelections

Rebalance a user's Retirement Mortgage holdings. Note: that in order to rebalance we sell all the holdings and re-invest them according to the new allocations. This is a different action than updating investment allocation for future contributions to the Retirement Mortgage.

service PartnerEmployeeIngressService {
  rpc RebalanceRetirementMortgageInvestmentSelections(RebalanceRetirementMortgageInvestmentSelectionsRequest) returns (RebalanceRetirementMortgageInvestmentSelectionsResponse);
}

message RebalanceRetirementMortgageInvestmentSelectionsRequest {
  string account_id = 1;
  repeated TrmInvestmentSelection selections = 2;
  bool apply_allocations_to_future = 3;
}

message RebalanceRetirementMortgageInvestmentSelectionsResponse {}

Data types: TrmInvestmentSelection

CreateBeneficiaries

  • If you create a Beneficiary before an employee has signed agreements the beneficiary status will be PENDING.
  • Allocations can be set per account. If no account id is provided we will apply to all accounts for a given Employee.
  • You can have an allocation for a given account that is < 100%. The remaining percentage legally would go to the legal definition of the default beneficiary.
  • Errors
    • If no allocations are provided.
    • If an allocation of 0 is provided.
    • Provide an allocation for a specific account and an allocation with no account selected.
    • If the total allocation for an account id is > 100% when creating this beneficiary allocations for accounts.
service PartnerEmployeeIngressService {
  rpc CreateBeneficiaries(CreateBeneficiariesRequest) returns (CreateBeneficiariesResponse);
}

message CreateBeneficiariesRequest {
  repeated BeneficiaryInfo beneficiary_data = 1;
}

message CreateBeneficiariesResponse {
  repeated Beneficiary beneficiaries = 1;
}

Data types: Beneficiary, BeneficiaryInfo

GetBeneficiary

Fetch a single beneficiary, including its allocations across accounts.

service PartnerEmployeeIngressService {
  rpc GetBeneficiary(GetBeneficiaryRequest) returns (GetBeneficiaryResponse);
}

message GetBeneficiaryRequest {
  string beneficiary_uuid = 1;
}

message GetBeneficiaryResponse {
  Beneficiary beneficiary = 1;
}

Data types: Beneficiary

UpdateBeneficiaries

Updates one or more existing beneficiaries. Every field except beneficiary_uuid is optional; omitted fields are left unchanged. Supplying an empty allocation_info array leaves the existing allocations unchanged.

  • Errors
    • If the total allocation for an account id is > 100% when creating this beneficiary allocations for accounts.
    • Provide an allocation for a specific account and an allocation with no account selected.
service PartnerEmployeeIngressService {
  rpc UpdateBeneficiaries(UpdateBeneficiariesRequest) returns (UpdateBeneficiariesResponse);
}

message UpdateBeneficiariesRequest {
  repeated UpdateBeneficiaryInfo update_beneficiaries = 1;
}

message UpdateBeneficiariesResponse {
  repeated Beneficiary beneficiaries = 1;
}

Data types: Beneficiary, UpdateBeneficiaryInfo

ListBeneficiaries

Lists the employee's beneficiaries. Scope the result to one account with account_uuid; if it is omitted, beneficiaries across every account the employee has are returned.

service PartnerEmployeeIngressService {
  rpc ListBeneficiaries(ListBeneficiariesRequest) returns (ListBeneficiariesResponse);
}

message ListBeneficiariesRequest {
  optional string account_uuid = 1;
}

message ListBeneficiariesResponse {
  repeated Beneficiary beneficiaries = 1;
}

Data types: Beneficiary

DeleteBeneficiary

Since you can have less than 100% for a given account when a beneficiary is deleted we will keep all other allocations the same and the remaining percentage will go to the default beneficiary.

service PartnerEmployeeIngressService {
  rpc DeleteBeneficiary(DeleteBeneficiaryRequest) returns (DeleteBeneficiaryResponse);
}

message DeleteBeneficiaryRequest {
  string beneficiary_uuid = 1;
}

message DeleteBeneficiaryResponse {}

PartnerCompanyIngress

PartnerConstantsIngress

Basic Capital
Copyright © Basic Capital 2026. All rights reserved.