Skip to content

PartnerCompanyIngressService

Endpoints taken on behalf of a company. CreateCompany and ListSupportedHrisProviders expect only the base Authorization header; all other company endpoints require the target company UUID.

Authorization: Bearer <token>
x-identity-uuid: <company_uuid>
x-identity-type: COMPANY

CreateCompany

Creates a company ready to initiate onboarding. This endpoint does not require the uuid or identity to be included. If a company exists with the same EIN, this will error and the company will not be created.

service PartnerCompanyIngressService {
  rpc CreateCompany(CreateCompanyRequest) returns (CreateCompanyResponse);
}

message CreateCompanyRequest {
  string external_id = 1;
  string business_name = 2;
  optional string business_phone = 3;
  string email = 4;
  com.basiccapital.common.external.Address address = 5;
  EntityType entity_type = 6;
  string ein = 7;
  optional string state_of_organization = 8;
}

message CreateCompanyResponse {
  Company company = 1;
}

Data types: Company, EntityType

GetCompany

Returns the company.

service PartnerCompanyIngressService {
  rpc GetCompany(GetCompanyRequest) returns (GetCompanyResponse);
}

message GetCompanyRequest {}

message GetCompanyResponse {
  Company company = 1;
}

Data types: Company

UpdateCompany

Updates company fields. Note that if a field is not included in the update it will remain unchanged.

service PartnerCompanyIngressService {
  rpc UpdateCompany(UpdateCompanyRequest) returns (UpdateCompanyResponse);
}

message UpdateCompanyRequest {
  optional com.basiccapital.common.external.Address address = 1;
  optional string business_name = 2;
  optional string business_phone = 3;
  optional string state_of_organization = 4;
  optional string email = 5;
}

message UpdateCompanyResponse {
  Company company = 1;
}

Data types: Company

GetOnboardingStatus

Get onboarding status for the company. All sections are required for the company to complete onboarding. ready_to_enroll_employees signals when you can start adding employees via AddEmployees and ready_to_start_deductions signals when you can start deductions for enrolled employees.

service PartnerCompanyIngressService {
  rpc GetOnboardingStatus(GetOnboardingStatusRequest) returns (GetOnboardingStatusResponse);
}

message GetOnboardingStatusRequest {}

message GetOnboardingStatusResponse {
  enum OnboardingStatus {
    UNKNOWN_ONBOARDING_STATUS = 0;
    ONBOARDING_IN_PROGRESS = 1;
    ONBOARDING_COMPLETE = 2;
  }

  enum SectionStatus {
    UNKNOWN_SECTION_STATUS = 0;
    BLOCKED = 1;
    PENDING = 2;
    IN_PROGRESS = 3;
    COMPLETE = 4;
  }

  SectionStatus plan_configuration_status = 1;
  SectionStatus sign_agreements_status = 2;
  SectionStatus bank_linking_status = 3;
  bool ready_to_enroll_employees = 4;
  bool ready_to_start_deductions = 5;
  OnboardingStatus status = 6;
  SectionStatus trustee_kyc_status = 7;
  SectionStatus kyb_status = 8;
  SectionStatus link_hris_status = 9;
}

Starts the bank linking process and returns the token that the client side Plaid widget will need.

service PartnerCompanyIngressService {
  rpc BeginBankLink(BeginBankLinkRequest) returns (BeginBankLinkResponse);
}

message BeginBankLinkRequest {}

message BeginBankLinkResponse {
  string link_token = 1;
}

This will throw a HAS_MAX_LINKED_BANK_ACCOUNTS error if there is already an account linked for this company. Currently only one bank is allowed for per company.

The BankAccount object will include an is_verified. Plaid may require a micro-deposit to verify the bank account. When this is complete, the company can be verified via the VerifyBankLink endpoint.

service PartnerCompanyIngressService {
  rpc CompleteBankLink(CompleteBankLinkRequest) returns (CompleteBankLinkResponse);
}

message CompleteBankLinkRequest {
  string public_token = 1;
}

message CompleteBankLinkResponse {
  BankAccount bank_account = 1;
}

Data types: BankAccount

