Switching payroll providers

If you already paid your employees this year through another provider (or by hand), Bokapsys needs to know what was paid so far. These year-to-date (YTD) figures are what tell Bokapsys when an employee has reached a tax limit. Without them, Bokapsys starts every employee at zero and keeps charging taxes that should already have stopped.

You can also bring your employees and contractors over from a file, instead of typing them in one by one.

If this is your first payroll of the calendar year and you only have a few people, you don’t need any of this: set people up by hand and skip to Run payroll.

1Last payroll with old provider
2Export files from old provider
3Import employees and contractors
4Import year-to-date figures
5First pay run in Bokapsys

Why year-to-date figures matter

Several US payroll taxes stop once an employee’s wages for the calendar year pass a limit. Bokapsys keeps a running total per employee and uses it on every pay run:

Tax	2026 limit	What goes wrong without the YTD figure
Social Security (6.2% employee + 6.2% employer)	Wages up to $184,500	A high earner who already passed the limit is charged again.
Additional Medicare Tax (0.9%, employee only)	Wages over $200,000	It starts too late, because Bokapsys thinks the employee has earned less.
FUTA (federal unemployment, 0.6%)	First $7,000 per employee	FUTA is charged again on someone already past $7,000.
State unemployment (SUI)	The wage base on your state notice	SUI is charged again on someone already past the wage base.
Retirement and HSA limits	The IRS yearly limits	Contributions carry on past the limit.

The same figures feed your Forms 941, 940 and W-2. A W-2 must cover the whole year, including what the old provider paid.

Worked example

Ana earns $10,000 a month. You move to Bokapsys in July. By the end of June she has earned $60,000, and the old provider has already charged FUTA on her first $7,000.

With her YTD figures imported: Bokapsys sees $60,000 of gross wages already, so it charges no FUTA on her July pay.
Without them: Bokapsys sees $0, charges FUTA on her first $7,000 of July pay ($42.00 that you don’t owe), and later her W-2 shows only half her year.

Before you start

Your role can run imports. By default Super admin, Admin and CFO can. See Team and roles.
Your last payroll with the old provider is finished, so the figures won’t change.
You have not posted a pay run in Bokapsys this year yet, ideally. If you have, see If you have already run payroll in Bokapsys.
From the old provider, download:
- an employee list (names, hire dates, pay, work state, W-4 filing status), if you are importing employees,
- a contractor list (names, tax IDs, addresses), if you are importing contractors,
- a year-to-date payroll summary per employee for the current calendar year. Most providers call it a “YTD payroll register”, “employee earnings summary” or “payroll summary by employee”. Your last pay stub for each employee also shows most of these totals.
Save each as a CSV file (most spreadsheets can Save as CSV), with one header row.

Import a file

Import employees and contractors first, then the year-to-date figures, because figures are matched to employees by employee number.

Open Payroll → Payroll Settings and click the Import from previous provider tab. (The Import figures button on the Payroll Dashboard checklist brings you here too.)
Click New import. The Import from your previous provider window opens.
In Previous provider, choose who you are moving from: ADP, Gusto, Paychex, QuickBooks Payroll, Rippling, Justworks, Workday, SAP, Oracle, Xero, Xero Payroll, Sage, or Another provider (CSV).
In What are you importing?, choose Year-to-date figures, Employees or Contractors.
For year-to-date figures, enter the Tax year and choose what happens If figures were imported before (see below).
Read Needed columns and Optional: these are the column headings your file must have. For year-to-date figures, Buckets you can use lists every figure you can import.
Click Choose CSV file, or paste the rows into CSV rows. The first row must be the header.
Click Check [N] rows. Nothing is saved yet.
Read the result. If any row needs fixing, a table lists each Row and What to fix, and the button reads Fix [N] rows first. Fix your file, click Back, load it again and check again.
When every row is ready, click Import [N] rows.
You see how many rows were imported, skipped and failed, with the reasons. Click Done.

Every import is listed on the tab with the Provider, What, File, Rows, Imported, Skipped, Failed, Status and the date it Started.

Employees file

Needed columns: first_name, last_name, hire_date. Optional: employee_number, middle_name, email, phone, birth_date, ssn, work_state, address columns, employment_type, classification, status, pay_type, annual_salary, hourly_rate, pay_schedule, filing_status.

employee_number,first_name,last_name,hire_date,work_state,pay_type,annual_salary,filing_status
EMP-00042,Jane,Doe,2026-01-15,TX,salaried,72000,single

Keep the employee numbers your old provider used if you can; you will need them for the year-to-date file. Someone already in Bokapsys is skipped and shown as Already in Bokapsys, never changed. Check each imported employee’s record afterwards, especially their W-4 and pay schedule.

Contractors file

Needed: business_name, or first_name and last_name. Optional: contractor_number, email, phone, tin, tax_id_type, address columns and country. Tax IDs are stored encrypted, as when you enter them by hand.

