Most HubSpot CMS sites eventually hit a point where the built-in data sources aren't quite enough. You need to pull in live product data from an external catalogue. You want to display customer-specific pricing from your ERP. You need a form submission to call a third-party API in real time. Standard modules will not get you there.

This is where custom API integration comes in and HubSpot has several distinct mechanisms for doing it, each suited to different use cases. Choosing the right one depends on what you are trying to do, where the data lives, and how often it changes.

Here is a clear guide to each approach, based on HubSpot's current developer platform as of 2026.

here-we-go-smg4

Authentication

Before any external API call can happen, you need to establish how your code authenticates with HubSpot's own APIs, and how HubSpot-hosted functions authenticate with external systems.

For accessing HubSpot's APIs: HubSpot deprecated API key authentication and now requires either Private Apps or OAuth 2.0. Private Apps are the recommended approach for single-portal integrations. When you create a Private App inside HubSpot (under Settings > Integrations > Private Apps), you select the specific scopes the app needs access to and receive a personal access token. That token authenticates API calls to HubSpot from your code.

OAuth 2.0 is the right choice when you are building a multi-tenant application, something that will connect to multiple different HubSpot portals. It handles the authorisation flow that lets each customer grant your app access to their account.

For calling external APIs from HubSpot: any credentials (API keys, tokens, secrets) needed to call a third-party system should never be hardcoded in your code or returned in a response. HubSpot provides a Secrets mechanism. Where you store sensitive values as named secrets via the CLI or settings, then reference them in your function configuration and access them as environment variables at runtime. This keeps credentials server-side and out of the browser entirely.

my secret pin

Approach One: Serverless Functions

Serverless functions are the primary way to run custom server-side logic inside HubSpot CMS, calling external APIs, transforming data, processing form submissions, or building lightweight endpoints that your CMS modules can call.

Two implementation paths exist in 2026, and it's important to know which one applies to your setup.

Design Manager serverless functions (legacy, still active)

The older approach, built through HubSpot's Design Manager, exposes functions at a URL structured as:

https://{domainName}/_hcms/api/{endpoint-name}?portalid={hubId}

Functions are written in Node.js and can use the request library or axios to make HTTP calls to external APIs. This approach still works and is documented in HubSpot's developer reference.

Developer Projects serverless functions (current, recommended)

Developer Platform version 2026.03, released on March 30, 2026, reintroduced serverless functions into the Projects framework after a period where they were temporarily unavailable in version 2025.2. This is now the recommended path for new builds.

In Projects 2026.03, functions are configured using -hsmeta.json files (replacing the older serverless.json format), support third-party NPM packages, and are invoked at:

https://<domain>/hs/serverless/<path>

Functions can be authenticated using either the Private App access token (stored as PRIVATE_APP_ACCESS_TOKEN in the environment) or named secrets referenced in the function configuration. Public HTTP endpoints, which can act as webhooks or lightweight APIs, are available on Content Hub Enterprise.

Functions can be tested in Developer Test Accounts before deploying to production.

One important limitation: If your process takes longer than a few seconds, involves chained API calls, or requires scheduled execution (like a recurring sync), serverless functions aren't the right tool. They're designed for on-demand, low-latency calls triggered by user interaction or a page request. For anything that needs to run on a schedule or handle heavy processing, you will need an external host.

Approach Two: GraphQL for CMS Data

If your goal is pulling data from HubSpot's own CRM or HubDB tables into CMS pages, rather than calling a third-party API, GraphQL is HubSpot's recommended approach.

GraphQL is available in Content Hub Professional and Enterprise, and allows you to query HubSpot data in a single, structured request rather than making multiple separate API calls. You can fetch data from the following sources in a query:

  • CRM - contacts, companies, deals, tickets, and custom objects.
  • HUBDB - rows from HubDB tables.
  • BLOG - blog posts, authors, and tags.
  • KB - knowledge base articles, categories, and tags.

You write the query directly in your HubL templates, React modules, or test it interactively in the built-in GraphiQL explorer, which provides autocompletion and lets you browse all available fields before writing production code.

A few limits worth knowing: Individual CRM queries are capped at 500 items returned. HubDB queries have no maximum row limit. Complex queries with nested associations are assigned a complexity score, and queries that exceed the complexity threshold will fail, which means you should test query complexity during development rather than discovering it in production.