This endpoint is used to verify bank link, either if the initial setup requires verification, or if the link expires. The United States requires ACH credentials to be re-verified every 12 months; but individual states and territories may have a shorter expiry period.

service PartnerCompanyIngressService {
  rpc VerifyBankLink(VerifyBankLinkRequest) returns (VerifyBankLinkResponse);
}

message VerifyBankLinkRequest {
  string bank_account_uuid = 1;
}

message VerifyBankLinkResponse {
  string link_token = 1;
}

ListBankAccounts

Lists linked bank accounts for the company.

service PartnerCompanyIngressService {
  rpc ListBankAccounts(ListBankAccountsRequest) returns (ListBankAccountsResponse);
}

message ListBankAccountsRequest {}

message ListBankAccountsResponse {
  repeated BankAccount accounts = 1;
  int32 max_linked_bank_accounts = 2;
}

Data types: BankAccount

UnlinkLinkedAccount

Remove a linked bank account. If a company wants to link a different bank account you will first have to unlink the currently linked bank account.

service PartnerCompanyIngressService {
  rpc UnlinkLinkedAccount(UnlinkLinkedAccountRequest) returns (UnlinkLinkedAccountResponse);
}

message UnlinkLinkedAccountRequest {
  string linked_account_uuid = 1;
}

message UnlinkLinkedAccountResponse {}

SetTrustee

Trustee must be set before a company can sign agreements since the Trustee is the signing party. We recommend partners place setting the trustee at the beginning of their onboarding flow even though it is not blocking for the majority of the onboarding steps.

Note: If the partner is also serving as the identity provider, the external_id should be the identifier we use when pulling KYC for the trustee. Calling SetTrustee will overwrite the previously set trustee if one exists. If the partner is not acting as the identity provider then KYC will need to be completed for the Trustee before they can sign agreements.

service PartnerCompanyIngressService {
  rpc SetTrustee(SetTrusteeRequest) returns (SetTrusteeResponse);
}

message SetTrusteeRequest {
  string external_id = 1;
  string email = 2;
  string given_name = 3;
  string surname = 4;
}

message SetTrusteeResponse {
  TrusteeInfo trustee_info = 1;
}

Data types: TrusteeInfo

GetTrustee

Returns trustee info if a trustee is set.

service PartnerCompanyIngressService {
  rpc GetTrustee(GetTrusteeRequest) returns (GetTrusteeResponse);
}

message GetTrusteeRequest {}

message GetTrusteeResponse {
  optional TrusteeInfo trustee_info = 1;
}

Data types: TrusteeInfo

CreatePlanConfiguration

This starts off the plan configuration. It requires a management option because this determines which configurations will be prefilled in the PlanConfiguration. For example if the user selects PARTNER_FULLY_MANAGED the InvestmentConfig will be filled and in a locked state. Note: each company can only have one plan configuration.

service PartnerCompanyIngressService {
  rpc CreatePlanConfiguration(CreatePlanConfigurationRequest) returns (CreatePlanConfigurationResponse);
}

message CreatePlanConfigurationRequest {
  ManagementOptionType management_option_type = 1;
}

message CreatePlanConfigurationResponse {
  PlanConfiguration plan_configuration = 1;
}

Data types: ManagementOptionType, PlanConfiguration

GetPlanConfiguration

Returns the plan configuration.

service PartnerCompanyIngressService {
  rpc GetPlanConfiguration(GetPlanConfigurationRequest) returns (GetPlanConfigurationResponse);
}

message GetPlanConfigurationRequest {}

message GetPlanConfigurationResponse {
  PlanConfiguration plan_configuration = 1;
}

Data types: PlanConfiguration

UpdatePlanConfiguration

This can be used to update any part of the plan configuration.

Will return one of the following errors in these cases:

  • EDIT_LOCKED_SECTION: If you attempt to update any sections that have a LOCKED status; this will also error if another part of the update locks a previously unlocked section that you then attempt to edit.
  • INVALID_INVESTMENT_CONFIGURATION: If you provide an incorrect QDIA + ticker_symbol combo e.g. VANGUARD with no Vanguard TDF included when setting InvestmentConfig
  • INVALID_CORE_CONFIGURATION:
    • If you set enable_mega_backdoor_roth to true and enable_roth to false. The latter must be true for enable_mega_backdoor_roth to be true.
    • If you are setting the hour eligibility rule on the config there is a max you can set the hour requirement at for a given period.
