Connecting two systems is easy to start and easy to get wrong in ways that surface months later. The initial API call is rarely the hard part. What determines whether an integration is still trustworthy in a year is a set of decisions usually made implicitly, or not at all.
These are the eleven we settle in writing before building anything.
1. Which system owns each field?
For every field that crosses the boundary, one system is the source of truth. If both can edit it, you do not have an integration — you have a conflict generator. Write the ownership down field by field. This single decision prevents more problems than any other.
2. What happens when both change at once?
Even with clear ownership, simultaneous edits happen. Decide the rule now: last write wins, source system always wins, or flag for human review. Each is defensible; having no rule is not. Silent overwrites are the integration failure users notice last and trust least.
3. Which direction does data flow?
One-way sync is dramatically simpler than two-way, and is sufficient far more often than teams assume. Ask what breaks if the reverse direction simply does not exist. Frequently the answer is "nothing", and you have just halved the complexity and most of the failure modes.
4. How are records matched?
Two systems need a shared identifier. Email addresses are the usual default and a poor one — they change, they are shared between people, and they are entered inconsistently. Decide the match key, decide what happens when no match is found, and decide what happens when two match. That third case is the one that gets skipped and later causes the merge nobody can undo.
5. What is the volume, and what are the rate limits?
Check the API rate limits of both systems against your realistic peak, not your average. A sync that works fine daily can fail on the one day a month when a bulk import runs. Design for the peak, and make the integration degrade by queueing rather than by dropping.
6. Is a failed call safe to retry?
Network calls fail. The question is whether running the same operation twice creates one record or two. Make writes idempotent — usually with a client-generated key the destination can deduplicate on — so a retry is always safe. Without this, your recovery procedure creates the next problem.
7. Who finds out when it breaks, and how?
The most damaging integration failure is the quiet one: it stops syncing, nobody notices for six weeks, and by then two systems have diverged badly enough that reconciliation is its own project. Failures need to alert a named person through a channel they actually read. An error log nobody opens is not monitoring.
8. What happens to the historical data?
Turning on a sync going forward is one project. Backfilling what already exists is another, with its own duplicate risk and its own runtime. Decide whether you are backfilling, from what date, and how you will verify the result — before the switch is flipped, not after someone asks where the old records went.
9. How will you prove it is still correct?
Build a reconciliation check: a scheduled comparison of record counts and a few key fields across both systems, reporting differences. This is perhaps twenty lines of work, and it is the difference between believing the integration works and knowing it does. Run it weekly.
10. What is the rollback plan?
If the integration writes bad data at scale, how do you undo it? A run log with enough detail to identify and reverse affected records is the minimum. For higher-risk syncs, a dry-run mode that reports what would change without changing it is worth the extra effort before every significant deployment.
11. Who maintains it when the vendor changes the API?
APIs get versioned and endpoints get deprecated, typically with a notice period that lands in an inbox nobody watches. Someone needs to be tracking vendor changelogs for both systems. If that person does not exist internally, it belongs in a managed engagement — otherwise the integration has a quiet expiry date nobody has scheduled.
The pattern behind the list
Nine of these eleven questions are about failure rather than function. That ratio is not accidental. Integrations spend a very small proportion of their life being built and the overwhelming majority of it running unattended, and the difference between a good one and a bad one is almost entirely in what happens when something goes wrong.
A build that answers all eleven takes perhaps twenty per cent longer than one that answers none. It also tends to still be working, and still be trusted, a year later.
We work through this list on every integration engagement before writing code. Tell us which two systems disagree and we will tell you what connecting them properly involves.