Custom software rarely overruns in the feature that was specified. It overruns in the systems that feature has to talk to — because five quite different realities all get called “an API”, and an estimate made from a description assumes the best of them. Two of the five are not slower versions of the same job; they change what the product can do. The fix is not a bigger contingency. It is one successful call against every system in scope before anyone commits to a date.
Ask a team what went wrong on the last build and you will mostly hear about integration. Not the screens, not the business logic, not the thing everybody argued about in the workshop. The connection to the system that already existed.
This is consistent enough to be structural rather than unlucky. It happens because of where the word “API” sits in a conversation about scope.
Five things called the same thing
When a stakeholder says the inventory platform has an API, they are almost always telling the truth as they understand it. What they cannot tell you is which of these they mean, because from their seat the distinction is invisible.
A documented interface with a sandbox. Current reference docs, a test instance you can reach today, credentials issued without a procurement conversation. This is the case every estimate silently assumes, and it is the rarest of the five.
An interface that exists but cannot be tried. There is a specification, possibly a decade old, possibly accurate. There is no test environment, so the first real call happens against production, which means the first real call happens after a change-control meeting. The work is not harder; the feedback loop goes from minutes to days, and everything downstream inherits that.
A read path and no write path. You can query and you cannot change anything. Features that display data land on schedule. Features that update it discover there is no supported route, and the workaround — a file drop, a vendor-built endpoint, a human retyping it — was never in the plan.
A scheduled export. A file lands on an SFTP server at two in the morning. This is a perfectly solid integration and it is not an API, because the data is up to a day old. The specification said the dashboard shows current stock. It cannot. That is a product change, not a technical difficulty, and it is the moment to tell whoever owns the requirement rather than the moment to be clever.
A screen. Nothing programmatic exists. The data lives in a user interface and the realistic options are a vendor change request with its own price and timetable, a direct database read the owning team has not agreed to, or driving the screen with automation and accepting that it breaks on their next release. All three are real projects. None of them is a line item in somebody else's estimate.
The two multipliers
On top of which rung you landed on, two things stretch the work independently of its difficulty.
Nobody in the room owns the other system. The sponsor paying for your project cannot grant access to the finance platform, because it belongs to finance, or to a vendor, or to a managed service with a ticket queue. The engineering work of an integration is often a few days. The wait for a test endpoint and credentials runs into weeks, and it does not compress by being asked about more often. It is a dependency with a named owner or it is a surprise.
There is no realistic test data. You cannot test a payments integration against production, and the sandbox contains three accounts invented by whoever built it. So the integration passes every test and meets its first real transaction after go-live. This is the same problem that makes core banking integration slow in ways that have nothing to do with the protocol, and it is worth asking about in the first week: what does a realistic test record look like, and who can produce one?
Why contingency does not fix it
The instinct is to add a buffer, and for the middle rungs it genuinely helps — those cases are slower, not different.
It does nothing for the bottom two. If the only route to the data is a nightly file, no contingency buys back the latency; the requirement has to change. If the only route is a screen, you are not over budget, you are holding an unscoped second project. Money cannot convert either into the thing the specification described, which is why both need to reach the person who owns the requirement rather than being absorbed quietly by the build team.
Absorbing them quietly is the common failure, and it is well intentioned every time.
What to do instead
Put a short discovery step in front of the estimate, with one deliverable per system: a call that worked.
- List every system in scope by name, with the person who can grant access to each. If that person is unknown, that is the first finding.
- Make one real call against a non-production instance — a read and, where the scope needs it, a write. Done by the team that will build it, with credentials they hold.
- Write down which of the five you found. One line each. This is the document that makes the estimate defensible.
- Ask what a realistic test record looks like, and who can produce one.
- Price each integration after this step. Anything unreachable is explicitly not estimated yet, and says so in the proposal.
This reads as a delay of a week or two before the real work starts, and it is a hard thing to sell against a competitor who skips it. What it buys is a number that was observed rather than invented — the same reason it is worth being specific about interfaces when you write the requirement in the first place.
A note on reading the database directly
When the fifth case turns up, the tempting shortcut is to read the other system's tables. Occasionally that is the right answer, with a read-only replica and the owning team's agreement in writing.
The cost is that you have adopted somebody's internal schema as an interface they never promised to keep stable. Their routine upgrade becomes your outage, and you have stepped around whatever validation their application layer was doing. For writes, the case is weaker still: their business rules live above the tables, and bypassing them puts invalid state into a system you do not own. Treat it as a deliberate, documented exception rather than a default.
Questions we get asked
Why do integration estimates go wrong so consistently?
Because the estimate is made against a description and the work is done against a system. Someone says the warehouse platform has an API, which is true, and the sizing assumes a documented endpoint with a sandbox. What turns up is a read-only query interface, or a nightly file export, or a vendor change request with its own commercial process. None of those are small variations on the first; they are different pieces of work, and two of them change what the product can do.
What should we check before committing to a date?
One successful call against a non-production instance of every system in scope, made by the team that will build the integration, using credentials they hold. Not a document, not a vendor assurance, not a screenshot from a sales deck. If a system cannot be reached before the estimate, it is not estimated, and the honest thing to do is price that integration separately once access exists.
Is a larger contingency the answer?
It helps with the cases that are merely slower, and it does nothing for the cases that change the product. If the only route to the data is a nightly export, a real-time feature becomes a next-day feature, and no amount of contingency buys back the latency. That is a decision for whoever owns the requirement, which is why it has to surface before the build rather than during it.
What makes test access so often the bottleneck?
The person who can grant it usually does not work for whoever is paying for your project. They are in another department, or at a vendor, and the request is not on their list. The technical work of an integration is frequently a few days; the wait for a test endpoint and credible test data is measured in weeks. Tracking that wait as a dependency with a named owner, from the first day, is the single most useful scheduling habit available here.
Can we not just read the other system's database directly?
Sometimes it is technically possible and it is usually a poor trade. You take on the other system's internal schema as an interface it never agreed to keep stable, so their routine upgrade becomes your outage, and you lose whatever validation their application layer performs. There are narrow cases for a read-only replica with the other team's written agreement. There are very few for writing.
How should an integration be priced when access is unknown?
Separate it from the build. Price a short, fixed discovery step whose only deliverable is a working call per system, and price each integration after that step rather than before it. It reads as a delay of a week or two and it replaces a number that was invented with a number that was observed, which is cheaper than discovering the difference halfway through a fixed-price build.
If you are about to commit to a date that depends on three systems you have never called, the cheapest week you will spend is the one that calls them. It is where we start on custom software projects, and it is usually the step that changes the plan.