CRM integration that keeps one system right and the rest in step

What CRM integration actually is

Most CRMs die the same way. Three systems write to the same field, nobody agreed who should, and after a few months the sales team stops trusting the record and keeps the real state in a spreadsheet. At that point the CRM is a place data goes to be forgotten, and no amount of new tooling fixes it, because the problem is not connectivity. It is that nothing decides what is true.

So the first deliverable is never code. It is a field-level map naming one writer per field, with the exceptions listed and a survivorship rule attached to each. Once that document exists, the engineering is mostly mechanical.

Who it is for, and who it is not for

This is for companies where the CRM is one of several systems holding customer state, and where the same fact is currently entered by hand in more than one place. If your CRM is the only system and a native connector covers your two other tools, buy the connector.

Three things that have to exist before the build

1. An agreed natural key per object. Usually a lowercased email for people and a normalised domain for companies, with the known exceptions written down: shared inboxes, subsidiaries, personal addresses on business accounts.
2. API access at a tier with enough call allowance, plus somebody who can raise it. Integrations that work in testing and fail in production are usually hitting a ceiling nobody checked.
3. A named owner for the CRM schema. If anyone in the company can add a required field or a validation rule on a Tuesday afternoon, the integration will break on a Tuesday afternoon.

Who should not buy this

• Teams whose real problem is CRM adoption. If sales will not update the record, syncing more data into it changes nothing.
• Anyone hoping the integration will settle an argument about which department owns the customer. It will surface the argument, not resolve it.
• Companies mid-way through a data migration. Finish the migration, then integrate the result.
• Teams who need reporting rather than sync. That is a warehouse job, and building it as an integration makes it slower and more fragile.

What we actually build

Six components. Most of this build contains no model at all, which is worth saying plainly on a page hosted by an AI automation studio.

The field custody manifest

A version-controlled file listing every object and field in scope with its writer, its readers, its transform, its allowed values and its conflict rule. It is readable by an operations lead, it is the artefact you argue about, and it is what the sync compiles from. When it changes, the change goes through review like any other code.

The identity and dedupe layer

Normalisation and matching before anything writes. Emails lowercased and trimmed, domains stripped of subdomains and free-mail providers flagged, company names normalised for matching but never overwritten. Deterministic rules first. Fuzzy matching only with a confidence threshold and a review queue, because an automatic merge of two real customers is one of the few integration errors that is genuinely hard to undo.

The sync workers

One worker per direction, driven by webhooks where the platform offers them and by a polled watermark where it does not. Each write is an upsert on the natural key, carries an idempotency key, and is tagged with its source so that the echo event coming back does not start a loop. Batched where the API rewards batching, serialised per record so two updates to the same contact cannot race.

The conflict log and the review queue

Every time a survivorship rule fires, the system records both values, the rule applied, the winner and the source events. Anything the rules cannot settle goes to a queue a human clears. Teams often discover their real ownership policy by reading a fortnight of that log, which is a better outcome than the workshop that was supposed to produce it.

The reconciliation job

Nightly, it walks both systems and compares the fields in scope. Drift opens a ticket with the record ids attached. This is the component that catches the failure everyone misses: a sync that stopped days ago and produced no errors, because zero events processed looks identical to a quiet weekend.

The backfill, run separately

History moves through its own path, with its own rate limit budget, its own batch size and a resumable cursor. Running a backfill through the live path is how teams consume a day's API allowance by lunchtime.

How it works technically

Events in, identity resolved, custody applied, write attempted, result verified, drift reconciled. The parts that break in production are identity, loops and rate limits, in that order.

Triggers, watermarks and the ordering problem

Webhooks are cheaper and faster, and they are not reliable enough to be the only path: they can be delayed, duplicated or dropped. Every webhook-driven sync also needs a polled sweep on a watermark to catch what was missed. Advance the watermark only after the write has been confirmed, never before, because the crash between those two lines is the classic silent data loss. Ordering matters too, since two updates to the same record arriving out of order will leave the older value in place. Serialise per record key rather than globally. The trade-offs are covered in webhooks vs polling.

Writes, echoes and loops

A two-way sync without loop suppression is a machine for generating infinite updates. System A writes, the webhook fires, system B writes back, A hears its own change and writes again. Three defences, and you want all three: tag every write with its source and ignore inbound events carrying your own tag, compare the new value with the current value and skip no-op writes, and cap updates per record per hour so a loop trips a circuit breaker instead of running all night.

