Custom API Integration Is 20% Connection and 80% Everything After

Every vendor page on this topic stops at the definition. Here is the part that decides whether the thing is still running in twelve months.

When a custom API integration beats the connector you already have

Most teams should not build. If HubSpot's native Salesforce sync moves the objects you care about, use it. The reason to write a custom API integration is almost always one of four specific gaps, and it is worth naming which one applies before anyone opens an editor.

The connector ignores your custom objects. Prebuilt connectors map standard entities (contact, company, deal, invoice) and skip the Project__c object your ops team actually runs on.

The direction is wrong. Plenty of connectors are one-way by design, and your process needs the write back.

The trigger granularity is too coarse. You need a fire on dealstage changing to one specific value, not a nightly batch of everything that moved.

The transform is business logic. Splitting a line item across two revenue accounts based on a rule nobody else has is not a mapping problem, it is code.

Approach	Custom objects and fields	Who fixes a breaking change	Error visibility	Cost driver at volume
Native connector	Standard objects only, usually	Vendor, on their timeline	Whatever their UI shows, often nothing	Seat or tier price
Zapier or Make	Yes, but one record at a time	You, inside their canvas	Per-run logs, no dead letter queue by default	Tasks or operations consumed
Unified API (Merge, Nango)	Normalised model, passthrough for the rest	Vendor absorbs the change	Their dashboard	Per connected account
Custom API integration	Anything the API exposes	You, immediately	Whatever you instrument	Compute and developer attention

If you are wiring CRM logic specifically, decide first whether the work belongs in the platform at all. A lot of what people call integration is really CRM workflow automation that should live inside the CRM's own engine, where support will help you debug it.

The five stages of a custom API integration build

People ask about the five stages of API integration as if it were a methodology. It is not, but there is a sequence that consistently works, and skipping stage two is what produces the projects that slip.

1. Contract discovery. Read the docs, then ignore them and pull a real payload with curl. Find the pagination style (cursor, offset, link header), the auth model, the rate limit, and whether deletes are hard or soft. Documented behaviour and actual behaviour diverge constantly on nullable fields and date formats.
2. Field mapping and ownership. For every field in scope, one system is the writer and the other is the reader. Two-way fields need a conflict rule agreed by a human before code exists. This is the slow stage and it is a decision stage, not an engineering one.
3. Build against a sandbox with idempotency from day one. Every write carries a stable key. Stripe formalises this with the Idempotency-Key header, which returns the original response for 24 hours on a repeat. APIs without it need your own dedupe table keyed on source ID plus operation.
4. Backfill and reconcile. Historical records go through a separate path with batching, then you compare row counts and spot check twenty records by hand. Custom fields, activity history and file attachments are where migrations lose data silently.
5. Observability and handover. Structured logs per record, a dead letter store, and an alert that names the failing record and payload rather than saying "workflow failed".

Where a custom API integration breaks after go-live

Rate limits first, because they are published and still catch people. HubSpot's Professional and Enterprise tiers allow 190 requests per 10 seconds per private app, with daily caps on top, documented in their API usage guidelines. Salesforce meters a 24 hour org-wide allocation that scales with licence count, per the platform API limits cheat sheet. A naive per-record sync running a backfill can exhaust a day's allocation before lunch and take your other integrations down with it, because the limit is shared.

Token refresh is the second one. Refresh tokens expire, get rotated, or get invalidated when a user changes a password. If the refresh happens inside a running job with no persistence of the new token, you get one silent failure and then a week of missing records. QuickBooks in particular rotates aggressively, which is one of the reasons QuickBooks and CRM integrations break in predictable places.

Webhook ordering is the third, and the most misunderstood. Webhooks are not a queue with guaranteed sequence. An update can land before the create it depends on, and retries mean the same event arrives twice. Handle it with a timestamp comparison against the record you hold, not with a hope. This is the same trap that shows up in VoIP and CRM integration after go-live, where call-ended fires before call-started gets processed.

Then the two that are not technical at all. Someone adds a required validation rule in the CRM and every write starts rejecting. Someone renames a picklist value and your mapping table sends a string the API refuses. Neither shows up in a test suite. Both show up as a support ticket three weeks later.

"Custom API" and "custom API integration" are not the same thing

Search results mix these constantly, so worth separating. In the Microsoft Power Platform, a custom API in Dataverse is a code-first way to define your own message with typed request and response parameters, registered as a plugin. It is closer to a custom action, but with a proper contract and the ability to block other plugins from being registered on it.

That is building an endpoint. A custom API integration is consuming endpoints, yours or someone else's, and holding the sync together. Sometimes you do both: exposing a thin API on your own application so partners have one stable surface instead of six internal tables. Pagetive, my open-source landing page builder, works that way, with blocks as typed objects rather than HTML so the contract survives a redesign.

What actually drives scope on a custom API integration

Three things, and none of them is the number of endpoints. How many systems the integration touches, because each one adds an auth model and a rate limit. The state of the data going in, because deduplicating 40,000 contacts where the same person exists three times with different casing is its own project. And how many edge cases exist, which is usually a function of how long the business has been operating without rules.

A quote before seeing the stack is a guess. I look at the actual payloads and the actual field list first, then scope it, and I will say when a native connector or a Make scenario does the job and a custom API integration does not.

If you have an integration that stopped working quietly, or one you have been told cannot be built, book a call. Bring the API docs and one failing record. Twenty minutes, no pitch.

Frequently asked questions

What is a custom API integration?

A custom API integration is purpose-written code that connects two or more systems through their APIs, handling authentication, field mapping, rate limits, retries and error reporting. Unlike a prebuilt connector, it can read and write any object the API exposes, including custom objects and fields, and it applies your own business logic during the transform rather than a vendor's generic mapping.

What are the 5 stages of API integration?

Contract discovery (pull real payloads and find the limits), field mapping with an agreed owner per field, building against a sandbox with idempotency and retry logic, backfilling historical data and reconciling row counts, then instrumenting logs, alerts and a dead letter path before handover. Stage two causes most delays, because it needs decisions from people rather than code.

How do I create a custom API in Dataverse?

Define the custom API record with a unique name, set the binding type and whether it is a function or action, add typed request parameters and response properties, then register a plugin on the main operation stage to implement the logic. Microsoft's Power Apps developer documentation covers the solution-aware setup and the differences from a custom action.

When should I use a native connector instead of a custom API integration?

When the connector already moves the objects, fields and direction you need. Native connectors are maintained by the vendor, survive API version changes without your involvement, and cost nothing extra in attention. Build custom only when a specific gap exists: an unsupported custom object, a one-way sync you need both ways, granular trigger conditions, or transform logic that is genuinely your own.

What happens when the vendor changes their API and the integration breaks?

It gets caught by alerting that names the failing step and payload, failed records land in a dead letter store instead of disappearing, and the fix is a mapping change rather than a rebuild. Silent failure is the real risk. An integration that stops routing leads for three weeks costs far more than one that raises a loud error on the first bad response.

How long does a custom API integration take to build?

One clean connection between two systems with well-documented APIs is usually days. Add multi-system sync, a historical backfill and messy source data, and it runs two to six weeks. The build is rarely the bottleneck. Waiting on API credentials, agreeing which system owns a field, and cleaning duplicate records account for most of the calendar.