Scope an API integration before promising an automated workflow
Define systems, records, ownership, exceptions, access, and acceptance checks before connecting two business applications.
An integration brief needs to describe more than two product logos joined by an arrow. The work depends on which records move, who owns them, how changes are detected, and what happens when either side refuses an update. Resolve those questions before promising that a process will run without supervision.
Identify the actual record and its owner
Choose one concrete transaction to map. For example, a qualified enquiry might create a customer record and a follow-up task. List the fields required by the destination and where each value originates. Decide how an existing customer is recognised so a repeated enquiry does not automatically become a duplicate organisation.
Name the authoritative system for facts that can change on both sides. If someone corrects a company name in the CRM, should the source form, a spreadsheet, or another application receive that correction? A one-way connection can be easier to understand than synchronising everything, provided its limitations are explicit.
Inspect access and failure conditions early
Confirm that the relevant accounts can access the needed operations, and review the provider’s current documentation for limitations before estimating implementation. Use a safe sample to test the complete transaction. A list endpoint working successfully does not establish that the account can create, update, or search every required record.
Define what the operator sees when the destination is unavailable, a field is rejected, or a response arrives too late to be certain of the result. Retrying should not blindly create another record. Agree a method for reconciling uncertain outcomes and an owner who can resolve items that need human judgement.
Accept the connection through realistic examples
Prepare a small set of representative records: a normal enquiry, a known customer, missing information, and a changed or withdrawn request. Review the resulting records with the business user who will depend on them. Check field meaning and ownership as well as whether the technical request returned successfully.
Document how to pause the connection, inspect a failure, update access, and resume safely. Make external service costs and ongoing account responsibilities visible in the scope. A successful pilot should leave the team with an understandable operating process, not an opaque connection that only its original developer can diagnose.
Practical checklist
- Map one transaction and its destination fields.
- Choose the source of truth for shared information.
- Verify required account capabilities with a safe sample.
- Define duplicate detection and uncertain-outcome recovery.
- Assign ownership for credentials, exceptions, and ongoing costs.
Example: enquiry to CRM
A hypothetical consultancy connects a project enquiry to its CRM. The agreed first phase searches for a matching contact, records the enquiry, and creates a review task. It does not automatically send a sales email. Missing company information enters an exception queue so a person can decide how to proceed.
Common questions
Is a two-way integration always better?
No. Two-way updates create additional ownership and conflict decisions. Choose them only when the business task requires both systems to change the same information.
What is the most useful first integration test?
Run a representative transaction through the complete path with safe data, then inspect the destination with its intended user. This exposes field and account assumptions early.
Start with your actual workflow.
Turn the useful parts of this guide into a focused project brief.
Shape your project