HubSpot + Nextech integration

Specialty clinics run two businesses at once. One is clinical: charts, encounters and surgical scheduling, all of it inside Nextech. The other is demand: paid search, lead forms, consultation requests and the long follow-up that turns an enquiry into a booked procedure. Marketing lives in HubSpot, the chart lives in Nextech, and the join between them is usually a coordinator retyping a name.

The cost shows up at both ends of the funnel. At the top, nobody can say which campaign produced a booked consultation, because the booking happened in a system the ad platform never sees. At the bottom, a patient who cancels falls out of every nurture sequence, because the portal never learns the appointment changed. Recall and cyclical treatments make it worse: the practice knows who is due, and the marketing tool does not.

Connecting the two is mostly an exercise in restraint. The clinic does not want a chart in HubSpot and should not have one. What it wants is the contact record, the appointment and its status, and the office and provider the appointment belongs to. That is enough to attribute a booking, trigger a reminder and route a follow-up to the right location. It is also a far smaller surface to defend than anything clinical.

The rule we work to is that clinical data stays in the practice system. Patients become contacts, carrying contact details and the identifiers that tie the two records together. Appointments become deals, because a consultation moving through requested, booked, confirmed and completed is a pipeline whether or not anyone calls it one. Locations become companies so a multi-site practice can route by office, and providers become a small custom object used for ownership rather than for anything about care.

Everything else on the FHIR surface stays where it is. Conditions, observations, medications and documents are available through the same API and have no business in a marketing platform. A clinic with a genuine reason to bring any of it across should do so with HubSpot’s sensitive data settings switched on and an agreement behind it, not as a mapping choice.

The match key is the Nextech patient identifier written to a unique HubSpot property. Email is unusable here, because families share addresses and the API will not let you change a name or a date of birth after the patient exists.

The Select API is FHIR over REST with OAuth, and it sends no events, so the runtime is a polling engine with a watermark. Each cycle asks for the resources whose last-updated timestamp is newer than the stored mark, writes the HubSpot side, and advances the mark only once that write has committed. A crash mid-cycle replays the same window instead of skipping it.

Two headers ride every request: a bearer token that expires after an hour, and the practice identifier. Tokens renew from a long-lived refresh token, so the engine holds its own credentials rather than asking a person for them. Writes into HubSpot are idempotent batch upserts keyed on the patient identifier, with a separate pass that associates each appointment to its patient and location.

The reverse direction is a sequence rather than a write. Booking reads available slots, creates the appointment, then sets its status, exactly as the API defines it.

The question is how much of the FHIR surface you are willing to own. A generic automation platform can move a patient and an appointment once someone has normalized the shapes. FHIR does not hand you flat fields: identifiers arrive as arrays, contact details live inside a telecom structure, and much of what a practice cares about sits in extensions. Whoever connects the systems has to write that adapter.

A healthcare-specific integration platform is a fair answer when the clinic wants no software of its own and the mapping is small. It prices per record or per connection, and it still needs an agreement covering patient data. A service we build costs more up front and gives the practice the field list, the audit trail and a clear answer to what left the chart.

Duplicate patients, the rate limit, immutable fields and scope creep in the field list cause the trouble here, and only one of them is a HubSpot problem.

1. Scope. We agree the field list first, with the practice, in writing. What leaves Nextech is the whole decision on a healthcare build, and everything else follows from it.
2. Architect. The object model, the identifier property per object, the appointment status to deal stage map, and where the practice identifier and tokens live.
3. Build. The polling engine and the FHIR adapter: identifier arrays, telecom parsing and extension extraction, with the mapping held as data so a field change is a configuration edit.
4. Validate. A sandbox portal and a test practice first, behind a fail-closed portal allowlist so a misconfigured token cannot write into the wrong portal. Production cutover is a token swap.
5. Operate. A watermark you can rewind, a replay endpoint, a reconciliation count of appointments on both sides, and alerting on conflict and rate limit responses rather than waiting for somebody to notice.