API integration for Notion
We build your Notion connector
We integrate Notion with your software: what the app already knows is written into Notion, and checking a box can trigger an invoice or a workflow.
- Senior product team
- Notion connectors in production
- from scoping to monitoring
What does the Notion API provide and why connect Notion to a business application?
Notion has become the knowledge management and project tracking tool of choice for many teams. Its API lets your application create and update Notion pages or database entries, read the content of an internal wiki, or trigger an action in your product when a checkbox is ticked or a status changes. You integrate it when Notion is the source of truth for a process: client tracking, onboarding, project management, and you want to eliminate manual re-entry between Notion and the business software.
What our clients build on the Notion API
Meeting notes in the base
Closing the meeting writes a page in Meeting notes. Nobody retypes the agenda in the evening.
Notion pipeline into the forecast
Read plus page updated webhook. The business software reads the pipeline without making it the accounting source of truth.
HR base that creates the employee
An Approved page in Notion triggers creation in the internal HRIS, with the business identifier already set.
Notion as the site CMS
The team publishes in Notion, the site reads the API at build time. The 2,000-character rich text cap is a ceiling, not a surprise.
What this changes in your production
Engineering in service of a measurable result: no more retyping, a base that triggers the business, an API version that holds.
Notion stays the team's tool
The software writes the order and the notes there. Nobody opens a second back office for the same information.
A checkbox starts a real flow
Webhooks avoid polling at 3 req/s. Approved in Notion can start an invoice, not only a cosmetic status.
Guards that Notion does not impose
Types, unique identifiers, exhaustive pagination. An SME uses it as a back office, without turning it into an improvised ERP.
Versioning stops being an afterthought
Notion-Version 2026-03-11, trash/archive and data source breaks. A bare fetch without the header fails. The SDK sets it, a forgotten HTTP client does not.
How we ship your Notion connector
Scoping
Which bases, internal token or public OAuth, which API version. The final webhook URL is chosen before activation.
Schema
Data sources, unique upsert properties, 2,000-character rich text limits. A 2022 databases connector is rewritten here.
Development
Pinned version header, single queue, Retry-After, webhooks, has_more pagination. No retry on 401/403.
Monitoring
429 rate_limited, 529 service_overload, verification_token off git. Guided upgrade on every changelog.
What the Notion API allows
- Pages, blocks, data sources
- Write and read the wiki or the base. Query: POST /v1/data_sources/{id}/query. Snake_case, null to clear, empty string forbidden.
- Connection webhooks
- HTTPS URL, one-shot verification token. After verification, changing the URL recreates the subscription. Event data_source.schema_updated.
- Double rate cap
- ~3 req/s per integration and a workspace cap by plan. 429 with rate_limit_reason, 529 service_overload, same handling.
- Mandatory versioning
- Dated Notion-Version. 2026-03-11: trash/archive semantics, block operations, transcription / notes types. JS SDK ≥ v5.
Notion API vocabulary
- Notion-Version
- Mandatory header. Without it: 400 missing_version. Current guide version: 2026-03-11. Versioning is the topic, not the Notion API in general.
- Data source
- The current name for what used to be called database. The 2025-09-03 and 2026-03-11 guides renamed the model. A 2022 databases connector needs a rewrite.
- 3 req/s
- Per integration, burst tolerated, plus a shared workspace cap by plan. A naive sync of 5,000 pages = ~30 min at best. Queue and cache.
- 529 service_overload
- Same handling as a 429: Retry-After, jitter, retry cap. It is not a business error. No retry on 401/403.
- verification_token
- One-shot to paste in the webhook portal. Off git. After verification, changing the URL recreates the subscription: the prod URL is chosen before activation.
- Rich text 2,000
- Cap per property, URL 2,000. An HTML contract pasted into a property fails. We truncate or move to child blocks.
The real constraints of the Notion API
Without Notion-Version, it is 400
A bare HTTP client fails. The SDK sets the header, a forgotten fetch does not. The 2026-03-11 upgrade changes trash/archive and data sources: JSON contract tests on every bump.
3 req/s and the workspace cap
Two limits, two reasons in the 429. A screen that reads Notion live needs a cache. The single queue anticipates, it does not only react.
The webhook URL is frozen after verification
Plan the final (prod) URL before activating. Recreating the subscription is not a rename. The one-shot token is not reread from git.
A PAT is not a product
Internal token, public OAuth, PAT: three regimes, three perimeters. A PAT does not hold a multi-workspace client. That is settled at scoping.
Notion webhooks or polling at 3 req/s?
Two ways to react to Notion. The 3 requests per second cap makes naive polling visible from the first real base.
| Criterion | WebhooksConnection | Polling3 req/s |
|---|---|---|
| Throughput | The useful event | ~3 req/s + workspace cap |
| Delay | Push, ACK 2xx | The cron period |
| 5,000 pages | Not the webhook's job | ~30 min at best |
| URL | Frozen after verification | None |
| Schema | data_source.schema_updated | Reread yourself |
| Initial sync | Bounded import + webhooks after | Often the only tool, too slow |
| The right case | Checkbox, invoice, HRIS | One-off replay, cache |
The two coexist: a paginated initial import, then webhooks. A live poll on a user screen goes through a cache, not through the API on every click.
What we measure on a Notion integration
The other productivity tools
Notion is combined more often than it is replaced. These options are discussed at scoping.
NotionWe build your Notion connectorThis page
SlackThe alert and the action, when the Notion page is not the right channel.
JiraThe ticket and the workflow, when Notion is no longer enough to track.
AirtableThe structured spreadsheet, when the base already looks like a grid.
MetabaseWe build your Metabase connectorWe combine Notion with
The stack around Notion on our projects.
Notion: your questions
Four steps. Pin Notion-Version (2026-03-11 in the guides we read): without the header, 400 missing_version. Map data sources and a unique property for upsert. Put a single queue under 3 req/s, Retry-After, jitter, has_more pagination. Wire webhooks (prod URL before verification, token off git, ACK 2xx, queue). The sensitive part is not POST /pages, it is the version, the double rate cap and the 2,000-character rich text limit.
Because Notion versions the JSON contract by date. Without Notion-Version: 400 missing_version. Version 2026-03-11 changes trash/archive semantics, block operations, and introduces transcription / notes types. Data source replaced database. A connector written in 2022 against databases needs a rewrite. We pin the version in configuration, add contract tests, and guide the upgrade on the changelog, rather than silently following latest.
A single queue per integration, not two independent workers. Honour Retry-After, treat 529 like 429, do not retry a 401/403. The workspace cap is extra: the 429 carries additional_data.rate_limit_reason (public_api_request_rate_limit or public_api_space_request_rate_limit). A sync of 5,000 pages takes ~30 min at best. Every user screen goes through a cache. Webhooks avoid polling for a checkbox. The limiter anticipates the 3 req/s, it does not only react.
It is not the same job. A Notion consultant structures bases, views, team habits. An integrator (us) wires the API into your application: writes from the ERP, webhooks toward the invoice, CMS, internal RAG. The two often follow each other. If your need is to train the team on Notion, this is not that page. If your need is that an Approved page starts a flow in the HRIS or the site, yes. We do not sell Notion training under an integration quote.
A first useful flow, writing a page when a meeting closes with a unique property, ships in two to three weeks. A full chain (several data sources, webhooks, CMS, multi-workspace OAuth) is closer to six to eight weeks. Duration depends on the schema, internal token vs OAuth, and the volume to paginate. We scope the perimeter up front and give you a firm estimate before we start, including the 3 req/s budget.
A Notion integration project?
Let's talk. 30 minutes to scope the bases to wire, the API version, and tell you frankly what 3 req/s will hold.
Discuss my Notion project