Rate limits and the CRM's own automation

CRM APIs meter calls, and the allowance depends on your product tier, so read your own limits page rather than any blog. Budget calls per record before you build: a lookup, a dedupe check and a write is three calls, and a fifty-thousand record backfill is a hundred and fifty thousand of them. A write into a CRM can also fire the CRM's own workflows. A backfill touching a field watched by an email automation is how a company sends a very large number of unintended emails in one afternoon.

# contact.custody.yaml
# One writer per field. Everything else reads. Direction is per field, never per object.
object: contact
natural_key: email_lower          # the dedupe key, deliberately not the CRM record id

sync:
  trigger: webhook                # poll only where webhooks do not exist
  poll_fallback_minutes: 15
  batch_max: 200
  loop_suppression: source_tag    # ignore an inbound event this system caused
  idempotency_key: "sha256(object + natural_key + field + new_value + source_event_id)"

fields:
  email:
    writer: product_db
    readers: [crm, billing, support]
    transform: lower_trim
    pii: true
  lifecycle_stage:
    writer: crm
    readers: [product_db, marketing]
    allowed_values: [lead, mql, sql, customer, churned]
    on_invalid: reject_and_log    # never coerce a value you do not recognise
  plan_tier:
    writer: billing
    readers: [crm, support]
  last_active_at:
    writer: product_db
    readers: [crm]
    write_if: "new_value > current_value"   # monotonic, never moves backwards
  owner_id:
    writer: crm
    readers: [support]
    survivorship: newest_non_empty
    on_conflict: log_both_values

deletes:
  strategy: tombstone             # propagate a delete, never a silent no-op
  merges: follow_surviving_id     # CRM merges must repoint foreign keys

dead_letter:
  queue: crm_sync_dlq
  retry: { attempts: 5, backoff: exponential, jitter: true }
  alert_after: 10

reconciliation:
  schedule: "daily 02:00"
  compare: [email, lifecycle_stage, plan_tier, owner_id]
  tolerance: 0
  on_drift: open_ticket

Two lines in that file are worth more than the rest combined. The write_if guard on last_active_at makes the field monotonic, so an out-of-order event cannot move a timestamp backwards. The on_invalid: reject_and_log on the picklist means an unrecognised value is refused loudly rather than coerced into the nearest match, which is how bad data enters a CRM and stays there.

Terms used on this page

Upsert

A write that creates the record when the key matches nothing and updates it when it does. Upserts are only safe against a natural key. Upserting on a system-specific id creates the same person twice.

Natural key

The field or combination that identifies a real entity across systems, such as a lowercased email or a normalised company domain. Weak natural keys are the direct cause of duplicate records.

Survivorship rule

The stated rule deciding which value wins when two systems have written the same field. Common rules are newest timestamp wins, non-empty wins, and human edit beats machine write.

Watermark

The stored timestamp or cursor recording how far a sync has read, so the next run resumes instead of rescanning. A watermark advanced before the write is confirmed causes silent data loss.

Tombstone

A record marking that something was deleted, kept so the deletion can propagate to other systems. Without tombstones, deletes vanish and a deleted contact reappears on the next sync.

Field custody, the rule that prevents most sync disasters

Almost every integration incident we have been called into traces back to a field with two writers and no stated rule. The model below is not sophisticated. It is just written down, which is the part everybody skips.

The build process stage by stage

Six stages. The first is a data audit, and it is the stage clients most often want to skip and most often thank us for afterwards.

1. Field-level data auditWeek 1

   Every object and field in scope profiled: fill rate, distinct values, duplicate rate on the proposed natural key, and which system last wrote each field. This is where you find out that a third of your company records share four generic domains.

2. The custody manifestWeek 1 to 2

   The map gets written and argued about with the people who own each system. Contested fields are the useful part of the meeting. The output is a file, in the repository, with a name attached to every decision.

3. Identity and dedupeWeek 2 to 4

   Normalisation, matching rules, a duplicate report and, where needed, a merge plan run by humans with the machine proposing. Nothing syncs until the duplicate rate on the natural key is understood and accepted.

