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

# Custom Integration Reference

> The certification checklist, common pitfalls, troubleshooting reference, and kickoff checklist for a custom DualEntry Public API integration.

This page collects the reference material for shipping and maintaining a certified DualEntry integration. For the architecture behind an integration, see [How Custom Integrations Work](./how-custom-integrations-work); for the implementation steps, see [How to Build a Custom DualEntry Integration](./how-to-build-a-custom-integration).

## Certification checklist

Before your integration ships to mutual customers, every applicable item below must pass. This is the pre-launch checklist and what the integrations team reviews during certification.

### Functional

* New record creation syncs correctly.
* Record updates sync correctly.
* Voids and deletes sync correctly.
* Field mapping matches the documented mapping table.
* Defaults apply correctly when source fields are null or missing.
* Mapping UI only exposes tabs and options relevant to your integration.
* Account and classification mappings invalidate cleanly when settings change.
* Mapping dropdowns are unambiguous (include disambiguating info like account number or type when names alone could collide).

### Cut-off date

* Cut-off date is enforced: no records before the cut-off sync into DualEntry.
* Records dated exactly on the cut-off are included.
* Re-sync respects the cut-off.
* Backdated records from your platform respect the cut-off.

### Duplicate prevention

* Initial sync produces no duplicates.
* Re-sync is fully idempotent.
* Concurrent sync workers do not produce duplicates or integrity errors.

### Multi-currency (if applicable)

* Non-base-currency transactions sync with the correct currency code.
* Exchange rates apply correctly.
* FX gain/loss entries are generated where applicable.
* Partial payments in different currencies are handled.

### Cross-company / intercompany (if applicable)

* Intercompany journal entries are created correctly.
* Cross-entity bank transfers post to the correct accounts in each entity.
* Elimination entries are generated as expected.

### Money-In / Money-Out (if applicable)

* AR / invoice transactions sync correctly.
* AP / bill transactions sync correctly.
* Received payments are matched and applied.
* Sent payments are recorded accurately.
* Refunds and credits are handled correctly.

### Attachments (if applicable)

* Attachments sync alongside their parent records.
* File size limits are respected.

### Resilience

* Partner API downtime is handled gracefully with retry.
* Large batch syncs complete without timeout.
* Rate limits are respected.
* Locked records cannot be edited manually in DualEntry.
* Sync History reports every sync run, success or failure.
* Failed syncs surface actionable error messages.

### Multi-instance (if applicable)

* Multiple instances per organization run independently.
* Each instance is clearly mapped to the correct DualEntry company.

## Common pitfalls

These are the issues that come up most often during certification reviews and post-launch support.

| Pitfall                                                               | What to do instead                                                      |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Records syncing in from before the cut-off date                       | Filter by cut-off in the sync **query**, not after fetching             |
| Duplicate records on re-sync                                          | Implement upsert by stable external ID with proper concurrency handling |
| Placeholder records like "Unknown Company" appearing in customer data | Use integration-level defaults the customer configured at setup         |
| Customers getting stuck on confusing auth fields                      | Use clear labels and inline help text; validate credentials on save     |
| Mapping screens showing raw UUIDs                                     | Resolve and cache display names at sync time                            |
| Sync failing silently with no record in DualEntry and no error        | Log every gap and surface failures in Sync History                      |
| Duplicate entries in mapping dropdowns                                | Deduplicate before rendering                                            |
| Migration or initial connect appearing to hang indefinitely           | Implement timeout detection and surface clear status to the user        |
| AI-driven mapping suggestions feeling laggy                           | Debounce input and cache results                                        |
| UI not refreshing after a successful connect                          | Refresh integration status after the connect callback                   |
| Ambiguous account mappings (multiple accounts with similar names)     | Include disambiguating info in dropdowns (account number, type)         |

## Troubleshooting reference

### Common symptoms

| Symptom                                     | Likely cause                                                     | Where to look                                                   |
| ------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- |
| Sync isn't triggering                       | Webhook misconfigured, schedule not set, or integration disabled | Webhook registration, schedule config, integration enable state |
| Duplicate records                           | Missing or unstable external ID, or concurrent sync race         | External ID matching, async worker concurrency                  |
| Amount mismatches                           | Currency conversion issue or minor/major unit confusion          | Field transformations, decimal precision                        |
| OAuth auth failure                          | Token expired, scopes changed, or revoked on partner side        | Token refresh logic; prompt customer to reconnect               |
| API key auth failure                        | Key invalid or rotated                                           | Validate with a lightweight API call; prompt re-entry           |
| Records appearing from before cut-off       | Cut-off filter missing or applied post-fetch                     | Cut-off logic in sync query                                     |
| Mapping screen shows UUIDs instead of names | Display name resolution missing                                  | Add lookup or cache name resolution                             |
| Initial connect hangs indefinitely          | Timeout or partner API unreachable                               | Add timeout detection, surface clear status                     |
| "Unknown" records appearing                 | Sync not using customer-configured defaults                      | Default to integration config, never invent placeholders        |

### Re-sync procedures

* **Manual re-sync**: Triggered by the customer via Sync Now in DualEntry.
* **Date range re-sync**: Re-pull records within a specific window.
* **Full re-import**: Clear and re-import all data. Use cautiously, and only if your idempotency guarantees are bulletproof.

### Observability

* DualEntry exposes integration sync status to customers in the admin UI.
* Integration health metrics flow into the partner observability dashboards: your support team can be granted access on request.
* Detailed sync logs are available for specific runs through the partner portal.

## New integration kickoff checklist

Use this when starting a new integration to make sure nothing slips:

* Partner agreement signed.
* API credentials and sandbox org provisioned.
* Field mapping spec agreed with DualEntry's integrations team.
* Integration category and complexity tier identified.
* Partner sandbox or test environment ready on your side.
* Auth flow implemented and tested.
* Sync engine built with the right schedule and trigger model.
* Field mapping and transformations implemented.
* Cut-off date enforcement implemented.
* Deduplication and idempotency implemented.
* Multi-currency handling implemented (if applicable).
* Cross-company / intercompany handling implemented (if applicable).
* Mapping UI configured with the correct tabs visible.
* Error handling and retry logic implemented.
* Sync History reporting verified.
* Observability and tracing in place.
* All applicable certification checklist items pass.
* Partner-facing documentation published.

## Support and resources

* **Partner API documentation**: Available in the partner portal once your account is provisioned. Request access through your partnership contact.
* **Partner support**: Reach out through your partnership contact for technical questions, certification scheduling, or post-launch support.
* **Status and observability**: Integration health dashboards are accessible to your team through the partner portal.
* **Public API reference**: See the [V2 API Reference](/developers/api/resources-v2) for endpoint-level documentation.