GraphQL isn't currently supported for modules or templates used in marketing emails.

Approach Three: HubDB as a CMS Data Layer

HubDB is HubSpot's built-in relational database, accessible via the HubSpot API and queryable through GraphQL. For use cases where you want to display structured content that comes from an external source, product listings, event schedules, team directories, review data, HubDB can serve as the cache and delivery layer.

The pattern works like this: An external service (your own server, an Azure Function, a GitHub Actions workflow) fetches data from a third-party API on a schedule and writes it into a HubDB table using HubSpot's API. Your CMS pages then query that HubDB table via GraphQL to display the data. Page visitors get fast page loads because they're reading from HubDB rather than making live calls to an external API on every request.

One clarification that trips people up: A HubSpot Private App alone can't schedule recurring syncs. The Private App provides the authentication token your sync script uses, but the scheduling and execution has to live somewhere outside HubSpot, on an external server, a cloud function (AWS Lambda, Azure Functions, Vercel), or a scheduled GitHub Actions workflow. HubSpot has no native cron or scheduled task runner unless you use custom code actions in workflows, which requires Operations Hub Professional.

Approach Four: Workflow Custom Code Actions

For integrations triggered by CRM events, a deal moving to a specific stage, a contact submitting a form, a lifecycle stage changing, HubSpot's custom code actions in workflows let you run Node.js or Python code that can call external APIs and write data back into HubSpot records.

This approach requires Operations Hub Professional. The code runs server-side, has access to the enrolled record's properties, and can both read from and write to HubSpot via the API using a Private App access token. This is a useful middle ground for teams who need API connectivity inside their automation logic without building and hosting a separate service.

The same caution about execution time applies: custom code actions work well for quick, targeted operations. For anything that requires significant processing or error handling across multiple systems, an external architecture is more reliable.

When to Move Logic Outside HubSpot

There are use cases where trying to keep all the integration logic inside HubSpot creates more complexity than it resolves. External hosting, whether that is a lightweight API on Vercel, a serverless function on AWS Lambda, or a dedicated backend service, makes sense when:

You need scheduled or recurring syncs. HubSpot has no native cron scheduler. If data needs to be pulled from an external source on a regular schedule and written into HubSpot, the scheduler must live outside the platform.

Your process exceeds the execution time window. Serverless functions are designed for short, on-demand operations. Heavy data processing, multiple chained API calls, or operations that could take ten or more seconds need to run on infrastructure designed for that workload.

You need complex error handling and retry logic. While HubSpot workflows have some built-in retry for webhooks, a dedicated external service gives you more control over retry strategies, alerting, and monitoring.

You are building for multiple portals. A service hosted externally that connects to multiple HubSpot accounts via OAuth 2.0 is architecturally cleaner than trying to replicate that logic across each individual portal.

okay, lets try that again, but this time good_

The Common Mistakes Worth Avoiding

Using deprecated API key authentication. API keys are deprecated. Any integration still using them is running on unsupported infrastructure. Migrate to Private Apps.

Storing secrets in code. Never hardcode an API key or token in a serverless function or template. Use HubSpot's Secrets mechanism and reference them as environment variables.

Running on an unsupported platform version. With Developer Platform 2026.03 now available, builds on 2025.1 need to migrate, builds on 2025.1 will fail after August 1, 2026.

Making live external API calls on every page load. For data that doesn't change frequently, writing it into HubDB and reading from there is faster and cheaper than calling an external API in real time for every visitor.

Conclusion

Custom API integration with HubSpot CMS is well-supported, there are multiple tools available depending on what you are building, and the options have become more capable with the 2026.03 platform release. The key is choosing the right mechanism for the job: serverless functions for on-demand calls, GraphQL for querying HubSpot's own data, HubDB for caching external data, workflow custom code for CRM-triggered events, and external hosting for anything that needs scheduling or heavy lifting.

Get the architecture right and the CMS can do genuinely complex things. Get it wrong and you end up with fragile integrations that fail quietly.

If your HubSpot CMS needs custom API work or your existing integrations need an audit, give us a shout.

Catch our latest HubSpot masterclasses and tutorial shorts on YouTube, or join us over on Facebook for a healthy dose of marketing reality and HUG event promos. No fluff, just the good stuff.

See you there!