service PartnerCompanyIngressService {
  rpc UpdatePlanConfiguration(UpdatePlanConfigurationRequest) returns (UpdatePlanConfigurationResponse);
}

message UpdatePlanConfigurationRequest {
  optional SetManagementOptionTypeRequest management_option = 1;
  optional SetInvestmentConfigRequest investment_config = 2;
  optional UpdateCoreConfigRequest core_config = 3;
}

message UpdatePlanConfigurationResponse {
  PlanConfiguration plan_configuration = 1;
}

Data types: PlanConfiguration

ValidatePlanConfiguration

Checks the current plan configuration against the Safe Harbor and Secure Act 2.0 requirements described in Safe Harbor and Secure Act 2.0. Returns one ValidationResult per ValidationType, with is_valid and a debug_description explaining any failure.

service PartnerCompanyIngressService {
  rpc ValidatePlanConfiguration(ValidatePlanConfigurationRequest) returns (ValidatePlanConfigurationResponse);
}

message ValidatePlanConfigurationRequest {}

message ValidatePlanConfigurationResponse {
  message ValidationResult {
    ValidationType type = 1;
    bool is_valid = 2;
    string debug_description = 3;
  }

  enum ValidationType {
    UNKNOWN_VALIDATION_TYPE = 0;
    SECURE_ACT = 1;
    SAFE_HARBOR = 2;
  }

  repeated ValidationResult validation_results = 3;
}

ListManagementOptions

Note: Bearer token only

Provides the list of management options available to that company.

service PartnerCompanyIngressService {
  rpc ListManagementOptions(ListManagementOptionsRequest) returns (ListManagementOptionsResponse);
}

message ListManagementOptionsRequest {}

message ListManagementOptionsResponse {
  repeated ManagementOption management_options = 1;
}

Data types: ManagementOption

SetManagementOptionType

This updates your management option and will also have the side effect of setting your InvestmentConfig if you switch from PARTNER_EMPLOYER_MANAGED to PARTNER_FULLY_MANAGED.

service PartnerCompanyIngressService {
  rpc SetManagementOptionType(SetManagementOptionTypeRequest) returns (SetManagementOptionTypeResponse);
}

message SetManagementOptionTypeRequest {
  ManagementOptionType management_option_type = 1;
}

message SetManagementOptionTypeResponse {
  PlanConfiguration plan_configuration = 1;
}

Data types: ManagementOptionType, PlanConfiguration

SetInvestmentConfig

Sets the InvestmentConfig. Note: This overwrites the entire investment config when called.

Errors:

  • INVALID_INVESTMENT_CONFIGURATION: If you provide an incorrect QDIA + ticker_symbol combo i.e. VANGUARD with no Vanguard TDF included.
  • EDIT_LOCKED_SECTION: If this section is locked
service PartnerCompanyIngressService {
  rpc SetInvestmentConfig(SetInvestmentConfigRequest) returns (SetInvestmentConfigResponse);
}

message SetInvestmentConfigRequest {
  QdiaType qdia_type = 1;
  repeated string ticker_symbols = 2;
}

message SetInvestmentConfigResponse {
  PlanConfiguration plan_configuration = 1;
}

Data types: PlanConfiguration, QdiaType

ListAvailablePlanInvestmentOptions

Note: Bearer token only

Provides a list of available investment options including popular investment options and QDIA for both Vanguard and Fidelity. Each investment option has an AssetSuggestionType; the corresponding target date funds for the QDIA you choose will be marked as REQUIRED indicating that these assets must be included when setting investment options for that QDIA type.

service PartnerCompanyIngressService {
  rpc ListAvailablePlanInvestmentOptions(ListAvailablePlanInvestmentOptionsRequest) returns (ListAvailablePlanInvestmentOptionsResponse);
}

message ListAvailablePlanInvestmentOptionsRequest {
  QdiaType qdia_type = 1;
}

