How to Specify an Integration So the Quotes Are Comparable and the Build Is Finishable
Most integration disputes are not about competence. They are about two parties who genuinely believed different things about what was being built, because the brief was three paragraphs and everything else was assumed. The specification is the cheapest risk control available on this kind of project, and almost nobody writes one.
This page sets out what belongs in an integration specification, in the order it should be written: the flow list, the ownership decisions, the field mapping table, the matching and duplicate rules, what happens to records that do not fit, the acceptance tests that define done, and the support and handover terms. Written properly it fits in a dozen pages and it makes three quotes genuinely comparable.
Realistic ROI
Four Reasons the Specification Pays for Itself
This is not documentation for its own sake. Each of these converts a future argument into a decision made while everybody is still calm.
It makes quotes comparable
Ask three suppliers to quote a paragraph and you get three different projects at three different prices, and no way to tell whether the cheapest is efficient or simply smaller. Ask them to quote the same specification and the differences resolve into rate, approach and support terms, which are things you can actually evaluate. The specification also exposes the supplier who has not read it, because their questions will be about things it already answers.
It forces the decisions that get deferred
Which system owns the customer record. Whether a partial refund reverses stock. What happens to an order with an address that will not validate. These are business decisions dressed as technical details, and if they are not made during specification they get made during the build, quietly, by whoever is writing the code that week. Occasionally they are made well. More often they surface months later as a behaviour nobody chose and nobody can explain.
It defines when the work is finished
Without acceptance criteria, done is a matter of opinion and the project acquires a long tail of small disagreements. With them, done is a list of tests that either pass or do not. This protects both sides: you get a clear basis for withholding sign off on something that genuinely does not work, and the supplier gets protection from an endlessly expanding definition of the same scope.
It survives the people who wrote it
Integrations outlive the staff and the suppliers who build them, and an undocumented one gets replaced rather than repaired because nobody dares touch what they cannot understand. The specification, kept current, is what makes a change a change rather than an archaeology exercise. It is also what you hand to a new supplier if the relationship ends, which is the difference between switching and rebuilding.
What Goes in the Specification
Seven sections in this order. Each one depends on the ones before it, which is why writing them out of sequence produces a document that contradicts itself.
The flow list
Every data flow as a single line: what moves, from which system to which, in which direction, how often, and roughly how many records a day and at peak. Ten to twenty lines covers most businesses. This list is what people should be quoting against, because counting flows rather than systems is the only way two proposals end up describing the same work. Write it before anything else and get the operational people to check it, because they will name flows the managers have forgotten about.
Ownership per data type
For every data type, name the one system that may create and change it, with everything else reading. Products, prices, stock, customers, orders, invoices, tracking. Where two systems genuinely both need to write, say which fields each may write and what happens when they conflict. This section is short, it takes the longest to agree, and skipping it is the single most reliable predictor of an integration that corrupts data slowly enough that nobody connects it to the integration.
The field mapping table
Source field, destination field, any transformation, whether it is required, and what happens when it is empty or invalid. Include the unglamorous ones: date formats, currency, units of measure, tax codes, truncation where a destination field is shorter, and any value list that has to be translated. This is the longest section and it is where the real work of specification lives. A supplier who cannot produce or check this table has not understood the job.
Matching and duplicate rules
How a record in one system is recognised as the same thing in another. Which keys are tried, in what order, what constitutes a confident match, and what happens to a partial one. State plainly that ambiguous records go to a queue rather than being merged automatically, because automatic merging of customer records is close to irreversible and is regretted about a year later. For Australian trade customers the ABN is usually the strongest key and it is frequently absent, so the fallback matters.
Exception handling
For every way a record can fail to process, say where it goes and who looks at it. A queue with the reason attached, an alert to a named role, a retry policy with a limit, and a rule for what the source system shows in the meantime. The default behaviour in unspecified integrations is a silent skip, which is the most damaging option available because the business keeps trusting numbers that are quietly incomplete.
Acceptance tests and non functionals
A list of scenarios that must work, written as inputs and expected outcomes, including the awkward ones: a duplicate, a refund, an oversized order, a record with a missing required field, a vendor outage mid transfer. Alongside them the non functional expectations: how fresh data must be, what volume must be supported at peak, what monitoring exists, how quickly a failure is noticed, and what happens during a vendor outage. These are the things that turn out to matter in production and are almost never written down.
Vague Brief Versus Specified Brief
| Task | Traditional | Specified | Notes |
|---|---|---|---|
| Describing the work | Connect our store to our ERP | Fourteen named flows with volumes | The single change that makes competing quotes comparable. |
| Who owns the customer record | Assumed by each side | Named, with fields listed | The most common source of slow data corruption when left unstated. |
| Date and currency handling | Discovered in testing | A row in the mapping table | Costs two minutes to specify and half a day to unpick later. |
| A customer who might be a duplicate | Merged or duplicated silently | Queued for a person | Automatic merging is close to irreversible. Say so explicitly in the document. |
| A record that will not process | Skipped, logged, unnoticed | Queued with reason and owner | Name the role who clears the queue, not just the fact that a queue exists. |
| Deciding it is finished | A matter of opinion | Acceptance tests pass | Protects both sides. Suppliers generally welcome this more than clients expect. |
| Peak trading volume | Never mentioned | A stated non functional | Test at three times current peak. November is not the time to find the ceiling. |
| If the relationship ends | Not discussed | Handover terms in writing | Specification, mappings, credentials and documentation. Agree it before you need it. |
How Specifications Go Wrong
It was written by the supplier who will build it
A specification written by the party being paid to deliver it will naturally reflect what they intend to build, which makes it a proposal rather than a requirement. It is fine and often efficient for a supplier to draft it, but somebody on your side has to read it critically, ask what is not in it, and be able to say no. Where the project is significant, having it written or reviewed independently is worth the cost, because the review typically surfaces the assumptions that would otherwise have become variations.
It describes systems rather than behaviour
A document full of platform names, technical architecture and interface diagrams can be entirely correct and still fail to specify anything, because it never says what should happen to a particular record in a particular situation. The test is whether an operations manager who does not know the technology can read it and confirm it describes their business. If they cannot, the parts they cannot check are the parts that will be built to somebody’s assumption.
It never says what happens when things fail
Specifications overwhelmingly describe the successful path, which is the part that needs the least specification because everybody agrees on it. The value is in the failure paths: a vendor outage, a timeout mid transfer, a duplicate, a record missing a required field, a retry, a rate limit. Write a short section per flow covering what happens in each case, who is told and what the source system shows in the meantime. It is the most useful two pages in the document.
It became too large to be read
A hundred page requirements document for a five flow integration is a way of avoiding decisions rather than making them, and it will not be read by the people who need to check it. Aim for the shortest document that answers every question a builder would otherwise have to guess at, which for most integrations is ten to fifteen pages plus the mapping table. Length is not a proxy for rigour, and a specification nobody finishes reading provides none of the protection it was written for.
It was never updated after go live
An integration changes, and a specification that describes the original build becomes actively misleading within a year. Make updating it part of every change, keep it somewhere your team controls rather than in a supplier’s system, and review it annually against actual behaviour. An out of date specification is worse than none, because people trust it, and the trust is misplaced precisely on the parts that changed.
Personal information was not considered
If the flows carry customer names, addresses, phone numbers, health information or payment references, the specification should say which systems hold what, where each stores its data, how long records are retained, who and what has access, and how an access, correction or deletion request would be honoured across every system in the chain. These are obligations under the Privacy Act 1988 and the Australian Privacy Principles regardless of whether anyone wrote them down, and they are dramatically easier to design in than to retrofit.
How Yes AI Handles Specification
We write it before we quote, every time
Nothing is built here against a paragraph. We produce the flow list, ownership decisions, mapping table, matching rules, exception handling and acceptance tests, and you approve them before any build starts. It is the reason our fixed prices stay fixed.
Independent scoping if we are not building it
We will write or review a specification for work another supplier will deliver, and we will do it without steering the outcome toward ourselves. If the review concludes their approach is sound, that is the finding you get. Businesses that use this typically find it pays for itself in the quote comparison alone.
Written so your operations people can check it
Plain English, business behaviour rather than architecture, with the mapping table as an attachment rather than the body. The test we apply is whether a finance manager or a warehouse supervisor can read it and confirm it matches how their part of the business actually works.
Yours to keep, and kept current
The specification, the mappings and the system map are deliverables you own from the outset, updated with every change. If you ever move to another supplier, you take a working document with you rather than starting the archaeology again.
From an Idea to a Document Suppliers Can Quote
Five steps. For a typical five to fifteen flow integration this is two to three weeks including the interviews.
Interview the people doing the work
Not the managers describing the process, the people executing it. They know about the spreadsheet, the shared mailbox, the exception nobody documented and the workaround that has been in place for two years. That is where the missing flows come from.
Write the flow list and agree ownership
Every flow on one line with volumes and frequency, then one owner per data type with any shared write fields called out explicitly. Circulated and signed off before anything more detailed is written, because everything else depends on it.
Build the mapping table with real data in front of you
Field by field, with actual records open rather than from memory or documentation. This is where the surprises live: the free text field holding three different meanings, the identifier that is not unique, the historical records that predate the current rules.
Specify matching, exceptions and non functionals
Matching keys and their order, what a partial match does, where failures go and who clears them, retry policy, freshness expectations, peak volume, monitoring and what happens during a vendor outage. Short, specific, and covering the failure paths rather than the happy one.
Write the acceptance tests, then go to market
Scenarios as inputs and expected outcomes, including the awkward cases, plus support terms and handover conditions. Then send the same document to every supplier and compare what comes back on identical scope.
Related Reading
SaaS Integration Explained
The six patterns and the decisions behind them.
What Integration Costs
Pricing models and comparing quotes on equal terms.
Questions to Ask a Vendor
Checking integration capability before you buy software.
Failed Integration Rescue
What happens when none of this was written down.
Monitoring and Support
The non functional requirements that matter most in production.
Custom API Integration
Building against a specification once it exists.
FAQ
Get It Written Down Before Anyone Quotes
Book a scoping engagement. We interview the people doing the work, produce the flow list, mapping table, rules and acceptance tests, and hand you a document any supplier can quote against. It is yours whoever builds it.
All discussions held in confidence. Australian-based consultants.