Integration projects often start with a deceptively simple sentence: “When this happens in system A, create or update that in system B.” The implementation becomes fragile when the team cannot answer the questions hidden inside that sentence.
Which record is authoritative? Which identifier links the same customer across platforms? What if the destination rejects the update? What if the source changes after the message is sent? What if the same event arrives twice?
Document the business contract before you build the technical connection.
Define the business purpose
Start by recording why the integration exists and which business outcome depends on it. “Sync CRM to finance” is too vague. “Create an approved customer account in finance after commercial onboarding is complete” defines a trigger, an intended result and a boundary.
This purpose becomes the test for future changes. If a requested field or automation does not support the agreed outcome, it may not belong in the integration.
Record ownership and authoritative data
For every important field, identify which system is authoritative and whether the destination can edit it. Bidirectional synchronisation without explicit ownership is one of the fastest ways to create conflicting data.
Document the stable identifiers used to match records. Names and email addresses may change or duplicate. Integration logic should rely on identifiers that are designed to remain stable enough for the business process.
Describe the event and state model
Record what initiates the integration: a new record, a status change, a scheduled batch, an approved transaction or another business event. Define the states in which an action is allowed and the conditions that should stop it.
This reduces accidental side effects. A record being edited is not always equivalent to a business event being completed.
Design failure and reconciliation before launch
Every important integration should document retry behaviour, error ownership, duplicate prevention, reconciliation and safe recovery. The destination may be temporarily unavailable, credentials can expire, validation rules can change and network calls can return uncertain outcomes.
Connect this design to explicit failure paths. A technically successful API call is not enough if the resulting business state cannot be confirmed.
Document security and operational dependencies
Record authentication method, required permissions, secrets ownership, data sensitivity, rate limits and external dependencies. Avoid documenting secrets themselves in general architecture records; document where they are controlled and who owns rotation.
Also capture platform versions, API endpoints, webhook subscriptions, scheduled jobs and any middleware involved. These dependencies become essential when a vendor changes behaviour or a new team inherits the integration.
A minimum integration record
- Business purpose and owner.
- Source and destination systems.
- Authoritative entities and fields.
- Stable identifiers and matching rules.
- Trigger or schedule.
- Transformation and validation rules.
- Duplicate-prevention strategy.
- Failure, retry and reconciliation behaviour.
- Security and permission model.
- Monitoring and escalation owner.
- Known limits and dependencies.
- Change and testing procedure.
What better looks like
A maintainable integration is understandable without reconstructing it from code, workflow screens and tribal memory. Documentation gives operators a map of the business contract, while the implementation remains free to change underneath that contract as platforms evolve.