message ListAvailablePlanInvestmentOptionsResponse {
  repeated AssetMetadata investment_options = 1;
}

Data types: AssetMetadata, QdiaType

ListQdiaFunds

Note: Bearer token only

List all the possible QDIA funds to pick from.

service PartnerCompanyIngressService {
  rpc ListQdiaFunds(ListQdiaFundsRequest) returns (ListQdiaFundsResponse);
}

message ListQdiaFundsRequest {}

message ListQdiaFundsResponse {
  repeated QdiaType qdia = 1;
}

Data types: QdiaType

GetCuratedInvestmentConfig

Returns the preset investment config as determined by Basic Capital and is what the InvestmentConfig will be set to if the PARTNER_FULLY_MANAGED management option is selected. This may vary across companies, so must be requested on a per-company basis.

service PartnerCompanyIngressService {
  rpc GetCuratedInvestmentConfig(GetCuratedInvestmentConfigRequest) returns (GetCuratedInvestmentConfigResponse);
}

message GetCuratedInvestmentConfigRequest {}

message GetCuratedInvestmentConfigResponse {
  InvestmentConfig investment_config = 1;
}

Data types: InvestmentConfig

UpdateCoreConfig

Updates core settings. Note: if a field is not included the existing value on the config will remain.

Errors:

  • INVALID_CORE_CONFIGURATION:
    • If you set enable_mega_backdoor_roth to true and enable_roth to false. The latter must be true for enable_mega_backdoor_roth to be true.
    • If you are setting the hour eligibility rule on the config there is a max you can set the hour requirement at for a given period.
  • EDIT_LOCKED_SECTION: If this section is locked
service PartnerCompanyIngressService {
  rpc UpdateCoreConfig(UpdateCoreConfigRequest) returns (UpdateCoreConfigResponse);
}

message UpdateCoreConfigRequest {
  repeated EmployerMatchTier employer_match_tiers = 1;
  optional bool enable_roth = 2;
  optional bool enable_plan401K_loans = 3;
  optional bool enable_mega_backdoor_roth = 4;
  optional int32 employee_auto_enrollment_bps = 5;
  optional int32 employee_auto_enrollment_increase_bps = 6;
  optional Date ideal_start_date = 7;
  optional EligibilityConfig eligibility_config = 8;
}

message UpdateCoreConfigResponse {
  PlanConfiguration plan_configuration = 1;
}

Data types: Date, EligibilityConfig, EmployerMatchTier, PlanConfiguration

ClearCoreConfigEmployerMatch

Clears the employer match on the CoreConfig. Note: this should be used to set no employer match rather than setting match to 0%.

service PartnerCompanyIngressService {
  rpc ClearCoreConfigEmployerMatch(ClearCoreConfigEmployerMatchRequest) returns (ClearCoreConfigEmployerMatchResponse);
}

message ClearCoreConfigEmployerMatchRequest {}

message ClearCoreConfigEmployerMatchResponse {
  PlanConfiguration plan_configuration = 1;
}

Data types: PlanConfiguration

ClearCoreConfigEligibility

Clears the eligibility config.

service PartnerCompanyIngressService {
  rpc ClearCoreConfigEligibility(ClearCoreConfigEligibilityRequest) returns (ClearCoreConfigEligibilityResponse);
}

message ClearCoreConfigEligibilityRequest {}

message ClearCoreConfigEligibilityResponse {
  PlanConfiguration plan_configuration = 1;
}

Data types: PlanConfiguration

DeletePlanConfiguration

This will delete a plan configuration. Note: if any of the sections of the PlanConfiguration object are in LOCKED_INCOMPLETE state (meaning the plan configuration needs manual intervention) or the plan configuration has been submitted then this will fail.

service PartnerCompanyIngressService {
  rpc DeletePlanConfiguration(DeletePlanConfigurationRequest) returns (DeletePlanConfigurationResponse);
}

message DeletePlanConfigurationRequest {}

message DeletePlanConfigurationResponse {}

SubmitPlanConfiguration

The PlanConfiguration must be READY_FOR_SUBMISSION otherwise attempting to submit will cause an error. Once submitted, the company cannot edit the configuration without reaching out to the Basic Capital Ops team.

