Skip to main content

​
👤 User Onboarding Flow

​
📘 Overview:

The user onboarding process ensures all legal, identity, and payment-related information is accurately collected and verified.

​
Admin steps:

​
🔹 Step 1: addUser

Purpose: Collect the user’s key information to add them to the platform. Mandatory Fields:
  • firstName - legal first name. Please avoid using nicknames
  • lastName - legal last name. Please avoid using nicknames
  • dateOfJoin - the employee’s first day at the company. Used to determine pay period elligibility
  • workerType - W2 or 1099-NEC
  • jobTitle
  • companyLocationCategory - Remote or Office
  • stateCode if Remote OR companyLocationId if Office
Notes:
  • userReferenceId can be used to store the ID you use to refer to the employee in your system
  • email and phone number are not required, but will need to be added later if you wish to invite the employee to the platform

​
🔹 Step 2: addUserWage

Purpose: Collect the user’s job and wage information for accurate payroll calculations. Mandatory Fields:
  • companyId - the company the employee belongs to
  • userId - the employee’s Rollfi ID
  • differentialPay - determines the wage structure of the employee and their corresponding payroll import endpoint
  • wageRate - combines with wagebasis to determine how much the employee will be paid
  • workerType - W2 or 1099-NEC
  • wageBasis - Per Hour, week etc.
  • standardWorkingHours - used to pre-fill hours for payPeriods
  • userType - determines wage and comission pay structures
  • employmentStatus
  • userRefTaxExempt - directly effects tax calculations for pay periods
  • startDate - when is this wage active from?
  • paymentMethod - how will the employee get paid? For Direct Deposit employees a bank account must be added before they are considered active

​
Employee steps:

​
🔹 Step 1: acceptTermsAndCondition

Purpose: Log the user’s acceptance of Terms & Conditions. 📜 Mandatory for compliance before proceeding.

​
🔹 Step 2: addKycInformation

Purpose: Collect essential identity information. Details:
  • Full Name
  • Date of Birth
  • SSN (or equivalent)
  • Address
  • Contact Info
Ensures regulatory compliance and identity validation.

​
🔹 Step 3: addW4Information

Purpose: Collect federal tax withholding data. Fields:
  • Filing status
  • Dependents
  • Additional withholdings
Used to accurately compute payroll taxes.

​
🔹 Step 4: addStateW4Information (Optional)

Purpose: Collect state-specific withholding data. 🏛️ Required only for states with their own W-4 forms. Others default to the federal form.

​
🔹 Step 5: initiateUserKyc

Purpose: Start the KYC verification process. Only verified users can access payroll and financial features.

​
🔹 Step 6: Add User Bank Account

Options: 1. Manual Entry with Microdeposit Verification
  • Fields: Bank Name, Account Number, Routing Number, Account Type
2. Plaid Integration
  • Secure linking via Plaid for automatic account verification
✅ At least one verified bank account is required to complete onboarding.