Documentation Index
Fetch the complete documentation index at: https://docs.dualentry.com/llms.txt
Use this file to discover all available pages before exploring further.
ADP TotalSource Integration: Finch Connect and Payroll Sync
Connect ADP TotalSource - ADP’s PEO offering - to DualEntry through Finch, the normalized payroll API DualEntry uses for ADP. You authenticate ADP inside Finch’s hosted Connect widget; DualEntry stores a Finch access token and pulls employees, pay runs, pay statements, and related payroll metadata. Data flows one way: ADP and Finch are read-only sources, and DualEntry does not push your chart of accounts or journal entries back into either system.
The headline behavior for ADP TotalSource is multi-company consolidation. Each Finch location under your TotalSource employer entity can become its own mappable DualEntry company, and DualEntry rolls up payroll into one journal entry per pay run, per DualEntry company - summing lines across every employee mapped to that company in the run, rather than producing a separate entry per employee.
Prerequisites
Confirm the following before connecting:
- Admin access in DualEntry to create integrations and complete mapping.
- Permission in ADP TotalSource to authorize Finch (or another third-party payroll API) for your account.
- Your DualEntry chart of accounts includes the GL accounts you will map for earnings, taxes, employee deductions, employer contributions, and any payroll clearing or offset accounts.
- A DualEntry vendor that represents the payroll provider on journal lines (typically named “ADP” or “ADP TotalSource”); this vendor is referenced on every consolidated entry.
- A decision on child companies. If you want DualEntry to auto-create a child company per Finch location, set the parent DualEntry company on the integration before applying mappings. Otherwise, plan to map each location to an existing DualEntry company yourself.
Step 1: Connect through Finch
ADP TotalSource does not use a long-lived API key. Authentication runs through Finch’s hosted Connect widget using OAuth.
- Navigate to Settings → Integrations → ADP TotalSource and choose Connect. DualEntry calls
POST /api/finch/hris/initialize/{integration_provider_id}/ and returns a Finch Connect widget URL.
- Open the widget, choose ADP in the provider list, and complete authentication in ADP as Finch prompts you.
- On success, DualEntry exchanges the Finch authorization code via
POST /api/finch/hris/create/ and stores the Finch access token and connection_id on the integration. An initial sync job is queued.
- If you abandon a partial attempt, choose Reset in DualEntry. This calls
DELETE /api/finch/hris/delete-pending/, which clears pending Finch integration rows for your organization so the next attempt starts clean.
If Finch returns connection_already_exists because a prior connection is still on file, DualEntry falls back to Finch’s reauthenticate session and gives you a new widget URL instead of failing permanently.
DualEntry re-authenticates against Finch on every sync step. If the stored token is invalid or the ADP connection has been disconnected on Finch’s side, reconnect from the integration page in DualEntry to obtain new credentials.
Open Settings → Integrations → ADP TotalSource → Settings to configure how DualEntry handles companies, classification dimensions, and journal entry dating. The defaults work for most TotalSource customers; the table below describes when to change each one.
| Setting | What it does |
|---|
| Create child companies from Finch locations | When enabled, DualEntry creates a child DualEntry company under your parent company for every Finch location and keeps names in sync on later mapping applies. Requires a parent company on the integration. Off by default - enable it only if you want location-derived companies materialized automatically. |
| Target classification for individual-to-location mapping | Selects which DualEntry classification (and its lines) is the valid target when mapping employees to locations. Changing this setting clears any existing individual-to-location mappings so you do not silently point at the wrong dimensions. |
| Journal entry date source | Sets the date used on consolidated journal entries: payment date (default) or pay period end date. If you choose pay period end and Finch does not supply one for a given run, DualEntry falls back to the payment date and logs a warning. |
| Consolidate payroll tax lines | When enabled (default), DualEntry combines payroll tax lines on the consolidated journal entry instead of carrying one tax line per employee. |
| Department classification name | Sets the DualEntry classification used for department splits on journal lines. Defaults to Department; rename only if your account uses a different classification name for the same purpose. |
Step 3: Complete required mappings
Sync runs in a setup-incomplete mode until every required mapping is in place. After the first connection, work through the mapping screens under Settings → Integrations → ADP TotalSource → Mappings in this order:
- Finch entities. Map employer-level entities so downstream pulls are valid; this is the base Finch setup validation.
- Companies. For each location-derived company row, choose the DualEntry company that should own that location’s payroll journal entries. Skip this step if you enabled auto-create in Step 2 and have a parent company set.
- Payroll vendor. Map the Finch payroll vendor row to the DualEntry vendor you created in Prerequisites.
- Pay statement items. Every earnings, tax, deduction, and contribution line must map to a GL account before consolidated journal entries can post. Unmapped items surface as integration errors on the affected pay statements.
- Individuals to company. Each employee must map to a DualEntry company so pay can be grouped for consolidation. Pay statements for unmapped employees are skipped with a record-level error until mapping is fixed.
- Individuals to location (ADP-specific). Map each employee to a classification line under the classification you selected in Step 2. Optional: lines without a match are simply omitted from the resulting journal entry without failing the run.
- Departments (optional). Map Finch department names to DualEntry classification lines if you want department splits on journal lines.
Until credentials are valid and the required mappings (entities, companies, payroll vendor, pay statement items, individuals to company) all exist, pay statement import will not produce journal entries for affected payments.
Step 4: Run sync
Trigger sync from Settings → Integrations → ADP TotalSource → Sync or via the Finch HRIS sync API. Finch payroll runs a fixed pull order with no push step.
- Connection metadata.
- Payroll vendor.
- Employer entities.
- Companies - expanded into location-derived rows for ADP TotalSource.
- Departments and locations as classifications.
- Individuals, plus the ADP-specific individual-company and individual-location rows.
- Payments. Pulled from a rolling window of the later of 180 days before today and your organization’s default cutoff date setting, so older open periods can be included when the cutoff is configured back.
- Pay statement items.
- Pay statements. Batched in chunks of 10
payment_ids per Finch call, with retry behavior on rate limits.
- Benefits, pay groups, and headcount metadata.
Finch can throttle long pay-statement pulls. If a sync is rate-limited, the batch backs off and resumes; you do not need to intervene unless errors persist after subsequent runs.
What syncs
The integration ingests Finch and ADP concepts into DualEntry records as follows. Mapping the right column to your existing master data is what Step 3 covers.
| Finch / ADP concept | DualEntry record | Notes specific to ADP TotalSource |
|---|
| Pay statement items | GL account on consolidated journal lines | Same categories as other Finch payroll: earnings, taxes, employee deductions, employer contributions. |
| Payroll vendor | Vendor | Required on every consolidated journal entry. |
| Employer entity plus locations | Company integration rows | Each Finch location under the TotalSource entity becomes a separate mappable company row, so you can split payroll across DualEntry entities. |
| Individual | Individual customer record plus individual-company and individual-location mapping rows | Individual-to-company mapping drives which DualEntry company receives each employee’s pay in a consolidated run. Individual-to-location is unique to ADP TotalSource. |
| Payment and pay statement | Source for consolidated journal entries | Payments are pulled from the rolling window described in Step 4; pay statements are batched and rate-limit-aware. |
How pay runs become journal entries
ADP TotalSource uses a multi-company consolidation strategy. Each Finch payment produces one or more journal entries, depending on how employees are mapped:
- Pay statements for a single payment are grouped together.
- They are split by each employee’s mapped DualEntry company.
- For every (payment, company) pair, DualEntry builds one consolidated journal entry that sums lines across every employee in that company for the run, applying the payroll tax line consolidation rule from Settings.
- The journal entry date comes from the payment date or the pay period end date, depending on the journal entry date source setting.
- The memo follows the pattern
[ADP TotalSource] Payroll {start} to {end} paid on {pay_date} ({n} employees) for that company’s slice of the run.
Employees with no DualEntry company mapping cause their pay statements to be skipped with an integration error on the record until mapping is fixed; the rest of the payment still posts.
Current limitations
Review these limitations before relying on the integration in production:
- One direction only. Data flows ADP → Finch → DualEntry. DualEntry does not push your chart of accounts, journal entries, or vendor edits back into ADP or Finch. ADP remains the system of record for payroll and HR.
- Consolidation is per company, not per employee. Imported journal entries summarize each pay run at the company level. If you need employee-level detail in DualEntry, plan to derive it from the source pay statements rather than the journal entry.
- Approvals stay in ADP. Pay run approvals, payroll corrections, and operational HR workflows remain in ADP TotalSource; DualEntry ingests the financial result.
- Finch multi-entity mode is not the same as DualEntry multi-company. TotalSource consolidation is built around mapping individuals to DualEntry companies derived from your TotalSource locations, not around arbitrary Finch multi-entity ids. If Finch reports an entity mode your deployment does not support, treat it as a support case.
- Auto-create requires a parent company. When you enable auto-creation of child companies from Finch locations, the integration must have a parent DualEntry company set or the apply step fails with an explicit error.
Troubleshoot sync errors
When a record fails, it appears in the Integration Errors log under Settings → Integrations → ADP TotalSource. The most common causes:
| Symptom | Likely cause | Resolution |
|---|
| Widget or token errors right after connect | Authorization code already used, Finch outage, or wrong provider chosen in the widget. | Reset the integration to clear pending Finch rows, then run Connect again; contact support with the Finch error payload if the widget keeps failing. |
| ”Payment record not found for pay statement” | A pay statement does not yet resolve to a payment-and-individual pair on Finch. | Ensure payments synced for the same window first; rerun sync after payments complete. |
| No journal entry for a company | No employees are mapped to that DualEntry company for that payment. | Map every paid employee to a DualEntry company under Settings → Integrations → ADP TotalSource → Mappings. |
| ”No locations found for company” | The Finch entity has an empty locations list. | Fix the source data in ADP or Finch, or map companies manually without relying on location expansion. |
| Rate limit or slow pay statement pull | Finch is throttling the batched pay-statement fetches. | Wait and rerun sync; batches are capped to reduce burst size, and the worker resumes on the next run. |
| Classification mapping looks wrong after a settings change | The target classification setting was changed, which clears existing individual-to-location mappings. | Re-map individuals to location lines under the new classification. |
Result
After you connect ADP TotalSource through Finch and finish mapping, DualEntry imports payroll history within the configured window and posts one consolidated payroll journal entry per pay run, per DualEntry company, with optional department and location dimensions on the lines.
To compare another Finch-backed payroll connector with different consolidation defaults, see Gusto. To connect more systems, return to Integrations.