Year-to-date figures file

Needed columns: employee_number, bucket and amount. Optional: tax_year (if blank, the Tax year you entered is used) and state. One row per employee per figure:

employee_number,bucket,state,amount
EMP-00001,gross,,24000.00
EMP-00001,federal_tax,,3072.51
EMP-00001,sui_wages,OK,9000.00

The bucket says which figure the row is. The window lists them all; the common ones are:

Bucket	Figure	Where it usually appears on the old provider’s report
`gross`	Gross pay	“Gross pay”
`federal_taxable`	Federal taxable wages	“Federal taxable wages”
`fica_ss_wages`	Social security wages	“SS wages”, “OASDI wages”
`fica_medicare_wages`	Medicare wages	“Medicare wages”
`futa_wages`	Federal unemployment (FUTA) wages	“FUTA wages”
`federal_tax`	Federal income tax withheld	“Federal withholding”, “FIT”
`fica_ss_tax`	Social security tax withheld (the employee’s share)	“Social Security”, “OASDI”
`fica_medicare_tax`	Medicare tax withheld (the employee’s share)	“Medicare”
`state_wages`	State taxable wages (one row per state)	“State taxable wages”
`state_tax`	State income tax withheld (one row per state)	“State withholding”, “SIT”
`sui_wages`	State unemployment wages (one row per state)	“SUI wages”, “SUTA wages”
`sui_tax`	State unemployment tax (one row per state)	“SUI”, “SUTA”
`retirement_401k`, `retirement_roth_401k`	401(k) and Roth 401(k) contributions	“401(k)”, “Roth”
`hsa_employee`, `hsa_employer`	HSA contributions	“HSA”
`section125`	Section 125 pre-tax deductions	“Section 125”, “pre-tax medical”
`employer_match`	Employer retirement match	“Employer match”

Other buckets cover 403(b), 457(b), SIMPLE and SEP IRA, FSA, dependent care FSA and commuter deductions, and the employer’s share of Social Security.

States. For the four state buckets, put the two-letter state the money was earned in, in the state column (for example OK). Leave it blank and the employee’s work state is used. If someone worked in two states this year, give one row per state. Federal figures never take a state.

Amounts are in dollars and cents, with at most two decimals, and never negative. A $ sign and commas are fine.

Replace or add

If figures were imported before decides what happens when a figure for the same employee, year, bucket and state was already imported:

Choice	What it does	Use it when
Replace earlier imported figures	Sets that figure to the amount in this file. Importing the same file twice gives the same result.	You are correcting an earlier import, or importing for the first time.
Add to earlier imported figures	Adds this file’s amount to what was imported before.	The file covers months you have not imported yet, for example a second provider’s figures.

Either way, only the old provider’s figures change. Pay runs you posted in Bokapsys are kept separately and are never overwritten by an import.

How the check works

Before anything is saved, every row is checked. A row needs fixing if the employee number or bucket is missing, the bucket is not one Bokapsys knows, the year is not a real year, the state is not a US state, the amount is not a number with at most two decimals or is negative, or the same employee, year, bucket and state appears twice. Nothing is imported while any row needs fixing.

Worth a second look lists figures that are allowed but look unusual, for example tax that doesn’t match the wages it was charged on. Check them against your old provider’s report.

A row whose employee number doesn’t match anyone in Bokapsys is skipped and shown as No employee with that number; the rest are imported.

If you have already run payroll in Bokapsys

Posted pay runs already add to each employee’s totals. Import only what your old provider paid, for the months before Bokapsys. When you check the file, a note says payroll has already been posted in Bokapsys for that year, and when you import, Bokapsys asks Import anyway? Click Import anyway only if the file covers pay from before you moved.

How to check it worked

Create and calculate your first pay run in Bokapsys. See Run payroll.
For an employee you know has passed a limit, click their name on the run: Social Security or FUTA should be lower than a full rate, or missing, as you expect.
On the Payroll Dashboard, Import year-to-date figures if you are switching provider is ticked once you have posted a payroll.

Common mistakes

Mistake	Result	Avoid it by
Running the first payroll before the import.	Taxes charged from zero.	Import first. If you already did, import the old provider’s figures and confirm Import anyway.
Employee numbers in the file differ from Bokapsys.	Those rows are skipped.	Use the exact employee number shown in Bokapsys.
Using the old provider’s figures for the wrong year.	Totals land in the wrong year.	Set Tax year to the calendar year of the pay dates.
Leaving out SUI wages, or the state for them.	State unemployment is charged again from zero, or counted for the wrong state.	Include `sui_wages` for every employee, with the state.
Choosing Add when re-importing a corrected file.	The figures are counted twice.	Use Replace earlier imported figures for corrections.

Set up payrollThe full setup checklist.

EmployeesAdd employees and employee numbers.

Run payrollYour first pay run in Bokapsys.

Payroll filings941, 940 and W-2 for the whole year.