Map the business event and record ownership
Describe the event that should trigger the integration: an approved quote, paid order, changed contact or completed booking. Identify the source of truth for each important field. If both systems allow edits, agree which changes win and how conflicts are reviewed. Two databases storing the same customer name do not automatically represent the same customer.
Write down identifiers and relationships before designing screens. Email addresses and names can change or be shared, so they are not always suitable permanent keys.
Confirm the actual interface
Obtain current API documentation, access permissions, test credentials and representative sample records through the appropriate secure process. Establish available operations, pagination, limits, versioning and the provider’s test environment. Check whether webhooks exist and how authenticity can be verified. Where no API is available, assess supported exports or imports rather than assuming direct database access is permitted.
Do not place secrets in public JavaScript or a downloadable configuration file. Access and credentials should follow the system owner’s security requirements.
Specify normal and exceptional behaviour
| Situation | Decision needed |
|---|---|
| The same event arrives twice | How to recognise an already processed operation |
| The destination is unavailable | Retry, queue, alert and manual recovery rules |
| A record is incomplete | Validation, rejection or human review |
| A value changes later | Update ownership and reconciliation |
For an illustrative order-to-CRM connection, a retry should not create a second sale merely because the first acknowledgement was lost. Make that behaviour an acceptance case.
Design observability without exposing data
Give operations staff a way to see completed, waiting and failed work. Record useful correlation identifiers, timestamps and status transitions, while avoiding unnecessary personal information or secrets in logs. Decide who receives an alert and what action they can take. A technical error message is not an operating procedure.
Reconcile business totals or record counts where appropriate. A job that runs without an exception can still omit records if pagination, time ranges or permissions are wrong.
Agree privacy and operational responsibilities
Identify personal or sensitive data, the reason it moves, the recipients and required retention. Involve the relevant data-protection owner in those decisions. Define who supports each side of the connection, how provider changes are detected and who pays for ongoing platform usage. Keep access in organisation-owned accounts and ensure the handover includes configuration, deployment and recovery instructions.
These arrangements should be visible in the scope rather than left until the first production failure.
Prove the workflow with representative tests
Test ordinary records, duplicate events, missing fields, provider outages, changed permissions and recovery. Use an agreed non-production environment or controlled production procedure. Validate what users see in both systems, not only the API response. Start with a narrow useful workflow, document the mapping and observe it in operation before expanding. We aim to remove repeated work without creating an invisible dependency that staff cannot understand or support.
Common questions
Can every system be integrated?
No. Feasibility depends on supported interfaces, access, data quality, vendor constraints and the process itself. Some steps may need to remain manual.
Is a successful API response enough to prove the integration works?
No. Validate the resulting business record, duplicate handling, failures and reconciliation across the complete workflow.