Payroll codes are the master keys that let Employee Navigator send new, updated, and ending deductions to your payroll system as enrollments and costs change. This guide walks you through three things:
- How to find your codes
- How to map them to plans
- How to edit them once you're live
How to Find Your Codes
There are two ways payroll codes get into Employee Navigator, and which one applies to you depends entirely on your payroll partner. Start by picking your partner below.
Who's your payroll partner?
Pick your partner so we can tailor the demo to your import method. API partners pull codes automatically; manual partners type them in.
Employee Navigator pulls your codes straight from your payroll system with one click. Scroll down to launch the demo →
Walk through finding and mapping your codes
Click through the real flow below. You'll find your payroll codes page, refresh codes from your partner, and map each plan to a code — all in one cohesive walkthrough. Every button works.
Manual method walkthrough
The screens look identical to the API method above — the only difference is you type the code into the Pre-tax or Post-tax Deduction Code field instead of picking from a dropdown.
- Ask HR to generate their payroll system's payroll code report (each vendor has specific steps — see the partner-specific guides linked above)
- In EN, go to the Payroll tab → Payroll Codes card → View Codes
- Click the ✎ pencil next to each plan
- Type the code from HR's list into the Pre-tax or Post-tax Deduction Code field, then Save
How to Map Your Codes
Now that your codes are loaded, it's time to map each code to the right plan in Employee Navigator. Before you map, review the three things below — rules to follow, what each toggle does, and where Pre-tax vs. Post-tax placement matters.
Rules every mapping must follow
The three toggles at the top of the modal
All three are off by default, and off is correct for most plans. Turn one on only when the situation below applies to you.
- Off — one code covers the whole plan, no matter which tier the employee is enrolled in. This is what most customers use.
- On — the table expands to one row per coverage tier so you can map a separate code to each.
- Off — EN transmits every employee cost, including $0.
- On — EN stops sending employee deductions for this plan. Use only for 100% employer-paid benefits.
- Off — EN transmits employer contributions when your partner accepts them via API.
- On — EN stops sending employer contributions. Use when your partner doesn't accept them, or when the code is for reporting only.
Pre-tax vs. Post-tax placement
Taxability is determined in payroll, but which column you map the code into in EN matters in some scenarios. Use this table to decide.
| Scenario | What to do |
|---|---|
| One code for all employees, configured as either pre- or post-tax in payroll | Map to the respective column depending on how the code's taxability is configured in payroll |
| Two codes — some employees pre-tax, others post-tax | Each code must go in its respective column on all applicable plans |
| One code, plan allows user to define tax status (e.g., Voluntary LTD/STD) |
|
| 3rd Party App plan (carrier is system of record) | Both a Pre-tax and a Post-tax Deduction Code are required to save |
🏢 How do I configure post-tax deductions for specific employees? ›
If they are 2% shareholders or Direct lineal descendants of a 2% shareholder:
- Go to the employee's Profile → Employment → Statutory Class
- Choose 2% Shareholder and Save
EN will apply only the post-tax codes you've mapped into your payroll group(s) for this employee.
If they are NOT 2% shareholders: Create a second payroll group with the same frequency, map the post-tax codes in that group (plus any pre-tax codes for plans withheld pre-tax for everyone), then reassign these employees to the new payroll group.
Mapping examples
With every toggle left off, one code covers the whole plan — that's the default and it handles most plans. Expand the examples below if you have tier-specific codes, HSA, or 3rd Party App plans that need a different setup.
EX Plan level codes — the default that most customers have ›
A single code like MDCL represents the full consolidated cost — employee plus spouse plus dependents. Leave Split codes by Coverage Level off, map the code in the applicable Pre-tax or Post-tax column, and you're done.
When to use it: most medical, dental, and vision plans, FSAs, and similar plans where payroll handles the full cost as one line item.
Static preview
Apply Codes
| Pre-tax Deduction CodeRequired | Post-tax Deduction CodeOptional | Employer Contribution CodeOptional | |
|---|---|---|---|
| Plan Level Codes | MDCL - MEDICAL INS | Add if needed | Add if needed |
Reset
EX Split codes by Coverage Level — a separate code per tier ›
Multiple codes, each representing one coverage tier's cost:
-
MEDEE— Employee -
MEDSP— Employee + Spouse -
MEDCH— Employee + Child(ren) -
MEDFAM— Employee + Family
Turn on Split codes by Coverage Level and the Apply Codes table expands to one row per tier, so you can map each tier independently.
Static preview
Apply Codes
| Coverage Level | Pre-tax Deduction CodeRequired | Post-tax Deduction CodeOptional | Employer Contribution CodeOptional |
|---|---|---|---|
| Employee | MEDEE - MED EMP ONLY | Add if needed | Add if needed |
| Employee + Spouse | MEDSP - MED EMP+SPS | Add if needed | Add if needed |
| Employee + Child(ren) | MEDCH - MED EMP+CHD | Add if needed | Add if needed |
| Employee + Family | MEDFAM - MED FAMILY | Add if needed | Add if needed |
Reset
EX HSA — Split codes by Limit Level for single vs. family IRS maximum rules ›
On HSA plans the toggle reads Split codes by Limit Level. Turn it on and you can configure up to 4 codes: Single, Family, Single Catch-up, and Family Catch-up. If a tier isn't used, the same code can be reused across rows.
Static preview
Apply Codes
| Limit Level | Pre-tax Deduction CodeRequired | Post-tax Deduction CodeOptional | Employer Contribution CodeReporting only |
|---|---|---|---|
| Single | HSAS - HSA SINGLE | Add if needed | Add if needed |
| Family | HSAF - HSA FAMILY | Add if needed | Add if needed |
| Single Catch-up | HSAS - HSA SINGLE | Add if needed | Add if needed |
| Family Catch-up | HSAF - HSA FAMILY | Add if needed | Add if needed |
Reset
⚠ EN does not send two codes for an over-55 employee (regular + catch-up). It only sends the code mapped into the Catch-up rows.
EX 3rd Party App plans (Colonial, etc.) ›
The carrier is the system of record — effective dates, benefit amounts, and premiums all flow from the carrier into EN, and EN passes the mapped code + cost to payroll.
- Splitting codes by coverage level isn't available — coverage is auto-configured based on the 3rd party app tie-in
- Both a Pre-tax and a Post-tax Deduction Code are required to save
- Each 3rd party plan needs a unique code (Accident and Critical Illness can't share the same Colonial code)
Static preview
Apply Codes
| Pre-tax Deduction CodeRequired | Post-tax Deduction Code | Employer Contribution CodeOptional | |
|---|---|---|---|
| Plan Level Codes | COLPRE - COLONIAL PRE | COLPOST - COLONIAL POST | Add if needed |
Reset
Editing Codes Once You're Live
Once your integration is live, codes and toggles can still be edited — by both brokers and HR. EN will prompt you to confirm the change and then immediately re-transmit affected deductions with their updated code(s) to your payroll partner.
- Edit freely — codes, toggles, and coverage/limit level splits
- No modal appears, no transmission triggered
- Re-enter the Deduction Audit to continue resolving discrepancies after your edits
- Edit a code → confirmation modal appears on Save
- On Confirm, EN immediately transmits all affected deductions
See it in action — edit a live code end-to-end
Watch what happens when you edit a code on a live integration. Open the edit modal, change a code, confirm, and watch your data sync to your payroll partner in real time.
What We Don't Exchange to Payroll
- Commuter Benefits
- 401(k)
- Universal Plans
- HSA
- Group Life
- Group AD&D
FAQs
Q Can I edit my payroll codes once I'm live for the integration? ›
Yes — see the Editing Codes Once You're Live section above. On Save, a confirmation modal appears; once you Confirm, EN immediately re-transmits all affected deductions to payroll. If you replaced a valid code with another, HR will need to end the old code in payroll manually.
Q Can I use the same code for more than one benefit type? ›
No. Every benefit category must have a unique code. For example, Accident and Critical Illness cannot share a "Colonial Pre" code — each plan needs its own code so EN can start, change, or stop deductions independently. This also applies to Group Life vs. Voluntary Life, and to every 3rd party app plan.
Q Does it matter if a code goes in the Pre-tax or Post-tax column? ›
Sometimes. See the Pre-tax vs. Post-tax tab in the Know Before You Map module — one-code-for-everyone scenarios don't care, but any setup with pre/post variation, user-defined tax status, or 3rd party apps does.
Q Do I need an Employer Contribution Code if my payroll partner doesn't accept them via API? ›
No — the field is optional. Leave it blank. If you want a code stored in EN for reporting purposes only, enter it and turn on Block Employer Contributions — the code will be saved but never transmitted.
Q What does the Split codes by Coverage Level toggle do? ›
Left off, one code covers the whole plan regardless of tier — that's the default and what most customers use. Turned on, the Apply Codes table expands to one row per coverage tier so you can map a separate code to each. Only turn it on if your payroll system already uses tier-specific codes. On HSA plans the same toggle reads Split codes by Limit Level and expands to Single, Family, Single Catch-up, and Family Catch-up.
Q For HSA plans with catch-up codes — what's the recommended setup? ›
Best practice is to map the regular Single/Family HSA codes into the Single Catch-up and Family Catch-up rows as well — then manage catch-up contributions manually in payroll. This prevents the catch-up code from capping an over-55 employee's deferrals at $1,000 if your payroll partner has an annual max on that code.
⚠ EN will not send two codes for employees over 55 (one for the regular limit + one for the catch-up). It sends only the code mapped into the Catch-up rows.
Q What's the "Incomplete Codes" banner I see on the Payroll Code Settings page? ›
It's a yellow warning banner telling you one or more active plans in the selected Payroll Group still needs codes mapped. It disappears once every plan has its required codes filled in. Click the How do I fix this? link on the banner to jump directly to the plans that need attention.
Comments
0 comments
Please sign in to leave a comment.