> ## 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. # Deel Integration: OAuth Setup and Payroll Posting > Connect Deel to DualEntry, map legal entities, contractors, and pay statement accounts, and post contractor, EOR, PEO, and payroll cycles as journal entries. Connect [Deel](https://www.deel.com/) to DualEntry so the payments you make through Deel post to your ledger as journal entries. DualEntry splits the entries by the kind of worker paid: independent contractors, workers employed through an employer of record (EOR) or a professional employer organization (PEO), and employees on Deel's Global Payroll. Deel's own service fees post separately as vendor bills in Accounts Payable. The integration is read-only toward Deel. DualEntry pulls accounting, contract, payment, and organization data from Deel's REST API and never pushes your chart of accounts, journal entries, or vendor edits back. DualEntry authenticates with OAuth 2.0, using the authorization code flow with a callback. The connection requests seven read scopes: `accounting:read`, `contracts:read`, `organizations:read`, `people:read`, `global-payroll:read`, `payslips:read`, and `legal-entity:read`. ## Prerequisites Confirm the following before connecting. * Admin or equivalent access in DualEntry to create integrations and map records. * Permission in Deel to authorize DualEntry for your organization. * A DualEntry company for each Deel legal entity. Every legal entity has to be mapped before setup counts as complete. * A vendor record in DualEntry to act as the payroll vendor. DualEntry uses it on journal entries and bills when Deel is the counterparty (EOR, PEO, shielded contractors) and when a contractor has no mapped vendor. * GL accounts for both pay statement catalogs described below, including Input VAT Recoverable and the Global Payroll row **\[Deel] Journal Entry Offset**. * A Default Offset Account in the Deel settings drawer. Contractor, EOR, and PEO journal entries credit this account. * An expense account mapped to **Deel Service Fees**. * EOR Employment Expense and PEO Employment Expense accounts in the drawer if you have workers of those types. Contractor vendor mapping is optional for posting. DualEntry does not create vendors. An unmapped contractor still posts, stamped with the payroll vendor. ## How to connect Connecting opens Deel's consent screen, where an account that can authorize OAuth apps approves the requested scopes. DualEntry exchanges the returned code for tokens, pulls your legal entities, and marks the integration connected. 1. Go to **Configuration → Company → Integrations → Deel**. 2. Choose **Connect with Deel**. 3. Sign in with a Deel account that can authorize OAuth apps for your organization. 4. Approve the requested permissions. 5. Confirm the integration shows as connected. If authorization fails, DualEntry leaves the integration in an error state with a status message. Reconnect and approve the requested scopes. DualEntry warns about Global Payroll when both `global-payroll:read` and `payslips:read` are missing. DualEntry warns about legal entities when `legal-entity:read` is missing. Without `payslips:read`, everything posts normally but EOR payslip PDFs are not attached to journal entries, and each affected entry carries a warning saying so. ## What syncs Each sync runs 10 pulls in a fixed order. The order matters: accounts and mappings are established first, then payments, and journal entries are built last from data the earlier steps put in place. | Order | Pull | Deel source | DualEntry target | | ----- | ------------------- | -------------------------------------------------------------------- | ---------------------------------------------- | | 1 | Connection metadata | `/rest/v2/legal-entities` (token check) | Entity count on the integration | | 2 | Payroll vendor | n/a | Your mapped payroll vendor | | 3 | Legal entities | `/rest/v2/legal-entities` | Mapped to companies | | 4 | Classifications | `/rest/v2/legal-entities/{id}/cost-centers` | Classification lines | | 5 | Individuals | `/rest/v2/contracts` | Mapped to vendors (Contractor tab only) | | 6 | Payments | `/rest/v2/payments` | Payment records | | 7 | Pay statement items | Fixed contractor and Global Payroll catalogs | Mapped to GL accounts | | 8 | Pay statements | `/rest/v2/payments/{id}/breakdown`, invoices, Global Payroll reports | Journal entries | | 9 | Deel fees | `/rest/v2/invoices/deel` | Vendor bills | | 10 | Headcount | Derived from contracts | Count per legal entity in integration metadata | DualEntry pulls payments and Deel fee invoices for a rolling 12-month window. Setting a cutoff date on the integration reaches further back, and the earlier of the two dates wins. ## Worker types Deel's contract type determines how a worker's pay posts. DualEntry resolves it from the contract rather than asking you to classify anyone. There are four posting models. * **Independent contractor.** Contracts of type contractor, milestones, time based, task based, pay as you go, fixed rate, or freelancer. Posts one journal entry per contractor invoice, itemized from the payment breakdown. * **EOR, employer of record.** A third party legally employs the worker on your behalf, typically where you have no legal entity. Posts a two-line journal entry per invoice: the invoice total debited to your EOR employment expense account, credited to the Default Offset Account. * **PEO, professional employer organization.** A co-employment arrangement covering workers at your own entity. Posts the same two-line shape as EOR, against your PEO employment expense account. * **Global Payroll employee.** Employees Deel runs payroll for directly. Posts from the payroll cycle's gross-to-net report rather than from an invoice. A contract whose type DualEntry does not recognize is skipped rather than guessed at, and the record carries an `UNMAPPED_CONTRACT_TYPE` error naming the type Deel sent. ## Map your Deel data DualEntry reports setup as complete only when all of the following hold: * Every legal entity is mapped to a company. * The payroll vendor is mapped. * Every contractor catalog row is mapped. * Every Global Payroll catalog row is mapped. * **Deel Service Fees** is mapped to a GL account. Setup complete does not require the drawer Default Offset Account. Contractor, EOR, and PEO posting does. EOR and PEO employment expense accounts are required at post time once DualEntry sees workers of that type, not as part of setup complete. ### Map legal entities to companies Each Deel legal entity maps to the DualEntry company its payroll posts to. An unmapped entity blocks the journal entries that belong to it, and each blocked record carries a `LEGAL_ENTITY_UNMAPPED` error naming the entity, so you can map it and resync without hunting. ### Map contractors to vendors The **Contractor** tab lists independent contractors only. EOR, PEO, Global Payroll, and shielded contractor of record (COR) workers are filtered off that tab. DualEntry does not create a vendor when none matches. Map each contractor you want stamped as their own vendor on journal entries. An unmapped contractor still posts. DualEntry falls back to the payroll vendor and writes the journal entry. ### Map pay statement items to GL accounts Pay data maps onto two fixed catalogs rather than a list built from your own Deel configuration, so the mapping work is bounded. Each item carries a fixed debit or credit direction, so you choose only the account. **Accounts (Contractors)** holds 10 items: Work, Bonus, Overtime, Commissions, Expenses, Pro Rata, Adjustment, Processing Fee, Deductions, and Input VAT Recoverable. **Accounts (GP Employees)** holds seven items plus **\[Deel] Journal Entry Offset**: Work (Base Pay / Wages), Bonus, Overtime, Commissions, Expenses (Allowances / Reimbursements), Employer Contributions, Deductions, and the offset row. Global Payroll journal entries credit that offset row. EOR and PEO expense accounts are drawer settings (**EOR Employment Expense** and **PEO Employment Expense**). ### Set the integration accounts Open the Deel settings drawer and set: * **Default Offset Account.** The credit side of contractor, EOR, and PEO journal entries. * **EOR Employment Expense** and **PEO Employment Expense.** The debit side for EOR and PEO entries. DualEntry requires these only once it sees workers of that type. Until one is set, entries for that worker type are held with an `EOR_EXPENSE_ACCOUNT_REQUIRED` or `PEO_EXPENSE_ACCOUNT_REQUIRED` error while everything else keeps posting. * **Cost Center Classification Name.** The classification Deel cost centers map onto. Cost centers apply on contractor, EOR, and PEO journal entry lines. ## How payments become journal entries Contractor, EOR, and PEO journal entries are built from Deel payments and invoices. Each of those entries is dated the payment date, falling back to the invoice paid date and then the issue date. Global Payroll entries are built from closed payroll cycles and dated from the cycle end date, falling back to the start date. ### Contractor invoices A contractor entry (including shielded COR) is a set of self-balancing pairs. Each non-zero category on the payment breakdown becomes a debit and credit pair against its mapped account. Breakdown `others` maps to Adjustment. Recoverable VAT posts as its own pair when the invoice VAT total is greater than zero. An "Unclassified payment" memo appears only when every breakdown amount is zero (and there is no VAT to post). In that case DualEntry posts the invoice total to Work. Entries post in the breakdown row's currency. The exchange rate is the breakdown total divided by the breakdown total in payment currency. The credit side of each pair uses the Default Offset Account from the drawer. ### EOR and PEO invoices EOR and PEO entries are two lines: the invoice total debited to the employment expense account for that type, credited to the Default Offset Account. ### Global Payroll cycles Global Payroll entries are built from the cycle's gross-to-net report, with columns classified into earnings, employer contributions, and deductions. They credit **\[Deel] Journal Entry Offset** on the GP catalog. Review the results in [Journal Entries](../../core-financials/general-ledger/journal-entries). ## EOR payslip attachments For EOR workers, DualEntry attaches the Deel payslip PDF to the journal entry it posts, so the supporting document sits with the entry during close rather than in a separate system. DualEntry lists the worker's payslips, picks the one whose pay period contains the entry date, and attaches it as `deel-payslip-{id}.pdf`. Where several periods overlap, the closest period end wins. Attachment is best effort and never blocks posting. When it fails, the entry posts and carries a warning naming the reason: the token is missing the `payslips:read` scope, no payslip matched the pay period, the download failed, or the worker could not be resolved from the payment row. Warnings are distinguished from errors, so an entry with an unattached payslip is not treated as a failed import. ## Deel service fees Deel's own invoices to you, as opposed to the invoices covering worker pay, post as vendor bills in Accounts Payable rather than as journal entries. Each fee invoice becomes one bill against your payroll vendor, posted to the **Deel Service Fees** account. Fee bills are skipped rather than failed when the payroll vendor or the **Deel Service Fees** account is unset, so setting them later picks up the backlog on the next sync. To pay these bills and see them in aging, see [Accounts Payable](../../core-financials/accounts-payable/index). ## Current limitations * **One Deel integration per DualEntry organization.** The connector maintains a single integration record per organization. Separate Deel workspaces need separate DualEntry organizations. * **Purchase order links are not synced.** Deel PO references are not populated on DualEntry records. Payslip PDFs are attached for EOR workers only. * **Read-only toward Deel.** DualEntry does not push accounts, entries, or vendor edits back. Deel remains the system of record for workforce and payment data. ## Troubleshoot sync errors Failed and warned records appear in the **Integration Errors** log under **Configuration → Company → Integrations → Deel**. Entries prefixed with `WARNING` posted successfully and need attention rather than a retry. | Symptom | Likely cause | Resolution | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Unauthorized right after connect | Declined scopes or revoked Deel access. | Reconnect and approve every requested scope. | | `LEGAL_ENTITY_UNMAPPED` | A Deel legal entity has no DualEntry company. | Map it on the Legal Entities tab and resync. The error clears on the next run. | | `UNMAPPED_CONTRACT_TYPE` | Deel sent a contract type DualEntry does not recognize. | Raise it with support, quoting the contract type in the message. The contract is skipped until then. | | `EOR_EXPENSE_ACCOUNT_REQUIRED` or `PEO_EXPENSE_ACCOUNT_REQUIRED` | Workers of that type exist but the employment expense account is unset. | Set the account in the Deel settings drawer. Held entries post on the next sync. | | A contractor's pay posts to the payroll vendor | The contractor is not mapped to a DualEntry vendor. | Map them on the Contractor tab if you want their vendor on the entry. The entry already posted. | | Pay statements fail after setup looks complete | Default Offset Account is empty in the drawer. | Set Default Offset Account, then resync. | | A pay statement category is not mapped | A catalog item has no GL account. Input VAT Recoverable must be mapped even when invoices have no VAT. | Assign the account, then resync. | | Fee bills never appear | **Deel Service Fees** is unmapped, or the payroll vendor is unset. | Map **Deel Service Fees** and the payroll vendor. Unset fees are skipped, not failed. | | `WARNING: EOR payslip PDF not attached` | Missing `payslips:read` scope, no payslip matching the pay period, a failed download, or an unresolved worker. | The entry posted. Reconnect with the scope granted, or attach the payslip by hand. | | Global Payroll report errors on every legal entity | The token lacks `global-payroll:read`. DualEntry then marks every entity as GP-enabled and the report fetch fails per entity. | Reconnect and grant `global-payroll:read`. | | Stale or failing API calls | Deel outage or rate limiting. | Check [Deel status](https://status.deel.com/) and retry after the incident clears. For payload changes, compare against the [Deel API changelog](https://developer.deel.com/api/changelog). | ## Result Once every legal entity is mapped to a company, both pay statement catalogs and **Deel Service Fees** are mapped, and the drawer Default Offset Account is set, the integration is ready. Each sync then posts your Deel payments as journal entries by worker type, attaches EOR payslips where available, and files Deel's service fees as bills for AP. For other payroll providers, see the [Gusto integration](./gusto) or the [Justworks integration](./justworks). For the sync actions common to every connector, see [Retry, resync, and archive](../managing-syncs). To connect more systems, return to [Integrations](../index).