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 AP Sync
Connect Deel to DualEntry so workforce invoices from Deel flow into your ledger as vendor bills in Accounts Payable, and Deel people (contractors and employees) sync into DualEntry as vendors for those bills. The integration is read-only toward Deel: DualEntry pulls accounting, people, contract, and organization data from Deel’s REST API; it does not push your chart of accounts or journal entries back into Deel. DualEntry authenticates with OAuth 2.0 (authorization code plus callback). Required Deel scopes areaccounting:read, contracts:read, organizations:read, and people:read.
Prerequisites
Confirm the following before connecting:- Admin (or equivalent) access in DualEntry to create integrations and map entities.
- Permission in Deel to install or authorize an OAuth application for your organization.
- A Deel OAuth app registered in Deel’s developer settings, with a redirect URI that matches the DualEntry callback URL for your environment. Your implementation team or DualEntry support provides the exact URL.
- Your DualEntry companies (entities) ready to map to Deel legal entities. Mapping is required before the integration is considered fully set up.
- Awareness that imported bill line items currently post to your organization’s system Accounts Payable account, not to natural expense accounts. Plan to reclassify in DualEntry if cost categorization matters for your reporting.
Step 1: Authorize DualEntry in Deel (OAuth)
DualEntry uses the standard OAuth 2.0 authorization-code flow against Deel’s auth and API base URLs configured for your deployment.- Navigate to Settings → Integrations → Deel.
- Choose Connect with Deel. DualEntry requests scopes
accounting:read,contracts:read,organizations:read, andpeople:read. - When Deel’s consent screen loads, sign in with an account that can authorize OAuth apps for your organization.
- Approve the requested permissions.
- Deel redirects back with an authorization code. DualEntry exchanges it for access and refresh tokens, stores them on the integration record, runs an initial legal-entity pull, and marks the integration connected when the pull succeeds.
/api/integrations/deel/.
Step 2: Map every Deel legal entity to a DualEntry company
After the first connection, DualEntry has integration records for each Deel legal entity. Setup is not complete until every legal entity is mapped to a DualEntry company (the entity dimension you use for books).- Open Settings → Integrations → Deel → Legal Entities.
- For each Deel legal entity row, choose the DualEntry company that corresponds to that entity.
- Save the mappings.
is_setup_completed remains false on the integration record. Automated syncs that depend on entity resolution will not run cleanly until every mapping is saved.
Step 3: Run sync and understand pull order
Ongoing sync pulls three categories from Deel in a fixed order: invoices first, then people, then legal entities. The order matters because bill creation depends on people being available as vendors.| Order | Pull | Deel source (REST) | DualEntry target |
|---|---|---|---|
| 1 | Invoices | /rest/v2/invoices (list) plus per-invoice detail for line items | Vendor bills (AP) |
| 2 | People | /rest/v2/people | Vendors (created or matched by name within your organization) |
| 3 | Legal entities | /rest/v2/legal-entities | Integration records mapped to companies |
The first full sync may attempt invoices before people have been imported into DualEntry. If bill creation fails because the worker on the invoice’s contract is not yet a vendor, run sync again after people complete; subsequent runs typically clear those errors.
PUSH is empty in the sync service configuration). Deel remains the system of record for workforce and invoice metadata; DualEntry ingests it for AP and vendor master data.
What becomes a bill in DualEntry
When a Deel invoice is imported as a bill, DualEntry maps the source fields as follows:- Vendor is resolved from the Deel person linked to the invoice’s contract (after people sync). If the contract has no matching person in the synced data, import fails with a clear integration error for that record.
- Dates and currency come from Deel (
issued_at,due_date, invoice currency, with a safe default to USD if an unknown currency code appears). - Memo includes the Deel invoice id (for example,
Deel Invoice <id>). - Line items become bill expense lines from Deel’s description, quantity, and total. Each line’s GL account is set to your organization’s system Accounts Payable account in the current implementation, not to natural expense categories from Deel.
How people become vendors
For each Deel person, DualEntry gets-or-creates a vendor keyed by name within your organization. The match is name-based, so workers who share a name across Deel records collide on the same DualEntry vendor; review the People list after the first sync if you have common names in your workforce. Vendor fields are populated from Deel as follows:- Email. DualEntry prefers the worker’s work email, falls back to their primary email, and uses any other listed address only if those two are missing.
- Vendor type. Direct employees in Deel map to vendor type
individual. Other hiring types (independent contractors, EOR workers) map tocompanyin DualEntry’s vendor model. - Status. Workers with Deel hiring status
terminatedare marked inactive in DualEntry; active workers stay active. - 1099 eligibility. New vendors default to
1099_eligible = false. Deel does not provide this signal, so set it manually in DualEntry for U.S. contractors who require a 1099-NEC. - Address. DualEntry uses the first address on the Deel person record. Missing fields are filled with placeholder values so the vendor record stays valid; review and correct these before issuing payment.
Current limitations
A few aspects of the integration are worth knowing before you rely on it:- One Deel integration per DualEntry organization. The connector creates or updates a single integration record per organization. If you need separate Deel workspaces represented in your books, set up separate DualEntry organizations.
- Bill line items post to the system AP account. Imported bill expense lines route to your organization’s system Accounts Payable account rather than to natural expense categories from Deel. Reclassify in DualEntry if cost categorization matters for your reporting.
- Attachments and purchase-order links are not synced. Deel attachments and PO references are not populated on DualEntry bills in the current code path.
- Read-only toward Deel. DualEntry does not push your chart of accounts, journal entries, or vendor edits back into Deel. Deel remains the system of record for workforce and invoice data.
Troubleshoot sync errors
When a record fails, it appears in the Integration Errors log under Settings → Integrations → Deel. The most common causes:| Symptom | Likely cause | Resolution |
|---|---|---|
| OAuth or “unauthorized” right after connect | Wrong redirect URI, revoked Deel app, or declined scopes. | Confirm the Deel OAuth app redirect URI matches DualEntry’s callback; re-run connect and approve all required scopes. |
| Legal entity mapping errors or “setup incomplete” | One or more Deel legal entities are not mapped to a DualEntry company. | Complete every legal-entity to company mapping under Settings → Integrations → Deel → Legal Entities, then save. |
| Bill import: no person for contract | People sync has not yet created or mapped the worker for that invoice’s contract_id. | Run sync again after people succeed; verify the contract exists in Deel for that worker. |
| Bill import: other validation errors | Line item shape or totals changed in the Deel API. | Check the integration error detail; compare against the Deel API changelog for breaking changes. |
| Stale or failing API calls | Deel outage or rate limiting. | Check Deel status; retry sync after the incident clears. |