The Notion API Integrations Guide for B2B Teams (2026): Workers, OAuth, and the Build-vs-Buy Decision

What This Guide Covers — and Who It's For

This guide is for B2B engineering, ops, and product leads who are about to make one of three decisions:

1. Build a custom integration on the Notion API (or one of the new Workers).
2. Buy a no-code automation platform — Zapier, Make, n8n, or Activepieces — and point it at Notion.
3. Both — buy for the long tail of "sync X to Notion" workflows, build for the 2–3 high-leverage flows that need custom logic.

Based on our research across Notion's official documentation, the May 13, 2026 Developer Platform release, and hands-on testing of the four leading automation platforms, here is what's actually true about Notion integrations in 2026 — what the marketing pages skip, what the docs bury, and what we'd tell a customer in a 30-minute scoping call.

What Changed in 2026: The Developer Platform Release

On May 13, 2026, Notion shipped its Developer Platform 3.5, the most significant change to how integrations work since the public API launched in 2021. Three things are new:

1. Workers (hosted runtime)

Workers are a hosted runtime for custom code. You write the code locally (often with a coding agent), deploy via the CLI, and Notion runs it in a secure sandbox attached to your workspace. They sit between "I'll call the API from my own server" and "I'll buy Zapier." Workers are free for developers through August 11, 2026, after which they consume Notion credits.

2. External Agents API

External Agents bring third-party agents — Claude, Codex, Decagon, or anything you build — into Notion as native workspace participants. They appear in the agent list, chat in pages and databases, and can take actions alongside humans. This is the most under-discussed piece: it changes what an integration looks like to end users. The integration is no longer a sidebar bot; it's a teammate.

3. The Notion CLI

A purpose-built command-line interface for developers and coding agents. It can sign into your workspace, read and write pages, build and deploy Workers, and is intended to be driven by AI coding agents as well as humans.

The Three Integration Types You Need to Know

Before you write a line of code, decide which of these you're building. The choice determines authentication, distribution, and what your users see in their workspace.

Internal Integration

Scoped to a single workspace. The integration's owner generates a Bearer token in notion.so/my-integrations and uses it server-to-server. Best for: internal tools, BI pipelines, "sync our CRM into our team workspace" jobs. No OAuth flow. The token lives in your secrets manager.

Public Integration (OAuth 2.0)

Distributable to any Notion workspace. You ship an OAuth flow: the user clicks "Connect Notion," picks the pages/databases they want to share, and you receive a workspace-scoped access token. Required for any SaaS product that talks to customers' Notion accounts. Notion requires a public-facing privacy policy, terms, redirect URI, and support email before it'll switch your app to public.

Worker (new in May 2026)

Custom code that runs inside Notion's sandbox, deployed via the CLI. Useful when you want low-latency reactions to workspace events without operating a server. Still in early adoption — production Workers are appropriate for internal/enterprise use first.

Setting Up Your First Integration (Step-by-Step)

This walkthrough covers the most common case: an Internal Integration that reads and writes a database. You can follow it in ~10 minutes.

curl -X POST 'https://api.notion.com/v1/databases/<DATABASE_ID>/query' \
  -H 'Authorization: Bearer ntn_xxx...' \
  -H 'Notion-Version: 2022-06-28' \
  -H 'Content-Type: application/json' \
  --data '{
    "filter": { "property": "Status", "select": { "equals": "In Progress" } },
    "page_size": 25
  }'

Core API Surface (Worth Knowing Before You Build)

The Notion API exposes four object types and a handful of endpoints. You will use four of them constantly.

If you're new to the API, our walkthrough of how to read and write Notion databases with Python covers the property-shape gotchas in depth.

Rate Limits: What Actually Matters in Production

The Notion API documents an average of 3 requests per second per integration token. A Notion engineer has publicly clarified that the underlying limit works out to roughly 2,700 calls per 15 minutes. Bursts above 3 r/s are tolerated; sustained traffic above it is not.

Two error codes signal you've hit a wall:

