The integration scope document: a template that prevents rework
An integration scope document turns a partner idea into a buildable plan. The five parts, how to write each one, and the test of a finished scope.
Two engineers, one on each side, sit down to build the integration. They both attended the partner calls. They both nodded at the same demo. There was no integration scope document, so six weeks later half the work gets thrown out, because one of them built a two-way sync and the other expected one-way, and nobody had written down which it was.
This is rework, and it is the most expensive failure in integration work. Not because the code was wrong, but because the two companies never shared one definition of what was being built. Everyone held a slightly different picture in their head, the pictures disagreed at exactly the point where it was costly to fix, and the cost showed up as code rewritten in week six instead of a sentence corrected in week one.
The fix is an artifact, not a meeting. An integration scope document is the single page that turns a partner idea into a buildable plan, the thing an engineer who was not in any of the calls can read and start building from without a stream of basic questions. This guide covers what goes in it, how to write each part well, and the simple test that tells you when it is done.
The 60-second version
If you only read one section, read this one:
- Integrations get rebuilt because two companies never share one definition of done. The scope document is the artifact that creates it, before anyone writes code.
- A good integration scope document has five parts: user stories for both sides, a workflow and data-ownership map, acceptance criteria, a named owner, and an explicit out-of-scope list.
- Write user stories from the customer's view, naming what the customer does and gets, not what the two systems do to each other.
- The workflow map settles ownership: which system owns which record, which direction syncs flow, and what happens on conflict. Most integration bugs are unanswered ownership questions.
- Acceptance criteria must be testable, a number or a behavior an engineer can verify, not "fast" or "reliable."
- The out-of-scope list is the part teams skip, and it is what stops scope creep and the "I thought v1 included that" argument at review.
- The test of a finished scope: hand it to an engineer who was not in the partner meetings, and they come back with no basic questions about ownership or done.
- The scope feeds the build and the two-company handoff, and it connects backward to API readiness and forward to the whole partner path.
Why integrations stall without an integration scope document
A normal feature has one team holding one mental model. When that model is wrong, one person notices in standup and corrects it the same day. An integration has two teams, in two companies, holding two models, and the gap between them is invisible until code collides with it.
The gap is almost never about the hard parts. Both sides understand the API and can write the sync. What they disagree on is the boring middle: which system is the source of truth for a contact, whether a delete on one side propagates to the other, what happens when the same record is edited in both places between syncs. These are not engineering problems. They are decisions, and a decision nobody wrote down gets made twice, differently.
When the two models finally collide, you do not find out gently. You find out at integration testing, or worse, at the partner's app review, the single most expensive place to discover that "done" meant two different things. By then there is code built on each assumption, a customer who was promised a date, and an engineer on each side who has to unwind work they were proud of.
The scope document exists to move that collision forward to week one, where it costs a sentence instead of a sprint. Writing the scope forces the two models to become one, on paper, while disagreement is still cheap.
The integration scope document, in five parts
A scope does not need to be long. The good ones fit on a page or two. What matters is that all five parts are present, because each one closes a specific category of rework.
| Part | The question it answers | The rework it prevents |
|---|---|---|
| User stories | What does the customer do and get? | Building for the partner instead of the customer |
| Workflow and data map | Who owns which record, and which way does it flow? | Sync conflicts, duplicate records, silent data loss |
| Acceptance criteria | How do we know it is done? | "Done" meaning two different things at review |
| Named owner | Who decides and unblocks? | Decisions that stall because nobody owns them |
| Out-of-scope list | What are we choosing not to build? | Scope creep and "I thought v1 had that" |
Notice that three of the five are not code at all. They are agreements. The user stories agree on who the work is for, the map agrees on ownership, the out-of-scope list agrees on the boundary. The scope document is mostly a record of decisions, and the code is what happens after the decisions are settled.
The order matters too. Stories say who you are building for, the map constrains how, criteria define when you stop. The owner runs the whole thing, and the out-of-scope list is the fence around it.
Part one: user stories from the customer's view
A user story names what a person does and what they get. The discipline that makes integration stories good is writing them from the customer's side, not the system's. The customer does not care that your app POSTs to the partner's contacts endpoint. They care that when they close a deal, the contact shows up in their CRM without retyping it.
Write the story as a moment in the customer's day. "As a sales rep, when I mark a deal closed-won in our app, the contact and company appear in my CRM within a minute, so I never retype them." That sentence carries a trigger, an outcome, and a timing expectation, and it is legible to a salesperson, a support lead, and an engineer at once.
| System-led story (weak) | Customer-led story (strong) |
|---|---|
| "We sync deals to the CRM." | "When a rep closes a deal, the contact appears in their CRM in under a minute." |
| "Contacts flow both ways." | "If a rep edits a phone number in the CRM, it updates in our app on the next sync." |
| "We handle deletes." | "If a rep deletes a contact in the CRM, it is removed from our app, not left as a ghost." |
Write a story for both directions of the integration, because each direction is a separate promise with its own edge cases. And resist writing the story as a feature list. "Syncs contacts, companies, and deals" is a scope of work, not a story. The story is the workflow the customer runs, and the data objects fall out of it.
If you cannot write the stories from real customer language, you have a research problem, not a scope problem. Run a few customer conversations first, because a scope built on imagined workflows is just a guess in a nicer format.
Part two: the workflow and data-ownership map
The map is where most integration bugs are prevented, because most integration bugs are really unanswered ownership questions wearing a technical disguise. The map settles three things: which system owns which record, which direction each sync flows, and what happens on conflict.
Ownership means: for each kind of record, one system is the source of truth. The deal lives in your app. The contact lives in the partner CRM. When the same field exists on both sides, you decide which one wins, and you write it down. A record with two owners is a conflict waiting for a customer to trigger it.
Direction means: for each record, you state whether it flows one way or both, and you do it per record, not for the integration as a whole. It is common and correct for deals to flow one way and contacts to flow the other. "Two-way sync" as a blanket phrase is how teams end up building twice the code they needed, or half.
Conflict means: when the same record changes on both sides between syncs, you state the rule. Source of truth wins, last write wins, newer timestamp wins, any rule is fine as long as it is explicit and never silently drops data. The silent drop is the bug that becomes a churn-risk ticket, because the customer loses a phone number and blames your product.
A map does not need to be a diagram. A short table works. The point is that every record has exactly one owner, one direction, and one conflict rule, written where both build teams can see it.
Part three: acceptance criteria that define done
Acceptance criteria are the part teams most often write badly, because vague criteria feel finished while saying nothing. "Sync is fast" is not a criterion. "Reliable error handling" is not a criterion. Neither can be tested, which means neither can be verified, which means the engineer and the reviewer are free to disagree about whether the work is done.
A real criterion is a number, a behavior, or a deadline that someone can check. The test is simple: could an engineer write an automated test for this sentence? If not, it is not a criterion.
| Vague (untestable) | Testable |
|---|---|
| "Contacts sync quickly." | "A closed deal appears in the CRM within 60 seconds." |
| "Errors are handled." | "On a 4xx, retry three times with backoff, then log and alert." |
| "Deletes work correctly." | "Deleting a record syncs a delete, not a blank update." |
| "Edge cases covered." | "A renamed field maps by ID, not by label, so renames do not break the sync." |
Good criteria cover the unglamorous cases that break in production: deleted records, renamed fields, records that exist on one side but not the other, what happens when the partner API is down. These are exactly the cases a demo skips and a real customer hits in week one. Writing them as criteria forces the conversation while it is cheap.
The criteria you write here are not just a definition of done. They are the checklist you verify against at the end of the build, which is why getting them concrete now pays off twice. We will come back to that handoff below.
Part four: a named owner
The owner is one name, not a committee and not a team. "Partnerships" is not an owner. "Engineering" is not an owner. A person is. The owner is who decides when the map has an open question, who unblocks when a handoff stalls, and who is accountable for the date.
The reason a name matters is that integrations generate decisions faster than committees make them. When the conflict rule for a record is undecided, the build stops until someone chooses, and a team-as-owner means everyone assumes someone else will choose. A named owner means the decision has an address, and the partner's owner has one person to talk to, which is half of what makes a two-company project move.
The owner does not need to be senior, but they need two things: the authority to decide what the integration does, and the access to engineering to get it built. A product leader or founder at seed to Series B is the usual fit. What does not work is splitting the role, where one person owns the relationship and another owns the build and neither owns the whole.
Part five: the explicit out-of-scope list
The out-of-scope list is the part almost everyone skips, and it is the cheapest insurance in the whole document. It is a short, explicit list of things you are choosing not to build in this version, written down so nobody assumes they are included.
Scope creep does not arrive as a decision. It arrives as an assumption. The partner assumes v1 includes custom field mapping. Your support lead assumes it covers historical backfill. Nobody decided to add these, but everyone expected them, and at review the gap between expected and built reads as a missed commitment instead of a deliberate choice.
| In scope (v1) | Out of scope (v1, maybe v1.1) |
|---|---|
| Contact and company sync | Custom field mapping |
| Closed-won deals push one way | Historical backfill of past deals |
| Standard fields, mapped by ID | Multi-currency conversion |
| Source-of-truth conflict rule | Bulk re-sync from a settings page |
The list does two things. It stops the creep, because anything not on the in-scope side is explicitly not promised. And it makes a deliberate descope easy, because if the date is at risk, you already have a list of what was negotiable. Marking v1 versus v1.1 calmly at scoping beats deciding it in the panic of week seven.
Writing this list is also a good faith test of the partnership. A partner who reads your out-of-scope list and works with it wants the thing shipped. One who treats every exclusion as a problem is showing you how the rest of the project will feel.
The test of a finished scope
There is one test that tells you the scope is done, and it does not involve a checklist. Hand the document to an engineer who was not in any of the partner meetings. If they read it and come back with no basic questions about who owns which record or what done means, the scope is finished. If they come back asking "wait, does this sync both ways?" or "what counts as done for deletes?", it is not finished, no matter how polished it looks.
This works because the whole point of the scope is to be legible without the room. The people who sat in the calls carry context the document does not, and that context is exactly what gets lost when the build hands off to someone new, which it always does. The cold-read engineer is a stand-in for everyone who will touch the integration without the meeting history: the partner's engineer, the maintainer next quarter, you in three months.
Run the test before the build, not after. A scope that passes the cold read is one you can hand across the boundary to the partner's team, and the cleaner that handoff, the less the project slips at the seams. For how that two-company handoff and the build are run, our guide to running integration projects covers the cadence, blocker discipline, and the RACI that keeps two companies moving on one date.
How the scope feeds the build and the handoff
A finished scope is not a document you file. It is the input to the next three things, and each one reuses a specific part of it.
First, the estimate. An engineer can only give a real estimate against a real scope. Hand them the stories, map, and criteria, and they can size the work. Hand them "integrate with the CRM" and you get a guess, which becomes a date that is a fiction.
Second, the build. The engineers on both sides code against the stories and the map, from the same document. The map is the contract between the two build teams. When a question comes up mid-build, it goes to the owner and the answer is written back into the scope, so the document stays the single source of truth instead of decaying.
Third, the verification. The acceptance criteria you wrote in part three are the exact checklist you test against at the end. This is why concrete criteria matter: "done" is not redefined late, because it was defined testably at the start. The build is done when every criterion passes, and not before.
| Scope part | Feeds | What it produces |
|---|---|---|
| Stories and map | The estimate | A real number, not a guess |
| Map | The build | The contract between two teams |
| Acceptance criteria | The verification | The done checklist |
| Owner | All three | The person who unblocks each step |
This is also why the scope is the cheapest leverage in the whole partnership. Every hour spent making it cold-read clean saves multiple hours of rework downstream, because the rework you are preventing is the most expensive kind: code thrown out, dates missed, trust spent.
How scope connects to API readiness and the partner path
The scope does not start the partnership and it does not end it. It sits in the middle, depends on the step before it, and enables the steps after.
Before the scope comes API readiness. You cannot write an honest workflow map if you do not know what your own API can do, or whether the partner's API exposes the records you need to own and sync. A scope written against an API that lacks a webhook for deletes is built on sand. Getting your API and docs partner-ready first is what makes the scope buildable rather than aspirational, and our guide to making your API partner-ready covers the docs, auth, and sandbox that let an engineer answer those questions in ten minutes instead of a week.
After the scope comes everything else: the build, enablement, launch, and maintenance. The scope is step five of a nine-step path, and the steps before it are cheap precisely so the expensive build step starts from solid ground. For where the scope sits in that whole arc, from partner idea to shipped and adopted integration, see our complete guide to tech partnerships for SaaS.
The shape is simple. API readiness makes the scope possible. The scope makes the build estimable and verifiable. The build, run as a two-company project, makes the launch real. Skip the scope and you have not saved a step, you have moved its cost downstream, where it arrives as rework instead of a page of writing.
A reusable scope checklist you can copy
Here is the section checklist to drop into your own scope document. Fill every line, and run the cold-read test before you call it done.
| Section | Must include | Done when |
|---|---|---|
| User stories | One per direction, written from the customer's view, with trigger, outcome, timing | A non-engineer reads them and recognizes their own workflow |
| Workflow and data map | Each record's owner, direction, and conflict rule | Every record has exactly one owner and one rule |
| Acceptance criteria | Numbers and behaviors, including deletes, renames, and API-down cases | Each line could become an automated test |
| Named owner | One person, with authority and engineering access | The partner knows exactly who to talk to |
| Out-of-scope list | What v1 explicitly does not do, with v1.1 candidates marked | Nobody can claim an unbuilt feature was promised |
Keep it to a page or two. The goal is not a long document, it is a clear one. If a section runs long, it usually means a decision is still open, and an open decision is the thing the scope exists to close.
Common mistakes, and the fix
Writing stories from the system's view. The fix: name the customer in every story, and describe what they do and get, not what the two apps do to each other. "We sync contacts" is a feature. "A rep never retypes a contact" is a story.
Leaving ownership implicit. The fix: the map states one owner, one direction, and one conflict rule per record. Most integration bugs are unanswered ownership questions, so answer them on paper before they become tickets.
Vague acceptance criteria. The fix: every criterion is a number or a behavior an engineer could write a test for. If you cannot test the sentence, rewrite it until you can. "Reliable" is not a criterion.
Skipping the out-of-scope list. The fix: write down what v1 does not do. The list costs five minutes and prevents the "I thought that was included" argument that turns a successful launch into a disappointment.
Calling the scope done without the cold read. The fix: hand it to an engineer who was not in the meetings. If they have basic questions, the scope is not finished, however polished it looks. The cold read is the only test that matters.
FAQ
How long should an integration scope document be? One to two pages for a typical first integration. The goal is clarity, not length. If a section is running long, a decision is usually still open, and the scope exists to close those decisions, not to describe them at length. A scope that fits on a page and passes the cold-read test beats a ten-page document that does not.
Who writes the integration scope document? The named owner on your side, with input from an engineer who understands both APIs and from real customer workflows. It is a product artifact, not a legal or BD one. The partner should review and agree to it, especially the workflow map, because the map is the contract between the two build teams.
What is the difference between a scope and a spec? The scope says what is being built and why, in terms the customer and both companies can agree on: stories, ownership, criteria, boundary. A technical spec says how, in terms only engineers need: endpoints, schemas, retry logic. The scope comes first and constrains the spec. You can write a spec from a good scope, but not the reverse.
Do we really need the workflow map if the integration is simple? Yes, especially then, because simple integrations are where teams skip the map and discover the ownership question in production. Even a one-way, one-object sync has a delete question and a conflict question. The map for a simple integration is short, which is the point, it takes minutes and removes the most common class of bug.
What goes in the out-of-scope list? Anything a reasonable person might assume v1 includes but it does not: custom field mapping, historical backfill, multi-currency, bulk re-sync, additional objects. Mark which ones are v1.1 candidates. The list exists so no one, on either side, can claim an unbuilt feature was promised, and so a deliberate descope has a ready menu.
How does the scope prevent the build from slipping? It does two things. It lets an engineer give a real estimate instead of a guess, so the date is grounded. And it makes "done" testable up front, so the build is not redefined late in the project. Slips at the build stage are usually a scoping failure surfacing late. The full mechanics are in our guide to running integration projects.
Can a scope change after it is signed? Yes, and it should when something real is learned, but through the owner and written back into the document. The failure mode is not change, it is undocumented change, where the build drifts from the scope and the two diverge silently. Keep the scope as the single source of truth and route changes through it.
Should the partner sign the scope too? The workflow map and the acceptance criteria, yes, because those are shared between both build teams. An engineer on each side should read and agree that the document defines done. If the two companies hold different pictures of done, you want to find that at scoping, not at the partner's app review, which is the most expensive place to discover it.
The short version
Integrations get rebuilt because two companies never share one definition of what is being built. The integration scope document is the artifact that creates that shared definition, on paper, while disagreement is still cheap, instead of in code at the partner's app review, where it is not.
A good scope has five parts: user stories written from the customer's view, a workflow and data-ownership map that settles who owns which record, acceptance criteria that are testable rather than vague, one named owner, and an explicit out-of-scope list. Three of the five are agreements, not code, which is the whole point. The scope is mostly a record of decisions, and the build is what happens after the decisions are settled.
The test is the cold read. Hand the scope to an engineer who was not in the partner meetings, and if they have no basic questions about ownership or done, it is finished. That same document then feeds the estimate, the build, and the verification, and connects backward to API readiness and forward to the whole partner path.
If you want the scope written, the build shipped, and the launch run end to end, that is exactly what a Partner Audit is for. We review your product, API, and partner potential, then define what to build, who to approach, and how to ship it without the rework.