Start free trial

Resources

Why your first hours import fails, and the header fix

Most first hours imports fail because the header row in your file doesn't match the header your payroll provider expects. Compare the two files and fix the header. That's usually the whole fix.

What the import is actually reading

Payroll imports are picky. They look for exact column names, in a set order, with a date style they recognize. If the first row says "Regular Hours" and the provider expects "Reg Hours", the upload fails. If the dates are MM/DD/YYYY and the import wants YYYY-MM-DD, it fails. The hours can be right and the file still bounces.

Firmhours doesn't guess those columns for you. You map them once, by drag and drop: the order, the headers, and the date style. You also set the header row and the separator. You can build one row per person, or one row per pay type with your provider's pay codes. Simple formats take seconds. Complex ones take a few minutes. Save it, and every payday export after that is one click.

The path is Settings, then Export. Start from a sample file your provider gives you, so you're matching what they ask for now, not what they asked for last year.

How the file is made

People punch on a phone or a shared tablet. A manager approves each day. You finalize the period. You download the file and upload it in your provider's hours import. Typical files carry regular, overtime, double time, PTO, and holiday hours per person, written as decimals.

On screen, a day can read 7h 56m. The payroll file writes the same hours as 7.93. If your provider's sample uses decimals, keep them. Don't convert back to hours and minutes in the file unless that's what the import asks for.

The full flow, and which providers need the import turned on first, is on the payroll file page.

Turn the import on before the first payday

A perfect file still fails if the import isn't turned on. Check with your provider before you run the first payday:

  • Gusto Smart Import: check that it's available under Pay, then Run payroll, then Import payroll data.
  • RUN Powered by ADP: Time Sheet Import must be turned on for your company. Ask your ADP payroll team.
  • Paychex Flex: ask your Paychex rep to turn on Standard Payroll Import (SPI).
  • OnPay: ask OnPay support to turn on Upload Hours.

None of these are integrations. You download the file and upload it yourself. OnPay is the format Firmhours has tested with a real import. Gusto, RUN Powered by ADP, and Paychex Flex formats are built to match their published imports, but haven't been tested with a real import yet. If an import fails, compare your file with what the provider expects. It's nearly always a header mismatch.

If you run Gusto, start with the Gusto Smart Import page, then match the columns to Gusto's current sample.

If your provider changes the import

Open your saved format, change the columns or header to match the new sample, and save. Payroll companies change their import specs. Don't treat last period's file as a permanent layout.

You can also build a format for a provider that isn't listed, as long as they import an hours file. Map their columns once and save it.

QuickBooks Online Payroll is a different path

QuickBooks Online Payroll doesn't take an hours file upload. Firmhours lines up the hours to match your pay run, then you enter them. Go to Reports, then Hours summary. Run it as is and type the hours into your QuickBooks Online Payroll run. There's nothing to header-match, because there's no import file.

Keep QuickBooks for the books and the payroll you already run. Firmhours is the hours file, or the hours summary you type from.

A short checklist for the first payday

  1. Get a sample import file from your provider, or look at the columns the import asks for.
  2. Confirm the hours import is turned on.
  3. In Firmhours, go to Settings, then Export. Drag in those columns in the same order. Set the header, date style, and separator.
  4. Approve the days for the period, finalize, and download the file.
  5. If the upload fails, open both files side by side. The mismatch is nearly always in the header.

Do that once. The next payday is one click.

FAQ

Why did my first Gusto or ADP hours import fail?

Most of the time, the header row doesn't match what the import expects, or the hours import isn't turned on yet. Compare your file with the provider's sample and fix the header. For RUN Powered by ADP, ask your ADP payroll team to turn on Time Sheet Import. For Gusto, check Smart Import under Pay, then Run payroll, then Import payroll data.

Do I have to remap the columns every payday?

No. You map them once and save the format. After that, every payday export is one click. If your provider changes its import, open the saved format, match the new sample, and save again.

Can I build a file for a payroll provider you don't list?

Yes, if they import an hours file. Map their columns by hand once: the order, headers, and date style. Simple formats take seconds. Complex ones take a few minutes.

Start a free trial

Start a free trial. It's $4 per active user per month. That is the whole price. No base fee. No minimum. No contract. 14 days free. Card or US bank account at the end of sign-up. You aren't charged today. The first charge lands the day the trial ends. Each month you pay $4 for every active user, meaning anyone who clocked in at least once that month. Cancel before the first charge and you owe nothing. See pricing for the full breakdown. Example: 12 active users in a month is $48.

Sources

Start free trial