Overview

In ADP Workforce Now (WFN), employers define their own unique set of deduction codes. These codes are arbitrary and company-specific, so a 401(k) may be defined as 401k, ADP 401k, and 401K for different clients / connections.

Because of this, Finch has no reliable way to know which ADP deduction code corresponds to which benefit without additional verification. The deduction mapping you provide bridges that gap: it tells Finch which code(s) make up each benefit, and how the amount should be interpreted (a dollar amount or a percentage).

Without this mapping Finch cannot return enrollment data for a WFN benefit, and cannot create or update enrollments (deduction writes) for it. The mapping is what makes the automated connection usable.

Before you begin

• Dashboard access. You'll complete the mapping in the Finch Dashboard, under the connection's benefits configuration. Make sure the person doing the mapping has access to that connection.

• Know your codes. Only the employer truly knows how their deduction codes are grouped. Have the list of the employer's ADP deduction codes and what each one represents on hand. If you don't have the list, you can send your client a Payroll Mapping Link so they can map it themselves. See "Map each benefit" below.

• Scope. Mapping applies to benefits that already exist in ADP for the employer. Benefits newly created through Finch do not require this mapping.

Responsibilities

Terms used in this guide

• Label: the name a benefit carries in Finch. You create it in Settings; it does not rename anything in ADP.

• Benefit type: the Finch category for a label (for example 401k, 401k_roth, or 401k_loan), chosen in the Payroll Code column.

• ADP deduction code: the employer-defined code in ADP that you map to a label.

How to map deduction codes

Complete this for every new connection. Each ADP WFN connection has its own deduction codes, so mapping is done per connection. Within a connection, each benefit only needs to be mapped once.

Setup

Step A — Set up your labels

1. In the Finch Dashboard, go to Settings and create a label for each benefit you want Finch to read and write (for example 401K, Roth, Loan).

2. Each label shows up as its own row in the connection's Payroll Mapping tab (the Label column).

Step B — Call Get All Deductions once

1. Open the connection and go to the API Explorer tab.

   

2. Call Get All Deductions.

   

3. You'll get back an empty array ([]). This is expected. It doesn't mean you missed a step or that the employer has no deductions: Finch only returns benefits once they're mapped. The call loads the employer's ADP codes into the Payroll Mapping dropdowns, and it can take a while to respond.

4. Check that the codes loaded. Go to the Payroll Mapping tab, click + Add Payroll Code on any row, and open the code dropdown.

   • You see the employer's ADP codes: you're ready to map.

   • The dropdown is empty: wait a few minutes, refresh the page, and check again. Loading codes from ADP isn't always instant.

   • Still empty after waiting and refreshing: contact your Finch contact. Don't keep calling Get All Deductions.

Map each benefit

Go to the connection's Payroll Mapping tab. Each row is one of your labels.

For each label row:

1. Pick the benefit type. In the Payroll Code column, open Select benefit type and choose the Finch benefit type for this label (for example 401k, 401k_roth, or 401k_loan).

   

2. Add the ADP deduction code. Click + Add Payroll Code. Choose how the amount is expressed (Flat Dollar, Percent, or a catch-up type where it applies), then pick the ADP deduction code from the dropdown.

   

   If you don’t know what the benefit codes are, you can “Send a Payroll Mapping Link” to your client so they can map it themselves. The link will route them to the client version of the dashboard!

   

3. Add any related codes. If one benefit uses more than one ADP code (for example a 401k % code and a 401k $ code), click + Add Payroll Code again under the same row for each one. Codes added under the same row are grouped into one Finch benefit. If it's unclear whether two codes belong together, confirm with the employer before grouping them rather than guessing, since a wrong grouping produces wrong or missing enrollment data.

4. Save the mapping. This is a one-time setup per benefit; once a benefit is mapped, you don't need to redo it.

Confirm the mapping

1. Go back to API Explorer and call Get All Benefits.

2. Your mapped benefits should now appear. This is not always immediate. If a benefit is missing, wait a bit and call again before changing the mapping.

3. Pull enrollments for the benefits you've mapped, and confirm the enrolled individuals and amounts match what you know to be true in ADP.

4. Important — empty does not always mean zero. If a benefit is left unmapped, or a code is mapped incorrectly, its enrollment data comes back empty rather than as an error. So an empty enrollment response is not proof that nobody is enrolled — it can also signal a mapping gap. If a benefit you expect to be populated comes back empty, revisit its mapping first. If the mapping looks correct but data is still missing, contact Finch.

What changes after mapping

• Your benefit IDs do not change. Finch keeps your existing benefit IDs intact. Any integration logic keyed on a benefit's ID will keep working, you don't need to remap anything on your end.

• Benefit descriptions may change. Once automated processing begins, Finch derives each benefit's description from the underlying ADP deduction codes. A benefit that previously displayed as, say, "Medical" may show as a code-derived string like 001 Medical | 081 Medical. If you surface benefit descriptions to your end users, expect this change — and prefer the benefit's type or ID over the description string for any display or routing logic.

Known limitations

401(k) company contributions

• Don't send the company contribution field. If you include company_contribution in an enrollment request, ADP rejects it and the request fails. Send only the employee contribution.

• How the employer contribution is handled depends on the ADP setup:

  • Match built into the deduction code: ADP WFN applies the company match automatically for every 401(k) enrollment. No action needed in Finch.

  • Separate employer deduction code: some employers set up the company contribution as its own code. This isn't confirmed to work through the Finch API yet, so check with your Finch contact before relying on it.

Getting help

If you hit an ambiguous grouping, an unexpected empty result after checking your mapping, or anything that doesn't match what you see in ADP, reach out to your Finch contact. Where Finch is unsure how your codes should be grouped, we'll come to you rather than guessing.

Quick reference checklist

1. Confirm dashboard access to each connection being mapped

2. Create a label in Settings for each benefit

3. Gather the employer's ADP deduction codes and what each represents

4. Call Get All Deductions once (an empty [] response is expected) and confirm ADP codes appear in the Payroll Mapping dropdown

5. For each label: pick the benefit type in Payroll Code, then + Add Payroll Code for each ADP code (dollar / percent / catch-up). Leave Payroll Items empty

6. Save each mapping (one-time per benefit)

7. Call Get All Benefits and confirm the mapped benefits appear (may take a little time)

8. Verify enrollments against ADP for a sample of benefits, and treat any unexpected empty result as a possible mapping issue