service PartnerCompanyIngressService {
  rpc SubmitPlanConfiguration(SubmitPlanConfigurationRequest) returns (SubmitPlanConfigurationResponse);
}

message SubmitPlanConfigurationRequest {}

message SubmitPlanConfigurationResponse {
  PlanConfiguration plan_configuration = 1;
}

Data types: PlanConfiguration

AddEmployees

Adds a new employee to a specific company. This action will error if the company is not marked as ready_to_enroll_employees. Each employee added will be returned with AddEmployeeResult which could include an error if the employee was unable to be added.

Errors:

  • START_DATE_IN_FUTURE: Employees can only be added on or after their start date.
  • MISSING_INFORMATIONAL: Required information for the employee is missing.
  • READY_TERMINATED: Employees cannot be added if they are already terminated.
  • INTERNAL_ERROR: Internal error.
service PartnerCompanyIngressService {
  rpc AddEmployees(AddEmployeesRequest) returns (AddEmployeesResponse);
}

message AddEmployeesRequest {
  repeated CreateEmployeeInfo create_employees_info = 1;
}

message AddEmployeesResponse {
  repeated AddEmployeeResult results = 1;
}

Data types: AddEmployeeResult, CreateEmployeeInfo

ListEmployeeDetails

Fetches a list of employee details.

service PartnerCompanyIngressService {
  rpc ListEmployeeDetails(ListEmployeeDetailsRequest) returns (ListEmployeeDetailsResponse);
}

message ListEmployeeDetailsRequest {
  optional com.basiccapital.common.external.PaginationRequest pagination = 1;
  repeated EmployeeDetails.ParticipationStatus statuses = 2;
  optional string search_query = 3;
}

message ListEmployeeDetailsResponse {
  repeated EmployeeDetails employees = 1;
  optional string next_page_token = 2;
}

Data types: EmployeeDetails

GetEmployeeDetails

Fetch a single employee's details.

service PartnerCompanyIngressService {
  rpc GetEmployeeDetails(GetEmployeeDetailsRequest) returns (GetEmployeeDetailsResponse);
}

message GetEmployeeDetailsRequest {
  string employee_uuid = 1;
}

message GetEmployeeDetailsResponse {
  EmployeeDetails employee = 1;
}

Data types: EmployeeDetails

SetEmployeeContributionRates

Endpoint to set contribution rates when initiated by an employer. Note: this should only be used in an employer initiated contribution change on behalf of an employee in an employer application.

service PartnerCompanyIngressService {
  rpc SetEmployeeContributionRates(CompanySetEmployeeContributionRatesRequest) returns (CompanySetEmployeeContributionRatesResponse);
}

message CompanySetEmployeeContributionRatesRequest {
  string employee_uuid = 1;
  repeated ContributionInfo employee_contribution_rates = 2;
}

message CompanySetEmployeeContributionRatesResponse {}

Data types: ContributionInfo

TerminateEmployee

Mark an employee as terminated.

service PartnerCompanyIngressService {
  rpc TerminateEmployee(TerminateEmployeeRequest) returns (TerminateEmployeeResponse);
}

message TerminateEmployeeRequest {
  string employee_uuid = 1;
  Date termination_date = 2;
}

message TerminateEmployeeResponse {
  EmployeeDetails employee = 1;
}

Data types: Date, EmployeeDetails

ListTransactions

List transactions for the company.

service PartnerCompanyIngressService {
  rpc ListTransactions(ListTransactionsRequest) returns (ListTransactionsResponse);
}

message ListTransactionsRequest {
  optional com.basiccapital.common.external.PaginationRequest pagination = 1;
  optional IntervalRequest interval = 2;
  optional Transaction.TransactionType transaction_type = 3;
  repeated string payroll_event_uuids = 4;
}

message ListTransactionsResponse {
  repeated Transaction transactions = 1;
  optional string next_page_token = 2;
}

Data types: IntervalRequest, Transaction

See also: Performance and data querying

ListEmployeeContributionDetails

List the per employee contributions for a given company transaction.

