Integration 101: the bridge is the whole job

A small moment first

The first integration I built that mattered was supposed to be a one-afternoon job: when a deal closes in one system, create the customer in another. Two tools, one arrow between them. I had it "working" before lunch.

It worked in the demo. It worked for a week. Then it started skipping records — not all of them, just enough to make me distrust everything. It felt unfair, honestly. I'd put my effort into the auth and the API calls, and that part was working fine — but those functions were choking on bad data from a bad mapping or a bad transformation. Something that silly shouldn't have dented my confidence the way it did.

The two ends were never the problem. The problem was in the middle — the part I'd barely thought about. So let me start there, after one quick map of the whole thing.

The shape of every integration

Strip away the jargon and every integration is three parts:

Source — the system where something happens, and where you read the data from. (A deal closes, a form is submitted, a payment lands.)

Bridge — the middle, where you decide which records cross, what each field becomes on the other side, and how the data gets reshaped to fit.

Destination — the system that needs to know, and where you write the data to.

Picture it left to right: read from the source, cross the bridge, write to the destination.

The two ends: real, but generic

Connecting to the source and the destination is real work — but it's generic work, and it's a solved problem.

Each end needs two things: authentication (proving you're allowed in — an API key, an OAuth login) and API calls (the actual read or write). Every serious platform gives you these, and every platform documents its own. HubSpot's auth is not Salesforce's auth is not your billing tool's auth — but they all have one, and the steps are written down for you.

That's the key point: because the ends are platform-specific, they're swappable and documented. Change the platform and this part changes, but you follow that platform's docs and move on. There's little for me to teach here that the vendor hasn't already written better.

The bridge is the opposite. It's the same set of problems on every project, and almost nobody writes them down. So that's where this post spends its time.

The bridge has three jobs. The first two are mostly decisions — you make the call once and they hold. The third, transformation, is where the care goes, because it's the one that keeps surprising you. So I'll move quickly through the first two and slow down on the third.

The bridge, part 1 — Filter: you don't always sync everything

The first instinct is to sync every record. Usually that's wrong.

Most of the time you only want some of what the source has: only deals that are actually Won, only contacts from this year, only paying customers, only the region this destination cares about. Filtering is deciding, on purpose, what is even allowed to cross the bridge.

Skip it and you flood the destination with noise, and make every later step do work on records that should never have been there. The plain-English version: before you ask "how do I move this record," ask "should this record move at all?"

Decide it once, and it holds.

The bridge, part 2 — Mapping: same meaning, different names

No two systems name their fields the same way. One calls it phone, the other mobile_number; one has Company, the other Account Name. Mapping is saying this field over here becomes that field over there. Mostly straightforward — with one catch people forget:

Mapping isn't just fields — it's the options inside the fields too. A dropdown in the source might offer "Won / Lost / In Progress". The destination's might say "Closed-Won / Closed-Lost / Open". Same idea, different labels. Map the field but not each option value and it arrives technically connected and quietly broken — unrecognized values fall on the floor.

(My "random skipping" lived one level deeper than this: one system identified a customer by email, the other by company name — two different ideas of what made one unique. Same word, different model. The drops weren't random; the systems just disagreed, and I'd never made them agree.)

Still, mapping is a decision you write down once and it holds. Transformation is not.

The bridge, part 3 — Transformation: where the real care goes

Filtering and mapping are decisions. Transformation is reshaping the data itself — and it's where most of my time, and most of the bugs, actually went. The reason is simple: filter and mapping are settled the moment you make the call, but transformation has to be right for every record that ever flows through, including the ones you didn't picture when you set it up. One weird value six months from now and it breaks.

The shapes are familiar enough:

Concatenate (join). Source has first_name and last_name; destination wants one Full Name. Glue them together.

Split. The reverse — source stores one Full Address; destination wants street, city, zip. Break it apart.

Change the type. Source sends a date as text — "21/06/2026" — destination expects a real date. Or "1,200" needs to become the number 1200. Same value, wrong format; convert it.

The shapes are easy. The care is in the cases that don't fit the happy path — and these are the ones that bite later, not in the demo:

• Empty and missing values. What does "join first + last name" produce when there's no last name? "Kaleem " with a trailing space? An error? Decide on purpose, for every transformation.
• Splitting is a guess. "Glue two fields" is safe — you always get one result. "Split one field into three" assumes a pattern. One address with no zip, or a name with a middle name, and your split lands the pieces in the wrong boxes silently. Splitting needs a rule for when the input doesn't match the shape you expected.
• Type changes hide ambiguity. "03/04/2026" — is that March 4th or April 3rd? The conversion looks clean and gives you a confidently wrong date. Numbers have the same trap: "1,200" is one thousand two hundred in one place and one-point-two in another. The format you assume is the bug.
• Same idea, different scale or unit. One system stores money in dollars, another in cents. One uses a percentage of 0–100, another 0–1. The field maps, the type matches, and the value is still off by 100×. Nothing errors — it's just wrong.

"Filter and mapping you decide once. Transformation you have to get right for every record that will ever cross — including the messy one you haven't seen yet. That's where the care goes."

What "basic" actually means

So a basic integration — the 101 version — is the three ends-and-bridge in their simplest form:

1. Source: read the right event from the right system (follow its docs for auth + the API call).
2. Bridge: filter to the records that should cross (decide once), map the fields and their option values (decide once), and transform anything that doesn't line up — the part that has to stay right for every record, so it's where your care goes.
3. Destination: write it where it needs to go (again, follow that platform's docs).

Get the bridge right and the basic version genuinely works. The concept is small once you stop staring at the two ends and start respecting the middle.

What this post is deliberately not covering

The basic version above is not the production version.

The moment it runs in the real world, the world shows up: the destination is down for thirty seconds, two events arrive at once, something fails silently at 2am and you hear about it from an angry customer instead of a dashboard. Handling that — retries, queues, logging, monitoring — is what turns a working integration into a reliable one.

I left every one of those out on purpose. Bolting reliability onto a bridge whose mapping is still wrong is just building a sturdier path to the wrong place. Get the bridge right first; make it reliable second. Each of those gets its own post, and I'll link them here as I write them.

What I'd do now

Before I touch either end, I sketch the bridge on paper: what's allowed to cross (filter), what each field and each dropdown value becomes (mapping), and what has to be reshaped (transformation). Plain words, no code. Nine times out of ten the bug I'd have spent a day chasing is sitting right there in that one-page sketch, visible before I connect anything.

If you take one thing from this: the two ends are the part the docs already solve. The bridge is the part that's yours.

Why I'm sharing this

I've been building integrations since 2021, and it was not a smooth five years. Syncs broke in UAT, broke on edge cases, broke at scale — one broke in production six months in, over a rare edge case, and took the whole sync down with it. Every one of those taught me something, and I can build robust, reliable syncs now because of them. I'm writing it down for the people a few steps behind me — and for the ones ahead, who can tell me what I'm still getting wrong.