External Sync

Keep Alguna and your CRM in step

External Sync keeps records in step between Alguna and a connected CRM. You choose, per object type, which system leads and what happens when both sides change.

Sync is configured in the dashboard under Settings → Integrations. There is no public API for sync configuration; the public API exposes your connected integrations read-only through GET /integrations and GET /integrations/{id}.

---

Supported Systems

External Sync covers the CRM integrations:

System	Objects
Salesforce	Accounts, contacts, opportunities, subscriptions, products
HubSpot	Companies, contacts, deals, subscriptions, products

Accounting integrations move data on their own schedules and are not configured here. See Quickbooks, Xero and Netsuite.

---

How It Works

Each sync configuration covers one object type on one integration. A configuration says which direction data flows and, when it flows both ways, which side wins a conflict.

1. Connect the integration

   Connect Salesforce or HubSpot under Settings → Integrations.

2. Add a sync configuration per object type

   Pick the object type — account, contact, subscription, product, invoice, payment or opportunity — and the sync type.

3. Choose a conflict strategy

   Required when the sync type is bidirectional.

4. Validate and enable

   Validate the configuration before enabling it, so a misconfigured mapping is caught before it moves any records.

Sync Types

Sync type	What it does
source	The external system leads. Changes are pulled into Alguna.
target	Alguna leads. Changes are pushed out to the external system.
bidirectional	Both sides can change records, and conflicts are resolved by the strategy below.

Conflict Strategies

Required for bidirectional configurations.

Strategy	Behaviour
none	Do not resolve. The record is marked failed and raised as a sync issue for a person to settle.
alguna	The Alguna record wins.
external	The external record wins.
latest	The most recently updated record wins.

none is the safest default while you are getting a configuration right: nothing is silently overwritten, and every clash lands in the sync issue list.

---

Object Types

A sync configuration is created per object type. Not every type is available on every integration — the dashboard only offers the ones the connected system supports.

Object type	Notes
account	Customers in Alguna, accounts or companies in the CRM
contact	Customer contacts
subscription	Alguna subscriptions
opportunity	CRM opportunities and deals
product	Product catalogue
invoice	Invoices
payment	Payments
credit_note	Tracked for sync issues raised by accounting integrations
tax_transaction	Tax transactions

---

Matching Records

Records are matched by external identifier. Store the CRM’s record ID on the Alguna customer as an alias, and the two sides stay linked even if names or emails change:

curl -X PATCH https://api.alguna.io/customers/cust_abc123 \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "aliases": ["001ABC123456789"]
  }'

aliases is a list of strings. Anywhere the API takes a customer you can pass an alias instead of the Alguna ID, which means you never have to store Alguna identifiers in your CRM.

For bulk account matching when you first connect a system, see Sync Accounts.

---

Sync Status and Issues

Each synced record carries a status:

Status	Meaning
pending	Queued, not yet sent
synced	Successfully synchronised
failed	The sync failed and raised an issue

When a sync fails, Alguna opens a sync issue so the failure is visible rather than silent. Issues are listed per integration in the dashboard.

Issue status	Meaning
open	Needs attention
retrying	Alguna is retrying automatically
paused	Retries are held, usually because the integration is unhealthy
resolved	Cleared, automatically or by a person

Issues are categorised by cause — authentication, rate limiting, provider outage, validation, configuration, or unknown. Authentication and rate-limit issues pause the integration rather than retrying into a wall; reconnect the integration or wait out the limit, then resume.

---

Checking Integration Health

The public API lists your connected integrations and their state:

curl https://api.alguna.io/integrations \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

Fetch one by ID with GET /integrations/{id}.

---

Best Practices

Pick one system of record

Per object type, decide which side leads and use source or target. Reach for bidirectional only where both sides genuinely edit.

Start with none

Let the first clashes surface as issues rather than silently resolving them, then choose a strategy once you have seen what actually collides.

Match on IDs, not names

Store the CRM record ID as a customer alias. Names and email addresses change.

Watch the issue list

A quiet integration with a growing issue list is not syncing.

---

Next Steps

Salesforce

Connect Salesforce and map its fields.

HubSpot

Connect HubSpot and map its fields.

Sync Accounts

Bring existing customers in when you first connect.

Automations

React to CRM changes with automation triggers and actions.