4. One field, end to endWeek 3 to 5

   A single low-risk field synced through the full path: trigger, worker, idempotent write, verification, conflict log, reconciliation. Every architectural mistake shows up here, cheaply, on a field nobody would miss.

5. Widen the scope, then backfillWeek 5 to 8

   Remaining fields added in batches, each with its custody entry. The backfill runs last, on its own path, in off-peak windows, with the CRM's own workflow automations reviewed and paused where a bulk write would trigger them.

6. Reconciliation, alerting and handoverWeek 8 to 10

   The nightly comparison goes live, the dead letter queue gets an owner, and heartbeat alerts fire when a sync produces no events for longer than it should. Then documentation and a walkthrough with the person who will own it.

What you get at handover

The manifest, the workers, the queues and the reconciliation all run in your infrastructure under your credentials. The test of a real handover is whether your team can add a new field to the sync without calling us.

We also hand over the document nobody asks for: what the integration deliberately does not do, and why. Six months later that page prevents an argument about whether something was forgotten or decided.

Where CRM integrations go wrong

Six failure modes. Every one of them is recoverable if you find it in week one and unpleasant if you find it in month six.

The ping-pong loop

Two-way sync with no loop suppression. A writes, B hears it and writes back, A hears its own echo. The record updates forever, the audit trail fills with machine edits, and the API allowance disappears. Source tagging, no-op comparison and a per-record update ceiling are the three defences.

Duplicate explosion from a weak key

Syncing on a system-specific record id, or on an email address for a population that shares inboxes, produces a second copy of everyone. The copies then sync onward. Profile the duplicate rate on your proposed natural key before writing a line of sync code.

The backfill that eats the day's quota

History pushed through the live path consumes the API allowance, live events queue up behind it, and by afternoon the sync is hours behind with no error to show for it. Separate path, separate budget, off-peak window, resumable cursor.

Deletes and merges that go nowhere

Most integrations sync creates and updates and quietly ignore deletions and merges. CRM users merge records constantly. When they do, the other system still points at an id that no longer exists, and the next sync recreates the record you just merged away. Handle tombstones and surviving ids explicitly.

Writes that succeed and change nothing

The API returns 200. The record is unchanged, because a validation rule rejected the field, or field-level permissions on the integration user exclude it, or a workflow overwrote your value a second later. Verify after write on a sample, and reconcile nightly, or you will trust a green log that describes nothing.

Personal data spreading faster than the policy

Each new destination is another place a deletion request has to reach. Mark personal fields in the manifest, keep the list of destinations current, and make deletion a first-class sync operation rather than a manual sweep somebody performs under time pressure. More detail in personal data in AI pipelines.

What it costs to run once live

Three real cost lines, and a fourth that is usually zero. Most CRM integration work is deterministic, so there may be no model in the running system at all.

The number worth estimating before you commit is API calls, because that is the ceiling you hit first. Count calls per record honestly: a lookup, a dedupe check and a write is three, and any enrichment adds more. Put your own allowance in the box below, taken from your CRM's current limits documentation for your tier rather than from an article.

Run it with backfill volumes too. A one-off load of half a million historical records at three calls each is one and a half million calls, which is why the backfill gets its own path and its own window. The connective layer underneath is shared with systems integration, so if you are building several of these it is worth building the queue once.

How to tell whether you need this

The signal is not the number of tools. It is whether the same fact exists in two systems with no stated rule about which one is right, and whether anybody has stopped trusting the CRM because of it.

If you ticked one or two, the fix is probably a written ownership map and an afternoon of configuration, not a build. Write the map anyway. It costs nothing and it is the deliverable that makes the eventual build cheap. Teams whose next step is pipeline hygiene rather than sync should look at sales pipeline automation instead.

How to start

Read access to both systems and one week is enough to tell you whether this is a mapping problem, a duplicate problem or an adoption problem. The three have very different price tags and only one of them is an integration.

1. Send the list of systems, the objects that exist in more than one, and the fields people currently re-key by hand.
2. We profile the data, propose the natural keys, measure the duplicate rate and draft the custody manifest for the contested fields.
3. You get a scoped build with stages and a cost, or a recommendation to configure the connector you already own and stop there.
4. If it proceeds, one low-risk field goes end to end first, so the architecture is proved on something nobody would miss.

The mechanics that keep this reliable overnight are covered in idempotency in automation, which is worth reading before you evaluate any vendor in this category.