{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Employees and payroll"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"employees-and-payroll","__idx":0},"children":["Employees and payroll"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Employee records, the data needed to add them, and payroll-driven contributions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"employeedetails","__idx":1},"children":["EmployeeDetails"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ParticipationStatus"]}," definitions:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]},": Employee is past the eligibility window and is actively contributing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING_ELIGIBILITY"]},": Employee has not exited the required eligibility window"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_PARTICIPATING"]},": Employee is past the eligibility window but has elected to not contribute"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANNOT_PARTICIPATE"]},": Employee cannot participate in the 401k"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TERMINATED"]},": Employee has been terminated"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OnboardingStatus"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ONBOARDING_UNINITIATED"]}," indefinitely."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"message EmployeeDetails {\n  message OnboardingStatus {\n    enum KycStatus {\n      UNKNOWN_KYC_STATUS = 0;\n      KYC_PENDING = 1;\n      KYC_FAILED = 2;\n      KYC_PASSED = 3;\n      MUST_LINK_ACCOUNT = 4;\n    }\n\n    enum SectionStatus {\n      UNKNOWN_SECTION_STATUS = 0;\n      BLOCKED = 1;\n      PENDING = 2;\n      IN_PROGRESS = 3;\n      COMPLETE = 4;\n    }\n\n    enum Status {\n      UNKNOWN_ONBOARDING_STATUS = 0;\n      ONBOARDING_UNINITIATED = 1;\n      ONBOARDING_IN_PROGRESS = 2;\n      ONBOARDING_COMPLETE = 3;\n    }\n\n    SectionStatus sign_agreements_status = 1;\n    Status status = 2;\n    SectionStatus set_investment_selections = 3;\n    SectionStatus set_trm_investment_selections = 4;\n    SectionStatus set_employee_contribution_rates = 5;\n    KycStatus kyc_status = 6;\n  }\n\n  enum ParticipationStatus {\n    UNKNOWN_PARTICIPATION_STATUS = 0;\n    ACTIVE = 1;\n    PENDING_ELIGIBILITY = 3;\n    NOT_PARTICIPATING = 4;\n    CANNOT_PARTICIPATE = 5;\n    TERMINATED = 6;\n    ELIGIBLE = 7;\n  }\n\n  string uuid = 1;\n  string given_name = 2;\n  string surname = 3;\n  string employment_email = 4;\n  repeated ContributionInfo contribution_rates = 5;\n  ParticipationStatus status = 6;\n  Date dob = 7;\n  Date employment_begin_date = 8;\n  Compensation compensation = 9;\n  bool is_auto_enrolled = 10;\n  OnboardingStatus onboarding_status = 11;\n  optional Date end_date = 12;\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["References:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/employees#compensation"},"children":["Compensation"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/employees#contributioninfo"},"children":["ContributionInfo"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/common#date"},"children":["Date"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"createemployeeinfo","__idx":2},"children":["CreateEmployeeInfo"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"message CreateEmployeeInfo {\n  enum EmploymentStatus {\n    UNKNOWN_EMPLOYMENT_STATUS = 0;\n    FULL_TIME = 1;\n    PART_TIME = 2;\n    INTERN = 3;\n    TEMPORARY = 4;\n    SEASONAL = 5;\n    INDIVIDUAL_CONTRACTOR = 6;\n    VOLUNTEER = 7;\n  }\n\n  string external_id = 1;\n  string given_name = 2;\n  string surname = 3;\n  string email = 4;\n  bool can_participate = 5 [deprecated = true];\n  bool is_match_eligible = 6 [deprecated = true];\n  Date dob = 7;\n  Date employment_begin_date = 8;\n  Compensation compensation = 9;\n  optional Date termination_date = 10;\n  EmploymentStatus employment_status = 11;\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["References:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/employees#compensation"},"children":["Compensation"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/common#date"},"children":["Date"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"addemployeeresult","__idx":3},"children":["AddEmployeeResult"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"message AddEmployeeResult {\n  string external_id = 1;\n  oneof outcome {\n    EmployeeDetails employee = 2;\n    AddEmployeeError error = 3;\n  }\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["References:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/employees#addemployeeerror"},"children":["AddEmployeeError"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/employees#employeedetails"},"children":["EmployeeDetails"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"addemployeeerror","__idx":4},"children":["AddEmployeeError"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"message AddEmployeeError {\n  AddEmployeeErrorType type = 1;\n  string message = 2;\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["References:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/employees#addemployeeerrortype"},"children":["AddEmployeeErrorType"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"addemployeeerrortype","__idx":5},"children":["AddEmployeeErrorType"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"enum AddEmployeeErrorType {\n  UNKNOWN_ADD_EMPLOYEE_ERROR = 0;\n  START_DATE_IN_FUTURE = 2;\n  MISSING_INFORMATION = 3;\n  ALREADY_TERMINATED = 5;\n  INTERNAL_ERROR = 6;\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"compensation","__idx":6},"children":["Compensation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"message Compensation {\n  enum Cadence {\n    UNKNOWN_CADENCE = 0;\n    MONTHLY = 1;\n    ANNUALLY = 2;\n    HOURLY = 3;\n    WEEKLY = 4;\n    COMMISSION = 5;\n  }\n\n  Money amount = 1;\n  Cadence cadence = 2;\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["References:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/common#money"},"children":["Money"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"contributioninfo","__idx":7},"children":["ContributionInfo"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"message ContributionInfo {\n  ContributionType type = 1;\n  int32 paycheck_contribution_amount_bps = 2;\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["References:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/employees#contributiontype"},"children":["ContributionType"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"contributiontype","__idx":8},"children":["ContributionType"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"enum ContributionType {\n  UNKNOWN_CONTRIBUTION_TYPE = 0;\n  TRADITIONAL = 1;\n  ROTH = 2;\n  MEGA_BACKDOOR_ROTH = 3;\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payrollevent","__idx":9},"children":["PayrollEvent"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Company-level payroll event (e.g., a payroll run produces one payroll event for a company)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"message PayrollEvent {\n  string uuid = 1;\n  string external_id = 2;\n  Date pay_date = 3;\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["References:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/common#date"},"children":["Date"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transaction","__idx":10},"children":["Transaction"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"message Transaction {\n  enum Status {\n    UNKNOWN_STATUS = 0;\n    CREATED = 1;\n    PROCESSING = 2;\n    COMPLETED = 3;\n    CANCELED = 4;\n    FAILED = 5;\n  }\n\n  enum TransactionType {\n    UNKNOWN_TRANSACTION_TYPE = 0;\n    CONTRIBUTION = 1;\n    FEE_BILLINGS = 2;\n  }\n\n  string transaction_id = 1;\n  string uuid = 2;\n  Status status = 3;\n  Date transaction_date = 4;\n  Money total_amount = 5;\n  optional ContributionDetails contribution_details = 6;\n  TransactionType transaction_type = 7;\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["References:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/employees#contributiondetails"},"children":["ContributionDetails"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/common#date"},"children":["Date"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/common#money"},"children":["Money"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"contributiondetails","__idx":11},"children":["ContributionDetails"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"protobuf","header":{"controls":{"copy":{}}},"source":"message ContributionDetails {\n  Date payroll_date = 1;\n  Money paycheck_deferral = 2;\n  Money trad_deferrals = 3;\n  Money roth_deferrals = 4;\n  Money employer_match = 5;\n  Money mbdr_contribution = 6;\n  string payroll_event_uuid = 7;\n}\n","lang":"protobuf"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["References:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/common#date"},"children":["Date"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/core-data-types/common#money"},"children":["Money"]}]}]},"headings":[{"value":"Employees and payroll","id":"employees-and-payroll","depth":1},{"value":"EmployeeDetails","id":"employeedetails","depth":2},{"value":"CreateEmployeeInfo","id":"createemployeeinfo","depth":2},{"value":"AddEmployeeResult","id":"addemployeeresult","depth":2},{"value":"AddEmployeeError","id":"addemployeeerror","depth":2},{"value":"AddEmployeeErrorType","id":"addemployeeerrortype","depth":2},{"value":"Compensation","id":"compensation","depth":2},{"value":"ContributionInfo","id":"contributioninfo","depth":2},{"value":"ContributionType","id":"contributiontype","depth":2},{"value":"PayrollEvent","id":"payrollevent","depth":2},{"value":"Transaction","id":"transaction","depth":2},{"value":"ContributionDetails","id":"contributiondetails","depth":2}],"frontmatter":{"title":"Employees and payroll","seo":{"title":"Employees and payroll"}},"lastModified":"2026-10-15T20:30:58.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/core-data-types/employees","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}