> ## 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: Connect and Payroll Sync

> Connect ADP TotalSource to DualEntry, map locations and employees to companies, and import consolidated payroll journal entries per pay run.

Connect [ADP TotalSource](https://www.adp.com/what-we-offer/products/totalsource-peo.aspx) - 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, 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 a third-party payroll API for your account.
* Your DualEntry [chart of accounts](../core-financials/general-ledger/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 **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 **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.

| Setting                                                  | What it does                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create child companies from provider locations           | When enabled, DualEntry creates a child DualEntry company under your parent company for every 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 the provider 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 **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 **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_id`s 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.

| Provider / ADP concept         | DualEntry record                                                                        | Notes specific to ADP TotalSource                                                                                                                                     |
| ------------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pay statement items            | GL account on consolidated journal lines                                                | Same categories as other payroll providers: earnings, taxes, employee deductions, employer contributions.                                                             |
| Payroll vendor                 | Vendor                                                                                  | Required on every consolidated journal entry.                                                                                                                         |
| Employer entity plus locations | Company integration rows                                                                | Each 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 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 **Company → Integrations → ADP TotalSource**. The most common causes:

| Symptom                                                    | Likely cause                                                                                          | Resolution                                                                                                                                                        |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Widget or token errors right after connect                 | Authorization code already used, provider outage, or wrong provider chosen in the widget.             | Reset the integration to clear pending integration rows, then run **Connect** again; contact support with the provider 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 the provider's side.         | 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 Company → Integrations → ADP TotalSource → Mappings.                                                         |
| "No locations found for company"                           | The provider entity has an empty locations list.                                                      | Fix the source data in ADP or the provider, or map companies manually without relying on location expansion.                                                      |
| Rate limit or slow pay statement pull                      | The provider 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.                                                                                                |

For payroll-provider outages, see the [provider status page](https://status.tryfinch.com/). For provider API or schema changes, see the [provider changelog](https://changelog.tryfinch.com/).

## Result

After you connect ADP TotalSource through the payroll-data provider 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 payroll connector with different consolidation defaults, see [Gusto](./gusto). To connect more systems, return to [Integrations](./index).