Integrating New Software with Legacy Systems: What Actually Goes Wrong

Ask any developer who has shipped enterprise software for a mid-size company which line item most reliably blows past its estimate, and most will say the same thing: connecting the new system to whatever the company was already running. Not the new build. The bridge to the old one.

The API you were promised isn't the API you get

Sales decks and vendor documentation describe an idealized integration surface. In practice, a lot of legacy systems — especially anything installed more than a decade ago — expose partial APIs, undocumented quirks, or no API at all, requiring database-level access, file exports, or screen-scraping to move data in and out. Before scoping any timeline, get read access to the actual system and make one real call. A documentation page is not evidence the endpoint works the way it says.

Data quality problems that were always there, now visible

Legacy systems accumulate two decades of inconsistent data entry: duplicate customer records, dates stored as text in three different formats, fields that were repurposed for something other than their name over the years. None of this caused problems when the old system was the only thing reading it. The moment you integrate, every inconsistency becomes a bug in the new system, and untangling it is usually a bigger project than the integration code itself.

• Audit a real data sample before estimating — not the schema, the actual rows
• Expect to write data-cleaning and normalization logic as a first-class part of the project, not a footnote
• Decide who owns "source of truth" when the two systems disagree, before it happens in production
• Budget time for a reconciliation process, not just a one-time migration

Authentication and security models that predate modern standards

Older systems often authenticate with mechanisms that predate OAuth or modern token-based security — shared service accounts, IP allowlisting, credentials embedded in config files. Bridging that gap securely, without either weakening the new system's security posture or breaking the old system's access model, is a real design problem, not a checkbox. Skipping it properly is how integration projects end up with a shared admin password living in a spreadsheet.

The organizational problem hiding inside the technical one

The hardest part of a legacy integration is often not technical at all — it's finding the one person who still understands why the old system behaves the way it does, and getting time on their calendar. Long-tenured systems accumulate institutional knowledge that was never documented because the person who built it never expected to leave. Identify that person early and protect their time in the project plan; a two-hour conversation with them can save weeks of reverse-engineering.

The short version

Never scope a legacy integration off documentation alone. Test the real API, sample the real data, map the real authentication model, and find the person who remembers why it was built that way. Budget extra time as a default, not a contingency — legacy integrations are one of the few areas of software where the estimate padding is usually not enough padding.

Sources