The sprint started with “this should take a week.” The ticket was simple: pull order data from one system, push it to another. By week three you were blocked on sandbox access. By week five you were debugging a rate-limit behavior the vendor’s docs didn’t mention. By week seven the retro had two slides on everything the estimate missed.
This is not a planning failure — it is the default shape of API integration work. The complexity that wrecks estimates is almost never in the happy-path HTTP call. It is in the scaffolding: auth edge cases, error handling, retry semantics, schema drift, environment parity, monitoring. That scaffolding is the actual work. Knowing how long an integration takes means scoping the scaffolding, not the endpoint call.
Here is an honest breakdown by project type, and a map of where time actually goes.
The Timeline Question Is Usually Being Asked Wrong
When a VP Engineering asks “how long does this integration take,” they mean development time. When the engineer estimates, they are thinking about the code. Neither is accounting for calendar time — the time spent navigating the other system’s organization.
Development time is roughly predictable per project type. Calendar time is not. It includes credential provisioning, sandbox access, rate-limit documentation that does not match production behavior, and deprecation notices that arrive mid-build. These are not edge cases. They are standard operating conditions.
The code is the easy part. The bureaucracy of two systems negotiating with each other is where the calendar goes.
Every integration estimate that turns out wrong has been right on the code and surprised by the rest.
Simple Integrations: One to Three Weeks Development, Up to Six Weeks Calendar
A simple integration connects two systems via a well-documented REST API with a clearly defined read or write operation. One source, one destination, a schema you mostly control. Happy path, error handling, retry logic, and a basic test harness run two to five days for a senior engineer who knows the target API.
Calendar time is different. Sandbox access provisioning averages several days at well-run SaaS vendors and several weeks at anything touching a bank, healthcare system, or government entity. If the integration touches PII or payment data, add a compliance review cycle. If the sandbox does not mirror production rate limits, your testing extends because you will discover the real limits in production.
The real variable in simple integrations is not complexity — it is how fast the other organization moves.
Internal between two systems you control: calendar matches development. One side is a third-party vendor: add two to four weeks of organizational latency.
Medium Integrations: Four to Eight Weeks Development, Two to Four Months Calendar
Medium complexity integrations involve bidirectional sync, multiple endpoints, non-trivial transformation logic, or stateful operations. A CRM-to-ERP bridge handling partial updates and deletion propagation. An HR system feeding payroll and benefits. An order management system syncing inventory across two warehouses.
The development work breaks into three phases: schema mapping and transformation (one to two weeks), error handling and retry strategy (a week minimum — edge cases only surface during testing), and integration testing against a realistic dataset (one to two weeks). Total: four to six weeks for a team that knows both systems.
Calendar time is where the estimate collapses. Medium integrations cross organizational boundaries in both directions — two credential provisioning queues, two sandboxes to validate, two API support teams. If the integration requires a data mapping approval (common in healthcare, fintech, GDPR territory), add a review cycle from a team on its own sprint schedule.
The other hidden cost: schema drift. A medium integration in production for more than six months will hit at least one upstream schema change requiring a mapping layer rebuild. Building drift-handling in from the start adds a week upfront and saves three at the first incident.
Medium integrations are where teams reliably double their estimate — not from bad engineering, but from scoping only the code and not the systems they cannot control.
Complex Integrations: Three Months and Up
Complex integrations involve multi-system orchestration, event-driven patterns, stateful long-running workflows, or regulated data. EDI pipelines connecting a retailer to dozens of suppliers. A claims processing workflow spanning three internal systems and two underwriting APIs. A real-time inventory sync where conflict resolution has business logic attached.
Development cannot be cleanly estimated before discovery. Architecture decisions compound: event ordering guarantees, idempotency handling, compensating transactions for mid-workflow failures, dead-letter queue strategy. Teams that skip the architecture phase almost always rebuild something fundamental in month two. Two to three weeks of design work is not overhead — it is what determines whether the calendar reads three months or nine.
Beyond that, the timeline variables multiply. Regulated data domains require security reviews on their own schedule. Legacy systems have undocumented behaviors that surface only under production load. Multi-vendor coordination means the integration stalls whenever any participant is unresponsive or in a freeze window.
Three months is the floor for complex integrations scoped correctly. Five to seven months is the median when the project crosses two or more of: legacy system, regulated data, multi-vendor coordination, or a team splitting attention.
If someone quotes you six weeks for a complex integration, ask them what happens when the EDI mapping doesn’t match the trading partner’s actual files. That answer tells you whether they have done this before.
What Every Timeline Miss Has in Common
Across all three tiers, failed estimates share one structural problem: they scope the development work and treat everything else as overhead. Credential provisioning is a blocking dependency with an external owner. Schema validation cannot be parallelized with the build. Observability is how you find out the integration broke six weeks after it shipped.
Teams that estimate accurately treat all of this as first-class work. They scope credential provisioning before writing code. They design error handling before building the happy path. They instrument from the start — so when something breaks in production, there is a trace to follow rather than a Slack message from a downstream team three days later.
The estimation problem is ultimately an observability problem. With OpenTelemetry traces from day one, you know within hours when a mapping fails silently, which retries are masking a deeper failure, and where a latency spike started before the incident ticket appeared. Without it, integration stacks run dark — and the time spent debugging looks like “the integration took longer than expected.”
It does not take longer. It runs in the dark for longer.
If you are evaluating a platform for integration work, the observability story is worth checking before anything else. Koodisi ships OpenTelemetry from the Community tier — before you spend a dollar — so you instrument from the first workflow rather than retrofitting visibility after the third incident. No per-execution billing, no overage invoices: the bill does not move when traffic spikes or retries stack up mid-incident.
The honest answer to how long an API integration takes: longer than the code, by the length of every external dependency you cannot control. Scope those accurately and the estimates stop lying.
Start on the free Community tier at koodisi.io/start — 30 workflows, 1,000 executions per month, and full OpenTelemetry from day one.