Integrating a CRM without breaking it

Decide the source of truth before writing any code

Every CRM integration starts with the same unanswered question: when the CRM and the other system disagree about a customer's address, which one is right? Until that is settled, no amount of engineering produces a trustworthy result. It is a business decision and it needs a named owner, not a technical default.

Do it field by field for anything contested. The CRM usually owns contact and opportunity data. Accounting usually owns invoices, credit status and payment history. The operational system usually owns stock, delivery and service records. Write that table down and get it agreed, because it is the specification the integration is built from.

Where two systems genuinely both need to write the same field, you need a rule: last write wins, one side is authoritative and the other is advisory, or conflicts are queued for a human. All three are workable. Having no rule is what produces data nobody trusts.

Match the record shapes honestly

CRMs model the world in leads, accounts, contacts and opportunities. Your operational system models it in customers, sites, orders and jobs. These do not map cleanly, and the mismatch is where integrations quietly go wrong: one account with three delivery sites, one contact working for two customers, an opportunity that becomes four separate orders.

Work through the awkward cases with someone who knows the business, not just the systems. Ask what happens when a customer is acquired, when a site changes hands, when a contact leaves. Those cases will occur within the first year and they decide the shape of the mapping.

Then decide what is not integrated. A deliberately narrow integration that handles four record types correctly is worth far more than a broad one that half-handles twelve.

The mechanics that stop it breaking

Make every operation idempotent. If the same event arrives twice, and it will, the result must be the same as if it arrived once. That normally means an external identifier stored on both sides and used for matching, rather than matching on name or email.

Assume the other end will be unavailable. Retries with backoff, a dead-letter store for messages that cannot be processed, and a way to replay them after a fix. Without a dead-letter store, a bad afternoon means permanently lost records.

Respect API limits from the start. Most CRMs enforce request quotas, and an integration that works fine in testing can exhaust a daily allowance in an hour during a bulk import. Batch where the API supports it, and throttle deliberately rather than discovering the ceiling in production.

Log the business event, not just the HTTP call. When someone asks why a customer did not sync on Tuesday, you want to answer from a readable log, not by reading raw payloads.

Give the business a way to see it working

Integrations fail silently by default, and silence gets interpreted as success right up to the point where somebody notices a month of missing records. The fix is a screen, in business language, showing what synced, what failed and why, with a button to retry.

Whoever owns the data process should be able to read that screen without asking a developer. The moment they can, integration problems become operational problems with a known owner, which is exactly what you want.

Alerts should reach a human channel that is actually watched, with a threshold that keeps them meaningful. An alert that fires daily gets filtered within a fortnight.

Roll out in parallel, not as a switch

Run the integration alongside the manual process for a period. Compare the two, reconcile the differences, and let the people doing the manual work confirm the automation is right before they stop. It feels slow and it is the reason integrations get trusted.

Start with one direction and the highest-volume record type. That is where the saved effort is most visible, and it teaches you the failure modes on the flow you understand best.

Finally, write the runbook while the knowledge is fresh: what each failure means, who to contact at the vendor, how to replay a batch, and what to check first. Integrations outlive the people who build them, and the runbook is what makes that survivable.