Employees and payroll

Employee records, the data needed to add them, and payroll-driven contributions.

EmployeeDetails

ParticipationStatus definitions:

ACTIVE: Employee is past the eligibility window and is actively contributing
PENDING_ELIGIBILITY: Employee has not exited the required eligibility window
NOT_PARTICIPATING: Employee is past the eligibility window but has elected to not contribute
CANNOT_PARTICIPATE: Employee cannot participate in the 401k
TERMINATED: Employee has been terminated
ELIGIBLE: Employee has exited the required eligibility window and is eligible to participate but is not active (i.e. has not been auto enrolled or configured custom contributions)

OnboardingStatus

Employees are not required to go through onboarding. They will be auto-enrolled regardless. It is possible for an employee who never goes through onboarding to be in a state of ONBOARDING_UNINITIATED indefinitely.

message EmployeeDetails {
  message OnboardingStatus {
    enum KycStatus {
      UNKNOWN_KYC_STATUS = 0;
      KYC_PENDING = 1;
      KYC_FAILED = 2;
      KYC_PASSED = 3;
      MUST_LINK_ACCOUNT = 4;
    }

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

    enum Status {
      UNKNOWN_ONBOARDING_STATUS = 0;
      ONBOARDING_UNINITIATED = 1;
      ONBOARDING_IN_PROGRESS = 2;
      ONBOARDING_COMPLETE = 3;
    }

    SectionStatus sign_agreements_status = 1;
    Status status = 2;
    SectionStatus set_investment_selections = 3;
    SectionStatus set_trm_investment_selections = 4;
    SectionStatus set_employee_contribution_rates = 5;
    KycStatus kyc_status = 6;
  }

  enum ParticipationStatus {
    UNKNOWN_PARTICIPATION_STATUS = 0;
    ACTIVE = 1;
    PENDING_ELIGIBILITY = 3;
    NOT_PARTICIPATING = 4;
    CANNOT_PARTICIPATE = 5;
    TERMINATED = 6;
    ELIGIBLE = 7;
  }

  string uuid = 1;
  string given_name = 2;
  string surname = 3;
  string employment_email = 4;
  repeated ContributionInfo contribution_rates = 5;
  ParticipationStatus status = 6;
  Date dob = 7;
  Date employment_begin_date = 8;
  Compensation compensation = 9;
  bool is_auto_enrolled = 10;
  OnboardingStatus onboarding_status = 11;
  optional Date end_date = 12;
}

References: Compensation, ContributionInfo, Date

CreateEmployeeInfo

message CreateEmployeeInfo {
  enum EmploymentStatus {
    UNKNOWN_EMPLOYMENT_STATUS = 0;
    FULL_TIME = 1;
    PART_TIME = 2;
    INTERN = 3;
    TEMPORARY = 4;
    SEASONAL = 5;
    INDIVIDUAL_CONTRACTOR = 6;
    VOLUNTEER = 7;
  }

  string external_id = 1;
  string given_name = 2;
  string surname = 3;
  string email = 4;
  bool can_participate = 5 [deprecated = true];
  bool is_match_eligible = 6 [deprecated = true];
  Date dob = 7;
  Date employment_begin_date = 8;
  Compensation compensation = 9;
  optional Date termination_date = 10;
  EmploymentStatus employment_status = 11;
}

References: Compensation, Date

AddEmployeeResult

message AddEmployeeResult {
  string external_id = 1;
  oneof outcome {
    EmployeeDetails employee = 2;
    AddEmployeeError error = 3;
  }
}

References: AddEmployeeError, EmployeeDetails

AddEmployeeError

message AddEmployeeError {
  AddEmployeeErrorType type = 1;
  string message = 2;
}

References: AddEmployeeErrorType

AddEmployeeErrorType

enum AddEmployeeErrorType {
  UNKNOWN_ADD_EMPLOYEE_ERROR = 0;
  START_DATE_IN_FUTURE = 2;
  MISSING_INFORMATION = 3;
  ALREADY_TERMINATED = 5;
  INTERNAL_ERROR = 6;
}

Compensation

message Compensation {
  enum Cadence {
    UNKNOWN_CADENCE = 0;
    MONTHLY = 1;
    ANNUALLY = 2;
    HOURLY = 3;
    WEEKLY = 4;
    COMMISSION = 5;
  }

  Money amount = 1;
  Cadence cadence = 2;
}

References: Money

ContributionInfo

message ContributionInfo {
  ContributionType type = 1;
  int32 paycheck_contribution_amount_bps = 2;
}

References: ContributionType

ContributionType

enum ContributionType {
  UNKNOWN_CONTRIBUTION_TYPE = 0;
  TRADITIONAL = 1;
  ROTH = 2;
  MEGA_BACKDOOR_ROTH = 3;
}

PayrollEvent

Company-level payroll event (e.g., a payroll run produces one payroll event for a company).

message PayrollEvent {
  string uuid = 1;
  string external_id = 2;
  Date pay_date = 3;
}

References: Date

Transaction

message Transaction {
  enum Status {
    UNKNOWN_STATUS = 0;
    CREATED = 1;
    PROCESSING = 2;
    COMPLETED = 3;
    CANCELED = 4;
    FAILED = 5;
  }

  enum TransactionType {
    UNKNOWN_TRANSACTION_TYPE = 0;
    CONTRIBUTION = 1;
    FEE_BILLINGS = 2;
  }

  string transaction_id = 1;
  string uuid = 2;
  Status status = 3;
  Date transaction_date = 4;
  Money total_amount = 5;
  optional ContributionDetails contribution_details = 6;
  TransactionType transaction_type = 7;
}

References: ContributionDetails, Date, Money

ContributionDetails

message ContributionDetails {
  Date payroll_date = 1;
  Money paycheck_deferral = 2;
  Money trad_deferrals = 3;
  Money roth_deferrals = 4;
  Money employer_match = 5;
  Money mbdr_contribution = 6;
  string payroll_event_uuid = 7;
}

References: Date, Money