service PartnerCompanyIngressService {
  rpc ListEmployeeContributionDetails(ListEmployeeContributionDetailsRequest) returns (ListEmployeeContributionDetailsResponse);
}

message ListEmployeeContributionDetailsRequest {
  string transaction_uuid = 1;
  optional com.basiccapital.common.external.PaginationRequest pagination = 2;
}

message ListEmployeeContributionDetailsResponse {
  message EmployeeContributionDetails {
    string employee_uuid = 1;
    ContributionDetails contribution_details = 2;
  }

  repeated EmployeeContributionDetails employee_contribution_details = 1;
  Transaction transaction = 2;
  optional string next_page_token = 4;
}

Data types: ContributionDetails, Transaction

GetPlanBalance

Returns plan balance details for a given date in the past.

service PartnerCompanyIngressService {
  rpc GetPlanBalance(GetPlanBalanceRequest) returns (GetPlanBalanceResponse);
}

message GetPlanBalanceRequest {
  optional Date on_date = 1;
}

message GetPlanBalanceResponse {
  PlanBalanceDetail plan_balance_details = 1;
}

Data types: Date, PlanBalanceDetail

ListEligibilityCounts

List eligibility counts over a given interval.

service PartnerCompanyIngressService {
  rpc ListEligibilityCounts(ListEligibilityCountsRequest) returns (ListEligibilityCountsResponse);
}

message ListEligibilityCountsRequest {
  NonDiscreteIntervalRequest interval = 1;
  optional com.basiccapital.common.external.PaginationRequest pagination = 2;
}

message ListEligibilityCountsResponse {
  repeated DatedEligibilityCounts eligibility_counts = 1;
  optional string next_page_token = 2;
}

Data types: DatedEligibilityCounts, NonDiscreteIntervalRequest

See also: Performance and data querying

GetEligibilityCounts

Returns eligibility counts for a specific date.

service PartnerCompanyIngressService {
  rpc GetEligibilityCounts(GetEligibilityCountsRequest) returns (GetEligibilityCountsResponse);
}

message GetEligibilityCountsRequest {
  optional Date on_date = 1;
}

message GetEligibilityCountsResponse {
  optional EligibilityCounts employee_eligibility_counts = 1;
}

Data types: Date, EligibilityCounts

ListPlanBalances

List the plan balance over a given interval.

service PartnerCompanyIngressService {
  rpc ListPlanBalances(ListPlanBalancesRequest) returns (ListPlanBalancesResponse);
}

message ListPlanBalancesRequest {
  NonDiscreteIntervalRequest interval_request = 1;
  optional com.basiccapital.common.external.PaginationRequest pagination = 2;
}

message ListPlanBalancesResponse {
  repeated DatedPlanBalanceDetail plan_balance_details = 1;
  optional string next_page_token = 2;
}

Data types: DatedPlanBalanceDetail, NonDiscreteIntervalRequest

See also: Performance and data querying

ListEmployeeAverageContributionRates

List the average contributions rates for employees over a specific interval.

service PartnerCompanyIngressService {
  rpc ListEmployeeAverageContributionRates(ListEmployeeAverageContributionRatesRequest) returns (ListEmployeeAverageContributionRatesResponse);
}

message ListEmployeeAverageContributionRatesRequest {
  NonDiscreteIntervalRequest interval = 1;
  optional com.basiccapital.common.external.PaginationRequest pagination = 2;
}

message ListEmployeeAverageContributionRatesResponse {
  repeated DatedEmployeeAverageContributionRates employee_average_contribution_rates = 1;
  optional string next_page_token = 2;
}

Data types: DatedEmployeeAverageContributionRates, NonDiscreteIntervalRequest

See also: Performance and data querying

GetEmployeeAverageContributionRates

Returns the average contribution rate across employees for a given date.

service PartnerCompanyIngressService {
  rpc GetEmployeeAverageContributionRates(GetEmployeeAverageContributionRatesRequest) returns (GetEmployeeAverageContributionRatesResponse);
}

message GetEmployeeAverageContributionRatesRequest {
  optional Date on_date = 1;
}

message GetEmployeeAverageContributionRatesResponse {
  optional EmployeeAverageContributionRates employee_average_contribution_rates = 1;
}