• HTTP 429 rate_limited — you're sending too fast. Respect the Retry-After response header.
• HTTP 529 service_overload — Notion is under heavy load; back off and try later.

The limits are dynamic: Notion doesn't publish hard ceilings because they flex with system load. In practice, the safe operating envelope for a single integration is:

Build vs Buy: The 2026 Honest Comparison

If your team can describe the integration in a sentence ("when a deal closes in HubSpot, create a row in our Notion CRM database with X, Y, Z fields"), you almost certainly do not need to write code. Four no-code platforms cover Notion well in 2026. They differ on price, hosting model, and how comfortable they are once your workflow has more than ~5 steps.

For a deeper head-to-head, see our hands-on Zapier vs Make comparison from 40 hours of testing and our Activepieces vs Make breakdown for B2B teams.

Quick decision framework

Common Integration Patterns (And How to Build Them)

Three patterns cover ~90% of B2B Notion integration requests we see. They're worth knowing before you commit to a tool — each one has a "buy" answer and a "build" answer.

Pattern 1: One-way sync from system-of-record into Notion

Example: HubSpot deals → Notion CRM database. The source system is canonical; Notion is the team-readable view. Buy first. Every no-code platform handles this in 4–6 clicks. Build only if you need custom field transformations the no-code UI can't express.

Pattern 2: Two-way sync

Example: A status change in Notion needs to update Linear, and vice versa. Build, or buy carefully. The trap is loop prevention — if A updates B, B's webhook fires and updates A, which fires again. Implement a "last writer" idempotency key, debounce, and a circuit breaker. Most no-code platforms can do this with branching, but expect to debug for a day.

Pattern 3: AI agent that operates inside Notion

Example: A weekly digest agent that reads the team's project pages, summarizes status, and posts into a "Weekly Sync" page — plus answers questions when @-mentioned. This is the case for the new External Agents API. The agent shows up as a workspace participant, not a sidebar bot. The build effort is non-trivial, but the UX payoff is large enough that it's usually worth doing in-house rather than gluing together Slack-mentions + Zapier hacks.

Common Pitfalls (We've Hit All of These)

1. Forgetting to connect the integration to pages

Creating the integration in my-integrations only authorizes it to exist. You also have to explicitly share each parent page or database with it via the page-level Connections menu. Without this, the API returns object_not_found for IDs that clearly exist.

2. Treating property values as strings

Notion properties are typed objects. "Status" isn't a string, it's { "status": { "name": "In Progress" } }. "Owner" isn't a name, it's { "people": [{ "id": "..." }] }. Always inspect a real row's JSON before writing.

3. Pagination assumptions

Database queries return at most 100 rows per page. You must paginate with start_cursor until has_more is false. Plenty of integrations look like they work in test (50 rows) and silently miss data in production (5,000 rows).

4. Skipping the Notion-Version header

Forgetting it doesn't fail in an obvious way — Notion picks a default and your code may receive a slightly different schema than you expect. Always pin to a version (currently 2022-06-28 is the broadly compatible choice).

5. Building on a single Internal Integration for a SaaS product

Tempting because OAuth setup is more work. But your customers' workspaces will share a single rate-limit bucket, which means your slowest customer can starve everyone else. Use OAuth from day one if you're shipping a customer-facing product.

6. Polling when webhooks would do

Webhooks are out of beta for most object types as of 2026. Polling every minute burns rate-limit budget you'll regret when you scale. Subscribe to the events you care about and only poll as a backup.

FAQ

Methodology

This guide synthesizes the official Notion API documentation (current to June 2026), the Developer Platform 3.5 release notes (May 13, 2026), and our hands-on use of Zapier, Make, n8n, and Activepieces against real Notion databases. Pricing was verified against each vendor's public pricing page on June 14, 2026. Rate-limit figures come from Notion's published request-limits documentation and corroborating engineering statements. We do not accept paid placements in this guide; affiliate links, where present, are clearly marked and do not influence rankings.

Ken Hayashi

Technology consultant with 10+ years in the Japanese tech industry. Specializing in SaaS evaluation, workflow automation, and B2B tool integration.