For the person who has to brief a supplier and then hold them to it

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.

Get an Integration Specified (03) 9003 0111

Realistic ROI

2 to 5 times

Spread between quotes for a vague brief

Which usually means the suppliers priced different things, not the same thing

10 to 15 pages

Is enough for most integrations

This is not an enterprise requirements exercise, it is a working document

Per field

Is the level a mapping table works at

Anything vaguer leaves the interesting decisions to be made during the build

Before the build

Is when exceptions cost minutes to decide

Afterwards they cost a correction project and a difficult conversation

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.

One line each

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.

One owner each

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.

Row per field

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.

Explicit keys

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.

Named destination

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.

Pass or fail

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.

FAQ

How long should an integration specification be?

For most business integrations, ten to fifteen pages plus a field mapping table as an attachment. The flow list is a page, ownership is a page, matching and exception rules are two or three, acceptance tests are two or three, and support and handover terms are one. If it is running past thirty pages, check whether it has started describing architecture rather than behaviour, or whether the scope has quietly become a programme that should be split into stages. Length is not rigour, and a document that is too long to be read carefully provides none of the protection it was written to give.

Who should write it, us or the supplier?

Either, provided the other side reviews it critically. A supplier drafting it is efficient because they know what questions to ask, but the result naturally reflects what they intend to build, so somebody on your side has to read it looking for what is missing rather than checking what is present. If nobody internally has the time or the background to do that, an independent scoping engagement is worth considering. The awkward middle ground, where the supplier writes it and the client signs without genuinely reading, produces documents that provide the appearance of protection and none of the substance.

What is the single most important section?

Data ownership, by a clear margin. Naming one system as the owner of each data type, with everything else reading, prevents the failure mode that is hardest to detect and most expensive to fix: two systems both allowed to write the same field, overwriting each other slowly, with the corruption spreading over months before anybody links it to the integration. It is also the shortest section and the one that takes longest to agree, because it is a business decision about authority rather than a technical one, and it often surfaces a disagreement that predates the integration entirely.

Do we really need acceptance tests written in advance?

Yes, and they are the section that most often prevents an unpleasant ending. Without them, done becomes a matter of opinion and projects acquire a long tail of small disputes about whether a behaviour was in scope. Written as inputs and expected outcomes, and including the awkward cases such as a duplicate, a refund and a mid transfer failure, they give you a clear basis for withholding sign off on something that genuinely does not work and give the supplier protection from scope that keeps expanding under the same fixed price. Most competent suppliers welcome them.

What if we do not know our own requirements well enough to write this?

That is the normal starting position and it is not a barrier. The requirements are mostly discovered by watching the current process rather than by deciding anything new, which is why the first step is interviewing the people doing the work rather than the people describing it. They will name the spreadsheet, the shared mailbox and the two year old workaround, and those are usually the flows that matter. A short scoping engagement of two to three weeks typically produces the document, and the discovery itself is often more valuable than the specification, because businesses regularly find processes nobody knew were still running.

How do we keep the specification useful after go live?

Make updating it part of every change rather than a separate task somebody will get to. Keep it somewhere your organisation controls rather than in a supplier’s system, so it does not leave with the relationship. Review it annually against what the integration actually does, because drift is normal and an out of date specification is worse than none since people trust it. And when a supplier proposes a change, ask for the specification update as part of the deliverable rather than as an optional extra.

Should the specification cover privacy and security?

Yes, at least briefly, and it is cheap to do at this stage. Note which systems hold personal information, where each one stores its data, how long records are kept, what accounts and services have access, and how you would honour an access, correction or deletion request across every system in the chain. Under the Privacy Act 1988 and the Australian Privacy Principles these obligations apply whether or not they are documented, and integrations are exactly the place where personal information quietly spreads into systems nobody has counted. A page written now avoids a difficult reconstruction later.

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.