Understanding the Paychex integration

What it is

The Paychex integration — Paychex Flat File in Onboarded — exports new hire data out of Onboarded as a CSV file for your team to import into Paychex. It's the same pattern payroll systems have used for decades, sometimes called a flat file export. It's not an API integration: Paychex has told prospective joint customers it won't open API access, so there's no live, field-by-field sync the way there is with an API-based connection like ADP Workforce Now.

Paychex Flat File uses the same profile and field-mapping setup as Onboarded's ADP Flat File integration. The difference is delivery: ADP Flat File can push its file to an SFTP server, optionally PGP-encrypted, while Paychex Flat File stops at the CSV. You download the file and bring it into Paychex yourself.

Why it matters

If your account runs an ATS like Lever alongside Paychex for payroll, and Paychex won't grant API access, a flat file export is the path to get new hire data from Onboarded into Paychex without re-keying it. Understanding how it works matters because a file-based handoff behaves differently than an API integration: records move in batches instead of instantly, someone on your team has to import each file into Paychex, and responsibility for finishing a worker's Paychex record is split between what the file carries and what Paychex still expects the account to enter directly.

How it works

Where the handoff happens

Data flows from Lever (or another ATS) into Onboarded during onboarding. Inside Onboarded, a Paychex Flat File field on a form collects the values your field mapping defines: fields assigned to employee are completed by the new hire, and fields assigned to employer are completed by your team. Once the employer part is submitted, that record waits in a queue for the next export. Each export gathers every queued record for a profile into one CSV, and the new hire lands in Paychex when your team imports that file — not the moment they finish their tasks.

The file's columns are whatever your field mapping defines. Each enabled field becomes a column, headed by its Output Key and in the order you set. In practice that means the columns your Paychex import template asks for, usually drawn from what Onboarded already collects during onboarding: legal name, address, Social Security number, and tax withholding details for the new hire's work state — a Nevada hire only needs a federal W-4, while a Colorado or California hire also completes that state's withholding form. EEO information can be mapped if an account wants it, but Onboarded typically keeps EEO answers inside the ATS rather than passing them downstream, since a payroll admin doesn't need them day to day.

What varies by account is how much of the record that leaves a new hire fully set up for payroll versus how much still requires action inside Paychex directly — things like direct deposit, benefits elections, and emergency contacts. Which of those fields Paychex's flat file import actually accepts is set per Paychex account, since Paychex customizes what its import template supports for each customer. Confirming that requires the account's actual Paychex flat file template, which Paychex can provide directly (usually by asking Paychex for its "flat file import requirements" or template). Until that template is in hand and mapped, plan on some new hire action still happening inside Paychex after the file lands.

What happens if a record doesn't match Paychex's format

Validation happens on both ends. On the Onboarded side, a field marked Required in the mapping has to be filled in before the form can be submitted, so a record can't reach the export without it. Paychex's import applies its own template rules once your team uploads the file.

If an export job itself fails — for example, because the profile's field mapping has no published version — the job shows Failed with an error message, and its records go back into the queue for the next export. Whether a bad row fails on its own or takes the whole file down with it once it reaches Paychex depends on how Paychex's import behaves for your account — that part happens on the Paychex side, not in Onboarded.

How setup works

You set up Paychex Flat File from its card in Account Settings → Integrations, where Configure opens your list of export profiles. A profile is one export definition: a Profile Name, an optional File Name Pattern ({date} and {id} are filled in at export time, and Onboarded adds the .csv extension for you), and a field mapping.

The field mapping is where the account's Paychex import template comes in. For each field you set its label and type — including a code list when Paychex expects specific codes — who fills it in (Assignee), a Default Value, and whether it's Enabled and Required. Source Fields fill a field from data Onboarded already has for the employee, and those fields show up prefilled and locked on the form. Value Mappings translate Onboarded's values into the codes Paychex expects. You can reorder fields to match the template's column order, and move a whole mapping in or out as JSON with Import Config and Export Config. The mapping only takes effect once you Publish Version. From there, add a Paychex Flat File field to the form that should collect the data and pick the Profile it feeds.

A Paychex rep does need to be involved, because the account's Paychex flat file import template — the actual document describing what fields Paychex will accept and in what format — has to come from Paychex. That template is the one piece Onboarded can't generate on its own. Once you have it, setup is configuration inside Onboarded rather than a custom build.

You can generate a file at any time with Run Export on the Export Jobs tab of the Paychex Flat File page. Onboarded also has an automatic export that runs every eight hours, but it's switched on by Onboarded rather than from your account, so confirm with your Onboarded contact whether it's running before you rely on it. Either way, each export job moves through Pending, Generating, and Ready; once it's Ready, click the file name to download the CSV. If nothing new was submitted since the last export, no file is created — that's expected.

Email deliverability for candidate-facing messages isn't part of this integration

If your ATS (like Lever) sends candidate-facing emails — offer letters, interview scheduling — from your own domain, authorizing that in your SPF record and setting up DKIM signing is a configuration on your ATS side, not something the Paychex integration touches. Your ATS provider's support team can give you the exact DNS entries to add. Onboarded's own onboarding emails to candidates are a separate step that happens after hire, and if you also want those sent from your own domain, that's Onboarded's own domain verification process — a different set of DNS records from your ATS's.

Example

Take an account that hires through an ATS and runs payroll on Paychex Flex. A new hire completes their I-9 and tax withholding forms inside Onboarded, along with the employee fields of the form's Paychex Flat File field — some of them already prefilled from data Onboarded has. Someone on the account's team then completes the employer fields, and the record joins the export queue. At the end of the day, the payroll admin clicks Run Export, downloads the CSV once the job shows Ready, and imports it into Paychex, which creates the worker record from it. Depending on what the account's Paychex template supports, the new hire (or the account's payroll admin) may still need to go into Paychex directly to finish direct deposit and benefits elections before that worker is fully ready for their first payroll run.

Read next

• 📄 How do I set up the ADP Workforce Now integration?

• 📄 How do I set up the UKG Pro integration?