External Sync

External Sync is the configuration layer for keeping records in step between Alguna and a connected CRM — Salesforce or HubSpot. For each object type you choose which system leads, whether changes flow one way or both, and how a conflict is settled; failed syncs surface as issues rather than disappearing. Use it once a CRM is connected and before you rely on CRM data in Alguna or Alguna data in the CRM. The objects being synced are described in How Alguna works. Sync is configured in the dashboard under Settings → Connections → Integrations. There is no public API for sync configuration; the public API exposes your connected integrations read-only through List integrations and Get an integration.

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.

Connect the integration

Connect Salesforce or HubSpot under Settings → Connections → Integrations.

Add a sync configuration per object type

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

Choose a conflict strategy

Required when the sync type is bidirectional.

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

What an account sync carries

Searching your CRM by company name — when creating a customer in Alguna, or when Alguna matches an incoming record — is how the two sides are connected. Once matched, an account sync carries a fixed set of fields in either direction:

Field	Notes
Name	The company or account name
External ID	The CRM record ID, stored as an alias on the Alguna customer
Contacts	Names and email addresses
Currency	The account’s billing currency
Billing address	Normalised to Alguna’s address shape
Website	Reduced to a domain; an unparseable value is dropped rather than synced
Link back to the CRM record	So you can jump from the customer to the source record

The CRM record’s owner is not one of them. Reassigning a company in Salesforce or HubSpot — a new Account Executive, a territory change — changes nothing in Alguna, and Alguna has no owner or Account Executive field of its own to change back. Ownership stays a CRM concept. If your team needs to see who owns an account from inside Alguna, follow the link back to the CRM record, where the current owner is always right.

Tax settings, legal entity and parent customer are likewise not synced; they are set on the Alguna side. See Manage customers.

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"]
  }'

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

response = requests.patch(
    "https://api.alguna.io/customers/cust_abc123",
    headers=HEADERS,
    json={"aliases": ["001ABC123456789"]},
    timeout=10,
)
response.raise_for_status()

await alguna.customers.update("cust_abc123", { 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. To go the other way, Look up a customer ID by alias resolves a CRM record ID to the Alguna customer. Reference: Update a customer. 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 under Settings → Connections → Sync issues, per integration. Accounting integrations (QuickBooks, Xero, NetSuite) raise issues in the same list.

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"

response = requests.get("https://api.alguna.io/integrations", headers=HEADERS, timeout=10)
response.raise_for_status()
integrations = response.json()

const integrations = await alguna.integrations.list();

Fetch one by ID with Get an integration.

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.

Integrations

Accounting

CRMs

Data Ingestion

Payments

Sales Tax

Invoicing Alternatives

Supported Systems

How It Works

Sync Types

Conflict Strategies

Object Types

What an account sync carries

Matching Records

Sync Status and Issues

Checking Integration Health

Best Practices

Pick one system of record

Start with `none`

Match on IDs, not names

Watch the issue list

Next Steps

Salesforce

HubSpot

Sync Accounts

Automations

​Supported Systems

​How It Works

​Sync Types

​Conflict Strategies

​Object Types

​What an account sync carries

​Matching Records

​Sync Status and Issues

​Checking Integration Health

​Best Practices

Pick one system of record

Start with none

Match on IDs, not names

Watch the issue list

​Next Steps

Salesforce

HubSpot

Sync Accounts

Automations

Supported Systems

How It Works

Sync Types

Conflict Strategies

Object Types

What an account sync carries

Matching Records

Sync Status and Issues

Checking Integration Health

Best Practices

Start with `none`

Next Steps