How do I build my employee pay history file for Tilt?

Quick answer

Build your employee pay history file from Tilt's CSV template so Tilt can calculate benefit amounts using data straight from your payroll system rather than second-hand from pay stubs. Populate the template — ideally with a custom payroll export that matches Tilt's headers — filling in every required field. Column headers must match the template exactly, dates must be YYYY-MM-DD, and the five gross pay fields must contain 0 or 0.00 when an employee has no pay in that category. Employee profiles must already exist in Tilt before pay history can be imported.

Who this applies to / Prerequisites

You must be an HR user in Tilt.
Employee profiles must be imported successfully before pay history. See How do I build my employee profile data file for Tilt?
Download the Tilt – Payroll History Import Guide CSV File Template.
Your file must be saved as .csv. Tilt does not accept .xlsx or other file types.

Steps

Step 1: Choose how to populate the file

Manual entry from your payroll system.
Recommended: a custom HRIS/payroll export that matches Tilt's expected column headers and data values. This makes it easy to send updated files at the close of each pay cycle.

Fill out as many optional fields as possible — the more complete the data, the more it benefits your HR team.

Step 2: Format the file

Column headers must match the template exactly and stay in order for Tilt to recognize the data. Leave unused optional columns empty and leave null values blank — except the five gross pay fields, which must contain 0 or 0.00 when the employee has no pay in that category.

Column	Field Name	Required?	Field Description	Format / Accepted Values
A	Payroll Run ID*	Required	An identifying string or number unique to the specific payroll run. Tilt uses this to decide whether to correct an existing payroll record or add a new one, so accuracy is critical.	Any alphanumeric string
B	Employee ID	Optional	An identifying string or number unique to the employee per company.	Unique string or number
C	Employee Work Email Address*	Required	Employee's work email. Functions as Tilt's unique identifier for the employee.	Valid email address
D	Employee First Name	Optional	Employee's legal first name.	Text
E	Employee Last Name	Optional	Employee's legal last name.	Text
F	Pay Period Start Date*	Required	The date the pay period started.	YYYY-MM-DD
G	Pay Period End Date*	Required	The date the pay period ended.	YYYY-MM-DD
I	Pay Date*	Required	The actual pay date.	YYYY-MM-DD
J	Gross regular wage amount*	Required	Total whole pay before taxes and withholdings, not including overtime, bonus, commission, or fringe benefits.	Numeric with a decimal; $ signs and commas optional. Example: 99999999.99
K	Gross overtime pay amount*	Required	Gross overtime pay before taxes and withholdings. Enter 0 or 0.00 if none.	Numeric with a decimal; $ signs and commas optional. Example: 99999999.99
L	Gross bonus amount*	Required	Gross bonus pay before taxes and withholdings. Enter 0 or 0.00 if none.	Numeric with a decimal; $ signs and commas optional. Example: 99999999.99
M	Gross commission amount*	Required	Gross commission pay before taxes and withholdings. Enter 0 or 0.00 if none.	Numeric with a decimal; $ signs and commas optional. Example: 99999999.99
N	Gross taxable fringe benefit amount*	Required	Gross taxable fringe benefit pay before taxes and withholdings. Do not include non-taxable fringe benefits. Enter 0 or 0.00 if none.	Numeric with a decimal; $ signs and commas optional. Example: 99999999.99
O	PTO Hours Balance	Optional	The employee's current PTO balance in hours. Helps LSMs calculate pay when employees use PTO to cover part of their leave.	Numeric, up to 6 decimal places; no other characters. Example: 88.5
P	Sick Leave Hours Balance	Optional	The employee's current Sick Leave balance in hours.	Numeric, up to 6 decimal places; no other characters. Example: 44
Q	Vacation Leave Hours Balance	Optional	The employee's current Vacation Leave balance in hours.	Numeric, up to 6 decimal places; no other characters. Example: 44
R	Personal Days Leave Hours Balance	Optional	The employee's current Personal Days balance in hours.	Numeric, up to 6 decimal places; no other characters. Example: 44

Step 3: Import your file

Once your file is built and formatted, test it, upload it, or send it via SFTP. See How do I test my import file before uploading it in Tilt?, How do I upload my import file in Tilt?, and How do I send import files to Tilt via SFTP instead of uploading them?

What if it doesn't work

Rows failed with header errors: Your column headers don't match Tilt's template exactly, or columns are out of order. Compare against the template (including asterisks) and correct any differences.
Rows failed with date errors: Pay Period Start Date, Pay Period End Date, and Pay Date must all be YYYY-MM-DD.
Rows failed for an employee not found in Tilt: The employee's profile doesn't exist yet, or the work email doesn't match their Tilt profile. Import or correct the profile first, then re-upload.
Rows failed on a gross pay field: One of the five required gross pay fields is blank or has invalid characters. Enter 0.00 when the employee has no pay in that category.
The file won't upload at all: The file is not a .csv. Re-save it as .csv.

Limits and exceptions

Only .csv files are accepted. Excel (.xlsx) and other formats will not import.
You must be an HR user to build and upload payroll files.
Column headers must match Tilt's template exactly.
Employee profile data must exist in Tilt before pay history can be imported. Pay rows for employees without Tilt profiles will not process.
All dates must be YYYY-MM-DD.
The five gross pay fields cannot be left blank. Enter 0.00 when there is no pay in a category.
Payroll Run ID must be included and unique to each payroll run.
Non-taxable fringe benefits must not be included in the Gross taxable fringe benefit amount field.
This file can also be submitted through the HR leave survey for a single employee.

How do I build my employee pay history file for Tilt?

Column by column — build a properly formatted pay history file, ready to test, upload, or send via SFTP.

Step 1: Choose how to populate the file

Step 2: Format the file

Step 3: Import your file