> ## 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.

# How Custom Integrations Work

> The architecture behind a DualEntry partner integration: its layers, the categories integrations fall into, and the complexity tiers that shape setup.

A DualEntry integration connects a partner system to a customer's DualEntry organization, transforms data between the two systems' models, and persists it through DualEntry's [Public API](/developers/api/resources-v2). Every integration that ships through the partner program must satisfy the requirements in the [Custom Integration Reference](./custom-integration-reference) before it goes live to mutual customers.

## Architecture overview

DualEntry is a cloud accounting and ERP platform. Integrations connect a partner system to a DualEntry organization, transform data between the two systems' models, and persist it through DualEntry's APIs. Depending on your use case, data moves in either direction, or both.

A typical integration includes the following layers:

* **Auth layer**: Establishes a secure connection between your system and a DualEntry organization. The DualEntry Public API authenticates with an organization [API key](/developers/guides/api/authentication) sent in the `X-API-KEY` header. Keys are scoped to one organization and carry the roles assigned to them.
* **Sync layer**: Moves data on a schedule, in response to webhooks, or on demand. Most integrations run as background jobs on the partner side.
* **Mapping layer**: Translates fields between your data model and DualEntry's. Some mappings are fixed; others are configurable by the customer in the DualEntry UI.
* **Deduplication layer**: Prevents duplicate records using stable external IDs and upsert semantics.
* **Error and retry layer**: Handles transient failures with backoff (see [Errors](/developers/guides/api/core-concepts/errors) and [Rate limiting](/developers/guides/api/core-concepts/rate-limiting)), and surfaces persistent failures to customers via DualEntry's Sync History view.

## Integration categories

Not all integrations follow the same pattern. The category yours falls into determines the setup flow, mapping requirements, and certification expectations.

* **Standard transactional**: The most common. The customer authenticates, maps accounts, and data flows on a schedule. Examples: corporate cards, payment processors, payroll, billing platforms.
* **Bank feed**: Bank account data sync rather than transactional record mapping. Different setup paradigm.
* **Data warehouse / BI push**: One-way data push for analytics or reporting. No record-level sync.
* **File-based**: Data exchanged via structured file transfer (CSV, EDI, etc.) rather than synchronous API calls. Typically not customer-self-service to set up.
* **ERP migration**: One-time or staged historical data import from a legacy system.

## Complexity tiers

Integration complexity shapes how much setup UI, configuration, and testing it needs.

* **Tier 1 - Simple:** API key auth, single entity, one-way sync, minimal mapping.
* **Tier 2 - Standard:** OAuth, account or vendor mapping, scheduled sync, bidirectional flow on a few record types.
* **Tier 3 - Complex:** Multi-entity mapping, classification or department mapping, custom field mapping, multi-currency, cross-company.

## Where to go next

For the step-by-step of building an integration, see [How to Build a Custom DualEntry Integration](./how-to-build-a-custom-integration). For the certification checklist and troubleshooting, see [Custom Integration Reference](./custom-integration-reference).