Skip to main content
Connect ADP TotalSource (ADP’s PEO offering) to DualEntry through DualEntry’s normalized payroll-data provider for ADP. You authenticate ADP inside the provider’s hosted Connect widget; DualEntry stores an access token and pulls employees, pay runs, pay statements, and related payroll metadata. Data flows one way: ADP and the provider 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 location under your TotalSource employer entity can become its own mappable DualEntry company. DualEntry rolls up payroll into one journal entry per pay run, per DualEntry company. It sums 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 a 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 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 the payroll-data provider

ADP TotalSource does not use a long-lived API key. Authentication runs through the provider’s hosted Connect widget using OAuth.
  1. Navigate to Configuration → Company → Integrations → ADP TotalSource and choose Connect. DualEntry calls POST /api/finch/hris/initialize/{integration_provider_id}/ and returns a Connect widget URL.
  2. Open the widget, choose ADP in the provider list, and complete authentication in ADP as prompted.
  3. On success, DualEntry exchanges the authorization code via POST /api/finch/hris/create/ and stores the access token and connection_id on the integration. An initial sync job is queued.
  4. If you abandon a partial attempt, choose Reset in DualEntry. This calls DELETE /api/finch/hris/delete-pending/, which clears pending integration rows for your organization so the next attempt starts clean.
If the provider returns connection_already_exists because a prior connection is still on file, DualEntry falls back to the provider’s reauthenticate session and gives you a new widget URL instead of failing permanently. DualEntry re-authenticates against the provider on every sync step. If the stored token is invalid or the ADP connection has been disconnected on the provider’s side, reconnect from the integration page in DualEntry to obtain new credentials.

​
Step 2: Configure integration settings

Open Configuration → Company → 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.

​
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 Configuration → Company → Integrations → ADP TotalSource → Mappings in this order:
  1. Provider entities. Map employer-level entities so downstream pulls are valid; this is the base setup validation.
  2. 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.
  3. Payroll vendor. Map the provider’s payroll vendor row to the DualEntry vendor you created in Prerequisites.
  4. 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.
  5. 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.
  6. 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.
  7. Departments (optional). Map provider 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 Configuration → Company → Integrations → ADP TotalSource → Sync or via the HRIS sync API. The provider’s payroll sync runs a fixed pull order with no push step.
  1. Connection metadata.
  2. Payroll vendor.
  3. Employer entities.
  4. Companies - expanded into location-derived rows for ADP TotalSource.
  5. Departments and locations as classifications.
  6. Individuals, plus the ADP-specific individual-company and individual-location rows.
  7. 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.
  8. Pay statement items.
  9. Pay statements. Batched in chunks of 10 payment_ids per provider call, with retry behavior on rate limits.
  10. Benefits, pay groups, and headcount metadata.
The provider 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 provider and ADP concepts into DualEntry records as follows. Mapping the right column to your existing master data is what Step 3 covers.

​
How pay runs become journal entries

ADP TotalSource uses a multi-company consolidation strategy. Each 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 → DualEntry through the payroll-data provider. DualEntry does not push your chart of accounts, journal entries, or vendor edits back into ADP or the provider. 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.
  • Provider 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 provider multi-entity ids. If the provider 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 provider 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 Configuration → Company → Integrations → ADP TotalSource. The most common causes: For payroll-provider outages, see the provider status page. For provider API or schema changes, see the provider changelog.

​
Result

After you connect ADP TotalSource through the payroll-data provider and finish mapping, DualEntry imports payroll history within the configured window. It posts one consolidated payroll journal entry per pay run, per DualEntry company, with optional department and location dimensions on the lines. To compare another payroll connector with different consolidation defaults, see Gusto. To connect more systems, return to Integrations.
Last modified on August 27, 2026