Data types: Date, EmployeeAverageContributionRates

ListCompanySummary

List the company summary data over a specific interval.

service PartnerCompanyIngressService {
  rpc ListCompanySummary(ListCompanySummaryRequest) returns (ListCompanySummaryResponse);
}

message ListCompanySummaryRequest {
  NonDiscreteIntervalRequest interval = 1;
  optional com.basiccapital.common.external.PaginationRequest pagination = 2;
}

message ListCompanySummaryResponse {
  repeated DatedCompanySummary company_summaries = 1;
  optional string next_page_token = 2;
}

Data types: DatedCompanySummary, NonDiscreteIntervalRequest

See also: Performance and data querying

GetCompanySummary

Provides useful summary data for a company.

service PartnerCompanyIngressService {
  rpc GetCompanySummary(GetCompanySummaryRequest) returns (GetCompanySummaryResponse);
}

message GetCompanySummaryRequest {
  optional Date on_date = 1;
}

message GetCompanySummaryResponse {
  optional CompanySummary company_summary = 1;
  optional CompanyYtdSummary company_ytd_summary = 2;
}

Data types: CompanySummary, CompanyYtdSummary, Date

SubmitPayrollEvent

Used to tell Basic Capital they should fetch pay event data from the payment provider and initiate an ACH pull from company's linked bank account.

service PartnerCompanyIngressService {
  rpc SubmitPayrollEvent(SubmitPayrollEventRequest) returns (SubmitPayrollEventResponse);
}

message SubmitPayrollEventRequest {
  string external_payroll_event_id = 1;
}

message SubmitPayrollEventResponse {
  PayrollEvent payroll_event = 1;
}

Data types: PayrollEvent

ListCompanyPayrollEvents

This will return all payroll events as they are in Basic Capital.

service PartnerCompanyIngressService {
  rpc ListCompanyPayrollEvents(ListCompanyPayrollEventsRequest) returns (ListCompanyPayrollEventsResponse);
}

message ListCompanyPayrollEventsRequest {
  optional com.basiccapital.common.external.PaginationRequest pagination = 1;
  optional IntervalRequest interval = 2;
  repeated string external_ids = 3;
}

message ListCompanyPayrollEventsResponse {
  repeated PayrollEvent payroll_events = 1;
  optional string next_page_token = 2;
}

Data types: IntervalRequest, PayrollEvent

See also: Performance and data querying

ListSupportedHrisProviders

Lists supported HRIS providers for the partner that are supported when invoking SetHrisProvider. Please contact Basic Capital to configure or add to your list of supported providers. Note: this needs no company identity header.

service PartnerCompanyIngressService {
  rpc ListSupportedHrisProviders(ListSupportedHrisProvidersRequest) returns (ListSupportedHrisProvidersResponse);
}

message ListSupportedHrisProvidersRequest {}

message ListSupportedHrisProvidersResponse {
  repeated Company.HrisProviderType hris_provider_types = 1;
}

Data types: Company

SetHrisProvider

Sets the HRIS provider Basic Capital reads the company's payroll from and writes its 401(k) deductions to. It must be one of the providers ListSupportedHrisProviders returns. If only one provider is set, Basic Capital will auto link any new company to this HRIS provider during company creation. When more than one HRIS provider is supported, then the partner must call SetHrisProvider during onboarding. This is tracked via link_hris_status on GetOnboardingStatus for a company. Calling it again with the same provider is safe.

Errors:

  • INVALID_ENUM_VALUE: hris_provider_type is unset.
  • INVALID_ARGUMENT status: the provider set is not in the list of supported providers for this partner, or Basic Capital is unable to link this company to this provider.
  • ALREADY_EXISTS status: the company is already linked to a different HRIS provider.
service PartnerCompanyIngressService {
  rpc SetHrisProvider(SetHrisProviderRequest) returns (SetHrisProviderResponse);
}

message SetHrisProviderRequest {
  Company.HrisProviderType hris_provider_type = 1;
}

message SetHrisProviderResponse {}

Data types: Company

PartnerSharedIngress

PartnerEmployeeIngress

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